Skip to content

Commit 9333360

Browse files
committed
docs: Add new features
1 parent c4bb37a commit 9333360

File tree

3 files changed

+53
-2
lines changed

3 files changed

+53
-2
lines changed

docs/running_tests/execute/hive.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,20 @@ Tests can be executed on a local hive-controlled single-client network by runnin
44

55
## The `eest/execute-blobs` Simulator
66

7-
The `blob_transaction_test` execute test spec sends blob transactions to a running client in order to verify its `engine_getBlobsVX` endpoint behavior. These tests can be run using:
7+
The `blob_transaction_test` execute test spec sends blob transactions to a running client. Blob transactions are fully supported in execute mode:
8+
9+
- Blob transactions can be sent via `eth_sendRawTransaction`
10+
- Blob validation via `engine_getBlobsVX` endpoints (when Engine RPC available)
11+
- Automatic gas pricing for blob gas fees
12+
13+
Tests can be run using:
814

915
```bash
1016
./hive --client besu --client-file ./configs/osaka.yaml --sim ethereum/eest/execute-blobs
1117
```
1218

19+
**Note**: If Engine RPC is unavailable, blob transactions will be sent but `getBlobsV*` validation is skipped.
20+
1321
See [Hive](../hive/index.md) for help installing and configuring Hive.
1422

1523
## Running `execute` tests with Hive in Dev Mode

docs/running_tests/execute/index.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,12 @@ Reasoning behind the random generation of the sender keys is that one can execut
3939

4040
The `fill` plugin will use a fixed and minimum gas price for all the transactions it uses for testing, but this is not possible with the `execute` plugin, as the gas price is determined by the current state of the network.
4141

42-
At the moment, the `execute` plugin does not query the client for the current gas price, but instead uses a fixed increment to the gas price in order to avoid the transactions to be stuck in the mempool.
42+
The `execute` plugin queries the network for current gas prices and defaults to 1.5x the network price to ensure transaction inclusion. Gas prices can be overridden via command-line flags (`--default-gas-price`, `--default-max-fee-per-gas`, `--default-max-priority-fee-per-gas`).
43+
44+
### Deferred EOA Funding
45+
46+
EOAs are funded after gas prices are determined, enabling accurate balance calculations based on actual network conditions. This ensures sufficient funds are allocated for all test transactions.
47+
48+
### Blob Transaction Support
49+
50+
Blob transactions are fully supported in execute mode, including automatic gas pricing for blob gas fees and validation via `engine_getBlobsVX` endpoints when Engine RPC is available.

docs/running_tests/execute/remote.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,41 @@ One last requirement is that the `--chain-id` flag is set to the chain id of the
2424
uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --rpc-seed-key 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --chain-id 12345
2525
```
2626

27+
## Test Accounts and Contracts
28+
29+
Since `execute remote` does not control the blockchain where it runs the tests, and therefore cannot modify the genesis pre-allocation like `fill` does, all accounts and contracts need to be deployed via transactions sent to the network.
30+
31+
These transactions are created from the seed or worker accounts provided via the command flags.
32+
33+
When the test is executed, all instances of `pre.fund_eoa` and `pre.deploy_contract` calls, instead of placing the account directly in the `pre` object like `fill` does, they generate transactions that result in the creation of the accounts when executed on chain.
34+
35+
The transactions are collected and only sent after the test function finishes execution. This is done in order to perform optimizations based on the transactions that the test requires to perform its verifications.
36+
37+
One optimization is the deferred calculation of the funding amount for the EOA, which is calculated on the fly depending the test transactions that use the account as sender, and this amount is the minimum balance that the account would need in order for the transactions to be included given the current network gas prices.
38+
39+
### Dry Run Mode
40+
41+
Calculate minimum balance requirements without executing any transactions on chain:
42+
43+
```bash
44+
uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --dry-run ./tests/prague/eip7702_set_code_tx/
45+
```
46+
47+
This outputs the minimum balance needed and total gas consumption per test, useful for:
48+
- Estimating costs before execution
49+
- Verifying seed account has sufficient funds
50+
- Planning parallel execution funding requirements
51+
52+
### Limit Gas Used By Tests
53+
54+
A limit of the total gas consumption per test can be specified with the `--max-gas-per-test` flag:
55+
56+
```bash
57+
uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --max-gas-per-test 30000000 --rpc-seed-key 0x... --chain-id 12345
58+
```
59+
60+
Tests exceeding this limit will fail with an assertion error and will not send any transactions to the chain.
61+
2762
## Engine RPC Endpoint (Optional)
2863

2964
By default, the `execute remote` command assumes that the execution client is connected to a beacon node and the chain progresses automatically. However, you can optionally specify an Engine RPC endpoint to drive the chain manually when new transactions are submitted.

0 commit comments

Comments
 (0)