Skip to content

Commit 3aac74f

Browse files
roethkeroethke
authored
consolidate api references, add rpc method subpages (#1244)
* refactor: consolidate api references, add rpc method subpages * fix layout, readability * fix file name reference, update llm files * refactor table, remove unmerged changes
1 parent 40fac1d commit 3aac74f

50 files changed

Lines changed: 2884 additions & 2644 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/ai-agents/guides/trading.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: 'Base-specific patterns, fee calibration, and onchain signals for t
44
keywords: ["Flashblocks trading", "machine payments protocol","trading agent Base", "base_transactionStatus", "onchain trading agent EVM", "L1 L2 fee optimization Base"]
55
---
66

7-
Base offers two structural advantages for trading agents: **Flashblocks** (200ms preconfirmed block state, 10× faster than the 2-second block) and an exposed L1/L2 fee structure that enables explicit cost-vs-speed tradeoffs. This page covers only what is unique to Base — general EVM execution patterns are in the [Ethereum documentation](https://ethereum.org/developers/docs), and Base's RPC methods are in the [JSON-RPC API Reference](/base-chain/reference/json-rpc-api) and [Flashblocks API Reference](/base-chain/flashblocks/api-reference).
7+
Base offers two structural advantages for trading agents: **Flashblocks** (200ms preconfirmed block state, 10× faster than the 2-second block) and an exposed L1/L2 fee structure that enables explicit cost-vs-speed tradeoffs. This page covers only what is unique to Base — general EVM execution patterns are in the [Ethereum documentation](https://ethereum.org/developers/docs), and Base's RPC methods are in the [API Reference](/base-chain/api-reference/rpc-overview).
88

99
---
1010

@@ -16,19 +16,19 @@ Always connect to `mainnet-preconf.base.org` (or `sepolia-preconf.base.org` for
1616

1717
### Simulate against preconfirmed state before signing
1818

19-
Call [`eth_simulateV1`](/base-chain/flashblocks/api-reference#eth_simulatev1) against the preconf endpoint with `"blockStateCalls"` targeting the `pending` block before signing any transaction. This catches reverts against current Flashblocks state rather than the last sealed block — which may be up to 2 seconds stale by the time your transaction lands.
19+
Call [`eth_simulateV1`](/base-chain/api-reference/flashblocks-api/eth_simulateV1) against the preconf endpoint with `"blockStateCalls"` targeting the `pending` block before signing any transaction. This catches reverts against current Flashblocks state rather than the last sealed block — which may be up to 2 seconds stale by the time your transaction lands.
2020

2121
### Poll `base_transactionStatus` instead of blocking on a receipt
2222

23-
After submission, [`base_transactionStatus`](/base-chain/flashblocks/api-reference#base_transactionstatus) returns preconfirmed inclusion status within a single Flashblock interval (~200ms). Blocking on `eth_getTransactionReceipt` waits for a full sealed block (up to 2 seconds). For latency-sensitive strategies, poll `base_transactionStatus` first and only fall back to the receipt for finality confirmation.
23+
After submission, [`base_transactionStatus`](/base-chain/api-reference/flashblocks-api/base_transactionStatus) returns preconfirmed inclusion status within a single Flashblock interval (~200ms). Blocking on `eth_getTransactionReceipt` waits for a full sealed block (up to 2 seconds). For latency-sensitive strategies, poll `base_transactionStatus` first and only fall back to the receipt for finality confirmation.
2424

2525
---
2626

2727
## Fee calibration
2828

2929
### L2 priority fee heuristics
3030

31-
Use [`eth_feeHistory`](/base-chain/reference/json-rpc-api#eth_feehistory) over the last 5–10 blocks with reward percentiles `[50, 90]`:
31+
Use [`eth_feeHistory`](/base-chain/api-reference/rpc-overview#eth_feehistory) over the last 5–10 blocks with reward percentiles `[50, 90]`:
3232

3333
- **50th percentile reward** — standard inclusion within 1–3 Flashblocks
3434
- **90th percentile reward** — fast inclusion within the next Flashblock
@@ -80,9 +80,9 @@ Base exposes data that most chains don't provide at this resolution. The table m
8080

8181
## Related
8282

83-
- [Flashblocks API Reference](/base-chain/flashblocks/api-reference) — `eth_simulateV1`, `base_transactionStatus`, subscription types
83+
- [Flashblocks API Reference](/base-chain/api-reference/rpc-overview#flashblocks-api) — `eth_simulateV1`, `base_transactionStatus`, subscription types
8484
- [Flashblocks Integration Guide](/base-chain/flashblocks/app-integration) — endpoints, library setup (Wagmi, Viem, Ethers)
8585
- [Block Building](/base-chain/network-information/block-building) — Flashblocks timing, per-transaction gas maximum
8686
- [Network Fees](/base-chain/network-information/network-fees) — EIP-1559 parameters, GasPriceOracle methods
87-
- [JSON-RPC API Reference](/base-chain/reference/json-rpc-api) — complete RPC method reference
87+
- [JSON-RPC API Reference](/base-chain/api-reference/rpc-overview) — complete RPC method reference
8888
- [Troubleshooting Transactions](/base-chain/network-information/troubleshooting-transactions) — full error taxonomy and retry policies

‎docs/base-chain/api-reference/debug-api/debug_traceBlockByHash.mdx‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: 'debug_traceBlockByHash'
3+
sidebarTitle: 'debug_traceBlockByHash'
4+
description: 'Returns EVM execution traces for all transactions in a block by block hash.'
5+
---
6+
7+
Replays all transactions in a block identified by its hash and returns an execution trace for each.
8+
9+
<Warning>
10+
Debug methods replay all transactions in the block and are computationally expensive. Availability varies by [node provider](/base-chain/node-operators/node-providers).
11+
</Warning>
12+
13+
## Parameters
14+
15+
<ParamField body="blockHash" type="string" required>
16+
The 32-byte block hash.
17+
</ParamField>
18+
19+
<ParamField body="traceOptions" type="object">
20+
Optional trace configuration. Accepts the same fields as [`debug_traceTransaction`](/base-chain/api-reference/debug-api/debug_traceTransaction).
21+
</ParamField>
22+
23+
## Returns
24+
25+
<ResponseField name="result" type="array">
26+
An array of trace result objects, one per transaction in the block.
27+
28+
<Expandable title="Trace result fields">
29+
<ResponseField name="txHash" type="string">The transaction hash.</ResponseField>
30+
<ResponseField name="result" type="object">The execution trace for this transaction. Same format as [`debug_traceTransaction`](/base-chain/api-reference/debug-api/debug_traceTransaction).</ResponseField>
31+
</Expandable>
32+
</ResponseField>
33+
34+
## Example
35+
36+
<CodeGroup>
37+
```json Request
38+
{
39+
"jsonrpc": "2.0",
40+
"method": "debug_traceBlockByHash",
41+
"params": [
42+
"0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
43+
{ "tracer": "callTracer" }
44+
],
45+
"id": 1
46+
}
47+
```
48+
49+
```json Response
50+
{
51+
"jsonrpc": "2.0",
52+
"id": 1,
53+
"result": [
54+
{
55+
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
56+
"result": {
57+
"type": "CALL",
58+
"from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
59+
"to": "0x4200000000000000000000000000000000000006",
60+
"value": "0x2c68af0bb14000",
61+
"gas": "0x5208",
62+
"gasUsed": "0x5208",
63+
"input": "0x",
64+
"output": "0x",
65+
"calls": []
66+
}
67+
}
68+
]
69+
}
70+
```
71+
</CodeGroup>

‎docs/base-chain/api-reference/debug-api/debug_traceBlockByNumber.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: 'debug_traceBlockByNumber'
3+
sidebarTitle: 'debug_traceBlockByNumber'
4+
description: 'Returns EVM execution traces for all transactions in a block by block number.'
5+
---
6+
7+
Returns the EVM execution traces for all transactions in a block identified by its number.
8+
9+
<Warning>
10+
Debug methods replay all transactions in the block and are computationally expensive. Availability varies by [node provider](/base-chain/node-operators/node-providers).
11+
</Warning>
12+
13+
## Parameters
14+
15+
<ParamField body="block" type="string" required>
16+
Block number in hex, or `"latest"`, `"earliest"`, `"safe"`, `"finalized"`.
17+
</ParamField>
18+
19+
<ParamField body="tracerConfig" type="object">
20+
Optional tracer configuration. See [`debug_traceTransaction`](/base-chain/api-reference/debug-api/debug_traceTransaction) for options.
21+
</ParamField>
22+
23+
## Returns
24+
25+
<ResponseField name="result" type="array">
26+
Array of trace objects, one per transaction in the block.
27+
</ResponseField>
28+
29+
## Example
30+
31+
<CodeGroup>
32+
```json Request
33+
{
34+
"jsonrpc": "2.0",
35+
"method": "debug_traceBlockByNumber",
36+
"params": ["latest", {"tracer": "callTracer"}],
37+
"id": 1
38+
}
39+
```
40+
41+
```json Response
42+
{
43+
"jsonrpc": "2.0",
44+
"id": 1,
45+
"result": [
46+
{
47+
"result": {
48+
"type": "CALL",
49+
"gasUsed": "0xab3f"
50+
}
51+
}
52+
]
53+
}
54+
```
55+
</CodeGroup>

‎docs/base-chain/api-reference/debug-api/debug_traceTransaction.mdx‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: 'debug_traceTransaction'
3+
sidebarTitle: 'debug_traceTransaction'
4+
description: 'Returns the full EVM execution trace for a transaction. Requires a node with debug APIs enabled.'
5+
---
6+
7+
Replays a transaction and returns its complete EVM execution trace, including every opcode executed, gas consumed at each step, stack contents, and storage changes.
8+
9+
<Warning>
10+
Debug methods replay transactions and are computationally expensive. Availability and rate limits vary by [node provider](/base-chain/node-operators/node-providers). Avoid calling these in hot paths.
11+
</Warning>
12+
13+
## Parameters
14+
15+
<ParamField body="transactionHash" type="string" required>
16+
The 32-byte transaction hash to trace.
17+
</ParamField>
18+
19+
<ParamField body="traceOptions" type="object">
20+
Optional tracing configuration.
21+
22+
<Expandable title="Trace options">
23+
<ParamField body="tracer" type="string">
24+
Built-in tracer name. `"callTracer"` returns a call tree. `"prestateTracer"` returns the pre-execution account state. Omit to use the default struct log tracer.
25+
</ParamField>
26+
<ParamField body="tracerConfig" type="object">
27+
Options for the selected tracer. For `"callTracer"`: `{ "onlyTopCall": true }` skips internal calls.
28+
</ParamField>
29+
<ParamField body="disableStorage" type="boolean">
30+
If `true`, omits storage capture from struct logs. Reduces response size. Defaults to `false`.
31+
</ParamField>
32+
<ParamField body="disableMemory" type="boolean">
33+
If `true`, omits memory capture from struct logs. Reduces response size. Defaults to `false`.
34+
</ParamField>
35+
<ParamField body="disableStack" type="boolean">
36+
If `true`, omits stack capture from struct logs. Defaults to `false`.
37+
</ParamField>
38+
<ParamField body="timeout" type="string">
39+
Execution timeout as a Go duration string (e.g., `"10s"`, `"30s"`). Defaults to `"5s"`.
40+
</ParamField>
41+
</Expandable>
42+
</ParamField>
43+
44+
## Returns
45+
46+
<ResponseField name="result" type="object">
47+
The execution trace. Format depends on the `tracer` option.
48+
49+
<Expandable title="Default struct log trace">
50+
<ResponseField name="gas" type="number">Total gas provided for the transaction.</ResponseField>
51+
<ResponseField name="failed" type="boolean">Whether the transaction failed (reverted).</ResponseField>
52+
<ResponseField name="returnValue" type="string">Hex-encoded return value from the execution.</ResponseField>
53+
<ResponseField name="structLogs" type="array">
54+
Array of struct log entries, one per EVM opcode executed.
55+
56+
<Expandable title="Struct log fields">
57+
<ResponseField name="pc" type="number">Program counter position.</ResponseField>
58+
<ResponseField name="op" type="string">EVM opcode name (e.g., `"PUSH1"`, `"SLOAD"`).</ResponseField>
59+
<ResponseField name="gas" type="number">Remaining gas at this step.</ResponseField>
60+
<ResponseField name="gasCost" type="number">Gas cost of this opcode.</ResponseField>
61+
<ResponseField name="depth" type="number">Call depth (1 = top-level call).</ResponseField>
62+
<ResponseField name="stack" type="array">EVM stack values at this step.</ResponseField>
63+
<ResponseField name="memory" type="array">EVM memory contents as 32-byte chunks.</ResponseField>
64+
<ResponseField name="storage" type="object">Contract storage changes at this step (slot → value).</ResponseField>
65+
</Expandable>
66+
</ResponseField>
67+
</Expandable>
68+
69+
<Expandable title="callTracer result">
70+
<ResponseField name="type" type="string">Call type: `"CALL"`, `"STATICCALL"`, `"DELEGATECALL"`, or `"CREATE"`.</ResponseField>
71+
<ResponseField name="from" type="string">Sender address.</ResponseField>
72+
<ResponseField name="to" type="string">Recipient address.</ResponseField>
73+
<ResponseField name="value" type="string">ETH value sent with the call.</ResponseField>
74+
<ResponseField name="gas" type="string">Gas provided for the call.</ResponseField>
75+
<ResponseField name="gasUsed" type="string">Gas actually consumed.</ResponseField>
76+
<ResponseField name="input" type="string">Call data sent.</ResponseField>
77+
<ResponseField name="output" type="string">Return data from the call.</ResponseField>
78+
<ResponseField name="error" type="string">Error message if the call reverted. Optional.</ResponseField>
79+
<ResponseField name="calls" type="array">Array of nested call objects for internal calls.</ResponseField>
80+
</Expandable>
81+
</ResponseField>
82+
83+
## Example
84+
85+
<CodeGroup>
86+
```json Request (default struct log)
87+
{
88+
"jsonrpc": "2.0",
89+
"method": "debug_traceTransaction",
90+
"params": [
91+
"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
92+
{}
93+
],
94+
"id": 1
95+
}
96+
```
97+
98+
```json Request (callTracer)
99+
{
100+
"jsonrpc": "2.0",
101+
"method": "debug_traceTransaction",
102+
"params": [
103+
"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
104+
{ "tracer": "callTracer" }
105+
],
106+
"id": 1
107+
}
108+
```
109+
110+
```json Response (default)
111+
{
112+
"jsonrpc": "2.0",
113+
"id": 1,
114+
"result": {
115+
"gas": 21000,
116+
"failed": false,
117+
"returnValue": "",
118+
"structLogs": [
119+
{
120+
"pc": 0,
121+
"op": "PUSH1",
122+
"gas": 21000,
123+
"gasCost": 3,
124+
"depth": 1,
125+
"stack": [],
126+
"memory": [],
127+
"storage": {}
128+
}
129+
]
130+
}
131+
}
132+
```
133+
134+
```json Response (callTracer)
135+
{
136+
"jsonrpc": "2.0",
137+
"id": 1,
138+
"result": {
139+
"type": "CALL",
140+
"from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
141+
"to": "0x4200000000000000000000000000000000000006",
142+
"value": "0x2c68af0bb14000",
143+
"gas": "0x5208",
144+
"gasUsed": "0x5208",
145+
"input": "0x",
146+
"output": "0x",
147+
"calls": []
148+
}
149+
}
150+
```
151+
</CodeGroup>

‎docs/base-chain/api-reference/ethereum-json-rpc-api/eth_blockNumber.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: 'eth_blockNumber'
3+
sidebarTitle: 'eth_blockNumber'
4+
description: 'Returns the number of the most recently mined block.'
5+
---
6+
7+
Returns the number of the most recently mined block.
8+
9+
## Parameters
10+
11+
No parameters.
12+
13+
## Returns
14+
15+
<ResponseField name="result" type="string">
16+
The current block number as a hexadecimal string.
17+
</ResponseField>
18+
19+
## Example
20+
21+
<CodeGroup>
22+
```json Request
23+
{
24+
"jsonrpc": "2.0",
25+
"method": "eth_blockNumber",
26+
"params": [],
27+
"id": 1
28+
}
29+
```
30+
31+
```json Response
32+
{
33+
"jsonrpc": "2.0",
34+
"id": 1,
35+
"result": "0x158a0e9"
36+
}
37+
```
38+
</CodeGroup>

0 commit comments

Comments
 (0)