Skip to content

Commit f93a839

Browse files
LouisTsai-CsieLouisTsai-Csie
committed
doc: add stub account configuration for state-actor
1 parent 5fa5938 commit f93a839

3 files changed

Lines changed: 133 additions & 2 deletions

File tree

‎docs/filling_tests/fill_stateful.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,9 @@ kurtosis files download fillst el_cl_genesis_data /tmp/multi-snap/genesis
5858
kurtosis files download fillst jwt_file /tmp/fillst-out/jwt
5959
```
6060

61-
For production benchmarking, use a perfnet / bloatnet snapshot instead.
61+
For production benchmarking, use a perfnet / bloatnet snapshot instead;
62+
[Stateful Environment Stub Accounts Configuration](stateful_environment.md)
63+
lists the accounts such a snapshot must contain.
6264

6365
### 2. Start a standalone client on a copy of the snapshot
6466

@@ -156,7 +158,7 @@ Some stateful tests (e.g. `test_erc20_operation.py`, `test_sload.py`) target on-
156158

157159
Without a matching `--address-stubs` entry, both paths fail loudly: the marker path with `FAILED ... MISSING_STUBS` carrying the missing prefix; the runtime path with `ValueError("Stub '<label>' not found...")`. Stock pytest's silent skip on empty parametrize is overridden — running a bloatnet test with no stubs is a misconfiguration, not a valid outcome.
158160

159-
Stubs must point at addresses already on the live client; fill-stateful validates each at session start. The kurtosis devnet recipe above does **not** include them — use a bloatnet / perfnet snapshot (or a custom snapshot generator) for these tests.
161+
Stubs must point at addresses already on the live client; fill-stateful validates each at session start. The kurtosis devnet recipe above does **not** include them — use a bloatnet / perfnet snapshot (or one providing the required [stub accounts](stateful_environment.md)) for these tests.
160162

161163
## Architecture
162164

‎docs/filling_tests/stateful_environment.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Stateful Environment Stub Accounts Configuration
2+
3+
Stateful benchmarks require pre-deployed contracts and accounts. You can download a snapshot or use state-actor to generate the required state. This page documents the necessary stub accounts for each benchmark and provides an example state-actor configuration.
4+
5+
Key points:
6+
7+
- Receiver variants are named `receivers-<kebab-case>` (except `NON_EXISTING_ACCOUNT`, which has no entity)
8+
- Exact addresses, keys, and derivation rules are in the full configuration
9+
- Account counts scale to the target block gas limit (examples target 300M; adjust for your needs)
10+
11+
## General
12+
13+
Required by every run, regardless of which tests are selected.
14+
15+
| Entry | Configuration | Used By |
16+
|-------|---------------|---------|
17+
| `deterministic-deployment-proxy` | Arachnid CREATE2 factory at `0x4e59…956C` | All tests: derives `receivers-existing-contract-*` addresses; needed for EEST pre-alloc deploys |
18+
| `fill-stateful-seed` | EOA (private key `0x…01`, balance `1e28` wei) | All tests: funds accounts during `fill --stateful` |
19+
20+
## Test-specific
21+
22+
Only needed by the listed tests; omit when those tests are not run.
23+
24+
| Entry | Configuration | Tests |
25+
| --- | --- | --- |
26+
| `bloated-eoa-10gb` | `storage_pattern`: bloated storage to cover existing slots | `test_sload_bloated`, `test_sstore_bloated` (`existing_slots=True`) |
27+
| `receivers-existing-eoa` | `sequential_eoas`: 1-wei EOAs, starting from `0x…1000` | `test_account_access`, `test_ether_transfers_onchain_receivers` (`EXISTING_EOA`) |
28+
| `receivers-existing-contract-minimal` | `create2_deploys`: 1-byte STOP (`MinimalContractInitcode`) | `test_account_access`, `test_ether_transfers_onchain_receivers` (`EXISTING_CONTRACT_MINIMAL`) |
29+
| `receivers-existing-contract-same-max` | `create2_deploys`: max-size identical copies | `test_account_access`, `test_ether_transfers_onchain_receivers` (`EXISTING_CONTRACT_SAME_MAX`) |
30+
| `receivers-existing-contract-diff-max` | `create2_deploys`: max-size unique copies | `test_account_access`, `test_ether_transfers_onchain_receivers` (`EXISTING_CONTRACT_DIFF_MAX`); delegation target for `receivers-7702-delegated` |
31+
| `receivers-existing-contract-jumpdest` | `create2_deploys`: JUMPDEST analysis | `test_account_access`, `test_ether_transfers_onchain_receivers` (`EXISTING_CONTRACT_JUMPDEST`) |
32+
| `sender-pool` | `sequential_pkey_eoas`: 1-ETH EOAs with keys `SENDER_BASE_KEY + i`, funded on-chain so senders stay uncached | Benchmarks using `yield_distinct_sender` (e.g., `test_ether_transfers_onchain_receivers`) |
33+
| `receivers-bittrex-contracts` | `create_preimage_deploys`: contracts at Bittrex controller CREATE addresses (nonces 2+) | `test_ether_transfers_onchain_receivers` (existing-contract receivers) |
34+
| `receivers-7702-delegated` | `sequential_pkey_delegations`: EIP-7702 authorities (keys `DELEGATE_BASE_KEY + i`), delegating to `receivers-existing-contract-diff-max` | `test_ether_transfers_onchain_receivers` (delegated receivers) |
35+
36+
## Full configuration
37+
38+
An example state-actor configuration targeting a 300M block gas limit:
39+
40+
```yaml
41+
entities:
42+
# Arachnid CREATE2 factory (required by create2_deploys and EEST fill).
43+
- kind: contract
44+
template: create2_factory
45+
name: deterministic-deployment-proxy
46+
address: 0x4e59b44847b379578588920cA78FbF26c0B4956C
47+
# Seed EOA for fill-stateful funding (private key 0x…01).
48+
- kind: eoa
49+
name: fill-stateful-seed
50+
address: 0x7e5f4552091a69125d5dfcb7b8c2659029395bdf
51+
balance: "10000000000000000000000000000"
52+
nonce: 0
53+
# Bloated storage account (test_sload_bloated / test_sstore_bloated with existing_slots=True).
54+
- kind: contract
55+
name: bloated-eoa-10gb
56+
template: storage_pattern
57+
address: 0x87a6314da5ac8832f6e7a176c8fb133b19f5be04
58+
nonce: 1
59+
balance: "1000000000000000000"
60+
parameters:
61+
final: 150000
62+
# Sequential EOAs for EXISTING_EOA account mode
63+
- kind: contract
64+
name: receivers-existing-eoa
65+
template: sequential_eoas
66+
address: 0x0000000000000000000000000000000000001000
67+
parameters:
68+
count: 150000
69+
balance: "1"
70+
# CREATE2 contract receivers for different code patterns. Initcodes are deterministic;
71+
# addresses derive from salt + code_pattern via the CREATE2 factory.
72+
- kind: contract
73+
name: receivers-existing-contract-minimal
74+
template: create2_deploys
75+
parameters:
76+
initcode: "0x60016000f3"
77+
runtime: "0x00"
78+
salt_count: 100000
79+
- kind: contract
80+
name: receivers-existing-contract-same-max
81+
template: create2_deploys
82+
parameters:
83+
code_pattern: max_same_pre_amsterdam
84+
salt_count: 100000 # (all byte-identical)
85+
- kind: contract
86+
name: receivers-existing-contract-diff-max
87+
template: create2_deploys
88+
parameters:
89+
code_pattern: max_diff_pre_amsterdam
90+
salt_count: 100000 # (all byte-unique, ADDRESS-embedded)
91+
- kind: contract
92+
name: receivers-existing-contract-jumpdest
93+
template: create2_deploys
94+
parameters:
95+
code_pattern: unique_jumpdest_pre_amsterdam
96+
salt_count: 100000 # (JUMPDEST-heavy)
97+
# Sender pool for bloatnet benchmarks (test_ether_transfers_onchain_receivers).
98+
# Senders derived as EOA(key=SENDER_BASE_KEY + i) and pre-funded.
99+
- kind: contract
100+
name: sender-pool
101+
template: sequential_pkey_eoas
102+
parameters:
103+
start_pkey: "0xe1e1d3457c4e69b29cba0f7e1f92ce080d4db56d221bed913b09b2753bd97c7a"
104+
count: 150000
105+
balance: "1000000000000000000"
106+
# Bittrex controller CREATE-derived contracts.
107+
# Sender is Bittrex, nonces 2+ produce the contract chain.
108+
- kind: contract
109+
name: receivers-bittrex-contracts
110+
template: create_preimage_deploys
111+
parameters:
112+
sender: "0xA3C1E324CA1CE40DB73ED6026C4A177F099B5770"
113+
start_nonce: 2
114+
count: 100000
115+
runtime: "0x606060405236156100495763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416636ea056a98114610052578063c0ee0b8a14610092575b6100505b5b565b005b341561005a57fe5b61007e73ffffffffffffffffffffffffffffffffffffffff60043516602435610104565b604080519115158252519081900360200190f35b341561009a57fe5b604080516020600460443581810135601f810184900484028501840190955284845261005094823573ffffffffffffffffffffffffffffffffffffffff169460248035956064949293919092019181908401838280828437509496506101ef95505050505050565b005b6000805460408051602090810184905281517f3c18d31800000000000000000000000000000000000000000000000000000000815273ffffffffffffffffffffffffffffffffffffffff878116600483015292519290931692633c18d318926024808301939282900301818787803b151561017b57fe5b6102c65a03f1151561018957fe5b5050506040518051905073ffffffffffffffffffffffffffffffffffffffff1660003660006040516020015260405180838380828437820191505092505050602060405180830381856102c65a03f415156101e057fe5b50506040515190505b92915050565b5b5050505600a165627a7a723058204cdd69fdcf3cf6cbee9677fe380fa5f044048aa9e060ec5619a21ca5a5bd4cd10029"
116+
storage_init:
117+
"0x0": "0xa3c1e324ca1ce40db73ed6026c4a177f099b5770"
118+
# EIP-7702 delegated authorities
119+
# Authority i (key=DELEGATE_BASE_KEY + i) delegates to max_diff receiver i.
120+
- kind: contract
121+
name: receivers-7702-delegated
122+
template: sequential_pkey_delegations
123+
parameters:
124+
start_pkey: "0x959a83d905ff1fab43bf72c3e87020e4c77fd4bde0e5eeb48e5edbf74a9ec64e"
125+
code_pattern: max_diff_pre_amsterdam
126+
count: 100000
127+
balance: "1000000000000000000"
128+
```

‎docs/navigation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
* [Transition Tool Support](filling_tests/transition_tool_support.md)
4545
* [Debugging Transition Tools](filling_tests/debugging_t8n_tools.md)
4646
* [Filling Stateful Benchmark Fixtures](filling_tests/fill_stateful.md)
47+
* [Stateful Environment Stub Accounts Configuration](filling_tests/stateful_environment.md)
4748
* [Running Tests](running_tests/index.md)
4849
* [Methods of Running Tests](running_tests/running.md)
4950
* [EELS Fixture Releases](running_tests/releases.md)

0 commit comments

Comments
 (0)