From 548acb80ca298930850cffb2fc2c2865863a4fc6 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 5 Jul 2024 12:24:14 -0400 Subject: [PATCH 1/9] Binary Serialization Standard --- config/sidebar.config.js | 36 +- .../casper/concepts/design/casper-design.md | 8 +- .../concepts/design/networking-protocol.md | 2 +- source/docs/casper/concepts/global-state.md | 2 +- source/docs/casper/concepts/glossary/D.md | 2 +- source/docs/casper/concepts/index.md | 2 +- .../casper/concepts/serialization-standard.md | 837 ---------------- .../casper/concepts/serialization/index.md | 11 + .../concepts/serialization/primitives.md | 190 ++++ .../concepts/serialization/structures.md | 462 +++++++++ .../casper/concepts/serialization/types.md | 910 ++++++++++++++++++ .../transactions-and-transaction-lifecycle.md | 4 +- .../developers/cli/sending-transactions.md | 2 +- .../docs/casper/developers/dapps/sdk/index.md | 2 +- .../developers/dapps/signing-a-transaction.md | 8 +- .../casper/developers/json-rpc/types_cl.md | 2 +- .../advanced/list-auth-keys-tutorial.md | 10 +- .../resources/advanced/storage-workflow.md | 2 +- source/docs/casper/resources/changelog.md | 2 +- 19 files changed, 1622 insertions(+), 872 deletions(-) delete mode 100644 source/docs/casper/concepts/serialization-standard.md create mode 100644 source/docs/casper/concepts/serialization/index.md create mode 100644 source/docs/casper/concepts/serialization/primitives.md create mode 100644 source/docs/casper/concepts/serialization/structures.md create mode 100644 source/docs/casper/concepts/serialization/types.md diff --git a/config/sidebar.config.js b/config/sidebar.config.js index 123eb88dd6..3891486ed7 100644 --- a/config/sidebar.config.js +++ b/config/sidebar.config.js @@ -2,17 +2,6 @@ module.exports = { concepts: [ "concepts/index", "concepts/about", - "concepts/intro-to-dapps", - "concepts/addressable-entity", - "concepts/accounts-and-keys", - "concepts/key-types", - "concepts/transactions-and-transaction-lifecycle", - "concepts/global-state", - "concepts/smart-contracts", - "concepts/list-auth-keys", - "concepts/callstack", - "concepts/dictionaries", - "concepts/serialization-standard", { type: "category", label: "Design", @@ -104,6 +93,31 @@ module.exports = { "concepts/glossary/Z", ], }, + { + type: "category", + label: "Binary Serialization Standard", + collapsible: true, + collapsed: true, + link: { + type: "doc", + id: "concepts/serialization/index", + }, + items: [ + "concepts/serialization/primitives", + "concepts/serialization/structures", + "concepts/serialization/types", + ], + }, + "concepts/intro-to-dapps", + "concepts/addressable-entity", + "concepts/accounts-and-keys", + "concepts/key-types", + "concepts/transactions-and-transaction-lifecycle", + "concepts/global-state", + "concepts/smart-contracts", + "concepts/list-auth-keys", + "concepts/callstack", + "concepts/dictionaries", ], developers: [ "developers/index", diff --git a/source/docs/casper/concepts/design/casper-design.md b/source/docs/casper/concepts/design/casper-design.md index c7bcc9ed25..8954f05667 100644 --- a/source/docs/casper/concepts/design/casper-design.md +++ b/source/docs/casper/concepts/design/casper-design.md @@ -134,7 +134,7 @@ In the case where there is a reference to stored on-chain Wasm (smart contracts) ## Unforgeable Reference (URef) {#uref-head} -This key type is used for storing any value except `Account`. Additionally, `URef`s used in Wasm carry permission information to prevent unauthorized usage of the value stored under the key. The runtime tracks this permission information. This means that if malicious Wasm attempts to produce a `URef` with permissions that the Wasm does not have, the Wasm has attempted to "forge" the unforgeable reference, and the runtime will raise a forged `URef` error. Permissions for a `URef` can be given across contract calls, allowing data stored under a `URef` to be shared in a controlled way. The 32-byte identifier representing the key is generated randomly by the runtime (see [Execution Semantics](#execution-semantics-head) for more information). The serialization for `Access Rights` that define the permissions for `URefs` is detailed in the [CLValues](../serialization-standard.md) section. +This key type is used for storing any value except `Account`. Additionally, `URef`s used in Wasm carry permission information to prevent unauthorized usage of the value stored under the key. The runtime tracks this permission information. This means that if malicious Wasm attempts to produce a `URef` with permissions that the Wasm does not have, the Wasm has attempted to "forge" the unforgeable reference, and the runtime will raise a forged `URef` error. Permissions for a `URef` can be given across contract calls, allowing data stored under a `URef` to be shared in a controlled way. The 32-byte identifier representing the key is generated randomly by the runtime (see [Execution Semantics](#execution-semantics-head) for more information). The serialization for `Access Rights` that define the permissions for `URefs` is detailed in the [CLValues](../serialization/primitives.md#clvalue) section. ### Permissions for `URef`s {#uref-permissions} @@ -152,7 +152,7 @@ The ability to pass `URef`s between contexts via `call_contract` / `ret`, allows ### `URef`s and Purses -Purses represent a unique type of `URef` used for accounting measures within a Casper network. `URef`s exist as a top-level entity, meaning that individual entities do not own ‘URef’s. As described above, entities possess certain `Access Rights`, allowing them to interact with the given `URef`. While an account entity will possess an associated `URef` representing their main purse, this `URef` exists as a [`Unit`](../serialization-standard.md#clvalue-unit) and corresponds to a *balance* key within the Casper *mint*. The individual balance key within the Casper mint is the account entity's purse, with transfers authorized solely through the associated `URef` and the `Access Rights` granted to it. +Purses represent a unique type of `URef` used for accounting measures within a Casper network. `URef`s exist as a top-level entity, meaning that individual entities do not own ‘URef’s. As described above, entities possess certain `Access Rights`, allowing them to interact with the given `URef`. While an account entity will possess an associated `URef` representing their main purse, this `URef` exists as a [`Unit`](../serialization/primitives.md#unit-clvalue-unit) and corresponds to a *balance* key within the Casper *mint*. The individual balance key within the Casper mint is the account entity's purse, with transfers authorized solely through the associated `URef` and the `Access Rights` granted to it. Through this logic, the Casper mint holds all motes on the network and transfers between balance keys at the behest of entities as required. @@ -176,7 +176,7 @@ The `block_hash` is the `blake2b256` hash of the block header. #### Header {#header} -The [block header](../serialization-standard.md#serialization-standard-block) contains the following fields: +The [block header](../serialization/structures.md#block-header) contains the following fields: * `parent_hash` @@ -226,7 +226,7 @@ The block body contains an **ordered** list of transaction hashes. All transacti The block body also contains the public key of the validator that proposed the block. -Refer to the [Serialization Standard](../serialization-standard.md) for additional information on how blocks and transactions are serialized. +Refer to the [Serialization Standard](../serialization/index.md) for additional information on how blocks and transactions are serialized. ## Tokens {#tokens-head} diff --git a/source/docs/casper/concepts/design/networking-protocol.md b/source/docs/casper/concepts/design/networking-protocol.md index 94754ad5e7..fe0ae2be2a 100644 --- a/source/docs/casper/concepts/design/networking-protocol.md +++ b/source/docs/casper/concepts/design/networking-protocol.md @@ -263,7 +263,7 @@ If the item was not found, `serialized_item` MUST contain a `FetchedOrNotFound:: A node MUST not send any items to a peer that it itself has not verified. -The following table shows which tag corresponds to which ID and item type. Type definitions for `DeployHash` and `GossippedAddress` can be found earlier in this document, other types are described following this section. Further details of many of these types can be found in the [Serialization Standard](../serialization-standard.md), but be aware that those docs describe serializing using bytesrepr rather than bincode. +The following table shows which tag corresponds to which ID and item type. Type definitions for `DeployHash` and `GossippedAddress` can be found earlier in this document, other types are described following this section. Further details of many of these types can be found in the [Serialization Standard](../serialization/index.md), but be aware that those docs describe serializing using bytesrepr rather than bincode. | Tag | ID type | Payload (item) type | | ---------------------------------------- | --------------------- | -------------------------- | diff --git a/source/docs/casper/concepts/global-state.md b/source/docs/casper/concepts/global-state.md index 676a2d5995..36aa115c10 100644 --- a/source/docs/casper/concepts/global-state.md +++ b/source/docs/casper/concepts/global-state.md @@ -6,7 +6,7 @@ The storage layer for the Casper blockchain is called *global state* and has the :::note -Refer to [Keys and Permissions](./serialization-standard.md#serialization-standard-state-keys) for further information on keys. +Refer to [Keys and Permissions](./serialization/types.md#serialization-standard-serialization-key) for further information on keys. ::: diff --git a/source/docs/casper/concepts/glossary/D.md b/source/docs/casper/concepts/glossary/D.md index 0bce642568..488a9a77e9 100644 --- a/source/docs/casper/concepts/glossary/D.md +++ b/source/docs/casper/concepts/glossary/D.md @@ -26,7 +26,7 @@ Casper's Condor release introduces the [Transaction](./T.md#transaction). Legacy All deploys on a Casper network can be broadly categorized as some unit of work that, when executed and committed, affects change to the [global state](./G.md#global-state). -Review the [deploy data structure](../serialization-standard.md#deploy) and the [deploy implementation](https://github.com/casper-network/casper-node/blob/master/node/src/types/deploy.rs#L475) for more details. +Review the [deploy data structure](../serialization/structures.md#deploy) and the [deploy implementation](https://github.com/casper-network/casper-node/blob/master/node/src/types/deploy.rs#L475) for more details. ## Dictionary {#dictionary} diff --git a/source/docs/casper/concepts/index.md b/source/docs/casper/concepts/index.md index 8369396ebc..99973605bd 100644 --- a/source/docs/casper/concepts/index.md +++ b/source/docs/casper/concepts/index.md @@ -22,7 +22,7 @@ This section of the documentation covers the core concepts underpinning the Casp | [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 | | [Smart Contracts](./smart-contracts.md) | Learn how to develop smart contracts on Casper | | [Dictionaries](./dictionaries.md) | Learn about dictionaries, which are a primary construct for storing and retrieving data on the Casper platform | -| [Serialization](./serialization-standard.md) | Learn about serializing data types and the Casper Serialization Standard | +| [Serialization](./serialization/index.md) | Learn about serializing data types and the Casper Serialization Standard | | [Design](./design/index.md) | The high-level design of a Casper network | | [Economics](./economics/index.md) | Learn about the Casper on-chain economics | | [Glossary](./glossary/index.md) | A compendium of all the terms used in Casper, in alphabetical order | diff --git a/source/docs/casper/concepts/serialization-standard.md b/source/docs/casper/concepts/serialization-standard.md deleted file mode 100644 index 0c50940899..0000000000 --- a/source/docs/casper/concepts/serialization-standard.md +++ /dev/null @@ -1,837 +0,0 @@ -# Serialization Standard {#serialization-standard-head} - -We provide a custom implementation to serialize data structures used by the Casper node to their byte representation. This document details how this custom serialization is implemented, allowing developers to build a library that implements the custom serialization. - -In your smart contracts, you can implement serialization using `cltype-any`. - -## Account {#serialization-standard-account} - -An Account is a structure that represents a user on a Casper network. The account structure consists of the following fields: - -- [`account_hash`](#account-hash) - -- [`named_keys`](#namedkey) - -- `main_purse` - - The account's main purse `URef`. You may find information on `URef` serialization [here](#clvalue-uref). - -- [`associated_keys`](#associated-keys) - -- [`action_thresholds`](#action-thresholds) - -## Account Hash {#account-hash} - -A `blake2b` hash of the public key, representing the address of a user's account. The account hash serializes as a 32-byte buffer containing the bytes of the account hash. - -## Action Thresholds {#action-thresholds} - -The minimum weight thresholds that have to be met when executing an action of a certain type. It serializes as three consecutive [`u8` values](#clvalue-numeric) as follows. - -- `deployment` The minimum weight threshold required to perform deployment actions as a `u8` value. - -- `upgrade_management` The minimum weight threshold required to perform upgrade management actions as a `u8` value. - -- `key_management` The minimum weight threshold required to perform key management actions as a `u8` value. - -## Activation Point {#activation-point} - -The first era to which the associated protocol version applies. It serializes as a single [`u8`](#clvalue-numeric) tag indicating if the era in question is genesis. If it is the genesis era, the following bytes will be a `timestamp`. If not, the bytes represent an `era_id`. - -- `era_id` An [Era ID newtype](#eraid) identifying the era when the protocol version will activate. - -- `timestamp` A [timestamp](#timestamp) if the activation point is of the Genesis variant. - -## Approval {#approval} - -A struct containing a signature and the public key of the signer. - -- `signature` The approval signature, which serializes as the byte representation of the [`Signature`](#signature). The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. - -- `signer` The public key of the approvals signer. It serializes to the byte representation of the [`PublicKey`](#clvalue-publickey). If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. - -## AssociatedKey {#associatedkey} - -A key granted limited permissions to an Account, for purposes such as multisig. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of keys and weights held within. The remainder consists of a repeating pattern of serialized named keys and then weights of the length dictated by the first four bytes. - -- `account_hash` The [account hash](#account-hash) of the associated key. - -- `weight` The weight of an associated key. The weight serializes as a [`u8` value](#clvalue-numeric). - -## AvailableBlockRange {#availableblockrange} - -An unbroken, inclusive range of blocks. It serializes as two consecutive [`u64` values](#clvalue-numeric) containing the following two fields: - -- `low` The inclusive lower bound of the range. - -- `high` - The inclusive upper bound of the range. - -## Bid {#bid} - -An entry in the validator map. The structure consists of the following fields: - -- `validator_public_key` The validator's public key. It serializes as a [`PublicKey`](#clvalue-publickey). - -- `bonding_purse` The purse used for bonding. It serializes as a [`Uref`](#clvalue-uref). - -- `staked_amount` The amount of tokens staked by a validator (not including delegators). It serializes as a [`U512` value](#clvalue-numeric). - -- `delegation_rate` The delegation rate of the bid. It serializes as an `i32` signed 32-bit integer primitive. - -- `vesting_schedule` The vesting schedule for a genesis validator. `None` if it is a non-genesis validator. It serializes as an [`Option`](#clvalue-option). - -- `delegators` The validator's delegators, indexed by their public keys. They are serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of `PublicKey`s and delegators held within. The remainder consists of a repeating pattern of serialized `PublicKey`s and then delegators of the length dictated by the first four bytes. - -- `inactive` If the validator has been evicted. A [boolean](#clvalue-boolean) value that serializes as a single byte; `true` maps to `1`, while `false` maps to `0`. - -## Block {#serialization-standard-block} - -A block is the core component of the Casper linear blockchain, used in two contexts: - -1. A data structure containing a collection of transactions. Blocks form the primary structure of the blockchain. -2. A message that is exchanged between nodes containing the data structure as explained in (1). - -Each block has a globally unique ID, achieved by hashing the contents of the block. - -Each block points to its parent. An exception is the first block, which has no parent. - -A block is structurally defined as follows: - -- `hash`: A hash over the header of the block. -- `header`: The header of the block that contains information about the contents of the block with additional metadata. -- `body`: The block's body contains the proposer of the block and hashes of deploys and transfers contained within it. - -### Block hash {#block-hash} - -The block hash is a `Digest` over the contents of the block Header. The `BlockHash` serializes as the byte representation of the hash itself. - -### Block header {#block-header} - -The header portion of a block, structurally, is defined as follows: - -- `parent_hash`: is the hash of the parent block. It serializes to the byte representation of the parent hash. The serialized buffer of the `parent_hash` is 32 bytes long. -- `state_root_hash`: is the global state root hash produced by executing this block's body. It serializes to the byte representation of the `state root hash`. The serialized buffer of the `state_root_hash` is 32 bytes long. -- `body_hash`: the hash of the block body. It serializes to the byte representation of the body hash. The serialized buffer of the `body_hash` is 32 bytes long. -- `random_bit`: is a boolean needed for initializing a future era. It is serialized as a single byte; true maps to 1, while false maps to 0. -- `accumulated_seed`: A seed needed for initializing a future era. It serializes to the byte representation of the parent Hash. The serialized buffer of the `accumulated_hash` is 32 bytes long. -- `era_end`: contains equivocation and reward information to be included in the terminal finalized block. It is an optional field. Thus if the field is set as `None`, it serializes to _0_. The serialization of the other case is described in the EraEnd. -- `timestamp`: The timestamp from when the block was proposed. It serializes as a single `u64` value. The serialization of a `u64` value is described in the CLValues section. -- `era_id`: Era ID in which this block was created. It serializes as a single `u64` value. -- `height`: The height of this block, i.e., the number of ancestors. It serializes as a single `u64` value. -- `protocol_version`: The version of the Casper network when this block was proposed. It is 3-element tuple containing `u32` values. It serializes as a buffer containing the three `u32` serialized values. Refer to the CLValues section on how `u32` values are serialized. - -### EraEnd {#serialization-standard-era-end} - -`EraEnd` as represented within the block header, is a struct containing two fields. - -- `era_report`: The first field is termed as `EraReport` and contains information about equivocators and rewards for an era. -- `next_era_validator_weights`: The second field is map for the validators and their weights for the era to follow. - -`EraReport` itself contains two fields: - -- `equivocators`: A vector of `PublicKey`. -- `rewards`: A Binary Tree Map of `PublicKey` and `u64`. - -When serializing an EraReport, the buffer is first filled with the individual serialization of the PublicKey contained within the vector. - -- If the `PublicKey` is an `Ed25519` key, the first byte within the buffer is a `1` followed by the individual bytes of the serialized key. -- If the `PublicKey` is an `Secp256k1` key, the first byte within the buffer is a `2` followed by the individual bytes of the serialized key. - -When serializing the overarching struct of `EraEnd`, we first allocate a buffer, which contains the serialized representation of the `EraReport` as described above, followed by the serialized BTreeMap. - -Note that `EraEnd` is an optional field. Thus the above scheme only applies if there is an `EraEnd`; if there is no era end, the field simply serializes to _0_. - -### Body {#body} - -The body portion of the block is structurally defined as: - -- `proposer`: The PublicKey which proposed this block. -- `deploy_hashes`: Is a vector of hex-encoded hashes identifying Deploys included in this block. -- `transfer_hashes`: Is a vector of hex-encoded hashes identifying Transfers included in this block. - -When we serialize the `BlockBody`, we create a buffer that contains the serialized representations of the individual fields present within the block. - -- `proposer`: serializes to the byte representation of the `PublicKey`. If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. -- `deploy_hashes`: serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of deploy hashes present within the body. -- `transfer_hashes`: serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of transfers present within the body. - -## BlockIdentifier {#blockidentifier} - -Identifier for possible ways to retrieve a Block. It can consist of any of the following in most situations: - -- [`hash`](#block-hash) Identify and retrieve a Block with its hash. The `BlockHash` serializes as the byte representation of the hash itself. - -- `height` Identify and retrieve the Block with its height. Height serializes as a single `u64` value. - -- `state_root_hash` Identify and retrieve the Block with its state root hash. It serializes to the byte representation of the `state root hash`. The serialized buffer of the `state_root_hash` is 32 bytes long. - -## ChainspecRegistry {#chainspecregistry} - -ChainspecRegistry is a unique key variant which contains a mapping of file names to the hash of the file itself. This map includes *Chainspec.toml* and may include *Accounts.toml* and *GlobalState.toml*. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of names as strings and [digests](#digest) held within. The remainder consists of a repeating pattern of serialized strings and then digests of the length dictated by the first four bytes. Digests and their inclusion criteria are as follows: - -- `chainspec_raw_hash` will always be included. - -- `genesis_accounts_raw_hash` may be included in specific circumstances. - -- `global_state_raw_hash` may be included in specific circumstances. - -## Contract {#contract} - - A contract struct containing the following fields: - - - [`contract_package_hash`](#contractpackagehash) - - - [`contract_wasm_hash`](#contractwasmhash) - - - [`named_keys`](#namedkey) - - - [`entry_points`](#entrypoint) - - - [`protocol_version`](#protocolversion) - -## ContractHash {#contracthash} - -A `blake2b` hash of a contract. The contract hash serializes as a 32-byte buffer containing the bytes of the contract hash. - -## ContractPackageHash {#contractpackagehash} - -A `blake2b` hash of a contract package. The contract package hash serializes as a 32-byte buffer containing the bytes of the contract package hash. - -## ContractVersion {#contractversion} - -The version of the contract. - -- [`contract_hash`](#contracthash) The contract hash of the contract. - -- `contract_version` The version of the contract within the protocol major version. It serializes as a [`u32` value](#clvalue-numeric). - -- `protocol_version_major` The major element of the protocol version this contract is compatible with. It serializes as a [`u32` value](#clvalue-numeric). - -## ContractWasmHash {#contractwasmhash} - -A `blake2b` hash of a contract's Wasm. The contract's Wasm hash serializes as a 32-byte buffer containing the bytes of the contract's Wasm hash. - -## Delegator {#delegator} - -Represents a party delegating their stake to a validator (or "delegatee"). The structure consists of the following fields: - -- `delegator_public_key` The public key of the delegator, serialized as a [`PublicKey`](#clvalue-publickey). - -- `staked_amount` The amount staked by the delegator, serialized as a [`U512` value](#clvalue-numeric). - -- `bonding_purse` The bonding purse associated with the delegation. It serializes as a [`URef` value](#clvalue-uref). - -- `validator_public_key` The public key of the validator that the delegator will be delegating to, serialized as a [`PublicKey`](#clvalue-publickey). - -- `vesting_schedule` The vesting schedule for the provided delegator bid. `None` if it is a non-genesis validator. It serializes as an [`Option`](#clvalue-option). - -## Deploy {#serialization-standard-deploy} - -A deploy is a data structure containing a smart contract and the requester's signature(s). Additionally, the deploy header contains additional metadata about the deploy itself. A deploy is structurally defined as follows: - -- `hash`: The hash of the deploy header. -- `header`: Contains metadata about the deploy. The structure of the header is detailed further in this document. -- `payment`: The payment code for contained smart contract. -- `session`: The stored contract itself. -- `approvals`: A list of signatures: - -### Deploy-Hash {#deploy-hash} - -The deploy hash is a digest over the contents of the deploy header. The deploy hash serializes as the byte representation of the hash itself. - -### Deploy-Header {#deploy-header} - -- `account`: A supported public key variant (currently either `Ed25519` or `Secp256k1`). An `Ed25519` key is serialized as a buffer of bytes, with the leading byte being `1` for `Ed25519`, with remainder of the buffer containing the byte representation of the signature. Correspondingly, a `Secp256k1` key is serialized as a buffer of bytes, with the leading byte being `2`. -- `timestamp`: A timestamp is a struct that is a unary tuple containing a `u64` value. This value is a count of the milliseconds since the UNIX epoch. Thus the value `1603994401469` serializes as `0xbd3a847575010000` -- `ttl`: The **Time to live** is defined as the amount of time for which deploy is considered valid. The `ttl` serializes in the same manner as the timestamp. -- `gas_price`: The gas is `u64` value which is serialized as `u64` CLValue discussed below. -- `body_hash`: Body hash is a hash over the contents of the deploy body, which includes the payment, session, and approval fields. Its serialization is the byte representation of the hash itself. -- `dependencies`: Dependencies is a vector of deploy hashes referencing deploys that must execute before the current deploy can be executed. It serializes as a buffer containing the individual serialization of each DeployHash within the Vector. -- `chain_name`: Chain name is a human-readable string describing the name of the chain as detailed in the chainspec. It is serialized as a String CLValue described below. - -### Payment & Session {#payment--session} - -Payment and Session are both defined as `ExecutableDeployItems`. More information on `ExecutableDeployItems` can be found [here](../developers/writing-onchain-code/calling-contracts.md) - -- Module Bytes are serialized such that the first byte within the serialized buffer is `0` with the rest of the buffer containing the bytes present. - - - `ModuleBytes { module_bytes: "[72 bytes]", args: 434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5 }` will serialize to - - `0x0048000000420481b0d5a665c8a7678398103d4333c684461a71e9ee2a13f6e859fb6cd419ed5f8876fc6c3e12dce4385acc777edf42dcf8d8d844bf6a704e5b2446750559911a4a328d649ddd48000000434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5` - -- StoredContractByHash serializes such that the first byte within the serialized buffer is 1u8. This is followed by the byte representation of the remaining fields. - - - `StoredContractByHash { hash: c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa4, entry_point: "pclphXwfYmCmdITj8hnh", args: d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850 }` - - `0x01c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa41400000070636c7068587766596d436d6449546a38686e685d000000d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850` - -- StoredContractByName serializes such that the first byte within the serialized buffer is 2u8. This is followed by the individual byte representation of the remaining fields. - - - `StoredContractByName { name: "U5A74bSZH8abT8HqVaK9", entry_point: "gIetSxltnRDvMhWdxTqQ", args: 07beadc3da884faa17454a }` - - `0x0214000000553541373462535a483861625438487156614b39140000006749657453786c746e5244764d685764785471510b00000007beadc3da884faa17454a` - -- StoredVersionedContractByHash serializes such that the first byte within the serialized buffer is 3u8. However, the field version within the enum serializes as an [Option](#option-clvalue-option) CLValue. - - - `StoredVersionedContractByHash { hash: b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423, version: None, entry_point: "PsLz5c7JsqT8BK8ll0kF", args: 3d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8 }` - - `0x03b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423001400000050734c7a3563374a73715438424b386c6c306b463b0000003d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8` - -- StoredVersionedContractByName serializes such that the first byte within the serialized buffer is 4u8. The name and entry_point are serialized as a [String](#string-clvalue-string) CLValue, with the version field serializing as an [Option](#option-clvalue-option). - - - `StoredVersionedContractByName { name: "lWJWKdZUEudSakJzw1tn", version: Some(1632552656), entry_point: "S1cXRT3E1jyFlWBAIVQ8", args: 9975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8 }` - - `0x04140000006c574a574b645a5545756453616b4a7a7731746e01d0c64e61140000005331635852543345316a79466c57424149565138270000009975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8` - -- Transfer serializes such that the first byte within the serialized buffer contains is 5u8, with the remaining bytes of the buffer containing the bytes contained within the args field of Transfer. - -### Approval {#approval} - -Approval contains two fields: - -- `signer`: The public key of the approvals signer. It serializes to the byte representation of the `PublicKey`. If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. -- `signature`: The approval signature, which serializes as the byte representation of the `Signature`. The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. - -## DeployInfo {#deployinfo} - -Information relating to a given deploy. The structure consists of the following fields: - -- `deploy_hash` The hash of the relevant deploy, serialized as a byte representation of the hash itself. - -- `transfers` Transfers performed by the deploy, serialized as a [`List`](#clvalue-list). - -- `from` The account identifier of the creator of the deploy, serialized as an [`account_hash`](#account-hash). - -- `source` The source purse used for payment of the deploy, serialized as a [`URef`](#clvalue-uref). - -- `gas` The gas cost of executing the deploy, serialized as a [`U512`](#clvalue-numeric). - -## Digest {#digest} - -A `blake2b` hash digest. The digest serializes as a byte representation of the hash itself. - -## DisabledVersions {#disabledversions} - -Disabled contract versions, containing the following: - -- `contract_version` The version of the contract within the protocol major version. It serializes as a [`u32` value](#clvalue-numeric). - -- `protocol_version_major` The major element of the protocol version this contract is compatible with. It serializes as a [`u32` value](#clvalue-numeric). - -## EntryPoint {#entrypoint} - -A type of signature method. Order of arguments matters, since this can be referenced by index as well as name. - -- `name` The name of the entry point, serialized as a [`String`](#clvalue-string). - -- `args` Arguments for this method. They serialize as a list of the [`Parameter`](#parameter)s, where each parameter represents an argument passed to the entrypoint. - -- `ret` The return type of the method, serialized as a [`Unit`](#clvalue-unit). - -- `access` An enum describing the possible access control options for a contract entry point. It serializes as a 1 for public or a 1 followed by a [`List`](#clvalue-list) of authorized users. - -- `entry_point_type` Identifies the type of entry point. It serializes as a `0` for Session and a `1` for Contract. - -## EraID {#eraid} - -An Era ID newtype. It serializes as a single [`u64` value](#clvalue-numeric). - -## EraInfo {#erainfo} - -Auction metadata, intended to be recorded each era. It serializes as a [`List`](#clvalue-list) of [seigniorage allocations](#seigniorageallocation). - - -## ExecutionEffect {#executioneffect} - -The journal of execution transforms from a single deploy. - -- `operations` The resulting operations, serialized as a [`List`](#clvalue-list) of [operations](#operation). - -- `transforms` The actual [transformation](#transform) performed while executing a deploy. - -## ExecutionResult {#executionresult} - -The result of a single deploy. It serializes as a `u8` tag indicating either `Failure` as a 0 or `Success` as a 1. This is followed by the appropriate structure below: - -### `Failure` - -The result of a failed execution. - -- `effect` The [effect](#executioneffect) of executing the deploy. - -- `transfers` A record of transfers performed while executing the deploy, serialized as a [`List`](#clvalue-list). - -- `cost` The cost of executing the deploy, serializes as a [`U512`](#clvalue-numeric) value. - -- `error_message` The error message associated with executing the deploy, serialized as a [`String`](#clvalue-string). - -### `Success` - -The result of a successful execution. - -- `effect` The [effect](#executioneffect) of executing the deploy. - -- `transfers` A record of transfers performed while executing the deploy, serialized as a [`List`](#clvalue-list). - -- `cost` The cost of executing the deploy, serializes as a [`U512`](#clvalue-numeric) value. - -## Group {#group} - -A (labeled) "user group". Each method of a versioned contract may be associated with one or more user groups which are allowed to call it. User groups are serialized as a [String](#clvalue-string). - -## Groups {#groups} - -They are serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of user groups and `BTreeSets` of [`URef`](#clvalue-uref)s held within. The remainder consists of a repeating pattern of serialized user groups and `BTreeSets` of the length dictated by the first four bytes. - -## Keys {#serialization-standard-state-keys} - -In this chapter, we describe what constitutes a "key", the permissions model for the keys, and how they are serialized. - -A _key_ in [Global State](./design/casper-design.md#global-state-head) is one of the following data types: - -- 32-byte account identifier (called an "account identity key") -- 32-byte immutable contract identifier (called a "hash key") -- 32-byte reference identifier (called an "unforgeable reference") -- 32-byte transfer identifier -- 32-byte deploy information identifier -- 32-byte purse balance identifier -- 32-byte Auction bid identifier -- 32-byte Auction withdrawal identifier -- 32-byte Dictionary identifier -- 32-byte System Contract Registry -- 32-byte Auction unbond identifier -- 32-byte Chainspec Registry - -The one exception to note here is the identifier for [`EraInfo`](#erainfo), which actually serializes as a [`u64`](#clvalue-numeric) value with an additional byte for the tag. - -### Account identity key {#global-state-account-key} - -This key type is used specifically for accounts in the global state. All accounts in the system must be stored under an account identity key, and no other types. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](./design/casper-design.md#accounts-associated-keys-weights) for more information). - -### Hash key {#serialization-standard-hash-key} - -This key type is used for storing contracts immutably. Once a contract is written under a hash key, that contract can never change. The 32-byte identifier representing this key is derived from the `blake2b256` hash of the deploy hash (see [block-structure-head](./design/casper-design.md#block-structure-head) for more information) concatenated with a 4-byte sequential ID. The ID begins at zero for each deploy and increments by one each time a contract is stored. The purpose of this ID is to allow each contract stored in the same deploy to have a unique key. - -### Unforgeable Reference (`URef`) {#serialization-standard-uref} - -`URef` broadly speaking can be used to store values and manage permissions to interact with the value stored under the `URef`. `URef` is a tuple which contains the address under which the values are stored and the Access rights to the `URef`. Refer to the [Unforgeable Reference](./design/casper-design.md#uref-head) section for details on how `URefs` are managed. - -### Transfer Key {#serialization-standard-transfer-key} - -This key type is used specifically for transfers in the global state. All transfers in the system must be stored under a transfer key and no other type. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the transfer address associated with the given transfer - -### DeployInfo Key {#serialization-standard-deploy-info-key} - -This key type is used specifically for storing information related to deploys in the global state. Information for a given deploy is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the deploy itself. - -### EraInfo Key {#serialization-standard-era-info-key} - -This key type is used specifically for storing information related to the `Auction` metadata for a particular era. The underlying data type stored under this is a vector of the allocation of seigniorage for that given era. The identifier for this key is a new type that wraps around the primitive `u64` data type and co-relates to the era number when the auction information was stored. - -This key type is used specifically for storing information related to auction bids in the global state. Information for the bids is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](./design/casper-design.md#accounts-associated-keys-weights) for more information). - -This key type is used specifically for storing information related to auction withdraws in the global state. Information for the withdrawals is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](./design/casper-design.md#accounts-associated-keys-weights) for more information). - -### Serialization for `Key` {#serialization-standard-serialization-key} - -Given the different variants for the over-arching `Key` data-type, each of the different variants is serialized differently. This section of this chapter details how the individual variants are serialized. The leading byte of the serialized buffer acts as a tag indicating the serialized variant. - -| `Key` | Serialization Tag | -| ------------ | ----------------- | -| `Account` | 0 | -| `Hash` | 1 | -| `URef` | 2 | -| `Transfer` | 3 | -| `DeployInfo` | 4 | -| `EraInfo` | 5 | -| `Balance` | 6 | -| `Bid` | 7 | -| `Withdraw` | 8 | -| `Dictionary` | 9 | -| `SystemContractRegistry`| 10 | -| `EraSummary` | 11 | -| `Unbond` | 12 | -| `ChainspecRegistry` | 13 | -| `ChecksumRegistry` | 14 | -| `BidAddr` | 15 | - -| `Package` | 16 | -| `AddressableEntity` | 17 | -| `ByteCode` | 18 | -| `Message` | 19 | - -- `Account` serializes as a 32 byte long buffer containing the byte representation of the underlying `AccountHash` -- `Hash` serializes as a 32 byte long buffer containing the byte representation of the underlying `Hash` itself. -- `URef` is a tuple that contains the address of the URef and the access rights to that `URef`. The serialized representation of the `URef` is 33 bytes long. The first 32 bytes are the byte representation of the `URef` address, and the last byte contains the bits corresponding to the access rights of the `URef`. Refer to the [CLValue](#serialization-standard-values) section of this chapter for details on how `AccessRights` are serialized. -- `Transfer` serializes as a 32 byte long buffer containing the byte representation of the hash of the transfer. -- `DeployInfo` serializes as 32 byte long buffer containing the byte representation of the Deploy hash. See the Deploy section above for how Deploy hashes are serialized. -- `EraInfo` serializes a `u64` primitive type containing the little-endian byte representation of `u64`. -- `Balance` serializes as 32 byte long buffer containing the byte representation of the URef address. -- `Bid` and `Withdraw` both contain the `AccountHash` as their identifier; therefore, they serialize in the same manner as the `Account` variant. -- `Dictionary` serializes as the 32 byte long buffer containing the byte representation of the seed URef hashed with the identifying name of the dictionary item. -- `SystemContractRegistry` serializes as a 32 byte long buffer of zeros. -- `EraSummary` serializes as a 32 byte long buffer of zeros. -- `Unbond` contains the `AccountHash` as its identifier; therefore, it serialize in the same manner as the `Account` variant. -- `ChainspecRegistry` serializes as a 32 byte long buffer of ones. -- `ChecksumRegistry` serializes as a 32 byte long buffer of zeros. -- `BidAddr` may be one of three types: - - `Unified` serializes as the tag `0` followed by a 32 byte long buffer containing the byte representation of a legacy bid. - - `Validator` serializes as the tag `1` followed by a 32 byte long buffer containing the byte representation of a validator's hash. - - `Delegator` serializes as the tag `2` followed by a 32 byte long buffer containing the byte representation of the associated validator's hash, appended with a 32 byte long buffer containing the byte representation of the given delegator's hash. - -## Permissions {#serialization-standard-permissions} - -There are three types of actions that can be done on a value: read, write, add. The reason for _add_ to be called out separately from _write_ is to allow for commutativity checking. The available actions depend on the key type and the context. Some key types only allow controlled access by smart contracts via the contract API, and other key types refer to values produced and used by the system itself and are not accessible to smart contracts at all but can be read via off-chain queries. This is summarized in the table below: - -| Key | Type Available Actions | -| -------- | ----------------------- | -| Account | Read + Add (via API) | -| Hash | Read | -| URef | Read + Write and/or Add | -| Transfer | System | -| Deploy | System | -| EraInfo | System | -| Balance | Read (via API) | -| Bid | System | -| Withdraw | System | -| Dictionary | Read (via API) | -| SystemContractRegistry | Read (via API)| -| Unbond | System | -| ChainspecRegistry | Read (via API) | - ---- - -Refer to [URef permissions](./design/casper-design.md#uref-permissions) on how permissions are handled in the case of `URef`s. - -## NamedArg {#namedarg} - -Named arguments to a contract. It is serialized by the combination of a [`String`](#clvalue-string) followed by the associated [`CLValue`](#clvalue-clvalue). - -## NamedKey {#namedkey} - -A mapping of string identifiers to a Casper `Key` type. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of named keys and values held within. The remainder consists of a repeating pattern of serialized named keys and then values of the length dictated by the first four bytes. - -- `name` The name of the entry. It serializes as a [`string`](#clvalue-string). - -- `key` The value of the entry, which is a Casper `Key` type. - -The named keys portion of the account structure serializes as a mapping of a string to Casper `Key` values as described [here](#serialization-standard-serialization-key). - -## Operation {#operation} - -An operation performed while executing a deploy. It contains: - -- `key` The formatted string of the key, serialized as a [`String`](#clvalue-string). - -- `kind` OpKind, The type of operation performed. It serializes as a single byte based on the following table: - -|OpKind|Serialization| -|------|-------------| -|Read | 0 | -|Write | 1 | -|Add | 2 | -|NoOp | 3 | - -## Parameter {#parameter} - -Parameter to a method, structured as a name followed by a `CLType`. It is serialized as a [`String`](#clvalue-string) followed by a [`CLType`](#clvalue-cltype). - -## ProtocolVersion {#protocolversion} - -A newtype indicating the Casper Platform protocol version. It is serialized as three [`u32`](#clvalue-numeric) values indicating major, minor and patch versions in that order. - -## PublicKey {#publickey} - -Hex-encoded cryptographic public key, including the algorithm tag prefix. Serialization can be found under [`PublicKey`](#clvalue-publickey). - -## RuntimeArgs {#runtimeargs} - -Represents a collection of arguments passed to a smart contract. They serialize as a [`List`](#clvalue-list) comprised of [`Tuples`](#clvalue-tuple). - -## SeigniorageAllocation {#seigniorageallocation} - -Information about seigniorage allocation. - -If the seigniorage allocation in question is for a validator, it serializes as the validator's [`PublicKey`](#clvalue-publickey) followed by the [`U512` amount](#clvalue-numeric). - -If it is a delegator, it serializes as the delegator's [`PublicKey`](#clvalue-publickey), followed by the validator's [`PublicKey`](#clvalue-publickey) and finally the [`U512` amount](#clvalue-numeric). - -## Signature {#signature} - -The signature serializes the byte representation of the underlying cryptographic primitive signature. The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. - -## SystemContractRegistry {#systemcontractregistry} - -SystemContractRegistry is a unique `Key` under which a mapping of the names and `ContractHashes` for system contracts. This includes `Mint`, `Auction`, `HandlePayment` and `StandardPayment`. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of names as strings and [ContractHashes](#contracthash) held within. The remainder consists of a repeating pattern of serialized strings and then ContractHashes of the length dictated by the first four bytes. - -## TimeDiff {#timediff} - -A human-readable duration between two timestamps. It serializes as a single [`u64`](#clvalue-numeric) value. - -## Timestamp {#timestamp} - -A timestamp formatted as per RFC 3339 and serialized as a single [`u64`](#clvalue-numeric) value. - -## TransferAddr {#transferaddr} - -Hex-encoded transfer address, which serializes as a byte representation of itself. - -## Transform {#transform} - -The actual transformation performed while executing a deploy. It serializes as a single `u8` value indicating the type of transform performed as per the following table. The remaining bytes represent the information and serialization as listed. - -| Transform Type | Serialization | Description | -| -------------- | ------------- | ----------- | -| Identity | 0 | A transform having no effect, created as a result of reading from the global state. | -| Write | 1 | Writes a new value in the global state. | -| AddInt32 | 2 | Adds the given [`i32`](#clvalue-numeric). | -| AddUInt64 | 3 | Adds the given [`u64`](#clvalue-numeric). | -| AddUInt128 | 4 | Adds the given [`U128`](#clvalue-numeric). | -| AddUInt256 | 5 | Adds the given [`U256`](#clvalue-numeric). | -| AddUInt512 | 6 | Adds the given [`U512`](#clvalue-numeric). | -| AddKeys | 7 | Adds the given collection of [named keys](#namedkey). | -| Failure | 8 | A failed transformation, containing an error message. | -| Prune | 9 | Removes the pathing to the global state entry of the specified key. The pruned element remains reachable from previously generated global state root hashes, but will not be included in the next generated global state root hash and subsequent states. | - -## TransformEntry {#transformentry} - -A transformation performed while executing a deploy. - -## UnbondingPurse {#unbondingpurse} - -A purse used for unbonding. The structure consists of the following: - -- `bonding_purse` The bonding purse, serialized as a [`URef`](#clvalue-uref). - -- `validator_public_key` The public key of the validator, serialized as a [`PublicKey`](#clvalue-publickey). - -- `unbonder_public_key` The public key of the unbonder, serialized as a [`PublicKey`](#clvalue-publickey). - -- `era_of_creation` Era in which this unbonding request was created, as an [`EraId`](#eraid) newtype, which serializes as a [`u64`](#clvalue-numeric) value. - -- `amount` The unbonding amount, serialized as a [`U512`](#clvalue-numeric) value. - -- `new_validator` The validator public key to redelegate to, serialized as an [`Option`](#clvalue-option) containing the public key. - -## Values {#serialization-standard-values} - -A value stored in the global state is a `StoredValue`. A `StoredValue` is one of three possible variants: - -- A `CLValue` -- A contract -- An account - -We discuss `CLValue` and contract in more detail below. Details about accounts can be found in [accounts-head](./design/casper-design.md#accounts-head). - -Each `StoredValue` is serialized when written to the global state. The serialization format consists of a single byte tag, indicating which variant of `StoredValue` it is, followed by the serialization of that variant. The tag for each variant is as follows: - -- `CLValue` is `0` -- `Account` is `1` -- `Contract` is `2` - -The details of `CLType` serialization are in the following section. Using the serialization format for `CLValue` as a basis, we can succinctly write the serialization rules for contracts and accounts: - -- contracts serialize in the same way as data with `CLType` equal to `Tuple3(List(U8), Map(String, Key), Tuple3(U32, U32, U32))`; -- accounts serialize in the same way as data with `CLType` equal to `Tuple5(ByteArray(U8, 32), Map(String, Key), URef, Map(ByteArray(U8, 32), U8), Tuple2(U8, U8))`. - -Note: `Tuple5` is not a presently supported `CLType`. However, it is clear how to generalize the rules for `Tuple1`, `Tuple2`, `Tuple3` to any size tuple. - -### `CLValue` {#clvalue} - -`CLValue` is used to describe data that is used by smart contracts. This could be as a local state variable, input argument, or return value. A `CLValue` consists of two parts: a `CLType` describing the type of the value and an array of bytes representing the data in our serialization format. - -`CLType` is described by the following recursive data type: - -```rust -enum CLType { - Bool, // boolean primitive - I32, // signed 32-bit integer primitive - I64, // signed 64-bit integer primitive - U8, // unsigned 8-bit integer primitive - U32, // unsigned 32-bit integer primitive - U64, // unsigned 64-bit integer primitive - U128, // unsigned 128-bit integer primitive - U256, // unsigned 256-bit integer primitive - U512, // unsigned 512-bit integer primitive - Unit, // singleton value without additional semantics - String, // e.g. "Hello, World!" - URef, // unforgeable reference (see above) - Key, // global state key (see above) - PublicKey // A Casper system PublicKey type - Option(CLType), // optional value of the given type - List(CLType), // list of values of the given type (e.g. Vec in rust) - ByteArray(CLType, u32), // same as `List` above, but number of elements - // is statically known (e.g. arrays in rust) - Result(CLType, CLType), // co-product of the given types; - // one variant meaning success, the other failure - Map(CLType, CLType), // key-value association where keys and values have the given types - Tuple1(CLType), // single value of the given type - Tuple2(CLType, CLType), // pair consisting of elements of the given types - Tuple3(CLType, CLType, CLType), // triple consisting of elements of the given types - Any // Indicates the type is not known -} -``` - -All data which can be assigned a (non-`Any`) `CLType` can be serialized according to the following rules (this defines the Casper serialization format): - -#### Boolean {#clvalue-boolean} - -Boolean values serialize as a single byte; `true` maps to `1`, while `false` maps to `0`. - -#### Numeric {#clvalue-numeric} - -Numeric values consisting of 64 bits or less serialize in the two's complement representation with little-endian byte order, and the appropriate number of bytes for the bit-width. - -- E.g. `7u8` serializes as `0x07` -- E.g. `7u32` serializes as `0x07000000` -- E.g. `1024u32` serializes as `0x00040000` - -- Wider numeric values (i.e. `U128`, `U256`, `U512`) serialize as one byte given the length of the next number (in bytes), followed by the two's complement representation with little-endian byte order. The number of bytes should be chosen as small as possible to represent the given number. This is done to reduce the serialization size when small numbers are represented within a wide data type. - -- E.g. `U512::from(7)` serializes as `0x0107` -- E.g. `U512::from(1024)` serializes as `0x020004` -- E.g. `U512::from("123456789101112131415")` serializes as `0x0957ff1ada959f4eb106` - -#### Unit {#clvalue-unit} - -Unit serializes to an empty byte array. - -#### String {#clvalue-string} - -Strings serialize as a 32-bit integer representing the length in bytes (note: this might be different than the number of characters since special characters, such as emojis, take more than one byte), followed by the UTF-8 encoding of the characters in the string. - -- E.g. `"Hello, World!"` serializes as `0x0d00000048656c6c6f2c20576f726c6421` - -#### Option {#clvalue-option} - -Optional values serialize with a single byte tag, followed by the serialization of the value itself. The tag is equal to `0` if the value is missing, and `1` if it is present. - -- E.g. `None` serializes as `0x00` -- E.g. `Some(10u32)` serializes as `0x010a000000` - -#### List {#clvalue-list} - -A list of values serializes as a 32-bit integer representing the number of elements in the list (note this differs from strings where it gives the number of _bytes_), followed by the concatenation of each serialized element. - -- E.g. `List()` serializes as `0x00000000` -- E.g. `List(1u32, 2u32, 3u32)` serializes as `0x03000000010000000200000003000000` - -#### ByteArray {#clvalue-ByteArray} - -A fixed-length list of values serializes as the concatenation of the serialized elements. Unlike a variable-length list, the length is not included in the serialization because it is statically known by the type of the value. - -- E.g. `[1u32, 2u32, 3u32]` serializes as `0x010000000200000003000000` - -#### Result {#clvalue-result} - -A `Result` serializes as a single byte tag followed by the serialization of the contained value. The tag is equal to `1` for the success variant and `0` for the error variant. - - - E.g. `Ok(314u64)` serializes as `0x013a01000000000000` - - E.g. `Err("Uh oh")` serializes as `0x00050000005568206f68` - -#### Tuple {#clvalue-tuple} - -Tuples serialize as the concatenation of their serialized elements. Similar to `ByteArray` the number of elements is not included in the serialization because it is statically known in the type. - - - E.g. `(1u32, "Hello, World!", true)` serializes as `0x010000000d00000048656c6c6f2c20576f726c642101` - -#### Map {#clvalue-map} - -A `Map` serializes as a list of key-value tuples. There must be a well-defined ordering on the keys, and in the serialization, the pairs are listed in ascending order. This is done to ensure determinism in the serialization, as `Map` data structures can be unordered. - -#### URef {#clvalue-uref} - -`URef` values serialize as the concatenation of its address (which is a fixed-length list of `u8`) and a single byte tag representing the access rights. Access rights are converted as follows: - -| Access Rights | Serialization | -| ---------------- | ------------- | -| `NONE` | 0 | -| `READ` | 1 | -| `WRITE` | 2 | -| `READ_WRITE` | 3 | -| `ADD` | 4 | -| `READ_ADD` | 5 | -| `ADD_WRITE` | 6 | -| `READ_ADD_WRITE` | 7 | - - - E.g. `uref-974019c976b5f26412ce486158d2431967af35d91387dae8cbcd43c20fce6452-007` shows a `URef` with full `READ_ADD_WRITE` rights. - -:::warning - -When passing a URef to another entity on chain, you must ensure that the `AccessRights` are set correctly. If the URef represents a [purse](./glossary/P.md#purse-purse), `AccessRights` impact who can deposit and withdraw CSPR. - -::: - -If a passed URef contains `ADD` permissions, the entity receiving the URef will then be able to deposit CSPR into the associated purse. `WRITE` permissions allow for withdrawing CSPR. As of 1.4.5, passing a main purse URef as a runtime argument will cause the host to automatically remove `WRITE` permissions. In this event, `READ` and `ADD` permissions will remain. Regardless, all due diligence should be performed to avoid passing a URef with `WRITE` permissions unintentionally. - -#### PublicKey {#clvalue-publickey} - -`PublicKey` serializes as a single byte tag representing the algorithm followed by 32 bytes of the `PublicKey` itself: - -- If the `PublicKey` is a `System` key, the single tag byte is `0`. With this variant, the single byte of `0` is the entire key. -- If the `PublicKey` is an `Ed25519` key, the single tag byte is `1` followed by the individual bytes of the serialized key. -- If the `PublicKey` is a `Secp256k1` key, the single tag byte is a `2` followed by the individual bytes of the serialized key. - -#### Key {#clvalue-key} - -`Key` values serialize as a single byte tag representing the variant, followed by the serialization of the data that variant contains. For most variants, this is simply a fixed-length 32-byte array. The exception is `Key::URef`, which contains a `URef`; so its data serializes per the description above. The tags are as follows: `Key::Account` serializes as `0`, `Key::Hash` as `1`, `Key::URef` as `2`. - -#### CLType {#clvalue-cltype} - -`CLType` itself also has rules for serialization. A `CLType` serializes as a single-byte tag, followed by the concatenation of serialized inner types, if any (e.g., lists and tuples have inner types). `ByteArray` is a minor exception because it also includes the length in the type. However, the length is included in the serialization (as a 32-bit integer, per the serialization rules above), following the serialization of the inner type. The tags are as follows: - -| `CLType` | Serialization Tag | -| ----------- | ----------------- | -| `Bool` | 0 | -| `I32` | 1 | -| `I64` | 2 | -| `U8` | 3 | -| `U32` | 4 | -| `U64` | 5 | -| `U128` | 6 | -| `U256` | 7 | -| `U512` | 8 | -| `Unit` | 9 | -| `String` | 10 | -| `Key` | 11 | -| `URef` | 12 | -| `Option` | 13 | -| `List` | 14 | -| `ByteArray` | 15 | -| `Result` | 16 | -| `Map` | 17 | -| `Tuple1` | 18 | -| `Tuple2` | 19 | -| `Tuple3` | 20 | -| `Any` | 21 | -| `PublicKey` | 22 | - -#### CLValue {#clvalue-clvalue} - -A complete `CLValue`, including both the data and the type, can also be serialized (to store it in the global state). This is done by concatenating: the serialization of the length (as a 32-bit integer) of the serialized data (in bytes), the serialized data itself, and the serialization of the type. - -### Contracts {#global-state-contracts} - -Contracts are a special value type because they contain the on-chain logic of the applications running on a Casper network. A _contract_ contains the following data: - -- a [wasm module](https://webassembly.github.io/spec/core/syntax/modules.html) -- a collection of named keys -- a protocol version - -The wasm module must contain a function named `call`, which takes no arguments and returns no values. This is the main entry point into the contract. Moreover, the module may import any of the functions supported by the [Casper runtime](./design/casper-design.md#execution-semantics-runtime). - -Note: though the `call` function signature has no arguments and no return value, within the `call` function body, the `get_named_arg` runtime function can be used to accept arguments (by ordinal), and the `ret` runtime function can be used to return a single `CLValue` to the caller. - -The named keys are used to give human-readable names to keys in the global state, which are essential to the contract. For example, the hash key of another contract it frequently calls may be stored under a meaningful name. It is also used to store the `URef`s, which are known to the contract (see the section on Permissions for details). - -Each contract specifies the Casper protocol version that was active when the contract was written to the global state. - -## WithdrawPurse {#withdrawpurse} - -A purse used for unbonding, replaced in 1.5 by [UnbondingPurse](#unbondingpurse). WithdrawPurses prior to 1.5 were known as UnbondingPurses and now consist of historical data. - -- `bonding_purse` The bonding purse, serialized as a [`URef`](#clvalue-uref). - -- `validator_public_key` The public key of the validator, serialized as a [`PublicKey`](#clvalue-publickey). - -- `unbonder_public_key` The public key of the unbonder, serialized as a [`PublicKey`](#clvalue-publickey). - -- `era_of_creation` Era in which this unbonding request was created, as an [`EraId`](#eraid) newtype, which serializes as a [`u64`](#clvalue-numeric) value. - -- `amount` The unbonding amount, serialized as a [`U512`](#clvalue-numeric) value. - diff --git a/source/docs/casper/concepts/serialization/index.md b/source/docs/casper/concepts/serialization/index.md new file mode 100644 index 0000000000..409c243f91 --- /dev/null +++ b/source/docs/casper/concepts/serialization/index.md @@ -0,0 +1,11 @@ +# Binary Serialization Standard {#serialization-standard-head} + +We provide a custom implementation to serialize data structures used by the Casper node to their byte representation. This category details custom serialization implementation, allowing developers to build a library that is compatible with the custom serialization. + +The `Casper Binary Serialization Standard` uses a default `u8` byte tag to identify the subsequent data's type and direct further deserialization. Additional serialization rules can be found in the following sub-categories. + +| Page | Description | +| ---- | ----------- | +| [Primitives](./primitives.md) | Base-level types used to create more complex structures. | +| [Structures](./structures.md) | Major structures used through Casper systems, as well as their included sub-types. | +| [Types](./types.md) | Minor types not covered `Primitives` or `Structures` | \ No newline at end of file diff --git a/source/docs/casper/concepts/serialization/primitives.md b/source/docs/casper/concepts/serialization/primitives.md new file mode 100644 index 0000000000..b529c3b1b7 --- /dev/null +++ b/source/docs/casper/concepts/serialization/primitives.md @@ -0,0 +1,190 @@ +# Primitives and Basic Serialization Rules + +## `CLValue` {#clvalue} + +`CLValue` is used to describe data that is used by smart contracts. This could be as a local state variable, input argument, or return value. A `CLValue` consists of two parts: a `CLType` describing the type of the value and an array of bytes representing the data in our serialization format. + +`CLType` is described by the following recursive data type: + +```rust +enum CLType { + Bool, // boolean primitive + I32, // signed 32-bit integer primitive + I64, // signed 64-bit integer primitive + U8, // unsigned 8-bit integer primitive + U32, // unsigned 32-bit integer primitive + U64, // unsigned 64-bit integer primitive + U128, // unsigned 128-bit integer primitive + U256, // unsigned 256-bit integer primitive + U512, // unsigned 512-bit integer primitive + Unit, // singleton value without additional semantics + String, // e.g. "Hello, World!" + URef, // unforgeable reference (see above) + Key, // global state key (see above) + PublicKey // A Casper system PublicKey type + Option(CLType), // optional value of the given type + List(CLType), // list of values of the given type (e.g. Vec in rust) + ByteArray(CLType, u32), // same as `List` above, but number of elements + // is statically known (e.g. arrays in rust) + Result(CLType, CLType), // co-product of the given types; + // one variant meaning success, the other failure + Map(CLType, CLType), // key-value association where keys and values have the given types + Tuple1(CLType), // single value of the given type + Tuple2(CLType, CLType), // pair consisting of elements of the given types + Tuple3(CLType, CLType, CLType), // triple consisting of elements of the given types + Any // Indicates the type is not known +} +``` + +All data which can be assigned a (non-`Any`) `CLType` can be serialized according to the following rules (this defines the Casper serialization format): + +### Boolean {#clvalue-boolean} + +Boolean values serialize as a single byte; `true` maps to `1`, while `false` maps to `0`. + +### Numeric {#clvalue-numeric} + +Numeric values consisting of 64 bits or less serialize in the two's complement representation with little-endian byte order, and the appropriate number of bytes for the bit-width. + +- E.g. `7u8` serializes as `0x07` +- E.g. `7u32` serializes as `0x07000000` +- E.g. `1024u32` serializes as `0x00040000` + +- Wider numeric values (i.e. `U128`, `U256`, `U512`) serialize as one byte given the length of the next number (in bytes), followed by the two's complement representation with little-endian byte order. The number of bytes should be chosen as small as possible to represent the given number. This is done to reduce the serialization size when small numbers are represented within a wide data type. + +- E.g. `U512::from(7)` serializes as `0x0107` +- E.g. `U512::from(1024)` serializes as `0x020004` +- E.g. `U512::from("123456789101112131415")` serializes as `0x0957ff1ada959f4eb106` + +### Unit {#clvalue-unit} + +Unit serializes to an empty byte array. + +### String {#clvalue-string} + +Strings serialize as a 32-bit integer representing the length in bytes (note: this might be different than the number of characters since special characters, such as emojis, take more than one byte), followed by the UTF-8 encoding of the characters in the string. + +- E.g. `"Hello, World!"` serializes as `0x0d00000048656c6c6f2c20576f726c6421` + +### Option {#clvalue-option} + +Optional values serialize with a single byte tag, followed by the serialization of the value itself. The tag is equal to `0` if the value is missing, and `1` if it is present. + +- E.g. `None` serializes as `0x00` +- E.g. `Some(10u32)` serializes as `0x010a000000` + +### List {#clvalue-list} + +A list of values serializes as a 32-bit integer representing the number of elements in the list (note this differs from strings where it gives the number of _bytes_), followed by the concatenation of each serialized element. + +- E.g. `List()` serializes as `0x00000000` +- E.g. `List(1u32, 2u32, 3u32)` serializes as `0x03000000010000000200000003000000` + +### ByteArray {#clvalue-ByteArray} + +A fixed-length list of values serializes as the concatenation of the serialized elements. Unlike a variable-length list, the length is not included in the serialization because it is statically known by the type of the value. + +- E.g. `[1u32, 2u32, 3u32]` serializes as `0x010000000200000003000000` + +### Result {#clvalue-result} + +A `Result` serializes as a single byte tag followed by the serialization of the contained value. The tag is equal to `1` for the success variant and `0` for the error variant. + + - E.g. `Ok(314u64)` serializes as `0x013a01000000000000` + - E.g. `Err("Uh oh")` serializes as `0x00050000005568206f68` + +### Tuple {#clvalue-tuple} + +Tuples serialize as the concatenation of their serialized elements. Similar to `ByteArray` the number of elements is not included in the serialization because it is statically known in the type. + + - E.g. `(1u32, "Hello, World!", true)` serializes as `0x010000000d00000048656c6c6f2c20576f726c642101` + +### Map {#clvalue-map} + +A `Map` serializes as a list of key-value tuples. There must be a well-defined ordering on the keys, and in the serialization, the pairs are listed in ascending order. This is done to ensure determinism in the serialization, as `Map` data structures can be unordered. + +### URef {#clvalue-uref} + +`URef` values serialize as the concatenation of its address (which is a fixed-length list of `u8`) and a single byte tag representing the access rights. Access rights are converted as follows: + +| Access Rights | Serialization | +| ---------------- | ------------- | +| `NONE` | 0 | +| `READ` | 1 | +| `WRITE` | 2 | +| `READ_WRITE` | 3 | +| `ADD` | 4 | +| `READ_ADD` | 5 | +| `ADD_WRITE` | 6 | +| `READ_ADD_WRITE` | 7 | + + +:::warning + +When passing a URef to another entity on chain, you must ensure that the `AccessRights` are set correctly. If the URef represents a [purse](../glossary/P.md#purse-purse), `AccessRights` impact who can deposit and withdraw CSPR. + +::: + +If a passed URef contains `ADD` permissions, the entity receiving the URef will then be able to deposit CSPR into the associated purse. `WRITE` permissions allow for withdrawing CSPR. As of 1.4.5, passing a main purse URef as a runtime argument will cause the host to automatically remove `WRITE` permissions. In this event, `READ` and `ADD` permissions will remain. Regardless, all due diligence should be performed to avoid passing a URef with `WRITE` permissions unintentionally. + +### PublicKey {#clvalue-publickey} + +`PublicKey` serializes as a single byte tag representing the algorithm followed by 32 bytes of the `PublicKey` itself: + +- If the `PublicKey` is a `System` key, the single tag byte is `0`. With this variant, the single byte of `0` is the entire key. +- If the `PublicKey` is an `Ed25519` key, the single tag byte is `1` followed by the individual bytes of the serialized key. +- If the `PublicKey` is a `Secp256k1` key, the single tag byte is a `2` followed by the individual bytes of the serialized key. + +### Key {#clvalue-key} + +`Key` values serialize as a single byte tag representing the variant, followed by the serialization of the data that variant contains. For most variants, this is simply a fixed-length 32-byte array. The exception is `Key::URef`, which contains a `URef`; so its data serializes per the description above. The tags are as follows: `Key::Account` serializes as `0`, `Key::Hash` as `1`, `Key::URef` as `2`. + +### CLType {#clvalue-cltype} + +`CLType` itself also has rules for serialization. A `CLType` serializes as a single-byte tag, followed by the concatenation of serialized inner types, if any (e.g., lists and tuples have inner types). `ByteArray` is a minor exception because it also includes the length in the type. However, the length is included in the serialization (as a 32-bit integer, per the serialization rules above), following the serialization of the inner type. The tags are as follows: + +| `CLType` | Serialization Tag | +| ----------- | ----------------- | +| `Bool` | 0 | +| `I32` | 1 | +| `I64` | 2 | +| `U8` | 3 | +| `U32` | 4 | +| `U64` | 5 | +| `U128` | 6 | +| `U256` | 7 | +| `U512` | 8 | +| `Unit` | 9 | +| `String` | 10 | +| `Key` | 11 | +| `URef` | 12 | +| `Option` | 13 | +| `List` | 14 | +| `ByteArray` | 15 | +| `Result` | 16 | +| `Map` | 17 | +| `Tuple1` | 18 | +| `Tuple2` | 19 | +| `Tuple3` | 20 | +| `Any` | 21 | +| `PublicKey` | 22 | + +### CLValue {#clvalue-clvalue} + +A complete `CLValue`, including both the data and the type, can also be serialized (to store it in the global state). This is done by concatenating: the serialization of the length (as a 32-bit integer) of the serialized data (in bytes), the serialized data itself, and the serialization of the type. + +### Contracts {#global-state-contracts} + +Contracts are a special value type because they contain the on-chain logic of the applications running on a Casper network. A _contract_ contains the following data: + +- a [wasm module](https://webassembly.github.io/spec/core/syntax/modules.html) +- a collection of named keys +- a protocol version + +The wasm module must contain a function named `call`, which takes no arguments and returns no values. This is the main entry point into the contract. Moreover, the module may import any of the functions supported by the [Casper runtime](../design/casper-design.md#execution-semantics-runtime). + +Note: though the `call` function signature has no arguments and no return value, within the `call` function body, the `get_named_arg` runtime function can be used to accept arguments (by ordinal), and the `ret` runtime function can be used to return a single `CLValue` to the caller. + +The named keys are used to give human-readable names to keys in the global state, which are essential to the contract. For example, the hash key of another contract it frequently calls may be stored under a meaningful name. It is also used to store the `URef`s, which are known to the contract (see the section on Permissions for details). + +Each contract specifies the Casper protocol version that was active when the contract was written to the global state. \ No newline at end of file diff --git a/source/docs/casper/concepts/serialization/structures.md b/source/docs/casper/concepts/serialization/structures.md new file mode 100644 index 0000000000..7d15ef3e6c --- /dev/null +++ b/source/docs/casper/concepts/serialization/structures.md @@ -0,0 +1,462 @@ +# Major Structures + +## Account {#serialization-standard-account} + +An Account is a structure that represented a user on a legacy Casper network. Alongside the Condor protocol release, `Accounts` were replaced with `AddressableEntities` of the type `Account`. The account structure consists of the following fields: + +- [`account_hash`](./types.md#account-hash) + +- [`named_keys`](./types.md#namedkey) + +- `main_purse`: The account's main purse `URef`. You may find information on `URef` serialization [here](./primitives.md#clvalue-uref). + +- [`associated_keys`](./types.md#associatedkey) + +- [`action_thresholds`](./types.md#action-thresholds) + +## AddressableEntity {#addressable-entity} + +An Addressable Entity is a structure that represents an entity on a Casper network. The addressable entity consists of the following fields: + +- [`package_hash`](./types.md#packagehash) + +- [`byte_code_hash`](./types.md#byte-code-hash) + +- [`entry_points`](./types.md#entrypoints) + +- [`protocol_version`](./types.md#protocolversion) + +- `main_purse`: The entity's main purse `URef`. You may find information on `URef` serialization [here](./primitives.md#clvalue-uref). + +- [`associated_keys`](./types.md#associatedkey) + +- [`action_thresholds`](./types.md#action-thresholds) + +- [`message_topics`](./types.md#message-topics) + +- [`entity_kind`](./types.md#entity-kind) + +## Block {#serialization-standard-block} + +A block is the core component of the Casper linear blockchain, used in two contexts: + +1. A data structure containing a collection of transactions. Blocks form the primary structure of the blockchain. +2. A message that is exchanged between nodes containing the data structure as explained in (1). + +Each block has a globally unique ID, achieved by hashing the contents of the block. + +Each block points to its parent. An exception is the first block, which has no parent. + +A block is structurally defined as follows: + +- `hash`: A hash over the header of the block. +- `header`: The header of the block that contains information about the contents of the block with additional metadata. +- `body`: The block's body contains the proposer of the block and hashes of deploys and transfers contained within it. + +Further, a block may consist of one of the following types: + +- `Version1`: A legacy block created prior to the Condor upgrade. + +- `Version2`: A modern block. + +### Block hash {#block-hash} + +The block hash is a `Digest` over the contents of the block Header. The `BlockHash` serializes as the byte representation of the hash itself. + +### Block Header {#block-header} + +The header portion of a block, structurally, is defined as follows: + +- `parent_hash` is the hash of the parent block. It serializes to the byte representation of the parent hash. The serialized buffer of the `parent_hash` is 32 bytes long. +- `state_root_hash` is the global state root hash produced by executing this block's body. It serializes to the byte representation of the `state root hash`. The serialized buffer of the `state_root_hash` is 32 bytes long. +- `body_hash` the hash of the block body. It serializes to the byte representation of the body hash. The serialized buffer of the `body_hash` is 32 bytes long. +- `random_bit` is a boolean needed for initializing a future era. It is serialized as a single byte; true maps to 1, while false maps to 0. +- `accumulated_seed` is a seed needed for initializing a future era. It serializes to the byte representation of the parent Hash. The serialized buffer of the `accumulated_hash` is 32 bytes long. +- `era_end` contains equivocation and reward information to be included in the terminal finalized block. It is an optional field. Thus if the field is set as `None`, it serializes to _0_. The serialization of the other case is described in the EraEnd. +- `timestamp` The timestamp from when the block was proposed. It serializes as a single `u64` value. The serialization of a `u64` value is described in the CLValues section. +- `era_id` Era ID in which this block was created. It serializes as a single `u64` value. +- `height` The height of this block, i.e., the number of ancestors. It serializes as a single `u64` value. +- `protocol_version` The version of the Casper network when this block was proposed. It is 3-element tuple containing `u32` values. It serializes as a buffer containing the three `u32` serialized values. Refer to the CLValues section on how `u32` values are serialized. + +Both `BlockHeaderV1` and `BlockHeaderV2` serialize in the same way. + +### EraEndV1 {#eraendV1} + +`EraEndV1` as represented within the block header, is a struct containing two fields. + +- `era_report`: The first field is termed as `EraReport` and contains information about equivocators and rewards for an era. +- `next_era_validator_weights`: The second field is map for the validators and their weights for the era to follow. + +`EraReport` itself contains two fields: + +- `equivocators`: A vector of `PublicKey`. +- `rewards`: A Binary Tree Map of `PublicKey` and `u64`. + +When serializing an EraReport, the buffer is first filled with the individual serialization of the PublicKey contained within the vector. + +- If the `PublicKey` is an `Ed25519` key, the first byte within the buffer is a `1` followed by the individual bytes of the serialized key. +- If the `PublicKey` is an `Secp256k1` key, the first byte within the buffer is a `2` followed by the individual bytes of the serialized key. + +When serializing the overarching struct of `EraEndV1`, we first allocate a buffer, which contains the serialized representation of the `EraReport` as described above, followed by the serialized BTreeMap. + +Note that `EraEndV1` is an optional field. Thus the above scheme only applies if there is an `EraEndV1`; if there is no era end, the field simply serializes to _0_. + +### EraEndV2 {#eraendV2} + +`EraEndV1` as represented within the block header, is a struct containing four fields. + +- `equivocators`: A vector of `PublicKey` listing equivocators for the era. +- `inactive_validators`: A list of inactive validators for the era. +- `next_era_validator_weights`: A map of validators and their weights for the era to follow. +- `rewards`: A Binary Tree Map of `PublicKey` and `u64`. + +Note that `EraEndV2` is an optional field. Thus the above scheme only applies if there is an `EraEndV2`; if there is no era end, the field simply serializes to _0_. + +### BlockBodyV1 {#blockbodyv1} + +The body portion of a block, prior to the Condor upgrade, is structurally defined as: + +- `proposer`: The PublicKey which proposed this block. +- `deploy_hashes`: Is a vector of hex-encoded hashes identifying Deploys included in this block. +- `transfer_hashes`: Is a vector of hex-encoded hashes identifying Transfers included in this block. + +When we serialize the `BlockBodyV1`, we create a buffer that contains the serialized representations of the individual fields present within the block. + +- `proposer` serializes to the byte representation of the `PublicKey`. If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. +- `deploy_hashes` serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of deploy hashes present within the body. +- `transfer_hashes` serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of transfers present within the body. + +### BlockBodyV2 {blockbodyv2} + +A modern block is structurally defined as: + +- [`transactions`](#transaction): Is a `BTreeMap` of transaction hashes and their given categories. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of values held within. The remainder consists of a repeating pattern of transaction categories as a `u8` value and then the associated `TransactionHash` the category tag describes. + +- [`rewarded_signatures`](./types.md#rewarded-signatures): A list of identifiers for finality signatures for a particular past block. It serializes as a vector of `SingleBlockRewardedSignatures` which describes signatures for a single ancestor block. The first entry represents the signatures for the parent block, the second for the parent of the parent, and so on. + +## Contract {#contract} + + A contract struct containing the following fields: + + - [`contract_package_hash`](#contractpackagehash) + + - [`contract_wasm_hash`](#contractwasmhash) + + - [`named_keys`](./types.md#namedkey) + + - [`entry_points`](./types.md#entrypoints) + + - [`protocol_version`](./types.md#protocolversion) + +### ContractPackageHash {#contractpackagehash} + +A `blake2b` hash of a contract package. The contract package hash serializes as a 32-byte buffer containing the bytes of the contract package hash. + +### ContractWasmHash {#contractwasmhash} + +A `blake2b` hash of a contract's Wasm. The contract's Wasm hash serializes as a 32-byte buffer containing the bytes of the contract's Wasm hash. + +### ContractHash {#contracthash} + +A `blake2b` hash of a contract. The contract hash serializes as a 32-byte buffer containing the bytes of the contract hash. + +### ContractPackageStatus {#contractpackagestatus} + +The lock status of the contract package, serialized as a [`boolean`](./primitives.md#boolean-clvalue-boolean) where `true` indicates a locked contract and `false` indicates an unlocked contract package. + +### ContractVersion {#contractversion} + +The version of the contract. + +- [`contract_hash`](#contracthash): The contract hash of the contract. + +- `contract_version`: The version of the contract within the protocol major version. It serializes as a [`u32` value](./primitives.md#clvalue-numeric). + +- `protocol_version_major`: The major element of the protocol version this contract is compatible with. It serializes as a [`u32` value](./primitives.md#clvalue-numeric). + +### ContractVersionKey {#contractversionkey} + +The major element of `ProtocolVersion` combined with `Contract` Version serialized as two [`u32`](./primitives.md#numeric-clvalue-numeric) values. + +### ContractWasm {#contractwasm} + +A container for a contract's Wasm bytes, serialized as the byte representation of itself. + +## Message {#message} + +A message emitted by an addressable entity during execution. The message `struct` contains the following fields: + +- `entity_hash`: The identity of the entity that produced the message, serialized as an [`EntityAddr`](./types.md#entity-addr). + +- `message`: The payload of the message, serialized as a [`MessagePayload`](#message-payload). + +- `topic_name`: The name of the topic on which the message was emitted, serialized as a [`String`](./primitives.md#clvalue-string). + +- `topic_name_hash`: The hash of the topic name, serialized as a [`TopicNameHash`](#topic-name-hash). + +- `topic_index`: The message index in the topic, serialized as a [`u32`](./primitives.md#clvalue-numeric) value. + +- `block_index`: The message index in the block, serialized as a [`u64`](./primitives.md#clvalue-numeric) value. + +### MessageAddr {#message-addr} + +A message topic address, a structure which consists of the following fields: + +- `entity_addr`: The entity address, serialized as an [`EntityAddr`](./types.md#entity-addr). + +- `topic_name_hash`: The hash of the topic name, serialized as a [`TopicNameHash`](#topic-name-hash). + +- `message_index`: The message index, serialized as an [`Option`](./primitives.md#clvalue-option) of `u32`. + +### MessageChecksum {#message-checksum} + +A newtype wrapping an array which contains the raw bytes of the hash of the message emitted. It serializes as a `CLType` [`u8`](./primitives.md#clvalue-numeric) tag followed by a [`ByteArray`](./primitives.md#clvalue-ByteArray). + +### MessageLimits {#message-limits} + +Configuration for message lists, serialized as three [`u32`](./primitives.md#clvalue-numeric) values: + +- `max_topic_name_size`: Maximum size in bytes of a topic name string. + +- `max_message_size`: Maximum message size in bytes. + +- `max_topics_per_contract`: Maximum number of topics that a contract can register. + +### MessagePayload {#message-payload} + +The payload of a message emitted by an addressable entity during execution. It serializes as either a `u8` tag of 0 followed by a a serialized version of a human-readable [`String`](./primitives.md#clvalue-string), or as a `u8` tag of 1 followed by serialized raw [`Bytes`](./types.md#bytes). + +### MessageTopicOperation {#message-topic-operation} + +Operations that can be performed on message topics. Currently, serializes as a [`u8`](./primitives.md#clvalue-numeric) of 0 representing the `Add` function. + +### TopicNameHash {#topic-name-hash} + +The hash of the name of a message topic, serialized as a [`u8`](./primitives.md#clvalue-numeric) describing the length of the string and the 32-byte serialized representation of the `string` itself. + +## Transaction (#transaction) + +A versioned wrapper for a transaction or deploy. It serializes as a `u8` tag of `0` followed by a [`Deploy`](#serialization-standard-deploy) or a `u8` tag of `1` followed by a [`TransactionV1`](#transactionv1). + +### Deploy {#serialization-standard-deploy} + +A deploy is a data structure containing a smart contract and the requester's signature(s). Additionally, the deploy header contains additional metadata about the deploy itself. A deploy is structurally defined as follows: + +- `hash`: The hash of the deploy header. +- `header`: Contains metadata about the deploy. The structure of the header is detailed further in this document. +- `payment`: The payment code for contained smart contract. +- `session`: The stored contract itself. +- `approvals`: A list of signatures. + +### Deploy-Hash {#deploy-hash} + +The deploy hash is a digest over the contents of the deploy header. The deploy hash serializes as the byte representation of the hash itself. + +### Deploy-Header {#deploy-header} + +- `account`: A supported public key variant (currently either `Ed25519` or `Secp256k1`). An `Ed25519` key is serialized as a buffer of bytes, with the leading byte being `1` for `Ed25519`, with remainder of the buffer containing the byte representation of the signature. Correspondingly, a `Secp256k1` key is serialized as a buffer of bytes, with the leading byte being `2`. +- `timestamp`: A timestamp is a struct that is a unary tuple containing a `u64` value. This value is a count of the milliseconds since the UNIX epoch. Thus the value `1603994401469` serializes as `0xbd3a847575010000` +- `ttl`: The **Time to live** is defined as the amount of time for which deploy is considered valid. The `ttl` serializes in the same manner as the timestamp. +- `gas_price`: The gas is `u64` value which is serialized as `u64` CLValue discussed below. +- `body_hash`: Body hash is a hash over the contents of the deploy body, which includes the payment, session, and approval fields. Its serialization is the byte representation of the hash itself. +- `dependencies`: Dependencies is a vector of deploy hashes referencing deploys that must execute before the current deploy can be executed. It serializes as a buffer containing the individual serialization of each DeployHash within the Vector. +- `chain_name`: Chain name is a human-readable string describing the name of the chain as detailed in the chainspec. It is serialized as a String CLValue described below. + +### Payment & Session {#payment--session} + +Payment and Session are both defined as `ExecutableDeployItems`. More information on `ExecutableDeployItems` can be found [here](../../developers/writing-onchain-code/calling-contracts.md) + +- Module Bytes are serialized such that the first byte within the serialized buffer is `0` with the rest of the buffer containing the bytes present. + + - `ModuleBytes { module_bytes: "[72 bytes]", args: 434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5 }` will serialize to + - `0x0048000000420481b0d5a665c8a7678398103d4333c684461a71e9ee2a13f6e859fb6cd419ed5f8876fc6c3e12dce4385acc777edf42dcf8d8d844bf6a704e5b2446750559911a4a328d649ddd48000000434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5` + +- StoredContractByHash serializes such that the first byte within the serialized buffer is 1u8. This is followed by the byte representation of the remaining fields. + + - `StoredContractByHash { hash: c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa4, entry_point: "pclphXwfYmCmdITj8hnh", args: d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850 }` + - `0x01c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa41400000070636c7068587766596d436d6449546a38686e685d000000d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850` + +- StoredContractByName serializes such that the first byte within the serialized buffer is 2u8. This is followed by the individual byte representation of the remaining fields. + + - `StoredContractByName { name: "U5A74bSZH8abT8HqVaK9", entry_point: "gIetSxltnRDvMhWdxTqQ", args: 07beadc3da884faa17454a }` + - `0x0214000000553541373462535a483861625438487156614b39140000006749657453786c746e5244764d685764785471510b00000007beadc3da884faa17454a` + +- StoredVersionedContractByHash serializes such that the first byte within the serialized buffer is 3u8. However, the field version within the enum serializes as an [Option](./primitives.md#option-clvalue-option) CLValue. + + - `StoredVersionedContractByHash { hash: b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423, version: None, entry_point: "PsLz5c7JsqT8BK8ll0kF", args: 3d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8 }` + - `0x03b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423001400000050734c7a3563374a73715438424b386c6c306b463b0000003d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8` + +- StoredVersionedContractByName serializes such that the first byte within the serialized buffer is 4u8. The name and entry_point are serialized as a [String](./primitives.md#string-clvalue-string) CLValue, with the version field serializing as an [Option](./primitives.md#option-clvalue-option). + + - `StoredVersionedContractByName { name: "lWJWKdZUEudSakJzw1tn", version: Some(1632552656), entry_point: "S1cXRT3E1jyFlWBAIVQ8", args: 9975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8 }` + - `0x04140000006c574a574b645a5545756453616b4a7a7731746e01d0c64e61140000005331635852543345316a79466c57424149565138270000009975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8` + +- Transfer serializes such that the first byte within the serialized buffer contains is 5u8, with the remaining bytes of the buffer containing the bytes contained within the args field of Transfer. + +### Approval {#approval} + +Approval contains two fields: + +- `signer`: The public key of the approvals signer. It serializes to the byte representation of the `PublicKey`. If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. +- `signature`: The approval signature, which serializes as the byte representation of the `Signature`. The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. + +### DeployInfo {#deployinfo} + +Information relating to a given deploy. The structure consists of the following fields: + +- `deploy_hash`: The hash of the relevant deploy, serialized as a byte representation of the hash itself. + +- `transfers`: Transfers performed by the deploy, serialized as a [`List`](./primitives.md#clvalue-list). + +- `from`: The account identifier of the creator of the deploy, serialized as an [`account_hash`](./types.md#account-hash). + +- `source`: The source purse used for payment of the deploy, serialized as a [`URef`](./primitives.md#clvalue-uref). + +- `gas`: The gas cost of executing the deploy, serialized as a [`U512`](./primitives.md#clvalue-numeric). + +## DeployConfig {#deployconfig} + +A `struct` containing configuration values associated with `deploys`. The structure contains the following fields: + +- `max_payment_cost`: The maximum amount any deploy can pay, serialized in [`Motes`](./types.md#motes). + +- `max_dependencies`: The maximum time to live any deploy can specify, serialized as a [`u8`](./primitives.md#clvalue-numeric). + +- `payment_args_max_length`: The maximum length in bytes of payment args per deploy, serialized as a [`u32`](./primitives.md#clvalue-numeric.) + +- `session_args_max_length`: The maximum length in bytes of session args per deploy, serialized as a [`u32`](./primitives.md#clvalue-numeric.) + +### TransactionV1 {#transactionv1} + +A unit of work sent by a client to the network, which when executed can cause global state to be altered. It is structurally defined as follows: + +- [`TransactionV1Hash`](#transactionv1hash) + +- [`TransactionV1Header`](#transactionv1header) + +- [`TransactionV1Body`](#transactionv1body) + +- `approvals`: A list of signatures. + +### TransactionV1Hash {#transactionv1hash} + +The transaction hash is a digest over the contents of the transaction header. The transaction hash serializes as the byte representation of the hash itself. + +### TransactionV1Header {#transactionv1header} + +The header portion of a transaction, structurally, is defined as follows: + +- `chain_name`: Chain name is a human-readable string describing the name of the chain as detailed in the chainspec. It is serialized as a [String](./primitives.md#string-clvalue-string). +- `timestamp`: A timestamp is a struct that is a unary tuple containing a `u64` value. This value is a count of the milliseconds since the UNIX epoch. Thus the value `1603994401469` serializes as `0xbd3a847575010000`. +- `ttl`: The **Time to live** is defined as the amount of time for which the transaction is considered valid. The `ttl` serializes in the same manner as the timestamp. +- `body_hash`: Body hash is a hash over the contents of the [transaction body](#transactionv1body). It serializes as the byte representation of the hash itself. +- [`pricing_mode`](./types.md#pricingmode-pricingmode) +- [`initator_addr`](./types.md#initiatoraddr-initiatoraddr) + +### TransactionV1Body {#transactionv1body} + +The body of a `TransactionV1`, consisting of the following: + +- [`args`](./types.md#runtimeargs-runtimeargs) +- [`target`](#transactiontarget) +- [`entry_point`](#transactionentrypoint) +- [`scheduling`](#transactionscheduling) + +### TransactionRuntime {#transactionruntime} + +The runtime used to execute a transaction, serialized as a [`u8`](./primitives.md#numeric-clvalue-numeric). Currently, only the `VmCasperV1` is available, which serializes as a `0`. + +### TransactionEntryPoint {#transactionentrypoint} + +An entry point of a transaction, serialized as a [`u8`](./primitives.md#numeric-clvalue-numeric) value based on the type of entry point. The following table outlines the available types: + +| Tag | Entry Point | +| --- | ----------- | +| 0 | Custom | +| 1 | Transfer | +| 2 | Add_Bid | +| 3 | Withdraw_Bid | +| 4 | Delegate | +| 5 | Undelegate | +| 6 | Redelegate | +| 7 | Activate_Bid | +| 8 | ChangePublicKey | +| 9 | Call | + +### TransactionConfig {#transactionconfig} + +A `struct` containing configuration values associated with `Transactions`. The structure contains the following fields: + +- `max_ttl`: The maximum time to live any transaction can specify, serialized as a [`TimeDiff`](./types.md#timediff). + +- `block_max_approval_count`: The maximum number of approvals (signatures) allowed in a block across all transactions, serialized as a [`u32`](./primitives.md#clvalue-numeric). + +- `max_block_size`: The maximum possible size in bytes of a block, serialized as a [`u32`](./primitives.md#clvalue-numeric). + +- `block_gas_limit`: The maximum sum of payment across al transactions included in a block, serialized as a [`u64`](./primitives.md#clvalue-numeric). + +- `native_transfer_minimum_motes`: The minimum token amount for a native transfer deploy or transaction, serialized as a [`u64`](./primitives.md#clvalue-numeric). + +- `max_timestamp_leeway`: The maximum value to which a `transaction_acceptor.timestamp_leeway` can be set in the *config.toml* file. + +- [`deploy_config`](#deployconfig): Configuration values specific to Deploy transactions. + +- [`transaction_v1_config`](#transactionv1config): Configuration values specific to V1 transactions. + +### TransactionV1Config {#transactionv1config} + +A `struct` containing configuration values associated with `TransactionV1s`. The structure contains the following fields: + +- `native_mint_lane`: The lane configuration for the native mint interaction, serializing as a vector of [`u64`](./primitives.md#clvalue-numeric) values. + +- `native_auction_lane`: The lane configuration for the native auction interaction, serializing as a vector of [`u64`](./primitives.md#clvalue-numeric) values. + +- `wasm_lanes`: The lane configuration for the Wasm-based lanes, serializing as a nested vector of [`u64`](./primitives.md#clvalue-numeric) values. + +### TransactionHash {#transactionhash} + +A versioned wrapper for transaction hash or deploy hash. It serializes as either a `u8` tag of 0 followed by a [`DeployHash`](#deploy-hash) or a `u8` tag of 1 followed by a [`TransactionV1Hash`](#transactionV1hash). + +### TransactionHeader {#transactionheader} + +A versioned wrapper for transaction header or deploy header. It serializes as either a `u8` tag of 0 followed by a [`DeployHeader`](#deploy-header) or a `u8` tag of 1 followed by a [`TransactionV1Header`](#transactionv1header). + +### TransactionId {#transactionid} + +The unique identifier of a `Transaction`, serialized as its [`TransactionHash`](#transactionhash) and [`ApprovalsHash`](#approvals-hash). + +### TransactionScheduling {#transactionscheduling} + +The scheduling mode of a transaction, serialized as a [`u8`](./primitives.md#numeric-clvalue-numeric) tag identifying the type: + +- `Standard` serializes as a `0`. + +- `FutureEra` serializes as a `1` followed by a future [`era_id`](./types.md#eraid-eraid). + +- `FutureTimestamp` serializes as a `2` followed by a future [`timestamp`](./types.md#timestamp-timestamp). + +### TransactionInvocationTarget {#transactioninvocationtarget} + +The identifier of a `stored` transaction target, serialized as one of the following: + +- `InvocableEntity` serializes as a `u8` tag of `0` followed by the hex-encoded entity address serialized as the byte representation of itself. + +- `InvocableEntityAlias` serializes as a `u8` tag of `1` followed by the alias serialized as a [`string`](./primitives.md#string-clvalue-string). + +- `Package` serializes as a `u8` tag of `2` followed by the [`package hash`](./types.md#packagehash-package-hash) and optionally the [`entity_version`](./types.md#entityversionkey-entityversionkey). + +- `PackageAlias` serializes as a `u8` tag of `3` followed by the alias serialized as a [`string`](./primitives.md#string-clvalue-string) and optionally the [`entity_version`](./types.md#entityversionkey-entityversionkey). + +### TransactionTarget {#transactiontarget} + +The execution target of a transaction, serializing as a [`u8`](./primitives.md#numeric-clvalue-numeric) that identifies the type, followed by any additional data. + +- `native` serializes as a `0`. + +- `stored` serializes as a `1` followed by the [`id`](#transactioninvocationtarget) and [`runtime`](#transactionruntime). + +- `session` serializes as a `2` followed by the [`kind`](#transactionsessionkind), [`module_bytes`](#payment--session) and [`runtime`](#transactionruntime). + +### TransactionWithExecutionInfo {#transaction-with-execution-info} + +A `struct` containing a`Transaction` with execution info. It serializes as a [`Transaction`](#transaction) followed by an [`Option`](./primitives.md#clvalue-option) of `ExecutionInfo`. \ No newline at end of file diff --git a/source/docs/casper/concepts/serialization/types.md b/source/docs/casper/concepts/serialization/types.md new file mode 100644 index 0000000000..25f60fda66 --- /dev/null +++ b/source/docs/casper/concepts/serialization/types.md @@ -0,0 +1,910 @@ +# Type Serialization + +## Account Config {#account-config} + +Configuration of an individual account in *accounts.toml*, containing the account's public key, main purse balance and validator config. + +- `public_key` The public key of the account, serialized as the byte representation of [itself](./primitives.md#clvalue-publickey). + +- `balance` The balance of the account's main purse, serialized as a [`U512 value`](./primitives.md#clvalue-numeric). + +- `validator` The validator configuration for the account, serialized as an [`Option`](./primitives.md#clvalue-option). + +## Account Hash {#account-hash} + +A `blake2b` hash of the public key, representing the address of a user's account. The account hash serializes as a 32-byte buffer containing the bytes of the account hash. + +## Account Identifier {#account-identifier} + +Identifier for possible ways to retrieve an Account. It can consist of any of the following in most situations: + +- [`PublicKey`](#publickey): The account's public key. + +- [`AccountHash`](#account-hash): The `blake2b` hash of the account's public key. + +## Action Thresholds {#action-thresholds} + +The minimum weight thresholds that have to be met when executing an action of a certain type. It serializes as three consecutive [`u8` values](./primitives.md#clvalue-numeric) as follows. + +- `deployment`: The minimum weight threshold required to perform deployment actions as a `u8` value. + +- `upgrade_management`: The minimum weight threshold required to perform upgrade management actions as a `u8` value. + +- `key_management`: The minimum weight threshold required to perform key management actions as a `u8` value. + +## Activation Point {#activation-point} + +The first era to which the associated protocol version applies. It serializes as a single [`u8`](./primitives.md#clvalue-numeric) tag indicating if the era in question is genesis. If it is the genesis era, the following bytes will be a `timestamp`. If not, the bytes represent an `era_id`. + +- `era_id`: An [Era ID newtype](#eraid) identifying the era when the protocol version will activate. + +- `timestamp`: A [timestamp](#timestamp) if the activation point is of the Genesis variant. + +## AddressableEntityHash {#addressable-entity-hash} + +The hex-encoded address of an addressable entity, which serializes as the byte representation of itself. + +## Approval {#approval} + +A struct containing a signature and the public key of the signer. + +- `signature`: The approval signature, which serializes as the byte representation of the [`Signature`](#signature). The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. + +- `signer`: The public key of the approvals signer. It serializes to the byte representation of the [`PublicKey`](./primitives.md#clvalue-publickey). If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. + +## ApprovalsHash {#approvals-hash} + +The cryptographic hash of the bytesrepr-encoded set of approvals. It serializes as a [`digest`](#digest). + +## AssociatedKey {#associatedkey} + +A key granted limited permissions to an Account, for purposes such as multisig. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of keys and weights held within. The remainder consists of a repeating pattern of serialized named keys and then weights of the length dictated by the first four bytes. + +- `account_hash`: The [account hash](#account-hash) of the associated key. + +- `weight`: The weight of an associated key. The weight serializes as a [`u8` value](./primitives.md#clvalue-numeric). + +## AvailableBlockRange {#availableblockrange} + +An unbroken, inclusive range of blocks. It serializes as two consecutive [`u64` values](./primitives.md#clvalue-numeric) containing the following two fields: + +- `low`: The inclusive lower bound of the range. + +- `high`: - The inclusive upper bound of the range. + +## BalanceHoldAddr {#balanceholdaddr} + +A balance hold address. It serializes as a [`BalanceHoldAddrTag`](#balanceholdaddrtag) describing the type of balance hold address as follows: + +- `Gas` serializes as a `BalanceHoldAddrTag` of `0` followed by the [URef](./primitives.md#clvalue-uref) of the purse the hold will be placed on, and the [`block_time`](#blocktime) that the hold was placed. + +- `Processing` serializes as a `BalanceHoldAddrTag` of `1` followed by the [URef](./primitives.md#clvalue-uref) of the purse the hold will be placed on, and the [`block_time`](#blocktime) that the hold was placed. + +## BalanceHoldAddrTag {#balanceholdaddrtag} + +A tag describing the type of `BalanceHoldAddr`, serializing as a single [`u8` value](./primitives.md#clvalue-numeric). + +## BalanceResponse {#balance-response} + +`BalanceResponse` is a struct that provides the response to a balance query. It consists the following fields: + +- `total_balance`: The purse's total balance, not considering holds. It serializes as a [`U512` value](./primitives.md#clvalue-numeric). + +- `available_balance`: The available balance, consisting of the total balance minus the sum of all active holds. It serializes as a [`U512` value](./primitives.md#clvalue-numeric). + +- `total_balance_proof`: A proof that the given value is present in the Merkle trie. It serializes as a `TrieMerkleProof`, consisting of a key, a value and a `proof_step`. + +- `balance_holds`: Any time-relevant active holds on the balance. It serializes as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of `BlockTime` and `BalanceHoldsWithProof` held within. The remainder consists of a repeating pattern of serialized `BlockTime`s and `BalanceHoldsWithProof`s of the length dictated by the first four bytes. + +## Bid {#bid} + +An entry in the validator map. The structure consists of the following fields: + +- `validator_public_key`: The validator's public key. It serializes as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `bonding_purse`: The purse used for bonding. It serializes as a [`Uref`](./primitives.md#clvalue-uref). + +- `staked_amount`: The amount of tokens staked by a validator (not including delegators). It serializes as a [`U512` value](./primitives.md#clvalue-numeric). + +- `delegation_rate`: The delegation rate of the bid. It serializes as an `i32` signed 32-bit integer primitive. + +- `vesting_schedule`: The vesting schedule for a genesis validator. `None` if it is a non-genesis validator. It serializes as an [`Option`](./primitives.md#clvalue-option). + +- `delegators`: The validator's delegators, indexed by their public keys. They are serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of `PublicKey`s and delegators held within. The remainder consists of a repeating pattern of serialized `PublicKey`s and then delegators of the length dictated by the first four bytes. + +- `inactive`: If the validator has been evicted. A [boolean](./primitives.md#clvalue-boolean) value that serializes as a single byte; `true` maps to `1`, while `false` maps to `0`. + +## BidAddr {#bidaddr} + +`BidAddr` manages data associated with bids for the `Auction` system contract. It serializes as a single [`u8`](./primitives.md#clvalue-numeric) tag describing the type of Bid, followed by information relating to the bid itself. It may be one of the following: + +- `Unified` A `BidAddr` for legacy unified bids. It serializes as a `u8` of `0` followed by the [`account_hash`](#account-hash) identifying the legacy bid. + +- `Validator` A validator bid. It serializes as a `u8` of `1` followed by the [`account_hash`](#account-hash) of the validator. + +- `Delegator` A delegator bid. It serializes as a `u8` of `2` followed by the [`account_hash`](#account-hash) of the associated validator and then the [`account_hash`](#account-hash) of the delegator. + +- `Credit` A `BidAddr` representing an auction credit. It serializes as a `u8` of `4` followed by the [`account_hash`](#account-hash) of the validator and the [`EraId`](#eraid) for the applicable credit. + +## BidKind {#bid-kind} + +Auction bid variants. It serializes as a single [`u8` value](./primitives.md#clvalue-numeric) indicating the type of bid kind as per the following table: + +| BidKind | u8 | Description | +| --------- | -- | ----------- | +| [Unified](#bid) | 0 | Legacy data that contains all delegators for a given validator. | +| [Validator](#validatorbid) | 1 | A bid record containing only validator data. | +| [Delegator](#delegatorbid) | 2 | A bid record containing only delegator data. | + +## BlockGlobalAddr {blockglobaladdr} + +An address for singleton values associated to a specific block. These are values which are calculated or set during the execution of a block such as the block timestamp, or the total count of messages emitted during the execution of the block. + +It serializes as two `u8` values, the first of which describes the category, followed by the underlying value as follows: + +- `BlockTime` begins with a `u8` of 0, followed by the `u8` of the block time. + +- `MessageCount` begins with a `u8` of 1, followed by message count as a `u8`. + +## BlockIdentifier {#blockidentifier} + +Identifier for possible ways to retrieve a Block. It can consist of any of the following in most situations: + +- [`hash`](./structures.md#block-hash): Identify and retrieve a Block with its hash. The `BlockHash` serializes as the byte representation of the hash itself. + +- `height`: Identify and retrieve the Block with its height. Height serializes as a single `u64` value. + +- `state_root_hash`: Identify and retrieve the Block with its state root hash. It serializes to the byte representation of the `state root hash`. The serialized buffer of the `state_root_hash` is 32 bytes long. + +## BlockSignatures {block-signatures} + +A collection of signatures for a single block, along with the associated block's hash and era ID. + +There are two possible versions for `BlockSignatures`, with a prefixed `u8` tag describing which version it is. + +- [`BlockSignaturesV1`](#block-signatures-v1) serializes as a `u8` of 0 followed by the `BlockSignaturesV1`. + +- [`BlockSignaturesV2`](#block-signatures-v2) serializes as a `u8` of 1 followed by the `BlockSignaturesV2`. + +### BlockSignaturesV1 {#block-signatures-v1} + +`BlockSignaturesV1` is a legacy version of `BlockSignatures` that applies to blocks created before the Condor release. The structure is as follows: + +- [`block_hash`](./structures.md#block-hash): The block hash of the associated block. It serializes as the byte representation of the hash itself. + +- [`era_id`](#eraid): The era ID in which this block was created. It serializes as a single [`u64` value](./primitives.md#clvalue-numeric). + +- `proofs`: The proofs of the block, a collection of validator's signatures of the block hash. It serializes as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of [`PublicKeys`](#publickey) and [`signatures`](#signature) held within. The remainder consists of a repeating pattern of serialized public keys and signatures of the length dictated by the first four bytes. + +### BlockSignaturesV2 {#block-signatures-v2} + +`BlockSignaturesV2` is the current version of `BlockSignatures` that applies to blocks created after the Condor release. The structure is as follows: + +- [`block_hash`](./structures.md#block-hash): The block hash of the associated block. It serializes as the byte representation of the hash itself. + +- `block_height`: The block height. It serializes as a single `u64` value. + +- [`era_id`](#eraid): The era ID in which this block was created. It serializes as a single [`u64` value](./primitives.md#clvalue-numeric). + +- [`chain_name_hash`](#chain-name-digest): The hash of the chain name of the associated block. It serializes as the byte representation of the hash itself. + +- `proofs`: The proofs of the block, a collection of validator's signatures of the block hash. It serializes as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of [`PublicKeys`](#publickey) and [`signatures`](#signature) held within. The remainder consists of a repeating pattern of serialized public keys and signatures of the length dictated by the first four bytes. + +## BlockSyncStatus {#blocksyncstatus} + +The status of syncing an individual block. It serializes as the byte representation of the [block hash](./structures.md#block-hash) of the block in question, followed by an [`option`](./primitives.md#option-clvalue-option) representing a [`u64`](./primitives.md#numeric-clvalue-numeric) of the block height and the remainder is the byte representation of the `acquisition_state` as a [string](./primitives.md#string-clvalue-string). + +## BlockTime (#blocktime) + +The block time serialized as a single `u64` value. + +## BTreeMap {#btreemap} + +A `BTreeMap` is a method of mapping keys to values within a Casper network. They serialize with the first 4 bytes representing a `u32` value describing the number of keys and values held within. The remainder consists of a repeating pattern of serialized keys and then values of the length dictated by the first four bytes. + +## BTreeSet {#btreeset} + +A `BTreeSet` is a method of storing a set of values within a Casper network. They serialize with the first 4 bytes representing a `u32` value describing the number of values held within. The remainder consists of a repeating series of values of the length dictated by the first four bytes. + +## ByteCode {#bytecode} + +A container for a contract's Wasm bytes. It serializes as the single `u8` [BidKind](#bidkind), followed by a [`u32`](./primitives.md#numeric-clvalue-numeric) value describing the size of the remaining [Bytes](#bytes) and then the bytes as described. + +## Bytes {#bytes} + +Hex-encoded bytes serialized as a `u32` value describing the length of the bytes, followed by the bytes themselves. + +## ByteCodeKind + +The type of byte code, serialized as a single `u8` value. A `0` indicates empty byte code, while a `1` indicates a `V1CasperWasm` to be executed with the first version of the Casper execution engine. + +## Caller {#caller} + +`Caller` is the identity of a calling entity. It serializes as one of two variants, described below: + +- `Initiator` is the overall calling account and serializes as a `u8` tag of 0 followed by the [`account_hash`](#accounthash) of the calling account. + +- `Entity` is a calling entity, such as a smart contract or a system contract. It serializes as a `u8` tag of 1 followed by the [`package_hash`](#packagehash) and [`entity_hash`](./structures.md#addressable-entity-hash). + +## CallStackElement {#call-stack-element} + +`CallStackElement` is a legacy `enum` created pre-Condor release that represents the origin of a sub-call in a call stack. It begins with a `u8` tag that describes the type of caller as follows: + +- `Session`: Session code, which serializes as a `u8` tag of 0 followed by the [`account_hash`](#accounthash) of the calling account. + +- `StoredSession`: Stored access to a session, serializing as a `u8` of 1 followed by the [`account_hash`](#accounthash), [`contract_package_hash`](./structures.md#contractpackagehash) and the [`contract_hash`](./structures.md#contracthash). + +- `StoredContract`: A contract, which serializes as a `u8` tag of 2 followed by the [`contract_package_hash`](./structures.md#contractpackagehash) and the [`contract_hash`](./structures.md#contracthash). + +## ChainNameDigest {#chain-name-digest} + +The cryptographic hash of a chain name, serialized as the byte representation of the hash itself. + +## ChainspecRegistry {#chainspecregistry} + +ChainspecRegistry is a unique key variant which contains a mapping of file names to the hash of the file itself. This map includes *Chainspec.toml* and may include *Accounts.toml* and *GlobalState.toml*. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of names as strings and [digests](#digest) held within. The remainder consists of a repeating pattern of serialized strings and then digests of the length dictated by the first four bytes. Digests and their inclusion criteria are as follows: + +- `chainspec_raw_hash` will always be included. + +- `genesis_accounts_raw_hash` may be included in specific circumstances. + +- `global_state_raw_hash` may be included in specific circumstances. + +## ChecksumRegistry {#checksum-registry} + +The checksum registry. It serializes as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of checksum names as strings and [digests](#digest) held within. The remainder consists of a repeating pattern of serialized strings and then digests of the length dictated by the first four bytes. + +## Delegator {#delegator} + +Represents a party delegating their stake to a validator (or "delegatee"). The structure consists of the following fields: + +- `delegator_public_key`: The public key of the delegator, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `staked_amount`: The amount staked by the delegator, serialized as a [`U512` value](./primitives.md#clvalue-numeric). + +- `bonding_purse`: The bonding purse associated with the delegation. It serializes as a [`URef` value](./primitives.md#clvalue-uref). + +- `validator_public_key`: The public key of the validator that the delegator will be delegating to, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `vesting_schedule`: The vesting schedule for the provided delegator bid. `None` if it is a non-genesis validator. It serializes as an [`Option`](./primitives.md#clvalue-option). + +## Digest {#digest} + +A `blake2b` hash digest. The digest serializes as a byte representation of the hash itself. + +## DisabledVersions {#disabledversions} + +Disabled contract versions, containing the following: + +- `contract_version`: The version of the contract within the protocol major version. It serializes as a [`u32` value](./primitives.md#clvalue-numeric). + +- `protocol_version_major`: The major element of the protocol version this contract is compatible with. It serializes as a [`u32` value](./primitives.md#clvalue-numeric). + +## Effects {#effects} + +A log of all transforms produced during execution, serialized as a vector of [transforms](#transformv2). + +## EntityAddr {#entity-addr} + +The address for an `AddressableEntity`. It serializes as a `u8` [`EntityKindTag`](#entity-kind-tag) followed by the 32-byte buffer containing the bytes of the `hash_addr` as follows: + +- `System`: A package associated with a native contract implementation, serialized as a `u8` of 0, followed by the `hash_addr`. + +- `Account`: A package associated with an Account hash, serialized as `u8` of 1 followed by the `hash_addr`. + +- `SmartContract`: A package associated with Wasm stored on chain, serialized as a `u8` of 2 followed by the `hash_addr` + +## EntityKind {#entity-kind} + +The type of `Package`, serialized as a `u8` [`EntityKindTag`](#entity-kind-tag) describing the type followed by further data as follows: + +- `System`: A package associated with a native contract implementation. It serializes as a `u8` of 0 followed by a [`SystemEntityType`](#system-entity-type). + +- `Account`: A package associated with an Account hash, serialized as a `u8` of 1 followed by an [`account_hash`](#accounthash). + +- `SmartContract`: A package associated with Wasm stored on chain, serialized as a `u8` of 2 followed by a [`transaction_runtime`](./structures.md#transactionruntime). + +## EntityKindTag {#entity-kind-tag} + +A tag for the variants of `EntityKind`, serialized as a single `u8` tag of 0 for `System`, 1 for `Account` and 2 for `SmartContract`. + +## EntityVersionKey {#entityversionkey} + +The major element of `ProtocolVersion` combined with `EntityVersion` serialized as two [`u32`](./primitives.md#numeric-clvalue-numeric) values. + +## EntityVersions {#entity-versions} + +A collection of entity versions, serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of [`EntityVersionKeys`](./structures.md#entityversionkey) mapped to [`AddressableEntityHashes`](./structures.md#addressable-entity-hash) within. The remainder consists of a repeating pattern of serialized `EntityVersionKeys` and `AddressableEntityHashes` of the length dictated by the first four bytes. + +## EntryPoint (Contract) {#entrypoint} + +A type of signature method. Order of arguments matters, since this can be referenced by index as well as name. + +- `name`: The name of the entry point, serialized as a [`String`](./primitives.md#clvalue-string). + +- `args`: Arguments for this method. They serialize as a list of the [`Parameter`](#parameter)s, where each parameter represents an argument passed to the entrypoint. + +- `ret`: The return type of the method, serialized as a [`Unit`](./primitives.md#clvalue-unit). + +- `access`: An `enum` describing the possible access control options for a contract entry point. It serializes as a `u8` value of 1 for public or a 2 followed by a [`List`](./primitives.md#clvalue-list) of authorized users. + +- `entry_point_type`: Identifies the type of entry point. It serializes as a `0` for Session and a `1` for Contract. + +## EntryPoint (Entity) {#entry-point} + +The type signature of a method. This structure consists of the following fields: + +- `name`: The name of the entry point, serialized as a [`String`](./primitives.md#clvalue-string). + +- `args`: Arguments for this method. They serialize as a list of the [`Parameter`](#parameter)s, where each parameter represents an argument passed to the entrypoint. + +- `ret`: The return type of the method, serialized as a [`Unit`](./primitives.md#clvalue-unit). + +- `access`: An `enum` describing the possible access control options for a contract entry point. It serializes as a `u8` value of 1 for public or a 2 followed by a [`List`](./primitives.md#clvalue-list) of authorized users. + +- [`entry_point_type`](#entry-point-type) + +- [`entry_point_payment`](#entry-point-payment) + +### EntryPointAddr + +An entry point's address. It serializes as one of the two following variants: + +- `VmCasperV1`: A V1 entry point. It serializes as a `u8` of 0 followed by an [`EntityAddr`](#entity-addr) and `name_bytes`, which is the 32-byte hash of the name of the entry point. + +- `VmCasperV2`: A V2 entry point. It serializes as a `u8` of 1 followed by an [`EntityAddr`](#entity-addr) followed by a `u32` `Selector`. + +### EntrypointPayment + +An `enum` specifying who pays for the invocation and execution of an entry point. It serializes as a single `u8` byte tag as follows: + +- `Caller`: Serializes as a 0 and indicates that the caller must cover the cost. + +- `SelfOnly`: Serializes as a 1 and indicates that the contract will pay the cost to execute itself, but no subsequent invoked contracts. + +- `SelfOnward`: Serializes as a 2 and indicates that the contract will pay for executing itself and any subsequent invocations. + +### EntrypointType + +The context of method execution. It serializes as one of the following: + +- `Caller`: Serializes as a single `u8`, `0b00000000` + +- `Called`: Serializes as a single `u8`, `0b00000001` + +- `Factory`: Serializes as a single `u8`, `0b10000000` + +## EntrypointV2 + +The entry point for the V2 Casper VM. It serializes as a `u32` representing the `Selector` followed by a `u32` representing the `Flags`. + +## EntryPoints {#entrypoints} + +Entry points for a given entity, serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of `String` to `EntryPoint`s held within. The remainder consists of a repeating pattern of serialized `String`s and then `EntryPoint`s of the length dictated by the first four bytes. + +## EraID {#eraid} + +An Era ID newtype. It serializes as a single [`u64` value](./primitives.md#clvalue-numeric). + +## EraInfo {#erainfo} + +Auction metadata, intended to be recorded each era. It serializes as a [`List`](./primitives.md#clvalue-list) of [seigniorage allocations](#seigniorageallocation). + +## ExecutableDeployItem {#executable-deploy-item} + +The executable component of a `Deploy`, serialized as a `u8` identifying tag followed by additional bytes as follows: + +- `ModuleBytes`: Serializes as a `u8` tag of 0 followed by [`bytes`](#bytes) and [`runtimeargs`](#runtimeargs). + +- `StoredContractByHash`: Serializes as a `u8` tag of 1 followed by the contract hash as an [`AddressableEntityHash`](./structures.md#addressable-entity-hash), the name of an entry point as a [String](./primitives.md#string-clvalue-string) and [`runtimeargs`](#runtimeargs). + +- `StoredContractByName`: Serializes as a `u8` tag of 2 followed by the named key as a [String](./primitives.md#string-clvalue-string), the name of an entry point as a `String` and [`runtimeargs`](#runtimeargs). + +- `StoredVersionedContractByHash`: Serializes as a `u8` tag of 3 followed by the [`PackageHash`](#package-hash), the `version` as an [`Option`](./primitives.md#clvalue-option), an entry point as a [String](./primitives.md#string-clvalue-string) and [`runtimeargs`](#runtimeargs). + +- `StoredVersionedContractByName`: Serializes as a `u8` tag of 4 followed by the named key as a [String](./primitives.md#string-clvalue-string), the `version` as an [`Option`](./primitives.md#clvalue-option), the name of an entry point as a `String` and [`runtimeargs`](#runtimeargs). + +- `Transfer`: Serializes as a `u8` tag of 5 followed by [`runtimeargs`](#runtimeargs). + +## ExecutionEffect {#executioneffect} + +The journal of execution transforms from a single deploy. + +- `operations`: The resulting operations, serialized as a [`List`](./primitives.md#clvalue-list) of [operations](#operation). + +- `transforms`: The actual [transformation](#transform) performed while executing a deploy. + +## ExecutionResultV1 {#executionresultv1} + +The result of a single deploy. It serializes as a `u8` tag indicating either `Failure` as a 0 or `Success` as a 1. This is followed by the appropriate structure below: + +### `Failure` + +The result of a failed execution. + +- `effect`: The [effect](#executioneffect) of executing the deploy. + +- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). + +- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. + +- `error_message`: The error message associated with executing the deploy, serialized as a [`String`](./primitives.md#clvalue-string). + +### `Success` + +The result of a successful execution. + +- `effect`: The [effect](#executioneffect) of executing the deploy. + +- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). + +- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. + +## ExecutionResultV2 {#executionresultv2} + +The result of a single deploy. It serializes as a `u8` tag indicating either `Failure` as a 0 or `Success` as a 1. This is followed by the appropriate structure below: + +### `Failure` + +The result of a failed execution. + +- `effects`: The [effect](#effects) of executing the deploy. + +- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). + +- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. + +- `error_message`: The error message associated with executing the deploy, serialized as a [`String`](./primitives.md#clvalue-string). + +### `Success` + +The result of a successful execution. + +- `effects`: The [effects](#effects) of executing the deploy. + +- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). + +- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. + +## Gas {#gas} + +The `Gas` structure serializes as a [`U512`](./primitives.md#clvalue-numeric) amount of gas. + +## Group {#group} + +A (labeled) "user group". Each method of a versioned contract may be associated with one or more user groups which are allowed to call it. User groups are serialized as a [String](./primitives.md#clvalue-string). + +## Groups {#groups} + +They are serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of user groups and `BTreeSets` of [`URef`](./primitives.md#clvalue-uref)s held within. The remainder consists of a repeating pattern of serialized user groups and `BTreeSets` of the length dictated by the first four bytes. + +## InitiatorAddr (#initiatoraddr) + +The address of the initiator of a [`TransactionV1`](./structures.md#transactionv1), which serializes as a `u8` of `0` followed by a [`PublicKey`](#publickey-publickey) or a `1` followed by an [`AccountHash`](#account-hash). + +## Keys {#serialization-standard-state-keys} + +A _key_ in [Global State](../design/casper-design.md#global-state-head) is one of the following data types: + +- 32-byte account identifier (called an "account identity key") +- 32-byte immutable contract identifier (called a "hash key") +- 32-byte reference identifier (called an "unforgeable reference") +- 32-byte transfer identifier +- 32-byte deploy information identifier +- 32-byte purse balance identifier +- 32-byte Auction bid identifier +- 32-byte Auction withdrawal identifier +- 32-byte Dictionary identifier +- 32-byte System Contract Registry +- 32-byte Auction unbond identifier +- 32-byte Chainspec Registry + +The one exception to note here is the identifier for [`EraInfo`](#erainfo), which actually serializes as a [`u64`](./primitives.md#clvalue-numeric) value with an additional byte for the tag. + +### Account identity key {#global-state-account-key} + +This key type is used specifically for accounts in the global state. All accounts in the system must be stored under an account identity key, and no other types. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](../design/casper-design.md#accounts-associated-keys-weights) for more information). + +### Hash key {#serialization-standard-hash-key} + +This key type is used for storing contracts immutably. Once a contract is written under a hash key, that contract can never change. The 32-byte identifier representing this key is derived from the `blake2b256` hash of the deploy hash (see [block-structure-head](../design/casper-design.md#block-structure-head) for more information) concatenated with a 4-byte sequential ID. The ID begins at zero for each deploy and increments by one each time a contract is stored. The purpose of this ID is to allow each contract stored in the same deploy to have a unique key. + +### Unforgeable Reference (`URef`) {#serialization-standard-uref} + +`URef` broadly speaking can be used to store values and manage permissions to interact with the value stored under the `URef`. `URef` is a tuple which contains the address under which the values are stored and the Access rights to the `URef`. Refer to the [Unforgeable Reference](../design/casper-design.md#uref-head) section for details on how `URefs` are managed. + +### Transfer Key {#serialization-standard-transfer-key} + +This key type is used specifically for transfers in the global state. All transfers in the system must be stored under a transfer key and no other type. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the transfer address associated with the given transfer + +### DeployInfo Key {#serialization-standard-deploy-info-key} + +This key type is used specifically for storing information related to deploys in the global state. Information for a given deploy is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the deploy itself. + +### EraInfo Key {#serialization-standard-era-info-key} + +This key type is used specifically for storing information related to the `Auction` metadata for a particular era. The underlying data type stored under this is a vector of the allocation of seigniorage for that given era. The identifier for this key is a new type that wraps around the primitive `u64` data type and co-relates to the era number when the auction information was stored. + +This key type is used specifically for storing information related to auction bids in the global state. Information for the bids is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](../design/casper-design.md#accounts-associated-keys-weights) for more information). + +This key type is used specifically for storing information related to auction withdraws in the global state. Information for the withdrawals is stored under this key only. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](../design/casper-design.md#accounts-associated-keys-weights) for more information). + +### Serialization for `Key` {#serialization-standard-serialization-key} + +Given the different variants for the over-arching `Key` data-type, each of the different variants is serialized differently. This section of this chapter details how the individual variants are serialized. The leading byte of the serialized buffer acts as a tag indicating the serialized variant. + +| `Key` | Serialization Tag | +| ------------ | ----------------- | +| `Account` | 0 | +| `Hash` | 1 | +| `URef` | 2 | +| `Transfer` | 3 | +| `DeployInfo` | 4 | +| `EraInfo` | 5 | +| `Balance` | 6 | +| `Bid` | 7 | +| `Withdraw` | 8 | +| `Dictionary` | 9 | +| `SystemContractRegistry`| 10 | +| `EraSummary` | 11 | +| `Unbond` | 12 | +| `ChainspecRegistry` | 13 | +| `ChecksumRegistry` | 14 | +| `BidAddr` | 15 | + +| `Package` | 16 | +| `AddressableEntity` | 17 | +| `ByteCode` | 18 | +| `Message` | 19 | + +- `Account` serializes as a 32 byte long buffer containing the byte representation of the underlying `AccountHash` +- `Hash` serializes as a 32 byte long buffer containing the byte representation of the underlying `Hash` itself. +- `URef` is a tuple that contains the address of the URef and the access rights to that `URef`. The serialized representation of the `URef` is 33 bytes long. The first 32 bytes are the byte representation of the `URef` address, and the last byte contains the bits corresponding to the access rights of the `URef`. Refer to the [CLValue](./primitives.md#clvalue-clvalue) section of this chapter for details on how `AccessRights` are serialized. +- `Transfer` serializes as a 32 byte long buffer containing the byte representation of the hash of the transfer. +- `DeployInfo` serializes as 32 byte long buffer containing the byte representation of the Deploy hash. See the Deploy section above for how Deploy hashes are serialized. +- `EraInfo` serializes a `u64` primitive type containing the little-endian byte representation of `u64`. +- `Balance` serializes as 32 byte long buffer containing the byte representation of the URef address. +- `Bid` and `Withdraw` both contain the `AccountHash` as their identifier; therefore, they serialize in the same manner as the `Account` variant. +- `Dictionary` serializes as the 32 byte long buffer containing the byte representation of the seed URef hashed with the identifying name of the dictionary item. +- `SystemContractRegistry` serializes as a 32 byte long buffer of zeros. +- `EraSummary` serializes as a 32 byte long buffer of zeros. +- `Unbond` contains the `AccountHash` as its identifier; therefore, it serialize in the same manner as the `Account` variant. +- `ChainspecRegistry` serializes as a 32 byte long buffer of ones. +- `ChecksumRegistry` serializes as a 32 byte long buffer of zeros. +- `BidAddr` may be one of three types: + - `Unified` serializes as the tag `0` followed by a 32 byte long buffer containing the byte representation of a legacy bid. + - `Validator` serializes as the tag `1` followed by a 32 byte long buffer containing the byte representation of a validator's hash. + - `Delegator` serializes as the tag `2` followed by a 32 byte long buffer containing the byte representation of the associated validator's hash, appended with a 32 byte long buffer containing the byte representation of the given delegator's hash. + +### Permissions {#serialization-standard-permissions} + +There are three types of actions that can be done on a value: read, write, add. The reason for _add_ to be called out separately from _write_ is to allow for commutativity checking. The available actions depend on the key type and the context. Some key types only allow controlled access by smart contracts via the contract API, and other key types refer to values produced and used by the system itself and are not accessible to smart contracts at all but can be read via off-chain queries. This is summarized in the table below: + +| Key | Type Available Actions | +| -------- | ----------------------- | +| Account | Read + Add (via API) | +| Hash | Read | +| URef | Read + Write and/or Add | +| Transfer | System | +| Deploy | System | +| EraInfo | System | +| Balance | Read (via API) | +| Bid | System | +| Withdraw | System | +| Dictionary | Read (via API) | +| SystemContractRegistry | Read (via API)| +| Unbond | System | +| ChainspecRegistry | Read (via API) | + +--- + +Refer to [URef permissions](../design/casper-design.md#uref-permissions) on how permissions are handled in the case of `URef`s. + +## MessageTopics {#message-topics} + +A topic for contract-level messages. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of `topic_name` strings and [`topic_name_hash`](#topicnamehash) held within. The remainder consists of a repeating pattern of serialized `topic_name` and `topic_name_hash` of the length dictated by the first four bytes. + +## MessageTopicSummary {#message-topic-summary} + +A summary of a message topic that will be stored in global state. It serializes as a [`u32`](./primitives.md#numeric-clvalue-numeric) value for the `message_count` followed by the [`BlockTime`](#blocktime-blocktime) + +## Motes (#motes) + +A `struct` representing a number of `Motes` serialized as a [`U512`](./primitives.md#clvalue-numeric) value. + +## NamedArg {#namedarg} + +Named arguments to a contract. It is serialized by the combination of a [`String`](./primitives.md#clvalue-string) followed by the associated [`CLValue`](./primitives.md#clvalue-clvalue). + +## NamedKey {#namedkey} + +A mapping of string identifiers to a Casper `Key` type. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of named keys and values held within. The remainder consists of a repeating pattern of serialized named keys and then values of the length dictated by the first four bytes. + +- `name`: The name of the entry. It serializes as a [`string`](./primitives.md#clvalue-string). + +- `key`: The value of the entry, which is a Casper `Key` type. + +The named keys portion of the account structure serializes as a mapping of a string to Casper `Key` values as described [here](#serialization-standard-serialization-key). + +## NamedKeyAddr {#named-key-addr} + +A NamedKey address, serialized as an [`EntityAddr`](#entity-addr) followed by a [`u8`](./primitives.md#clvalue-numeric) describing the length of a string and the 32-byte representation of the string itself. + +## NamedKeyValue {#named-key-value} + +A NamedKey value, serialized as the `named_key` serialized as a [`CLValue`](./primitives.md#clvalue-clvalue) followed by the `name` of the key also serialized as a [`CLValue`](./primitives.md#clvalue-clvalue). + +## NamedKeys {#named-keys} + +A collection of named keys. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of [`names`](./primitives.md#clvalue-string) and [`keys`](./primitives.md#clvalue-key) held within. The remainder consists of a repeating pattern of names and keys of the length dictated by the first four bytes. + +## Operation {#operation} + +An operation performed while executing a deploy. It contains: + +- `key`: The formatted string of the key, serialized as a [`String`](./primitives.md#clvalue-string). + +- `kind`: OpKind, The type of operation performed. It serializes as a single byte based on the following table: + +|OpKind|Serialization| +|------|-------------| +|Read | 0 | +|Write | 1 | +|Add | 2 | +|NoOp | 3 | + +## Package {#package} + +A structure defining an entity, metadata and security container. The structure consists of the following fields: + +- [`access_key`](./primitives.md#uref-clvalue-uref) + +- `versions`: An array of entity versions associated with given hashes. + +- [`disabled_versions`](#entityversionkey-entityversionkey) + +- [`groups`](#group-group) + +- [`lock_status`](./structures.md#contractpackagestatus) + +## PackageHash {#package-hash} + +The hex-encoded address of a package associated with an [`AddressableEntity`](./structures.md#addressableentity-addressable-entity), serialized as the byte representation of itself. + +## PackageStatus {#package-status} + +The lock status of the package, serialized as a [`boolean`](./primitives.md#boolean-clvalue-boolean) where `true` indicates a locked package and `false` indicates an unlocked package. + +## Parameter {#parameter} + +Parameter to a method, structured as a name followed by a `CLType`. It is serialized as a [`String`](./primitives.md#clvalue-string) followed by a [`CLType`](./primitives.md#clvalue-cltype). + +## PricingMode (#pricingmode) + +The pricing mode of a transaction, with two possible variants. It serializes as a `u8` tag followed by additional data based on the following table: + +| Tag | PricingMode| Description | +| --- | ---------- | ----------- | +| 0 | Classic | The original payment model, in which the creator of a transaction specifies how much they will pay and at which gas price. | +| 1 | Fixed | The cost of the transaction is determined by the cost table, per the transaction kind. | + +### Classic {#pricingmode-classic} + +After the `0` tag, a `Classic` `PricingMode` serializes as the [`u64`](./primitives.md#numeric-clvalue-numeric) `payment_amount` followed by the `u64` value of the `gas_price`. + +### Fixed {#pricingmode-fixed} + +After the `1` tag, a `Fixed` `PricingMode` serializes as the [`u64`](./primitives.md#numeric-clvalue-numeric) `gas_price_tolerance`. + +## ProtocolVersion {#protocolversion} + +A newtype indicating the Casper Platform protocol version. It is serialized as three [`u32`](./primitives.md#clvalue-numeric) values indicating major, minor and patch versions in that order. + +## PublicKey {#publickey} + +Hex-encoded cryptographic public key, including the algorithm tag prefix. Serialization can be found under [`PublicKey`](./primitives.md#clvalue-publickey). + +## RewardedSignatures {#rewarded-signatures} + +A list of identifiers for finality signatures for a particular past block. It serializes as a vector of `SingleBlockRewardedSignatures` which describes signatures for a single ancestor block. The first entry represents the signatures for the parent block, the second for the parent of the parent, and so on. + +## RuntimeArgs {#runtimeargs} + +Represents a collection of arguments passed to a smart contract. They serialize as a [`List`](./primitives.md#clvalue-list) comprised of [`Tuples`](./primitives.md#clvalue-tuple). + +## SeigniorageAllocation {#seigniorageallocation} + +Information about seigniorage allocation. + +If the seigniorage allocation in question is for a validator, it serializes as the validator's [`PublicKey`](./primitives.md#clvalue-publickey) followed by the [`U512` amount](./primitives.md#clvalue-numeric). + +If it is a delegator, it serializes as the delegator's [`PublicKey`](./primitives.md#clvalue-publickey), followed by the validator's [`PublicKey`](./primitives.md#clvalue-publickey) and finally the [`U512` amount](./primitives.md#clvalue-numeric). + +## SemVer {#semver} + +A `struct` for semantic versioning, it serializes as three [`u32`](./primitives.md#clvalue-numeric) that describe the major version, minor version and patch version. + +## Signature {#signature} + +The signature serializes the byte representation of the underlying cryptographic primitive signature. The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. + +## Stored Values {#serialization-standard-values} + +A value stored in the global state is a `StoredValue`. A `StoredValue` is one of three possible variants: + +- A `CLValue` +- A contract +- An account + +We discuss `CLValue` and contract in more detail below. Details about accounts can be found in [accounts-head](../design/casper-design.md#accounts-head). + +Each `StoredValue` is serialized when written to the global state. The serialization format consists of a single byte tag, indicating which variant of `StoredValue` it is, followed by the serialization of that variant. The tag for each variant is as follows: + +- `CLValue` is `0` +- `Account` is `1` +- `Contract` is `2` + +The details of `CLType` serialization are in the following section. Using the serialization format for `CLValue` as a basis, we can succinctly write the serialization rules for contracts and accounts: + +- contracts serialize in the same way as data with `CLType` equal to `Tuple3(List(U8), Map(String, Key), Tuple3(U32, U32, U32))`; +- accounts serialize in the same way as data with `CLType` equal to `Tuple5(ByteArray(U8, 32), Map(String, Key), URef, Map(ByteArray(U8, 32), U8), Tuple2(U8, U8))`. + +Note: `Tuple5` is not a presently supported `CLType`. However, it is clear how to generalize the rules for `Tuple1`, `Tuple2`, `Tuple3` to any size tuple. + +## SystemContractRegistry {#systemcontractregistry} + +SystemContractRegistry is a unique `Key` under which a mapping of the names and `ContractHashes` for system contracts. This includes `Mint`, `Auction`, `HandlePayment` and `StandardPayment`. It is serialized as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of names as strings and [ContractHashes](./structures.md#contracthash) held within. The remainder consists of a repeating pattern of serialized strings and then ContractHashes of the length dictated by the first four bytes. + +## SystemEntityType {#system-entity-type} + +Entity types for system contracts, serialized as a single `u8` tag identifying the contract as per the following table: + +| Tag | System Contract | +| --- | --------------- | +| 0 | `Mint` | +| 1 | `Auction` | +| 2 | `StandardPayment` | +| 3 | `HandlePayment` | + +## TimeDiff {#timediff} + +A human-readable duration between two timestamps. It serializes as a single [`u64`](./primitives.md#clvalue-numeric) value. + +## Timestamp {#timestamp} + +A timestamp formatted as per RFC 3339 and serialized as a single [`u64`](./primitives.md#clvalue-numeric) value. + +## TopicNameHash {#topic-name-hash} + +A `blake2b` hash of a topic name. The topic name hash serializes as a 32-byte buffer containing the bytes of the topic name hash. + +## TransferAddr {#transferaddr} + +Hex-encoded transfer address, which serializes as a byte representation of itself. + +## TransformKindV1 {#transform} + +The actual transformation performed while executing a deploy. It serializes as a single `u8` value indicating the type of transform performed as per the following table. The remaining bytes represent the information and serialization as listed. + +| Transform Type | Serialization | Description | +|----------------------|---------------|------------------------------------------------------------------------------| +|Identity | 0 | A transform having no effect. | +|Write_CLValue | 1 | Writes the given [`CLValue`](./primitives.md#clvalue-calvalue) to global state. | +|Write_Account | 2 | Writes the given [`Account`](#account-hash) to global state. | +|Write_Contract_WASM | 3 | Writes a smart [contract as Wasm](./structures.md#contractwasmhash) to global state. | +|Write_Contract | 4 | Writes a smart [contract](./structures.md#contracthash) to global state. | +|Write_Contract_Package| 5 | Writes a smart [contract package](./structures.md#contractpackagehash) to global state. | +|Write_Deploy_Info | 6 | Writes the given [`DeployInfo`](./structures.md#deployinfo) to global state. | +|Write_Transfer | 7 | Writes the given [Transfer](#transferaddr) to global state. | +|Write_Era_Info | 8 | Writes the given [`EraInfo`](#erainfo) to global state. | +|Write_Bid | 9 | Writes the given [`Bid`](#bid) to global state. | +|Write_Withdraw | 10 | Writes the given [Withdraw](#unbondingpurse) to global state. | +|Add_INT32 | 11 | Adds the given [`i32`](./primitives.md#clvalue-numeric). | +|Add_UINT64 | 12 | Adds the given [`u64`](./primitives.md#clvalue-numeric). | +|Add_UINT128 | 13 | Adds the given [`U128`](./primitives.md#clvalue-numeric). | +|Add_UINT256 | 14 | Adds the given [`U256`](./primitives.md#clvalue-numeric). | +|Add_UINT512 | 15 | Adds the given [`U512`](./primitives.md#clvalue-numeric). | +|Add_Keys | 16 | Adds the given collection of [named keys](#namedkey). | +|Failure | 17 | A failed transformation, containing an error message. | + +## TransformKindV2 {#transformV2} + +The actual transformation performed while executing a deploy. It serializes as a single `u8` value indicating the type of transform performed as per the following table. The remaining bytes represent the information and serialization as listed. + +| Transform Type | Serialization | Description | +| -------------- | ------------- | ----------- | +| Identity | 0 | A transform having no effect, created as a result of reading from the global state. | +| Write | 1 | Writes a new value in the global state. | +| AddInt32 | 2 | Adds the given [`i32`](./primitives.md#clvalue-numeric). | +| AddUInt64 | 3 | Adds the given [`u64`](./primitives.md#clvalue-numeric). | +| AddUInt128 | 4 | Adds the given [`U128`](./primitives.md#clvalue-numeric). | +| AddUInt256 | 5 | Adds the given [`U256`](./primitives.md#clvalue-numeric). | +| AddUInt512 | 6 | Adds the given [`U512`](./primitives.md#clvalue-numeric). | +| AddKeys | 7 | Adds the given collection of [named keys](#namedkey). | +| Failure | 8 | A failed transformation, containing an error message. | +| Prune | 9 | Removes the pathing to the global state entry of the specified key. The pruned element remains reachable from previously generated global state root hashes, but will not be included in the next generated global state root hash and subsequent states. | + +## TransformEntry {#transformentry} + +A transformation performed while executing a deploy. + +## TransformV1 {#transformv1} + +A legacy transform struct serialized as a [`String`](./primitives.md#string-clvalue-string) of the [key](./primitives.md#key-clvalue-key) followed by the [`transformkindv1`](#transformkindv1). + +## Transformv2 {#transformv2} + +A struct representing an executed transformation serialized as a [`String`](./primitives.md#string-clvalue-string) of the [key](./primitives.md#key-clvalue-key) followed by the [`transformkindv2`](#transformkindv2). + +## UnbondingPurse {#unbondingpurse} + +A purse used for unbonding. The structure consists of the following: + +- `bonding_purse`: The bonding purse, serialized as a [`URef`](./primitives.md#clvalue-uref). + +- `validator_public_key`: The public key of the validator, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `unbonder_public_key`: The public key of the unbonder, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `era_of_creation`: Era in which this unbonding request was created, as an [`EraId`](#eraid) newtype, which serializes as a [`u64`](./primitives.md#clvalue-numeric) value. + +- `amount`: The unbonding amount, serialized as a [`U512`](#clvalue-numeric) value. + +- `new_validator`: The validator public key to redelegate to, serialized as an [`Option`](./primitives.md#clvalue-option) containing the public key. + +## ValidatorBid {#validatorbid} + +An entry in the validator map. The structure consists of the following fields: + +- `validator_public_key`: The public key of the validator that the delegator will be delegating to, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `bonding_purse`: The bonding purse associated with the delegation. It serializes as a [`URef` value](./primitives.md#clvalue-uref). + +- `staked_amount`: The amount staked by the delegator, serialized as a [`U512` value](./primitives.md#clvalue-numeric). + +- `delegation_rate`: The delegation rate serialized as a [`u8` value](./primitives.md#numeric-clvalue-numeric). + +- `vesting_schedule`: The vesting schedule for the provided delegator bid. `None` if it is a non-genesis validator. It serializes as an [`Option`](./primitives.md#clvalue-option). + +- `inactive`: The validator's inactivity status, serialized as a [`boolean`](./primitives.md#boolean-clvalue-boolean). + +## ValidatorChange {#validator-change} + +A change to a validator's status between two eras, serialized as a [`u8`](./primitives.md#clvalue-numeric) tag as follows: + +| Tag | Change | +| --- | ----------- | +| 0 | Added | +| 1 | Removed | +| 2 | Banned | +| 3 | Cannot Propose | +| 4 | Seen as Faulty | + +## ValidatorConfig {#validator-config} + +A validator account configuration, serialized as a [`bonded_amount`](#motes) followed by the `delegation_rate` as a [`u8`](./primitives.md#clvalue-numeric). + +## ValidatorCredit {#validator-credit} + +A `struct` representing the record of a validator credit, with fields as follows: + +- [`validator_public_key`](./primitives.md#clvalue-publickey): The validator's public key. + +- [`era_id`](#eraid): The era ID the credit was created. + +- `amount`: The credit amount as a [`U512`](./primitives.md#clvalue-numeric). + +## WithdrawPurse {#withdrawpurse} + +A purse used for unbonding, replaced in 1.5 by [UnbondingPurse](#unbondingpurse). WithdrawPurses prior to 1.5 were known as UnbondingPurses and now consist of historical data. + +- `bonding_purse`: The bonding purse, serialized as a [`URef`](./primitives.md#clvalue-uref). + +- `validator_public_key`: The public key of the validator, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `unbonder_public_key`: The public key of the unbonder, serialized as a [`PublicKey`](./primitives.md#clvalue-publickey). + +- `era_of_creation` Era in which this unbonding request was created, as an [`EraId`](#eraid) newtype, which serializes as a [`u64`](./primitives.md#clvalue-numeric) value. + +- `amount` The unbonding amount, serialized as a [`U512`](./primitives.md#clvalue-numeric) value. + diff --git a/source/docs/casper/concepts/transactions-and-transaction-lifecycle.md b/source/docs/casper/concepts/transactions-and-transaction-lifecycle.md index 419574e39f..2003bd295f 100644 --- a/source/docs/casper/concepts/transactions-and-transaction-lifecycle.md +++ b/source/docs/casper/concepts/transactions-and-transaction-lifecycle.md @@ -15,7 +15,7 @@ A [transaction](./glossary/T.md#transaction) is a data structure containing Wasm - Body: Containing payment code and session code (more details on these below) - Header: containing - - The [Public Key](./serialization-standard.md#publickey) of the account in whose context the transaction will run + - The [Public Key](./serialization/types.md#publickey) of the account in whose context the transaction will run - The timestamp of the transaction’s creation - A time-to-live, after which the transaction expires and cannot be included in a block - the `blake2b256` hash of the body @@ -73,7 +73,7 @@ _Session code_ provides the main logic for the transaction. It only executes if The user-defined logic of a transaction can be specified in a number of ways: - a Wasm module in binary format representing valid session code, including logic to be executed in the context of an account entity or to store Wasm in the form of a contract to be executed later. (Note that the named keys from the context of the entity the transaction is running in.) -- a 32-byte identifier representing the [hash](./serialization-standard.md#serialization-standard-hash-key) where a contract is already stored in the global state +- a 32-byte identifier representing the [hash](./serialization/types.md#hash-key-serialization-standard-hash-key) where a contract is already stored in the global state - a name corresponding to a named key, where a contract is stored under the key Payment and session code can be independently specified, so different methods of specifying them may be used (e.g. payment could be specified by a hash key, while the session is explicitly provided as a Wasm module). \ No newline at end of file diff --git a/source/docs/casper/developers/cli/sending-transactions.md b/source/docs/casper/developers/cli/sending-transactions.md index 24eb255308..dab53571a9 100644 --- a/source/docs/casper/developers/cli/sending-transactions.md +++ b/source/docs/casper/developers/cli/sending-transactions.md @@ -388,6 +388,6 @@ If your test configuration matches your production [chainspec](../../concepts/gl Please be aware that sending a deploy always requires payment. This is true regardless of the validity of included Wasm. -If the deploy failure occurs after session execution begins, the penalty payment of 2.5 CSPR is included in the gas costs of the [failed execution](../../concepts/serialization-standard.md#executionresult-executionresult). +If the deploy failure occurs after session execution begins, the penalty payment of 2.5 CSPR is included in the gas costs of the [failed execution](../../concepts/serialization/types.md#executionresultv1). However, if the failure occurs prior to session execution, the penalty payment will not appear within the gas cost of the deploy. Instead, the system automatically deducts the 2.5 CSPR from the sending account's main purse. \ No newline at end of file diff --git a/source/docs/casper/developers/dapps/sdk/index.md b/source/docs/casper/developers/dapps/sdk/index.md index 9a97e0cff1..9c8efb6f08 100644 --- a/source/docs/casper/developers/dapps/sdk/index.md +++ b/source/docs/casper/developers/dapps/sdk/index.md @@ -13,7 +13,7 @@ Each such third party is solely responsible for the SDK it provides, any warrant ## Serialization Standard -The Casper platform uses a custom serialization format. To this end, we've established a [Serialization Standard](../../../concepts/serialization-standard.md), which must be followed when building a Casper SDK. +The Casper platform uses a custom serialization format. To this end, we've established a [Serialization Standard](../../../concepts/serialization/index.md), which must be followed when building a Casper SDK. ## JSON-RPC API diff --git a/source/docs/casper/developers/dapps/signing-a-transaction.md b/source/docs/casper/developers/dapps/signing-a-transaction.md index f32258eee9..96ce2d544c 100644 --- a/source/docs/casper/developers/dapps/signing-a-transaction.md +++ b/source/docs/casper/developers/dapps/signing-a-transaction.md @@ -2,17 +2,17 @@ When creating a [`Transaction`](../../concepts/glossary/T.md#transaction) to be executed on a Casper network, the account owner, or more accurately, enough authorized signers must sign the transaction using their account's cryptographic key-pair. This key-pair is a combination of the account's secret and public keys. The signatures attached to the transaction allow the network to verify that it should be executed. -When a signature is attached to a transaction, it is paired with the public key of the signer, and referred to as an [`Approval`](../../concepts/serialization-standard.md#approval). Every valid transaction has at least one approval. +When a signature is attached to a transaction, it is paired with the public key of the signer, and referred to as an [`Approval`](../../concepts/serialization/types.md#approval). Every valid transaction has at least one approval. -The signature creation process begins with the hashing of the payment and session of the transaction to create the `BodyHash`. The `BodyHash` becomes a component of the `TransactionV1Header` as outlined in the [serialization standard](../../concepts/serialization-standard.md). From there, the `TransactionV1Header` can be hashed to create the `TransactionV1Hash`. As outlined above, the `TransactionV1Hash` is then combined with the account's key-pair to create the transaction's signature. +The signature creation process begins with the hashing of the payment and session of the transaction to create the `BodyHash`. The `BodyHash` becomes a component of the `TransactionV1Header` as outlined in the [serialization standard](../../concepts/serialization/index.md). From there, the `TransactionV1Header` can be hashed to create the `TransactionV1Hash`. As outlined above, the `TransactionV1Hash` is then combined with the account's key-pair to create the transaction's signature. As the `TransactionV1Hash` contains a hash of the transaction's body within, any variation to any aspect of the transaction or sending account's keys would render the `TransactionV1Hash` invalid. ## Public Key Cryptography -Casper networks are compatible with both `Ed25519` and `Secp256k1` public key cryptography. When [serialized](../../concepts/serialization-standard.md), public keys and signatures are prefixed with a single byte, used as a tag to denote the applicable algorithm. Ed25519 public keys and signatures are prefixed with `1`, whereas Secp256k1 are prefixed with `2`. +Casper networks are compatible with both `Ed25519` and `Secp256k1` public key cryptography. When [serialized](../../concepts/serialization/index.md), public keys and signatures are prefixed with a single byte, used as a tag to denote the applicable algorithm. Ed25519 public keys and signatures are prefixed with `1`, whereas Secp256k1 are prefixed with `2`. -Casper uses `blake2b` hashing within our [serialization](../../concepts/serialization-standard.md). However, these hashed values will be hashed once again when they are signed over. The type of hashing depends on the associated keypair algorithm as follows: +Casper uses `blake2b` hashing within our serialization. However, these hashed values will be hashed once again when they are signed over. The type of hashing depends on the associated keypair algorithm as follows: * Ed25519 signs over a SHA-512 digest. diff --git a/source/docs/casper/developers/json-rpc/types_cl.md b/source/docs/casper/developers/json-rpc/types_cl.md index 58c4bf7001..bd96529675 100644 --- a/source/docs/casper/developers/json-rpc/types_cl.md +++ b/source/docs/casper/developers/json-rpc/types_cl.md @@ -30,6 +30,6 @@ Casper types, i.e. types which can be stored and manipulated by smart contracts. A Casper value, i.e. a value which can be stored and manipulated by smart contracts. It holds the underlying data as a type-erased, serialized `Vec` and also holds the CLType of the underlying data as a separate member. The `parsed` field, representing the original value, is a convenience only available when a CLValue is encoded to JSON, and can always be set to null if preferred. -* `bytes` A Casper serialized representation of the underlying value. For more information, reference the [Serialization Standard](../../concepts/serialization-standard.md). +* `bytes` A Casper serialized representation of the underlying value. For more information, reference the [Serialization Standard](../../concepts/serialization/index.md). * [`cl_type`](#cltype) diff --git a/source/docs/casper/resources/advanced/list-auth-keys-tutorial.md b/source/docs/casper/resources/advanced/list-auth-keys-tutorial.md index a5cc3c3f7d..9b2bd06f11 100644 --- a/source/docs/casper/resources/advanced/list-auth-keys-tutorial.md +++ b/source/docs/casper/resources/advanced/list-auth-keys-tutorial.md @@ -16,7 +16,7 @@ This tutorial demonstrates retrieving and using the authorization keys associate let authorization_keys = runtime::list_authorization_keys(); ``` -Remember that authorization keys are listed under a Deploy's [approvals](../../concepts/serialization-standard.md#serialization-standard-deploy) section, which lists the signatures and the public keys of the signers, also called authorizing keys. Here is an example of a deploy's approvals: +Remember that authorization keys are listed under a Deploy's [approvals](../../concepts/serialization/structures.md#deploy-serialization-standard-deploy) section, which lists the signatures and the public keys of the signers, also called authorizing keys. Here is an example of a deploy's approvals: ```json "approvals": [ @@ -34,10 +34,10 @@ The contract code in this example retrieves the set of authorization keys for a - You meet the [development prerequisites](../../developers/prerequisites.md) and are familiar with [writing and testing on-chain code](../../developers/writing-onchain-code/index.md) - You know how to [send and verify deploys](../../developers/cli/sending-transactions.md) - You are familiar with these concepts: - - [Casper Accounts](../../concepts/serialization-standard.md#serialization-standard-account) - - [Deploys](../../concepts/serialization-standard.md#serialization-standard-deploy) - - [Associated Keys](../../concepts/serialization-standard.md#associatedkey) - - [Approvals](../../concepts/serialization-standard.md#approval), also known as authorization keys + - [Casper Accounts](../../concepts/serialization/structures.md#account-serialization-standard-account) + - [Deploys](../../concepts/serialization/structures.md#deploy-serialization-standard-deploy) + - [Associated Keys](../../concepts/serialization/types.md#associatedkey) + - [Approvals](../../concepts/serialization/types.md#approval), also known as authorization keys ## Workflow diff --git a/source/docs/casper/resources/advanced/storage-workflow.md b/source/docs/casper/resources/advanced/storage-workflow.md index 6ce6585b10..c61b9cd61a 100644 --- a/source/docs/casper/resources/advanced/storage-workflow.md +++ b/source/docs/casper/resources/advanced/storage-workflow.md @@ -14,7 +14,7 @@ Essentially, there are three means of storage within the Casper ecosystem. These ### `runtime::put_key` / `runtime::get_key` -Both the [`put_key`](https://docs.rs/casper-contract/latest/casper_contract/contract_api/runtime/fn.put_key.html) and [`get_key`](https://docs.rs/casper-contract/latest/casper_contract/contract_api/runtime/fn.get_key.html) functions refer to Casper `Key` types as outlined in both the [Understanding Hash Types](../../concepts/serialization-standard.md#serialization-standard-state-keys) and [Serialization Standard](../../concepts/serialization-standard.md#serialization-standard-state-keys). These keys are stored within a URef as a `Key` type. +Both the [`put_key`](https://docs.rs/casper-contract/latest/casper_contract/contract_api/runtime/fn.put_key.html) and [`get_key`](https://docs.rs/casper-contract/latest/casper_contract/contract_api/runtime/fn.get_key.html) functions refer to Casper `Key` types as outlined in both the [Understanding Hash Types](../../concepts/key-types.md) and [Serialization Standard](../../concepts/serialization/types.md#keys-serialization-standard-state-keys). These keys are stored within a URef as a `Key` type. ### `storage::write` / `storage::read` diff --git a/source/docs/casper/resources/changelog.md b/source/docs/casper/resources/changelog.md index dcf1e63b11..16f932af53 100644 --- a/source/docs/casper/resources/changelog.md +++ b/source/docs/casper/resources/changelog.md @@ -8,7 +8,7 @@ The following are changes introduced alongside release of the Condor network upg [Understanding Key Types](../concepts/key-types.md) - Additional Key Types and document restructuring. -[Serialization Standard](../concepts/serialization-standard.md) - Serialization information for new types. +[Serialization Standard](../concepts/serialization/index.md) - Serialization information for new types. [Smart Contracts](../concepts/smart-contracts.md) - Information on the new factory pattern feature for smart contracts. From d7d994c70a040b49837b1d6a4831a8b2617b8971 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Fri, 5 Jul 2024 12:31:10 -0400 Subject: [PATCH 2/9] Broken link. --- source/docs/casper/developers/dapps/uref-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/casper/developers/dapps/uref-security.md b/source/docs/casper/developers/dapps/uref-security.md index 592d323b9c..c276678a98 100644 --- a/source/docs/casper/developers/dapps/uref-security.md +++ b/source/docs/casper/developers/dapps/uref-security.md @@ -8,7 +8,7 @@ title: URef Access Rights An [Unforgeable Reference](/concepts/design/casper-design/#uref-head) or **URef** is a key type used for storage on a Casper network. They can store any value other than `Account` and exist as a top-level entity. As such, no individual entity may *own* a URef, they can only hold the necessary `AccessRights` to interact with a given URef. -[`AccessRights`](/concepts/serialization-standard/#clvalue-uref) determine how an entity on a Casper network may interact with a URef. They appear as a single byte suffix after the concatenation of te URef's address. As an example, the following is an example of a URef with no associated access rights: +[`AccessRights`](/concepts/serialization/primitives.md#clvalue-uref) determine how an entity on a Casper network may interact with a URef. They appear as a single byte suffix after the concatenation of te URef's address. As an example, the following is an example of a URef with no associated access rights: ```bash uref-974019c976b5f26412ce486158d2431967af35d91387dae8cbcd43c20fce6452-000 From 18c93a21457e99624397d32c3a7afe66cdb70153 Mon Sep 17 00:00:00 2001 From: bradjohnl Date: Mon, 8 Jul 2024 19:30:42 +0200 Subject: [PATCH 3/9] ci: remove hardcoded pages for testing --- .github/workflows/main.yml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 68334d8981..9edc2b39b3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -171,10 +171,6 @@ jobs: echo "Jekyll site is up..." echo "Testing if homepage responds correctly" curl --fail http://127.0.0.1:4000/ - echo "Testing if a page responds correctly" - curl --fail http://127.0.0.1:4000/operators/setup-network/chain-spec/ - echo "Testing if a page responds correctly" - curl --fail http://127.0.0.1:4000/concepts/serialization-standard/ working-directory: ./docs deploy-preview: @@ -233,14 +229,6 @@ jobs: run: | echo "Testing if homepage responds correctly" curl --fail https://$prod_pages_fqdn - - name: Test a random page - run: | - echo "Testing if a page responds correctly" - curl --fail https://$prod_pages_fqdn/operators/setup-network/chain-spec - - name: Test another random page - run: | - echo "Testing if a page responds correctly" - curl --fail https://$prod_pages_fqdn/concepts/serialization-standard rollback-if-tests-fail-prod: if: ${{ always() && (needs.system-tests-postdeployment-prod.result=='failure') }} From 69acd18c373fa52da64c8455a63969438f1cf3ec Mon Sep 17 00:00:00 2001 From: ipopescu Date: Fri, 19 Jul 2024 23:31:02 +0200 Subject: [PATCH 4/9] Fix link --- source/docs/casper/developers/cli/sending-transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/casper/developers/cli/sending-transactions.md b/source/docs/casper/developers/cli/sending-transactions.md index 977aecfc3f..5f3da2752c 100644 --- a/source/docs/casper/developers/cli/sending-transactions.md +++ b/source/docs/casper/developers/cli/sending-transactions.md @@ -1421,6 +1421,6 @@ If your test configuration matches your production [chainspec](../../concepts/gl Please be aware that sending a transaction always requires payment. This is true regardless of the validity of included Wasm. -If the transaction failure occurs after session execution begins, the penalty payment of 2.5 CSPR is included in the gas costs of the [failed execution](../../concepts/serialization-standard.md#executionresult-executionresult). +If the transaction failure occurs after session execution begins, the penalty payment of 2.5 CSPR is included in the gas costs of the [failed execution](../../concepts/serialization/types.md#executionresultv2). However, if the failure occurs prior to session execution, the penalty payment will not appear within the gas cost of the transaction. Instead, the system automatically deducts the 2.5 CSPR from the sending account's main purse. From ab9f6cae997ac5873d26936e960d94890ac5cf83 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 15 Aug 2024 10:53:29 -0400 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Iulia Popescu --- source/docs/casper/concepts/serialization/index.md | 2 +- .../casper/concepts/serialization/primitives.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/source/docs/casper/concepts/serialization/index.md b/source/docs/casper/concepts/serialization/index.md index 409c243f91..5d072838d6 100644 --- a/source/docs/casper/concepts/serialization/index.md +++ b/source/docs/casper/concepts/serialization/index.md @@ -8,4 +8,4 @@ The `Casper Binary Serialization Standard` uses a default `u8` byte tag to ident | ---- | ----------- | | [Primitives](./primitives.md) | Base-level types used to create more complex structures. | | [Structures](./structures.md) | Major structures used through Casper systems, as well as their included sub-types. | -| [Types](./types.md) | Minor types not covered `Primitives` or `Structures` | \ No newline at end of file +| [Types](./types.md) | Minor types not covered `Primitives` or `Structures`. | \ No newline at end of file diff --git a/source/docs/casper/concepts/serialization/primitives.md b/source/docs/casper/concepts/serialization/primitives.md index b529c3b1b7..7fe8909df4 100644 --- a/source/docs/casper/concepts/serialization/primitives.md +++ b/source/docs/casper/concepts/serialization/primitives.md @@ -2,7 +2,7 @@ ## `CLValue` {#clvalue} -`CLValue` is used to describe data that is used by smart contracts. This could be as a local state variable, input argument, or return value. A `CLValue` consists of two parts: a `CLType` describing the type of the value and an array of bytes representing the data in our serialization format. +`CLValue` describes data that is used by smart contracts. This could be a local state variable, input argument, or return value. A `CLValue` consists of two parts: a `CLType` describing the type of the value and an array of bytes representing the data in our serialization format. `CLType` is described by the following recursive data type: @@ -36,7 +36,7 @@ enum CLType { } ``` -All data which can be assigned a (non-`Any`) `CLType` can be serialized according to the following rules (this defines the Casper serialization format): +All data that can be assigned a (non-`Any`) `CLType` can be serialized according to the following rules, which define the Casper serialization format: ### Boolean {#clvalue-boolean} @@ -50,7 +50,7 @@ Numeric values consisting of 64 bits or less serialize in the two's complement r - E.g. `7u32` serializes as `0x07000000` - E.g. `1024u32` serializes as `0x00040000` -- Wider numeric values (i.e. `U128`, `U256`, `U512`) serialize as one byte given the length of the next number (in bytes), followed by the two's complement representation with little-endian byte order. The number of bytes should be chosen as small as possible to represent the given number. This is done to reduce the serialization size when small numbers are represented within a wide data type. +- Wider numeric values (i.e. `U128`, `U256`, `U512`) serialize as one byte given the length of the next number (in bytes), followed by the two's complement representation with little-endian byte order. The number of bytes should be chosen as small as possible to represent the given number. This reduces the serialization size when small numbers are represented within a wide data type. - E.g. `U512::from(7)` serializes as `0x0107` - E.g. `U512::from(1024)` serializes as `0x020004` @@ -62,7 +62,7 @@ Unit serializes to an empty byte array. ### String {#clvalue-string} -Strings serialize as a 32-bit integer representing the length in bytes (note: this might be different than the number of characters since special characters, such as emojis, take more than one byte), followed by the UTF-8 encoding of the characters in the string. +Strings serialize as a 32-bit integer representing the length in bytes (that might be different than the number of characters since special characters, such as emojis, take more than one byte), followed by the UTF-8 encoding of the characters in the string. - E.g. `"Hello, World!"` serializes as `0x0d00000048656c6c6f2c20576f726c6421` @@ -75,7 +75,7 @@ Optional values serialize with a single byte tag, followed by the serialization ### List {#clvalue-list} -A list of values serializes as a 32-bit integer representing the number of elements in the list (note this differs from strings where it gives the number of _bytes_), followed by the concatenation of each serialized element. +A list of values serializes as a 32-bit integer representing the number of elements in the list (differing from strings where it gives the number of _bytes_), followed by the concatenation of each serialized element. - E.g. `List()` serializes as `0x00000000` - E.g. `List(1u32, 2u32, 3u32)` serializes as `0x03000000010000000200000003000000` @@ -105,7 +105,7 @@ A `Map` serializes as a list of key-value tuples. There must be a well-defined o ### URef {#clvalue-uref} -`URef` values serialize as the concatenation of its address (which is a fixed-length list of `u8`) and a single byte tag representing the access rights. Access rights are converted as follows: +`URef` values serialize as the concatenation of their address (a fixed-length list of `u8`) and a single byte tag representing access rights, which are converted as follows: | Access Rights | Serialization | | ---------------- | ------------- | @@ -137,7 +137,7 @@ If a passed URef contains `ADD` permissions, the entity receiving the URef will ### Key {#clvalue-key} -`Key` values serialize as a single byte tag representing the variant, followed by the serialization of the data that variant contains. For most variants, this is simply a fixed-length 32-byte array. The exception is `Key::URef`, which contains a `URef`; so its data serializes per the description above. The tags are as follows: `Key::Account` serializes as `0`, `Key::Hash` as `1`, `Key::URef` as `2`. +`Key` values serialize as a single byte tag representing the variant, followed by the serialization of the data that the variant contains. For most variants, this is simply a fixed-length 32-byte array. The exception is `Key::URef`, which contains a `URef`; so its data serializes per the description above. The tags are as follows: `Key::Account` serializes as `0`, `Key::Hash` as `1`, `Key::URef` as `2`. ### CLType {#clvalue-cltype} From 2bd3261b3d85935920ec0720ea2612290b96ac88 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 15 Aug 2024 11:08:45 -0400 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Iulia Popescu --- .../docs/casper/concepts/serialization/structures.md | 8 ++++---- source/docs/casper/concepts/serialization/types.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/docs/casper/concepts/serialization/structures.md b/source/docs/casper/concepts/serialization/structures.md index 7d15ef3e6c..3032dbf0c8 100644 --- a/source/docs/casper/concepts/serialization/structures.md +++ b/source/docs/casper/concepts/serialization/structures.md @@ -59,11 +59,11 @@ Further, a block may consist of one of the following types: - `Version2`: A modern block. -### Block hash {#block-hash} +### BlockHash {#block-hash} The block hash is a `Digest` over the contents of the block Header. The `BlockHash` serializes as the byte representation of the hash itself. -### Block Header {#block-header} +### BlockHeader {#block-header} The header portion of a block, structurally, is defined as follows: @@ -248,11 +248,11 @@ A deploy is a data structure containing a smart contract and the requester's sig - `session`: The stored contract itself. - `approvals`: A list of signatures. -### Deploy-Hash {#deploy-hash} +### DeployHash {#deploy-hash} The deploy hash is a digest over the contents of the deploy header. The deploy hash serializes as the byte representation of the hash itself. -### Deploy-Header {#deploy-header} +### DeployHeader {#deploy-header} - `account`: A supported public key variant (currently either `Ed25519` or `Secp256k1`). An `Ed25519` key is serialized as a buffer of bytes, with the leading byte being `1` for `Ed25519`, with remainder of the buffer containing the byte representation of the signature. Correspondingly, a `Secp256k1` key is serialized as a buffer of bytes, with the leading byte being `2`. - `timestamp`: A timestamp is a struct that is a unary tuple containing a `u64` value. This value is a count of the milliseconds since the UNIX epoch. Thus the value `1603994401469` serializes as `0xbd3a847575010000` diff --git a/source/docs/casper/concepts/serialization/types.md b/source/docs/casper/concepts/serialization/types.md index 25f60fda66..d03961c382 100644 --- a/source/docs/casper/concepts/serialization/types.md +++ b/source/docs/casper/concepts/serialization/types.md @@ -86,7 +86,7 @@ A tag describing the type of `BalanceHoldAddr`, serializing as a single [`u8` va ## BalanceResponse {#balance-response} -`BalanceResponse` is a struct that provides the response to a balance query. It consists the following fields: +`BalanceResponse` is a struct that provides the response to a balance query. It consists of the following fields: - `total_balance`: The purse's total balance, not considering holds. It serializes as a [`U512` value](./primitives.md#clvalue-numeric). @@ -501,11 +501,11 @@ A _key_ in [Global State](../design/casper-design.md#global-state-head) is one o The one exception to note here is the identifier for [`EraInfo`](#erainfo), which actually serializes as a [`u64`](./primitives.md#clvalue-numeric) value with an additional byte for the tag. -### Account identity key {#global-state-account-key} +### Account Identity Key {#global-state-account-key} This key type is used specifically for accounts in the global state. All accounts in the system must be stored under an account identity key, and no other types. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the public key used to create the associated account (see [Accounts](../design/casper-design.md#accounts-associated-keys-weights) for more information). -### Hash key {#serialization-standard-hash-key} +### Hash Key {#serialization-standard-hash-key} This key type is used for storing contracts immutably. Once a contract is written under a hash key, that contract can never change. The 32-byte identifier representing this key is derived from the `blake2b256` hash of the deploy hash (see [block-structure-head](../design/casper-design.md#block-structure-head) for more information) concatenated with a 4-byte sequential ID. The ID begins at zero for each deploy and increments by one each time a contract is stored. The purpose of this ID is to allow each contract stored in the same deploy to have a unique key. @@ -515,7 +515,7 @@ This key type is used for storing contracts immutably. Once a contract is writte ### Transfer Key {#serialization-standard-transfer-key} -This key type is used specifically for transfers in the global state. All transfers in the system must be stored under a transfer key and no other type. The 32-byte identifier which represents this key is derived from the `blake2b256` hash of the transfer address associated with the given transfer +This key type is used specifically for transfers in the global state. All transfers in the system must be stored under a transfer key and no other type. The 32-byte identifier representing this key is derived from the `blake2b256` hash of the transfer address associated with the given transfer. ### DeployInfo Key {#serialization-standard-deploy-info-key} @@ -557,7 +557,7 @@ Given the different variants for the over-arching `Key` data-type, each of the d | `ByteCode` | 18 | | `Message` | 19 | -- `Account` serializes as a 32 byte long buffer containing the byte representation of the underlying `AccountHash` +- `Account` serializes as a 32 byte long buffer containing the byte representation of the underlying `AccountHash`. - `Hash` serializes as a 32 byte long buffer containing the byte representation of the underlying `Hash` itself. - `URef` is a tuple that contains the address of the URef and the access rights to that `URef`. The serialized representation of the `URef` is 33 bytes long. The first 32 bytes are the byte representation of the `URef` address, and the last byte contains the bits corresponding to the access rights of the `URef`. Refer to the [CLValue](./primitives.md#clvalue-clvalue) section of this chapter for details on how `AccessRights` are serialized. - `Transfer` serializes as a 32 byte long buffer containing the byte representation of the hash of the transfer. From 9b2b54aa422620296ae1d4ca03a3d290e63adde6 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 15 Aug 2024 11:22:33 -0400 Subject: [PATCH 7/9] Update structures.md --- .../concepts/serialization/structures.md | 39 ++++--------------- 1 file changed, 7 insertions(+), 32 deletions(-) diff --git a/source/docs/casper/concepts/serialization/structures.md b/source/docs/casper/concepts/serialization/structures.md index 3032dbf0c8..111e1244ec 100644 --- a/source/docs/casper/concepts/serialization/structures.md +++ b/source/docs/casper/concepts/serialization/structures.md @@ -91,6 +91,7 @@ Both `BlockHeaderV1` and `BlockHeaderV2` serialize in the same way. - `equivocators`: A vector of `PublicKey`. - `rewards`: A Binary Tree Map of `PublicKey` and `u64`. +- `inactive_validators`: A vector of `PublicKey`. When serializing an EraReport, the buffer is first filled with the individual serialization of the PublicKey contained within the vector. @@ -109,6 +110,7 @@ Note that `EraEndV1` is an optional field. Thus the above scheme only applies if - `inactive_validators`: A list of inactive validators for the era. - `next_era_validator_weights`: A map of validators and their weights for the era to follow. - `rewards`: A Binary Tree Map of `PublicKey` and `u64`. +- `next_era_gas_price`: The next era's gas price as a `u8`. Note that `EraEndV2` is an optional field. Thus the above scheme only applies if there is an `EraEndV2`; if there is no era end, the field simply serializes to _0_. @@ -262,37 +264,6 @@ The deploy hash is a digest over the contents of the deploy header. The deploy h - `dependencies`: Dependencies is a vector of deploy hashes referencing deploys that must execute before the current deploy can be executed. It serializes as a buffer containing the individual serialization of each DeployHash within the Vector. - `chain_name`: Chain name is a human-readable string describing the name of the chain as detailed in the chainspec. It is serialized as a String CLValue described below. -### Payment & Session {#payment--session} - -Payment and Session are both defined as `ExecutableDeployItems`. More information on `ExecutableDeployItems` can be found [here](../../developers/writing-onchain-code/calling-contracts.md) - -- Module Bytes are serialized such that the first byte within the serialized buffer is `0` with the rest of the buffer containing the bytes present. - - - `ModuleBytes { module_bytes: "[72 bytes]", args: 434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5 }` will serialize to - - `0x0048000000420481b0d5a665c8a7678398103d4333c684461a71e9ee2a13f6e859fb6cd419ed5f8876fc6c3e12dce4385acc777edf42dcf8d8d844bf6a704e5b2446750559911a4a328d649ddd48000000434705a38470ec2b008bb693426f47f330802f3bd63588ee275e943407649d3bab1898897ab0400d7fa09fe02ab7b7e8ea443d28069ca557e206916515a7e21d15e5be5eb46235f5` - -- StoredContractByHash serializes such that the first byte within the serialized buffer is 1u8. This is followed by the byte representation of the remaining fields. - - - `StoredContractByHash { hash: c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa4, entry_point: "pclphXwfYmCmdITj8hnh", args: d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850 }` - - `0x01c4c411864f7b717c27839e56f6f1ebe5da3f35ec0043f437324325d65a22afa41400000070636c7068587766596d436d6449546a38686e685d000000d8b59728274edd2334ea328b3292ed15eaf9134f9a00dce31a87d9050570fb0267a4002c85f3a8384d2502733b2e46f44981df85fed5e4854200bbca313e3bca8d888a84a76a1c5b1b3d236a12401a2999d3cad003c9b9d98c92ab1850` - -- StoredContractByName serializes such that the first byte within the serialized buffer is 2u8. This is followed by the individual byte representation of the remaining fields. - - - `StoredContractByName { name: "U5A74bSZH8abT8HqVaK9", entry_point: "gIetSxltnRDvMhWdxTqQ", args: 07beadc3da884faa17454a }` - - `0x0214000000553541373462535a483861625438487156614b39140000006749657453786c746e5244764d685764785471510b00000007beadc3da884faa17454a` - -- StoredVersionedContractByHash serializes such that the first byte within the serialized buffer is 3u8. However, the field version within the enum serializes as an [Option](./primitives.md#option-clvalue-option) CLValue. - - - `StoredVersionedContractByHash { hash: b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423, version: None, entry_point: "PsLz5c7JsqT8BK8ll0kF", args: 3d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8 }` - - `0x03b348fdd0d0b3f66468687df93141b5924f6bb957d5893c08b60d5a78d0b9a423001400000050734c7a3563374a73715438424b386c6c306b463b0000003d0d7f193f70740386cb78b383e2e30c4f976cf3fa834bafbda4ed9dbfeb52ce1777817e8ed8868cfac6462b7cd31028aa5a7a60066db35371a2f8` - -- StoredVersionedContractByName serializes such that the first byte within the serialized buffer is 4u8. The name and entry_point are serialized as a [String](./primitives.md#string-clvalue-string) CLValue, with the version field serializing as an [Option](./primitives.md#option-clvalue-option). - - - `StoredVersionedContractByName { name: "lWJWKdZUEudSakJzw1tn", version: Some(1632552656), entry_point: "S1cXRT3E1jyFlWBAIVQ8", args: 9975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8 }` - - `0x04140000006c574a574b645a5545756453616b4a7a7731746e01d0c64e61140000005331635852543345316a79466c57424149565138270000009975e6957ea6b07176c7d8471478fb28df9f02a61689ef58234b1a3cffaebf9f303e3ef60ae0d8` - -- Transfer serializes such that the first byte within the serialized buffer contains is 5u8, with the remaining bytes of the buffer containing the bytes contained within the args field of Transfer. - ### Approval {#approval} Approval contains two fields: @@ -300,6 +271,10 @@ Approval contains two fields: - `signer`: The public key of the approvals signer. It serializes to the byte representation of the `PublicKey`. If the `PublicKey` is an `Ed25519` key, then the first byte within the serialized buffer is 1 followed by the bytes of the key itself; else, in the case of `Secp256k1`, the first byte is 2. - `signature`: The approval signature, which serializes as the byte representation of the `Signature`. The first byte within the signature is 1 in the case of an `Ed25519` signature or 2 in the case of `Secp256k1`. +### ApprovalsHash {#approvals-hash} + +The cryptographic hash of the bytesrepr-encoded set of approvals. It serializes as a [`digest`](./types.md#digest). + ### DeployInfo {#deployinfo} Information relating to a given deploy. The structure consists of the following fields: @@ -459,4 +434,4 @@ The execution target of a transaction, serializing as a [`u8`](./primitives.md#n ### TransactionWithExecutionInfo {#transaction-with-execution-info} -A `struct` containing a`Transaction` with execution info. It serializes as a [`Transaction`](#transaction) followed by an [`Option`](./primitives.md#clvalue-option) of `ExecutionInfo`. \ No newline at end of file +A `struct` containing a`Transaction` with execution info. It serializes as a [`Transaction`](#transaction) followed by an [`Option`](./primitives.md#clvalue-option) of `ExecutionInfo`. From 6d5e5bf1d5e6ffea665592537efeaa4b4531d714 Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 15 Aug 2024 11:45:21 -0400 Subject: [PATCH 8/9] Update structures.md --- source/docs/casper/concepts/serialization/structures.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/docs/casper/concepts/serialization/structures.md b/source/docs/casper/concepts/serialization/structures.md index 111e1244ec..2c8949043e 100644 --- a/source/docs/casper/concepts/serialization/structures.md +++ b/source/docs/casper/concepts/serialization/structures.md @@ -12,7 +12,7 @@ An Account is a structure that represented a user on a legacy Casper network. Al - [`associated_keys`](./types.md#associatedkey) -- [`action_thresholds`](./types.md#action-thresholds) +- [`action_thresholds`](./types.md#account-action-thresholds) ## AddressableEntity {#addressable-entity} @@ -30,7 +30,7 @@ An Addressable Entity is a structure that represents an entity on a Casper netwo - [`associated_keys`](./types.md#associatedkey) -- [`action_thresholds`](./types.md#action-thresholds) +- [`action_thresholds`](./types.md#entity-action-thresholds) - [`message_topics`](./types.md#message-topics) From 9e70b22b42d54bd17a100f3456de2011820e8b6a Mon Sep 17 00:00:00 2001 From: Adam Stone <97986246+ACStoneCL@users.noreply.github.com> Date: Thu, 15 Aug 2024 11:49:04 -0400 Subject: [PATCH 9/9] Update types.md --- .../casper/concepts/serialization/types.md | 44 +++++++++++-------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/source/docs/casper/concepts/serialization/types.md b/source/docs/casper/concepts/serialization/types.md index d03961c382..c5dac83b5c 100644 --- a/source/docs/casper/concepts/serialization/types.md +++ b/source/docs/casper/concepts/serialization/types.md @@ -1,5 +1,13 @@ # Type Serialization +## Account Action Thresholds {#account-action-thresholds} + +The minimum weight thresholds that have to be met when executing an action of a certain type. It serializes as three consecutive [`u8` values](./primitives.md#clvalue-numeric) as follows. + +- `deployment`: The minimum weight threshold required to perform deployment actions as a `u8` value. + +- `key_management`: The minimum weight threshold required to perform key management actions as a `u8` value. + ## Account Config {#account-config} Configuration of an individual account in *accounts.toml*, containing the account's public key, main purse balance and validator config. @@ -22,16 +30,6 @@ Identifier for possible ways to retrieve an Account. It can consist of any of th - [`AccountHash`](#account-hash): The `blake2b` hash of the account's public key. -## Action Thresholds {#action-thresholds} - -The minimum weight thresholds that have to be met when executing an action of a certain type. It serializes as three consecutive [`u8` values](./primitives.md#clvalue-numeric) as follows. - -- `deployment`: The minimum weight threshold required to perform deployment actions as a `u8` value. - -- `upgrade_management`: The minimum weight threshold required to perform upgrade management actions as a `u8` value. - -- `key_management`: The minimum weight threshold required to perform key management actions as a `u8` value. - ## Activation Point {#activation-point} The first era to which the associated protocol version applies. It serializes as a single [`u8`](./primitives.md#clvalue-numeric) tag indicating if the era in question is genesis. If it is the genesis era, the following bytes will be a `timestamp`. If not, the bytes represent an `era_id`. @@ -284,6 +282,16 @@ Disabled contract versions, containing the following: A log of all transforms produced during execution, serialized as a vector of [transforms](#transformv2). +## Entity Action Thresholds {#entity-action-thresholds} + +The minimum weight thresholds that have to be met when executing an action of a certain type. It serializes as three consecutive [`u8` values](./primitives.md#clvalue-numeric) as follows. + +- `deployment`: The minimum weight threshold required to perform deployment actions as a `u8` value. + +- `upgrade_management`: The minimum weight threshold required to perform upgrade management actions as a `u8` value. + +- `key_management`: The minimum weight threshold required to perform key management actions as a `u8` value. + ## EntityAddr {#entity-addr} The address for an `AddressableEntity`. It serializes as a `u8` [`EntityKindTag`](#entity-kind-tag) followed by the 32-byte buffer containing the bytes of the `hash_addr` as follows: @@ -442,29 +450,29 @@ The result of a successful execution. ## ExecutionResultV2 {#executionresultv2} -The result of a single deploy. It serializes as a `u8` tag indicating either `Failure` as a 0 or `Success` as a 1. This is followed by the appropriate structure below: +The result of a single transaction. It serializes as a `u8` tag indicating either `Failure` as a 0 or `Success` as a 1. This is followed by the appropriate structure below: ### `Failure` The result of a failed execution. -- `effects`: The [effect](#effects) of executing the deploy. +- `effects`: The [effect](#effects) of executing the transaction. -- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). +- `transfers`: A record of transfers performed while executing the transaction, serialized as a [`List`](./primitives.md#clvalue-list). -- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. +- `cost`: The cost of executing the transaction, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. -- `error_message`: The error message associated with executing the deploy, serialized as a [`String`](./primitives.md#clvalue-string). +- `error_message`: The error message associated with executing the transaction, serialized as a [`String`](./primitives.md#clvalue-string). ### `Success` The result of a successful execution. -- `effects`: The [effects](#effects) of executing the deploy. +- `effects`: The [effects](#effects) of executing the transaction. -- `transfers`: A record of transfers performed while executing the deploy, serialized as a [`List`](./primitives.md#clvalue-list). +- `transfers`: A record of transfers performed while executing the transaction, serialized as a [`List`](./primitives.md#clvalue-list). -- `cost`: The cost of executing the deploy, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. +- `cost`: The cost of executing the transaction, serializes as a [`U512`](./primitives.md#clvalue-numeric) value. ## Gas {#gas}