From c787a61f396cd9d80382a79ea2d2cee6c9796fc4 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 9 May 2024 09:49:09 -0400 Subject: [PATCH 1/9] Revamp Hash Type Doc --- config/sidebar.config.js | 2 +- source/docs/casper/concepts/hash-types.md | 68 ------ source/docs/casper/concepts/key-types.md | 240 ++++++++++++++++++++++ 3 files changed, 241 insertions(+), 69 deletions(-) delete mode 100644 source/docs/casper/concepts/hash-types.md create mode 100644 source/docs/casper/concepts/key-types.md diff --git a/config/sidebar.config.js b/config/sidebar.config.js index 896ecd10e0..c5ce0d0095 100644 --- a/config/sidebar.config.js +++ b/config/sidebar.config.js @@ -5,7 +5,7 @@ module.exports = { "concepts/intro-to-dapps", "concepts/addressable-entity", "concepts/accounts-and-keys", - "concepts/hash-types", + "concepts/key-types", "concepts/transactions-and-transaction-lifecycle", "concepts/global-state", "concepts/smart-contracts", diff --git a/source/docs/casper/concepts/hash-types.md b/source/docs/casper/concepts/hash-types.md deleted file mode 100644 index fa47196e0e..0000000000 --- a/source/docs/casper/concepts/hash-types.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Hash Types ---- - -# Understanding Hash Types - -For the sake of user convenience and compatibility, we expect the delivery of hashes and similar data in the form of a prefixed string when using the node. The following is a list of string representations used. - -## Table of Associated Hash Types {#table-of-associated-hash-types} - -|Type|Prefix|Example| -|---|---|---| -|PublicKey | | 018a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c| -|AccountHash | account-hash- | account-hash-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| -|ContractHash | contract- | contract-0101010101010101010101010101010101010101010101010101010101010101| -|ContractPackageHash | contract-package- | contract-package-0101010101010101010101010101010101010101010101010101010101010101| -|Key::Account | account-hash-| account-hash-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| -|Key::Hash | hash- | hash-0101010101010101010101010101010101010101010101010101010101010101| -|Key::URef | uref- | uref-0101010101010101010101010101010101010101010101010101010101010101-001| -|Key::Transfer | transfer- | transfer-0101010101010101010101010101010101010101010101010101010101010101| -|Key::DeployInfo | deploy- | deploy-0101010101010101010101010101010101010101010101010101010101010101| -|Key::EraInfo | era- | era-1| -|Key::Balance | balance- | balance-0101010101010101010101010101010101010101010101010101010101010101| -|Key::Bid | bid- | bid-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| -|Key::Withdraw | withdraw- | withdraw-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| -|Key::Dictionary | dictionary- | dictionary-0101010101010101010101010101010101010101010101010101010101010101| -|Key::SystemContractRegistry | system-contract-registry- |system-contract-registry-00000000000000000000000000000000| -|Key::EraSummary | era-summary- |era-summary-00000000000000000000000000000000| -|Key::Unbond | unbond- | unbond-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| -|Key::ChainspecRegistry | chainspec-registry- | chainspec-registry-11111111111111111111111111111111 | -|Key::ChecksumRegistry | checksum-registry- | checksum-registry-00000000000000000000000000000000 | -|Key::BidAddr | bid-addr- | `Unified` bid-addr-00ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70, `Validator` bid-addr-01ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70, `Delegator` bid-addr-02ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70 | -|Key::Package | package- | package-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a| -|Key::AddressableEntity | addressable-entity- | `Account` addressable-entity-account-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a, `System` addressable-entity-system-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a, `SmartContract` addressable-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a| -|Key::ByteCode | byte-code- | `v1-wasm` byte-code-v1-wasm-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a, `empty` byte-code-empty-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a| -|Key::Message | message- | message-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-topic-name-0202020202020202020202020202020202020202020202020202020202020202-f | - -## Hash and Key Explanations {#hash-and-key-explanations} - -`PublicKey` is a 32 byte asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. - -`AccountHash` is a 32 byte hash of the `PublicKey` serving to identify user accounts. - -`ContractHash` is the 32 byte hash of specific smart contract versions. You can use this to call specific contract versions. - -`ContractPackageHash` is a 32 byte hash of the smart contract package. This hash directs you to the contract package. The function `call_versioned_contract` uses `ContractPackageHash` and allows you to call the latest version of the contract (by default). It also allows you to call any version stored previously to the package. - -`Key` is a wrapper type that may contain one of several possible sets of data. -- `Key::Account` contains an AccountHash. -- `Key::Hash` contains a byte array with a length of 32, and as such can be used to pass any of the hashes. Please take note that the developer of the contract is responsible for implementation of any checks necessary on the receiving side. -- `Key::URef` contains an URef suffixed by access rights. -- `Key::Transfer` should contain the address hash for a transfer. -- `Key::DeployInfo` retains the address hash of deploy information. -- `Key::EraInfo` is the integer number of the associated era. -- `Key::Balance` is the balance of a purse. -- `Key::Bid` is used to keep track of bids for the auction contract. It is not generally used by users. -- `Key::Withdraw` is used to keep track of withdraws for the auction contract. It is not generally used by users and exists in a historical context. -- `Key::Dictionary` is the hash derived from a URef and a piece of arbitrary data and leads to a dictionary. -- `Key::SystemContractRegistry` is a unique `Key` under which a mapping of the names and ContractHashes for system contracts, including `Mint`, `Auction`, `HandlePayment` and `StandardPayment`, is stored. -- `Key::EraSummary` is a `Key` under which we store current era info. -- `Key::Unbond` is a variant of the key type that tracks unbonding purses. -- `Key::ChainspecRegistry` is a unique `Key` which contains a mapping of file names to the hash of the file itself. These files include *Chainspec.toml* and may also include *Accounts.toml* and *GlobalState.toml*. -- `Key::ChecksumRegistry` is a unique `key` variant under which we write a registry of checksums for a given block. There are two checksums in the registry, one for the execution results and the other for the approvals of all transactions in the block. -- `Key::BidAddr` manages data associated with bids for the `Auction` contract. It may be any one of three variants: `unified`, `validator`, or `delegator`. -- `Key::Package` is a `Key` under which package information is stored. -- `Key::AddressableEntity` is a `Key` under which an [`AddressableEntity`](/developers/json-rpc/types_chain.md/#addressableentity) is stored. It may be one of three variants: `Account`, `System` or `SmartContract`. -- `Key::ByteCode` is a `Key` under which a byte code record is stored. It may be one of two variants: `v1-wasm` or `empty`. -- `Key::Message` is a `Key` under which a message is stored. diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md new file mode 100644 index 0000000000..0c59c521be --- /dev/null +++ b/source/docs/casper/concepts/key-types.md @@ -0,0 +1,240 @@ +--- +title: Key Types +--- + +# Understanding Key Types + +For the sake of user convenience and compatibility, we expect the delivery of hashes, keys and similar data in the form of a prefixed string when using the node. The following is a list of string representations used. + +## Hash Explanations {#hash-explanations} + +### PublicKey + +`PublicKey` is a 32 byte asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. + +Type|Prefix|Example| +|---|---|---| +|PublicKey | | 018a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c| + +### AccountHash + +`AccountHash` is a 32 byte hash of the `PublicKey` serving to identify user accounts. + +|Type|Prefix|Example| +|---|---|---| +|AccountHash | account-hash- | account-hash-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| + +### ContractHash + +`ContractHash` is the 32 byte hash of specific smart contract versions. You can use this to call specific contract versions. + +|Type|Prefix|Example| +|---|---|---| +|ContractHash | contract- | contract-0101010101010101010101010101010101010101010101010101010101010101| + +### ContractPackageHash + +`ContractPackageHash` is a 32 byte hash of the smart contract package. This hash directs you to the contract package. The function `call_versioned_contract` uses `ContractPackageHash` and allows you to call the latest version of the contract (by default). It also allows you to call any version stored previously to the package. + +|Type|Prefix|Example| +|---|---|---| +|ContractPackageHash | contract-package- | contract-package-0101010101010101010101010101010101010101010101010101010101010101| + +## Key Explanations {#key-explanations} + +`Key` is a wrapper type that may contain one of several possible sets of data. + +### Account + +`Key::Account` contains an AccountHash. + +|Type|Prefix|Example| +|---|---|---| +|Key::Account | account-hash-| account-hash-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| + +### Hash + +`Key::Hash` contains a byte array with a length of 32, and as such can be used to pass any of the hashes. Please take note that the developer of the contract is responsible for implementation of any checks necessary on the receiving side. + +|Type|Prefix|Example| +|---|---|---| +|Key::Hash | hash- | hash-0101010101010101010101010101010101010101010101010101010101010101| + +### URef + +`Key::URef` contains an URef suffixed by access rights. + +|Type|Prefix|Example| +|---|---|---| +|Key::URef | uref- | uref-0101010101010101010101010101010101010101010101010101010101010101-001| + +### Transfer + +`Key::Transfer` should contain the address hash for a transfer. + +|Type|Prefix|Example| +|---|---|---| +|Key::Transfer | transfer- | transfer-0101010101010101010101010101010101010101010101010101010101010101| + +### DeployInfo + +`Key::DeployInfo` retains the address hash of deploy information. + +|Type|Prefix|Example| +|---|---|---| +|Key::DeployInfo | deploy- | deploy-0101010101010101010101010101010101010101010101010101010101010101| + +### EraInfo + +`Key::EraInfo` is the integer number of the associated era. + +|Type|Prefix|Example| +|---|---|---| +|Key::EraInfo | era- | era-1| + +### Balance + +`Key::Balance` is the balance of a purse. + +|Type|Prefix|Example| +|---|---|---| +|Key::Balance | balance- | balance-0101010101010101010101010101010101010101010101010101010101010101| + +### Bid + +`Key::Bid` is used to keep track of bids for the auction contract. It is not generally used by users. + +|Type|Prefix|Example| +|---|---|---| +|Key::Bid | bid- | bid-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| + +### Withdraw + +`Key::Withdraw` is used to keep track of withdraws for the auction contract. It is not generally used by users and exists in a historical context. + +|Type|Prefix|Example| +|---|---|---| +|Key::Withdraw | withdraw- | withdraw-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| + +### Dictionary + +`Key::Dictionary` is the hash derived from a URef and a piece of arbitrary data and leads to a dictionary. + +|Type|Prefix|Example| +|---|---|---| +|Key::Dictionary | dictionary- | dictionary-0101010101010101010101010101010101010101010101010101010101010101| + +### SystemContractRegistry + +`Key::SystemContractRegistry` is a unique `Key` under which a mapping of the names and ContractHashes for system contracts, including `Mint`, `Auction`, `HandlePayment` and `StandardPayment`, is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::SystemContractRegistry | system-contract-registry- |system-contract-registry-00000000000000000000000000000000| + +### EraSummary + +`Key::EraSummary` is a `Key` under which we store current era info. + +|Type|Prefix|Example| +|---|---|---| +|Key::EraSummary | era-summary- |era-summary-00000000000000000000000000000000| + +### Unbond + +`Key::Unbond` is a variant of the key type that tracks unbonding purses. + +|Type|Prefix|Example| +|---|---|---| +|Key::Unbond | unbond- | unbond-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| + +### ChainspecRegistry + +`Key::ChainspecRegistry` is a unique `Key` which contains a mapping of file names to the hash of the file itself. These files include *Chainspec.toml* and may also include *Accounts.toml* and *GlobalState.toml*. + +|Type|Prefix|Example| +|---|---|---| +|Key::ChainspecRegistry | chainspec-registry- | chainspec-registry-11111111111111111111111111111111 | + +### ChecksumRegistry + +`Key::ChecksumRegistry` is a unique `key` variant under which we write a registry of checksums for a given block. There are two checksums in the registry, one for the execution results and the other for the approvals of all transactions in the block. + +|Key::ChecksumRegistry | checksum-registry- | checksum-registry-00000000000000000000000000000000 | + +### BidAddr + +`Key::BidAddr` manages data associated with bids for the `Auction` contract. It may be any one of three variants: `unified`, `validator`, or `delegator`. + +|Type|Prefix|Example| +|---|---|---| +| `Unified` | bid-addr-00 | bid-addr-00ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70 | +| `Validator` | bid-addr-01 | bid-addr-01ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70 | +|`Delegator` | bid-addr-02 |bid-addr-02ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70 | + +### Package + +`Key::Package` is a `Key` under which package information is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::Package | package- | package-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a| + +### AddressableEntity + +`Key::AddressableEntity` is a `Key` under which an [`AddressableEntity`](/developers/json-rpc/types_chain.md/#addressableentity) is stored. It may be one of three variants: `Account`, `System` or `SmartContract`. + +|Type|Prefix|Example| +|---|---|---| +| `Account` | addressable-entity-account- |addressable-entity-account-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a | +| `System` | addressable-entity-system- | addressable-entity-system-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a | +| `SmartContract` | addressable-entity-contract- | addressable-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a| + +### ByteCode + +`Key::ByteCode` is a `Key` under which a byte code record is stored. It may be one of two variants: `v1-wasm` or `empty`. + +|Type|Prefix|Example| +|---|---|---| +| `v1-wasm` | byte-code-v1-wasm- | byte-code-v1-wasm-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a | +| `empty` | byte-code-empty- | byte-code-empty-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a | + +### Message + +`Key::Message` is a `Key` under which a message is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::Message | message- | message-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-topic-name-0202020202020202020202020202020202020202020202020202020202020202-f | + +### NamedKey + +`Key::NamedKey` is a `Key` under which a single named key entry is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::NamedKey | (named-key-?) | | + +### BlockGlobal + +`Key::BlockGlobal` is a `Key` under which per-block details are stored to global state. + +|Type|Prefix|Example| +|---|---|---| +|Key::BlockGlobal | | | + +### BalanceHold + +`Key::BalanceHold` is a `Key` under which a hold on a purse balance is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::BalanceHold | | | + +### EntryPoint + +`Key::EntryPoint` is a `Key` under which an entrypoint record is written. + +|Type|Prefix|Example| +|---|---|---| +|Key::EntryPoint | | | \ No newline at end of file From 78f429e30d6217f6e22c66dbfadce4fbf56dd885 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 9 May 2024 11:08:26 -0400 Subject: [PATCH 2/9] Revamp Hash/Key Type Doc --- source/docs/casper/concepts/key-types.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index 0c59c521be..c90f126afa 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -205,7 +205,8 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::Message | message- | message-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-topic-name-0202020202020202020202020202020202020202020202020202020202020202-f | +| Message Topic| message-topic-entity-contract- | message-topic-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a | +| Message | message-entity-contract- |message-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-0202020202020202020202020202020202020202020202020202020202020202-f| ### NamedKey @@ -213,7 +214,7 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::NamedKey | (named-key-?) | | +|Key::NamedKey | named-key-entity-contract- | named-key-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b | ### BlockGlobal @@ -221,7 +222,8 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::BlockGlobal | | | +| Block Time | block-time- | block-time-00000000000000000000000000000000000000000000000000000000000000 | +| Block Message Count | block-message-count- | block-message-count-00000000000000000000000000000000000000000000000000000000000000 | ### BalanceHold @@ -229,7 +231,7 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::BalanceHold | | | +|Key::BalanceHold | balance-hold- | balance-hold-002a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a6400000000000000 | ### EntryPoint @@ -237,4 +239,4 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::EntryPoint | | | \ No newline at end of file +|Key::EntryPoint | entry-point-v2-entity-contract- | entry-point-v2-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-1 | \ No newline at end of file From 6c31f23cfbf14baa5f39cd9fc0ad9a6608b64ff0 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 9 May 2024 11:17:07 -0400 Subject: [PATCH 3/9] Link fixes --- source/docs/casper/concepts/addressable-entity.md | 2 +- source/docs/casper/concepts/dictionaries.md | 4 ++-- source/docs/casper/concepts/index.md | 2 +- .../casper/developers/dapps/monitor-and-consume-events.md | 4 ++-- .../casper/developers/writing-onchain-code/simple-contract.md | 2 +- source/docs/casper/resources/beginner/upgrade-contract.md | 2 +- source/docs/casper/resources/changelog.md | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/docs/casper/concepts/addressable-entity.md b/source/docs/casper/concepts/addressable-entity.md index 1de497ebcb..d93f6557cd 100644 --- a/source/docs/casper/concepts/addressable-entity.md +++ b/source/docs/casper/concepts/addressable-entity.md @@ -26,5 +26,5 @@ As part of the migration to Casper 2.0, system contracts (`Mint`, `Auction` and - [Accounts and Keys](../concepts/accounts-and-keys.md) - [Smart Contracts](../concepts/smart-contracts.md) -- [Hash Types](../concepts/hash-types.md) +- [Hash Types](../concepts/key-types.md) - [Multi-Signature Management](../resources/advanced/multi-sig/index.md) diff --git a/source/docs/casper/concepts/dictionaries.md b/source/docs/casper/concepts/dictionaries.md index 0cf61cf10d..6609545553 100644 --- a/source/docs/casper/concepts/dictionaries.md +++ b/source/docs/casper/concepts/dictionaries.md @@ -3,7 +3,7 @@ title: Dictionaries --- # Understanding Dictionaries {#dictionaries} -In a Casper network, you can now store sets of data under [`Keys`](./hash-types.md#hash-and-key-explanations). Previously, [URefs](./glossary/U.md#uref) were the exclusive means by which users could store data in global state. To maintain persistent access to these URefs, they would have to be stored within an `addressable entity`'s context. In the case of Contracts, sustained and continuous use of URefs would result in the expansion of the associated [NamedKeys](./glossary/N.md#namedkeys) structures. +In a Casper network, you can now store sets of data under [`Keys`](./key-types.md#hash-and-key-explanations). Previously, [URefs](./glossary/U.md#uref) were the exclusive means by which users could store data in global state. To maintain persistent access to these URefs, they would have to be stored within an `addressable entity`'s context. In the case of Contracts, sustained and continuous use of URefs would result in the expansion of the associated [NamedKeys](./glossary/N.md#namedkeys) structures. Individual value changes to data stored within the NamedKeys would require deserializing the entire NamedKeys data structure, increasing gas costs over time and thus having a negative impact. Additionally, users storing large subsets of mapped data structures would face the same deep copy problem where minor or single updates required the complete deserialization of the map structure, also leading to increased gas costs. @@ -13,7 +13,7 @@ Casper's Condor release shifts `NamedKeys` to a top-level key, removing this res ## Seed URefs -Items within a dictionary exist as individual records stored underneath their unique [dictionary address](./hash-types.md#hash-and-key-explanations) in global state. In other words, items associated with a specific dictionary share the same seed [`URef`](./design/casper-design.md#uref-head) but are otherwise independent of each other. Dictionary items are not stored beneath this URef, it is only used to create the dictionary key. +Items within a dictionary exist as individual records stored underneath their unique [dictionary address](./key-types.md#hash-and-key-explanations) in global state. In other words, items associated with a specific dictionary share the same seed [`URef`](./design/casper-design.md#uref-head) but are otherwise independent of each other. Dictionary items are not stored beneath this URef, it is only used to create the dictionary key. As each dictionary item exists as a stand-alone entity in global state, regularly used dictionary keys may be used directly without referencing their seed URef. diff --git a/source/docs/casper/concepts/index.md b/source/docs/casper/concepts/index.md index 050faa590f..8369396ebc 100644 --- a/source/docs/casper/concepts/index.md +++ b/source/docs/casper/concepts/index.md @@ -16,7 +16,7 @@ This section of the documentation covers the core concepts underpinning the Casp | [Introduction to dApps](./intro-to-dapps.md) | Developing distributed applications on the Casper blockchain | | [Addressable Entities](./addressable-entity.md) | Learn about addressable entities and how they relate to accounts and smart contracts. | | [Accounts and Cryptographic Keys](./accounts-and-keys.md) | The Casper programming model is account-based. Learn how Casper accounts work and how they are secured | -| [Hash Types](./hash-types.md) | Hashes are used throughout the Casper ecosystem for keys, addresses, packaging data, and more | +| [Key Types](./key-types.md) | Hashes/Keys are used throughout the Casper ecosystem for addresses, packaging data, and more | | [Global State](./global-state.md) | Learn about the storage layer for the Casper blockchain. All accounts, contracts, and data are stored in global state | | [Call Stacks](./callstack.md) | Learn how Casper manages the calling of a contract | | [Transactions and the Transaction Lifecycle](./transactions-and-transaction-lifecycle.md) | Transactions are a concept fundamental to the Casper blockchain. Learn about transactions, what they are for, how to create and send them | diff --git a/source/docs/casper/developers/dapps/monitor-and-consume-events.md b/source/docs/casper/developers/dapps/monitor-and-consume-events.md index 7212c8f0c9..c7db6325fa 100644 --- a/source/docs/casper/developers/dapps/monitor-and-consume-events.md +++ b/source/docs/casper/developers/dapps/monitor-and-consume-events.md @@ -190,9 +190,9 @@ A `BlockAdded` event is emitted when a new block is added to the blockchain and } ``` -* [hash](../../concepts/hash-types.md) - The blake2b hash of the Deploy. +* [hash](../../concepts/key-types.md) - The blake2b hash of the Deploy. * [account](../../concepts/serialization-standard.md#serialization-standard-account) - The hexadecimal-encoded public key of the account submitting the Deploy. -* [body_hash](../../concepts/hash-types.md) - The blake2b hash of the Deploy body. +* [body_hash](../../concepts/key-types.md) - The blake2b hash of the Deploy body. * [payment](../../concepts/glossary/P.md#payment-code) - Gas payment information. * [session](../writing-onchain-code/contract-vs-session.md#what-is-session-code) - The session logic defining the Deploy's functionality. * [approvals](../json-rpc/types_chain.md#approval) - The signer's hexadecimal-encoded public key and signature. diff --git a/source/docs/casper/developers/writing-onchain-code/simple-contract.md b/source/docs/casper/developers/writing-onchain-code/simple-contract.md index e9b93a6ce6..6bb0947dd5 100644 --- a/source/docs/casper/developers/writing-onchain-code/simple-contract.md +++ b/source/docs/casper/developers/writing-onchain-code/simple-contract.md @@ -12,7 +12,7 @@ Smart contracts exist as stored on-chain logic, allowing disparate users to call On the Casper platform, developers may write smart contracts in any language that compiles to Wasm binaries. This tutorial focuses specifically on writing a smart contract in the Rust language. The Rust compiler compiles the contract code into Wasm. After that, the Wasm binary can be [sent to a node](../cli/installing-contracts.md) on a Casper network using a transaction. Nodes within the network then [gossip transactions](../../concepts/design/p2p.md#communications-gossiping), include them within a block, and finalize them. After finalizing, the network executes the transactions within the block. -Further, the Casper platform allows for [upgradable contracts](./upgrading-contracts.md). A [ContractPackage](https://docs.rs/casper-types/latest/casper_types/contracts/struct.ContractPackage.html) is created through the [new_contract](https://docs.rs/casper-contract/latest/casper_contract/contract_api/storage/fn.new_contract.html) or [new_locked_contract](https://docs.rs/casper-contract/latest/casper_contract/contract_api/storage/fn.new_locked_contract.html) methods. Through these methods, the Casper execution engine automatically creates the new contract package and assigns a [`ContractPackageHash`](../../concepts/hash-types.md#hash-and-key-explanations). The new contract is added to this package with a [`ContractHash`](https://docs.rs/casper-types/latest/casper_types/contracts/struct.ContractHash.html) key. The execution engine stores the new contract within the contract package alongside any previously installed contract versions, if applicable. +Further, the Casper platform allows for [upgradable contracts](./upgrading-contracts.md). A [ContractPackage](https://docs.rs/casper-types/latest/casper_types/contracts/struct.ContractPackage.html) is created through the [new_contract](https://docs.rs/casper-contract/latest/casper_contract/contract_api/storage/fn.new_contract.html) or [new_locked_contract](https://docs.rs/casper-contract/latest/casper_contract/contract_api/storage/fn.new_locked_contract.html) methods. Through these methods, the Casper execution engine automatically creates the new contract package and assigns a [`ContractPackageHash`](../../concepts/key-types.md#hash-and-key-explanations). The new contract is added to this package with a [`ContractHash`](https://docs.rs/casper-types/latest/casper_types/contracts/struct.ContractHash.html) key. The execution engine stores the new contract within the contract package alongside any previously installed contract versions, if applicable. The `new_contract` and `new_locked_contract` methods are a convenience that automatically creates the package associated with a new contract. Developers choosing not to use these methods must first create a contract package to function as a container for their new contract. diff --git a/source/docs/casper/resources/beginner/upgrade-contract.md b/source/docs/casper/resources/beginner/upgrade-contract.md index a88f72c250..99c6eb49de 100644 --- a/source/docs/casper/resources/beginner/upgrade-contract.md +++ b/source/docs/casper/resources/beginner/upgrade-contract.md @@ -89,7 +89,7 @@ To add a new contract version in the package, invoke the [add_contract_version]( Explanation of arguments: -- `contract_package_hash` - This hash directs you to the contract package. See [Hash and Key Explanations](../../concepts/hash-types.md#hash-and-key-explanations). +- `contract_package_hash` - This hash directs you to the contract package. See [Hash and Key Explanations](../../concepts/key-types.md#hash-and-key-explanations). - `entry_points` - Entry points of the contract, which can be modified or newly added. - `named_keys` - Named key pairs of the contract. diff --git a/source/docs/casper/resources/changelog.md b/source/docs/casper/resources/changelog.md index ceeee4c2bd..dcf1e63b11 100644 --- a/source/docs/casper/resources/changelog.md +++ b/source/docs/casper/resources/changelog.md @@ -6,7 +6,7 @@ The following are changes introduced alongside release of the Condor network upgrade. -[Understanding Hash Types](../concepts/hash-types.md) - Additional Key Types. +[Understanding Key Types](../concepts/key-types.md) - Additional Key Types and document restructuring. [Serialization Standard](../concepts/serialization-standard.md) - Serialization information for new types. From 8090ead0be5e3f7b04d225eecb4c297f89ad330d Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 10 May 2024 10:45:41 -0400 Subject: [PATCH 4/9] Update source/docs/casper/concepts/key-types.md Co-authored-by: Iulia Popescu --- source/docs/casper/concepts/key-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index c90f126afa..e15610b127 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -4,7 +4,7 @@ title: Key Types # Understanding Key Types -For the sake of user convenience and compatibility, we expect the delivery of hashes, keys and similar data in the form of a prefixed string when using the node. The following is a list of string representations used. +For user convenience and compatibility, we expect the delivery of hashes, keys, and similar data as a prefixed string when using the node. The following is a list of string representations used. ## Hash Explanations {#hash-explanations} From 0cdbd109104f99051e2a11b777e2bf30596b5d97 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 10 May 2024 10:46:05 -0400 Subject: [PATCH 5/9] Update source/docs/casper/concepts/key-types.md Co-authored-by: Iulia Popescu --- source/docs/casper/concepts/key-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index e15610b127..31ec52005f 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -54,7 +54,7 @@ Type|Prefix|Example| ### Hash -`Key::Hash` contains a byte array with a length of 32, and as such can be used to pass any of the hashes. Please take note that the developer of the contract is responsible for implementation of any checks necessary on the receiving side. +`Key::Hash` contains a byte array with a length of 32, which can be used to pass any of the hashes. Please take note that the developer of the contract is responsible for the implementation of any checks necessary on the receiving side. |Type|Prefix|Example| |---|---|---| From c2cd286ea7cfd25e0745d0a8e5481839f17546b2 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 10 May 2024 13:22:21 -0400 Subject: [PATCH 6/9] Update key-types.md --- source/docs/casper/concepts/key-types.md | 33 ++++++++++++------------ 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index 31ec52005f..58db82985c 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -10,7 +10,7 @@ For user convenience and compatibility, we expect the delivery of hashes, keys, ### PublicKey -`PublicKey` is a 32 byte asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. +`PublicKey` is a 32-bytes asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. Type|Prefix|Example| |---|---|---| @@ -18,7 +18,7 @@ Type|Prefix|Example| ### AccountHash -`AccountHash` is a 32 byte hash of the `PublicKey` serving to identify user accounts. +`AccountHash` is a 32-bytes hash of the `PublicKey` serving to identify user accounts. |Type|Prefix|Example| |---|---|---| @@ -26,7 +26,7 @@ Type|Prefix|Example| ### ContractHash -`ContractHash` is the 32 byte hash of specific smart contract versions. You can use this to call specific contract versions. +`ContractHash` is the 32-bytes hash of specific smart contract versions. You can use this to call specific contract versions. |Type|Prefix|Example| |---|---|---| @@ -34,7 +34,7 @@ Type|Prefix|Example| ### ContractPackageHash -`ContractPackageHash` is a 32 byte hash of the smart contract package. This hash directs you to the contract package. The function `call_versioned_contract` uses `ContractPackageHash` and allows you to call the latest version of the contract (by default). It also allows you to call any version stored previously to the package. +`ContractPackageHash` is a 32-bytes hash of the smart contract package. This hash directs you to the contract package. The function `call_versioned_contract` uses `ContractPackageHash` and allows you to call the latest version of the contract (by default). It also allows you to call any version stored previously to the package. |Type|Prefix|Example| |---|---|---| @@ -62,7 +62,7 @@ Type|Prefix|Example| ### URef -`Key::URef` contains an URef suffixed by access rights. +`Key::URef` contains an URef suffixed by [access rights](./developers/dapps/uref-security.md). |Type|Prefix|Example| |---|---|---| @@ -100,6 +100,14 @@ Type|Prefix|Example| |---|---|---| |Key::Balance | balance- | balance-0101010101010101010101010101010101010101010101010101010101010101| +### BalanceHold + +`Key::BalanceHold` is a `Key` under which a hold on a purse balance is stored. + +|Type|Prefix|Example| +|---|---|---| +|Key::BalanceHold | balance-hold- | balance-hold-002a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a6400000000000000 | + ### Bid `Key::Bid` is used to keep track of bids for the auction contract. It is not generally used by users. @@ -130,7 +138,7 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::SystemContractRegistry | system-contract-registry- |system-contract-registry-00000000000000000000000000000000| +|Key::SystemContractRegistry | system-entity-registry- |system-entity-registry-0000000000000000000000000000000000000000000000000000000000000000| ### EraSummary @@ -214,7 +222,8 @@ Type|Prefix|Example| |Type|Prefix|Example| |---|---|---| -|Key::NamedKey | named-key-entity-contract- | named-key-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b | +| Account Named Key | named-key-entity-account- | named-key-entity-account-928d914bdcad3ca269e750f63ed3615c5d3f615cf97dba87006fd9f979dacb3c-dde6f264c89fe385a5b07c26d77284d6fddabe79653c5ca25cec39a6363e6ec7 | +| Contract Named Key | named-key-entity-contract- | named-key-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b | ### BlockGlobal @@ -225,18 +234,10 @@ Type|Prefix|Example| | Block Time | block-time- | block-time-00000000000000000000000000000000000000000000000000000000000000 | | Block Message Count | block-message-count- | block-message-count-00000000000000000000000000000000000000000000000000000000000000 | -### BalanceHold - -`Key::BalanceHold` is a `Key` under which a hold on a purse balance is stored. - -|Type|Prefix|Example| -|---|---|---| -|Key::BalanceHold | balance-hold- | balance-hold-002a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a6400000000000000 | - ### EntryPoint `Key::EntryPoint` is a `Key` under which an entrypoint record is written. |Type|Prefix|Example| |---|---|---| -|Key::EntryPoint | entry-point-v2-entity-contract- | entry-point-v2-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-1 | \ No newline at end of file +|Key::EntryPoint | entry-point-v2-entity-contract- | entry-point-v2-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-1 | From 3832cabd1c71637724a63880e344e532bf5ce74a Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 10 May 2024 13:30:55 -0400 Subject: [PATCH 7/9] Update key-types.md --- source/docs/casper/concepts/key-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index 58db82985c..be1140b7a9 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -62,7 +62,7 @@ Type|Prefix|Example| ### URef -`Key::URef` contains an URef suffixed by [access rights](./developers/dapps/uref-security.md). +`Key::URef` contains an URef suffixed by [access rights](../developers/dapps/uref-security.md). |Type|Prefix|Example| |---|---|---| From ca6ed17587f13db4d649452cda57a1fd909437b9 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Mon, 13 May 2024 13:30:14 -0400 Subject: [PATCH 8/9] Update key-types.md --- source/docs/casper/concepts/key-types.md | 34 ------------------------ 1 file changed, 34 deletions(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index be1140b7a9..ab255cb551 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -6,40 +6,6 @@ title: Key Types For user convenience and compatibility, we expect the delivery of hashes, keys, and similar data as a prefixed string when using the node. The following is a list of string representations used. -## Hash Explanations {#hash-explanations} - -### PublicKey - -`PublicKey` is a 32-bytes asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. - -Type|Prefix|Example| -|---|---|---| -|PublicKey | | 018a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c| - -### AccountHash - -`AccountHash` is a 32-bytes hash of the `PublicKey` serving to identify user accounts. - -|Type|Prefix|Example| -|---|---|---| -|AccountHash | account-hash- | account-hash-ef4687f74d465826239bab05c4e1bdd2223dd8c201b96f361f775125e624ef70| - -### ContractHash - -`ContractHash` is the 32-bytes hash of specific smart contract versions. You can use this to call specific contract versions. - -|Type|Prefix|Example| -|---|---|---| -|ContractHash | contract- | contract-0101010101010101010101010101010101010101010101010101010101010101| - -### ContractPackageHash - -`ContractPackageHash` is a 32-bytes hash of the smart contract package. This hash directs you to the contract package. The function `call_versioned_contract` uses `ContractPackageHash` and allows you to call the latest version of the contract (by default). It also allows you to call any version stored previously to the package. - -|Type|Prefix|Example| -|---|---|---| -|ContractPackageHash | contract-package- | contract-package-0101010101010101010101010101010101010101010101010101010101010101| - ## Key Explanations {#key-explanations} `Key` is a wrapper type that may contain one of several possible sets of data. From 18d78baffe2f36ffff8b6a7b18af8a905cb48f4d Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Mon, 13 May 2024 13:35:29 -0400 Subject: [PATCH 9/9] Update key-types.md --- source/docs/casper/concepts/key-types.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/docs/casper/concepts/key-types.md b/source/docs/casper/concepts/key-types.md index ab255cb551..c8e080474b 100644 --- a/source/docs/casper/concepts/key-types.md +++ b/source/docs/casper/concepts/key-types.md @@ -206,4 +206,5 @@ For user convenience and compatibility, we expect the delivery of hashes, keys, |Type|Prefix|Example| |---|---|---| -|Key::EntryPoint | entry-point-v2-entity-contract- | entry-point-v2-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-1 | +| V1 Entry Point | entry-point-v1-entity-contract- | entry-point-v1-entity-contract-53c02487fa9a4bb1cd3e27b849e942cddb97caacb357e5b6bc86f702b2e32dbb-3eba75fc27f0ec2786e09c09d72d61e4c28a86d44d8efc9911460d5438396481 | +| V2 Entry Point | entry-point-v2-entity-contract- | entry-point-v2-entity-contract-2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a-1 |