Skip to content

Commit

Permalink
Document override functionality for eth_call and eth_estimateGas (#…
Browse files Browse the repository at this point in the history 
…1756)

* Add state override documentation.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Add example.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Address reviewer feedback.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Apply suggestions from code review

Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com>
Signed-off-by: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com>

---------

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>
Signed-off-by: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com>
Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com>
  • Loading branch information
@bgravenorst @alexandratran
bgravenorst and alexandratran authored Jan 13, 2025
1 parent 167f387 commit de72fff
Show file tree
Hide file tree
Showing 3 changed files with 115 additions and 48 deletions.
39 changes: 22 additions & 17 deletions docs/public-networks/how-to/send-transactions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,18 @@ tags:

# Create and send transactions

You can send signed transactions using the [`eth_sendRawTransaction`](../reference/api/index.md#eth_sendrawtransaction) JSON-RPC API method.
You can send signed transactions using the [`eth_sendRawTransaction`](../reference/api/index.md#eth_sendrawtransaction)
JSON-RPC API method.
Signed transactions can be simple value transfers, contract creation, or contract invocation. Set the
maximum transaction fee for transactions using the [`--rpc-tx-feecap`](../reference/cli/options.md#rpc-tx-feecap) CLI option.

Signed transactions can be simple value transfers, contract creation, or contract invocation. Set the maximum transaction fee for transactions using the [`--rpc-tx-feecap`](../reference/cli/options.md#rpc-tx-feecap) CLI option.
[Use client libraries](develop/client-libraries.md) to create and send a signed raw transaction to
transfer Ether and create a smart contract.

To accept signed transactions from remote connections, set the [API listening host](use-besu-api/index.md#service-hosts) to `0.0.0.0`.

[Use client libraries](develop/client-libraries.md) to create and send a signed raw transaction to transfer Ether and create a smart contract.
To accept signed transactions from remote connections, set the [API listening host](use-besu-api/index.md#service-hosts)
to `0.0.0.0`. Setting the listening host to `0.0.0.0` exposes the API service connection on your node to
any remote connection. In a production environment, ensure you are using a firewall to avoid exposing
your node to the internet.

:::danger Private keys

Expand All @@ -26,18 +31,6 @@ In production environments avoid exposing your private keys by creating signed t

:::

:::caution

Setting the [listening host](use-besu-api/index.md#service-hosts) to `0.0.0.0` exposes the API service connection on your node to any remote connection. In a production environment, ensure you are using a firewall to avoid exposing your node to the internet.

:::

:::tip

Libraries such as [web3j](https://github.com/web3j/web3j) or [ethereumj](https://github.com/ethereum/ethereumj) and tools such as [MyCrypto](https://mycrypto.com/) can also create signed transactions.

:::

## `eth_call` vs `eth_sendRawTransaction`

You can interact with contracts using [`eth_call`](../reference/api/index.md#eth_call) or [`eth_sendRawTransaction`](../reference/api/index.md#eth_sendrawtransaction). The table below compares the characteristics of both calls.
Expand All @@ -51,6 +44,18 @@ You can interact with contracts using [`eth_call`](../reference/api/index.md#eth
| Synchronous | Asynchronous |
| Returns the value of a contract function available immediately | Returns transaction hash only. A block might not include all possible transactions (for example, if the gas price is too low). |

## Override state values

Use [`eth_call`](../reference/api/index.md#eth_call) to override an account with temporary state values before
making the call. This allows you to make temporary state changes without affecting the actual
blockchain state, and provides the following benefits:

- Minimizes the amount of contract code required to be deployed onchain. Code that returns
internal state or performs predefined validations can be kept offchain and provided to the node on demand.
- Extends and invokes custom methods on deployed contracts for analysis and debugging, avoiding
the need to reconstruct the entire state in a sandbox, and allowing selective state or code
overrides to observe execution changes.

## Use wallets for key management

Besu doesn't support key management inside the client. Use:
Expand Down
100 changes: 74 additions & 26 deletions docs/public-networks/reference/api/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2277,14 +2277,9 @@ By default, the `eth_call` error response includes the [revert reason](../../../
- `call`: _object_ - [transaction call object](objects.md#transaction-call-object)
:::note
The [`strict` parameter](objects.md#transaction-call-object) determines if the sender account balance is checked:
* If `strict:true`, the balance is checked and `eth_call` fails if the sender account has an insufficient balance to send the transaction with the specified gas parameters.
* If `strict:false`, the balance is not checked and `eth_call` can succeed even if the sender account has an insufficient balance.
* If `strict` is not specified, the balance is checked against the gas parameters if supplied.
If you do not want the sender account balance checked, send zero gas or specify `strict:false`.
If you don't want the sender account balance checked, set the gas to zero or specify
[`strict:false`](objects.md#transaction-call-object). Otherwise the call may fail if the sender account
does not have sufficient funds to cover the gas fees.
:::
- `blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number,
Expand All @@ -2295,6 +2290,11 @@ By default, the `eth_call` error response includes the [revert reason](../../../
`pending` returns the same value as `latest`.
:::
- `stateOverride`: _object_ - (optional) The [address-to-state mapping](./objects.md#state-override-object).
Each entry specifies a state that will be temporarily overridden before executing the call.
This allows you to test, analyze, and debug smart contracts more efficiently by allowing
temporary state changes without affecting the actual blockchain state.
#### Returns
`result`: _string_ - return value of the executed contract
Expand Down Expand Up @@ -2381,9 +2381,9 @@ curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block {num
</Tabs>
:::info Example of a simulated contract creation
The following example creates a simulated contract by not including the `to` parameter from the [transaction call object](objects.md#transaction-call-object) in the `call` parameter. Besu simulates the data to create the contract.
The following example creates a simulated contract by not including the `to` parameter from the
[transaction call object](objects.md#transaction-call-object) in the `call` parameter.
Besu simulates the data to create the contract.
<Tabs>
Expand All @@ -2409,7 +2409,33 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"from":"0xf
</Tabs>
:::
The following example checks the USDT contract for the balance of the address `0xfe3b557e8fb62b89f4916b721be55ceb828dbd73`, with
a state override that sets the balance to 20,000 USDT. The result will reflect the overridden balance
for the specified address.
<Tabs>
<TabItem value="curl HTTP" label="curl HTTP" default>
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0xdAC17F958D2ee523a2206206994597C13D831ec7","data":"0x70a08231000000000000000000000000fe3b557e8fb62b89f4916b721be55ceb828dbd73"},"latest",{"0xdAC17F958D2ee523a2206206994597C13D831ec7":{"stateDiff":{"0xd0dd44a13782bf89714335c2b2b08ecb7c074e78a161807742c578965dda1b56":"0x0000000000000000000000000000000000000000000000000000000000004E20"}}}],"id":1}' http://127.0.0.1:8545
```
</TabItem>
<TabItem value="JSON result" label="JSON result">
```json
{
"jsonrpc":"2.0",
"id":1,
"result":"0x0000000000000000000000000000000000000000000000000000000000004e20"
}
```
</TabItem>
</Tabs>
### `eth_chainId`
Expand Down Expand Up @@ -2589,9 +2615,14 @@ By default, the `eth_estimateGas` error response includes the [revert reason](..
#### Parameters
For `eth_estimateGas`, all fields are optional because setting a gas limit is irrelevant to the estimation process (unlike transactions, in which gas limits apply).
For `eth_estimateGas`, all fields are optional because setting a gas limit is irrelevant to the
estimation process (unlike transactions, in which gas limits apply).
`call`: _object_ - [transaction call object](objects.md#transaction-call-object)
- `call`: _object_ - [transaction call object](objects.md#transaction-call-object)
- `stateOverride`: _object_ - The [address-to-state mapping](./objects.md#state-override-object).
Each entry specifies a state that will be temporarily overridden before executing the call.
This allows you to make temporary state changes without affecting the actual blockchain state.
#### Returns
Expand Down Expand Up @@ -2683,18 +2714,7 @@ The following example request estimates the cost of deploying a simple storage s
<TabItem value="curl HTTP request" label="curl HTTP request" default>
```bash
curl -X POST \
http://127.0.0.1:8545 \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"method": "eth_estimateGas",
"params": [{
"from": "0x8bad598904ec5d93d07e204a366d084a80c7694e",
"data": "0x608060405234801561001057600080fd5b5060e38061001f6000396000f3fe6080604052600436106043576000357c0100000000000000000000000000000000000000000000000000000000900480633fa4f24514604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b806000819055505056fea165627a7a7230582020d7ad478b98b85ca751c924ef66bcebbbd8072b93031073ef35270a4c42f0080029"
}],
"id": 1
}'
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0x8bad598904ec5d93d07e204a366d084a80c7694e","data":"0x608060405234801561001057600080fd5b5060e38061001f6000396000f3fe6080604052600436106043576000357c0100000000000000000000000000000000000000000000000000000000900480633fa4f24514604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b806000819055505056fea165627a7a7230582020d7ad478b98b85ca751c924ef66bcebbbd8072b93031073ef35270a4c42f0080029"}],"id":1}' http://127.0.0.1:8545
```
</TabItem>
Expand All @@ -2713,6 +2733,34 @@ http://127.0.0.1:8545 \
</Tabs>
The following example estimates the gas required for the `transfer` call in the USDT contract, with a state
override that sets the balance of the sender address to 20,000 USDT. The result provides the gas required
for the transaction.
<Tabs>
<TabItem value="curl HTTP request" label="curl HTTP request" default>
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to":"0xdAC17F958D2ee523a2206206994597C13D831ec7","data":"0xa9059cbb000000000000000000000000627306090abaB3A6e1400e9345bC60c78a8BEf570000000000000000000000000000000000000000000000000000000000000064"},"latest",{"0xdAC17F958D2ee523a2206206994597C13D831ec7":{"stateDiff":{"0xd0dd44a13782bf89714335c2b2b08ecb7c074e78a161807742c578965dda1b56":"0x0000000000000000000000000000000000000000000000000000000000004E20"}}}],"id":1}' http://127.0.0.1:8545
```
</TabItem>
<TabItem value="JSON result" label="JSON result">
```json
{
"jsonrpc":"2.0",
"id":1,
"result":"0xfa07"
}
```
</TabItem>
</Tabs>
### `eth_feeHistory`
Returns base fee per gas and transaction effective priority fee per gas history for the requested block
Expand Down
24 changes: 19 additions & 5 deletions docs/public-networks/reference/api/objects.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,15 +114,15 @@ Returned by [`txpool_besuPendingTransactions`](index.md#txpool_besupendingtransa
| `accessList` | Array | (Optional) List of addresses and storage keys the transaction plans to access. Used in [`ACCESS_LIST` transactions](../../concepts/transactions/types.md#access_list-transactions) and may be used in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `from` | Data, 20&nbsp;bytes | Address of the sender. |
| `gas` | Quantity | Gas provided by the sender. |
| `gasPrice` | Quantity | (Optional) Gas price, in Wei, provided by the sender. Not used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `maxPriorityFeePerGas` | Quantity, Integer | (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `maxFeePerGas` | Quantity, Integer | (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `gasPrice` | Quantity | (Optional) Gas price, in wei, provided by the sender. Not used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `maxPriorityFeePerGas` | Quantity, Integer | (Optional) Maximum fee, in wei, the sender is willing to pay per gas above the base fee. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `maxFeePerGas` | Quantity, Integer | (Optional) Maximum total fee (base fee + priority fee), in wei, the sender is willing to pay per gas. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). |
| `hash` | Data, 32&nbsp;bytes | Hash of the transaction. |
| `input` | Data | Data sent with the transaction to create or invoke a contract. |
| `nonce` | Quantity | Number of transactions made by the sender before this one. |
| `to` | Data, 20&nbsp;bytes | Address of the receiver. `null` if a contract creation transaction. |
| `transactionType` | String | [Transaction type](../../concepts/transactions/types.md). |
| `value` | Quantity | Value transferred, in Wei. |
| `value` | Quantity | Value transferred, in wei. |
| `v` | Quantity | ECDSA Recovery ID. |
| `r` | Data, 32&nbsp;bytes | ECDSA signature r. |
| `s` | Data, 32&nbsp;bytes | ECDSA signature s. |
Expand All @@ -136,7 +136,21 @@ Returned by [`debug_storageRangeAt`](index.md#debug_storagerangeat).
| `storage` | Object | Key hash and value. Pre-image key is `null` if it falls outside the cache. |
| `nextKey` | Hash | Hash of next key if further storage in range. Otherwise, not included. |

### Structured log object
## State override object

Optional parameter for [`eth_call`](./index.md#eth_call) and [`eth_estimateGas`](./index.md#eth_estimategas).
Override an account with the following state values temporarily before making the call. This allows you
to make ephemeral state changes, for the purposes of transaction simulation, without affecting the actual
blockchain state.

| Key | Type | Value |
|-------------|:--------:|------------------------------------------------------------------------|
| `balance` | Quantity | Temporary account balance for the call execution. |
| `nonce` | Quantity | Temporary nonce value for the call execution. |
| `code` | Binary | Bytecode to inject into the account. |
| `stateDiff` | Quantity | `key:value` pairs to override individual slots in the account storage. |

## Structured log object

Log information returned as part of the [Trace object](#trace-object).

Expand Down

0 comments on commit de72fff

Please sign in to comment.