Skip to content

Commit

Permalink
Replace state_get_balance with query_balance
Browse files Browse the repository at this point in the history
  • Loading branch information
@ipopescu
ipopescu committed Sep 20, 2023
1 parent bb0ddd2 commit 45c5ad5
Show file tree
Hide file tree
Showing 4 changed files with 193 additions and 149 deletions.
102 changes: 66 additions & 36 deletions source/docs/casper/developers/cli/transfers/verify-transfer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ casper-client get-state-root-hash --node-address [NODE_SERVER_ADDRESS]
"jsonrpc": "2.0",
"result": {
"api_version": "1.4.13",
"state_root_hash": "a1f11692c5adc0e8b0a3f83e34d5831593a39ba03c8be73a0ebf7e9d9aadd76b"
"state_root_hash": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3"
}
}
```
Expand Down Expand Up @@ -250,98 +250,128 @@ casper-client query-global-state \

</details>

## Get Purse Balance {#get-purse-balance}
## Query 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 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 `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:

```bash
casper-client query-balance --help
```

Now that we have the source purse address, we can verify its balance using the `get-balance` command:

```bash
casper-client get-balance \
casper-client query-balance \
--id 6 \
--node-address http://<node-ip-address>:7777 \
--state-root-hash <state-root-hash> \
--purse-uref <source-account-purse-uref>
--purse-identifier <source-account>
```

**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` - Hex-encoded hash of the state root
- `purse-uref` - The URef under which the purse is stored, following the format "uref-<hex_value>".
- `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.

**Query Source Account Example:**

```bash
casper-client query-balance -v --id 6 \
--node-address http://<node-ip-address>:7777 \
--state-root-hash cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3 \
--purse-identifier account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5
```

<details>
<summary>Explore the JSON-RPC request and response generated.</summary>
<summary>Explore the sample JSON-RPC request and response generated.</summary>

**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": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3"
},
"purse_identifier": {
"main_purse_under_account_hash": "account-hash-b0049301811f23aab30260da66927f96bfae7b99a66eb2727da23bf1427a38f5"
}
},
"id": 6
}
```

**JSON-RPC Response**:

```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
}
```

</details>

Similarly, we have the address of the target purse, so we can get its balance.
Similarly, we have the public key of the target purse, so we can get its balance.

```bash
casper-client get-balance \
--id 7 \
--node-address http://<node-ip-address>:7777 \
--state-root-hash <state-root-hash> \
--purse-uref <target-account-purse-uref>
--purse-identifier <target-account>
```

**Target Account Example:**

```bash
casper-client query-balance -v --id 7 \
--node-address http://<node-ip-address>:7777 \
--state-root-hash cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3 \
--purse-identifier account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668
```

<details>
<summary>Explore the JSON-RPC request and response generated.</summary>
<summary>Explore the sample JSON-RPC request and response generated.</summary>

**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": "cfdbf775b6671de3787cfb1f62f0c5319605a7c1711d6ece4660b37e57e81aa3"
},
"purse_identifier": {
"main_purse_under_account_hash": "account-hash-8ae68a6902ff3c029cea32bb67ae76b25d26329219e4c9ceb676745981fd3668"
}
},
"id": 7
}
```

**JSON-RPC Response**:

```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.2",
"balance": "5000000000"
},
"id": 7
}
```

Expand Down
61 changes: 1 addition & 60 deletions source/docs/casper/developers/json-rpc/json-rpc-informational.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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|
|---------|----|-----------|
Expand Down Expand Up @@ -829,65 +829,6 @@ This method returns a JSON representation of an [Account](../../concepts/design/

</details>

## 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.|

<details>
<summary>Example state_get_balance request</summary>

```bash

{
"id": 1,
"jsonrpc": "2.0",
"method": "state_get_balance",
"params": [
"uref-09480c3248ef76b603d386f3f4f8a5f87f597d4eaffd475433f861af187ab5db-007",
"0808080808080808080808080808080808080808080808080808080808080808"
]
}

```

</details>

### `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.|

<details>
<summary>Example state_get_balance result</summary>

```bash

{
"id": 1,
"jsonrpc": "2.0",
"result": {
"api_version": "1.4.13",
"balance_value": "123456",
"merkle_proof": "01000000006ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a72536147614625016ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a72536147614625000000003529cde5c621f857f75f3810611eb4af3f998caaa9d4a3413cf799f99c67db0307010000006ef2e0949ac76e55812421f755abe129b6244fe7168b77f47a7253614761462501010102000000006e06000000000074769d28aac597a36a03a932d4b43e4f10bf0403ee5c41dd035102553f5773631200b9e173e8f05361b681513c14e25e3138639eb03232581db7557c9e8dbbc83ce94500226a9a7fe4f2b7b88d5103a4fc7400f02bf89c860c9ccdd56951a2afe9be0e0267006d820fb5676eb2960e15722f7725f3f8f41030078f8b2e44bf0dc03f71b176d6e800dc5ae9805068c5be6da1a90b2528ee85db0609cc0fb4bd60bbd559f497a98b67f500e1e3e846592f4918234647fca39830b7e1e6ad6f5b7a99b39af823d82ba1873d000003000000010186ff500f287e9b53f823ae1582b1fa429dfede28015125fd233a31ca04d5012002015cc42669a55467a1fdf49750772bfc1aed59b9b085558eb81510e9b015a7c83b0301e3cf4a34b1db6bfa58808b686cb8fe21ebe0c1bcbcee522649d2b135fe510fe3"
}
}

```

</details>

## 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.
Expand Down
4 changes: 2 additions & 2 deletions source/docs/casper/developers/json-rpc/minimal-compliance.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ 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. The deprecated method `state_get_balance` should not be used.

* [`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.

Expand Down
Loading

0 comments on commit 45c5ad5

Please sign in to comment.