From 336379518150ad69e1fb0670c2a14e8b3bd96c7c Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 3 Feb 2025 23:04:52 -0800 Subject: [PATCH 1/4] Document truststore options Signed-off-by: Alexandra Tran --- docs/public-networks/reference/cli/options.md | 82 ++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index b14f547d88..4de9493657 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -4194,7 +4194,7 @@ rpc-http-tls-keystore-file="/home/me/me_node/keystore.pfx" -The Keystore file (in PKCS #12 format) that contains private key and the certificate presented to the client during authentication. +The keystore file (in PKCS #12 format) that contains private key and the certificate presented to the client during authentication. ### `rpc-http-tls-keystore-password-file` @@ -4330,6 +4330,86 @@ The singular `--rpc-http-tls-protocol` and plural `--rpc-http-tls-protocols` are ::: +### `rpc-http-tls-truststore-file` + + + + + +```bash +--rpc-http-tls-truststore-file= +``` + + + + + +```bash +--rpc-http-tls-truststore-file=/home/me/me_node/truststore.pfx +``` + + + + + +```bash +BESU_RPC_HTTP_TLS_TRUSTSTORE_FILE=/home/me/me_node/truststore.pfx +``` + + + + + +```bash +rpc-http-tls-truststore-file="/home/me/me_node/truststore.pfx" +``` + + + + + +The path to the truststore file used for authentication. + +### `rpc-http-tls-truststore-password-file` + + + + + +```bash +--rpc-http-tls-truststore-password-file= +``` + + + + + +```bash +--rpc-http-tls-truststore-password-file=/home/me/me_node/password +``` + + + + + +```bash +BESU_RPC_HTTP_TLS_TRUSTSTORE_PASSWORD_FILE=/home/me/me_node/password +``` + + + + + +```bash +rpc-http-tls-truststore-password-file="/home/me/me_node/password" +``` + + + + + +The path to the file containing the password to decrypt the truststore. + ### `rpc-max-logs-range` From 9fce7700b51ffb69bce3393a52aed64758d1e9d4 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Tue, 4 Feb 2025 13:07:55 -0800 Subject: [PATCH 2/4] add more context to descriptions Signed-off-by: Alexandra Tran --- docs/public-networks/reference/cli/options.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 4de9493657..5943a31029 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -4194,7 +4194,10 @@ rpc-http-tls-keystore-file="/home/me/me_node/keystore.pfx" -The keystore file (in PKCS #12 format) that contains private key and the certificate presented to the client during authentication. +Path to the keystore file (in PKCS #12 format) when enabling TLS for the JSON-RPC HTTP service. +The keystore file contains the private key and certificate presented to the client during authentication. + +Specify the keystore password file using [`--rpc-http-tls-keystore-password-file`](#rpc-http-tls-keystore-password-file). ### `rpc-http-tls-keystore-password-file` @@ -4234,7 +4237,8 @@ rpc-http-tls-keystore-password-file="/home/me/me_node/password" -The path to the file containing the password to decrypt the keystore. +Path to the file containing the password for the keystore specified in [`--rpc-http-tls-keystore-file`](#rpc-http-tls-keystore-file), +when enabling TLS for the JSON-RPC HTTP service. ### `rpc-http-tls-known-clients-file` @@ -4274,7 +4278,7 @@ rpc-http-tls-known-clients-file="/home/me/me_node/knownClients" -The path to the file used to [authenticate clients](../../../private-networks/how-to/configure/tls/client-and-server.md#create-the-known-clients-file) using self-signed certificates or non-public certificates. +Path to the file used to [authenticate clients](../../../private-networks/how-to/configure/tls/client-and-server.md#create-the-known-clients-file) using self-signed certificates or non-public certificates. Must contain the certificate's Common Name, and SHA-256 fingerprint in the format ` `. @@ -4368,7 +4372,9 @@ rpc-http-tls-truststore-file="/home/me/me_node/truststore.pfx" -The path to the truststore file used for authentication. +Path to the truststore file when enabling TLS for the JSON-RPC HTTP service. + +Specify the truststore password file using [`--rpc-http-tls-truststore-password-file`](#rpc-http-tls-truststore-password-file). ### `rpc-http-tls-truststore-password-file` @@ -4408,7 +4414,8 @@ rpc-http-tls-truststore-password-file="/home/me/me_node/password" -The path to the file containing the password to decrypt the truststore. +Path to the file containing the password for the truststore specified in [`--rpc-http-tls-truststore-file`](#rpc-http-tls-truststore-file), +when enabling TLS for the JSON-RPC HTTP service. ### `rpc-max-logs-range` From 70510bcf3799205a4961b2199b078b93e1b68d0b Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 23 Apr 2025 11:30:18 -0700 Subject: [PATCH 3/4] Document `eth_simulateV1` Signed-off-by: Alexandra Tran --- docs/public-networks/reference/api/index.md | 185 ++++++++++++++++++ docs/public-networks/reference/api/objects.md | 40 +++- 2 files changed, 220 insertions(+), 5 deletions(-) diff --git a/docs/public-networks/reference/api/index.md b/docs/public-networks/reference/api/index.md index 22d2ff800b..0c46e5d996 100644 --- a/docs/public-networks/reference/api/index.md +++ b/docs/public-networks/reference/api/index.md @@ -6067,6 +6067,191 @@ mutation { +### `eth_simulateV1` + +Simulates transactions across multiple blocks. Allows you to test transactions with custom state and +block parameters without submitting them to the network. + +#### Parameters + +- `payload`: _object_ - transaction simulation payload object containing the following fields: + + - `blockStateCalls`: _array_ of _objects_ - list of block state call objects, each containing the following fields: + + - `blockOverrides`: _array_ of _objects_ - list of [block override objects](objects.md#block-override-object) + + - `stateOverrides`: _array_ of _objects_ - list of [state override objects](objects.md#state-override-object) + + - `calls`: _array_ of _objects_ - list of [transaction call objects](objects.md#transaction-call-object) + + - `traceTransfers`: _boolean_ - (optional) if `true`, ETH transfers are added as ERC-20 transfer + events to the logs, allowing you to trace value transfers. The default is `false`. + + - `validation`: _boolean_ - (optional) If `true`, `eth_simulateV1` does all the validation that a + normal EVM would do, except contract sender and signature checks. If `false`, `eth_simulateV1` behaves like `eth_call`. + The default is `false`. + + - `returnFullTransactionObjects`: _boolean_ - (optional) If `true`, `eth_simulateV1` returns full transaction + objects. If `false`, `eth_simulateV1` returns only hashes. The default is `false`. + +- `blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, + block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as + described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _objects_ - list of simulation result objects, each containing the following fields: + +- all the fields of a [block object](objects.md#block-object) + +- `calls`: _array_ of _objects_ - list of [call result objects](objects.md#call-result-object) + + + + + +```bash +curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_simulateV1", "params":[{"blockStateCalls":[{"blockOverrides":{"baseFeePerGas":"0x9"},"stateOverrides":{"0xc000000000000000000000000000000000000000":{"balance":"0x4a817c800"}},"calls":[{"from":"0xc000000000000000000000000000000000000000","to":"0xc000000000000000000000000000000000000001","maxFeePerGas":"0xf","value":"0x1"},{"from":"0xc000000000000000000000000000000000000000","to":"0xc000000000000000000000000000000000000002","maxFeePerGas":"0xf","value":"0x1"}]}],"validation":true,"traceTransfers":true},"latest"],"id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json" +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "method": "eth_simultateV1", + "params": [ + { + "blockStateCalls": [ + { + "blockOverrides": { + "baseFeePerGas": "0x9" + }, + "stateOverrides": { + "0xc000000000000000000000000000000000000000": { + "balance": "0x4a817c800" + } + }, + "calls": [ + { + "from": "0xc000000000000000000000000000000000000000", + "to": "0xc000000000000000000000000000000000000001", + "maxFeePerGas": "0xf", + "value": "0x1" + }, + { + "from": "0xc000000000000000000000000000000000000000", + "to": "0xc000000000000000000000000000000000000002", + "maxFeePerGas": "0xf", + "value": "0x1" + } + ] + } + ], + "validation": true, + "traceTransfers": true + }, + "latest" + ], + "id": 1 +} +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "baseFeePerGas": "0x9", + "blobGasUsed": "0x0", + "calls": [ + { + "gasUsed": "0x5208", + "logs": [ + { + "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f", + "blockNumber": "0x1496e50", + "data": "0x0000000000000000000000000000000000000000000000000000000000000001", + "logIndex": "0x0", + "removed": false, + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x000000000000000000000000c000000000000000000000000000000000000000", + "0x000000000000000000000000c000000000000000000000000000000000000001" + ], + "transactionHash": "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51", + "transactionIndex": "0x0" + } + ], + "returnData": "0x", + "status": "0x1" + }, + { + "gasUsed": "0x5208", + "logs": [ + { + "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f", + "blockNumber": "0x1496e50", + "data": "0x0000000000000000000000000000000000000000000000000000000000000001", + "logIndex": "0x1", + "removed": false, + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x000000000000000000000000c000000000000000000000000000000000000000", + "0x000000000000000000000000c000000000000000000000000000000000000002" + ], + "transactionHash": "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa", + "transactionIndex": "0x1" + } + ], + "returnData": "0x", + "status": "0x1" + } + ], + "difficulty": "0x0", + "excessBlobGas": "0x4920000", + "extraData": "0x", + "gasLimit": "0x1c9c380", + "gasUsed": "0xa410", + "hash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "miner": "0x7e2a2fa2a064f693f0a55c5639476d913ff12d05", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0000000000000000", + "number": "0x1496e50", + "parentBeaconBlockRoot": "0x0000000000000000000000000000000000000000000000000000000000000000", + "parentHash": "0xddd47e7383c8ced495e85e053f898d7a333feb0432fa9098306f6f563cde4984", + "receiptsRoot": "0x75308898d571eafb5cd8cde8278bf5b3d13c5f6ec074926de3bb895b519264e1", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x29c", + "stateRoot": "0xd6da11fae4ab94ddba2c4c71206962f7c6eaec6e5fabf00f3f7540c4ed7ad8f1", + "timestamp": "0x67803e64", + "transactions": [ + "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51", + "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa" + ], + "transactionsRoot": "0x9bdb74f3ce41f5893a02a631e904ae0d21ae8c4e416786d8dbd9cb5c54f1dc0f", + "uncles": [], + "withdrawals": [], + "withdrawalsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" + } + ] +} +``` + + + + + ### `eth_submitHashrate` (Deprecated) Submits the mining hashrate. This is used by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer). diff --git a/docs/public-networks/reference/api/objects.md b/docs/public-networks/reference/api/objects.md index cd472a2b48..e23245fdde 100644 --- a/docs/public-networks/reference/api/objects.md +++ b/docs/public-networks/reference/api/objects.md @@ -18,7 +18,7 @@ This reference contains API objects that apply to both public and private networ ## Block object -Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash) and [`eth_getBlockByNumber`](index.md#eth_getblockbynumber). +Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash), [`eth_getBlockByNumber`](index.md#eth_getblockbynumber), and [`eth_simulateV1`](index.md#eth_simulatev1). | Key | Type | Value | | --- | :-: | --- | @@ -43,6 +43,35 @@ Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash) and [`eth_getBlo | `uncles` | Array | Array of uncle hashes. | | `baseFeePerGas` | Quantity | The block's [base fee per gas](../../concepts/transactions/types.md#eip1559-transactions). This field is empty for blocks created before [EIP-1559](https://github.com/ethereum/EIPs/blob/2d8a95e14e56de27c5465d93747b0006bd8ac47f/EIPS/eip-1559.md). | +## Block override object + +Parameter for [`eth_simulateV1`](index.md#eth_simulatev1). +Override the following block parameters temporarily before making the call. +This allows you to make ephemeral block changes, for the purposes of transaction simulation, without affecting the actual blockchain. + +| Key | Type | Value | +|-----------------|:-------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `baseFeePerGas` | Quantity | Base fee per gas for the block. | +| `blobBaseFee` | Quantity | Base fee per unit of blob gas. | +| `feeRecipient` | Data, 20 bytes | Address of the fee recipient for the block proposal. | +| `gasLimit` | Quantity | Maximum gas allowed in this block. | +| `number` | Quantity | Block number. When overriding block numbers across multiple blocks, block number must be increasing. By default, it's incremented by one for each block. | +| `prevRandao` | Data, 32 bytes | Previous value of randomness. | +| `time` | Quantity | Unix epoch time in seconds. Time must increase or remain constant relative to the previous block. By default, it's incremented by one for each block. | +| `withdrawals` | Array | Array of withdrawals made by validators. This array can have a maximum length of 16. | + +## Call result object + +Returned by [`eth_simulateV1`](index.md#eth_simulatev1). +All fields are required. + +| Key | Type | Value | +|--------------|:--------:|-----------------------------------------------------------------------------------------------| +| `returnData` | Data | Data returned for the call. | +| `logs` | Array | Array of [log objects](#log-object) generated during the call. | +| `gasUsed` | Quantity | Amount of gas used by the call. | +| `status` | Quantity | Status indicating whether the call succeeded (`0x1`). `0x0` indicates that a call has failed. | + ## Fee history results object Returned by [`eth_feeHistory`](index.md#eth_feehistory) for the requested block range. If blocks in the specified block range are not available, then only the fee history for available blocks is returned. @@ -75,7 +104,8 @@ Parameter for [`eth_newFilter`](index.md#eth_newfilter), [`eth_getLogs`](index.m ## Log object -Returned by [`eth_getFilterChanges`](index.md#eth_getfilterchanges) and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs). [`Transaction receipt objects`](#transaction-receipt-object) can contain an array of log objects. +Returned by [`eth_getFilterChanges`](index.md#eth_getfilterchanges) and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs). +[Transaction receipt objects](#transaction-receipt-object) and [call result objects](#call-result-object) can contain an array of log objects. | Key | Type | Value | | --- | :-: | --- | @@ -138,12 +168,11 @@ Returned by [`debug_storageRangeAt`](index.md#debug_storagerangeat). ## State override object -Optional parameter for [`eth_call`](./index.md#eth_call) and [`eth_estimateGas`](./index.md#eth_estimategas). +Parameter for [`eth_call`](./index.md#eth_call), [`eth_estimateGas`](./index.md#eth_estimategas), and [`eth_simulateV1`](index.md#eth_simulatev1). 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. | @@ -221,7 +250,8 @@ Returned by [`eth_getTransactionByHash`](index.md#eth_gettransactionbyhash), [`e ## Transaction call object -Parameter for [`eth_call`](index.md#eth_call), [`eth_createAccessList`](index.md#eth_createaccesslist), and [`eth_estimateGas`](index.md#eth_estimategas). +Parameter for [`eth_call`](index.md#eth_call), [`eth_createAccessList`](index.md#eth_createaccesslist), [`eth_estimateGas`](index.md#eth_estimategas), +and [`eth_simulateV1`](index.md#eth_simulatev1). All transaction call object parameters are optional. From 0b0c95c364fb67b64beecee4eb4657dbf87e2496 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Wed, 7 May 2025 10:29:31 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com> Signed-off-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> --- docs/public-networks/reference/api/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/public-networks/reference/api/index.md b/docs/public-networks/reference/api/index.md index 0c46e5d996..5697c83c17 100644 --- a/docs/public-networks/reference/api/index.md +++ b/docs/public-networks/reference/api/index.md @@ -6091,12 +6091,12 @@ block parameters without submitting them to the network. normal EVM would do, except contract sender and signature checks. If `false`, `eth_simulateV1` behaves like `eth_call`. The default is `false`. - - `returnFullTransactionObjects`: _boolean_ - (optional) If `true`, `eth_simulateV1` returns full transaction - objects. If `false`, `eth_simulateV1` returns only hashes. The default is `false`. + - `returnFullTransactionObjects`: _boolean_ - (optional) If `true`, returns full transaction + objects. If `false`, returns only hashes. The default is `false`. - `blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as - described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). #### Returns