JSON-RPC API

Endpoint

HTTP, 127.0.0.1:4444 by default. Change it with --rpc-host and --rpc-port, or turn it off with --no-rpc. Single requests and batches are both accepted.

curl -s -X POST -H 'content-type: application/json' --data '[
  {"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]},
  {"jsonrpc":"2.0","id":2,"method":"net_peerCount","params":[]},
  {"jsonrpc":"2.0","id":3,"method":"web3_clientVersion","params":[]}
]' http://127.0.0.1:4444/

[{"id":1,"jsonrpc":"2.0","result":"0x8d1804"},
 {"id":2,"jsonrpc":"2.0","result":"0x10"},
 {"id":3,"jsonrpc":"2.0","result":"Rustock/0.1.0"}]

Block parameters

Methods taking a block accept a hex block number, or the tags latest, earliest and pending. Historical state is served from the local Unitrie, so a query at an old height is answered from disk rather than refused. A node left alone is an archive node in practice, because no collector runs unless it is enabled.

Chain and node info

State queries

Served from the local Unitrie at any historical block.

Execution

Calls against the Bridge precompile go through rskj's local-call gate, so the local-only getters behave as they do on rskj — including the ones that are only reachable this way. All 70 methods in rskj's dispatch table now have an arm; none of them fall through to an empty-bytes catch-all that would decode as a plausible-looking zero. What changed →

# read a contract, at a historical block
curl -s -X POST -H 'content-type: application/json' --data '{
  "jsonrpc":"2.0","id":1,"method":"eth_call","params":[
    {"to":"0x0000000000000000000000000000000001000006","data":"0x3f9b2a45"},
    "0x8d1804"]}' http://127.0.0.1:4444/

Transactions and receipts

Logs and filters

Transaction pool

Admission validates nonce, balance, intrinsic gas and chain id against live state, and pending nonces are tracked per sender so a sequence submitted at once is not rejected on the second transaction.

Broadcast is additionally rate-limited per account: a port of rskj's TxQuotaChecker, where each account accumulates virtual gas and pays a cost computed from six factors when it broadcasts or replaces a transaction. It is what stops one account flooding the shared mempool by broadcast-then-replace.

The rsk namespace

Six further rsk_ methods act on the node rather than answering questions about the chain, and are gated behind --rpc-admin.

Tracing — debug_ and trace_

One inspector, rendered two ways, so the two namespaces cannot disagree about the same transaction.

Tracing a historical transaction re-executes its whole block from the parent with the tracer switched on at one index, because the pre-state exists nowhere — only per-block roots are stored. The consensus block executor is shared for this rather than copied.

WebSocket subscriptions

eth_subscribe over a WebSocket on its own port, fed by one typed chain-event channel the sync service publishes to as it follows the tip.

Peer scoring — sco_

A port of rskj's co.rsk.scoring: fifteen event counters per peer, kept by node id and by address, punishment whose length grows on repeat offences, and address/CIDR bans that persist across restarts. The sco_* methods inspect and override all of it — sco_peerList, sco_reputationSummary, sco_banAddress, sco_unbanAddress and the rest, matching rskj's names and shapes.

Merged mining — mnr_

The interface mining software speaks. Rustock builds block templates, selects uncles, handles the Bitcoin coinbase and RSKIP110 fork-detection data, then validates and imports submitted solutions.

Administrative — --rpc-admin

These act on the node rather than answering questions about the chain, so they are refused outright unless the operator passes --rpc-admin. The server binds to loopback by default, but "not reachable" is a deployment detail rather than an access-control decision — a method that deletes a database should require the operator to have asked for it.

Development chain — --dev-rpc

Seven methods for driving a local chain, off unless --dev-rpc is passed. They let an RPC caller rewrite chain state, which is exactly what a test harness wants and exactly what a node on a real network must not offer.

Gas estimation in one pass

eth_estimateGas answers in one execution. The obvious implementation is a binary search — execute at the cap, halve the interval until it closes — which costs about twenty-four executions for an answer a single pass already contains.

One execution knows it if it records three things while it runs, which is what rskj has done since EthModule.internalEstimateGas:

estimate = movedRemainingGasToChild ? gasUsed + deductedRefund
                                    : maxGasUsed
if (callWithValuePerformed) estimate += STIPEND_CALL

The load-bearing idea is that RSK's gas counter is not monotonic. At a CALL it adds the callee's whole allowance and subtracts whatever comes back. The peak of that counter — not its final value — is what the caller had to hold, and therefore what the limit has to be. A contract calling out with a fixed generous stipend finishes having consumed very little while having needed a great deal, and that gap is what binary search rediscovers one halving at a time.

The two estimators do not always agree, and neither is wrong. Binary search finds the smallest limit at which the transaction does not revert; the single pass reports the limit at which it behaves as it did at the cap. They part over a CALL with a large fixed allowance, because RSK has no EIP-150 retention — calleeGas = min(remaining, requested), so a call asking for more than is left does not fail, the callee simply gets less. The transaction still succeeds at the lower limit, but the inner call then runs on different gas than it was estimated at.

The binary search is kept behind --gas-estimator-binary-search, where it also serves as the test oracle. Where the single-pass estimate is loose, and why, is written down rather than left as a comment.

eth_getProof, over a unitrie

EIP-1186 defines accountProof and storageProof[].proof as arrays of RLP-encoded Merkle-Patricia nodes. RSK has no Merkle-Patricia trie. It has a unitrie: one binary radix trie with path compression, holding accounts, code and storage together, with its own node encoding. So there is no way to satisfy the letter of the standard, and the question is what to answer instead.

Rustock answers with EIP-1186's envelope — balance, nonce, codeHash, storageHash and a storageProof entry per slot are all trie-agnostic, and are what a caller actually came for — while the proof arrays carry unitrie node messages, hex-encoded, deepest first.

The encoding is not invented. rskj already exposes proofs in exactly this shape — RskModuleImpl.getTransactionReceiptNodesByHash returns the hex of each node's toMessage() in findNodes order — so this reuses RSK's established convention rather than adding a second one.

storageHash is the field needing judgement. On Ethereum it is the root of a separate storage trie; RSK has none, since storage lives beneath account_key || 0x00 in the same trie. The hash of the node at that path is the true analogue — it commits to that account's storage and nothing else — and is what this returns. No storage, no node, and the answer is zero.

Absence is an empty array, never a truncated path. A proof of absence over a radix trie needs the divergence point and its siblings, which is a different structure; emitting a partial inclusion path would look like evidence without being any.

rskj does not implement eth_getProof at all. Offering it is a deliberate divergence: the question is worth answering, and there is no standard shape RSK could satisfy instead.

Known gaps

Methods an Ethereum-shaped tool will reach for and not find. These are not yet built rather than declined — the distinction the table below does not make.

Unsupported

These return an error rather than a wrong answer, and are absent by design rather than unbuilt — see known gaps for the other kind: