Merge pull request ethereum#53 from ChainAgnostic/waves-namespace-fin…

…al-edits Final editorial pass on Waves Namespace
bumblefudge · Feb 2, 2023 · 0908537 · 0908537
2 parents 1610259 + aa045fd
commit 0908537
Show file tree

Hide file tree

Showing 3 changed files with 103 additions and 50 deletions.
diff --git a/waves/caip-10.md b/waves/caip-10.md
@@ -15,11 +15,15 @@ requires: ["CAIP-2", "CAIP-10"]
 
 ## Rationale
 
-Waves "account" has a public key that is the same for any Waves blockchain.
+Each Waves "account" has one public key that is the same across any Waves
+blockchain. But on each Waves blockchain, this public key is expressed as a
+distinct "address" expressed as a 26 byte array derived from public key (and
+chain identifier) and represented as a [Base58btc][] encoded string.
 
-But Waves "address" is 26 byte array derived from public key and represented as Base58 encoded string.
-
-Waves "address" can change depending on chain ID. It prevents unintentional transfers on other Waves blockchains. Address also contains checksum, which protects against typos and copying errors of the address.
+Waves "address" can change depending on chain ID. This prevents unintentional
+transfers across Waves blockchains. Addresses also contain an [address
+checksum][] mechanism, which protects against typos and copying errors of the
+address.
 
 ## Syntax
 
@@ -28,20 +32,27 @@ The syntax of Waves addresses:
 ```
 caip10-like address:    namespace + ":" chainId + ":" + address
 namespace:              waves
-chain Id:               [-128..127] value. If the value is shorter than 3 characters, then must be padded with leading zeros to 3 characters
-address:                Waves address represented as Base58 encoded string
+chain Id:               [-128..127] value packed with leading zeros at least 3 characters in length
+address:                Waves address represented as a [Base58btc][]-encoded string
 ```
 
-Waves address is byte array of `Entity type + Chain ID + Account public key hash + Checksum`, where:
+The underlying form of each Waves address is byte array of `Entity type + Chain
+ID + Account public key hash + Checksum`, where:
 1. `Entity type` — always 1-byte integer with value `1`
 2. `Chain ID` — 1-byte integer of current blockchain ID
-3. `Account public key hash` — first 20 bytes of the result of `keccak256(publicKey)` hashing function
-4. `Checksum` — first 4 bytes of the result of `keccak256(Entity type + Chain ID + Account public key hash)` hashing function
+3. `Account public key hash` — first 20 bytes of the result of
+   `keccak256(publicKey)` hashing function
+4. `Checksum` — first 4 bytes of the result of `keccak256(Entity type + Chain ID
+   + Account public key hash)` hashing function.
 
 ### Resolution method
 
-To derive an address from public key, make a GET HTTP request `/addresses/publicKey/{publicKey}` to the blockchain node, for example: https://nodes-testnet.wavesnodes.com/addresses/publicKey/7Y5rWP1aB1iGkDer8cS9TasAv1HpvCMZiZ2C9KLema6 \
-Thus, the node will return in response an address of the account with the public key for the current blockchain, for example:
+To derive an address from public key, make a GET HTTP request
+`/addresses/publicKey/{publicKey}` to the blockchain node, for example:
+https://nodes-testnet.wavesnodes.com/addresses/publicKey/7Y5rWP1aB1iGkDer8cS9TasAv1HpvCMZiZ2C9KLema6
+
+Thus, the node will return in response an address of the account with the public
+key for the current blockchain, for example:
 
 ```json
 {
@@ -52,23 +63,29 @@ Thus, the node will return in response an address of the account with the public
 ## Test Cases
 
 ```
-# Public Key:
+# Namespace-wide Public Key:
 # 7Y5rWP1aB1iGkDer8cS9TasAv1HpvCMZiZ2C9KLema6
 
-# Waves Mainnet
+# Address on Waves Mainnet (87)
 waves:087:3PPPJ62chFkr7hQu34WLPwKiywCpeSbfap7
 
-# Waves Testnet
+# Address on Waves Testnet (84)
 waves:084:3NBNV8hiq8DTVF7UmzFLSUwud3h3pKZkVB3
 
-# Waves custom network with negative Chain ID
+# Waves custom network (-7)
 waves:-07:3NBNV8hiq8DTVF7UmzFLSUwud3h3pKZkVB3
 ```
 
 ## Links
 
-- [About addresses in Waves Documentation](https://docs.waves.tech/en/blockchain/account/address)
+- [About addresses in Waves Documentation][address format]
+- [Conversion between binary and Base58btc representation][base58btc]
+
+[address format]: https://docs.waves.tech/en/blockchain/account/address
+[address checksum]: https://docs.waves.tech/en/blockchain/binary-format/address-binary-format
+[base58btc]: https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart
 
 ## Copyright
 
-Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
diff --git a/waves/caip-19.md b/waves/caip-19.md
@@ -12,42 +12,57 @@ created: 2023-01-19
 
 Any account can issue its own token. The new token is immediately available.
 
-ID format of fungible and non-fungible tokens is the same.
-
-Process of issuing is also the same. The only difference is that NFTs must have specific values for certain properties.
+The ID format for fungible (ERC20-equivalent) and non-fungible (ERC-721
+equivalent) tokens is the same.  The process for issuance of either is also the
+same. The only difference is that NFTs must have specific values for certain
+properties.
 
 ## Specification of Asset ID
 
-Asset ID is a 32 byte array encoded as Base58 string. It's usually equal to ID of the transaction that issued this asset (except when the token is issued using a dApp contract, but in this case the Asset ID format is always the same). This is true for both fungible and non-fungible tokens.
+Asset ID is a 32 byte array encoded as a [Base58btc][]-encoded string. When
+issued directly, it is equal to the ID of the transaction that issued this
+asset; when the token is issued using via a smart contract call, the asset will
+instead be addressed by a Blake2b-256 hash of the transaction and parameters
+passed in the call. This is true for both fungible and non-fungible tokens,
+which are distinguished instead by their [token][] metadata which can be
+retrieved or verified by an RPC call from a node (see [token][] reference).
 
 ## Syntax
 
 The syntax of Waves Asset ID:
 
 ```
-caip10-like asset id:    namespace + ":" chainId + ":" + assetId
-namespace:               waves
-chain Id:                [-128..127] value. If the value is shorter than 3 characters, then must be padded with leading zeros to 3 characters
-assetId:                 Waves Asset ID represented as Base58 encoded string
+address:    namespace + ":" chainId + ":" + reference
+namespace:  waves
+chain ID:   [-128..127] value packed to 3 characters with leading zeros
+reference:  Waves Asset ID represented as [Base58btc][]-encoded string
 ```
 
 ## Examples
 
 ```
-# Waves Mainnet
+# Waves Mainnet (87)
 waves:087:DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p
 
-# Waves Testnet
+# Waves Testnet (84)
 waves:084:2HAJrwa8q4SxBx9cHYaBTQdBjdk5wwqdof7ccpAx2uhZ
 
-# Waves custom network with negative Chain ID
+# Waves custom network (-7)
 waves:-07:2HAJrwa8q4SxBx9cHYaBTQdBjdk5wwqdof7ccpAx2uhZ
 ```
 
 ## Links
 
-- [Token](https://docs.waves.tech/en/blockchain/token)
-- [Token ID](https://docs.waves.tech/en/blockchain/token/token-id)
+- [Token][token] overview
+- [Token ID][token id] syntax
+- [About addresses in Waves Documentation][address format]
+- [Conversion between binary and Base58btc representation][base58btc]
+
+[token]: https://docs.waves.tech/en/blockchain/token
+[token id]: https://docs.waves.tech/en/blockchain/token/token-id
+[address format]: https://docs.waves.tech/en/blockchain/account/address
+[address checksum]: https://docs.waves.tech/en/blockchain/binary-format/address-binary-format
+[base58btc]: https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart
 
 ## Copyright
 

diff --git a/waves/caip-2.md b/waves/caip-2.md
@@ -10,28 +10,38 @@ created: 2023-01-19
 
 ## Abstract
 
-In CAIP-2 a general blockchain identification scheme is defined. This is the implementation of CAIP-2 for Waves network.
+In CAIP-2 a general blockchain identification scheme is defined. This is the
+implementation of CAIP-2 for Waves network.
 
 ## Specification
 
 ### Syntax
 
 Blockchains in the "waves" namespace are identified by their chain ID.
 
-Chain ID format is a signed integer in decimal representation. The signed integer is represented as a one-byte signed integer in the range [-128..127].
+Chain ID format is a signed integer in decimal representation. The signed
+integer is represented as a one-byte signed integer in the range [-128..127].
 
 ```
-chain_id:    namespace + ":" + reference
-namespace:   waves
-reference:   integer in the range [-128..127]. If the value is shorter than 3 characters, then must be padded with leading zeros to 3 characters
+chainId:    namespace + ":" + reference
+namespace:  waves
+reference:  integer in the range [-128..127], padded to 3 chars with leading 0s
 ```
 
+If the value is shorter than 3 characters (negative sign included), then it must
+be padded with enough leading zeros to reach 3 characters, i.e. `-69` or `007`.
+
 ### Resolution method
 
-There is no in-protocol resolution method at present. But there is a solution for some cases where it might be needed.
+There is no in-protocol resolution method at present. But there is a solution
+for some cases where it might be needed.
+
+To resolve a blockchain reference for the Waves namespace, make a GET HTTP
+request `/addresses` to the blockchain node, for example:
+- ```GET https://nodes-testnet.wavesnodes.com/addresses```
 
-To resolve a blockchain reference for the Waves namespace, make a GET HTTP request `/addresses` to the blockchain node, for example: https://nodes-testnet.wavesnodes.com/addresses \
-Thus, the node will return in response an array of its public blockchain addresses, for example:
+The node will return in response an array of its public blockchain
+addresses, for example:
 
 ```json
 [
@@ -40,7 +50,8 @@ Thus, the node will return in response an array of its public blockchain address
 ]
 ```
 
-Decode any of them as Base58 string and take the second byte from the resulting array, for example (in pseudocode):
+Decode any of them as Base58 string and take the second byte from the resulting
+array, for example (in pseudocode):
 
 ```java
 byte getChainId(String address) {
@@ -55,16 +66,19 @@ This byte is the chain ID of the blockchain where this node is running.
 
 The chain ID is specified as a one-byte signed integer.
 
-For example, chain ID of Mainnet is 87 (ASCII code of "W").
+For example, the chain ID of Mainnet is 87 (ASCII code of "W").
 
-There may also be other custom networks based on Waves, but with a different chain ID.
+There may also be other custom networks based on Waves, but with a different
+chain ID.
 
-Chain ID is used in [binary format](https://docs.waves.tech/en/blockchain/binary-format/) of blockchain entities:
-- [Block](https://docs.waves.tech/en/blockchain/binary-format/block-binary-format)
-- [Transaction](https://docs.waves.tech/en/blockchain/binary-format/transaction-binary-format/)
-- [Order](https://docs.waves.tech/en/blockchain/binary-format/order-binary-format)
-- [Address](https://docs.waves.tech/en/blockchain/binary-format/address-binary-format)
-- [Alias](https://docs.waves.tech/en/blockchain/binary-format/alias-binary-format)
+Chain ID is used in [binary
+format](https://docs.waves.tech/en/blockchain/binary-format/) in the addressing
+representations of all entities in the namespace, namely:
+- [Block][]
+- [Transaction][]
+- [Order][]
+- [Address][]
+- [Alias][]
 
 Therefore, these entities cannot be used on another network with different chain ID.
 
@@ -82,18 +96,25 @@ waves:084
 # Waves Stagenet
 waves:083
 
-# Waves custom network used in the [private node Docker image](https://hub.docker.com/r/wavesplatform/waves-private-node)
+# Waves custom network used in the [private node Docker image][]
 waves:082
 
-# Waves custom network with negative Chain ID
-waves:-07:3NBNV8hiq8DTVF7UmzFLSUwud3h3pKZkVB3
+# Waves custom network with a negative Chain ID
+waves:-07
 ```
 
 ## Links
 
 - [About Chain ID in Waves Documentation](https://docs.waves.tech/en/blockchain/blockchain-network/#chain-id)
 - [About binary format of blockchain entities](https://docs.waves.tech/en/blockchain/binary-format/)
 
+[Block]: https://docs.waves.tech/en/blockchain/binary-format/block-binary-format
+[Transaction]: https://docs.waves.tech/en/blockchain/binary-format/transaction-binary-format/
+[Order]: https://docs.waves.tech/en/blockchain/binary-format/order-binary-format
+[Address]: https://docs.waves.tech/en/blockchain/binary-format/address-binary-format
+[Alias]: https://docs.waves.tech/en/blockchain/binary-format/alias-binary-format
+[private node Docker image]: https://hub.docker.com/r/wavesplatform/waves-private-node
+
 ## Copyright
 
 Copyright and related rights waived via [CC0](../LICENSE).