XGR Chain — Node Operator RPC & Internals
v3.4.0 update: The current release and fork-dependent changes are specified in v3.4.0 release and activation. Interchain uses Direct-BLS message authorization and independent delivery; older checkpoint/Merkle transport descriptions do not apply to the current Interchain runtime. This does not remove the chain state/transaction tries.
Document ID: XGRCHAIN-NODE-OPERATOR-RPC
Last updated: 2026-10-27
Audience: Node operators, validator operators, infrastructure engineers, tracing operators, internal tooling developers
Release baseline: xgr-node v3.4.0
Release commit: cbe6f8a4ae1718429a9924dcf87f0d28591d74e1
Node implementation: xgr-network/xgr-node
Scope: Operator-facing JSON-RPC, tracing, txpool, XGR-specific diagnostic endpoints and gRPC services
1. Scope
This document describes operator-facing node interfaces in xgr-node v3.4.0.
It covers:
- registered JSON-RPC namespaces,
- dispatcher behavior,
debug_*tracing,- trace configuration,
- debug request throttling,
txpool_*inspection,- txpool internals,
bridge_*compatibility endpoints,xgr_*public-node behavior,- native interchain-attestation RPC,
- public-build engine stub behavior,
- gRPC operator services,
- historical-state requirements for tracing,
- operational security,
- troubleshooting.
This is not the primary application JSON-RPC reference.
Standard Ethereum-compatible methods are documented in:
XGRCHAIN_Ethereum_JSON_RPC_Reference.md
PoS-specific public RPC is documented in:
XGRCHAIN_Staking_PoS_Endpoint_Reference.md
2. Current dispatcher namespaces
The v3.4.0 JSON-RPC dispatcher registers:
eth
net
web3
txpool
bridge
xgr
debug
Corresponding method naming follows:
<namespace>_<lowerCamelCaseMethod>
Examples:
eth_blockNumber
txpool_status
debug_traceTransaction
bridge_generateExitProof
xgr_getNextProcessId
xgr_getInterchainAttestation
The dispatcher converts exported Go endpoint method names by lowercasing the first character.
3. RPC surface classification
| Namespace | Primary purpose | Recommended exposure |
|---|---|---|
eth_* |
Ethereum-compatible application/chain RPC | Public with controls |
net_* |
Network metadata | Public with controls |
web3_* |
Client/hash helpers | Public with controls |
txpool_* |
Local transaction-pool inspection | Internal / controlled |
debug_* |
EVM tracing | Internal only |
bridge_* |
Legacy/compatibility bridge proof helpers | Internal / use-case-specific |
xgr_* |
XGR-specific methods | Method-specific |
| gRPC | Node/peer/consensus operator control | Internal only |
Namespace registration does not mean every method should be publicly exposed.
4. JSON-RPC dispatcher behavior
A JSON-RPC method name is split at the first underscore:
debug_traceTransaction
becomes:
service = debug
method = traceTransaction
Unknown services or methods return method-not-found errors.
The dispatcher supports:
- single JSON-RPC 2.0 requests,
- batch requests,
- HTTP RPC,
- WebSocket RPC,
- WebSocket subscriptions.
Relevant runtime limits:
| Setting | v3.4.0 default |
|---|---|
| Batch request limit | 20 |
| Block-range limit | 1000 |
| Concurrent debug requests | 32 |
| WebSocket read limit | 8192 bytes |
Runtime flags:
--json-rpc-batch-request-limit
--json-rpc-block-range-limit
--concurrent-requests-debug
--websocket-read-limit
A value of 0 for the batch-request limit disables that specific limit.
Debug / Tracing RPC
5. Debug RPC overview
v3.4.0 exposes:
debug_traceBlockByNumber
debug_traceBlockByHash
debug_traceBlock
debug_traceTransaction
debug_traceCall
Debug tracing can be expensive in:
- CPU,
- memory,
- state reads,
- disk I/O.
It should not be exposed as an unrestricted public service.
Recommended topology:
public RPC
→ no public debug
internal tracing node
→ debug enabled for trusted users
Avoid sustained tracing load on validator nodes.
6. debug_traceBlockByNumber
Traces all transactions in a selected canonical block.
Example:
{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceBlockByNumber",
"params": [
"latest",
{
"tracer": "callTracer",
"timeout": "5s"
}
]
}
The node:
- resolves the block selector,
- loads the full block,
- constructs the requested tracer,
- replays the block execution.
Genesis cannot be traced.
The implementation returns:
genesis is not traceable
for block 0.
7. debug_traceBlockByHash
Example:
{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceBlockByHash",
"params": [
"0x<blockHash>",
{
"tracer": "callTracer",
"timeout": "5s"
}
]
}
The block must exist locally.
Unknown hashes return an error.
8. debug_traceBlock
This endpoint accepts an RLP-encoded block.
Example:
{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceBlock",
"params": [
"0x<rlpEncodedBlock>",
{
"tracer": "callTracer",
"timeout": "5s"
}
]
}
Invalid:
- hexadecimal encoding,
- RLP,
- block structure,
returns an error.
This is primarily an internal diagnostic method.
9. debug_traceTransaction
Traces a mined transaction.
Example:
{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceTransaction",
"params": [
"0x<transactionHash>",
{
"tracer": "callTracer",
"timeout": "5s"
}
]
}
The node:
- resolves the transaction through the transaction lookup,
- locates its block,
- reconstructs the execution context,
- traces the transaction.
Pending transactions are not supported by this method.
Unknown transactions return an error.
10. debug_traceCall
Simulates and traces a call without changing canonical state.
Example:
{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceCall",
"params": [
{
"from": "0x<sender>",
"to": "0x<target>",
"value": "0x0",
"data": "0x"
},
"latest",
{
"tracer": "callTracer",
"timeout": "5s"
}
]
}
If gas is omitted:
gas = selected block gas limit
is used by the tracing path.
debug_traceCall does not broadcast a transaction.
11. Trace configuration
The trace configuration contains:
| Field | Type | Meaning |
|---|---|---|
tracer |
string | Select tracing implementation |
timeout |
string | Go duration such as 5s |
enableMemory |
bool | Capture EVM memory |
disableStack |
bool | Disable stack capture |
disableStorage |
bool | Disable storage capture |
enableReturnData |
bool | Capture return data |
disableStructLogs |
bool | Disable opcode-level struct logs |
A trace config object is required.
If it is omitted:
missing config object
is returned.
Default timeout:
5 seconds
12. Call tracer
Use:
{
"tracer": "callTracer",
"timeout": "5s"
}
The call tracer is useful for:
- contract call trees,
- nested calls,
- internal value movements,
- revert analysis,
- protocol interaction analysis.
It is usually preferable when opcode-level tracing is unnecessary.
13. Struct tracer
Any tracer value other than:
callTracer
selects the struct tracer.
Example:
{
"disableStack": false,
"disableStorage": true,
"enableMemory": false,
"enableReturnData": true,
"timeout": "5s"
}
Struct tracing is substantially more detailed and can be considerably more expensive.
14. Debug request throttling
Runtime flag:
--concurrent-requests-debug
Default:
32
The implementation uses a weighted semaphore.
At most the configured number of debug calls may execute concurrently.
A request waits for a slot for up to:
1 second
If a slot is not available:
request limit exceeded
is returned.
This is concurrency throttling, not a requests-per-second quota.
15. Trie pruning and historical tracing
Tracing historical execution requires historical EVM state.
When the Online State Trie Sweeper is enabled, sufficiently old state may have been reclaimed.
Therefore a pruned node may still have:
block
transaction
receipt
logs
while no longer having the complete state required to replay that old block.
Historical:
debug_traceBlockByNumber
debug_traceBlockByHash
debug_traceTransaction
debug_traceCall
can therefore fail for old state on a pruned node.
For unrestricted historical tracing:
use an archive-style node
or a node with a retention window covering the requested block.
This is not a consensus error.
It is a local state-retention limitation.
TxPool RPC
16. TxPool methods
The txpool namespace exposes:
txpool_content
txpool_inspect
txpool_status
Txpool contents are local node state.
Two healthy nodes can temporarily expose different txpool contents.
Consensus finalizes blocks, not mempool state.
17. txpool_status
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "txpool_status",
"params": []
}
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"pending": 12,
"queued": 3
}
}
Fields:
| Field | Meaning |
|---|---|
pending |
Promoted/executable transaction count |
queued |
Enqueued/non-currently-executable transaction count |
The fields are plain JSON numbers in this operator endpoint.
18. txpool_content
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "txpool_content",
"params": []
}
Response structure:
{
"pending": {
"0x<sender>": {
"0": {
"hash": "0x...",
"nonce": "0x0",
"from": "0x...",
"to": "0x..."
}
}
},
"queued": {}
}
Transactions are grouped by:
sender
↓
nonce
This endpoint can become large on busy nodes.
Keep it internal or tightly controlled.
19. txpool_inspect
Example structure:
{
"pending": {
"0x<sender>": {
"0": "0 wei + 21000 gas x 100000000000 wei"
}
},
"queued": {},
"currentCapacity": 10,
"maxCapacity": 4096
}
The summary format is:
<value> wei + <gas> gas x <effective gas price> wei
The effective gas price is calculated using the node's current base fee.
20. TxPool defaults
Current v3.4.0 defaults:
| Setting | Default |
|---|---|
--max-slots |
4096 |
--max-enqueued |
128 |
--price-limit |
0 |
Internal constants include:
| Constant | Value |
|---|---|
| Transaction slot size | 32 KB |
| Maximum encoded transaction size | 128 KB |
| TxPool gossip topic | txpool/0.1 |
These are node implementation values rather than chain-consensus parameters.
21. TxPool transaction sources
Transactions can originate from:
local RPC submission
or:
P2P gossip
Typical path:
eth_sendRawTransaction
↓
local validation
↓
txpool
↓
txpool/0.1 gossip
↓
peer txpool validation
Every receiving peer independently validates the transaction.
22. TxPool validation
Admission checks include:
- transaction encoding,
- maximum transaction size,
- transaction type,
- chain ID,
- sender recovery,
- signature validity,
- sender consistency,
- nonce,
- account balance,
- intrinsic gas,
- block gas limit,
- contract-initcode rules,
- access-list activation,
- dynamic-fee activation,
- fee-cap/tip-cap consistency,
- base fee,
- local price limit.
Internal:
StateTx / 0x7f
transactions are not ordinary user txpool transactions.
23. Chain ID
Typed transactions must use:
1643
for XGRChain mainnet.
Incorrect transaction-chain IDs are rejected.
This is distinct from RPC endpoint reachability.
A transaction sent to an XGR node is not valid merely because the node accepted the JSON-RPC request itself.
24. TxPool and base fee
The pool tracks the current chain base fee.
Effective pricing:
Legacy:
effectiveGasPrice = gasPrice
Dynamic fee:
effectiveGasPrice =
min(
maxFeePerGas,
maxPriorityFeePerGas + baseFee
)
The effective price is used for txpool admission and ordering behavior.
25. Transaction replacement
Same-sender / same-nonce replacement requires an economically better replacement.
An underpriced replacement is rejected.
Operationally:
same sender
+
same nonce
+
higher effective fee
is the normal replacement pattern.
Clients should not repeatedly resubmit the same nonce at the same or lower effective price.
Bridge Compatibility RPC
26. bridge_* namespace
v3.4.0 registers a bridge namespace.
Implemented methods:
bridge_generateExitProof
bridge_getStateSyncProof
These endpoints belong to the node's bridge/state-sync compatibility surface.
They must not be confused with the current native XGR Hyperlane-based interchain route.
27. bridge_generateExitProof
Go endpoint:
GenerateExitProof(exitID)
JSON-RPC name:
bridge_generateExitProof
Parameter:
exit event ID
The node delegates proof creation to the underlying bridge store.
Availability depends on the relevant bridge/state-sync implementation and local data.
28. bridge_getStateSyncProof
Go endpoint:
GetStateSyncProof(stateSyncID)
JSON-RPC name:
bridge_getStateSyncProof
Parameter:
state sync ID
This endpoint retrieves a state-sync proof from the bridge store.
29. bridge_* versus XGR Interchain
Do not equate:
bridge_*
with:
Multi-asset XGRChain/Base/Arbitrum Interchain
The current native XGR Interchain stack uses separate:
- router contracts,
- Hyperlane-compatible messaging,
- BLS attestations,
- per-message Direct-BLS authorizations,
- Interchain Security Modules,
- permissionless delivery by any gas-paying executor.
The bridge_* namespace remains a separate compatibility surface inherited from the node architecture.
XGR-specific RPC
30. xgr_* namespace
The node registers an xgr endpoint in both:
stub mode
and:
embedded-engine mode
Default public node behavior is stub mode unless an embedded engine build and configuration are explicitly used.
Environment mode selection is based on:
XGR_ENGINE_MODE
with backwards compatibility for:
XGR_ENGINE=on/off
A standard public build does not require an embedded private engine.
31. Public stub methods
The normal public build provides methods including:
xgr_getPublicSale
xgr_getCoreAddrs
xgr_getNextProcessId
as lightweight public/stub functionality.
It also registers engine-backed method names such as:
xgr_validateDataTransfer
xgr_getCirculatingSupply
xgr_estimateRuleGas
xgr_wakeUpProcess
xgr_control
xgr_listSessions
xgr_stepExecuted
xgr_sessionAlive
xgr_manageGrants
xgr_listGrants
xgr_getGrantFeePerYear
xgr_getXRC137Meta
xgr_getEncryptedLogInfo
xgr_encryptXRC137
In a normal non-embedded public build, those engine-dependent calls return:
xgr engine is disabled (stub mode)
Therefore:
Method registration does not imply active embedded-engine functionality.
32. xgr_getNextProcessId
The public stub exposes:
xgr_getNextProcessId
Request object:
{
"owner": "0x<address>"
}
Response shape:
{
"owner": "0x<normalized-address>",
"next": "0x1"
}
In public stub mode this is intentionally lightweight fallback behavior.
Applications that depend on actual engine process orchestration must use the corresponding active XGR service architecture rather than interpreting stub behavior as a full process engine.
33. xgr_getCoreAddrs
The public stub returns configured XGR core-address information including:
grants
publicSale
precompile
chainId
The values can depend on:
- environment configuration,
- build mode,
- active deployment.
Do not hard-code optional service addresses based solely on one node instance's result.
Direct-BLS Interchain RPC
Current methods and complete parameter/response/error semantics are specified in the Interchain JSON-RPC reference. The implementation is message-specific Direct-BLS; root/index/Merkle-hook fields and checkpoint-indexed lookup do not apply.
| Method | Ordered parameters | Result |
|---|---|---|
xgr_requestILNQuorum |
route, messageId, sourceBlockNumber | Bounded untrusted processing hint |
xgr_getILNQuorum |
route, messageId | Local progress, not delivery |
xgr_getILNQuorumAttestation |
route, messageId, setId | Explicit-set archive |
xgr_getInterchainAttestation |
route | Latest Direct-BLS archive |
xgr_getILNInterchainAttestation |
route, messageId | Message archive compatibility read |
xgr_getInterchainValidators |
destinationName | Ordered current configured destination set |
xgr_getILNGovernanceQuorum |
proposalId | Completed source-fee quorum |
xgr_getILNIndexerStatus |
none | Schema-2 worker/per-route health |
Use the complete canonical iln_<sourceDomain>_<destinationDomain>_<routeIdWithout0x> label. A chain name such as base is used for physical membership selection, not an arbitrary token route alias. Archived proof reads do not initiate a wallet transaction and do not imply current-set acceptance or recipient settlement.
For source dispatch, current-set recovery and wallet submission use the independent runbook. Validator control uses the CLI reference. The website and managed relayer are optional.
gRPC Operator Services
41. gRPC bind
The node exposes internal gRPC services.
Runtime control:
--grpc-address
Recommended validator/full-node bind:
127.0.0.1:9632
Do not expose operator gRPC unrestricted to the public internet.
42. System gRPC service
v3.4.0 defines:
service System
with:
GetStatus
PeersAdd
PeersList
PeersStatus
Subscribe
BlockByNumber
Export
These methods are intended for node tooling and operations.
43. GetStatus
Returns information including:
network
genesis
current block number
current block hash
P2P address
This is useful for local operator health checks.
44. Peer gRPC methods
Methods:
PeersAdd
PeersList
PeersStatus
support:
- adding a peer,
- listing known/connected peers,
- inspecting peer protocol/address state.
Peer management does not grant validator authority.
45. Subscribe
The System service can stream blockchain events.
Events contain added and removed headers.
This is useful for internal tooling that needs chain-head event streams without relying on public WebSocket RPC.
46. BlockByNumber
Returns serialized block data by block number.
This is an operator/internal interface rather than the normal application block API.
For ordinary application integration use:
eth_getBlockByNumber
instead.
47. Export
Streams blockchain export data for a requested range.
This should be treated as an operator function.
It can involve substantial I/O and should not be publicly exposed without a deliberate infrastructure design.
48. TxPool gRPC service
The txpool module also registers operator gRPC support.
This is intended for:
- CLI tooling,
- internal diagnostics,
- node operation.
Use the JSON txpool_* methods for simple inspection where appropriate.
Keep the gRPC operator endpoint private.
49. Consensus gRPC services
Consensus-specific services are registered by the active consensus implementation.
For example:
xgrchain ibft status
uses gRPC to inspect local validator identity/status.
These interfaces are:
operator/internal
rather than normal dApp APIs.
WebSocket Operator Considerations
50. WebSocket subscriptions
Supported subscription categories include:
newHeads
logs
newPendingTransactions
through:
eth_subscribe
Subscription state is connection-local.
After disconnect:
client must subscribe again
51. Pending-transaction subscription
newPendingTransactions
can become high-volume.
Public deployment should account for:
- connection count,
- outbound bandwidth,
- client backpressure,
- memory,
- RPC abuse.
A dedicated event/indexing service may be preferable for large-scale downstream consumers.
Security
52. Recommended exposure policy
| Surface | Exposure |
|---|---|
eth_* |
Public with rate limits |
net_* |
Public with rate limits |
web3_* |
Public with rate limits |
PoS read-only eth_* |
Public if intentionally supported |
txpool_* |
Internal / restricted |
debug_* |
Internal only |
bridge_* |
Internal/use-case-specific |
| XGR read-only public methods | Method-specific |
| XGR engine-control methods | Not public in normal architecture |
| Interchain attestation read RPC | Trusted relayer/operator or deliberately controlled |
| gRPC | Internal only |
| Metrics | Monitoring network |
53. Public RPC node
A public RPC node should normally:
- run
--seal=false, - contain no validator keys,
- bind node RPC locally,
- use a TLS reverse proxy,
- rate-limit requests,
- limit JSON batches,
- limit log ranges,
- restrict debug,
- restrict txpool,
- keep gRPC private,
- explicitly define historical-state retention.
54. Tracing node
A dedicated internal tracing node should normally:
- retain sufficient historical state,
- keep Trie Sweeper disabled if full archive tracing is required,
- expose
debug_*only internally, - use request concurrency limits,
- monitor CPU/memory/I/O,
- avoid serving unrestricted public traffic.
55. Validator node
A validator should prioritize:
consensus reliability
over:
diagnostic workload
Recommended:
- JSON-RPC local/private,
- gRPC local/private,
- no unrestricted public debug,
- no large public txpool inspection,
- no heavy historical tracing,
- validator keys isolated,
- interchain credentials isolated appropriately,
- disk and state-retention policy monitored.
Troubleshooting
56. RPC returns method not found
Check:
- namespace spelling,
- method spelling,
- node version,
- build mode,
- whether method belongs to a separate service,
- whether the endpoint is available in the current release.
Examples:
xgr_* engine method
may be registered but return an engine-disabled error in stub mode.
That is different from:
method not found
57. XGR method says engine disabled
Expected on a public stub build for engine-backed calls:
xgr engine is disabled (stub mode)
This does not mean standard XGRChain operation is broken.
It means the requested RPC belongs to the optional embedded-engine layer.
58. Interchain attestation not found
Possible causes:
- route not configured,
- validator worker not producing attestations,
- no completed current-set message quorum yet,
- wrong data directory,
- wrong route name,
- requested message/set archive does not exist.
Expected error:
interchain attestation not found
Check:
<data-dir>/interchain/attestations/<route>/
59. Debug trace fails for an old transaction
Check:
- block exists,
- transaction lookup exists,
- requested state is still retained,
- Trie Sweeper policy,
- node storage health.
A pruned node may be unable to reconstruct execution even though:
eth_getTransactionReceipt
still succeeds.
60. TxPool transaction not visible
Possible reasons:
- rejected before admission,
- already mined,
- replaced,
- dropped under pressure,
- submitted to another RPC backend,
- future nonce,
- insufficient effective fee.
Check:
txpool_status
txpool_content
eth_getTransactionByHash
eth_getTransactionCount
61. TxPool pressure
Check:
currentCapacity
maxCapacity
pending
queued
Possible mitigations:
- identify abusive accounts,
- inspect future-nonce queues,
- rate-limit RPC,
- tune pool size carefully,
- ensure adequate memory,
- investigate underpriced spam.
62. Debug request limit exceeded
Error:
request limit exceeded
means all configured debug concurrency slots remained unavailable for the throttling wait period.
Possible actions:
- reduce trace concurrency,
- use dedicated tracing infrastructure,
- increase the limit only after capacity analysis.
Do not simply raise it on validators.
63. RPC latency high
Investigate:
- debug load,
- large log ranges,
- large batches,
- txpool inspection,
- WebSocket subscriptions,
- historical-state reads,
- Trie Sweeper / LevelDB compaction,
- CPU,
- memory,
- disk I/O.
A slow RPC endpoint does not necessarily imply slow consensus.
64. Operator quick reference
| Task | Method/interface |
|---|---|
| Current block | eth_blockNumber |
| Peers | net_peerCount |
| Node version | web3_clientVersion |
| TxPool counts | txpool_status |
| TxPool detail | txpool_content |
| TxPool compact view | txpool_inspect |
| Trace transaction | debug_traceTransaction |
| Trace block | debug_traceBlockByNumber |
| Trace call | debug_traceCall |
| Legacy exit proof | bridge_generateExitProof |
| Legacy state-sync proof | bridge_getStateSyncProof |
| Next process ID stub | xgr_getNextProcessId |
| Latest interchain attestation | xgr_getInterchainAttestation |
| Explicit-set message attestation | xgr_getILNQuorumAttestation |
| Node operator status | gRPC System.GetStatus |
| Peer administration | gRPC PeersAdd/List/Status |
| Blockchain event stream | gRPC System.Subscribe |
| Local IBFT status | IBFT gRPC / xgrchain ibft status |
65. v3.4.0 operator-interface summary
| Area | Current behavior |
|---|---|
| Standard JSON-RPC | Active |
| TxPool RPC | Active |
| Debug RPC | Active |
| Bridge compatibility RPC | Registered |
| XGR namespace | Registered |
| Public engine mode | Stub by default |
xgr_getNextProcessId |
Available in public stub |
| Engine-dependent XGR RPC | Registered but disabled in stub mode |
| Native Interchain attestation RPC | Active |
| Latest attestation lookup | xgr_getInterchainAttestation |
| Explicit-set message lookup | xgr_getILNQuorumAttestation |
| Attestation RPC signing side effect | None |
| gRPC System service | Active |
| Debug concurrency default | 32 |
| TxPool max slots default | 4096 |
| TxPool per-account queue default | 128 |
| Historical tracing on pruned node | Retention-dependent |
66. Design principle
Operator interfaces expose powerful node-local functionality.
They should be separated according to purpose:
application RPC
│
├── eth
├── net
└── web3
operator diagnostics
│
├── txpool
├── debug
└── gRPC
XGR-specific integration
│
├── public/stub xgr methods
├── native interchain attestation RPC
└── optional embedded-engine methods
compatibility interfaces
│
└── bridge
A registered method is not automatically a public API.
A registered stub is not automatically an active engine.
An operator endpoint is not consensus authority.
A read-only interchain attestation request is not a signing request.
Keeping these boundaries explicit is essential for secure XGRChain infrastructure.