diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 8f3f00d727..5dbeb1a5a8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -6,7 +6,8 @@ env: on: push: - branches: "*" + branches: + - dev pull_request: types: [ opened, reopened, synchronize ] diff --git a/config/sidebar.config.js b/config/sidebar.config.js index 42ecb1c065..40ab19a4e4 100644 --- a/config/sidebar.config.js +++ b/config/sidebar.config.js @@ -110,6 +110,7 @@ module.exports = { "developers/writing-onchain-code/contract-vs-session", "developers/writing-onchain-code/writing-session-code", "developers/writing-onchain-code/testing-session-code", + "developers/writing-onchain-code/contract-hash-vs-package-hash", "developers/writing-onchain-code/best-practices", ], }, @@ -225,6 +226,7 @@ module.exports = { "operators/setup/basic-node-configuration", "operators/setup/node-endpoints", "operators/setup/install-node", + "operators/setup/fast-sync", "operators/setup/open-files", "operators/setup/upgrade", "operators/setup/joining", @@ -297,6 +299,7 @@ module.exports = { resources: [ "resources/index", "resources/build-on-casper", + "resources/moving-to-casper", "resources/casper-open-source-software", "resources/quick-start", //"resources/sample-projects", // NEW CONTENT WILL BE HERE diff --git a/source/docs/casper/concepts/design/casper-design.md b/source/docs/casper/concepts/design/casper-design.md index 7eafd949f0..2b42fe1d82 100644 --- a/source/docs/casper/concepts/design/casper-design.md +++ b/source/docs/casper/concepts/design/casper-design.md @@ -259,7 +259,7 @@ The Casper *mint* is a system contract that manages the balance of *motes* withi The `AccessRights` of the URefs permissions model determines what actions can be performed when using a `URef` associated with a purse. -As all URef`s are unforgeable, the only way to interact with a purse is for a `URef` with appropriate `AccessRights` to be validly given to the current context. +As all `URef`s are unforgeable, the only way to interact with a purse is for a `URef` with appropriate `AccessRights` to be validly given to the current context. The basic global state options map onto more standard monetary operations according to the table below: diff --git a/source/docs/casper/concepts/hash-types.md b/source/docs/casper/concepts/hash-types.md index 4613716c11..79ee6257bf 100644 --- a/source/docs/casper/concepts/hash-types.md +++ b/source/docs/casper/concepts/hash-types.md @@ -34,7 +34,7 @@ For the sake of user convenience and compatibility, we expect the delivery of ha ## Hash and Key Explanations {#hash-and-key-explanations} -`PublicKey` is a 32 byte asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. +`PublicKey` is a 32 byte asymmetric public key, preceded by a one-byte prefix that tells whether the key is `ed25519` or `secp256k1`. There is a third type of `PublicKey` that refers to the system and it is a single `00`. `AccountHash` is a 32 byte hash of the `PublicKey` serving to identify user accounts. diff --git a/source/docs/casper/concepts/serialization-standard.md b/source/docs/casper/concepts/serialization-standard.md index e44c404ce1..a526046238 100644 --- a/source/docs/casper/concepts/serialization-standard.md +++ b/source/docs/casper/concepts/serialization-standard.md @@ -745,6 +745,7 @@ A `Map` serializes as a list of key-value tuples. There must be a well-defined o `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. diff --git a/source/docs/casper/developers/cli/calling-contracts.md b/source/docs/casper/developers/cli/calling-contracts.md index 144a48843e..c8efd84544 100644 --- a/source/docs/casper/developers/cli/calling-contracts.md +++ b/source/docs/casper/developers/cli/calling-contracts.md @@ -68,7 +68,7 @@ The payment amount varies based on each deploy and network [chainspec](../../con The following sample response contains a `deploy_hash`, needed to verify the changes in global state, as described [here](./installing-contracts.md#querying-global-state).
-Sample response +Sample response ```rust { diff --git a/source/docs/casper/developers/cli/installing-contracts.md b/source/docs/casper/developers/cli/installing-contracts.md index 1f4dcf75fc..13fee67ab1 100644 --- a/source/docs/casper/developers/cli/installing-contracts.md +++ b/source/docs/casper/developers/cli/installing-contracts.md @@ -123,7 +123,7 @@ casper-client query-global-state \ Here is how your account state would look. Notice that the sample response contains several named keys, including "counter", "counter_package_name", and "version". You can use these values to query the contract state further, as shown in the next example.
-Sample account state +Sample account state ```bash { @@ -197,7 +197,7 @@ casper-client query-global-state \ Here is how the sample contract would look and would contain details such as the `contract_package_hash`, the contract `entry_points`, and the `named_keys` for the contract.
-Sample contract state +Sample contract state ```bash { @@ -257,7 +257,7 @@ casper-client query-global-state \ ```
-Sample stored value +Sample stored value ```bash { @@ -308,7 +308,7 @@ casper-client query-global-state \ Here is how the contract package details would look. The response would contain the `contract_hash`, which you would need to [call a contract by hash](./calling-contracts.md#calling-contracts-by-hash) in the next section. You would also see the `access_key` for the `ContractPackage` and the current `contract_version`.
-Sample contract package state +Sample contract package state ```bash { diff --git a/source/docs/casper/developers/cli/querying-global-state.md b/source/docs/casper/developers/cli/querying-global-state.md index d8df350da1..73f21320c7 100644 --- a/source/docs/casper/developers/cli/querying-global-state.md +++ b/source/docs/casper/developers/cli/querying-global-state.md @@ -60,7 +60,7 @@ casper-client query-global-state \ Here is how your account state would look. Notice that the sample response contains several named keys, including "counter", "counter_package_name", and "version". You can use these values to query the contract state further, as shown in the next example.
-Sample account state +Sample account state ```bash { @@ -134,7 +134,7 @@ casper-client query-global-state \ Here is how the sample contract would look and would contain details such as the `contract_package_hash`, the contract `entry_points`, and the `named_keys` for the contract.
-Sample contract state +Sample contract state ```bash { @@ -194,7 +194,7 @@ casper-client query-global-state \ ```
-Sample stored value +Sample stored value ```bash { @@ -245,7 +245,7 @@ casper-client query-global-state \ Here is how the contract package details would look. The response would contain the `contract_hash`, which you would need to [call a contract by hash](./calling-contracts.md#calling-contracts-by-hash) in the next section. You would also see the `access_key` for the `ContractPackage` and the current `contract_version`.
-Sample contract package state +Sample contract package state ```bash { diff --git a/source/docs/casper/developers/cli/transfers/direct-token-transfer.md b/source/docs/casper/developers/cli/transfers/direct-token-transfer.md index 09cff009f9..5247f64a02 100644 --- a/source/docs/casper/developers/cli/transfers/direct-token-transfer.md +++ b/source/docs/casper/developers/cli/transfers/direct-token-transfer.md @@ -2,60 +2,72 @@ This workflow describes how to use the Casper command-line client to transfer tokens between purses on a Casper network. +## Prerequisites + This workflow assumes: -1. You meet the [prerequisites](../../prerequisites.md) +1. You meet the general [development prerequisites](../../prerequisites.md) 2. You are using the Casper command-line client -3. You have a target *public key* hex the path to the source *secret key* -4. You have a valid *node-address* -5. You must be able to sign a deploy for the source account +3. You have a target *public key* +4. You have a valid *node address* +5. You must be able to sign a deploy for the source account using the source *secret key* -## Transfer {#transfer} +## Direct Transfer Example {#transfer} -The `transfer` command allows you to move CSPR from one account's purse to another as denominated in [Motes](../../../concepts/design/casper-design.md#tokens-divisibility). A _Mote_ is a denomination of the cryptocurrency CSPR, where 1 CSPR = 1,000,000,000 Motes. +The following `transfer` command allows you to move CSPR from one account's purse to another as denominated in [Motes](../../../concepts/design/casper-design.md#tokens-divisibility). A _Mote_ is a denomination of the cryptocurrency CSPR, where 1 CSPR = 1,000,000,000 Motes. For transfers of at least 2.5 CSPR (2,500,000,000 Motes) from a single sender to a single recipient on a Casper network, the most efficient option is to use the direct transfer capability. -**Direct transfer example**: - ```bash casper-client transfer \ ---id 1 \ ---transfer-id 123456789012345 \ ---node-address http://:7777 \ ---amount \ ---secret-key .pem \ ---chain-name casper \ ---target-account \ ---payment-amount +--id \ +--transfer-id \ +--node-address [NODE_SERVER_ADDRESS] \ +--amount [AMOUNT_TO_TRANSFER] \ +--secret-key [KEY_PATH]/secret_key.pem \ +--chain-name [CHAIN_NAME] \ +--target-account [TARGET_PUBLIC_KEY_HEX] \ +--payment-amount [PAYMENT_AMOUNT_IN_MOTES] ``` **Request fields:** - `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned - - `transfer-id` -<64-BIT INTEGER> The `transfer-id` is a memo field, providing additional information about the recipient, which is necessary when transferring tokens to some recipients. For example, if depositing tokens into an account's purse where off-chain management keeps track of individual sub-balances, it is necessary to provide a memo ID uniquely identifying the actual recipient. If this is not necessary for a given recipient, you may pass `0` or some `u64` value that is meaningful to you - - `node-address` - Hostname or IP and port of a node on a network bound to a JSON-RPC endpoint \[default:\] - - `amount` -<512-BIT INTEGER> The number of motes to transfer (1 CSPR = 1,000,000,000 `Motes`) - - `secret-key` - Path to secret key file - - `chain-name` - Name of the chain, to avoid the deploy from being accidentally or maliciously included in a different chain - - The _chain-name_ for testnet is **casper-test** - - The _chain-name_ for mainnet is **casper** - -- `target-account` - Hex-encoded public key of the account from which the main purse will be used as the target + - The _chain-name_ for Testnet is **casper-test** + - The _chain-name_ for Mainnet is **casper** +- `target-account` - Hex-encoded public key of the account that will receive the funds in its main purse - `payment-amount` - The payment for the transfer in motes. The payment amount varies based on each deploy and network [chainspec](../../../concepts/glossary/C.md#chainspec). For Testnet node version [1.5.1](https://github.com/casper-network/casper-node/blob/release-1.5.1/resources/production/chainspec.toml), you can specify 10^8 motes **Important response fields:** -- `"result"."deploy_hash"` - the address of the executed transfer, needed to look up additional information about the transfer +- `"result"."deploy_hash"` - The address of the deploy, needed to look up additional information about the transfer + +:::note + +Save the returned _deploy_hash_ from the output to query information about the transfer deploy later. + +::: -**Note**: Save the returned _deploy_hash_ from the output to query information about the transfer deploy later. +**Example Transfer:** + +```bash +casper-client transfer -v \ +--id 3 \ +--transfer-id 11102023 \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--amount 5000000000 \ +--secret-key ~/KEYS/secret_key.pem \ +--chain-name casper-test \ +--target-account 01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986 \ +--payment-amount 100000000 +```
Explore the JSON-RPC request and response generated. @@ -64,78 +76,76 @@ casper-client transfer \ ```json { - "id": 1, - "jsonrpc": "2.0", - "method": "account_put_deploy", - "params": { - "deploy": { - "approvals": [ - { - "signature": "130 chars", - "signer": "010f50b0116f213ef65b99d1bd54483f92bf6131de2f8aceb7e3f825a838292150" - } + "jsonrpc": "2.0", + "method": "account_put_deploy", + "params": { + "deploy": { + "hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", + "header": { + "account": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "timestamp": "2023-10-12T14:59:40.760Z", + "ttl": "30m", + "gas_price": 1, + "body_hash": "ea7e6a6cbdd4d761827cb627e162896bee3e771beda000550615c9b4fafa3a2d", + "dependencies": [], + "chain_name": "casper-test" + }, + "payment": { + "ModuleBytes": { + "module_bytes": "", + "args": [ + [ + "amount", + { + "cl_type": "U512", + "bytes": "0400e1f505", + "parsed": "100000000" + } + ] + ] + } + }, + "session": { + "Transfer": { + "args": [ + [ + "amount", + { + "cl_type": "U512", + "bytes": "0500f2052a01", + "parsed": "5000000000" + } ], - "hash": "ec2d477a532e00b08cfa9447b7841a645a27d34ee12ec55318263617e5740713", - "header": { - "account": "010f50b0116f213ef65b99d1bd54483f92bf6131de2f8aceb7e3f825a838292150", - "body_hash": "da35b095640a403324306c59ac6f18a446dfcc28faf753ce58b96b635587dd8e", - "chain_name": "casper-net-1", - "dependencies": [], - "gas_price": 1, - "timestamp": "2021-04-20T18:04:40.333Z", - "ttl": "1h" - }, - "payment": { - "ModuleBytes": { - "args": [ - [ - "amount", - { - "bytes": "021027", - "cl_type": "U512", - "parsed": "10000" - } - ] - ], - "module_bytes": "" - } - }, - "session": { - "Transfer": { - "args": [ - [ - "amount", - { - "bytes": "0400f90295", - "cl_type": "U512", - "parsed": "2500000000" - } - ], - [ - "target", - { - "bytes": "8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668", - "cl_type": { - "ByteArray": 32 - }, - "parsed": "8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668" - } - ], - [ - "id", - { - "bytes": "00", - "cl_type": { - "Option": "U64" - }, - "parsed": null - } - ] - ] - } - } + [ + "target", + { + "cl_type": "PublicKey", + "bytes": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", + "parsed": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986" + } + ], + [ + "id", + { + "cl_type": { + "Option": "U64" + }, + "bytes": "014767a90000000000", + "parsed": 11102023 + } + ] + ] + } + }, + "approvals": [ + { + "signer": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "signature": "01e53cb742ed13ff4f0584a3da0f22f5942a33e010965adf640c91204ae4bc7436f1e5534d338ffa117d193295214816445439781229d24a372085c316eac5e305" } + ] } + }, + "id": 3 } ``` @@ -143,29 +153,44 @@ casper-client transfer \ ```json { - "id": 1, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "deploy_hash": "ec2d477a532e00b08cfa9447b7841a645a27d34ee12ec55318263617e5740713" - } + "jsonrpc": "2.0", + "id": 3, + "result": { + "api_version": "1.5.3", + "deploy_hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c" + } } ```
-### Deploy Status {#deploy-status} +## Verifying the Deploy {#verify-deploy} A transfer on a Casper network is only executed after it has been included in a finalized block. -Refer to the Section on [querying deploys](../../../resources/beginner/querying-network.md#querying-deploys) within the network to check the execution status of the transfer. +```bash +casper-client get-deploy +--node-address [NODE_SERVER_ADDRESS] [DEPLOY_HASH] +``` **Important response fields:** - `"result"."execution_results"[0]."transfers[0]"` - the address of the executed transfer that the source account initiated. We will use it to look up additional information about the transfer -- `"result"."execution_results"[0]."block_hash"` - contains the block hash of the block that included our transfer. We will require the _state_root_hash_ of this block to look up information about the accounts and their purse balances +- `"result"."execution_results"[0]."block_hash"` - contains the block hash of the block that included the transfer. We will require the _state_root_hash_ of this block to look up information about the accounts and their purse balances + +:::note + +Transfer addresses use a `transfer-` string prefix. + +::: + +**Example Query:** -**Note**: Transfer addresses use a `transfer-` string prefix. +```bash +casper-client get-deploy +--node-address https://rpc.testnet.casperlabs.io +1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c +```
Explore the JSON-RPC request and response generated. @@ -174,12 +199,13 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- ```json { - "id": 2, - "jsonrpc": "2.0", - "method": "info_get_deploy", - "params": { - "deploy_hash": "ec2d477a532e00b08cfa9447b7841a645a27d34ee12ec55318263617e5740713" - } + "jsonrpc": "2.0", + "method": "info_get_deploy", + "params": { + "deploy_hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", + "finalized_approvals": false + }, + "id": -3447643973713335073 } ``` @@ -187,40 +213,33 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- ```json { - "id": 6054990863558097019, "jsonrpc": "2.0", "result": { - "api_version": "1.4.6", + "api_version": "1.5.3", "deploy": { - "approvals": [ - { - "signature": "01c8c1704a2c921988cd546fe85d249f27bc9da198e8c2f79d91e19a40e015e59a099723b5540c20c57a1ebffef2e4d2e333d9e52f1f27fef9d6b9a4ec5080b40a", - "signer": "01ea8ff63a2b3bcf42c3e8e057959d864043fb989082ddc54464ef9a2ea7338ba0" - } - ], - "hash": "d5862af0c7d06df6cb265c2dee9a014ce570a8db75eb0689f14d819c632c305d", + "hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", "header": { - "account": "01ea8ff63a2b3bcf42c3e8e057959d864043fb989082ddc54464ef9a2ea7338ba0", - "body_hash": "9ccc49a951b9b783bbb20746007e221e8326fbbb48f002aaa40d664abf35995d", - "chain_name": "casper-test", - "dependencies": [], + "account": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "timestamp": "2023-10-12T14:59:40.760Z", + "ttl": "30m", "gas_price": 1, - "timestamp": "2022-07-05T22:39:20.190Z", - "ttl": "30m" + "body_hash": "ea7e6a6cbdd4d761827cb627e162896bee3e771beda000550615c9b4fafa3a2d", + "dependencies": [], + "chain_name": "casper-test" }, "payment": { "ModuleBytes": { + "module_bytes": "", "args": [ [ "amount", { - "bytes": "0400e1f505", "cl_type": "U512", + "bytes": "0400e1f505", "parsed": "100000000" } ] - ], - "module_bytes": "" + ] } }, "session": { @@ -229,48 +248,61 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- [ "amount", { - "bytes": "0400f90295", "cl_type": "U512", - "parsed": "2500000000" + "bytes": "0500f2052a01", + "parsed": "5000000000" } ], [ "target", { - "bytes": "0203343d88a5dd8a67ab8c9d572c50c7f4604960d78f8a41ea48b98d3dcec6316834", "cl_type": "PublicKey", - "parsed": "0203343d88a5dd8a67ab8c9d572c50c7f4604960d78f8a41ea48b98d3dcec6316834" + "bytes": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", + "parsed": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986" } ], [ "id", { - "bytes": "01e6c6720000000000", "cl_type": { "Option": "U64" }, - "parsed": 7522022 + "bytes": "014767a90000000000", + "parsed": 11102023 } ] ] } - } + }, + "approvals": [ + { + "signer": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "signature": "01e53cb742ed13ff4f0584a3da0f22f5942a33e010965adf640c91204ae4bc7436f1e5534d338ffa117d193295214816445439781229d24a372085c316eac5e305" + } + ] }, "execution_results": [ { - "block_hash": "b357fc78f105e43be66f268bb8d7308f357fe37e0e55d92d26f8e255c9292529", + "block_hash": "aac51dad028ba8b3d6fec86a39252bbc4285d513fd57a8af4696ab5390ac5c2b", "result": { "Success": { - "cost": "100000000", "effect": { "operations": [], "transforms": [ { - "key": "account-hash-aff4921ce6f73072a914f04e7327a946b72ec4562a7d99f107e9411d1592c3f6", + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, + { + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", "transform": "Identity" }, { - "key": "account-hash-aff4921ce6f73072a914f04e7327a946b72ec4562a7d99f107e9411d1592c3f6", + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "transform": "Identity" + }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", "transform": "Identity" }, { @@ -281,6 +313,14 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "key": "hash-624dbe2395b9d9503fbee82162f1714ebff6b639f96d2084d26d944c354ec4c5", "transform": "Identity" }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, + { + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, { "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", "transform": "Identity" @@ -290,7 +330,11 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, + { + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": "Identity" }, { @@ -298,12 +342,12 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": { "WriteCLValue": { - "bytes": "0500a7d0dd2c", "cl_type": "U512", - "parsed": "192700000000" + "bytes": "06621c3e660301", + "parsed": "1114111876194" } } }, @@ -314,11 +358,19 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- } }, { - "key": "account-hash-aff4921ce6f73072a914f04e7327a946b72ec4562a7d99f107e9411d1592c3f6", + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, + { + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", "transform": "Identity" }, { - "key": "account-hash-aff4921ce6f73072a914f04e7327a946b72ec4562a7d99f107e9411d1592c3f6", + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "transform": "Identity" + }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", "transform": "Identity" }, { @@ -329,6 +381,14 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "key": "hash-624dbe2395b9d9503fbee82162f1714ebff6b639f96d2084d26d944c354ec4c5", "transform": "Identity" }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, + { + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, { "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", "transform": "Identity" @@ -338,7 +398,11 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, + { + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": "Identity" }, { @@ -346,12 +410,12 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": { "WriteCLValue": { - "bytes": "0500a7d0dd2c", "cl_type": "U512", - "parsed": "192700000000" + "bytes": "06621c3e660301", + "parsed": "1114111876194" } } }, @@ -365,60 +429,68 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", "transform": "Identity" }, + { + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, { "key": "hash-9824d60dc3a5c44a20b9fd260a412437933835b52fc683d8ae36e4ec2114843e", "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, + { + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": "Identity" }, { - "key": "balance-be85882962304905286b2b4d3602f7f287095536ef4ce3e9a5360930c729ec2c", + "key": "balance-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c", "transform": "Identity" }, { - "key": "balance-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4", + "key": "balance-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1", "transform": { "WriteCLValue": { - "bytes": "0500aecd482c", "cl_type": "U512", - "parsed": "190200000000" + "bytes": "06622a383c0201", + "parsed": "1109111876194" } } }, { - "key": "balance-be85882962304905286b2b4d3602f7f287095536ef4ce3e9a5360930c729ec2c", + "key": "balance-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c", "transform": { - "AddUInt512": "2500000000" + "AddUInt512": "5000000000" } }, { - "key": "transfer-86760957e94a46839bcd03bee35c9db6b8a906e6fbfe87e69e93383df3d41b2a", + "key": "transfer-0de7250864e67aa76626a844dcc931e615284a13a110df3f97cec9e3e97af405", "transform": { "WriteTransfer": { - "amount": "2500000000", - "deploy_hash": "d5862af0c7d06df6cb265c2dee9a014ce570a8db75eb0689f14d819c632c305d", - "from": "account-hash-9aed70924116013bdd5517109bea97678d9cff449640457a8a4ed3e561d864d4", + "deploy_hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", + "from": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "to": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "source": "uref-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1-007", + "target": "uref-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c-004", + "amount": "5000000000", "gas": "0", - "id": 7522022, - "source": "uref-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4-007", - "target": "uref-be85882962304905286b2b4d3602f7f287095536ef4ce3e9a5360930c729ec2c-004", - "to": "account-hash-aff4921ce6f73072a914f04e7327a946b72ec4562a7d99f107e9411d1592c3f6" + "id": 11102023 } } }, { - "key": "deploy-d5862af0c7d06df6cb265c2dee9a014ce570a8db75eb0689f14d819c632c305d", + "key": "deploy-1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", "transform": { "WriteDeployInfo": { - "deploy_hash": "d5862af0c7d06df6cb265c2dee9a014ce570a8db75eb0689f14d819c632c305d", - "from": "account-hash-9aed70924116013bdd5517109bea97678d9cff449640457a8a4ed3e561d864d4", - "gas": "100000000", - "source": "uref-20c3a137051eaa98efa048fd8f888ed4b342bcc1c8166f475e25b6a627d669a4-007", + "deploy_hash": "1f17a0bdeaaf71abd03492c854cdf97f746432751721ce555e95b9cefe641e3c", "transfers": [ - "transfer-86760957e94a46839bcd03bee35c9db6b8a906e6fbfe87e69e93383df3d41b2a" - ] + "transfer-0de7250864e67aa76626a844dcc931e615284a13a110df3f97cec9e3e97af405" + ], + "from": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "source": "uref-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1-007", + "gas": "100000000" } } }, @@ -426,10 +498,18 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", "transform": "Identity" }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, { "key": "hash-624dbe2395b9d9503fbee82162f1714ebff6b639f96d2084d26d944c354ec4c5", "transform": "Identity" }, + { + "key": "hash-8cf5e4acf51f54eb59291599187838dc3bc234089c46fc6ca8ad17e762ae4401", + "transform": "Identity" + }, { "key": "balance-98d945f5324f865243b7c02c0417ab6eac361c5c56602fd42ced834a1ba201b6", "transform": "Identity" @@ -446,26 +526,30 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- "key": "hash-9824d60dc3a5c44a20b9fd260a412437933835b52fc683d8ae36e4ec2114843e", "transform": "Identity" }, + { + "key": "hash-010c3fe81b7b862e50c77ef9a958a05bfa98444f26f96f23d37a13c96244cfb7", + "transform": "Identity" + }, { "key": "balance-98d945f5324f865243b7c02c0417ab6eac361c5c56602fd42ced834a1ba201b6", "transform": "Identity" }, { - "key": "balance-874289dbe721508e8d2893efd86364ea1ca67a6a2456825259efd6db8efb427c", + "key": "balance-da632bfba17f4a7882581de2a37219be71628600ccd0df83f1d42465bd018537", "transform": "Identity" }, { "key": "balance-98d945f5324f865243b7c02c0417ab6eac361c5c56602fd42ced834a1ba201b6", "transform": { "WriteCLValue": { - "bytes": "00", "cl_type": "U512", + "bytes": "00", "parsed": "0" } } }, { - "key": "balance-874289dbe721508e8d2893efd86364ea1ca67a6a2456825259efd6db8efb427c", + "key": "balance-da632bfba17f4a7882581de2a37219be71628600ccd0df83f1d42465bd018537", "transform": { "AddUInt512": "100000000" } @@ -473,14 +557,22 @@ Refer to the Section on [querying deploys](../../../resources/beginner/querying- ] }, "transfers": [ - "transfer-86760957e94a46839bcd03bee35c9db6b8a906e6fbfe87e69e93383df3d41b2a" - ] + "transfer-0de7250864e67aa76626a844dcc931e615284a13a110df3f97cec9e3e97af405" + ], + "cost": "100000000" } } } ] - } + }, + "id": -3447643973713335073 } ```
+ +Refer to the Section on [querying deploys](../../../resources/beginner/querying-network.md#querying-deploys) for more information. + +## Verifying the Transfer + +In addition to verifying the deploy, you also need to [verify the transfer details](./verify-transfer.md). The deploy may have been successful, but you also need to ensure the source and target accounts were updated correctly. \ No newline at end of file diff --git a/source/docs/casper/developers/cli/transfers/multisig-deploy-transfer.md b/source/docs/casper/developers/cli/transfers/multisig-deploy-transfer.md index 130dbb354a..ad4a11a592 100644 --- a/source/docs/casper/developers/cli/transfers/multisig-deploy-transfer.md +++ b/source/docs/casper/developers/cli/transfers/multisig-deploy-transfer.md @@ -1,8 +1,10 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; -# Transferring Tokens using a Multi-sig Deploy +# Transferring Tokens using a Multi-Sig Deploy -This topic explores using a deploy file to transfer Casper tokens (CSPR) between purses on a Casper network. This method of transferring tokens is recommended when you want to implement multi-signature deploys. The `make-transfer` command allows you to create a transfer Deploy and save the output to a file. You can then have the Deploy signed by other parties using the `sign-deploy` command and send it to the network for execution using the `send-deploy` command. +This page presents a method of transferring tokens via a deploy file using multiple signatures. This method is recommended when implementing multi-signature transfers between purses on a Casper network. + +The `make-transfer` command allows you to create a transfer and save the output to a file. You can then have the transfer signed by other parties using the `sign-deploy` command and send it to the network for execution using the `send-deploy` command. ## Prerequisites @@ -16,15 +18,15 @@ You must ensure the following prerequisites are met. 3. Get the path of the source account's _secret key_ file 4. Get the target account's _public key_ in hex format -## Token Transfer Workflow with the Casper Client {#token-transfer-workflow} +## Token Transfer Workflow {#token-transfer-workflow} The high-level flow to transfer tokens using the Casper CLI client and a deploy file is described in the following steps: 1. The `make-transfer` command creates and signs a transfer, saving the output to a file -2. The `sign-transfer` command adds additional signatures for a multi-signature transfer +2. The `sign-deploy` command adds additional signatures for a multi-signature transfer 3. The `send-deploy` command sends the deploy containing the transfer to the network -Deployment flow +Deployment flow ### Creating the transfer {#creating-the-transfer} @@ -35,7 +37,7 @@ casper-client make-transfer --amount 2500000000 \ --secret-key [PATH]/secret_key.pem \ --chain-name casper-test \ --target-account [PUBLIC_KEY_HEX] \ ---transfer-id 3 \ +--transfer-id [ID] \ --payment-amount 100000000 \ --output transfer.deploy ``` @@ -51,20 +53,32 @@ The following table explains the parameters used in the `make-transfer` command. | transfer-id | A user-defined identifier permanently associated with the transfer | | payment-amount | The payment for the transfer in motes. The payment amount varies based on the deploy and network [chainspec](../../../concepts/glossary/C.md#chainspec). For Testnet node version [1.5.1](https://github.com/casper-network/casper-node/blob/release-1.5.1/resources/production/chainspec.toml), wasmless transfers cost 10^8 motes | -In the output, you will see a section named **approvals**. This is where a signature from the source account is added to the Deploy. +In the output, you will see a section named **approvals**. This is where a signature from the source account is added to the deploy. + +**Example:** + +```bash +casper-client make-transfer --amount 2500000000 \ +--secret-key ~/KEYS/multi-sig/keys/default_secret_key.pem \ +--chain-name casper-test \ +--target-account 0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf \ +--transfer-id 1 \ +--payment-amount 100000000 \ +--output transfer.deploy +```
Sample output of the make-transfer command ```json { - "hash": "0e17da4c7b6d12984910aa25e397fc85db53e5cd896776d47494cb4a5f2083f1", + "hash": "88c49fa9108485397a330f294914a6c2d614c581fbe0a31de1a954baad6d709b", "header": { - "account": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", - "timestamp": "2023-01-05T11:30:05.269Z", + "account": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", + "timestamp": "2023-10-12T19:14:22.080Z", "ttl": "30m", "gas_price": 1, - "body_hash": "5d7d30965d503dba0459d5e6b3a0c923059f89e6a7179f76aec0fda1263b7819", + "body_hash": "1bb7436d4703816b5cbeef245dd83c0520f1c7173cdf609c664a29487cc5de1c", "dependencies": [], "chain_name": "casper-test" }, @@ -76,8 +90,8 @@ In the output, you will see a section named **approvals**. This is where a signa "amount", { "cl_type": "U512", - "bytes": "021027", - "parsed": "10000" + "bytes": "0400e1f505", + "parsed": "100000000" } ] ] @@ -98,8 +112,8 @@ In the output, you will see a section named **approvals**. This is where a signa "target", { "cl_type": "PublicKey", - "bytes": "01f48f5b095518be188286d896921d33e97f9729f5945237d5ff6cf7b077aabf1f", - "parsed": "01f48f5b095518be188286d896921d33e97f9729f5945237d5ff6cf7b077aabf1f" + "bytes": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "parsed": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf" } ], [ @@ -108,8 +122,8 @@ In the output, you will see a section named **approvals**. This is where a signa "cl_type": { "Option": "U64" }, - "bytes": "013930000000000000", - "parsed": 3 + "bytes": "010100000000000000", + "parsed": 1 } ] ] @@ -117,8 +131,8 @@ In the output, you will see a section named **approvals**. This is where a signa }, "approvals": [ { - "signer": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", - "signature": "016853b69b98434f236ac2eacb053b244f5853f0ec2a1d86b8f8a35601353cebe160f3c57606be9f289da34b7ccd5b7285751d1e6edc9cc76a84c14fb286272702" + "signer": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", + "signature": "015e0db50b174f3627e0e27cb503f0836b30bd0e0f2c4b989366b0df57500a1cb2b0945408c938bc3c33c40dab59a9c6af6f4e01e474330cd27262bfc87680030e" } ] } @@ -143,6 +157,15 @@ casper-client sign-deploy \ | secret-key | The path of the secret key file used to sign the deploy | | output | The path of the output file used to save the deploy with multiple signatures | +**Example:** + +```bash +casper-client sign-deploy \ +--input transfer.deploy \ +--secret-key ~/KEYS/multi-sig/keys/user_1_secret_key.pem \ +--output transfer2.deploy +``` + Towards the end of the following output, you can observe that there is an **approvals** section, which has two signatures, one from the account initiating the transfer and the second from the account used to sign the deploy.
@@ -150,13 +173,13 @@ Towards the end of the following output, you can observe that there is an **appr ```json { - "hash": "959ba7154a58bf3a9ec555b38fb2c96dba81523b49f9a086630d0cf44d74cacc", + "hash": "88c49fa9108485397a330f294914a6c2d614c581fbe0a31de1a954baad6d709b", "header": { - "account": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", - "timestamp": "2023-01-05T11:42:23.311Z", + "account": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", + "timestamp": "2023-10-12T19:14:22.080Z", "ttl": "30m", "gas_price": 1, - "body_hash": "5d7d30965d503dba0459d5e6b3a0c923059f89e6a7179f76aec0fda1263b7819", + "body_hash": "1bb7436d4703816b5cbeef245dd83c0520f1c7173cdf609c664a29487cc5de1c", "dependencies": [], "chain_name": "casper-test" }, @@ -168,8 +191,8 @@ Towards the end of the following output, you can observe that there is an **appr "amount", { "cl_type": "U512", - "bytes": "021027", - "parsed": "10000" + "bytes": "0400e1f505", + "parsed": "100000000" } ] ] @@ -190,8 +213,8 @@ Towards the end of the following output, you can observe that there is an **appr "target", { "cl_type": "PublicKey", - "bytes": "01f48f5b095518be188286d896921d33e97f9729f5945237d5ff6cf7b077aabf1f", - "parsed": "01f48f5b095518be188286d896921d33e97f9729f5945237d5ff6cf7b077aabf1f" + "bytes": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", + "parsed": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf" } ], [ @@ -200,8 +223,8 @@ Towards the end of the following output, you can observe that there is an **appr "cl_type": { "Option": "U64" }, - "bytes": "013930000000000000", - "parsed": 3 + "bytes": "010100000000000000", + "parsed": 1 } ] ] @@ -210,11 +233,11 @@ Towards the end of the following output, you can observe that there is an **appr "approvals": [ { "signer": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986", - "signature": "014c2dc520a1d7f2b7cc18fe704899dd158c02448a4c575bc5214bad3384cb4fff6e32ece196768a8d21b5644c96850fea8b980bd2f6c1fe3c717c1c45a6b75508" + "signature": "015e0db50b174f3627e0e27cb503f0836b30bd0e0f2c4b989366b0df57500a1cb2b0945408c938bc3c33c40dab59a9c6af6f4e01e474330cd27262bfc87680030e" }, { - "signer": "0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf", - "signature": "0107b684e395879fed81d8387b0b4422301c1e4fcbd76672cf3fb7ab2ea8a2ef1429622a999fbbb56bcb79d871bfaeeb107415d67c78a57e8f67987e7f4368980c" + "signer": "01e3d3392c2e0b943abe709b25de5c353e5e1e9d95c7a76e3dd343d8aa1aa08d51", + "signature": "017793ad52d27393b1aa8ff5bb9bdbcb48708910d6cdabd9a89b44690ca174edf8924aad340bf901ac343391cb4cba7cf4db07390372f28ecf471fd522e0b63803" } ] } @@ -224,12 +247,12 @@ Towards the end of the following output, you can observe that there is an **appr ### Sending the deploy {#sending-the-deploy} -The next step is to send the deploy for processing on the network. As described in the [Prerequisites](#prerequisites) section, you need to get an active node address from the corresponding network to complete this task. The following example uses the node `http://65.21.235.219` from the Testnet; replace this with an active node before using the command. Port `7777` is the RPC endpoint for interacting with the Casper client. +The next step is to send the deploy for processing on the network. As described in the [Prerequisites](#prerequisites) section, you need to get an active node address from the corresponding network to complete this task. The following example uses the node `https://rpc.testnet.casperlabs.io/` from the Testnet. ```bash casper-client send-deploy \ --input transfer2.deploy \ ---node-address http://65.21.235.219:7777 +--node-address https://rpc.testnet.casperlabs.io/ ``` | Parameter | Description | @@ -244,18 +267,22 @@ Make a note of the *deploy_hash* from the `send-deploy` command output to verify ```json { - "id": 261147078494867680, - "jsonrpc": "2.0", - "result": { - "api_version": "1.3.4", - "deploy_hash": "87912f9ea859159dcf2f0554751ba0bce8b1df41f4b4339bc6de370d7734bdae" - } + "jsonrpc": "2.0", + "id": -818883417884028030, + "result": { + "api_version": "1.5.3", + "deploy_hash": "88c49fa9108485397a330f294914a6c2d614c581fbe0a31de1a954baad6d709b" + } } ```
-If you encounter an account authorization error, you must set up the source account to allow multi-signature deploys using session code. The [Two-Party Multi-Signature Deploys](../../../resources/advanced/two-party-multi-sig.md) workflow is an example of how to accomplish this. +:::note + +If you encounter an account authorization error, you **must set up the source account to allow multi-signature deploys** using session code. The [Two-Party Multi-Signature Deploys](../../../resources/advanced/two-party-multi-sig.md) workflow is an example of how to accomplish this. + +:::
Example of an account authorization error @@ -270,7 +297,7 @@ If you encounter an account authorization error, you must set up the source acco
-## Verifying the Transfer {#verifying-the-transfer} +### Verifying the transfer {#verifying-the-transfer} To verify the transfer status, see [Verifying a Transfer](./verify-transfer.md). diff --git a/source/docs/casper/developers/cli/transfers/verify-transfer.md b/source/docs/casper/developers/cli/transfers/verify-transfer.md index d07abe827b..7b7216c8aa 100644 --- a/source/docs/casper/developers/cli/transfers/verify-transfer.md +++ b/source/docs/casper/developers/cli/transfers/verify-transfer.md @@ -6,127 +6,152 @@ Before verifying a transfer, make sure you have: 1. Initiated a [Direct Transfer](./direct-token-transfer.md) or [Multi-sig Deploy Transfer](./multisig-deploy-transfer.md) 2. The *deploy_hash* of the transfer you want to verify -3. The *public key* hex for the source and target accounts +3. The *public key* of the source and target accounts -## Query Transfer Details {#query-transfer-details} +## Query the State Root Hash -A transfer is a part of a deploy - in a Casper network, deploys can contain multiple transfers. Execution of the deploy includes writing information about each individual transfer to global state. A unique hash known as the `transfer-address` identifies each transfer. The `transfer-address` consists of a formatted string with a `transfer-` prefix. +The state root hash is an identifier of the current network state. It gives a snapshot of the blockchain state at a moment in time. You can use the state root hash to query the network state after sending a deploy. -First, we will use the *deploy_hash* to identify the corresponding transfer: +```bash +casper-client get-state-root-hash --node-address [NODE_SERVER_ADDRESS] +``` + +**Example Query:** + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io +``` + +
+Sample output of the get-state-root-hash command + +```json +{ + "jsonrpc": "2.0", + "id": 6458079936180872466, + "result": { + "api_version": "1.5.3", + "state_root_hash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + } +} +``` +
+ +:::note + +After sending deploys to the network, you must get the new state root hash to see the changes reflected. Otherwise, you will be looking at events in the past. + +::: + +## Query the Transfer Details {#query-transfer-details} + +A transfer is executed as part of a deploy. In a Casper network, deploys can contain multiple transfers. Execution of the deploy includes writing information about each individual transfer to global state. A unique hash known as the `transfer-address` identifies each transfer. The `transfer-address` consists of a formatted string with a `transfer-` prefix. + +

+Image showing a transfer hash +

+ +First, use the `get-deploy` command and the *deploy_hash* to identify the corresponding transfer: ```bash casper-client get-deploy \ ---node-address http://:7777 \ +--node-address [NODE_SERVER_ADDRESS] \ [DEPLOY_HASH] ``` **Important response fields:** -- `"result"."execution_results"."result"."Success"."transfers"` - List of transfers contained in a successful deploy. +- `"result"."execution_results"."result"."Success"."transfers"` - List of transfers contained in a successful deploy -After we have obtained the `transfer-` identifier, we can query transfer details. +After obtaining the transfer identifier, query the transfer details. ```bash casper-client query-global-state \ ---id 8 \ ---node-address http://:7777 \ ---state-root-hash \ ---key transfer- +--id [ID] \ +--node-address [NODE_SERVER_ADDRESS] \ +--state-root-hash [STATE_ROOT_HASH] \ +--key [TRANSFER_HASH] ``` **Request fields:** -- `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned. -- `node-address` - An IP address of a node on the network. -- `state-root-hash` - The hex-encoded hash of the state root. -- `key` - The base key for the query. This must be a properly formatted transfer address. +- `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned +- `node-address` - An IP address of a node on the network +- `state-root-hash` - The hex-encoded hash of the state root +- `key` - The base key for the query. This must be a properly formatted transfer address with a `transfer-` prefix, i.e., `transfer-ab3e11fd612ccf9ddf5ddb3e5c0b3d3b5e5c0921fd1b45e8c657a63f01d6adcb` -
-Explore the JSON-RPC request and response generated. +The `-v` option generates verbose output, printing the RPC request and response generated. Let's explore an example below. -**JSON-RPC Request**: +**Example Query:** -```json -{ - "id": 8, - "jsonrpc": "2.0", - "method": "state_get_item", - "params": { - "key": "transfer-8d81f4a1411d9481aed9c68cd700c39d870757b0236987bb6b7c2a7d72049c0e", - "path": [], - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" - } -} +```bash +casper-client query-global-state -v \ +--id 3 \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1 \ +--key transfer-ab3e11fd612ccf9ddf5ddb3e5c0b3d3b5e5c0921fd1b45e8c657a63f01d6adcb ``` -**JSON-RPC Response**: +
+Explore the JSON-RPC request and response generated. + +**JSON-RPC Request**: ```json { - "id": 8, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "merkle_proof": "924 chars", - "stored_value": { - "Transfer": { - "amount": "2500000000", - "deploy_hash": "ec2d477a532e00b08cfa9447b7841a645a27d34ee12ec55318263617e5740713", - "from": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "gas": "0", - "id": null, - "source": "uref-9e90f4bbd8f581816e305eb7ea2250ca84c96e43e8735e6aca133e7563c6f527-007", - "target": "uref-6f4026262a505d5e1b0e03b1e3b7ab74a927f8f2868120cf1463813c19acb71e-004", - "to": "account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668" - } - } - } + "jsonrpc": "2.0", + "method": "query_global_state", + "params": { + "state_identifier": { + "StateRootHash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + }, + "key": "transfer-ab3e11fd612ccf9ddf5ddb3e5c0b3d3b5e5c0921fd1b45e8c657a63f01d6adcb", + "path": [] + }, + "id": 3 } ``` -
- -The query responds with more information about the transfer we conducted: its deploy hash, the account which executed the transfer, the source and target purses, and the target account. We can verify that our transfer processed successfully using this additional information. - -## The State Root Hash - -The state root hash is an identifier of the current network state. It gives a snapshot of the blockchain state at a moment in time. You can use the state root hash to query the network state after deployments. - -``` -casper-client get-state-root-hash --node-address [NODE_SERVER_ADDRESS] -``` - -
-Sample output of the get-state-root-hash command +**JSON-RPC Response**: ```json { - "id": -550641580167406055, "jsonrpc": "2.0", "result": { - "api_version": "1.4.13", - "state_root_hash": "a1f11692c5adc0e8b0a3f83e34d5831593a39ba03c8be73a0ebf7e9d9aadd76b" - } + "api_version": "1.5.3", + "block_header": null, + "stored_value": { + "Transfer": { + "deploy_hash": "4eedbb5cf4a571748cf7ae9c2f17777364a01f80f79f3633a0cec32b7e8cf2e3", + "from": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "to": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "source": "uref-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1-007", + "target": "uref-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c-004", + "amount": "5000000000", + "gas": "0", + "id": 11102023 + } + }, + "merkle_proof": "[42526 hex chars]" + }, + "id": 3 } ``` -
-:::note - -After any deploys to the network, you must get the new state root hash to see the new changes reflected. Otherwise, you will be looking at events in the past. +
-::: +The query responds with more information about the transfer: its deploy hash, the account which executed the transfer, the source and target purses, and the target account. You can verify that the transfer processed successfully using this additional information. -## Query Account State {#query-account-state} +## Query the Account State {#query-account-state} -Here, we will query for information about the _Source_ account, using the `state-root-hash` of the block containing the transfer: +Next, query for information about the _Source_ account, using the `state-root-hash` of the block containing the transfer: ```bash casper-client query-global-state \ ---id 4 \ ---node-address http://:7777 \ ---state-root-hash \ ---key +--id [ID] \ +--node-address [NODE_SERVER_ADDRESS] \ +--state-root-hash [STATE_ROOT_HASH] \ +--key [SOURCE_PUBLIC_KEY] ``` **Request fields:** @@ -134,12 +159,22 @@ casper-client query-global-state \ - `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned - `node-address` - An IP address of a node on the network - `state-root-hash` - Hex-encoded hash of the network state -- `key` - The base key for the query. This must be a properly formatted public key, account hash, contract address hash, URef, transfer hash, or deploy-info hash. +- `key` - The base key for the query. This must be a properly formatted public key, account hash, contract address hash, URef, transfer hash, or deploy-info hash **Important response fields:** - `"result"."stored_value"."Account"."main_purse"` - the address of the main purse containing the sender's tokens. In this example, this purse is the source of the tokens transferred +**Source Account Query:** + +```bash +casper-client query-global-state -v \ +--id 4 \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1 \ +--key 0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf +``` +
Explore the JSON-RPC request and response generated. @@ -147,14 +182,16 @@ casper-client query-global-state \ ```json { - "id": 4, - "jsonrpc": "2.0", - "method": "state_get_item", - "params": { - "key": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "path": [], - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" - } + "jsonrpc": "2.0", + "method": "query_global_state", + "params": { + "state_identifier": { + "StateRootHash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + }, + "key": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "path": [] + }, + "id": 4 } ``` @@ -162,42 +199,45 @@ casper-client query-global-state \ ```json { - "id": 4, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "merkle_proof": "2228 chars", - "stored_value": { - "Account": { - "account_hash": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "action_thresholds": { - "deployment": 1, - "key_management": 1 - }, - "associated_keys": [ - { - "account_hash": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "weight": 1 - } - ], - "main_purse": "uref-9e90f4bbd8f581816e305eb7ea2250ca84c96e43e8735e6aca133e7563c6f527-007", - "named_keys": [] - } + "jsonrpc": "2.0", + "result": { + "api_version": "1.5.3", + "block_header": null, + "stored_value": { + "Account": { + "account_hash": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "named_keys": [...], + "main_purse": "uref-11e6fc5354f61a004df98482376c45964b8b1557e8f2f13fb5f3adab5faa8be1-007", + "associated_keys": [ + { + "account_hash": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "weight": 1 + } + ], + "action_thresholds": { + "deployment": 1, + "key_management": 1 } - } + } + }, + "merkle_proof": "[31406 hex chars]" + }, + "id": 4 } ```
-We can repeat the same step to query information about the _Target_ account: +**Target Account Query:** + +Repeat the same step to query information about the _Target_ account: ```bash -casper-client query-global-state \ +casper-client query-global-state -v \ --id 5 \ ---node-address http://:7777 \ ---state-root-hash \ ---key +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1 \ +--key 01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986 ```
@@ -207,14 +247,16 @@ casper-client query-global-state \ ```json { - "id": 5, - "jsonrpc": "2.0", - "method": "state_get_item", - "params": { - "key": "account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668", - "path": [], - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" - } + "jsonrpc": "2.0", + "method": "query_global_state", + "params": { + "state_identifier": { + "StateRootHash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + }, + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "path": [] + }, + "id": 5 } ``` @@ -222,46 +264,46 @@ casper-client query-global-state \ ```json { - "id": 5, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "merkle_proof": "2228 chars", - "stored_value": { - "Account": { - "account_hash": "account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668", - "action_thresholds": { - "deployment": 1, - "key_management": 1 - }, - "associated_keys": [ - { - "account_hash": "account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668", - "weight": 1 - } - ], - "main_purse": "uref-6f4026262a505d5e1b0e03b1e3b7ab74a927f8f2868120cf1463813c19acb71e-007", - "named_keys": [] - } + "jsonrpc": "2.0", + "result": { + "api_version": "1.5.3", + "block_header": null, + "stored_value": { + "Account": { + "account_hash": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "named_keys": [...], + "main_purse": "uref-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c-007", + "associated_keys": [...], + "action_thresholds": { + "deployment": 2, + "key_management": 3 } - } + } + }, + "merkle_proof": "[32060 hex chars]" + }, + "id": 5 } ```
-## Get Purse Balance {#get-purse-balance} +## Query the Purse Balance {#get-purse-balance} -All accounts on a Casper network have a purse associated with the Casper system mint, which we call the _main purse_. The balance associated with a given purse is recorded in global state, and the value can be queried using the `URef` associated with the purse. +All accounts on a Casper network have a purse associated with the Casper system mint, which is the _main purse_. The balance associated with a given purse is recorded in global state, and the value can be queried using the `query-balance` command and the purse identifier, which can be a public key or account hash, implying the main purse of the given account should be used. Alternatively, the purse's URef can be used. For full details, run the following help command: -Now that we have the source purse address, we can verify its balance using the `get-balance` command: +```bash +casper-client query-balance --help +``` + +Verify the source purse balance using the `query-balance` command: ```bash -casper-client get-balance \ +casper-client query-balance \ --id 6 \ ---node-address http://:7777 \ ---state-root-hash \ ---purse-uref +--node-address [NODE_SERVER_ADDRESS] \ +--state-root-hash [STATE_ROOT_HAHS] \ +--purse-identifier [SOURCE_PUBLIC_KEY_HEX] ``` **Request fields:** @@ -269,22 +311,35 @@ casper-client get-balance \ - `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned - `node-address` - An IP address of a node on the network - `state-root-hash` - Hex-encoded hash of the state root -- `purse-uref` - The URef under which the purse is stored, following the format "uref-". +- `purse-identifier` - A public key or account hash, implying the main purse of the given account should be used. Alternatively, the purse's URef + +**Query Source Account Example:** + +```bash +casper-client query-balance -v --id 6 \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1 \ +--purse-identifier account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655 +```
-Explore the JSON-RPC request and response generated. +Explore the sample JSON-RPC request and response generated. **JSON-RPC Request**: ```json { - "id": 6, - "jsonrpc": "2.0", - "method": "state_get_balance", - "params": { - "purse_uref": "uref-6f4026262a505d5e1b0e03b1e3b7ab74a927f8f2868120cf1463813c19acb71e-007", - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" + "jsonrpc": "2.0", + "method": "query_balance", + "params": { + "state_identifier": { + "StateRootHash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + }, + "purse_identifier": { + "main_purse_under_account_hash": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655" } + }, + "id": 6 } ``` @@ -292,42 +347,54 @@ casper-client get-balance \ ```json { - "id": 6, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "balance_value": "5000000000", - "merkle_proof": "2502 chars" - } + "jsonrpc": "2.0", + "result": { + "api_version": "1.5.3", + "balance": "1109111876194" + }, + "id": 6 } ```
-Similarly, we have the address of the target purse, so we can get its balance. +Similarly, query the balance of the target purse. ```bash casper-client get-balance \ --id 7 \ ---node-address http://:7777 \ ---state-root-hash \ ---purse-uref +--node-address [NODE_SERVER_ADDRESS] \ +--state-root-hash [STATE_ROOT_HAHS] \ +--purse-identifier [TARGET_PUBLIC_KEY_HEX] +``` + +**Target Account Example:** + +```bash +casper-client query-balance -v --id 7 \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1 \ +--purse-identifier account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7 ```
-Explore the JSON-RPC request and response generated. +Explore the sample JSON-RPC request and response generated. **JSON-RPC Request**: ```json { - "id": 7, - "jsonrpc": "2.0", - "method": "state_get_balance", - "params": { - "purse_uref": "uref-6f4026262a505d5e1b0e03b1e3b7ab74a927f8f2868120cf1463813c19acb71e-007", - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" + "jsonrpc": "2.0", + "method": "query_balance", + "params": { + "state_identifier": { + "StateRootHash": "fdb1474d441ec0fcbf2e088f1630dbf98d3bcf7f7a7fe298303797f35b8cb4e1" + }, + "purse_identifier": { + "main_purse_under_account_hash": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7" } + }, + "id": 7 } ``` @@ -335,13 +402,12 @@ casper-client get-balance \ ```json { - "id": 7, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "balance_value": "5000000000", - "merkle_proof": "2502 chars" - } + "jsonrpc": "2.0", + "result": { + "api_version": "1.5.3", + "balance": "46200000000" + }, + "id": 7 } ``` diff --git a/source/docs/casper/developers/json-rpc/json-rpc-informational.md b/source/docs/casper/developers/json-rpc/json-rpc-informational.md index b802e71f10..aff285b77a 100644 --- a/source/docs/casper/developers/json-rpc/json-rpc-informational.md +++ b/source/docs/casper/developers/json-rpc/json-rpc-informational.md @@ -15,7 +15,7 @@ This method returns the JSON representation of a [Block](../../concepts/design/c
-Example chain_get_block request +Example chain_get_block request ```bash @@ -45,7 +45,7 @@ The result from `chain_get_block` depends on block availability from a given nod
-Example chain_get_block result +Example chain_get_block result ```bash @@ -128,7 +128,7 @@ This method returns all **successful** native transfers within a given [Block](.
-Example chain_get_block_transfers request +Example chain_get_block_transfers request ```bash @@ -156,7 +156,7 @@ This method returns all **successful** native transfers within a given [Block](.
-Example chain_get_block_transfers result +Example chain_get_block_transfers result ```bash @@ -195,7 +195,7 @@ This method returns the era summary at a given [Block](../../concepts/design/cas
-Example chain_get_era_summary request +Example chain_get_era_summary request ```bash @@ -223,7 +223,7 @@ This method returns the era summary at a given [Block](../../concepts/design/cas
-Example chain_get_era_summary result +Example chain_get_era_summary result ```bash @@ -326,7 +326,7 @@ This method returns a state root hash at a given [Block](../../concepts/design/c
-Example chain_get_state_root_hash request +Example chain_get_state_root_hash request ```bash @@ -354,7 +354,7 @@ This method returns a state root hash at a given [Block](../../concepts/design/c
-Example chain_get_state_root_hash result +Example chain_get_state_root_hash result ```bash @@ -377,7 +377,7 @@ This method returns raw bytes for chainspec files.
-Example info_get_chainspec request +Example info_get_chainspec request ```bash @@ -400,7 +400,7 @@ This method returns raw bytes for chainspec files.
-Example info_get_chainspec result +Example info_get_chainspec result Please note that adding a `--vv` flag will return the full chainspec bytes. @@ -434,7 +434,7 @@ This method retrieves a [Deploy](../../concepts/design/casper-design.md#executio
-Example info_get_deploy request +Example info_get_deploy request ```bash @@ -466,7 +466,7 @@ If the `execution_results` field is empty, it means that the network processed t
-Example info_get_deploy result +Example info_get_deploy result ```bash @@ -581,7 +581,7 @@ This method allows you to query for the balance of a purse using a `PurseIdentif
-Example query_balance request +Example query_balance request ```bash { @@ -618,7 +618,7 @@ This method allows you to query for the balance of a purse using a `PurseIdentif
-Example query_balance result +Example query_balance result ```bash @@ -639,7 +639,7 @@ This method allows you to query for the balance of a purse using a `PurseIdentif This method allows for you to query for a value stored under certain keys in global state. You may query using either a [Block hash](../../concepts/design/casper-design.md#block_hash) or state root hash. -* Note: Querying a purse's balance requires the use of `state_get_balance` or `query_balance`, rather than any iteration of `query_global_state`. +* Note: Querying a purse's balance requires the use of `query_balance`, rather than any iteration of `query_global_state`. |Parameter|Type|Description| |---------|----|-----------| @@ -649,7 +649,7 @@ This method allows for you to query for a value stored under certain keys in glo
-Example query_global_state request +Example query_global_state request ```bash @@ -681,7 +681,7 @@ This method allows for you to query for a value stored under certain keys in glo
-Example query_global_state result +Example query_global_state result ```bash @@ -767,7 +767,7 @@ This method returns a JSON representation of an [Account](../../concepts/design/
-Example state_get_account_info request +Example state_get_account_info request ```bash @@ -797,7 +797,7 @@ This method returns a JSON representation of an [Account](../../concepts/design/
-Example state_get_account_info result +Example state_get_account_info result ```bash @@ -829,65 +829,6 @@ This method returns a JSON representation of an [Account](../../concepts/design/
-## state_get_balance {#state-get-balance} - -This method returns a purse's balance from a network. The request takes in the formatted representation of a purse URef as a parameter. - -To query for the balance of an Account, you must provide the formatted representation of the Account's main purse URef, which can be obtained from the [`state_get_account_info`](#stategetaccountinfo-state-get-account-info) response. The response contains the balance of a purse in motes. - -For instance, one native layer-1 token of the Casper Mainnet [CSPR](../../concepts/glossary/C.md#cspr) is comprised of 1,000,000,000 motes. On a different Casper network, the representation of token-to-motes may differ. - -|Parameter|Type|Description| -|---------|----|-----------| -|[state_root_hash](types_chain.md#digest)|String|The hash of state root.| -|purse_uref|String|Formatted URef.| - -
-Example state_get_balance request - -```bash - -{ - "id": 1, - "jsonrpc": "2.0", - "method": "state_get_balance", - "params": [ - "uref-09480c3248ef76b603d386f3f4f8a5f87f597d4eaffd475433f861af187ab5db-007", - "0808080808080808080808080808080808080808080808080808080808080808" - ] -} - -``` - -
- -### `state_get_balance_result` - -|Parameter|Type|Description| -|---------|----|-----------| -|api_version|String|The RPC API version.| -|[balance_value](types_chain.md#u512)|String|The balance value in motes.| -|[merkle_proof](types_chain.md#merkle-proof)|String|The merkle proof.| - -
-Example state_get_balance result - -```bash - -{ - "id": 1, - "jsonrpc": "2.0", - "result": { - "api_version": "1.4.13", - "balance_value": "123456", - "merkle_proof": "01000000006ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a72536147614625016ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a72536147614625000000003529cde5c621f857f75f3810611eb4af3f998caaa9d4a3413cf799f99c67db0307010000006ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a7253614761462501010102000000006e06000000000074769d28aac597a36a03a932d4b43e4f10bf0403ee5c41dd035102553f5773631200b9e173e8f05361b681513c14e25e3138639eb03232581db7557c9e8dbbc83ce94500226a9a7fe4f2b7b88d5103a4fc7400f02bf89c860c9ccdd56951a2afe9be0e0267006d820fb5676eb2960e15722f7725f3f8f41030078f8b2e44bf0dc03f71b176d6e800dc5ae9805068c5be6da1a90b2528ee85db0609cc0fb4bd60bbd559f497a98b67f500e1e3e846592f4918234647fca39830b7e1e6ad6f5b7a99b39af823d82ba1873d000003000000010186ff500f287e9b53f823ae1582b1fa429dfede28015125fd233a31ca04d5012002015cc42669a55467a1fdf49750772bfc1aed59b9b085558eb81510e9b015a7c83b0301e3cf4a34b1db6bfa58808b686cb8fe21ebe0c1bcbcee522649d2b135fe510fe3" - } -} - -``` - -
- ## state_get_dictionary_item {#state-get-dictionary-item} This method returns an item from a Dictionary. Every dictionary has a seed URef, findable by using a `dictionary_identifier`. The address of a stored value is the blake2b hash of the seed URef and the byte representation of the dictionary key. @@ -901,7 +842,7 @@ You may query a stored value directly using the dictionary address.
-Example state_get_dictionary_item request +Example state_get_dictionary_item request ```bash @@ -935,7 +876,7 @@ You may query a stored value directly using the dictionary address.
-Example state_get_dictionary_item result +Example state_get_dictionary_item result ```bash @@ -975,7 +916,7 @@ This method returns a list of peers connected to the node.
-Example info_get_peers request +Example info_get_peers request ```bash @@ -999,7 +940,7 @@ This method returns a list of peers connected to the node.
-Example info_get_peers result +Example info_get_peers result ```bash @@ -1027,7 +968,7 @@ This method returns the current status of a node.
-Example info_get_status request +Example info_get_status request ```bash @@ -1063,7 +1004,7 @@ This method returns the current status of a node.
-Example info_get_status result +Example info_get_status result ```bash diff --git a/source/docs/casper/developers/json-rpc/json-rpc-pos.md b/source/docs/casper/developers/json-rpc/json-rpc-pos.md index dc4e58d185..946f270ceb 100644 --- a/source/docs/casper/developers/json-rpc/json-rpc-pos.md +++ b/source/docs/casper/developers/json-rpc/json-rpc-pos.md @@ -14,7 +14,7 @@ This method returns the [bids](../../concepts/economics/consensus.md#bids) and [
-Example state_get_auction_info request +Example state_get_auction_info request ```bash @@ -42,7 +42,7 @@ This method returns the [bids](../../concepts/economics/consensus.md#bids) and [
-Example state_get_auction_info result +Example state_get_auction_info result ```bash @@ -102,7 +102,7 @@ Potential change types:
-Example info_get_validator_changes request +Example info_get_validator_changes request ```bash @@ -128,7 +128,7 @@ If no changes occurred in the current era, `info_get_validator_changes` will ret
-Example info_get_validator_changes result +Example info_get_validator_changes result ```bash @@ -165,7 +165,7 @@ This method returns an EraInfo from the network. Only the last Block in an `era`
-Example chain_get_era_info_by_switch_block request +Example chain_get_era_info_by_switch_block request ```bash @@ -193,7 +193,7 @@ This method returns an EraInfo from the network. Only the last Block in an `era`
-Example chain_get_era_info_by_switch_block +Example chain_get_era_info_by_switch_block ```bash diff --git a/source/docs/casper/developers/json-rpc/json-rpc-transactional.md b/source/docs/casper/developers/json-rpc/json-rpc-transactional.md index 933a179560..03bb8a7229 100644 --- a/source/docs/casper/developers/json-rpc/json-rpc-transactional.md +++ b/source/docs/casper/developers/json-rpc/json-rpc-transactional.md @@ -14,7 +14,7 @@ This is the only means by which users can send their compiled Wasm (as part of a
-Example account_put_deploy request +Example account_put_deploy request ```bash @@ -26,20 +26,20 @@ This is the only means by which users can send their compiled Wasm (as part of a { "approvals": [ { - "signature": "014c1a89f92e29dd74fc648f741137d9caf4edba97c5f9799ce0c9aa6b0c9b58db368c64098603dbecef645774c05dff057cb1f91f2cf390bbacce78aa6f084007", - "signer": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c" + "signer": "01f8b29f39c38600ecb3bbb082951e04ab63a4ad4f7c9048a5057e461a5a8d58a5", + "signature": "019d6ef5c62c80ad4e50df343fba6f0fced17dea4c65e7976f66335ffcfcde2a7f02e928c8507cef3c76c3151e0e9cc9c3f7838b9f7a99ac4be5522ca092841100" } ], - "hash": "5c9b3b099c1378aa8e4a5f07f59ff1fcdc69a83179427c7e67ae0377d94d93fa", + "hash": "00a8677713222df88b6988926e0b14adeda6c663957f5075003395da4e5c6888", "header": { - "account": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c", - "body_hash": "d53cf72d17278fd47d399013ca389c50d589352f1a12593c0b8e01872a641b50", - "chain_name": "casper-example", + "account": "01f8b29f39c38600ecb3bbb082951e04ab63a4ad4f7c9048a5057e461a5a8d58a5", + "body_hash": "145ae09d6da5bc290051db8cb7132a41a30473d5900eaaf409d92b666325ca00", + "chain_name": "casper-net-1", "dependencies": [ "0101010101010101010101010101010101010101010101010101010101010101" ], "gas_price": 1, - "timestamp": "2020-11-17T00:39:24.072Z", + "timestamp": "2023-09-26T14:07:10.024Z", "ttl": "1h" }, "payment": { @@ -48,9 +48,8 @@ This is the only means by which users can send their compiled Wasm (as part of a [ "amount", { - "bytes": "e8030000", - "cl_type": "I32", - "parsed": 1000 + "bytes": "0400f90295", + "cl_type": "U512" } ] ], @@ -64,9 +63,15 @@ This is the only means by which users can send their compiled Wasm (as part of a [ "amount", { - "bytes": "e8030000", - "cl_type": "I32", - "parsed": 1000 + "cl_type": "U512", + "bytes": "0400f90295" + } + ], + [ + "target", + { + "cl_type": "URef", + "bytes": "09480c3248ef76b603d386f3f4f8a5f87f597d4eaffd475433f861af187ab5db07" } ] ] @@ -91,7 +96,7 @@ The result contains the [deploy_hash](./types_chain.md#deployhash), which is the
-Example account_put_deploy result +Example account_put_deploy result ```bash @@ -121,7 +126,7 @@ The `speculative_exec` endpoint provides a method to execute a `Deploy` without
-Example speculative_exec request +Example speculative_exec request ```bash @@ -215,7 +220,7 @@ The result contains the hash of the targeted block and the results of the execut
-Example speculative_exec result +Example speculative_exec result ```bash diff --git a/source/docs/casper/developers/json-rpc/minimal-compliance.md b/source/docs/casper/developers/json-rpc/minimal-compliance.md index c411f3dec6..2e6fbae77d 100644 --- a/source/docs/casper/developers/json-rpc/minimal-compliance.md +++ b/source/docs/casper/developers/json-rpc/minimal-compliance.md @@ -8,14 +8,20 @@ The methods included in this document represent the most basic, fundamental endp * [`account_put_deploy`](./json-rpc-transactional.md#account-put-deploy) - This method allows users to send their compiled Wasm (as part of a Deploy) to a node on a Casper network. Deploys represent the only means by which a user can perform computation on the platform, without which their interaction with a Casper network will be entirely passive. -* [`chain_get_state_root_hash`](./json-rpc-informational.md#chain-get-state-root-hash) - The state root hash is one of the several [global state identifiers](./types_chain.md#globalstateidentifier) used to query the network state after deployments, and the only way to do so in the context of `state_get_balance` and `state_get_dictionary_item`. A minimal SDK requires both dependent methods. +* [`chain_get_state_root_hash`](./json-rpc-informational.md#chain-get-state-root-hash) - The state root hash is one of the several [global state identifiers](./types_chain.md#globalstateidentifier) used to query the network state after sending deploys. * [`state_get_account_info`](./json-rpc-informational.md#state-get-account-info) - This method returns a JSON representation of an Account from the network. `state_get_account_info` is required to view associated account information, including any associated keys, named keys, action thresholds and the main purse. -* [`state_get_balance`](./json-rpc-informational.md#state-get-balance) - This method returns a purse's balance from a network. This is the only method to return a purse's balance in a human-readable format. +* [`query_balance`](./json-rpc-informational.md#query-balance) - This method returns a purse's balance from a network. This is the only method to return a purse's balance in a human-readable format. * [`state_get_dictionary_item`](./json-rpc-informational.md#state-get-dictionary-item) - This method returns an item from a Dictionary. Dictionaries represent a more efficient means of tracking large amounts of state. * [`query_global_state`](./json-rpc-informational.md#query-global-state) - This method allows for querying values stored under certain keys in global state. Aside from purse balances, this is the main means of recovering stored data from a Casper network. +:::note + +The deprecated method `state_get_balance` should not be used. + +::: + In addition to these methods, a minimally compliant Casper SDK must account for the [types](./types_chain.md) associated with each method. Each method above links to the expanded information available within the larger JSON RPC method pages, which includes the necessary associated types. diff --git a/source/docs/casper/developers/writing-onchain-code/best-practices.md b/source/docs/casper/developers/writing-onchain-code/best-practices.md index 0afa88d6f9..617de3bb61 100644 --- a/source/docs/casper/developers/writing-onchain-code/best-practices.md +++ b/source/docs/casper/developers/writing-onchain-code/best-practices.md @@ -9,7 +9,7 @@ When developing on Casper, a policy of efficient data usage will ensure the lowe When creating smart contracts, including an explicit initialization entry point allows the contract to self-initialize without a subsequent Deploy of session code. This entry point creates the internal structure of the contract and cannot be called after the initial deploy. Below is an example of a self-initalizing entry point that can be used within the `call` function.
-Example Self-initialization Entry Point +Example Self-initialization Entry Point ```rust diff --git a/source/docs/casper/developers/writing-onchain-code/contract-hash-vs-package-hash.md b/source/docs/casper/developers/writing-onchain-code/contract-hash-vs-package-hash.md new file mode 100644 index 0000000000..99e43584ab --- /dev/null +++ b/source/docs/casper/developers/writing-onchain-code/contract-hash-vs-package-hash.md @@ -0,0 +1,106 @@ +--- +title: Contract Hash vs. Package Hash +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# Using the Contract Hash vs. the Package Hash + +This page describes the possibilities of using the [contract hash](https://docs.rs/casper-types/3.0.0/casper_types/contracts/struct.ContractHash.html) vs. the [contract package hash](https://docs.rs/casper-types/3.0.0/casper_types/contracts/struct.ContractPackageHash.html) (package hash for short) when calling a contract or managing calls from other contracts. Contracts can allow, block, or track calls from other contracts. As noted in [Upgrading and Maintaining Smart Contracts](./upgrading-contracts.md#the-contract-package), the contract package contains various contract versions. The contract hash is a BLAKE2b hash of a contract, and the contract package hash is the BLAKE2b hash of a contract package. + +

package-representation

+ +Depending on what a contract needs to accomplish, it may save and manage the contract hash, package hash, or both. This behavior depends on what the contract needs to do, so a given contract might: + +- Want to identify specific versions of contracts within the same package and thus use a contract hash +- Not need specific contract versions and allow or block all versions in the same package, thus using the contract package hash +- Need specific contract versions within the same package, and thus use both contract hash and contract package hash +- Not need either hash for this use case + +A given contract, i.e., CEP-18, which wants to allow or block or track calls from other contracts, should then decide: + +- Will the contract allow, block, or track contract callers loosely at the package level? +- Will the contract allow, block, or track contract callers specifically at the contract level? + +Or a more fine-grained variation would be: + +- Will the contract allow or block callers at the package level but track by both package and contract hash? +- Will the contract allow other combinations of these basic concepts? + +Each contract is responsible for documenting its choices and what it requires of its callers. It is essential to keep in mind the difference between the behavior of the Casper execution engine (the host), as exposed by the [Casper External FFI](https://docs.rs/casper-contract/latest/casper_contract/ext_ffi/), versus use cases and interactions between two or more ecosystem entities such as accounts and contracts. + +The execution engine doesn't know how a contract such as CEP-18 is trying to manage its internal data or its exposed functionality. The contract is responsible for creating and managing a sub-ledger of resource management, access control, etc. + +## The Casper Call Stack + +When identifying who called a contract or initiated a call chain, the execution engine offers the FFI method [casper_load_call_stack](https://docs.rs/casper-contract/latest/casper_contract/ext_ffi/fn.casper_load_call_stack.html), which provides a stack of one or more entries of this kind: + +```rust +/// Represents the origin of a sub-call. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum CallStackElement { + /// Session + Session { + /// The account hash of the caller + account_hash: AccountHash, + }, + /// Effectively an EntryPointType::Session - stored access to a session. + StoredSession { + /// The account hash of the caller + account_hash: AccountHash, + /// The contract package hash + contract_package_hash: ContractPackageHash, + /// The contract hash + contract_hash: ContractHash, + }, + /// contract + StoredContract { + /// The contract package hash + contract_package_hash: ContractPackageHash, + /// The contract hash + contract_hash: ContractHash, + }, +} +``` + +You can find the source code [here](https://github.com/casper-network/casper-node/blob/release-1.5.1/types/src/system/call_stack_element.rs). + +After retrieving the required information, the contract must manage its internal logic and data storage, actions entirely opaque to the execution engine. + +Learn more about [Call Stacks](../../concepts/callstack.md) and how Casper manages the calling of a contract. + +## Recommendations + +Consider the following questions when designing the contract and choosing whether to use the contract hash or package hash. + +1. Will you allow only accounts to use the contract? If so, what kind of accounts are you considering? + + |Answer|Recommendation| + |----|-----------| + | Specific accounts | Use the account hash to identify and track each account. | + | Exactly one specific account | Use the account hash of a specific account to identify it. | + | Any accounts | There is no need to track the accounts by account hash. | + +2. Will you allow only contracts to use it? If so, what kind of contracts? + + |Answer|Recommendation| + |----|-----------| + | Specific contract versions| Use the contract hash to identify each contract version. | + | Specific contract versions of specific packages| Use the contract hash and the package hash to identify each contract version. | + | Any contract versions of specific packages| Use only the package hash to identify each contract package. | + | Any contract version of any contract| There is no need to track by contract or package hash. | + +3. Will you allow both accounts and contracts to use it? If so, will these accounts and contracts be: + + |Answer|Recommendation| + |----|-----------| + | Specific accounts and contract versions | Use the account hash to track each account and the contract hash to identify each contract version. | + | Specific accounts and specific versions of specific packages | Use the account hash to identify each account and the contract hash and package hash to identify each contract version. | + | Specific accounts and any versions of specific packages | Use the account hash to identify each account and the package hash to identify each contract package. | + | Any accounts and contracts | There is no need to track by account hash or contract hash. | + +## What's Next? + +- [Best Practices for Casper Smart Contract Authors](./best-practices.md) - An outline of best practices when developing smart contracts on a Casper network +- [Cross-Contract Communication](../../resources/advanced/cross-contract.md) - Variations of cross-contract communication for more complex scenarios +- [Interacting with Runtime Return Values](../../resources/advanced/return-values-tutorial.md) - Contract code returning a value to the immediate caller via `runtime::ret()` diff --git a/source/docs/casper/developers/writing-onchain-code/index.md b/source/docs/casper/developers/writing-onchain-code/index.md index bb9576a52b..96580532a3 100644 --- a/source/docs/casper/developers/writing-onchain-code/index.md +++ b/source/docs/casper/developers/writing-onchain-code/index.md @@ -14,32 +14,40 @@ This section shows you how to write session code and smart contracts in Rust and | Title | Description | | ------------------------------------------- | ------------------------------- | |[Getting Started with Rust](./getting-started.md)| An introduction to using Rust with the Casper Platform| -|[Best Practices for Casper Smart Contract Authors](./best-practices.md)| An outline of best practices when developing smart contracts on a Casper network| +|[Getting Started with AssemblyScript](./assembly-script.md) | An introduction to using AssemblyScript with the Casper Platform | |[Writing a Basic Smart Contract in Rust](./simple-contract.md) | An example of a smart contract built in Rust| |[Unit Testing Smart Contracts](./testing-contracts.md) | Steps to test contract code using the unit testing framework| +|[Upgrading and Maintaining Smart Contracts](./upgrading-contracts.md)| An introduction to versioning smart contracts| +|[Calling Contracts](./calling-contracts.md) | | |[Smart Contracts and Session Code](./contract-vs-session.md) | Understand what session code is and when you would use it over contract code | |[Writing Session Code](./writing-session-code.md) | An introduction to writing session code| |[Unit Testing Session Code](./testing-session-code.md) | Steps to test session code using the unit testing framework| +|[Using Contract Hash vs. Package Hash](./contract-hash-vs-package-hash.md)| Advantages and disadvantages of using `contract_hash` vs. `contract_package_hash` when calling a contract| +|[Best Practices for Casper Smart Contract Authors](./best-practices.md)| An outline of best practices when developing smart contracts on a Casper network| + +## Interacting with Contracts on the Blockchain + +Additionally, the section on [Interacting with the Blockchain](../cli/index.md) covers installing and calling contracts using the Casper command-line client written in Rust. + +| Title | Description | +| ----------------------------------------------------------- | ---------------------------------------------------------------- | |[Installing Smart Contracts and Querying Global State](../cli/installing-contracts.md)| A guide on installing smart contracts and querying global state | |[Calling Smart Contracts with the Rust Client](../cli/calling-contracts.md)| Steps to call a smart contract with the Rust command-line client| -|[Upgrading and Maintaining Smart Contracts](./upgrading-contracts.md)| An introduction to versioning smart contracts| |[Reading and Writing to Dictionaries](../../concepts/dictionaries.md)| Information on Dictionaries and how to read and write to them on the Casper Platform.| |[Execution Error Codes](../cli/execution-error-codes.md)|Possible error codes when writing smart contracts.| -|[Getting Started with AssemblyScript](./assembly-script.md) | An introduction to using AssemblyScript with the Casper Platform | -Additionally, the following tutorials outline some aspects of writing smart contracts on a Casper network. +## Tutorials + +The following tutorials outline some aspects of writing smart contracts on a Casper network. | Title | Description | | ----------------------------------------------------------- | ---------------------------------------------------------------- | |[Getting Started Video](../../resources/beginner/getting-started-tutorial.md) | Step-by-step video tutorial for setting up the Casper development environment | -|[NFTs on Casper with the CEP-78 NFT Standard](https://github.com/casper-ecosystem/cep-78-enhanced-nft/blob/dev/README.md) | Implementing the Casper CEP-78 NFT standard | -|[A Counter on an NCTL Network](../../resources/beginner/counter/index.md) | An example contract that maintains a counter variable on a local Casper Network with NCTL | |[A Counter on the Testnet](../../resources/beginner/counter-testnet/index.md) | An example contract that maintains a counter variable on the Casper Testnet | +|[Smart Contract Upgrades](../../resources/beginner/upgrade-contract.md) | Learn how to upgrade smart contracts | +|[NFTs on Casper with the CEP-78 NFT Standard](https://github.com/casper-ecosystem/cep-78-enhanced-nft/blob/dev/README.md) | Implementing the Casper CEP-78 NFT standard | |[Fungible Tokens on Casper](https://github.com/casper-ecosystem/cep18/blob/master/docs/full-tutorial.md) | Implement the Casper Fungible Token standard | |[Interacting with Runtime Return Values](../../resources/advanced/return-values-tutorial.md)| Learning how to return a value using contract code | |[Working with Authorization Keys](../../resources/advanced/list-auth-keys-tutorial.md)| Retrieving and using the authorization keys associated with a deploy | |[Safely Transfer Tokens to a Contract](../../resources/advanced/transfer-token-to-contract.md) | How to handle tokens via a contract | -|[Smart Contract Upgrades](../../resources/beginner/upgrade-contract.md) | Learn how to upgrade smart contracts | -|[Interacting with Runtime Return Values](../../resources/advanced/return-values-tutorial.md)| Learning how to return a value using contract code | -|[Safely Transfer Tokens to a Contract](../../resources/advanced/transfer-token-to-contract.md) | How to handle tokens via a contract | -|[Smart Contract Upgrades](../../resources/beginner/upgrade-contract.md) | Learn how to upgrade smart contracts | + diff --git a/source/docs/casper/developers/writing-onchain-code/upgrading-contracts.md b/source/docs/casper/developers/writing-onchain-code/upgrading-contracts.md index 55b061a29e..799a47ffe0 100644 --- a/source/docs/casper/developers/writing-onchain-code/upgrading-contracts.md +++ b/source/docs/casper/developers/writing-onchain-code/upgrading-contracts.md @@ -9,6 +9,8 @@ Our smart contract packaging tools enable you to: - Version your contracts and deprecate old versions - Set permissions around who can perform contract upgrades +## The Contract Package + When you upgrade a contract, you add a new contract version in a contract package. The versioning process is additive rather than an in-place replacement of an existing contract. The original version of the contract is still there, and you can enable certain versions for specific clients. You can also disable a contract version if needed.

package-representation

diff --git a/source/docs/casper/operators/becoming-a-validator/bonding.md b/source/docs/casper/operators/becoming-a-validator/bonding.md index 1786faeaea..88e95f7c06 100644 --- a/source/docs/casper/operators/becoming-a-validator/bonding.md +++ b/source/docs/casper/operators/becoming-a-validator/bonding.md @@ -140,7 +140,7 @@ casper-client get-auction-info --node-address http:// ```
-Example auction info response +Example auction info response ```bash { diff --git a/source/docs/casper/operators/becoming-a-validator/fast-sync.md b/source/docs/casper/operators/becoming-a-validator/fast-sync.md deleted file mode 100644 index 03be1b7fbf..0000000000 --- a/source/docs/casper/operators/becoming-a-validator/fast-sync.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Fast-Sync ---- - -# Introducing Fast-Sync - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -The Casper Network is a smart contract platform. It requires new nodes to download and execute each and every block to join the network. Starting from genesis (start of the Mainnet), the node executes each deploy in every block. This process continues until the node has arrived at the current state of the blockchain. This process to sync a node with the blockchain can take a very long time. - -To provide an alternative and faster approach to joining a Casper network, we have introduced fast‑sync. Fast-sync does not start syncing at the genesis block; instead, the user verifies a recent block, e.g. using block explorers, and provides its hash to the node software. The network [global state](../../concepts/design/casper-design.md#global-state-head) — smart contract data, account balances and all other on-chain information — is the storage layer of the blockchain and is massive in size, so fast-sync downloads the global state of only the most recent block. The following section briefly describes the fast-sync process. - -## How Fast-sync Works - - - -For fast-sync, you need to provide the trusted hash of a block on a Casper network in the config.toml file. Fast-sync uses this trusted block as part of the cryptographic verification for the later blocks. This trusted block is downloaded, as are all newer blocks up to and including the most recent block from the current era. For example, if the trusted block hash is 5 hours old, it will first download that block, then newer blocks until it arrives at one that is only a few minutes old. It then downloads the newer block's global state. Finally, it executes all blocks the network created while the download was in progress, until it is fully in sync. - diff --git a/source/docs/casper/operators/maintenance/moving-node.md b/source/docs/casper/operators/maintenance/moving-node.md index ce53bd355d..ff9f12ded7 100644 --- a/source/docs/casper/operators/maintenance/moving-node.md +++ b/source/docs/casper/operators/maintenance/moving-node.md @@ -6,68 +6,82 @@ title: Move a Node This guide is for active validators who want to move their node to another machine. +:::note + +Starting with node version 1.5, operators need to move the unit files at the database level. This step allows moving the node with nearly zero rewards loss. + +::: + ## Swapping Keys with a Hot Backup This method limits downtime and enables a smooth transition from the old to the new node. It keeps the node in sync with the tip of the chain. 1. Once a node is running (`current_node`), create a second node (`backup_node`) on another machine. These two nodes will run in parallel. -2. When the `backup_node` is up to date, stop both nodes. -3. Swap their associated keys. -4. Restart the `backup_node`. +2. When the `backup_node` is up to date, stop the `current_node`. +3. Move the unit files at the DB level using `rsync`. This step allows moving the node with nearly zero rewards loss. +4. Stop the `backup_node`. +5. Swap keys on the `backup_node`, now the new validator. +6. Restart the `backup_node`. +7. Swap keys on the `current_node`, now the new backup. +8. Restart the `current_node`. ### Preparation for swapping -Let both nodes synchronize to the tip of the blockchain. Keep the current validating node running with the original validator keyset. +1. Let both nodes synchronize to the tip of the blockchain. Keep the current validating node running with the original validator keyset. -Bond the `backup_node` and wait until rewards are issued. +2. Bond the `backup_node` and wait until rewards are issued. -To swap keys: +3. Prepare to swap keys by following these steps: -1. Create the following folder structure on both nodes under the `/etc/casper/validator_keys/` directory. -2. Create subdirectories for the `current_node` and `backup_node`. -3. Copy each node's keyset under the corresponding directories. + - Create the following folder structure on both nodes under the `/etc/casper/validator_keys/` directory. + - Create subdirectories for the `current_node` and `backup_node`. + - Copy each node's keyset under the corresponding directories. ```bash -/etc/casper/validator_keys/ -├── public_key.pem -├── public_key_hex -├── secret_key.pem -├── current_node -│ ├── public_key.pem -│ ├── public_key_hex -│ └── secret_key.pem -└── backup_node -| ├── public_key.pem -| ├── public_key_hex -| └── secret_key.pem + /etc/casper/validator_keys/ + ├── public_key.pem + ├── public_key_hex + ├── secret_key.pem + ├── current_node + │ ├── public_key.pem + │ ├── public_key_hex + │ └── secret_key.pem + └── backup_node + | ├── public_key.pem + | ├── public_key_hex + | └── secret_key.pem ``` This setup allows key swapping by running the `sudo -u casper cp * ../` command, as shown below. ### Swapping the nodes -On the `current_node`, run these commands: +1. When the `backup_node` is up to date, stop the `current_node`. -```bash -sudo systemctl stop casper-node-launcher -cd /etc/casper/validator_keys/backup_node -sudo -u casper cp * ../ -``` +2. On the `backup_node` (the future validator), use `rsync` to move the unit files from the `current_node`, located in `/var/lib/casper/casper-node/[NETWORK_NAME]/unit_files`. -On the `backup_node` (the future validator), run these commands: +3. On the `backup_node`, run these commands to stop the node, swap keys, and restart the node: -```bash -sudo systemctl stop casper-node-launcher -cd /etc/casper/validator_keys/current_node -sudo -u casper cp * ../ -sudo systemctl start casper-node-launcher -``` + ```bash + sudo systemctl stop casper-node-launcher + cd /etc/casper/validator_keys/current_node + sudo -u casper cp * ../ + sudo systemctl start casper-node-launcher + ``` -Restart the original validator node (`current_node`), which is now the new backup: +4. On the `current_node`, run these commands to stop the node and swap keys: -```bash -sudo systemctl start casper-node-launcher -``` + ```bash + sudo systemctl stop casper-node-launcher + cd /etc/casper/validator_keys/backup_node + sudo -u casper cp * ../ + ``` + +5. Restart the original validator node (`current_node`), which is now the new backup: + + ```bash + sudo systemctl start casper-node-launcher + ``` ### Understanding rewards impact diff --git a/source/docs/casper/operators/setup/fast-sync.md b/source/docs/casper/operators/setup/fast-sync.md new file mode 100644 index 0000000000..7614eb400b --- /dev/null +++ b/source/docs/casper/operators/setup/fast-sync.md @@ -0,0 +1,20 @@ +--- +title: Fast Sync +--- + +# Introducing Fast Sync + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +A Casper Network requires new nodes to download and execute every block to join the network. From genesis (start of the Mainnet), the node executes each deploy in every block. This process continues until the node has arrived at the current state of the blockchain. Syncing a node this way can take a very long time. + +We have introduced a fast syncing process (fast sync) to provide a faster alternative to joining a Casper network. Fast sync does not start syncing at the genesis block; instead, the operator verifies a recent block and provides a [trusted hash](../setup/basic-node-configuration.md#trusted-hash-for-synchronizing) to the node software. The global state, account balances, and all other on-chain information is the storage layer of the blockchain and is massive in size, so fast sync downloads the global state of only the most recent block. The following section briefly describes the fast sync process. + +## How Fast Sync Works + + + +For fast sync, operators must provide the trusted hash of a block in the `config.toml` file. An example can be found [here](https://github.com/casper-network/casper-node/blob/f7d8228de3cb56a3fe705f5a787d3dbf03ff7998/resources/production/config-example.toml#L7). + +Fast sync uses this trusted block as part of the cryptographic verification for the later blocks. The node downloads the trusted block first, then newer blocks up to and including the most recent block from the current era. For example, if the trusted hash is 5 hours old, it will first download that block, then newer blocks, until it arrives at one that is only a few minutes old. It then downloads the newer block's global state. Finally, it executes all the blocks the network created while the download was in progress until it is entirely in sync. + diff --git a/source/docs/casper/operators/setup/install-node.md b/source/docs/casper/operators/setup/install-node.md index 39026d495e..8e080ac82d 100644 --- a/source/docs/casper/operators/setup/install-node.md +++ b/source/docs/casper/operators/setup/install-node.md @@ -119,7 +119,7 @@ For more details, see the [Node Setup](./basic-node-configuration.md#create-fund ## Getting a Trusted Hash -In the past, we have used a lower `trusted_hash`. Connecting at the tip, we now use as high of a `trusted_hash` as possible. +In the past, we have used a lower `trusted_hash`. Connecting at the tip, we now use as high of a `trusted_hash` as possible. Find out more about [Fast Sync](./fast-sync.md). ### Node Address diff --git a/source/docs/casper/operators/setup/node-endpoints.md b/source/docs/casper/operators/setup/node-endpoints.md index 9a3dbe7179..fdf149a3f3 100644 --- a/source/docs/casper/operators/setup/node-endpoints.md +++ b/source/docs/casper/operators/setup/node-endpoints.md @@ -74,7 +74,7 @@ curl -s http://:8888/status | jq ```
-Sample response +Sample response ```json { @@ -134,7 +134,7 @@ curl -s http://:8888/status | jq -r '.api_version, .last_added_blo ```
-Sample response +Sample response ```json "1.4.15" diff --git a/source/docs/casper/resources/advanced/cross-contract.md b/source/docs/casper/resources/advanced/cross-contract.md index 4ae1272c2e..45a8908919 100644 --- a/source/docs/casper/resources/advanced/cross-contract.md +++ b/source/docs/casper/resources/advanced/cross-contract.md @@ -674,7 +674,7 @@ Query the state of Casper network using the account hash: If we check the account's named keys, we can see all of the account's deployed contracts:
-Account's named keys +Account's named keys ```bash { @@ -843,7 +843,7 @@ casper-client get-deploy \ After the deploy finishes successfully, you should see a similar outcome to the following:
-Deploy details +Deploy details ```bash { diff --git a/source/docs/casper/resources/advanced/list-cspr.md b/source/docs/casper/resources/advanced/list-cspr.md index 9104a48267..a534a6576a 100644 --- a/source/docs/casper/resources/advanced/list-cspr.md +++ b/source/docs/casper/resources/advanced/list-cspr.md @@ -37,7 +37,7 @@ Casper supports native two-party transfers as well as bulk transfers using custo You can accomplish a native transfer by sending a native transfer deploy, without any Wasm. Included below is an example of this type of deploy. The included `payment` field describes how we are paying for the deploy, in this case a native transfer, while the `session` field describes the actual transfer.
-Native Transfer Deploy +Native Transfer Deploy ```json diff --git a/source/docs/casper/resources/advanced/multi-sig/multi-sig-workflow.md b/source/docs/casper/resources/advanced/multi-sig/multi-sig-workflow.md index 63f551810b..e09859fbfd 100644 --- a/source/docs/casper/resources/advanced/multi-sig/multi-sig-workflow.md +++ b/source/docs/casper/resources/advanced/multi-sig/multi-sig-workflow.md @@ -8,11 +8,7 @@ The purpose of this tutorial is to provide an example of how to integrate key ma :::warning -The session code provided in this tutorial should not be used in a production environment. - -Incorrect account configurations could render accounts defunct and unusable, thus losing access to all the corresponding CSPR tokens. - -Test any changes to an account in a test environment like Testnet before performing changes in a live environment like Mainnet. +Understanding the multi-sig feature and trying it out on Testnet before using it on Mainnet is essential. Incorrect account configurations could render accounts unusable, and you could lose access to all the corresponding CSPR tokens. ::: @@ -46,17 +42,29 @@ The [multi-sig GitHub repository](https://github.com/casper-ecosystem/tutorials- git clone https://github.com/casper-ecosystem/tutorials-example-wasm/ && cd multi-sig ``` +If you take a look at the repository structure and open the `contracts` folder, you will see session code with different functionality: + +- `add_account.wasm` - adds an associated account with a specified weight +- `update_associated_keys.wasm` - updates a key’s weight +- `update_thresholds.wasm` - updates the account's action thresholds for deployment and account management +- `remove_account.wasm` - removes an associated account from the primary account + ### Step 2: Build the sample Wasm provided Prepare your environment, build and test the session code provided with the following commands: ```bash rustup update -make clean make prepare make test ``` +- `rustup update` - checks and updates your Rust installation +- `make prepare` - sets the Wasm target +- `make test` - builds and verifies the session code + +Note that in the test folder there is a `contract.wasm` that is needed for the tests to pass. If you run `make clean` that file will be deleted. + ### Step 3: Increase the primary key's weight to set thresholds This workflow starts by increasing the weight of the primary key from 1 to 3. To make account updates, a key's weight must equal or exceed the `key_management` threshold. In a later step, you will add the associated accounts that will participate in signing deploys. @@ -75,10 +83,27 @@ casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --payment-amount 500000000 \ --secret-key $PATH/secret_key.pem \ --session-path target/wasm32-unknown-unknown/release/update_associated_keys.wasm \ ---session-arg "associated_key:key='account-hash-'" \ +--session-arg "associated_key:key='account-hash-'" \ --session-arg "new_weight:u8='3'" ``` +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` + The primary key in this account should now have weight 3.
@@ -127,7 +152,24 @@ casper-client put-deploy \ --session-arg "key_management_threshold:u8='3'" ``` -The account's action thresholds would look like this: +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` + +The account's action thresholds should look like this: ```json "action_thresholds": { @@ -184,6 +226,12 @@ casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --session-arg "weight:u8='1'" ``` +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + ```bash casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --chain-name "casper-test" \ @@ -194,8 +242,24 @@ casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --session-arg "weight:u8='1'" ``` -Now, the account has one primary key with weight 3, and two associated accounts, each with weight 1. +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` +Now, the account should have one primary key with weight 3, and two associated accounts, each with weight 1.
Account details @@ -258,7 +322,24 @@ casper-client put-deploy --chain-name casper-test \ --session-arg "message:string='Hello, World'" ``` -The `hello_world.wasm` will run and add a named key to the account. +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` + +The `hello_world.wasm` should have run and added a named key to the account. ```json "named_keys": [ @@ -273,9 +354,9 @@ The `hello_world.wasm` will run and add a named key to the account. Given the multi-signature scheme set up in this example, two associated keys need to sign to send a deploy from one of the associated keys. This example uses the following commands to sign a deploy with multiple keys and send it to the network: -1. `make-deploy` - creates and signs a deploy, saving the output to a file -2. `sign-deploy` - adds additional signatures for a multi-signature deploy -3. `send-deploy` - sends the deploy to the network +- `make-deploy` - creates and signs a deploy, saving the output to a file +- `sign-deploy` - adds additional signatures for a multi-signature deploy +- `send-deploy` - sends the deploy to the network Similar to step 6, this example uses Wasm (`contract.wasm`), which adds a named key to the account. The deploy originates from the primary account, specified with the `--session-account` argument. The deploy needs two signatures to meet the `deployment` weight equal to 2. Once both associated keys sign the deploy, either can send it to the network. @@ -306,8 +387,24 @@ The deploy can be sent to the network using the `send-deploy` command: casper-client send-deploy --node-address https://rpc.testnet.casperlabs.io -i hello_world_two_signatures ``` -The `hello_world.wasm` will run and add a named key to the account. +Verify that the deploy ran successfully. +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` + +The `hello_world.wasm` should have run and added a named key to the account. ## Removing a Compromised Key @@ -333,6 +430,23 @@ casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --session-arg "weight:u8='1'" ``` +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` +
Account details @@ -390,6 +504,23 @@ casper-client put-deploy --node-address https://rpc.testnet.casperlabs.io/ \ --session-arg "remove_key:key='account-hash-1fed34baa6807a7868bb18f91b161d99ebf21763810fe4c92e39775d10bbf1f8" ``` +Verify that the deploy ran successfully. + +```bash +casper-client get-deploy --node-address https://rpc.testnet.casperlabs.io/ +``` + +Retrieve the latest state root hash and check the primary account details. + +```bash +casper-client get-state-root-hash --node-address https://rpc.testnet.casperlabs.io/ + +casper-client query-global-state \ +--node-address https://rpc.testnet.casperlabs.io/ \ +--state-root-hash \ +--key account-hash- +``` + The resulting account should not contain the associated key that was just removed.
diff --git a/source/docs/casper/resources/beginner/querying-network.md b/source/docs/casper/resources/beginner/querying-network.md index 60bb9e88e7..e8b2b5e8f6 100644 --- a/source/docs/casper/resources/beginner/querying-network.md +++ b/source/docs/casper/resources/beginner/querying-network.md @@ -87,21 +87,33 @@ casper-client query-global-state \ - `"result"."stored_value"."Account"."main_purse"` - the address of the main purse containing the sender's tokens. This purse is the source of the tokens transferred in this example +**Example Account Query with Verbose Output:** + +```bash +casper-client query-global-state -v \ + --id 4 \ + --node-address https://rpc.testnet.casperlabs.io/ \ + --state-root-hash a306a9cf869e52fe9eacdc28aade94215112cc04b6737b3669c35568a47a7dc2 \ + --key 01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986 +``` +
-Explore the JSON-RPC request and response generated. +Explore the sample JSON-RPC request and response generated. **JSON-RPC Request**: ```json { - "id": 4, - "jsonrpc": "2.0", - "method": "state_get_item", - "params": { - "key": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "path": [], - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" - } + "jsonrpc": "2.0", + "method": "query_global_state", + "params": { + "state_identifier": { + "StateRootHash": "a306a9cf869e52fe9eacdc28aade94215112cc04b6737b3669c35568a47a7dc2" + }, + "key": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "path": [] + }, + "id": 4 } ``` @@ -109,42 +121,88 @@ casper-client query-global-state \ ```json { - "id": 4, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "merkle_proof": "2228 chars", - "stored_value": { - "Account": { - "account_hash": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "action_thresholds": { - "deployment": 1, - "key_management": 1 - }, - "associated_keys": [ - { - "account_hash": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5", - "weight": 1 - } - ], - "main_purse": "uref-9e90f4bbd8f581816e305eb7ea2250ca84c96e43e8735e6aca133e7563c6f527-007", - "named_keys": [] - } + "jsonrpc": "2.0", + "id": 4, + "result": { + "api_version": "1.5.2", + "block_header": null, + "stored_value": { + "Account": { + "account_hash": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "named_keys": [ + { + "name": "counter", + "key": "hash-4bf23564c8849a0a3193781f0a9df7d27c4bce2cc585d6e9bb161a7a1ce5cd7e" + }, + { + "name": "counter_access_uref", + "key": "uref-76b6c7e7a87b752d34a8c3ccdc070dbfd1940960016c537525b2ab9076b61a3e-007" + }, + { + "name": "counter_package_name", + "key": "hash-e4b2060f098fa763f9a68c5c98a2d98a4fa80815ec0fd6b93ac9efbb0c18f19b" + }, + { + "name": "my-key-name", + "key": "uref-09376d4202d32457ceefa4d9cdf1db6ab2324981ade06ba6f495cdf14124c3b9-007" + }, + { + "name": "version", + "key": "uref-244a270207dd13ef5ff190f75d84efe4ab54bd5787be0bbb175c3fb154b7f5ed-007" + } + ], + "main_purse": "uref-8294864177c2c1ec887a11dae095e487b5256ce6bd2a1f2740d0e4f28bd3251c-007", + "associated_keys": [ + { + "account_hash": "account-hash-0ea7998b2822afe5b62b08a21d54c941ad791279b089f3f7ede0d72b477eca34", + "weight": 1 + }, + { + "account_hash": "account-hash-1ed5a1c39bea93c105f2d22c965a84b205b36734a377d05dbb103b6bfaa595a7", + "weight": 3 + }, + { + "account_hash": "account-hash-77ea2e433c94c9cb8303942335da458672249d38c1fa5d1d7a7500b862ff52a4", + "weight": 1 + }, + { + "account_hash": "account-hash-d65d053f5017af101b752a9a12ba4c41fe3054b8632998a69193b891eab4caf5", + "weight": 1 + }, + { + "account_hash": "account-hash-e70dbca48c2d31bc2d754e51860ceaa8a1a49dc627b20320b0ecee1b6d9ce655", + "weight": 1 + }, + { + "account_hash": "account-hash-f1802d2dbd83e41f638eb9b046f762e481d56b27d4aa00817fec77fbb21f944a", + "weight": 1 + } + ], + "action_thresholds": { + "deployment": 2, + "key_management": 3 } - } + } + }, + "merkle_proof": "[32054 hex chars]" + } } ```
-You can use the URef of the `main_purse` to query the account balance. The balance returned is in motes (the unit that makes up the Casper token). +To query the account balance, use the `query-balance` command and the purse identifier, which can be a public key or account hash, implying the main purse of the given account should be used. Alternatively, the purse's URef can be used. The balance returned is in motes (the unit that makes up the Casper token). For full details, run the following help command: ```bash -casper-client get-balance \ - --id 6 \ - --node-address http://:7777 \ - --state-root-hash \ - --purse-uref +casper-client query-balance --help +``` + +```bash +casper-client query-balance \ +--id 6 \ +--node-address http://:7777 \ +--state-root-hash \ +--purse-identifier ``` **Request fields:** @@ -152,7 +210,19 @@ casper-client get-balance \ - `id` - Optional JSON-RPC identifier applied to the request and returned in the response. If not provided, a random integer will be assigned - `node-address` - An IP address of a node on the network - `state-root-hash` - Hex-encoded hash of the state root -- `purse-uref` - The URef under which the purse is stored. This must be a properly formatted URef "uref-\-" +- `purse-identifier` - A public key or account hash, implying the main purse of the given account should be used. Alternatively, the purse's URef. + +The `-v` option generates verbose output, printing the RPC request and response generated. Let's explore an example below. + +**Example Balance Query with Verbose Output:** + +```bash +casper-client query-balance -v \ + --id 6 \ + --node-address https://rpc.testnet.casperlabs.io/ \ + --state-root-hash a306a9cf869e52fe9eacdc28aade94215112cc04b6737b3669c35568a47a7dc2 \ + --purse-identifier 01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986 +```
Explore the JSON-RPC request and response generated. @@ -161,13 +231,17 @@ casper-client get-balance \ ```json { - "id": 6, - "jsonrpc": "2.0", - "method": "state_get_balance", - "params": { - "purse_uref": "uref-6f4026262a505d5e1b0e03b1e3b7ab74a927f8f2868120cf1463813c19acb71e-007", - "state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3" + "jsonrpc": "2.0", + "method": "query_balance", + "params": { + "state_identifier": { + "StateRootHash": "a306a9cf869e52fe9eacdc28aade94215112cc04b6737b3669c35568a47a7dc2" + }, + "purse_identifier": { + "main_purse_under_public_key": "01360af61b50cdcb7b92cffe2c99315d413d34ef77fadee0c105cc4f1d4120f986" } + }, + "id": 6 } ``` @@ -175,13 +249,12 @@ casper-client get-balance \ ```json { - "id": 6, - "jsonrpc": "2.0", - "result": { - "api_version": "1.0.0", - "balance_value": "5000000000", - "merkle_proof": "2502 chars" - } + "jsonrpc": "2.0", + "result": { + "api_version": "1.5.2", + "balance": "164000000000" + }, + "id": 6 } ``` diff --git a/source/docs/casper/resources/beginner/upgrade-contract.md b/source/docs/casper/resources/beginner/upgrade-contract.md index 724fb52b7a..3a1a4d40ac 100644 --- a/source/docs/casper/resources/beginner/upgrade-contract.md +++ b/source/docs/casper/resources/beginner/upgrade-contract.md @@ -141,7 +141,7 @@ For the simple example counter above, here are the [corresponding tests](https:/ You could store the latest version of the contract package under a NamedKey, as shown [here](https://github.com/casper-ecosystem/counter/blob/57e3912735f93e1d0f667b936675964ecfdc6594/contract-v1/src/main.rs#L107). Then, you can query the NamedKey to check the latest version of the contract package.
-Example test function +Example test function ```rust // Verify the contract version is now 2. @@ -186,7 +186,7 @@ casper-client query-global-state \ ```
-Example output +Example output ```rust { @@ -248,7 +248,7 @@ casper-client query-global-state \ --key [ACCOUNT_HASH] -q "version" ```
-Example output +Example output ```rust { @@ -278,7 +278,7 @@ casper-client query-global-state \ --key [ACCOUNT_HASH] -q "counter_package_name" ```
-Example output +Example output ```rust { diff --git a/source/docs/casper/resources/build-on-casper.md b/source/docs/casper/resources/build-on-casper.md index c2a7aff0fd..afcebc98ae 100644 --- a/source/docs/casper/resources/build-on-casper.md +++ b/source/docs/casper/resources/build-on-casper.md @@ -24,7 +24,7 @@ The Casper Ecosystem is growing every day through the addition of new dApps and - [Ledger](https://support.ledger.com/hc/en-us/articles/4416379141009-Casper-CSPR-?docs=true) - [Tor.us](https://casper.tor.us) - [Casper Wallet](https://www.casperwallet.io) -- [Metamask Flask](https://metamask.io/flask/) with [Casper Snap](https://github.com/casper-ecosystem/casper-manager) +- [Metamask](https://metamask.io/) with [Casper Snap](https://github.com/casper-ecosystem/casper-manager) ### Block Explorers - [cspr.live](https://cspr.live) diff --git a/source/docs/casper/resources/casper-open-source-software.md b/source/docs/casper/resources/casper-open-source-software.md index bc663d89f7..c12ac235f7 100644 --- a/source/docs/casper/resources/casper-open-source-software.md +++ b/source/docs/casper/resources/casper-open-source-software.md @@ -62,3 +62,5 @@ Name | Description | Author | Language | License | Last Update Date | Type [ServicesDAO](https://github.com/EKON-YAZILIM/ServicesDAO) | The ServicesDAO portal provides a platform for the service DAOs which provide services in a decentralized manner through a modular implementation of MVPR. | Ekon Yazilim | HTML-CSS-C# | MIT license | 2022-09-13 | DAO [Uniswap DemoApp](https://github.com/Rengo-Labs/CasperLabs-Uniswap-DemoApp) | Uniswap UI + Contracts | Rengo Labs | JavaScript | GPL-3.0 license | 2022-09-15 | DeFi [Verified Impact NFT](https://github.com/AdelElMessiry/Verified-Impact-NFTs) | An NFT platform dedicated to impact causes with verification of the beneficiaries | AlphaFin | JavaScript-Rust | MIT license | 2022-07-08 | NFT +[UseWallet](https://usewallet.casperdash.io) | useWallet is a collection of React Hooks containing everything you need to start working with a Casper network | CasperDash | Typescript-React | MIT license | 2023-09-19 | dApp library +[Testnet Faucet](https://faucet.casperdash.io) | A faucet is a Casper tool that distributes Testnet tokens to anyone requesting them for free | CasperDash | Typescript-React | MIT license | 2023-09-19 | Tools diff --git a/source/docs/casper/resources/index.md b/source/docs/casper/resources/index.md index ba80e7f8f6..08ff288d08 100644 --- a/source/docs/casper/resources/index.md +++ b/source/docs/casper/resources/index.md @@ -10,6 +10,12 @@ | [Developer tools](./build-on-casper.md#development-tools) | Available development tools | | [Ecosystem Projects](./casper-open-source-software.md) | Explore some open-source code available in the Casper ecosystem | +## Move to Casper + +| Topic | Description | +| ----------------------------------------------------------- | ---------------------------------------------------------------- | +| [Move to Casper](./moving-to-casper.md) | Learn how to start working with Casper, having previous knowledge of other blockchains | + ## Tutorials | Topic | Description | diff --git a/source/docs/casper/resources/moving-to-casper.md b/source/docs/casper/resources/moving-to-casper.md new file mode 100644 index 0000000000..b68bcfad50 --- /dev/null +++ b/source/docs/casper/resources/moving-to-casper.md @@ -0,0 +1,314 @@ +--- +title: Move to Casper +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Moving to Casper from another Blockchain {#moving-to-casper} + +This page covers various considerations for moving to Casper from another blockchain by comparing Casper to Ethereum, Near, Aptos, and Solana in these aspects: + +1. [Smart Contract Platform Overview](#contract-overview) +2. [Variable Storage and State Management](#variable-storage) +3. [Contract Functions](#contract-functions) +4. [Passing Arguments](#passing-arguments) + +Since other blockchain projects use different technologies, it is essential to consider how those technologies serve your use case. + +When choosing a blockchain, it is also essential to compare consensus mechanisms, tokenomics, cross-contract capabilities, contract upgradability, and software development kits (SDKs) as described [here](#additional-considerations). + +## Smart Contract Platform {#contract-overview} + + + + +Casper smart contracts are written in Rust. + +Variables defined within the smart contract can be stored as either [Named Keys](../developers/json-rpc/types_chain.md#namedkey) or [Dictionaries](../concepts/dictionaries.md) as described in [Reading and Writing Data to the Blockchain](../concepts/design/reading-and-writing-to-the-blockchain.md). + +The `call` function serves as the main entry point of the [smart contract](../developers/writing-onchain-code/simple-contract.md). It automatically executes when the smart contract is installed, setting the initial state of the contract and defining all other entry points. + +It's worth noting that Casper only supports public entry points for contracts. Additionally, contracts can be defined as upgradable or immutable as described [here](../developers/writing-onchain-code/upgrading-contracts.md). + + + + +Ethereum smart contracts are primarily written in Solidity, a programming language specifically designed for this purpose. These contracts comprise a collection of global variables that persist on the blockchain and define the contract's state. + +Furthermore, Ethereum smart contracts feature a constructor that specifies an initial state after deployment on the blockchain. Public functions declared within the contract can be invoked from outside the blockchain. + +In terms of immutability, Ethereum smart contracts are inherently immutable once deployed. However, design patterns such as "Proxy" or "Diamond" facilitate versioning contracts on the Ethereum blockchain. + +Solidity smart contracts adhere to object-oriented programming principles and support features such as inheritance and libraries. + + + + +Near smart contracts can be written in JavaScript or Rust, and the Near SDK can pack the code with lightweight runtime. This can be compiled into a single WebAssembly file and deployed on the NEAR network. + +In the Near ecosystem, smart contracts function as classes. The constructor, referred to as the "init" method, can receive attributes required for initializing the contract's initial state. + +All public methods defined within the contract serve as its interface, exposing its functionality. + +Near smart contracts are immutable, but their state can change as transactions are executed. Contracts can also be upgraded by deploying new versions of the contract. The Near blockchain provides various capabilities for versioning, including state migrations, state versioning, and contract self-updates. + + + + +The Aptos programming language is known as Move. Its primary concepts revolve around scripts and modules. Scripts enable developers to incorporate additional logic into transactions, while modules allow them to expand blockchain functionality or create custom smart contracts. + +A distinctive feature of Move is the concept of Resources, which are specialized structures representing assets. This design allows resources to be managed similarly to other data types in Aptos, such as vectors or structs. + +A smart contract in the Aptos blockchain is called a Module. It is always connected with an account address. The modules have to be compiled to call functions in the Module. + +The Module's public methods are its interface and can be invoked from code outside the blockchain. + +Module code can be upgraded and changed under the account address, which does not change. The upgrade is only accepted if the code is backward compatible. + + + + +Solana smart contracts are primarily written in Rust. + +Unlike other blockchain platforms, Solana's smart contracts are stateless and solely focus on program logic. The management of the contract state is handled at the account level, separating the state stored within the account and the contract logic defined in the programs. + +Smart contracts are commonly referred to as on-chain programs. These programs expose their interface as a public entry point, allowing external interaction. + +It is worth noting that Solana programs can be updated using an authority known as the "update authority," which holds the necessary permissions for making modifications to the program. + + + + +## Variable Storage and State Management {#variable-storage} + + + + +Variables can be stored as Named Keys or Dictionaries as described in [Reading and Writing Data to the Blockchain](../concepts/design/reading-and-writing-to-the-blockchain.md). + +Additionally, local variables are available within the entry points and can be used to perform necessary actions or computations within the scope of each entry point. + + + + +The variables within the contract are responsible for storing the state of the contract at a specific moment in time. However, it's important to note that local variables used within the call functions are not stored in the contract's state. Instead, they are employed solely for computational purposes within those specific functions. + +State variables must be strongly typed so that the smart contract compiler can enforce type consistency and ensure the storage space aligns with the declared data types. Strong typing promotes code correctness and prevents potential data corruption or memory-related issues related to the contract's state variables. + + + + +Variables in the contract can be stored as native types, SDK collections, or internal structures. SDK collections offer advantages over native types. + +Additionally, there is a distinction between class attributes and local variables. Class attributes represent the state of the contract, while local variables are specific to the invocation of a function and have no impact on the contract's overall state. + +SDK Collections are typical when creating state variables because they provide convenient data structures such as lists, maps, and sets. These data structures can organize and manage complex data within the contract's storage. Using SDK Collections ensures efficient storage and facilitates easier access and data management in the smart contract. + + + + +Aptos employs primitive types, such as integers, booleans, and addresses, to represent variables. These elementary types can be combined to create structures, but it's important to note that struct definitions are only permitted within Modules. + +Aptos advises developers to cluster related data into Resources for efficient data management and organization. Resources represent assets or specific data entities on the blockchain. By grouping data into Resources, you can maintain logical coherence and improve the readability and maintainability of the code. + +The Aptos blockchain introduces a tree-shaped persistent global storage that allows read and write operations. Global storage consists of trees originating from an account address. + + + + +Variables can be utilized locally within the execution context of a specific entry point. They are limited to the scope of that entry point and not accessible outside of it. These variables can be defined as elementary types such as bool, String, int, etc. + +Data persists in structs within the account. The Binary Object Representation Serializer for Hashing (Borsh) facilitates the serialization and deserialization of these structs. The process involves reading the data from the account, deserializing it to obtain the values it contains, updating the values, and then serializing the modified data to save the new values back into the account. + + + + + +## Contract Functions {#contract-functions} + + + + +For Casper smart contracts, public functions are called entry points. To declare them, the following format is used: + +```rust +#[no_mangle] +pub extern "C" fn counter_inc() { + + // Entry point body +} +``` + +It's important to note that entry points do not have input arguments in their definition, but the arguments can be accessed using the [RuntimeArgs](https://docs.rs/casper-types/latest/casper_types/struct.RuntimeArgs.html) passed to the contract. Entry points are instantiated within the `call` entry point. + +If a return value is needed, it should be declared using the syntax described in the [Interacting with Runtime Return Values](../resources/advanced/return-values-tutorial.md) tutorial. + +```rust +runtime::ret(value); +``` + +Each call to an entry point is treated as a [Deploy](../concepts/deploy-and-deploy-lifecycle.md) to the network, and therefore, each call incurs a cost paid in motes (the network's native accounting unit). + + + + +On Ethereum, public methods serve two purposes: they can be used to execute contract logic and modify the contract's state, or they can be utilized to retrieve data stored within the contract's state. + +The declaration of public methods in Ethereum follows the format: + +```bash +function update_name(string value) public { + dapp_name = value; +} +``` + +In cases where a public method only returns a value without modifying the state, it should be defined as follows: + +```bash +function balanceOf(address _owner) public view returns (uint256 return_parameter) { } +``` + +It is worth noting that public view methods on Ethereum, which solely retrieve data without making state changes, do not consume gas. + + + + +In the Near blockchain, there are three types of public functions: + +- **Init Methods** - These are used as the class constructors to initialize the state of the contract. +- **View Methods** - These functions are used to read the state of the contract variables. +- **Call Methods** - These methods can mutate the state of the contract and perform specific actions, such as calling another contract. + +The definition of public methods in Near is as follows: + +```rust +pub fn add_message(&mut self, ...) { } +``` + +For public methods that return variables, the definition would be: + +```rust +pub fn get_messages(&self, from_index: Option, limit: Option) -> Vec { } +``` + +The actual implementation of the functions may include the necessary parameters and logic based on the contract's specific requirements. + + + + +Public functions in Aptos are similar to public methods or functions found in other blockchain networks. The definition of a public function in Aptos appears as follows: + +```rust +public fun start_collection(account: &signer) {} +``` + +For public functions that return variables, the definition would be as follows: + +```rust +public fun max(a: u8, b: u8): (u8, bool) {} +``` + +In the Aptos blockchain, it is possible to return one or more values from a function. + + + + +In Solana, functions are defined as public entry points that act as interfaces visible to the network. The declaration of an entry point follows this format: + +```rust +entrypoint!(process_instruction); +``` + +The implementation of the entry point may resemble the following: + +```rust +pub fn process_instruction( + program_id: &Pubkey, + accounts: &[AccountInfo], + _instruction_data: &[u8], +) -> ProgramResult {} +``` + +Within the entry point function, the necessary parameters are specified, such as `program_id`, which represents the program's identifier, `accounts`, an array of `AccountInfo` providing account details, and `_instruction_data`, representing the instruction data received. The function returns a `ProgramResult`, which indicates the success or failure of the instruction execution. + + + + +## Passing Arguments {#passing-arguments} + + + + + +Named arguments are passed as strings with type specifiers. To provide session arguments to the entry point during a Deploy, you can utilize the following approach: + +```bash +casper-client put-deploy \ + --node-address http://65.21.235.219:7777 \ + --chain-name casper-test \ + --secret-key [KEY_PATH]/secret_key.pem \ + --payment-amount 2500000000 \ + --session-hash hash-93d923e336b20a4c4ca14d592b60e5bd3fe330775618290104f9beb326db7ae2 \ + --session-entry-point "delegate" \ + --session-arg "validator:public_key='0145fb72c75e1b459839555d70356a5e6172e706efa204d86c86050e2f7878960f'" \ + --session-arg "amount:u512='500000000000'" \ + --session-arg "delegator:public_key='0154d828baafa6858b92919c4d78f26747430dcbecb9aa03e8b44077dc6266cabf'" +``` + +To understand the context of this example, refer to: [Delegating with the Casper Client](../developers/cli/delegate.md). + +In the contract, you can access the session arguments as follows: + +```bash +let uref: URef = runtime::get_key(Key_Name) +``` + +Use the `get_key` function to retrieve the desired session argument by specifying the key's name. + +If you are uncertain how to use the `get_key` function to obtain a specific session argument, check how to [write a basic smart contract on Casper](../developers/writing-onchain-code/simple-contract.md). + + + + +Ethereum uses strongly typed function arguments, and developers must explicitly define the input and return variables. The compiler checks the correctness of the arguments passed to the functions during runtime. As a result, developers must explicitly specify the argument and return types in the function signature. The compiler ensures that the provided arguments adhere to the specified types, helping to catch type-related errors and ensure type safety. + +By enforcing strong typing, the compiler helps prevent potential runtime errors and enhances code reliability by verifying the compatibility of the passed arguments and expected return types. + + + + +Strongly typed function arguments require explicitly defining the input and return variables. By enforcing strong typing, the programming language ensures that the arguments passed to a function match the expected types, preventing type-related errors and promoting code correctness. Strong typing provides additional clarity and safety by explicitly stating the data types of the function's inputs and outputs. + + + + +Like Near, Aptos requires strongly typed function arguments, thus preventing type-related errors and promoting code correctness. + + + + +Like Near and Aptos, Solana requires strongly typed function arguments, thus preventing type-related errors and promoting code correctness. + + + + + +## Additional Considerations {#additional-considerations} + +When choosing a blockchain, you may also look into the network's consensus mechanism, the tokenomics or economic model, cross-contract communication, smart contract upgrades, and the available software development kits (SDKs). + +1. **Consensus mechanism** refers to the algorithm the blockchain network uses to achieve agreement on the validity and ordering of transactions. Different blockchains employ various consensus mechanisms such as Proof-of-Work (PoW), Proof-of-Stake (PoS), or Delegated Proof-of-Stake (DPoS). The choice of consensus mechanism impacts factors like security, scalability, and energy efficiency. + +2. **Tokenomics** relates to the economic model of the blockchain network and its native tokens, involving token distribution, inflation, utility, and governance. Understanding the tokenomics of the network is crucial for evaluating the ecosystem's long-term viability and potential value. + +3. **Cross-contract capabilities** refer to the ability of smart contracts to interact and communicate within the blockchain network. This feature is essential for building complex decentralized applications (dApps) and implementing inter-contract functionality. + +4. **Contract upgradability** determines whether the smart contracts installed on the network can be modified or updated after installation. It is essential to assess the flexibility of the chosen blockchain in terms of contract maintenance, bug fixes, and incorporating new features or improvements without disrupting the existing ecosystem. + +5. **SDK availability** also plays a significant role in the development process. SDKs provide tools, libraries, and documentation to simplify the creation of applications and smart contracts on the blockchain. Evaluating the maturity, community support, and compatibility of the available SDKs is crucial for developers. + +Considering these aspects helps when selecting a blockchain that aligns with a project or application's specific requirements and goals. + +The Casper ecosystem aims to fulfill all of these aspects, including supporting enterprise-grade projects. \ No newline at end of file diff --git a/src/assets/scss/_global.scss b/src/assets/scss/_global.scss index 8670bd44b4..4b88d958cd 100644 --- a/src/assets/scss/_global.scss +++ b/src/assets/scss/_global.scss @@ -236,3 +236,51 @@ html { font-size: 26px; } } + +// Fix for low readability. +// See: https://github.com/casper-network/docs/issues/1287. +// +.main-wrapper { + font: var(--ifm-font-size-base)/var(--ifm-line-height-base) var(--ifm-font-family-base); + + h1, h2, h3, h4, h5, h6 { + font-family: var(--ifm-heading-font-family); + font-weight: var(--ifm-heading-font-weight); + line-height: var(--ifm-heading-line-height); + } + + h1 { + font-size: var(--ifm-h1-font-size) + } + + h2 { + font-size: var(--ifm-h2-font-size) + } + + h3 { + font-size: var(--ifm-h3-font-size) + } + + h4 { + font-size: var(--ifm-h4-font-size) + } + + h5 { + font-size: var(--ifm-h5-font-size) + } + + h6 { + font-size: var(--ifm-h6-font-size) + } + + .menu__list { + .menu__link { + font-size: inherit !important; + } + + .menu__link--sublist { + letter-spacing: inherit !important; + font-size: inherit !important; + } + } +} diff --git a/static/image/package-representation-extended.png b/static/image/package-representation-extended.png new file mode 100644 index 0000000000..a2dae97568 Binary files /dev/null and b/static/image/package-representation-extended.png differ diff --git a/static/image/transfers/transfer-hash-example.png b/static/image/transfers/transfer-hash-example.png new file mode 100644 index 0000000000..e9e0d82f50 Binary files /dev/null and b/static/image/transfers/transfer-hash-example.png differ