From 2f5238c8e848b6127f70d3aed2678cbdecc42013 Mon Sep 17 00:00:00 2001 From: Bloxster Date: Mon, 19 Jan 2026 11:35:18 +0100 Subject: [PATCH 01/10] broken link, added debug APIs description --- .../src/interacting-with-erigon/README.md | 4 +- .../src/interacting-with-erigon/debug.md | 654 +++++++++++++++++- 2 files changed, 650 insertions(+), 8 deletions(-) diff --git a/docs/gitbook/src/interacting-with-erigon/README.md b/docs/gitbook/src/interacting-with-erigon/README.md index 639a0af3a9e..a705ce51bd3 100644 --- a/docs/gitbook/src/interacting-with-erigon/README.md +++ b/docs/gitbook/src/interacting-with-erigon/README.md @@ -24,11 +24,11 @@ The Erigon RPC Service, managed by Erigon's modular [RPC daemon](../fundamentals {% include "../../../.gitbook/includes/warning-admin_-and-debug_-....md" %} -For a complete reference on the standard Ethereum JSON-RPC methods, especially those in the `eth`, `net`, and `web3` namespaces, it is recommended to consult the general documentation on [ethereum.org's JSON-RPC API page](https://ethereum.org/en/developers/docs/apis/json-rpc/). Additionally, for the formal specification of the `debug`, `engine`, and `eth` namespaces, including unique, detailed descriptions for methods like `eth_getProof` and `eth_simulateV1`, refer to the [Execution APIs documentation](https://ethereum.github.io/execution-apis/api-documentation/). +For a complete reference on the standard Ethereum JSON-RPC methods, especially those in the `eth`, `net`, and `web3` namespaces, it is recommended to consult the general documentation on [ethereum.org's JSON-RPC API page](https://ethereum.org/en/developers/docs/apis/json-rpc/). Additionally, for the formal specification of the `debug`, `engine`, and `eth` namespaces, including unique, detailed descriptions for methods like `eth_getProof` and `eth_simulateV1`, refer to the [Execution APIs documentation](https://ethereum.github.io/execution-apis). {% embed url="https://ethereum.org/en/developers/docs/apis/json-rpc/" %} -{% embed url="https://ethereum.github.io/execution-apis/api-documentation/" %} +{% embed url="https://ethereum.github.io/execution-apis" %} ## Erigon RPC Transports diff --git a/docs/gitbook/src/interacting-with-erigon/debug.md b/docs/gitbook/src/interacting-with-erigon/debug.md index ee3ef547cf8..cba218b9e04 100644 --- a/docs/gitbook/src/interacting-with-erigon/debug.md +++ b/docs/gitbook/src/interacting-with-erigon/debug.md @@ -8,12 +8,6 @@ The `debug` namespace provides debugging and diagnostic methods for Erigon node The debug namespace must be explicitly enabled using the `--http.api` flag when starting the RPC daemon. For security reasons, these methods are considered private and should not be exposed on public RPC endpoints. -For API usage refer to the below official resources: - -{% embed url="https://ethereum.org/en/developers/docs/apis/json-rpc/" %} - -{% embed url="https://ethereum.github.io/execution-apis/api-documentation/" %} - ### Security and Access Control * Debug methods are considered private and should not be exposed on public RPC endpoints; @@ -37,3 +31,651 @@ For API usage refer to the below official resources: * These methods are essential for debugging transaction execution issues; * Storage range methods help analyze contract state changes; * Memory management methods assist in performance optimization and resource monitoring. + + +# JSON RPC API Reference + + + +## `debug_accountRange` + +Enumerates all accounts at a given block with paging capability. `maxResults` are returned in the page and the items have keys that come after the `start` key (hashed address). + +- **Parameters:** + - `blockNrOrHash`: The block number or hash. + - `start`: The starting key (hashed address). + - `maxResults`: The maximum number of results to return. + - `nocode`: (Optional) Whether to exclude code. + - `nostorage`: (Optional) Whether to exclude storage. + - `incompletes`: (Optional) Whether to include incomplete accounts. + +- **RPC Call:** + ```json + RPC{"method": "debug_accountRange", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]} + ``` + +## `debug_backtraceAt` + +Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr. + +- **Parameters:** + - `string`: The location specified as `:`. + +- **RPC Call:** + ```json + RPC{"method": "debug_backtraceAt", "params": [string]} + ``` + +- **Example:** + ```json + debug.backtraceAt("server.go:443") + ``` + +## `debug_blockProfile` + +Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`. + +- **Parameters:** + - `file`: The file to write the profile data to. + - `seconds`: The duration to run the profile. + +- **RPC Call:** + ```json + RPC{"method": "debug_blockProfile", "params": [string, number]} + ``` + +## `debug_chaindbCompact` + +Flattens the entire key-value database into a single level, removing all unused slots and merging all keys. + +- **RPC Call:** + ```json + RPC{"method": "debug_chaindbCompact", "params": []} + ``` + +## `debug_chaindbProperty` + +Returns leveldb properties of the key-value database. + +- **Parameters:** + - `property`: The property to retrieve. + +- **RPC Call:** + ```json + RPC{"method": "debug_chaindbProperty", "params": [property]} + ``` + +## `debug_cpuProfile` + +Turns on CPU profiling for the given duration and writes profile data to disk. + +- **Parameters:** + - `file`: The file to write the profile data to. + - `seconds`: The duration to run the profile. + +- **RPC Call:** + ```json + RPC{"method": "debug_cpuProfile", "params": [string, number]} + ``` + +## `debug_dbAncient` + +Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. + +- **Parameters:** + - `kind`: The table kind (e.g., headers, hashes, bodies, receipts, diffs). + - `number`: The block number. + +- **RPC Call:** + ```json + RPC{"method": "debug_dbAncient", "params": [string, number]} + ``` + +## `debug_dbAncients` + +Returns the number of ancient items in the ancient store. + +- **RPC Call:** + ```json + RPC{"method": "debug_dbAncients", "params": []} + ``` + +## `debug_dbGet` + +Returns the raw value of a key stored in the database. + +- **Parameters:** + - `key`: The key to retrieve. + +- **RPC Call:** + ```json + RPC{"method": "debug_dbGet", "params": [key]} + ``` + +## `debug_dumpBlock` + +Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code). + +- **Parameters:** + - `number`: The block number. + +- **RPC Call:** + ```json + RPC{"method": "debug_dumpBlock", "params": [number]} + ``` + +- **Example:** + ```json + > debug.dumpBlock(10) + { + fff7ac99c8e4feb60c9750054bdc14ce1857f181: { + balance: "49358640978154672", + code: "", + codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + nonce: 2, + root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + storage: {} + }, + fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: { + balance: "3460945928", + code: "", + codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + nonce: 657, + root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + storage: {} + } + }, + root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1" + } + ``` + +## `debug_freeOSMemory` + +Forces garbage collection. + +- **RPC Call:** + ```json + RPC{"method": "debug_freeOSMemory", "params": []} + ``` + +## `debug_freezeClient` + +Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server. + +- **Parameters:** + - `node`: The node to freeze. + +- **RPC Call:** + ```json + RPC{"method": "debug_freezeClient", "params": [node]} + ``` + +## `debug_gcStats` + +Returns garbage collection statistics. See for information about the fields of the returned object. + +- **RPC Call:** + ```json + RPC{"method": "debug_gcStats", "params": []} + ``` + +## `debug_getAccessibleState` + +Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next block. The `(from, to)` parameters are the sequence of blocks to search, which can go either forwards or backwards. + +- **Parameters:** + - `from`: The starting block number. + - `to`: The ending block number. + +- **RPC Call:** + ```json + RPC{"method": "debug_getAccessibleState", "params": [from, to]} + ``` + +## `debug_getBadBlocks` + +Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes. + +- **RPC Call:** + ```json + RPC{"method": "debug_getBadBlocks", "params": []} + ``` + +## `debug_getRawBlock` + +Retrieves and returns the RLP encoded block by number. + +- **Parameters:** + - `blockNrOrHash`: The block number or hash. + +- **RPC Call:** + ```json + RPC{"method": "debug_getRawBlock", "params": [blockNrOrHash]} + ``` + +## `debug_getRawHeader` + +Returns an RLP-encoded header. + +- **Parameters:** + - `blockNrOrHash`: The block number or hash. + +- **RPC Call:** + ```json + RPC{"method": "debug_getRawHeader", "params": [blockNrOrHash]} + ``` + +## `debug_getRawTransaction` + +Returns the bytes of the transaction. + +- **Parameters:** + - `transactionHash`: The transaction hash. + +- **RPC Call:** + ```json + RPC{"method": "debug_getRawTransaction", "params": [transactionHash]} + ``` + +## `debug_getModifiedAccountsByHash` + +Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block. + +- **Parameters:** + - `startHash`: The starting block hash. + - `endHash`: The ending block hash. + +- **RPC Call:** + ```json + RPC{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]} + ``` + +## `debug_getModifiedAccountsByNumber` + +Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash. + +- **Parameters:** + - `startNum`: The starting block number. + - `endNum`: The ending block number. + +- **RPC Call:** + ```json + RPC{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]} + ``` + +## `debug_getRawReceipts` + +Returns the consensus-encoding of all receipts in a single block. + +- **Parameters:** + - `blockNrOrHash`: The block number or hash. + +- **RPC Call:** + ```json + RPC{"method": "debug_getRawReceipts", "params": [blockNrOrHash]} + ``` + +## `debug_goTrace` + +Turns on Go runtime tracing for the given duration and writes trace data to disk. + +- **Parameters:** + - `file`: The file to write the trace data to. + - `seconds`: The duration to run the trace. + +- **RPC Call:** + ```json + RPC{"method": "debug_goTrace", "params": [string, number]} + ``` + +## `debug_intermediateRoots` + +Executes a block (bad- or canon- or side-) and returns a list of intermediate roots: the stateroot after each transaction. + +- **Parameters:** + - `blockHash`: The block hash. + - `options`: Additional options. + +- **RPC Call:** + ```json + RPC{"method": "debug_intermediateRoots", "params": [blockHash, {}]} + ``` + +## `debug_memStats` + +Returns detailed runtime memory statistics. + +- **RPC Call:** + ```json + RPC{"method": "debug_memStats", "params": []} + ``` + +## `debug_mutexProfile` + +Turns on mutex profiling for `nsec` seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually. + +- **Parameters:** + - `file`: The file to write the profile data to. + - `nsec`: + +## `debug_preimage` + +Returns the preimage for a sha3 hash, if known. + +- **Client Method invocation:** + - **Console:** `debug.preimage(hash)` +- **RPC Call:** + ```json + RPC{"method": "debug_preimage", "params": [hash]} + ``` + +## `debug_printBlock` + +Retrieves a block and returns its pretty printed form. + +- **Client Method invocation:** + - **Console:** `debug.printBlock(number uint64)` +- **RPC Call:** + ```json + RPC{"method": "debug_printBlock", "params": [number]} + ``` + +## `debug_setBlockProfileRate` + +Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`. + +- **Client Method invocation:** + - **Console:** `debug.setBlockProfileRate(rate)` +- **RPC Call:** + ```json + RPC{"method": "debug_setBlockProfileRate", "params": [number]} + ``` + +## `debug_setGCPercent` + +Sets the garbage collection target percentage. A negative value disables garbage collection. + +- **Client Method invocation:** + - **Go:** `debug.SetGCPercent(v int)` + - **Console:** `debug.setGCPercent(v)` +- **RPC Call:** + ```json + RPC{"method": "debug_setGCPercent", "params": [v]} + ``` + +## `debug_setHead` + +Sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution. + +- **Client Method invocation:** + - **Go:** `debug.SetHead(number uint64)` + - **Console:** `debug.setHead(number)` +- **RPC Call:** + ```json + RPC{"method": "debug_setHead", "params": [number]} + ``` +- **References:** [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/ethash/) + +## `debug_setMutexProfileFraction` + +Sets the rate of mutex profiling. + +- **Client Method invocation:** + - **Console:** `debug.setMutexProfileFraction(rate int)` +- **RPC Call:** + ```json + RPC{"method": "debug_setMutexProfileFraction", "params": [rate]} + ``` + +## `debug_setTrieFlushInterval` + +Configures how often in-memory state tries are persisted to disk. The interval needs to be in a format parsable by a `time.Duration`. Note that the interval is not wall-clock time. Rather it is accumulated block processing time after which the state should be flushed. For example, the value `0s` will essentially turn on archive mode. If set to `1h`, it means that after one hour of effective block processing time, the trie would be flushed. If one block takes 200ms, a flush would occur every `5*3600=18000` blocks. The default interval for mainnet is `1h`. + +Note: this configuration will not be persisted through restarts. + +- **Client Method invocation:** + - **Console:** `debug.setTrieFlushInterval(interval string)` +- **RPC Call:** + ```json + RPC{"method": "debug_setTrieFlushInterval", "params": [interval]} + ``` + +## `debug_stacks` + +Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string. + +- **Client Method invocation:** + - **Console:** `debug.stacks(filter *string)` +- **RPC Call:** + ```json + RPC{"method": "debug_stacks", "params": [filter]} + ``` + +## `debug_standardTraceBlockToFile` + +When JS-based tracing (see below) was first implemented, the intended use case was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see PR) + +It streams output to disk during the execution, to not blow up the memory usage on the node +It uses `jsonl` as output format (to allow streaming) +Uses a cross-client standardized output, so called 'standard json' +Uses `op` for string-representation of opcode, instead of `op/opName` for numeric/string, and other similar small differences. +has `refund` +Represents memory as a contiguous chunk of data, as opposed to a list of 32-byte segments like `debug_traceTransaction` +This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. + +The method can be used to dump a certain transaction out of a given block: + +```json +debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true}) +["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"] +``` + +Or all txs from a block: + +```json +debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true}) +["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x151741 +``` + +Files are created in a temp-location, with the naming standard `block_blockhash:4>---`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does. + +On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not available` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target: + +``` +INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s +INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s +INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB +INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834 +INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969 +INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484 +``` + +The `options` is as follows: + +```json +type StdTraceConfig struct { + *vm.LogConfig + Reexec *uint64 + TxHash *common.Hash + } +``` + +```markdown +## `debug_standardTraceBadBlockToFile` + +This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been rejected as invalid (for some reason). + +## `debug_startCPUProfile` + +Turns on CPU profiling indefinitely, writing to the given file. + +- **Client Method invocation:** + - **Console:** `debug.startCPUProfile(file)` +- **RPC Call:** + ```json + RPC{"method": "debug_startCPUProfile", "params": [string]} + ``` + +## `debug_startGoTrace` + +Starts writing a Go runtime trace to the given file. + +- **Client Method invocation:** + - **Console:** `debug.startGoTrace(file)` +- **RPC Call:** + ```json + RPC{"method": "debug_startGoTrace", "params": [string]} + ``` + +## `debug_stopCPUProfile` + +Stops an ongoing CPU profile. + +- **Client Method invocation:** + - **Console:** `debug.stopCPUProfile()` +- **RPC Call:** + ```json + RPC{"method": "debug_stopCPUProfile", "params": []} + ``` + +## `debug_stopGoTrace` + +Stops writing the Go runtime trace. + +- **Client Method invocation:** + - **Console:** `debug.stopGoTrace()` +- **RPC Call:** + ```json + RPC{"method": "debug_stopGoTrace", "params": []} + ``` + +## `debug_storageRangeAt` + +Returns the storage at the given block height and transaction index. The result can be paged by providing a `maxResult` to cap the number of storage slots returned as well as specifying the offset via `keyStart` (hash of storage key). + +- **Client Method invocation:** + - **Console:** `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)` +- **RPC Call:** + ```json + RPC{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]} + ``` + +## `debug_traceBadBlock` + +Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object. For the second parameter, see `TraceConfig` reference. + +- **Client Method invocation:** + - **Console:** `debug.traceBadBlock(blockHash, [options])` +- **RPC Call:** + ```json + RPC{"method": "debug_traceBadBlock", "params": [blockHash, {}]} + ``` + +## `debug_traceBlock` + +The `traceBlock` method will return a full stack trace of all invoked opcodes of all transactions that were included in this block. Note, the parent of this block must be present or it will fail. For the second parameter, see `TraceConfig` reference. + +- **Client Method invocation:** + - **Go:** `debug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult` + - **Console:** `debug.traceBlock(tblockRlp, [options])` +- **RPC Call:** + ```json + RPC{"method": "debug_traceBlock", "params": [blockRlp, {}]} + ``` +- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +**Example:** + +```json +> debug.traceBlock("0xblock_rlp") +[ + { + txHash: "0xabba...", + result: { + gas: 85301, + returnValue: "", + structLogs: [{ + depth: 1, + error: "", + gas: 162106, + gasCost: 3, + memory: null, + op: "PUSH1", + pc: 0, + stack: [], + storage: {} + }, + /* snip */ + { + depth: 1, + error: "", + gas: 100000, + gasCost: 0, + memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], + op: "STOP", + pc: 120, + stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], + storage: { + 0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", + 0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", + f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" + } + }] + } + }, + { + txHash: "0xacca...", + result: { + /* snip */ + } + } +] +``` + +## `debug_traceBlockByNumber` + +Similar to `debug_traceBlock`, `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. + +- **Client Method invocation:** + - **Go:** `debug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult` + - **Console:** `debug.traceBlockByNumber(number, [options])` +- **RPC Call:** + ```json + RPC{"method": "debug_traceBlockByNumber", "params": [number, {}]} + ``` +- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +## `debug_traceBlockByHash` + +Similar to `debug_traceBlock`, `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. + +- **Client Method invocation:** + - **Go:** `debug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult` + - **Console:** `debug.traceBlockByHash(hash, [options])` +- **RPC Call:** + ```json + RPC{"method": "debug_traceBlockByHash", "params": [hash {}]} + ``` +- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +## `debug_traceBlockFromFile` + +Similar to `debug_traceBlock`, `traceBlockFromFile` accepts a file containing the RLP of the block. For the second parameter, see `TraceConfig` reference. + +- **Client Method invocation:** + - **Go:** `debug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult` + - **Console:** `debug.traceBlockFromFile(fileName, [options])` +- **RPC Call:** + ```json + RPC{"method": "debug_traceBlockFromFile", "params": [fileName, {}]} + ``` +- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +## `debug_traceCall` + +The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a transaction object. The block can be specified either by hash or by number as the second argument. The trace can be configured similar to `debug_traceTransaction`, see `TraceCallConfig`. The method returns the same output as `debug_traceTransaction`. + +```json +{"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]} +``` + From 2a8cec53610184f2dfceca741cae3b1dd5cc0f45 Mon Sep 17 00:00:00 2001 From: bloxster Date: Mon, 19 Jan 2026 14:55:07 +0000 Subject: [PATCH 02/10] GITBOOK-3: No subject --- .../src/interacting-with-erigon/debug.md | 959 +++++++++++------- 1 file changed, 608 insertions(+), 351 deletions(-) diff --git a/docs/gitbook/src/interacting-with-erigon/debug.md b/docs/gitbook/src/interacting-with-erigon/debug.md index cba218b9e04..1ad65cc1cbf 100644 --- a/docs/gitbook/src/interacting-with-erigon/debug.md +++ b/docs/gitbook/src/interacting-with-erigon/debug.md @@ -1,467 +1,480 @@ --- description: 'Erigon RPC debug Namespace: Deep Diagnostics and State Introspection' +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/debug --- # debug +## debug + The `debug` namespace provides debugging and diagnostic methods for Erigon node operators and developers. These methods offer deep introspection into blockchain state, transaction execution, and node performance. The debug namespace is implemented through the `PrivateDebugAPI` interface and `DebugAPIImpl` struct. The debug namespace must be explicitly enabled using the `--http.api` flag when starting the RPC daemon. For security reasons, these methods are considered private and should not be exposed on public RPC endpoints. -### Security and Access Control +#### Security and Access Control * Debug methods are considered private and should not be exposed on public RPC endpoints; * These methods can consume significant resources and should be used carefully in production environments; * Access should be restricted to trusted operators and developers only. -### Performance Considerations +#### Performance Considerations * Tracing methods (`debug_traceTransaction`, `debug_traceBlockByHash`, etc.) support streaming to handle large results efficiently; * The `AccountRangeMaxResults` constant limits account range queries to 8192 results, or 256 when storage is included; * Memory and GC control methods allow fine-tuning of node performance. -### Integration with Erigon Architecture +#### Integration with Erigon Architecture * Debug methods leverage Erigon's temporal database for historical state access; * The implementation uses `kv.TemporalRoDB` for efficient historical queries; * Tracing functionality integrates with Erigon's execution engine and EVM implementation. -### Usage in Development and Testing +#### Usage in Development and Testing * These methods are essential for debugging transaction execution issues; * Storage range methods help analyze contract state changes; * Memory management methods assist in performance optimization and resource monitoring. +*** -# JSON RPC API Reference - +## JSON RPC API Reference - -## `debug_accountRange` +### debug\_accountRange Enumerates all accounts at a given block with paging capability. `maxResults` are returned in the page and the items have keys that come after the `start` key (hashed address). -- **Parameters:** - - `blockNrOrHash`: The block number or hash. - - `start`: The starting key (hashed address). - - `maxResults`: The maximum number of results to return. - - `nocode`: (Optional) Whether to exclude code. - - `nostorage`: (Optional) Whether to exclude storage. - - `incompletes`: (Optional) Whether to include incomplete accounts. +* **Parameters:** + * `blockNrOrHash`: The block number or hash. + * `start`: The starting key (hashed address). + * `maxResults`: The maximum number of results to return. + * `nocode`: (Optional) Whether to exclude code. + * `nostorage`: (Optional) Whether to exclude storage. + * `incompletes`: (Optional) Whether to include incomplete accounts. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_accountRange", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]} - ``` + ```json + RPC{"method": "debug_accountRange", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]} + ``` -## `debug_backtraceAt` +### debug\_backtraceAt Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr. -- **Parameters:** - - `string`: The location specified as `:`. +* **Parameters:** + * `string`: The location specified as `:`. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_backtraceAt", "params": [string]} - ``` + ```json + RPC{"method": "debug_backtraceAt", "params": [string]} + ``` +* **Example:** -- **Example:** - ```json - debug.backtraceAt("server.go:443") - ``` + ```json + debug.backtraceAt("server.go:443") + ``` -## `debug_blockProfile` +### debug\_blockProfile Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`. -- **Parameters:** - - `file`: The file to write the profile data to. - - `seconds`: The duration to run the profile. +* **Parameters:** + * `file`: The file to write the profile data to. + * `seconds`: The duration to run the profile. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_blockProfile", "params": [string, number]} - ``` + ```json + RPC{"method": "debug_blockProfile", "params": [string, number]} + ``` -## `debug_chaindbCompact` +### debug\_chaindbCompact Flattens the entire key-value database into a single level, removing all unused slots and merging all keys. -- **RPC Call:** - ```json - RPC{"method": "debug_chaindbCompact", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_chaindbCompact", "params": []} + ``` -## `debug_chaindbProperty` +### debug\_chaindbProperty Returns leveldb properties of the key-value database. -- **Parameters:** - - `property`: The property to retrieve. +* **Parameters:** + * `property`: The property to retrieve. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_chaindbProperty", "params": [property]} - ``` + ```json + RPC{"method": "debug_chaindbProperty", "params": [property]} + ``` -## `debug_cpuProfile` +### debug\_cpuProfile Turns on CPU profiling for the given duration and writes profile data to disk. -- **Parameters:** - - `file`: The file to write the profile data to. - - `seconds`: The duration to run the profile. +* **Parameters:** + * `file`: The file to write the profile data to. + * `seconds`: The duration to run the profile. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_cpuProfile", "params": [string, number]} - ``` + ```json + RPC{"method": "debug_cpuProfile", "params": [string, number]} + ``` -## `debug_dbAncient` +### debug\_dbAncient Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. -- **Parameters:** - - `kind`: The table kind (e.g., headers, hashes, bodies, receipts, diffs). - - `number`: The block number. +* **Parameters:** + * `kind`: The table kind (e.g., headers, hashes, bodies, receipts, diffs). + * `number`: The block number. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_dbAncient", "params": [string, number]} - ``` + ```json + RPC{"method": "debug_dbAncient", "params": [string, number]} + ``` -## `debug_dbAncients` +### debug\_dbAncients Returns the number of ancient items in the ancient store. -- **RPC Call:** - ```json - RPC{"method": "debug_dbAncients", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_dbAncients", "params": []} + ``` -## `debug_dbGet` +### debug\_dbGet Returns the raw value of a key stored in the database. -- **Parameters:** - - `key`: The key to retrieve. +* **Parameters:** + * `key`: The key to retrieve. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_dbGet", "params": [key]} - ``` + ```json + RPC{"method": "debug_dbGet", "params": [key]} + ``` -## `debug_dumpBlock` +### debug\_dumpBlock Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code). -- **Parameters:** - - `number`: The block number. - -- **RPC Call:** - ```json - RPC{"method": "debug_dumpBlock", "params": [number]} - ``` - -- **Example:** - ```json - > debug.dumpBlock(10) - { - fff7ac99c8e4feb60c9750054bdc14ce1857f181: { - balance: "49358640978154672", - code: "", - codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", - nonce: 2, - root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", - storage: {} +* **Parameters:** + * `number`: The block number. +* **RPC Call:** + + ```json + RPC{"method": "debug_dumpBlock", "params": [number]} + ``` +* **Example:** + + ```json + > debug.dumpBlock(10) + { + fff7ac99c8e4feb60c9750054bdc14ce1857f181: { + balance: "49358640978154672", + code: "", + codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + nonce: 2, + root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + storage: {} + }, + fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: { + balance: "3460945928", + code: "", + codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + nonce: 657, + root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + storage: {} + } }, - fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: { - balance: "3460945928", - code: "", - codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", - nonce: 657, - root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", - storage: {} + root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1" } - }, - root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1" - } - ``` + ``` -## `debug_freeOSMemory` +### debug\_freeOSMemory Forces garbage collection. -- **RPC Call:** - ```json - RPC{"method": "debug_freeOSMemory", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_freeOSMemory", "params": []} + ``` -## `debug_freezeClient` +### debug\_freezeClient Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server. -- **Parameters:** - - `node`: The node to freeze. +* **Parameters:** + * `node`: The node to freeze. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_freezeClient", "params": [node]} - ``` + ```json + RPC{"method": "debug_freezeClient", "params": [node]} + ``` -## `debug_gcStats` +### debug\_gcStats -Returns garbage collection statistics. See for information about the fields of the returned object. +Returns garbage collection statistics. See [https://golang.org/pkg/runtime/debug/#GCStats](https://golang.org/pkg/runtime/debug/#GCStats) for information about the fields of the returned object. -- **RPC Call:** - ```json - RPC{"method": "debug_gcStats", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_gcStats", "params": []} + ``` -## `debug_getAccessibleState` +### debug\_getAccessibleState Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next block. The `(from, to)` parameters are the sequence of blocks to search, which can go either forwards or backwards. -- **Parameters:** - - `from`: The starting block number. - - `to`: The ending block number. +* **Parameters:** + * `from`: The starting block number. + * `to`: The ending block number. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getAccessibleState", "params": [from, to]} - ``` + ```json + RPC{"method": "debug_getAccessibleState", "params": [from, to]} + ``` -## `debug_getBadBlocks` +### debug\_getBadBlocks Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes. -- **RPC Call:** - ```json - RPC{"method": "debug_getBadBlocks", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_getBadBlocks", "params": []} + ``` -## `debug_getRawBlock` +### debug\_getRawBlock Retrieves and returns the RLP encoded block by number. -- **Parameters:** - - `blockNrOrHash`: The block number or hash. +* **Parameters:** + * `blockNrOrHash`: The block number or hash. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getRawBlock", "params": [blockNrOrHash]} - ``` + ```json + RPC{"method": "debug_getRawBlock", "params": [blockNrOrHash]} + ``` -## `debug_getRawHeader` +### debug\_getRawHeader Returns an RLP-encoded header. -- **Parameters:** - - `blockNrOrHash`: The block number or hash. +* **Parameters:** + * `blockNrOrHash`: The block number or hash. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getRawHeader", "params": [blockNrOrHash]} - ``` + ```json + RPC{"method": "debug_getRawHeader", "params": [blockNrOrHash]} + ``` -## `debug_getRawTransaction` +### debug\_getRawTransaction Returns the bytes of the transaction. -- **Parameters:** - - `transactionHash`: The transaction hash. +* **Parameters:** + * `transactionHash`: The transaction hash. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getRawTransaction", "params": [transactionHash]} - ``` + ```json + RPC{"method": "debug_getRawTransaction", "params": [transactionHash]} + ``` -## `debug_getModifiedAccountsByHash` +### debug\_getModifiedAccountsByHash Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block. -- **Parameters:** - - `startHash`: The starting block hash. - - `endHash`: The ending block hash. +* **Parameters:** + * `startHash`: The starting block hash. + * `endHash`: The ending block hash. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]} - ``` + ```json + RPC{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]} + ``` -## `debug_getModifiedAccountsByNumber` +### debug\_getModifiedAccountsByNumber Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash. -- **Parameters:** - - `startNum`: The starting block number. - - `endNum`: The ending block number. +* **Parameters:** + * `startNum`: The starting block number. + * `endNum`: The ending block number. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]} - ``` + ```json + RPC{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]} + ``` -## `debug_getRawReceipts` +### debug\_getRawReceipts Returns the consensus-encoding of all receipts in a single block. -- **Parameters:** - - `blockNrOrHash`: The block number or hash. +* **Parameters:** + * `blockNrOrHash`: The block number or hash. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_getRawReceipts", "params": [blockNrOrHash]} - ``` + ```json + RPC{"method": "debug_getRawReceipts", "params": [blockNrOrHash]} + ``` -## `debug_goTrace` +### debug\_goTrace Turns on Go runtime tracing for the given duration and writes trace data to disk. -- **Parameters:** - - `file`: The file to write the trace data to. - - `seconds`: The duration to run the trace. +* **Parameters:** + * `file`: The file to write the trace data to. + * `seconds`: The duration to run the trace. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_goTrace", "params": [string, number]} - ``` + ```json + RPC{"method": "debug_goTrace", "params": [string, number]} + ``` -## `debug_intermediateRoots` +### debug\_intermediateRoots Executes a block (bad- or canon- or side-) and returns a list of intermediate roots: the stateroot after each transaction. -- **Parameters:** - - `blockHash`: The block hash. - - `options`: Additional options. +* **Parameters:** + * `blockHash`: The block hash. + * `options`: Additional options. +* **RPC Call:** -- **RPC Call:** - ```json - RPC{"method": "debug_intermediateRoots", "params": [blockHash, {}]} - ``` + ```json + RPC{"method": "debug_intermediateRoots", "params": [blockHash, {}]} + ``` -## `debug_memStats` +### debug\_memStats Returns detailed runtime memory statistics. -- **RPC Call:** - ```json - RPC{"method": "debug_memStats", "params": []} - ``` +* **RPC Call:** + + ```json + RPC{"method": "debug_memStats", "params": []} + ``` -## `debug_mutexProfile` +### debug\_mutexProfile Turns on mutex profiling for `nsec` seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually. -- **Parameters:** - - `file`: The file to write the profile data to. - - `nsec`: +* **Parameters:** + * `file`: The file to write the profile data to. + * `nsec`: -## `debug_preimage` +### debug\_preimage Returns the preimage for a sha3 hash, if known. -- **Client Method invocation:** - - **Console:** `debug.preimage(hash)` -- **RPC Call:** - ```json - RPC{"method": "debug_preimage", "params": [hash]} - ``` +* **Client Method invocation:** + * **Console:** `debug.preimage(hash)` +* **RPC Call:** + + ```json + RPC{"method": "debug_preimage", "params": [hash]} + ``` -## `debug_printBlock` +### debug\_printBlock Retrieves a block and returns its pretty printed form. -- **Client Method invocation:** - - **Console:** `debug.printBlock(number uint64)` -- **RPC Call:** - ```json - RPC{"method": "debug_printBlock", "params": [number]} - ``` +* **Client Method invocation:** + * **Console:** `debug.printBlock(number uint64)` +* **RPC Call:** + + ```json + RPC{"method": "debug_printBlock", "params": [number]} + ``` -## `debug_setBlockProfileRate` +### debug\_setBlockProfileRate Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`. -- **Client Method invocation:** - - **Console:** `debug.setBlockProfileRate(rate)` -- **RPC Call:** - ```json - RPC{"method": "debug_setBlockProfileRate", "params": [number]} - ``` +* **Client Method invocation:** + * **Console:** `debug.setBlockProfileRate(rate)` +* **RPC Call:** -## `debug_setGCPercent` + ```json + RPC{"method": "debug_setBlockProfileRate", "params": [number]} + ``` + +### debug\_setGCPercent Sets the garbage collection target percentage. A negative value disables garbage collection. -- **Client Method invocation:** - - **Go:** `debug.SetGCPercent(v int)` - - **Console:** `debug.setGCPercent(v)` -- **RPC Call:** - ```json - RPC{"method": "debug_setGCPercent", "params": [v]} - ``` +* **Client Method invocation:** + * **Go:** `debug.SetGCPercent(v int)` + * **Console:** `debug.setGCPercent(v)` +* **RPC Call:** -## `debug_setHead` + ```json + RPC{"method": "debug_setGCPercent", "params": [v]} + ``` + +### debug\_setHead Sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution. -- **Client Method invocation:** - - **Go:** `debug.SetHead(number uint64)` - - **Console:** `debug.setHead(number)` -- **RPC Call:** - ```json - RPC{"method": "debug_setHead", "params": [number]} - ``` -- **References:** [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/ethash/) +* **Client Method invocation:** + * **Go:** `debug.SetHead(number uint64)` + * **Console:** `debug.setHead(number)` +* **RPC Call:** + + ```json + RPC{"method": "debug_setHead", "params": [number]} + ``` +* **References:** [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/ethash/) -## `debug_setMutexProfileFraction` +### debug\_setMutexProfileFraction Sets the rate of mutex profiling. -- **Client Method invocation:** - - **Console:** `debug.setMutexProfileFraction(rate int)` -- **RPC Call:** - ```json - RPC{"method": "debug_setMutexProfileFraction", "params": [rate]} - ``` +* **Client Method invocation:** + * **Console:** `debug.setMutexProfileFraction(rate int)` +* **RPC Call:** + + ```json + RPC{"method": "debug_setMutexProfileFraction", "params": [rate]} + ``` -## `debug_setTrieFlushInterval` +### debug\_setTrieFlushInterval Configures how often in-memory state tries are persisted to disk. The interval needs to be in a format parsable by a `time.Duration`. Note that the interval is not wall-clock time. Rather it is accumulated block processing time after which the state should be flushed. For example, the value `0s` will essentially turn on archive mode. If set to `1h`, it means that after one hour of effective block processing time, the trie would be flushed. If one block takes 200ms, a flush would occur every `5*3600=18000` blocks. The default interval for mainnet is `1h`. Note: this configuration will not be persisted through restarts. -- **Client Method invocation:** - - **Console:** `debug.setTrieFlushInterval(interval string)` -- **RPC Call:** - ```json - RPC{"method": "debug_setTrieFlushInterval", "params": [interval]} - ``` +* **Client Method invocation:** + * **Console:** `debug.setTrieFlushInterval(interval string)` +* **RPC Call:** + + ```json + RPC{"method": "debug_setTrieFlushInterval", "params": [interval]} + ``` -## `debug_stacks` +### debug\_stacks Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string. -- **Client Method invocation:** - - **Console:** `debug.stacks(filter *string)` -- **RPC Call:** - ```json - RPC{"method": "debug_stacks", "params": [filter]} - ``` +* **Client Method invocation:** + * **Console:** `debug.stacks(filter *string)` +* **RPC Call:** -## `debug_standardTraceBlockToFile` + ```json + RPC{"method": "debug_stacks", "params": [filter]} + ``` + +### debug\_standardTraceBlockToFile When JS-based tracing (see below) was first implemented, the intended use case was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see PR) -It streams output to disk during the execution, to not blow up the memory usage on the node -It uses `jsonl` as output format (to allow streaming) -Uses a cross-client standardized output, so called 'standard json' -Uses `op` for string-representation of opcode, instead of `op/opName` for numeric/string, and other similar small differences. -has `refund` -Represents memory as a contiguous chunk of data, as opposed to a list of 32-byte segments like `debug_traceTransaction` -This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. +It streams output to disk during the execution, to not blow up the memory usage on the node It uses `jsonl` as output format (to allow streaming) Uses a cross-client standardized output, so called 'standard json' Uses `op` for string-representation of opcode, instead of `op/opName` for numeric/string, and other similar small differences. has `refund` Represents memory as a contiguous chunk of data, as opposed to a list of 32-byte segments like `debug_traceTransaction` This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. The method can be used to dump a certain transaction out of a given block: @@ -477,7 +490,7 @@ debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffd ["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x151741 ``` -Files are created in a temp-location, with the naming standard `block_blockhash:4>---`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does. +Files are created in a temp-location, with the naming standard `block_blockhash:4>---`. Each opcode immediately streams to file, with no in-erigon buffering aside from whatever buffering the os normally does. On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not available` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target: @@ -500,7 +513,7 @@ type StdTraceConfig struct { } ``` -```markdown +````markdown ## `debug_standardTraceBadBlockToFile` This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been rejected as invalid (for some reason). @@ -514,75 +527,81 @@ Turns on CPU profiling indefinitely, writing to the given file. - **RPC Call:** ```json RPC{"method": "debug_startCPUProfile", "params": [string]} - ``` +```` -## `debug_startGoTrace` +### debug\_startGoTrace Starts writing a Go runtime trace to the given file. -- **Client Method invocation:** - - **Console:** `debug.startGoTrace(file)` -- **RPC Call:** - ```json - RPC{"method": "debug_startGoTrace", "params": [string]} - ``` +* **Client Method invocation:** + * **Console:** `debug.startGoTrace(file)` +* **RPC Call:** + + ```json + RPC{"method": "debug_startGoTrace", "params": [string]} + ``` -## `debug_stopCPUProfile` +### debug\_stopCPUProfile Stops an ongoing CPU profile. -- **Client Method invocation:** - - **Console:** `debug.stopCPUProfile()` -- **RPC Call:** - ```json - RPC{"method": "debug_stopCPUProfile", "params": []} - ``` +* **Client Method invocation:** + * **Console:** `debug.stopCPUProfile()` +* **RPC Call:** -## `debug_stopGoTrace` + ```json + RPC{"method": "debug_stopCPUProfile", "params": []} + ``` + +### debug\_stopGoTrace Stops writing the Go runtime trace. -- **Client Method invocation:** - - **Console:** `debug.stopGoTrace()` -- **RPC Call:** - ```json - RPC{"method": "debug_stopGoTrace", "params": []} - ``` +* **Client Method invocation:** + * **Console:** `debug.stopGoTrace()` +* **RPC Call:** + + ```json + RPC{"method": "debug_stopGoTrace", "params": []} + ``` -## `debug_storageRangeAt` +### debug\_storageRangeAt Returns the storage at the given block height and transaction index. The result can be paged by providing a `maxResult` to cap the number of storage slots returned as well as specifying the offset via `keyStart` (hash of storage key). -- **Client Method invocation:** - - **Console:** `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)` -- **RPC Call:** - ```json - RPC{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]} - ``` +* **Client Method invocation:** + * **Console:** `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)` +* **RPC Call:** -## `debug_traceBadBlock` + ```json + RPC{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]} + ``` + +### debug\_traceBadBlock Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object. For the second parameter, see `TraceConfig` reference. -- **Client Method invocation:** - - **Console:** `debug.traceBadBlock(blockHash, [options])` -- **RPC Call:** - ```json - RPC{"method": "debug_traceBadBlock", "params": [blockHash, {}]} - ``` +* **Client Method invocation:** + * **Console:** `debug.traceBadBlock(blockHash, [options])` +* **RPC Call:** + + ```json + RPC{"method": "debug_traceBadBlock", "params": [blockHash, {}]} + ``` -## `debug_traceBlock` +### debug\_traceBlock The `traceBlock` method will return a full stack trace of all invoked opcodes of all transactions that were included in this block. Note, the parent of this block must be present or it will fail. For the second parameter, see `TraceConfig` reference. -- **Client Method invocation:** - - **Go:** `debug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult` - - **Console:** `debug.traceBlock(tblockRlp, [options])` -- **RPC Call:** - ```json - RPC{"method": "debug_traceBlock", "params": [blockRlp, {}]} - ``` -- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +* **Client Method invocation:** + * **Go:** `debug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult` + * **Console:** `debug.traceBlock(tblockRlp, [options])` +* **RPC Call:** + + ```json + RPC{"method": "debug_traceBlock", "params": [blockRlp, {}]} + ``` +* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) **Example:** @@ -632,46 +651,49 @@ The `traceBlock` method will return a full stack trace of all invoked opcodes of ] ``` -## `debug_traceBlockByNumber` +### debug\_traceBlockByNumber Similar to `debug_traceBlock`, `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. -- **Client Method invocation:** - - **Go:** `debug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult` - - **Console:** `debug.traceBlockByNumber(number, [options])` -- **RPC Call:** - ```json - RPC{"method": "debug_traceBlockByNumber", "params": [number, {}]} - ``` -- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +* **Client Method invocation:** + * **Go:** `debug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult` + * **Console:** `debug.traceBlockByNumber(number, [options])` +* **RPC Call:** + + ```json + RPC{"method": "debug_traceBlockByNumber", "params": [number, {}]} + ``` +* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) -## `debug_traceBlockByHash` +### debug\_traceBlockByHash Similar to `debug_traceBlock`, `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. -- **Client Method invocation:** - - **Go:** `debug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult` - - **Console:** `debug.traceBlockByHash(hash, [options])` -- **RPC Call:** - ```json - RPC{"method": "debug_traceBlockByHash", "params": [hash {}]} - ``` -- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +* **Client Method invocation:** + * **Go:** `debug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult` + * **Console:** `debug.traceBlockByHash(hash, [options])` +* **RPC Call:** -## `debug_traceBlockFromFile` + ```json + RPC{"method": "debug_traceBlockByHash", "params": [hash {}]} + ``` +* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +### debug\_traceBlockFromFile Similar to `debug_traceBlock`, `traceBlockFromFile` accepts a file containing the RLP of the block. For the second parameter, see `TraceConfig` reference. -- **Client Method invocation:** - - **Go:** `debug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult` - - **Console:** `debug.traceBlockFromFile(fileName, [options])` -- **RPC Call:** - ```json - RPC{"method": "debug_traceBlockFromFile", "params": [fileName, {}]} - ``` -- **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +* **Client Method invocation:** + * **Go:** `debug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult` + * **Console:** `debug.traceBlockFromFile(fileName, [options])` +* **RPC Call:** -## `debug_traceCall` + ```json + RPC{"method": "debug_traceBlockFromFile", "params": [fileName, {}]} + ``` +* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) + +### debug\_traceCall The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a transaction object. The block can be specified either by hash or by number as the second argument. The trace can be configured similar to `debug_traceTransaction`, see `TraceCallConfig`. The method returns the same output as `debug_traceTransaction`. @@ -679,3 +701,238 @@ The `debug_traceCall` method lets you run an `eth_call` within the context of th {"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]} ``` +**TraceCallConfig** + +TraceCallConfig is a superset of [TraceConfig](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig), providing additional arguments in addition to those provided by [TraceConfig](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig): + +* stateOverrides: StateOverride. Overrides for the state data (accounts/storage) for the call, see [StateOverride](https://geth.ethereum.org/docs/interacting-with-geth/rpc/objects#state-override-set) for more details. +* blockOverrides: BlockOverrides. Overrides for the block data (number, timestamp etc) for the call, see [BlockOverrides](https://geth.ethereum.org/docs/interacting-with-geth/rpc/objects#block-overrides) for more details. +* txIndex: NUMBER. If set, the state at the given transaction index will be used to tracing (default = the last transaction index in the block). + +**Example:** + +No specific call options: + +```javascript +> debug.traceCall(null, "0x0") +{ + failed: false, + gas: 53000, + returnValue: "", + structLogs: [] +} +``` + +Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC) + +```javascript +> debug.traceCall( + { + from: "0xdeadbeef29292929192939494959594933929292", + to: "0xde929f939d939d393f939393f93939f393929023", + gas: "0x7a120", + data: "0xf00d4b5d00000000000000000000000001291230982139282304923482304912923823920000000000000000000000001293123098123928310239129839291010293810" + }, + "latest", + { disableStorage: true, disableMemory: true } +); +``` + +It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes NUMBER is performed, and the overridden number is placed on the stack: + +```javascript +> debug.traceCall( + { + from: eth.accounts[0], + value: "0x1", + gasPrice: "0xffffffff", + gas: "0xffff", + input: "0x43" + }, + "latest", + { + "blockOverrides": {"number": "0x50"} + }) +{ + failed: false, + gas: 53018, + returnValue: "", + structLogs: [{ + depth: 1, + gas: 12519, + gasCost: 2, + op: "NUMBER", + pc: 0, + stack: [] + }, { + depth: 1, + gas: 12517, + gasCost: 0, + op: "STOP", + pc: 1, + stack: ["0x50"] + }] +} +``` + +Curl example: + +```sh +> curl -H "Content-Type: application/json" -X POST localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}' +{"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}} +``` + +#### debug\_traceChain + +Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via debug\_subscribe as follows: + +```javascript +const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])` +``` + +please refer to the [subscription page](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub) for more details. + +#### debug\_traceTransaction + +**OBS** For heavy traces and when direct access to the node disk is possible, debug.standardTraceBlockToFile is more suitable! + +The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash. + +| Client | Method invocation | +| ------- | ------------------------------------------------------------------------------------------- | +| Go | debug.TraceTransaction(txHash common.Hash, config \*TraceConfig) (\*ExecutionResult, error) | +| Console | debug.traceTransaction(txHash, \[options]) | +| RPC | {"method": "debug\_traceTransaction", "params": \[txHash, {}]} | + +**TraceConfig** + +In addition to the hash of the transaction you may give it a secondary _optional_ argument, which specifies the options for this specific call. The possible options are: + +| Field | Type | Description | +| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| tracer | String | Name for built-in tracer or Javascript expression. See below for more details. | +| tracerConfig | String | Config for the specified tracer formatted as a JSON object (see below) | +| timeout | String | Overrides the default timeout of 5 seconds for each transaction tracing, valid values are described \[here] ( [https://golang.org/pkg/time/#ParseDuration](https://golang.org/pkg/time/#ParseDuration)). | +| reexec | uint64 | The number of blocks the tracer is willing to go back and re-execute to produce missing historical state necessary to run a specific trace. (default is 128). | + +Erigon comes with a bundle of [buil](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers)[t-in tracers](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers), each providing various data about a transaction. The tracer field can be set to either a [JS expression](https://geth.ethereum.org/docs/developers/evm-tracing/custom-tracer#custom-javascript-tracing) or the name of a built-in or [custom native tracer](https://geth.ethereum.org/docs/developers/evm-tracing/custom-tracer#custom-go-tracing). If tracer is left empty the [opcode logger](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#structopcode-logger) will be chosen as default. + +TraceConfig object has more fields that are specific to the [opcode logger](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#structopcode-logger) and which will be ignored when tracer field is set to any value. For configuration of built-in tracers refer to their respective documentation. The fields are: + +| field | type | description | +| ---------------- | ------- | ---------------------------------------------------------- | +| enableMemory | BOOL | Enable memory capture (default = false) | +| disableStack | BOOL | Disable stack capture (default = false) | +| disableStorage | BOOL | Disable storage capture (default = false) | +| enableReturnData | BOOL | Enable return data capture (default = false) | +| debug | BOOL | Print output during capture end (default = false) | +| limit | INTEGER | Limit the number of steps captured (default = 0, no limit) | + +**Example:** + +```javascript +> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a") +{ + gas: 85301, + returnValue: "", + structLogs: [{ + depth: 1, + error: "", + gas: 162106, + gasCost: 3, + memory: null, + op: "PUSH1", + pc: 0, + stack: [], + storage: {} + }, + /* snip */ + { + depth: 1, + error: "", + gas: 100000, + gasCost: 0, + memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], + op: "STOP", + pc: 120, + stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], + storage: { + 0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", + 0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", + f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" + } + }] +``` + +#### debug\_verbosity + +Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed. + +The verbosity of individual packages and source files can be raised using debug\_vmodule. + +| Client | Method invocation | +| ------- | --------------------------------------------------- | +| Console | debug.verbosity(level) | +| RPC | {"method": "debug\_verbosity", "params": \[number]} | + +#### debug\_vmodule + +Sets the logging verbosity pattern. + +| Client | Method invocation | +| ------- | ------------------------------------------------- | +| Console | debug.vmodule(string) | +| RPC | {"method": "debug\_vmodule", "params": \[string]} | + +**Examples:** + +If you want to see messages from a particular Go package (directory) and all subdirectories, use: + +```javascript +> debug.vmodule("eth/*=6") +``` + +If you want to restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use: + +```javascript +> debug.vmodule("p2p=6") +``` + +If you want to see log messages from a particular source file, use + +```javascript +> debug.vmodule("server.go=6") +``` + +You can compose these basic patterns. If you want to see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use: + +```javascript +debug.vmodule('eth/*/peer.go=6,p2p=5'); +``` + +#### debug\_writeBlockProfile + +Writes a goroutine blocking profile to the given file. + +| Client | Method invocation | +| ------- | ----------------------------------------------------------- | +| Console | debug.writeBlockProfile(file) | +| RPC | {"method": "debug\_writeBlockProfile", "params": \[string]} | + +#### debug\_writeMemProfile + +Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the --pprof.memprofilerate flag. + +| Client | Method invocation | +| ------- | ----------------------------------------------------------- | +| Console | debug.writeMemProfile(file string) | +| RPC | {"method": "debug\_writeBlockProfile", "params": \[string]} | + +#### debug\_writeMutexProfile + +Writes a goroutine blocking profile to the given file. + +| Client | Method invocation | +| ------- | --------------------------------------------------------- | +| Console | debug.writeMutexProfile(file) | +| RPC | {"method": "debug\_writeMutexProfile", "params": \[file]} | From 6f846e2440b3e58d366d7f3241513cd975cffea8 Mon Sep 17 00:00:00 2001 From: bloxster Date: Tue, 20 Jan 2026 09:31:47 +0000 Subject: [PATCH 03/10] GITBOOK-4: No subject --- .../src/interacting-with-erigon/debug.md | 1003 ++++------------- 1 file changed, 242 insertions(+), 761 deletions(-) diff --git a/docs/gitbook/src/interacting-with-erigon/debug.md b/docs/gitbook/src/interacting-with-erigon/debug.md index 1ad65cc1cbf..e35aacbb81f 100644 --- a/docs/gitbook/src/interacting-with-erigon/debug.md +++ b/docs/gitbook/src/interacting-with-erigon/debug.md @@ -8,11 +8,13 @@ metaLinks: # debug -## debug +The `debug` namespace provides debugging and diagnostic methods for Erigon node operators and developers. These methods offer deep introspection into blockchain state, transaction execution, and node performance. -The `debug` namespace provides debugging and diagnostic methods for Erigon node operators and developers. These methods offer deep introspection into blockchain state, transaction execution, and node performance. The debug namespace is implemented through the `PrivateDebugAPI` interface and `DebugAPIImpl` struct. +The debug namespace must be explicitly enabled using the `--http.api=debug` flag when starting the RPC daemon. -The debug namespace must be explicitly enabled using the `--http.api` flag when starting the RPC daemon. For security reasons, these methods are considered private and should not be exposed on public RPC endpoints. +{% hint style="warning" %} +The `debug` namespace is intended for debugging and development purposes, not for production use. +{% endhint %} #### Security and Access Control @@ -22,9 +24,10 @@ The debug namespace must be explicitly enabled using the `--http.api` flag when #### Performance Considerations -* Tracing methods (`debug_traceTransaction`, `debug_traceBlockByHash`, etc.) support streaming to handle large results efficiently; +* Tracing methods (`debug_traceBlockByHash`, `debug_traceBlockByNumber`, `debug_traceTransaction`, `debug_traceCall`, `debug_traceCallMany`) support streaming for large results to reduce memory usage * The `AccountRangeMaxResults` constant limits account range queries to 8192 results, or 256 when storage is included; * Memory and GC control methods allow fine-tuning of node performance. +* Some methods like `debug_accountRange` have compatibility layers for both Geth and legacy Erigon parameter formats `debug_api` #### Integration with Erigon Architecture @@ -42,897 +45,375 @@ The debug namespace must be explicitly enabled using the `--http.api` flag when ## JSON RPC API Reference -### debug\_accountRange - -Enumerates all accounts at a given block with paging capability. `maxResults` are returned in the page and the items have keys that come after the `start` key (hashed address). - -* **Parameters:** - * `blockNrOrHash`: The block number or hash. - * `start`: The starting key (hashed address). - * `maxResults`: The maximum number of results to return. - * `nocode`: (Optional) Whether to exclude code. - * `nostorage`: (Optional) Whether to exclude storage. - * `incompletes`: (Optional) Whether to include incomplete accounts. -* **RPC Call:** - - ```json - RPC{"method": "debug_accountRange", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]} - ``` - -### debug\_backtraceAt - -Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr. - -* **Parameters:** - * `string`: The location specified as `:`. -* **RPC Call:** - - ```json - RPC{"method": "debug_backtraceAt", "params": [string]} - ``` -* **Example:** - - ```json - debug.backtraceAt("server.go:443") - ``` - -### debug\_blockProfile - -Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`. - -* **Parameters:** - * `file`: The file to write the profile data to. - * `seconds`: The duration to run the profile. -* **RPC Call:** - - ```json - RPC{"method": "debug_blockProfile", "params": [string, number]} - ``` - -### debug\_chaindbCompact - -Flattens the entire key-value database into a single level, removing all unused slots and merging all keys. - -* **RPC Call:** - - ```json - RPC{"method": "debug_chaindbCompact", "params": []} - ``` - -### debug\_chaindbProperty - -Returns leveldb properties of the key-value database. - -* **Parameters:** - * `property`: The property to retrieve. -* **RPC Call:** - - ```json - RPC{"method": "debug_chaindbProperty", "params": [property]} - ``` - -### debug\_cpuProfile - -Turns on CPU profiling for the given duration and writes profile data to disk. - -* **Parameters:** - * `file`: The file to write the profile data to. - * `seconds`: The duration to run the profile. -* **RPC Call:** - - ```json - RPC{"method": "debug_cpuProfile", "params": [string, number]} - ``` - -### debug\_dbAncient - -Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. - -* **Parameters:** - * `kind`: The table kind (e.g., headers, hashes, bodies, receipts, diffs). - * `number`: The block number. -* **RPC Call:** - - ```json - RPC{"method": "debug_dbAncient", "params": [string, number]} - ``` - -### debug\_dbAncients - -Returns the number of ancient items in the ancient store. - -* **RPC Call:** - - ```json - RPC{"method": "debug_dbAncients", "params": []} - ``` - -### debug\_dbGet - -Returns the raw value of a key stored in the database. - -* **Parameters:** - * `key`: The key to retrieve. -* **RPC Call:** - - ```json - RPC{"method": "debug_dbGet", "params": [key]} - ``` - -### debug\_dumpBlock - -Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code). - -* **Parameters:** - * `number`: The block number. -* **RPC Call:** - - ```json - RPC{"method": "debug_dumpBlock", "params": [number]} - ``` -* **Example:** - - ```json - > debug.dumpBlock(10) - { - fff7ac99c8e4feb60c9750054bdc14ce1857f181: { - balance: "49358640978154672", - code: "", - codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", - nonce: 2, - root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", - storage: {} - }, - fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: { - balance: "3460945928", - code: "", - codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", - nonce: 657, - root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", - storage: {} - } - }, - root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1" - } - ``` - -### debug\_freeOSMemory - -Forces garbage collection. - -* **RPC Call:** - - ```json - RPC{"method": "debug_freeOSMemory", "params": []} - ``` - -### debug\_freezeClient - -Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server. - -* **Parameters:** - * `node`: The node to freeze. -* **RPC Call:** - - ```json - RPC{"method": "debug_freezeClient", "params": [node]} - ``` - -### debug\_gcStats - -Returns garbage collection statistics. See [https://golang.org/pkg/runtime/debug/#GCStats](https://golang.org/pkg/runtime/debug/#GCStats) for information about the fields of the returned object. - -* **RPC Call:** - - ```json - RPC{"method": "debug_gcStats", "params": []} - ``` - -### debug\_getAccessibleState +### debug\_getRawReceipts -Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next block. The `(from, to)` parameters are the sequence of blocks to search, which can go either forwards or backwards. +Returns an array of EIP-2718 binary-encoded receipts from a single block. debug\_api. -* **Parameters:** - * `from`: The starting block number. - * `to`: The ending block number. -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_getAccessibleState", "params": [from, to]} - ``` +| Parameter | Type | Description | +| ------------- | ----------------------- | ------------------------------------------------------------------ | +| blockNrOrHash | QUANTITY \| TAG \| DATA | Block number, tag ("earliest", "latest", "pending"), or block hash | -### debug\_getBadBlocks +#### Example -Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x123456"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_getBadBlocks", "params": []} - ``` +| Type | Description | +| ------------- | -------------------------------------------- | +| Array of DATA | Array of binary-encoded transaction receipts | -### debug\_getRawBlock +### debug\_accountRange -Retrieves and returns the RLP encoded block by number. +Returns a range of accounts involved in the given block range. debug\_api. -* **Parameters:** - * `blockNrOrHash`: The block number or hash. -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_getRawBlock", "params": [blockNrOrHash]} - ``` +| Parameter | Type | Description | +| -------------- | --------------- | ----------------------------------------------------------- | +| blockNrOrHash | QUANTITY \| TAG | Block number or tag | +| start | DATAARRAY | Array of prefixes to match account addresses | +| maxResults | QUANTITY | Maximum number of accounts to retrieve | +| excludeCode | BOOLEAN | If true, exclude byte code from results | +| excludeStorage | BOOLEAN | If true, exclude storage from results | +| incompletes | BOOLEAN | If true, return missing preimages (not supported when true) | -### debug\_getRawHeader +#### Example -Returns an RLP-encoded header. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["0xaaaaa",[1],1,true,true,true],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **Parameters:** - * `blockNrOrHash`: The block number or hash. -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_getRawHeader", "params": [blockNrOrHash]} - ``` +| Type | Description | +| ------ | -------------------------------------------------- | +| Object | IteratorDump object containing account information | -### debug\_getRawTransaction +### debug\_accountAt -Returns the bytes of the transaction. +Returns account information at a specific block and transaction index. debug\_api. -* **Parameters:** - * `transactionHash`: The transaction hash. -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_getRawTransaction", "params": [transactionHash]} - ``` +| Parameter | Type | Description | +| --------- | -------------- | ---------------------------------- | +| blockHash | DATA, 32 Bytes | Hash of the block | +| txIndex | QUANTITY | Transaction index within the block | +| address | DATA, 20 Bytes | Account address | -### debug\_getModifiedAccountsByHash +#### Example -Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x123456...",1,"0x123456..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **Parameters:** - * `startHash`: The starting block hash. - * `endHash`: The ending block hash. -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]} - ``` +| Type | Description | +| ------ | ----------------------------------------------------- | +| Object | AccountResult with balance, nonce, code, and codeHash | ### debug\_getModifiedAccountsByNumber -Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash. - -* **Parameters:** - * `startNum`: The starting block number. - * `endNum`: The ending block number. -* **RPC Call:** - - ```json - RPC{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]} - ``` - -### debug\_getRawReceipts - -Returns the consensus-encoding of all receipts in a single block. - -* **Parameters:** - * `blockNrOrHash`: The block number or hash. -* **RPC Call:** - - ```json - RPC{"method": "debug_getRawReceipts", "params": [blockNrOrHash]} - ``` - -### debug\_goTrace - -Turns on Go runtime tracing for the given duration and writes trace data to disk. +Returns a list of accounts modified in the given block range by number. debug\_api. -* **Parameters:** - * `file`: The file to write the trace data to. - * `seconds`: The duration to run the trace. -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_goTrace", "params": [string, number]} - ``` +| Parameter | Type | Description | +| ----------- | --------------- | ---------------------------------- | +| startNumber | QUANTITY \| TAG | Start block number or tag | +| endNumber | QUANTITY \| TAG | End block number or tag (optional) | -### debug\_intermediateRoots +#### Example -Executes a block (bad- or canon- or side-) and returns a list of intermediate roots: the stateroot after each transaction. - -* **Parameters:** - * `blockHash`: The block hash. - * `options`: Additional options. -* **RPC Call:** - - ```json - RPC{"method": "debug_intermediateRoots", "params": [blockHash, {}]} - ``` - -### debug\_memStats - -Returns detailed runtime memory statistics. - -* **RPC Call:** - - ```json - RPC{"method": "debug_memStats", "params": []} - ``` - -### debug\_mutexProfile - -Turns on mutex profiling for `nsec` seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually. - -* **Parameters:** - * `file`: The file to write the profile data to. - * `nsec`: - -### debug\_preimage - -Returns the preimage for a sha3 hash, if known. - -* **Client Method invocation:** - * **Console:** `debug.preimage(hash)` -* **RPC Call:** - - ```json - RPC{"method": "debug_preimage", "params": [hash]} - ``` - -### debug\_printBlock +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByNumber","params":["0xccccd","0xcccce"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -Retrieves a block and returns its pretty printed form. +#### Returns -* **Client Method invocation:** - * **Console:** `debug.printBlock(number uint64)` -* **RPC Call:** +| Type | Description | +| ----------------------- | ----------------------------------- | +| Array of DATA, 20 Bytes | Array of modified account addresses | - ```json - RPC{"method": "debug_printBlock", "params": [number]} - ``` +### debug\_getModifiedAccountsByHash -### debug\_setBlockProfileRate +Returns a list of accounts modified in the given block range by hash. debug\_api. -Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`. +#### Parameters -* **Client Method invocation:** - * **Console:** `debug.setBlockProfileRate(rate)` -* **RPC Call:** +| Parameter | Type | Description | +| --------- | -------------- | -------------------------------- | +| startHash | DATA, 32 Bytes | Hash of the start block | +| endHash | DATA, 32 Bytes | Hash of the end block (optional) | - ```json - RPC{"method": "debug_setBlockProfileRate", "params": [number]} - ``` +#### Example -### debug\_setGCPercent - -Sets the garbage collection target percentage. A negative value disables garbage collection. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByHash","params":["0x2a1af0...","0x4e3d3e..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **Client Method invocation:** - * **Go:** `debug.SetGCPercent(v int)` - * **Console:** `debug.setGCPercent(v)` -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_setGCPercent", "params": [v]} - ``` +| Type | Description | +| ----------------------- | ----------------------------------- | +| Array of DATA, 20 Bytes | Array of modified account addresses | -### debug\_setHead +### debug\_storageRangeAt -Sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution. +Returns information about a range of storage locations for a contract address. debug\_api. -* **Client Method invocation:** - * **Go:** `debug.SetHead(number uint64)` - * **Console:** `debug.setHead(number)` -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_setHead", "params": [number]} - ``` -* **References:** [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/ethash/) +| Parameter | Type | Description | +| --------------- | ----------------- | --------------------------------------- | +| blockHash | DATA, 32 Bytes | Hash of block at which to retrieve data | +| txIndex | QUANTITY, 8 Bytes | Transaction index in the block | +| contractAddress | DATA, 20 Bytes | Contract address | +| keyStart | DATA, 32 Bytes | Storage key to start from | +| maxResult | QUANTITY, 8 Bytes | Maximum number of values to retrieve | -### debug\_setMutexProfileFraction +#### Example -Sets the rate of mutex profiling. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0xd3f185...",1,"0xb734c7...","0x00",2],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **Client Method invocation:** - * **Console:** `debug.setMutexProfileFraction(rate int)` -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_setMutexProfileFraction", "params": [rate]} - ``` +| Type | Description | +| ------ | --------------------------------------------------- | +| Object | StorageRangeResult with key/value pairs and nextKey | -### debug\_setTrieFlushInterval +### debug\_traceBlockByHash -Configures how often in-memory state tries are persisted to disk. The interval needs to be in a format parsable by a `time.Duration`. Note that the interval is not wall-clock time. Rather it is accumulated block processing time after which the state should be flushed. For example, the value `0s` will essentially turn on archive mode. If set to `1h`, it means that after one hour of effective block processing time, the trie would be flushed. If one block takes 200ms, a flush would occur every `5*3600=18000` blocks. The default interval for mainnet is `1h`. +Returns Geth style transaction traces for a block by hash. tracing. -Note: this configuration will not be persisted through restarts. +#### Parameters -* **Client Method invocation:** - * **Console:** `debug.setTrieFlushInterval(interval string)` -* **RPC Call:** +| Parameter | Type | Description | +| --------- | ----------------- | --------------------------- | +| hash | DATA, 32 Bytes | Hash of block to trace | +| config | Object (optional) | Trace configuration options | - ```json - RPC{"method": "debug_setTrieFlushInterval", "params": [interval]} - ``` +#### Example -### debug\_stacks +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string. +#### Returns -* **Client Method invocation:** - * **Console:** `debug.stacks(filter *string)` -* **RPC Call:** +| Type | Description | +| ----- | ---------------------------------- | +| Array | Array of transaction trace objects | - ```json - RPC{"method": "debug_stacks", "params": [filter]} - ``` +### debug\_traceBlockByNumber -### debug\_standardTraceBlockToFile +Returns Geth style transaction traces for a block by number. tracing. -When JS-based tracing (see below) was first implemented, the intended use case was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see PR) +#### Parameters -It streams output to disk during the execution, to not blow up the memory usage on the node It uses `jsonl` as output format (to allow streaming) Uses a cross-client standardized output, so called 'standard json' Uses `op` for string-representation of opcode, instead of `op/opName` for numeric/string, and other similar small differences. has `refund` Represents memory as a contiguous chunk of data, as opposed to a list of 32-byte segments like `debug_traceTransaction` This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. +| Parameter | Type | Description | +| ----------- | ----------------- | --------------------------- | +| blockNumber | QUANTITY \| TAG | Block number or tag | +| config | Object (optional) | Trace configuration options | -The method can be used to dump a certain transaction out of a given block: +#### Example -```json -debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true}) -["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"] ``` - -Or all txs from a block: - -```json -debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true}) -["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x151741 +curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x123456",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -Files are created in a temp-location, with the naming standard `block_blockhash:4>---`. Each opcode immediately streams to file, with no in-erigon buffering aside from whatever buffering the os normally does. +#### Returns -On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not available` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target: +| Type | Description | +| ----- | ---------------------------------- | +| Array | Array of transaction trace objects | -``` -INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s -INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s -INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB -INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834 -INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969 -INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484 -``` +### debug\_traceTransaction -The `options` is as follows: +Returns Geth style transaction trace. debug\_api. -```json -type StdTraceConfig struct { - *vm.LogConfig - Reexec *uint64 - TxHash *common.Hash - } -``` +#### Parameters -````markdown -## `debug_standardTraceBadBlockToFile` +| Parameter | Type | Description | +| --------- | ----------------- | ---------------------------- | +| hash | DATA, 32 Bytes | Hash of transaction to trace | +| config | Object (optional) | Trace configuration options | -This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been rejected as invalid (for some reason). +#### Example -## `debug_startCPUProfile` +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -Turns on CPU profiling indefinitely, writing to the given file. +#### Returns -- **Client Method invocation:** - - **Console:** `debug.startCPUProfile(file)` -- **RPC Call:** - ```json - RPC{"method": "debug_startCPUProfile", "params": [string]} -```` +| Type | Description | +| ------ | ------------------------ | +| Object | Transaction trace object | -### debug\_startGoTrace +### debug\_traceCall -Starts writing a Go runtime trace to the given file. +Returns Geth style call trace. debug\_api. -* **Client Method invocation:** - * **Console:** `debug.startGoTrace(file)` -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_startGoTrace", "params": [string]} - ``` +| Parameter | Type | Description | +| ------------- | ----------------------- | ----------------------------------------------------- | +| args | Object | Call arguments (to, from, gas, gasPrice, value, data) | +| blockNrOrHash | QUANTITY \| TAG \| DATA | Block number, tag, or hash | +| config | Object (optional) | Trace configuration options | -### debug\_stopCPUProfile +#### Example -Stops an ongoing CPU profile. +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x123456..."},"latest",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -* **Client Method invocation:** - * **Console:** `debug.stopCPUProfile()` -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_stopCPUProfile", "params": []} - ``` +| Type | Description | +| ------ | ----------------- | +| Object | Call trace object | -### debug\_stopGoTrace +### debug\_traceCallMany -Stops writing the Go runtime trace. +Returns Geth style traces for multiple call bundles. tracing. -* **Client Method invocation:** - * **Console:** `debug.stopGoTrace()` -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_stopGoTrace", "params": []} - ``` +| Parameter | Type | Description | +| --------------- | ----------------- | -------------------------------------------------- | +| bundles | Array | Array of transaction bundles to trace | +| simulateContext | Object | Simulation context (blockNumber, transactionIndex) | +| config | Object (optional) | Trace configuration options | -### debug\_storageRangeAt +#### Example -Returns the storage at the given block height and transaction index. The result can be paged by providing a `maxResult` to cap the number of storage slots returned as well as specifying the offset via `keyStart` (hash of storage key). - -* **Client Method invocation:** - * **Console:** `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)` -* **RPC Call:** - - ```json - RPC{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]} - ``` - -### debug\_traceBadBlock - -Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object. For the second parameter, see `TraceConfig` reference. - -* **Client Method invocation:** - * **Console:** `debug.traceBadBlock(blockHash, [options])` -* **RPC Call:** - - ```json - RPC{"method": "debug_traceBadBlock", "params": [blockHash, {}]} - ``` - -### debug\_traceBlock - -The `traceBlock` method will return a full stack trace of all invoked opcodes of all transactions that were included in this block. Note, the parent of this block must be present or it will fail. For the second parameter, see `TraceConfig` reference. - -* **Client Method invocation:** - * **Go:** `debug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult` - * **Console:** `debug.traceBlock(tblockRlp, [options])` -* **RPC Call:** - - ```json - RPC{"method": "debug_traceBlock", "params": [blockRlp, {}]} - ``` -* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) - -**Example:** - -```json -> debug.traceBlock("0xblock_rlp") -[ - { - txHash: "0xabba...", - result: { - gas: 85301, - returnValue: "", - structLogs: [{ - depth: 1, - error: "", - gas: 162106, - gasCost: 3, - memory: null, - op: "PUSH1", - pc: 0, - stack: [], - storage: {} - }, - /* snip */ - { - depth: 1, - error: "", - gas: 100000, - gasCost: 0, - memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], - op: "STOP", - pc: 120, - stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], - storage: { - 0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", - 0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", - f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" - } - }] - } - }, - { - txHash: "0xacca...", - result: { - /* snip */ - } - } -] +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCallMany","params":[[{"transactions":[...]}],{"blockNumber":"latest"},{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -### debug\_traceBlockByNumber - -Similar to `debug_traceBlock`, `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. - -* **Client Method invocation:** - * **Go:** `debug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult` - * **Console:** `debug.traceBlockByNumber(number, [options])` -* **RPC Call:** - - ```json - RPC{"method": "debug_traceBlockByNumber", "params": [number, {}]} - ``` -* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) - -### debug\_traceBlockByHash - -Similar to `debug_traceBlock`, `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. For the second parameter, see `TraceConfig` reference. - -* **Client Method invocation:** - * **Go:** `debug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult` - * **Console:** `debug.traceBlockByHash(hash, [options])` -* **RPC Call:** +#### Returns - ```json - RPC{"method": "debug_traceBlockByHash", "params": [hash {}]} - ``` -* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +| Type | Description | +| ----- | -------------------------------------- | +| Array | Array of trace results for each bundle | -### debug\_traceBlockFromFile +### debug\_setMemoryLimit -Similar to `debug_traceBlock`, `traceBlockFromFile` accepts a file containing the RLP of the block. For the second parameter, see `TraceConfig` reference. +Sets the GOMEMLIMIT for the process. debug\_api. -* **Client Method invocation:** - * **Go:** `debug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult` - * **Console:** `debug.traceBlockFromFile(fileName, [options])` -* **RPC Call:** +#### Parameters - ```json - RPC{"method": "debug_traceBlockFromFile", "params": [fileName, {}]} - ``` -* **References:** [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +| Parameter | Type | Description | +| --------- | -------- | --------------------- | +| limit | QUANTITY | Memory limit in bytes | -### debug\_traceCall +#### Example -The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a transaction object. The block can be specified either by hash or by number as the second argument. The trace can be configured similar to `debug_traceTransaction`, see `TraceCallConfig`. The method returns the same output as `debug_traceTransaction`. - -```json -{"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]} +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_setMemoryLimit","params":[8589934592],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -**TraceCallConfig** +#### Returns -TraceCallConfig is a superset of [TraceConfig](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig), providing additional arguments in addition to those provided by [TraceConfig](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig): +| Type | Description | +| -------- | --------------------- | +| QUANTITY | Previous memory limit | -* stateOverrides: StateOverride. Overrides for the state data (accounts/storage) for the call, see [StateOverride](https://geth.ethereum.org/docs/interacting-with-geth/rpc/objects#state-override-set) for more details. -* blockOverrides: BlockOverrides. Overrides for the block data (number, timestamp etc) for the call, see [BlockOverrides](https://geth.ethereum.org/docs/interacting-with-geth/rpc/objects#block-overrides) for more details. -* txIndex: NUMBER. If set, the state at the given transaction index will be used to tracing (default = the last transaction index in the block). +### debug\_setGCPercent -**Example:** +Sets the garbage collection target percentage. debug\_api. -No specific call options: +#### Parameters -```javascript -> debug.traceCall(null, "0x0") -{ - failed: false, - gas: 53000, - returnValue: "", - structLogs: [] -} -``` +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------------ | +| v | QUANTITY | GC percentage (negative value disables GC) | -Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC) +#### Example -```javascript -> debug.traceCall( - { - from: "0xdeadbeef29292929192939494959594933929292", - to: "0xde929f939d939d393f939393f93939f393929023", - gas: "0x7a120", - data: "0xf00d4b5d00000000000000000000000001291230982139282304923482304912923823920000000000000000000000001293123098123928310239129839291010293810" - }, - "latest", - { disableStorage: true, disableMemory: true } -); +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_setGCPercent","params":[100],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes NUMBER is performed, and the overridden number is placed on the stack: - -```javascript -> debug.traceCall( - { - from: eth.accounts[0], - value: "0x1", - gasPrice: "0xffffffff", - gas: "0xffff", - input: "0x43" - }, - "latest", - { - "blockOverrides": {"number": "0x50"} - }) -{ - failed: false, - gas: 53018, - returnValue: "", - structLogs: [{ - depth: 1, - gas: 12519, - gasCost: 2, - op: "NUMBER", - pc: 0, - stack: [] - }, { - depth: 1, - gas: 12517, - gasCost: 0, - op: "STOP", - pc: 1, - stack: ["0x50"] - }] -} -``` - -Curl example: - -```sh -> curl -H "Content-Type: application/json" -X POST localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}' -{"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}} -``` - -#### debug\_traceChain - -Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via debug\_subscribe as follows: - -```javascript -const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])` -``` - -please refer to the [subscription page](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub) for more details. - -#### debug\_traceTransaction - -**OBS** For heavy traces and when direct access to the node disk is possible, debug.standardTraceBlockToFile is more suitable! - -The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash. - -| Client | Method invocation | -| ------- | ------------------------------------------------------------------------------------------- | -| Go | debug.TraceTransaction(txHash common.Hash, config \*TraceConfig) (\*ExecutionResult, error) | -| Console | debug.traceTransaction(txHash, \[options]) | -| RPC | {"method": "debug\_traceTransaction", "params": \[txHash, {}]} | - -**TraceConfig** +#### Returns -In addition to the hash of the transaction you may give it a secondary _optional_ argument, which specifies the options for this specific call. The possible options are: +| Type | Description | +| -------- | ------------------------------ | +| QUANTITY | Previous GC percentage setting | -| Field | Type | Description | -| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| tracer | String | Name for built-in tracer or Javascript expression. See below for more details. | -| tracerConfig | String | Config for the specified tracer formatted as a JSON object (see below) | -| timeout | String | Overrides the default timeout of 5 seconds for each transaction tracing, valid values are described \[here] ( [https://golang.org/pkg/time/#ParseDuration](https://golang.org/pkg/time/#ParseDuration)). | -| reexec | uint64 | The number of blocks the tracer is willing to go back and re-execute to produce missing historical state necessary to run a specific trace. (default is 128). | +### debug\_freeOSMemory -Erigon comes with a bundle of [buil](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers)[t-in tracers](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers), each providing various data about a transaction. The tracer field can be set to either a [JS expression](https://geth.ethereum.org/docs/developers/evm-tracing/custom-tracer#custom-javascript-tracing) or the name of a built-in or [custom native tracer](https://geth.ethereum.org/docs/developers/evm-tracing/custom-tracer#custom-go-tracing). If tracer is left empty the [opcode logger](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#structopcode-logger) will be chosen as default. +Forces a garbage collection to free OS memory. debug\_api. -TraceConfig object has more fields that are specific to the [opcode logger](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#structopcode-logger) and which will be ignored when tracer field is set to any value. For configuration of built-in tracers refer to their respective documentation. The fields are: +#### Parameters -| field | type | description | -| ---------------- | ------- | ---------------------------------------------------------- | -| enableMemory | BOOL | Enable memory capture (default = false) | -| disableStack | BOOL | Disable stack capture (default = false) | -| disableStorage | BOOL | Disable storage capture (default = false) | -| enableReturnData | BOOL | Enable return data capture (default = false) | -| debug | BOOL | Print output during capture end (default = false) | -| limit | INTEGER | Limit the number of steps captured (default = 0, no limit) | +| Parameter | Type | Description | +| --------- | ---- | ---------------------- | +| None | - | No parameters required | -**Example:** +#### Example -```javascript -> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a") -{ - gas: 85301, - returnValue: "", - structLogs: [{ - depth: 1, - error: "", - gas: 162106, - gasCost: 3, - memory: null, - op: "PUSH1", - pc: 0, - stack: [], - storage: {} - }, - /* snip */ - { - depth: 1, - error: "", - gas: 100000, - gasCost: 0, - memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], - op: "STOP", - pc: 120, - stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], - storage: { - 0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", - 0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", - f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" - } - }] +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_freeOSMemory","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -#### debug\_verbosity - -Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed. - -The verbosity of individual packages and source files can be raised using debug\_vmodule. - -| Client | Method invocation | -| ------- | --------------------------------------------------- | -| Console | debug.verbosity(level) | -| RPC | {"method": "debug\_verbosity", "params": \[number]} | - -#### debug\_vmodule +#### Returns -Sets the logging verbosity pattern. +| Type | Description | +| ---- | --------------- | +| null | No return value | -| Client | Method invocation | -| ------- | ------------------------------------------------- | -| Console | debug.vmodule(string) | -| RPC | {"method": "debug\_vmodule", "params": \[string]} | +### debug\_gcStats -**Examples:** +Returns garbage collection statistics. debug\_api. -If you want to see messages from a particular Go package (directory) and all subdirectories, use: +#### Parameters -```javascript -> debug.vmodule("eth/*=6") -``` +| Parameter | Type | Description | +| --------- | ---- | ---------------------- | +| None | - | No parameters required | -If you want to restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use: +#### Example -```javascript -> debug.vmodule("p2p=6") ``` - -If you want to see log messages from a particular source file, use - -```javascript -> debug.vmodule("server.go=6") +curl -s --data '{"jsonrpc":"2.0","method":"debug_gcStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` -You can compose these basic patterns. If you want to see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use: +#### Returns -```javascript -debug.vmodule('eth/*/peer.go=6,p2p=5'); -``` +| Type | Description | +| ------ | -------------------- | +| Object | GC statistics object | -#### debug\_writeBlockProfile +### debug\_memStats -Writes a goroutine blocking profile to the given file. +Returns detailed runtime memory statistics. debug\_api. -| Client | Method invocation | -| ------- | ----------------------------------------------------------- | -| Console | debug.writeBlockProfile(file) | -| RPC | {"method": "debug\_writeBlockProfile", "params": \[string]} | +#### Parameters -#### debug\_writeMemProfile +| Parameter | Type | Description | +| --------- | ---- | ---------------------- | +| None | - | No parameters required | -Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the --pprof.memprofilerate flag. +#### Example -| Client | Method invocation | -| ------- | ----------------------------------------------------------- | -| Console | debug.writeMemProfile(file string) | -| RPC | {"method": "debug\_writeBlockProfile", "params": \[string]} | +``` +curl -s --data '{"jsonrpc":"2.0","method":"debug_memStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 +``` -#### debug\_writeMutexProfile +#### Returns -Writes a goroutine blocking profile to the given file. +| Type | Description | +| ------ | -------------------------------- | +| Object | Runtime memory statistics object | -| Client | Method invocation | -| ------- | --------------------------------------------------------- | -| Console | debug.writeMutexProfile(file) | -| RPC | {"method": "debug\_writeMutexProfile", "params": \[file]} | From 5421b41ee493af5f5339a323024141bab220143a Mon Sep 17 00:00:00 2001 From: bloxster Date: Tue, 20 Jan 2026 10:01:17 +0000 Subject: [PATCH 04/10] GITBOOK-5: No subject --- docs/gitbook/src/.gitbook/vars.yaml | 2 +- .../src/interacting-with-erigon/admin.md | 18 ++-- .../src/interacting-with-erigon/bor.md | 48 ++++------ .../src/interacting-with-erigon/debug.md | 94 ++++++++++++------- .../src/interacting-with-erigon/engine.md | 6 +- .../src/interacting-with-erigon/erigon.md | 42 ++++----- .../src/interacting-with-erigon/eth.md | 6 +- .../src/interacting-with-erigon/internal.md | 8 +- .../src/interacting-with-erigon/trace.md | 8 +- .../src/interacting-with-erigon/txpool.md | 16 ++-- 10 files changed, 134 insertions(+), 114 deletions(-) diff --git a/docs/gitbook/src/.gitbook/vars.yaml b/docs/gitbook/src/.gitbook/vars.yaml index e040ecdfc58..e6a9cade71e 100644 --- a/docs/gitbook/src/.gitbook/vars.yaml +++ b/docs/gitbook/src/.gitbook/vars.yaml @@ -1 +1 @@ -version: 3.2.2 +version: 3.3.3 diff --git a/docs/gitbook/src/interacting-with-erigon/admin.md b/docs/gitbook/src/interacting-with-erigon/admin.md index f0066233f6f..e6adcc86676 100644 --- a/docs/gitbook/src/interacting-with-erigon/admin.md +++ b/docs/gitbook/src/interacting-with-erigon/admin.md @@ -1,5 +1,9 @@ --- description: Security-Sensitive Methods for Node Operators +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/admin --- # admin @@ -34,7 +38,9 @@ The admin namespace must be explicitly enabled using the `--http.api` flag when *** -## **admin\_nodeInfo** +## **JSON-RPC Specification** + +### **admin\_nodeInfo** Returns information about the running node, including network details, protocols, and node identification. @@ -56,9 +62,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":"1"} | ------ | --------------------------------------------------------------- | | Object | Node information object containing network and protocol details | -*** - -## **admin\_peers** +### **admin\_peers** Returns information about connected peers, including their network addresses, protocols, and connection status. @@ -82,7 +86,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":"1"}' - *** -## **admin\_addPeer** +### **admin\_addPeer** Attempts to add a new peer to the node's peer list by connecting to the specified enode URL. @@ -106,9 +110,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":["enode://a97 | ------- | -------------------------------------------------------- | | Boolean | True if the peer was successfully added, false otherwise | -*** - -## **admin\_removePeer** +### **admin\_removePeer** Removes a peer from the node's peer list by disconnecting from the specified enode URL. diff --git a/docs/gitbook/src/interacting-with-erigon/bor.md b/docs/gitbook/src/interacting-with-erigon/bor.md index 603c0134b2f..c7d7277c4a2 100644 --- a/docs/gitbook/src/interacting-with-erigon/bor.md +++ b/docs/gitbook/src/interacting-with-erigon/bor.md @@ -1,5 +1,9 @@ --- description: Accessing Polygon Validator and Bor Consensus Data +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/bor --- # bor @@ -28,7 +32,9 @@ The bor namespace must be explicitly enabled using the `--http.api` flag when st *** -## **bor\_getSnapshot** +## **JSON-RPC Specification** + +### **bor\_getSnapshot** Returns the validator snapshot at a given block number, containing information about the current validator set and their voting power. @@ -52,9 +58,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshot","params":["latest"], | ------ | ------------------------------------------------------------------- | | Object | Snapshot object containing validator information and voting details | -*** - -## **bor\_getAuthor** +### **bor\_getAuthor** Returns the author (block proposer) of a block at the given block number or hash. @@ -78,9 +82,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getAuthor","params":["0x1b4"],"id | -------------- | ---------------------------------------- | | DATA, 20 BYTES | The address of the block author/proposer | -*** - -## **bor\_getSnapshotAtHash** +### **bor\_getSnapshotAtHash** Returns the validator snapshot at a specific block hash. @@ -104,9 +106,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshotAtHash","params":["0x1 | ------ | ---------------------------------------------------------------------------- | | Object | Snapshot object containing validator information at the specified block hash | -*** - -## **bor\_getSigners** +### **bor\_getSigners** Returns the list of authorized signers (validators) at a given block number. @@ -130,9 +130,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getSigners","params":["latest"]," | ----- | ------------------------------------------------------ | | Array | Array of validator addresses authorized to sign blocks | -*** - -## **bor\_getSignersAtHash** +### **bor\_getSignersAtHash** Returns the list of authorized signers (validators) at a specific block hash. @@ -156,9 +154,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getSignersAtHash","params":["0x1d | ----- | ---------------------------------------------------------------------------- | | Array | Array of validator addresses authorized to sign blocks at the specified hash | -*** - -## **bor\_getCurrentProposer** +### **bor\_getCurrentProposer** Returns the address of the current block proposer based on the current validator set and proposer selection algorithm. @@ -180,9 +176,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getCurrentProposer","params":[]," | -------------- | ----------------------------------- | | DATA, 20 BYTES | The address of the current proposer | -*** - -## **bor\_getCurrentValidators** +### **bor\_getCurrentValidators** Returns the current validator set with their details including voting power and other metadata. @@ -200,13 +194,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getCurrentValidators","params":[] **Returns** -| Type | Description | -| ----- | --------------------------------------------------------------------------- | -| Array | Array of validator objects with their addresses, voting power, and metadata | - -*** - -## **bor\_getSnapshotProposerSequence** +### **bor\_getSnapshotProposerSequence** Returns the proposer sequence for a given block, showing the order in which validators are expected to propose blocks. @@ -230,9 +218,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshotProposerSequence","par | ------ | ---------------------------------------------------------------- | | Object | BlockSigners object containing the proposer sequence information | -*** - -## **bor\_getRootHash** +### **bor\_getRootHash** Returns the root hash for a range of blocks, used for checkpoint verification and state synchronization. @@ -257,9 +243,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"bor_getRootHash","params":["0x1", "0x | ------ | ------------------------------------------- | | STRING | The root hash for the specified block range | -*** - -## **bor\_getVoteOnHash** +### **bor\_getVoteOnHash** Returns voting information for a specific block hash, used in the Bor consensus mechanism. diff --git a/docs/gitbook/src/interacting-with-erigon/debug.md b/docs/gitbook/src/interacting-with-erigon/debug.md index e35aacbb81f..67012c5d429 100644 --- a/docs/gitbook/src/interacting-with-erigon/debug.md +++ b/docs/gitbook/src/interacting-with-erigon/debug.md @@ -43,7 +43,7 @@ The `debug` namespace is intended for debugging and development purposes, not fo *** -## JSON RPC API Reference +## JSON-RPC Specification ### debug\_getRawReceipts @@ -57,9 +57,11 @@ Returns an array of EIP-2718 binary-encoded receipts from a single block. debug\ #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x123456"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -84,9 +86,11 @@ Returns a range of accounts involved in the given block range. debug\_api. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["0xaaaaa",[1],1,true,true,true],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -108,9 +112,11 @@ Returns account information at a specific block and transaction index. debug\_ap #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x123456...",1,"0x123456..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -131,9 +137,11 @@ Returns a list of accounts modified in the given block range by number. debug\_a #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByNumber","params":["0xccccd","0xcccce"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -154,9 +162,11 @@ Returns a list of accounts modified in the given block range by hash. debug\_api #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByHash","params":["0x2a1af0...","0x4e3d3e..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -180,9 +190,11 @@ Returns information about a range of storage locations for a contract address. d #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0xd3f185...",1,"0xb734c7...","0x00",2],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -203,9 +215,11 @@ Returns Geth style transaction traces for a block by hash. tracing. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -226,9 +240,11 @@ Returns Geth style transaction traces for a block by number. tracing. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x123456",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -249,9 +265,11 @@ Returns Geth style transaction trace. debug\_api. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -273,9 +291,11 @@ Returns Geth style call trace. debug\_api. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x123456..."},"latest",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -297,9 +317,11 @@ Returns Geth style traces for multiple call bundles. tracing. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCallMany","params":[[{"transactions":[...]}],{"blockNumber":"latest"},{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -309,7 +331,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCallMany","params":[[{"tra ### debug\_setMemoryLimit -Sets the GOMEMLIMIT for the process. debug\_api. +Sets the GOMEMLIMIT for the process. Part of `debug_api`. #### Parameters @@ -319,9 +341,11 @@ Sets the GOMEMLIMIT for the process. debug\_api. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_setMemoryLimit","params":[8589934592],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -331,7 +355,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_setMemoryLimit","params":[85899 ### debug\_setGCPercent -Sets the garbage collection target percentage. debug\_api. +Sets the garbage collection target percentage. Part of `debug_api`. #### Parameters @@ -341,9 +365,11 @@ Sets the garbage collection target percentage. debug\_api. #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_setGCPercent","params":[100],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -353,19 +379,19 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_setGCPercent","params":[100],"i ### debug\_freeOSMemory -Forces a garbage collection to free OS memory. debug\_api. +Forces a garbage collection to free OS memory. Part of `debug_api`. -#### Parameters +#### **Parameters** -| Parameter | Type | Description | -| --------- | ---- | ---------------------- | -| None | - | No parameters required | +None #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_freeOSMemory","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -375,19 +401,19 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_freeOSMemory","params":[],"id": ### debug\_gcStats -Returns garbage collection statistics. debug\_api. +Returns garbage collection statistics. Part of `debug_api`. -#### Parameters +#### **Parameters** -| Parameter | Type | Description | -| --------- | ---- | ---------------------- | -| None | - | No parameters required | +None #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_gcStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns @@ -397,19 +423,19 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_gcStats","params":[],"id":"1"}' ### debug\_memStats -Returns detailed runtime memory statistics. debug\_api. +Returns detailed runtime memory statistics. Part of `debug_api`. -#### Parameters +#### **Parameters** -| Parameter | Type | Description | -| --------- | ---- | ---------------------- | -| None | - | No parameters required | +None #### Example -``` +{% code overflow="wrap" %} +```bash curl -s --data '{"jsonrpc":"2.0","method":"debug_memStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545 ``` +{% endcode %} #### Returns diff --git a/docs/gitbook/src/interacting-with-erigon/engine.md b/docs/gitbook/src/interacting-with-erigon/engine.md index 61673e330d6..13f75109eea 100644 --- a/docs/gitbook/src/interacting-with-erigon/engine.md +++ b/docs/gitbook/src/interacting-with-erigon/engine.md @@ -1,5 +1,9 @@ --- description: Connecting Erigon (EL) to Consensus Clients (CL) +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/engine --- # engine @@ -12,7 +16,7 @@ For API usage refer to the below official resources: {% embed url="https://ethereum.org/en/developers/docs/apis/json-rpc/" %} -{% embed url="https://ethereum.github.io/execution-apis/api-documentation/" %} +{% embed url="https://ethereum.github.io/execution-apis" %} #### Default Erigon Behavior (Caplin) diff --git a/docs/gitbook/src/interacting-with-erigon/erigon.md b/docs/gitbook/src/interacting-with-erigon/erigon.md index ce486644c35..cf01c7ab197 100644 --- a/docs/gitbook/src/interacting-with-erigon/erigon.md +++ b/docs/gitbook/src/interacting-with-erigon/erigon.md @@ -1,5 +1,9 @@ --- description: Erigon-Specific Methods for Optimized Data Access +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/erigon --- # erigon @@ -28,7 +32,9 @@ See more details [here](https://github.com/erigontech/erigon/blob/main/cmd/rpcda *** -## **erigon\_forks** +## **JSON-RPC Specification** + +### **erigon\_forks** Returns the genesis block hash and a sorted list of all fork block numbers for the current chain configuration. @@ -53,9 +59,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_forks","params":[],"id":"1"}' | heightForks | ARRAY - Array of block numbers where height-based forks occur | | timeForks | ARRAY - Array of timestamps where time-based forks occur | -*** - -## **erigon\_blockNumber** +### **erigon\_blockNumber** Returns the latest executed block number. Unlike `eth_blockNumber`, this method can accept a specific block number parameter and returns the latest executed block rather than the fork choice head after the merge. @@ -79,9 +83,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_blockNumber","params":[],"id": | -------- | ------------------------------- | | QUANTITY | The block number as hexadecimal | -*** - -## **erigon\_getHeaderByNumber** +### **erigon\_getHeaderByNumber** Returns a block header by block number, ignoring transaction and uncle data for potentially faster response times. @@ -105,9 +107,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getHeaderByNumber","params":[" | ------ | ------------------------------------------ | | Object | Block header object with all header fields | -*** - -## **erigon\_getHeaderByHash** +### **erigon\_getHeaderByHash** Returns a block header by block hash, ignoring transaction and uncle data for potentially faster response times. @@ -133,7 +133,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getHeaderByHash","params":["0x *** -## **erigon\_getBlockByTimestamp** +### **erigon\_getBlockByTimestamp** Returns a block by timestamp using binary search to find the closest block to the specified timestamp. @@ -158,9 +158,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBlockByTimestamp","params": | ------ | ---------------------------------------------- | | Object | Block object matching closest to the timestamp | -*** - -## **erigon\_getBalanceChangesInBlock** +### **erigon\_getBalanceChangesInBlock** Returns all account balance changes that occurred within a specific block. @@ -184,9 +182,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBalanceChangesInBlock","par | ------ | ------------------------------------------------ | | Object | Mapping of addresses to their new balance values | -*** - -## **erigon\_getLogsByHash** +### **erigon\_getLogsByHash** Returns an array of arrays of logs generated by transactions in a block given by block hash. @@ -210,9 +206,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLogsByHash","params":["0x1d | ----- | --------------------------------------------------------- | | Array | Array of arrays of log objects, one array per transaction | -*** - -## **erigon\_getLogs** +### **erigon\_getLogs** Returns an array of logs matching a given filter object with enhanced filtering capabilities. @@ -236,9 +230,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLogs","params":[{"fromBlock | ----- | ------------------------------------------------- | | Array | Array of ErigonLog objects with enhanced metadata | -*** - -## **erigon\_getLatestLogs** +### **erigon\_getLatestLogs** Returns the latest logs matching a filter criteria in descending order with advanced pagination and topic matching options. @@ -265,7 +257,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLatestLogs","params":[{"add *** -## **erigon\_getBlockReceiptsByBlockHash** +### **erigon\_getBlockReceiptsByBlockHash** Returns all transaction receipts for a canonical block by block hash. @@ -291,7 +283,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBlockReceiptsByBlockHash"," *** -## **erigon\_nodeInfo** +### **erigon\_nodeInfo** Returns a collection of metadata known about the host node and connected peers. diff --git a/docs/gitbook/src/interacting-with-erigon/eth.md b/docs/gitbook/src/interacting-with-erigon/eth.md index 288bbe25d40..7c8d03863d4 100644 --- a/docs/gitbook/src/interacting-with-erigon/eth.md +++ b/docs/gitbook/src/interacting-with-erigon/eth.md @@ -12,13 +12,15 @@ The `eth` namespace is the foundational and most commonly used API set in Ethere Key methods within this namespace allow you to check an account's balance (`eth_getBalance`), get the current block number (`eth_blockNumber`), retrieve transaction details (`eth_getTransactionByHash`), and send signed transactions to the network (`eth_sendRawTransaction`). Essentially, the `eth` namespace contains all the fundamental tools needed to observe and participate in the life of the chain. -### API usage +## JSON-RPC Specification For API usage refer to the below official resources: {% embed url="https://ethereum.org/en/developers/docs/apis/json-rpc/" %} -{% embed url="https://ethereum.github.io/execution-apis/api-documentation/" %} +{% embed url="https://ethereum.github.io/execution-apis/" %} + + ### eth\_getProof diff --git a/docs/gitbook/src/interacting-with-erigon/internal.md b/docs/gitbook/src/interacting-with-erigon/internal.md index 2d494641c54..bc04bb38f8c 100644 --- a/docs/gitbook/src/interacting-with-erigon/internal.md +++ b/docs/gitbook/src/interacting-with-erigon/internal.md @@ -1,12 +1,18 @@ --- description: Internal Methods for Erigon Development and Debugging +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/internal --- # internal The **`internal_`** methods are for development and debugging utilities and must be explicitly included in the `--http.api` flag if customizing enabled namespaces. -## **internal\_getTxNumInfo** +## JSON-RPC Specification + +### **`internal_getTxNumInfo`** Returns transaction number information for development and debugging purposes. This is part of Erigon's internal APIs and may change without notice. diff --git a/docs/gitbook/src/interacting-with-erigon/trace.md b/docs/gitbook/src/interacting-with-erigon/trace.md index 0e62418ed1f..10f4005bcbd 100644 --- a/docs/gitbook/src/interacting-with-erigon/trace.md +++ b/docs/gitbook/src/interacting-with-erigon/trace.md @@ -1,5 +1,9 @@ --- description: Inspecting Transaction Execution with Trace, VMTrace, and StateDiff +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/trace --- # trace @@ -58,7 +62,7 @@ then it should look something like: `[ {A: []}, {B: [0]}, {G: [0, 0]}, {C: [1]}, {G: [1, 0]} ]` -## JSON-RPC methods +## JSON-RPC Specification #### Ad-hoc Tracing @@ -75,8 +79,6 @@ then it should look something like: * [trace\_get](trace.md#trace_get) * [trace\_transaction](trace.md#trace_transaction) -## JSON-RPC API Reference - ### trace\_call Executes the given call and returns a number of possible traces for it. diff --git a/docs/gitbook/src/interacting-with-erigon/txpool.md b/docs/gitbook/src/interacting-with-erigon/txpool.md index 27848993ea8..af1c6bb650b 100644 --- a/docs/gitbook/src/interacting-with-erigon/txpool.md +++ b/docs/gitbook/src/interacting-with-erigon/txpool.md @@ -1,5 +1,9 @@ --- description: Inspecting Unconfirmed Transactions in Erigon +metaLinks: + alternates: + - >- + https://app.gitbook.com/s/3DGBf2RdbfoitX1XMgq0/interacting-with-erigon/interacting-with-erigon/txpool --- # txpool @@ -45,7 +49,9 @@ The txpool namespace must be explicitly enabled using the `--http.api` flag when *** -## **txpool\_content** +## **JSON-RPC Specification** + +### **txpool\_content** Returns the content of the transaction pool, organized by sender address and categorized into pending, queued, and baseFee sub-pools. @@ -70,9 +76,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"txpool_content","params":[],"id":"1"} | baseFee | Object | | queued | Object | -*** - -## **txpool\_contentFrom** +### **txpool\_contentFrom** Returns the content of the transaction pool for a specific sender address, showing all transactions from that address across all sub-pools. @@ -99,9 +103,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"txpool_contentFrom","params":["0xb60e | baseFee | Object | | queued | Object | -*** - -## **txpool\_status** +### **txpool\_status** Returns the current status of the transaction pool, including the count of transactions in each sub-pool. From ab0f9895bb73d821d7d8dd464997efb942d79eb0 Mon Sep 17 00:00:00 2001 From: bloxster Date: Tue, 20 Jan 2026 10:50:51 +0000 Subject: [PATCH 05/10] GITBOOK-6: No subject --- .../src/interacting-with-erigon/debug.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/gitbook/src/interacting-with-erigon/debug.md b/docs/gitbook/src/interacting-with-erigon/debug.md index 67012c5d429..953540f841c 100644 --- a/docs/gitbook/src/interacting-with-erigon/debug.md +++ b/docs/gitbook/src/interacting-with-erigon/debug.md @@ -47,7 +47,7 @@ The `debug` namespace is intended for debugging and development purposes, not fo ### debug\_getRawReceipts -Returns an array of EIP-2718 binary-encoded receipts from a single block. debug\_api. +Returns an array of EIP-2718 binary-encoded receipts from a single block. #### Parameters @@ -71,7 +71,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x12 ### debug\_accountRange -Returns a range of accounts involved in the given block range. debug\_api. +Returns a range of accounts involved in the given block range. #### Parameters @@ -100,7 +100,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["0xaaaa ### debug\_accountAt -Returns account information at a specific block and transaction index. debug\_api. +Returns account information at a specific block and transaction index. #### Parameters @@ -126,7 +126,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x123456. ### debug\_getModifiedAccountsByNumber -Returns a list of accounts modified in the given block range by number. debug\_api. +Returns a list of accounts modified in the given block range by number. #### Parameters @@ -151,7 +151,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByNumber","p ### debug\_getModifiedAccountsByHash -Returns a list of accounts modified in the given block range by hash. debug\_api. +Returns a list of accounts modified in the given block range by hash. #### Parameters @@ -176,7 +176,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByHash","par ### debug\_storageRangeAt -Returns information about a range of storage locations for a contract address. debug\_api. +Returns information about a range of storage locations for a contract address. #### Parameters @@ -204,7 +204,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0xd3 ### debug\_traceBlockByHash -Returns Geth style transaction traces for a block by hash. tracing. +Returns Geth style transaction traces for a block by hash. #### Parameters @@ -229,7 +229,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0x ### debug\_traceBlockByNumber -Returns Geth style transaction traces for a block by number. tracing. +Returns Geth style transaction traces for a block by number. #### Parameters @@ -254,7 +254,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":[" ### debug\_traceTransaction -Returns Geth style transaction trace. debug\_api. +Returns Geth style transaction trace. #### Parameters @@ -279,7 +279,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x ### debug\_traceCall -Returns Geth style call trace. debug\_api. +Returns Geth style call trace. #### Parameters @@ -305,7 +305,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x1 ### debug\_traceCallMany -Returns Geth style traces for multiple call bundles. tracing. +Returns Geth style traces for multiple call bundles. #### Parameters @@ -331,7 +331,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCallMany","params":[[{"tra ### debug\_setMemoryLimit -Sets the GOMEMLIMIT for the process. Part of `debug_api`. +Sets the GOMEMLIMIT for the process. #### Parameters @@ -355,7 +355,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_setMemoryLimit","params":[85899 ### debug\_setGCPercent -Sets the garbage collection target percentage. Part of `debug_api`. +Sets the garbage collection target percentage. #### Parameters @@ -379,7 +379,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_setGCPercent","params":[100],"i ### debug\_freeOSMemory -Forces a garbage collection to free OS memory. Part of `debug_api`. +Forces a garbage collection to free OS memory. #### **Parameters** @@ -401,7 +401,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_freeOSMemory","params":[],"id": ### debug\_gcStats -Returns garbage collection statistics. Part of `debug_api`. +Returns garbage collection statistics. #### **Parameters** @@ -423,7 +423,7 @@ curl -s --data '{"jsonrpc":"2.0","method":"debug_gcStats","params":[],"id":"1"}' ### debug\_memStats -Returns detailed runtime memory statistics. Part of `debug_api`. +Returns detailed runtime memory statistics. #### **Parameters** From 8f4631f691636884bfe90d41b816ba0b36e86a56 Mon Sep 17 00:00:00 2001 From: bloxster Date: Tue, 20 Jan 2026 11:00:15 +0000 Subject: [PATCH 06/10] GITBOOK-7: No subject --- .../src/interacting-with-erigon/trace.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/gitbook/src/interacting-with-erigon/trace.md b/docs/gitbook/src/interacting-with-erigon/trace.md index 10f4005bcbd..cbfaed32063 100644 --- a/docs/gitbook/src/interacting-with-erigon/trace.md +++ b/docs/gitbook/src/interacting-with-erigon/trace.md @@ -62,6 +62,8 @@ then it should look something like: `[ {A: []}, {B: [0]}, {G: [0, 0]}, {C: [1]}, {G: [1, 0]} ]` +*** + ## JSON-RPC Specification #### Ad-hoc Tracing @@ -127,8 +129,6 @@ Response } ``` -*** - ### trace\_callMany Performs multiple call traces on top of the same block. i.e. transaction `n` will be executed on top of a pending block with all `n-1` transactions applied (traced) first. Allows to trace dependent transactions. @@ -231,8 +231,6 @@ Response } ``` -*** - ### trace\_rawTransaction Traces a call to `eth_sendRawTransaction` without making the call, returning the traces @@ -289,8 +287,6 @@ Response } ``` -*** - ### trace\_replayBlockTransactions Replays all transactions in a block returning the requested traces for each transaction. @@ -349,8 +345,6 @@ Response } ``` -*** - ### trace\_replayTransaction Replays a transaction, returning the traces. @@ -405,8 +399,6 @@ Response } ``` -*** - ### trace\_block Returns traces created at given block. @@ -468,8 +460,6 @@ Response } ``` -*** - ### trace\_filter Returns traces matching given filter @@ -541,8 +531,6 @@ Response } ``` -*** - ### trace\_get Returns trace at given position. @@ -605,8 +593,6 @@ Response } ``` -*** - ### trace\_transaction Returns all traces of given transaction From 1e954bb4148c027d90cc2eacf31e31a3c0df7ecb Mon Sep 17 00:00:00 2001 From: bloxster Date: Tue, 20 Jan 2026 11:13:39 +0000 Subject: [PATCH 07/10] GITBOOK-8: No subject --- .../src/fundamentals/configuring-erigon.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/gitbook/src/fundamentals/configuring-erigon.md b/docs/gitbook/src/fundamentals/configuring-erigon.md index 595ab645a51..876ed8e1515 100644 --- a/docs/gitbook/src/fundamentals/configuring-erigon.md +++ b/docs/gitbook/src/fundamentals/configuring-erigon.md @@ -74,14 +74,14 @@ These flags control database performance and memory usage. Flags for managing how old chain data is handled and stored. -* `--prune.mode value`: Selects a pruning preset (`full`, `archive`, `minimal`, `blocks`). See also [Sync Modes](../fundamentals/sync-modes.md) +* `--prune.mode value`: Selects a pruning preset (`full`, `archive`, `minimal`, `blocks`). See also [Sync Modes](sync-modes.md) * Default: `"full"` * `--prune.distance value`: Keeps state history for the latest `N` blocks. * Default: `0` * `--prune.distance.blocks value`: Keeps block history for the latest `N` blocks. * Default: `0` * `--prune.experimental.include-commitment-history, --experimental.commitment-history`: Enables faster `eth_getProof` for executed blocks. - * Default: `false` + * Default: `false` * `--prune.include-commitment-history` : (experimental) Enables the storage of commitment history. When enabled, it allows for blazing fast retrieval of Merkle proofs for executed blocks using the `eth_getProof` JSON-RPC method. * Default: `false` * `--snap.keepblocks`: Keeps ancient blocks in the database for debugging. @@ -557,7 +557,7 @@ USAGE: erigon [command] [flags] VERSION: - 3.3.0-dev-fc7a858a + 3.3.3-7bc3d6d1 COMMANDS: init Bootstrap and initialize a new genesis block @@ -602,7 +602,6 @@ GLOBAL OPTIONS: --tls.key value Specify key file --tls.cacert value Specify certificate authority --state.stream.disable Disable streaming of state changes from core to RPC daemon (default: false) - --experimental.bal generate block access list (default: false) --sync.loop.throttle value Sets the minimum time between sync loop starts (e.g. 1h30m, default is none) --bad.block value Marks block with given hex string as bad and forces initial reorg before normal staged sync --http JSON-RPC server (enabled by default). Use --http=false to disable it (default: true) @@ -655,7 +654,7 @@ GLOBAL OPTIONS: --snap.state.stop Workaround to stop producing new state files, if you meet some state-related critical bug. It will stop aggregate DB history in a state files. DB will grow and may slightly slow-down - and removing this flag in future will not fix this effect (db size will not greatly reduce). (default: false) --snap.skip-state-snapshot-download Skip state download and start from genesis block (default: false) --snap.download.to.block value, --shadow.fork.block value Download snapshots up to the given block number (exclusive). Disabled by default. Useful for testing and shadow forks. (default: 0) - --db.pagesize value DB is split to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintenance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") + --db.pagesize value DB is splitted to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintainance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") --db.size.limit value Runtime limit of chaindata db size (can change at any time) (default: "1TB") --db.writemap Enable WRITE_MAP feature for fast database writes and fast commit times (default: true) --torrent.port value Port to listen and serve BitTorrent protocol (default: 42069) @@ -679,7 +678,8 @@ GLOBAL OPTIONS: "stun" Uses STUN to detect an external IP using a default server "stun:" Uses STUN to detect an external IP using the given server (host:port) --nodiscover Disables the peer discovery mechanism (manual peer addition) (default: false) - --v5disc Enables the experimental RLPx V5 (Topic Discovery) mechanism (default: false) + --discovery.v4, --discv4 Enables the V4 discovery mechanism (default: false) + --discovery.v5, --discv5 Enables the V5 discovery mechanism (default: false) --netrestrict value Restricts network communication to the given IP networks (CIDR masks) --nodekey value P2P node key file --nodekeyhex value P2P node key as hex (for testing) @@ -723,6 +723,7 @@ GLOBAL OPTIONS: --aa Enable AA transactions (default: false) --ethstats value Reporting URL of a ethstats service (nodename:secret@host:port) --override.osaka value Manually specify the Osaka fork time, overriding the bundled setting (default: 0) + --override.balancer value Manually specify the Balancer fork time, overriding the bundled setting (default: 0) --keep.stored.chain.config Avoid overriding chain config already stored in the DB (default: false) --caplin.discovery.addr value Address for Caplin DISCV5 protocol (default: "0.0.0.0") --caplin.discovery.port value Port for Caplin DISCV5 protocol (default: 4000) @@ -763,7 +764,7 @@ GLOBAL OPTIONS: --caplin.blocks-archive sets whether backfilling is enabled for caplin (default: false) --caplin.blobs-archive sets whether backfilling is enabled for caplin (default: false) --caplin.states-archive enables archival node for historical states in caplin (it will enable block archival as well) (default: false) - --caplin.blobs-immediate-backfill sets whether caplin should immediately backfill blobs (4096 epochs) (default: false) + --caplin.blobs-immediate-backfill sets whether caplin should immediatelly backfill blobs (4096 epochs) (default: false) --caplin.blobs-no-pruning disable blob pruning in caplin (default: false) --caplin.checkpoint-sync.disable disable checkpoint sync in caplin (default: false) --caplin.snapgen enables snapshot generation in caplin (default: false) @@ -773,7 +774,7 @@ GLOBAL OPTIONS: --caplin.custom-genesis value set the custom genesis for caplin --caplin.use-engine-api Use engine API for internal Caplin. useful for testing and if CL network is degraded (default: false) --trusted-setup-file value Absolute path to trusted_setup.json file - --rpc.slow value Print in logs RPC requests slower than given threshold: 100ms, 1s, 1m. Excluded methods: eth_getBlock,eth_getBlockByNumber,eth_getBlockByHash,eth_blockNumber,erigon_blockNumber,erigon_getHeaderByNumber,erigon_getHeaderByHash,erigon_getBlockByTimestamp,eth_call (default: 0s) + --rpc.slow value Print in logs RPC requests slower than given threshold: 100ms, 1s, 1m. Exluded methods: eth_getBlock,eth_getBlockByNumber,eth_getBlockByHash,eth_blockNumber,erigon_blockNumber,erigon_getHeaderByNumber,erigon_getHeaderByHash,erigon_getBlockByTimestamp,eth_call (default: 0s) --txpool.gossip.disable Disabling p2p gossip of txs. Any txs received by p2p - will be dropped. Some networks like 'Optimism execution engine'/'Optimistic Rollup' - using it to protect against MEV attacks (default: false) --sync.loop.block.limit value Sets the maximum number of blocks to process per loop iteration (default: 5000) --sync.loop.break.after value Sets the last stage of the sync loop to run From ea0d4b95abed4d119650ce64a1a2ae5cd0e10a01 Mon Sep 17 00:00:00 2001 From: bloxster Date: Fri, 23 Jan 2026 10:30:58 +0000 Subject: [PATCH 08/10] GITBOOK-9: No subject --- .../gitbook/src/fundamentals/configuring-erigon.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/gitbook/src/fundamentals/configuring-erigon.md b/docs/gitbook/src/fundamentals/configuring-erigon.md index 876ed8e1515..fc84a1fd799 100644 --- a/docs/gitbook/src/fundamentals/configuring-erigon.md +++ b/docs/gitbook/src/fundamentals/configuring-erigon.md @@ -557,7 +557,7 @@ USAGE: erigon [command] [flags] VERSION: - 3.3.3-7bc3d6d1 + 3.3.4-745451f6 COMMANDS: init Bootstrap and initialize a new genesis block @@ -568,8 +568,8 @@ COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - --datadir value Data directory for the databases (default: /home/user/.local/share/erigon) - --ethash.dagdir value Directory to store the ethash mining DAGs (default: /home/user/.local/share/erigon-ethash) + --datadir value Data directory for the databases (default: /home/bloxster/.local/share/erigon) + --ethash.dagdir value Directory to store the ethash mining DAGs (default: /home/bloxster/.local/share/erigon-ethash) --externalcl Enables the external consensus layer (default: false) --txpool.disable External pool and block producer, see ./cmd/txpool/readme.md for more info. Disabling internal txpool and block producer. (default: false) --txpool.pricelimit value Minimum gas price (fee cap) limit to enforce for acceptance into the pool (default: 1) @@ -591,6 +591,8 @@ GLOBAL OPTIONS: archive: Keep the entire state history and all blocks, minimal: Keep only latest state (default: "full") --prune.include-commitment-history, --experimental.commitment-history, --prune.experimental.include-commitment-history Enables blazing fast eth_getProof for executed block (default: false) + --fcu.timeout value FCU timeout before it switches to being process async (use 0 to disable) (default: 1s) + --fcu.background.prune Enables background pruning post fcu (default: true) --batchSize value Batch size for the execution stage (default: "512M") --bodies.cache value Limit on the cache for block bodies (default: "268435456") --database.verbosity value Enabling internal db logs. Very high verbosity levels may require recompile db. Default: 2, means warning. (default: 2) @@ -635,6 +637,7 @@ GLOBAL OPTIONS: --rpc.txfeecap value Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap) (default: 1) --txpool.api.addr value TxPool api network address, for example: 127.0.0.1:9090 (default: use value of --private.api.addr) --trace.maxtraces value Sets a limit on traces that can be returned in trace_filter (default: 200) + --experimental.always-generate-changesets Allows to override changesets generation logic (default: false) --http.timeouts.read value Maximum duration for reading the entire request, including the body. (default: 30s) --http.timeouts.write value Maximum duration before timing out writes of the response. It is reset whenever a new request's header is read. (default: 30m0s) --http.timeouts.idle value Maximum amount of time to wait for the next request when keep-alive connections are enabled. If http.timeouts.idle is zero, the value of http.timeouts.read is used. (default: 2m0s) @@ -654,7 +657,7 @@ GLOBAL OPTIONS: --snap.state.stop Workaround to stop producing new state files, if you meet some state-related critical bug. It will stop aggregate DB history in a state files. DB will grow and may slightly slow-down - and removing this flag in future will not fix this effect (db size will not greatly reduce). (default: false) --snap.skip-state-snapshot-download Skip state download and start from genesis block (default: false) --snap.download.to.block value, --shadow.fork.block value Download snapshots up to the given block number (exclusive). Disabled by default. Useful for testing and shadow forks. (default: 0) - --db.pagesize value DB is splitted to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintainance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") + --db.pagesize value DB is split to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintenance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") --db.size.limit value Runtime limit of chaindata db size (can change at any time) (default: "1TB") --db.writemap Enable WRITE_MAP feature for fast database writes and fast commit times (default: true) --torrent.port value Port to listen and serve BitTorrent protocol (default: 42069) @@ -764,7 +767,7 @@ GLOBAL OPTIONS: --caplin.blocks-archive sets whether backfilling is enabled for caplin (default: false) --caplin.blobs-archive sets whether backfilling is enabled for caplin (default: false) --caplin.states-archive enables archival node for historical states in caplin (it will enable block archival as well) (default: false) - --caplin.blobs-immediate-backfill sets whether caplin should immediatelly backfill blobs (4096 epochs) (default: false) + --caplin.blobs-immediate-backfill sets whether caplin should immediately backfill blobs (4096 epochs) (default: false) --caplin.blobs-no-pruning disable blob pruning in caplin (default: false) --caplin.checkpoint-sync.disable disable checkpoint sync in caplin (default: false) --caplin.snapgen enables snapshot generation in caplin (default: false) @@ -813,5 +816,6 @@ GLOBAL OPTIONS: --config value Sets erigon flags from YAML/TOML file --help, -h show help --version, -v print the version + ``` {% endcode %} From ddee3ac2f6396a6ff3e1fdec4e480b72bb579b62 Mon Sep 17 00:00:00 2001 From: bloxster Date: Mon, 26 Jan 2026 14:20:11 +0000 Subject: [PATCH 09/10] GITBOOK-10: No subject --- docs/gitbook/src/fundamentals/configuring-erigon.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/gitbook/src/fundamentals/configuring-erigon.md b/docs/gitbook/src/fundamentals/configuring-erigon.md index fc84a1fd799..672feebb314 100644 --- a/docs/gitbook/src/fundamentals/configuring-erigon.md +++ b/docs/gitbook/src/fundamentals/configuring-erigon.md @@ -568,8 +568,8 @@ COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - --datadir value Data directory for the databases (default: /home/bloxster/.local/share/erigon) - --ethash.dagdir value Directory to store the ethash mining DAGs (default: /home/bloxster/.local/share/erigon-ethash) + --datadir value Data directory for the databases (default: /home/user/.local/share/erigon) + --ethash.dagdir value Directory to store the ethash mining DAGs (default: /home/user/.local/share/erigon-ethash) --externalcl Enables the external consensus layer (default: false) --txpool.disable External pool and block producer, see ./cmd/txpool/readme.md for more info. Disabling internal txpool and block producer. (default: false) --txpool.pricelimit value Minimum gas price (fee cap) limit to enforce for acceptance into the pool (default: 1) @@ -682,7 +682,7 @@ GLOBAL OPTIONS: "stun:" Uses STUN to detect an external IP using the given server (host:port) --nodiscover Disables the peer discovery mechanism (manual peer addition) (default: false) --discovery.v4, --discv4 Enables the V4 discovery mechanism (default: false) - --discovery.v5, --discv5 Enables the V5 discovery mechanism (default: false) + --discovery.v5, --discv5 Enables the V5 discovery mechanism (default: true) --netrestrict value Restricts network communication to the given IP networks (CIDR masks) --nodekey value P2P node key file --nodekeyhex value P2P node key as hex (for testing) From 32ba1a2b115da6ea946dc9dceca9153eddbbdc84 Mon Sep 17 00:00:00 2001 From: Bloxster Date: Wed, 4 Feb 2026 09:03:25 +0100 Subject: [PATCH 10/10] updated --h to 3.3.7 --- docs/gitbook/src/.gitbook/vars.yaml | 2 +- docs/gitbook/src/fundamentals/configuring-erigon.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/gitbook/src/.gitbook/vars.yaml b/docs/gitbook/src/.gitbook/vars.yaml index e6a9cade71e..31ff46613bd 100644 --- a/docs/gitbook/src/.gitbook/vars.yaml +++ b/docs/gitbook/src/.gitbook/vars.yaml @@ -1 +1 @@ -version: 3.3.3 +version: 3.3.7 diff --git a/docs/gitbook/src/fundamentals/configuring-erigon.md b/docs/gitbook/src/fundamentals/configuring-erigon.md index 672feebb314..b16fd69ce71 100644 --- a/docs/gitbook/src/fundamentals/configuring-erigon.md +++ b/docs/gitbook/src/fundamentals/configuring-erigon.md @@ -557,7 +557,7 @@ USAGE: erigon [command] [flags] VERSION: - 3.3.4-745451f6 + 3.3.7-9a898cf7 COMMANDS: init Bootstrap and initialize a new genesis block @@ -657,7 +657,7 @@ GLOBAL OPTIONS: --snap.state.stop Workaround to stop producing new state files, if you meet some state-related critical bug. It will stop aggregate DB history in a state files. DB will grow and may slightly slow-down - and removing this flag in future will not fix this effect (db size will not greatly reduce). (default: false) --snap.skip-state-snapshot-download Skip state download and start from genesis block (default: false) --snap.download.to.block value, --shadow.fork.block value Download snapshots up to the given block number (exclusive). Disabled by default. Useful for testing and shadow forks. (default: 0) - --db.pagesize value DB is split to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintenance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") + --db.pagesize value DB is splitted to 'pages' of fixed size. Can't change DB creation. Must be power of 2 and '256b <= pagesize <= 64kb'. Default: equal to OperationSystem's pageSize. Bigger pageSize causing: 1. More writes to disk during commit 2. Smaller b-tree high 3. Less fragmentation 4. Less overhead on 'free-pages list' maintainance (a bit faster Put/Commit) 5. If expecting DB-size > 8Tb then set pageSize >= 8Kb (default: "16KB") --db.size.limit value Runtime limit of chaindata db size (can change at any time) (default: "1TB") --db.writemap Enable WRITE_MAP feature for fast database writes and fast commit times (default: true) --torrent.port value Port to listen and serve BitTorrent protocol (default: 42069) @@ -681,8 +681,8 @@ GLOBAL OPTIONS: "stun" Uses STUN to detect an external IP using a default server "stun:" Uses STUN to detect an external IP using the given server (host:port) --nodiscover Disables the peer discovery mechanism (manual peer addition) (default: false) - --discovery.v4, --discv4 Enables the V4 discovery mechanism (default: false) - --discovery.v5, --discv5 Enables the V5 discovery mechanism (default: true) + --discovery.v4, --discv4 Enables the V4 discovery mechanism (default: true) + --discovery.v5, --discv5, --v5disc Enables the V5 discovery mechanism (default: true) --netrestrict value Restricts network communication to the given IP networks (CIDR masks) --nodekey value P2P node key file --nodekeyhex value P2P node key as hex (for testing) @@ -767,7 +767,7 @@ GLOBAL OPTIONS: --caplin.blocks-archive sets whether backfilling is enabled for caplin (default: false) --caplin.blobs-archive sets whether backfilling is enabled for caplin (default: false) --caplin.states-archive enables archival node for historical states in caplin (it will enable block archival as well) (default: false) - --caplin.blobs-immediate-backfill sets whether caplin should immediately backfill blobs (4096 epochs) (default: false) + --caplin.blobs-immediate-backfill sets whether caplin should immediatelly backfill blobs (4096 epochs) (default: false) --caplin.blobs-no-pruning disable blob pruning in caplin (default: false) --caplin.checkpoint-sync.disable disable checkpoint sync in caplin (default: false) --caplin.snapgen enables snapshot generation in caplin (default: false)