Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document override functionality for eth_call and eth_estimateGas #1756

Merged
merged 7 commits into from
Jan 13, 2025
Merged

Document override functionality for eth_call and eth_estimateGas #1756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5bb224e
Add state override documentation.
bgravenorst Dec 11, 2024
b7a652b
Add example.
bgravenorst Jan 8, 2025
dfd23bf
Merge branch 'main' into DOC-1738
bgravenorst Jan 8, 2025
e5f8099
Merge branch 'main' into DOC-1738
bgravenorst Jan 8, 2025
d828d1d
Address reviewer feedback.
bgravenorst Jan 13, 2025
ec3ba89
Merge branch 'DOC-1738' of https://github.com/bgravenorst/besu-docs i…
bgravenorst Jan 13, 2025
6edbc53
Apply suggestions from code review
bgravenorst Jan 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 22 additions & 17 deletions docs/public-networks/how-to/send-transactions.md
View file
Open in desktop
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.

:::
bgravenorst marked this conversation as resolved.
Show resolved Hide resolved

## `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
Open in desktop
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
Open in desktop
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
Loading