From db9612dd983463d2e8358b5c1e916ce476737857 Mon Sep 17 00:00:00 2001 From: Andrea Maria Piana Date: Wed, 29 Apr 2020 15:51:11 +0200 Subject: [PATCH 1/3] initial draft --- docs/stable/9-blockchain-usage.md | 184 ++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 docs/stable/9-blockchain-usage.md diff --git a/docs/stable/9-blockchain-usage.md b/docs/stable/9-blockchain-usage.md new file mode 100644 index 0000000..77d3f5e --- /dev/null +++ b/docs/stable/9-blockchain-usage.md @@ -0,0 +1,184 @@ +--- +permalink: /spec/9 +parent: Stable specs +title: 9/BLOCKCHAIN-USAGE +--- + +# 3/BLOCKCHAIN-USAGE + +> Version: 0.1 +> +> Status: Stable +> +> Authors: Andrea Maria Piana + +# Status interactions with the blockchain + +In this document is document all the interactions that the Status client has +with the blockchain. + +1. [Wallet](#Wallet) +2. [ENS](#ENS) + +## Wallet + +The wallet in Status has two main components: + +1) Sending transactions +2) Fetching balance + +In the section below are described the `RPC` calls made the nodes, with a brief +description of their functionality and how it is used by Status. + +1. [Sending transactions](#Sending-transactions) + *[EstimateGas](#EstimateGas) + *[PendingNonceAt](#PendingNonceAt) + *[SuggestGasPrice](#SuggestGasPrice) + *[SendTransaction](#SendTransaction) +2. [Fetching balance](#Fetching-balance) + *[BlockByHash](#BlockByHash) + *[BlockByNumber](#BlockByNumber) + *[FilterLogs](#FilterLogs) + *[HeaderByNumber](#HeaderByNumber) + *[NonceAt](#NonceAt) + *[TransactionByHash](#TransactionByHash) + *[TransactionReceipt](#TransactionReceipt) + +### Sending transactions + +#### EstimateGase + +EstimateGas tries to estimate the gas needed to execute a specific transaction based on +the current pending state of the backend blockchain. There is no guarantee that this is +the true gas limit requirement as other transactions may be added or removed by miners, +but it should provide a basis for setting a reasonable default. + +``` +func (ec *Client) EstimateGas(ctx context.Context, msg ethereum.CallMsg) (uint64, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L499 + + +#### PendingNonceAt +`PendingNonceAt` returns the account nonce of the given account in the pending state. + This is the nonce that should be used for the next transaction. + + ``` +func (ec *Client) PendingNonceAt(ctx context.Context, account common.Address) (uint64, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L440 + + +#### SuggestGasPrice + +`SuggestGasPrice` retrieves the currently suggested gas price to allow a timely +execution of a transaction. + +``` +func (ec *Client) SuggestGasPrice(ctx context.Context) (*big.Int, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L487 + +#### SendTransaction + +`SendTransaction` injects a signed transaction into the pending pool for execution. + +If the transaction was a contract creation use the TransactionReceipt method to get the +contract address after the transaction has been mined. + + +``` +func (ec *Client) SendTransaction(ctx context.Context, tx *types.Transaction) error +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L512 + +### Fetching balance + +#### BlockByHash + +BlockByHash returns the given full block. + +It is used by status to fetch a given block which will then be inspected for +transfers to the user address, both tokens and ETH. + +``` +func (ec *Client) BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L78 + +#### BlockByNumber + +`BlockByNumber` returns a block from the current canonical chain. If number is nil, the +latest known block is returned. + +``` +func (ec *Client) BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L82 + +#### FilterLogs + +`FilterLogs` executes a filter query. + +Status uses this function to filter out logs, using the hash of the block +and the address that we are interested in, both inbound and outbound. + +``` +func (ec *Client) FilterLogs(ctx context.Context, q ethereum.FilterQuery) ([]types.Log, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L377 + + +#### NonceAt + +`NonceAt` returns the account nonce of the given account. + +``` +func (ec *Client) NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L366 + + +#### TransactionByHash + +`TransactionByHash` returns the transaction with the given hash, used to inspect those +transaction made/received by the user. + +``` +func (ec *Client) TransactionByHash(ctx context.Context, hash common.Hash) (tx *types.Transaction, isPending bool, err error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L202 + +#### HeaderByNumber + +`HeaderByNumber` returns a block header from the current canonical chain. + +``` +func (ec *Client) HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L172 + + +#### TransactionReceipt + +`TransactionReceipt` returns the receipt of a transaction by transaction hash. +It is used in status to check if a token transfer was made to the user address. + +``` +func (ec *Client) TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error) +``` + +https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d462c61/ethclient/ethclient.go#L270 + + +## ENS From 237ad01f8f7ba87c63aee9374fedcc60518cca49 Mon Sep 17 00:00:00 2001 From: Andrea Maria Piana Date: Mon, 4 May 2020 13:51:52 +0200 Subject: [PATCH 2/3] address feedback --- .../9-blockchain-interactions.md} | 32 ++++++++++--------- docs/raw/status-blockchain-spec.md | 15 --------- 2 files changed, 17 insertions(+), 30 deletions(-) rename docs/{stable/9-blockchain-usage.md => raw/9-blockchain-interactions.md} (89%) delete mode 100644 docs/raw/status-blockchain-spec.md diff --git a/docs/stable/9-blockchain-usage.md b/docs/raw/9-blockchain-interactions.md similarity index 89% rename from docs/stable/9-blockchain-usage.md rename to docs/raw/9-blockchain-interactions.md index 77d3f5e..9148bb1 100644 --- a/docs/stable/9-blockchain-usage.md +++ b/docs/raw/9-blockchain-interactions.md @@ -1,6 +1,6 @@ --- permalink: /spec/9 -parent: Stable specs +parent: Raw specs title: 9/BLOCKCHAIN-USAGE --- @@ -8,7 +8,7 @@ title: 9/BLOCKCHAIN-USAGE > Version: 0.1 > -> Status: Stable +> Status: Raw > > Authors: Andrea Maria Piana @@ -31,22 +31,22 @@ In the section below are described the `RPC` calls made the nodes, with a brief description of their functionality and how it is used by Status. 1. [Sending transactions](#Sending-transactions) - *[EstimateGas](#EstimateGas) - *[PendingNonceAt](#PendingNonceAt) - *[SuggestGasPrice](#SuggestGasPrice) - *[SendTransaction](#SendTransaction) + - [EstimateGas](#EstimateGas) + - [PendingNonceAt](#PendingNonceAt) + - [SuggestGasPrice](#SuggestGasPrice) + - [SendTransaction](#SendTransaction) 2. [Fetching balance](#Fetching-balance) - *[BlockByHash](#BlockByHash) - *[BlockByNumber](#BlockByNumber) - *[FilterLogs](#FilterLogs) - *[HeaderByNumber](#HeaderByNumber) - *[NonceAt](#NonceAt) - *[TransactionByHash](#TransactionByHash) - *[TransactionReceipt](#TransactionReceipt) + - [BlockByHash](#BlockByHash) + - [BlockByNumber](#BlockByNumber) + - [FilterLogs](#FilterLogs) + - [HeaderByNumber](#HeaderByNumber) + - [NonceAt](#NonceAt) + - [TransactionByHash](#TransactionByHash) + - [TransactionReceipt](#TransactionReceipt) ### Sending transactions -#### EstimateGase +#### EstimateGas EstimateGas tries to estimate the gas needed to execute a specific transaction based on the current pending state of the backend blockchain. There is no guarantee that this is @@ -100,7 +100,7 @@ https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d4 #### BlockByHash -BlockByHash returns the given full block. +`BlockByHash` returns the given full block. It is used by status to fetch a given block which will then be inspected for transfers to the user address, both tokens and ETH. @@ -182,3 +182,5 @@ https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d4 ## ENS + +All the interactions with `ENS` are made through the [ENS contract](https://github.com/ensdomains/ens) diff --git a/docs/raw/status-blockchain-spec.md b/docs/raw/status-blockchain-spec.md deleted file mode 100644 index 7af4350..0000000 --- a/docs/raw/status-blockchain-spec.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -nav_exclude: true -parent: Raw specs ---- - -# Status Blockchain Specification - -> Version: 0.1 -> -> Status: Draft -> -> Authors: Corey Petty [corey@status.im](mailto:corey@status.im) (alphabetical order) - -TODO From 130f9790e5ccec9c0c66464f22c28a4f0f82c92a Mon Sep 17 00:00:00 2001 From: Andrea Maria Piana Date: Fri, 15 May 2020 10:28:10 +0200 Subject: [PATCH 3/3] Address feedback --- .../9-ethereum-usage.md} | 57 ++++++++++++++++--- 1 file changed, 50 insertions(+), 7 deletions(-) rename docs/{raw/9-blockchain-interactions.md => stable/9-ethereum-usage.md} (61%) diff --git a/docs/raw/9-blockchain-interactions.md b/docs/stable/9-ethereum-usage.md similarity index 61% rename from docs/raw/9-blockchain-interactions.md rename to docs/stable/9-ethereum-usage.md index 9148bb1..a5c6d39 100644 --- a/docs/raw/9-blockchain-interactions.md +++ b/docs/stable/9-ethereum-usage.md @@ -1,21 +1,29 @@ --- permalink: /spec/9 -parent: Raw specs -title: 9/BLOCKCHAIN-USAGE +parent: Stable specs +title: 9/ETHEREUM-USAGE --- -# 3/BLOCKCHAIN-USAGE +# 9/ETHEREUM-USAGE > Version: 0.1 > -> Status: Raw +> Status: Stable > > Authors: Andrea Maria Piana -# Status interactions with the blockchain +# Status interactions with the Ethereum blockchain -In this document is document all the interactions that the Status client has -with the blockchain. +In this document we document all the interactions that the Status client has +with the [Ethereum](https://ethereum.org/developers/) blockchain. + +All the interactions are made through [JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC). +Currently [Infura](https://infura.io/) is used. The client assumes high-availability, otherwise +it will not be able to interact with the Ethereum blockchain. +We rely on these nodes to validate the integrity of the transaction and report a +consistent history. + +Key handling is described [here](./2-account.md) 1. [Wallet](#Wallet) 2. [ENS](#ENS) @@ -98,6 +106,11 @@ https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d4 ### Fetching balance +We currently fetch the current and historical [ECR20] (https://eips.ethereum.org/EIPS/eip-20) and ETH balance for the user wallet address. +Collectibles following the [ECR-721](https://eips.ethereum.org/EIPS/eip-721) are also fetched if enabled. + +We support by default the following [tokens](https://github.com/status-im/status-react/blob/develop/src/status_im/ethereum/tokens.cljs). Custom tokens can be added by specifying the `address`, `symbol` and `decimals`. + #### BlockByHash `BlockByHash` returns the given full block. @@ -184,3 +197,33 @@ https://github.com/ethereum/go-ethereum/blob/26d271dfbba1367326dec38068f9df828d4 ## ENS All the interactions with `ENS` are made through the [ENS contract](https://github.com/ensdomains/ens) + +For the `stateofus.eth` username, one can be registered through these [contracts](https://github.com/status-im/ens-usernames) + +### Registering, releasing and updating + +- [Registering a username](https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L113) +- [Releasing a username](https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L131) +- [Updating a username] (https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L174) + +### Slashing + +Usernames MUST be in a specific format, otherwise they MAY be slashed: + +- They MUST only contain alphanumeric characters +- They MUST NOT be in the form `0x[0-9a-f]{5}.*` and have more than 12 characters +- They MUST NOT be in the [reserved list] (https://github.com/status-im/ens-usernames/blob/47c4c6c2058be0d80b7d678e611e166659414a3b/config/ens-usernames/reservedNames.js) +- They MUST NOT be too short, this is dinamically set in the contract and can be checked against the [contract](https://github.com/status-im/ens-usernames/blob/master/contracts/registry/UsernameRegistrar.sol#L26) + +- [Slash a reserved username](https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L237) +- [Slash an invalid username] (https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L261) +- [Slash a username too similar to an address](https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L215) +- [Slash a username that is too short](https://github.com/status-im/ens-usernames/blob/77d9394d21a5b6213902473b7a16d62a41d9cd09/contracts/registry/UsernameRegistrar.sol#L200) + +ENS names are propagated through `ChatMessage` and `ContactUpdate` [payload](./6-payloads.md). +A client SHOULD verify ens names against the public key of the sender on receiving the message against the [ENS contract](https://github.com/ensdomains/ens) + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). +