Para desenvolvedores / JSON-RPC

Referência JSON-RPC

Os 61 métodos registrados, agrupados pelo que você está tentando fazer. Um método ausente desta página não é alcançável: as duas tabelas de despacho do nó são o registro, e tudo o que fica fora delas responde -32601 antes que o nó seja consultado.

A forma de uma chamada

JSON-RPC 2.0 comum sobre HTTP POST. Sem autenticação, sem chave de API, sem cabeçalho além de um tipo de conteúdo. A rede de teste pública responde em https://rpc.picklechain.xyz; os exemplos a escrevem como $RPC_URL para que rodem sem alteração contra um nó seu:

bash
curl -s "$RPC_URL" \
  -X POST -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Os lotes funcionam até 32 chamadas. Todos os métodos também são chamáveis na porta WebSocket, com uma armadilha - os códigos de erro são reencapsulados lá - descrita na página das inscrições.

Duas coisas para ler antes de construir em cima disto

A página das diferenças reúne todos os lugares onde esta cadeia responde de outra forma que a Ethereum, e a página de retenção explica por que uma consulta que funcionava em teste devolverá null em produção. As duas são curtas e as duas poupam mais tempo do que tomam.

Identity

eth_chainId

Available
Params
none
Returns
"0x131be"

The chain id as a hex quantity. 78270 on the public testnet; the whitepaper's 78271 is the mainnet figure.

net_version

Available
Params
none
Returns
"78270"

The same id as a decimal string, per the older convention.

net_peerCount

Available
Params
none
Returns
"0x0"

Always zero. The node has no peer-to-peer layer.

web3_clientVersion

Available
Params
none
Returns
"pickle-sequencer/0.1.0"

The client identifier.

web3_sha3

Available
Params
[data]
Returns
keccak256 of the bytes

Hashes the hex-encoded bytes you pass.

rpc_modules

Available
Params
none
Returns
{ eth, net, web3, pickle }

The advertised namespaces, each at version 1.0. Note what is absent and unimplemented: debug, trace, txpool and admin.

Gas and fees

eth_gasPrice

Available
Params
none
Returns
"0x1"

One wei, which is also the minimum the chain accepts.

eth_feeHistory

Stub
Params
[blockCount, …]
Returns
constant arrays

Reads only the first parameter, clamped to 1..1024, and ignores newestBlock and rewardPercentiles entirely.

Differs from Ethereum. The values are constants, not measurements: baseFeePerGas is 0x1 repeated, gasUsedRatio is 0.0 repeated, and reward is null. Do not read it as fee data.

Account and chain state

eth_blockNumber

Available
Params
none
Returns
hex quantity

The retained tip. A fresh node answers 0x0 while eth_getBlockByNumber("latest") answers null, because no block has sealed yet.

eth_getBalance

Available
Params
[address, block?]
Returns
hex wei

The account's balance at the latest state.

Differs from Ethereum. The block parameter is accepted and silently ignored. There is no historical state - every state read answers from the published latest snapshot.

eth_getTransactionCount

Available
Params
[address, block?]
Returns
hex quantity

The account's nonce at the latest state.

Differs from Ethereum. The block parameter is accepted and silently ignored.

eth_getCode

Available
Params
[address, block?]
Returns
hex bytes

The deployed bytecode at the latest state.

Differs from Ethereum. The block parameter is accepted and silently ignored.

eth_getStorageAt

Available
Params
[address, slot, block?]
Returns
32-byte hex word

One storage slot at the latest state.

Differs from Ethereum. The block parameter is accepted and silently ignored.

eth_syncing

Available
Params
none
Returns
false, or a progress object

A leader always answers false. A replica answers false once it has caught up, otherwise { startingBlock, currentBlock, highestBlock } where highestBlock is the L1-derived target.

Differs from Ethereum. startingBlock is currentBlock + 1 rather than the block the sync actually began at.

Mini-blocks

pickle_miniBlockNumber

Available
Params
none
Returns
hex quantity

The mini-block tip, or 0x0 before the first one is sealed.

pickle_getMiniBlockByNumber

Available
Params
[quantity]
Returns
mini-block, or null

Accepts either a hex string or a plain JSON number. Answers null outside the retained window.

pickle_getMiniBlockByHash

Available
Params
[hash]
Returns
mini-block, or null

A reverse scan of the retained mini-blocks. Answers null when it is gone.

Blocks

eth_getBlockByNumber

Available
Params
[tag, fullTransactions?]
Returns
block, or null

The Cancun-shaped block, plus Pickle's own miniBlockFrom, miniBlockTo and miniBlocks fields.

Differs from Ethereum. With fullTransactions true, a transaction whose receipt has been evicted falls back to its bare hash string - so one block can return a mixed array of objects and strings.

eth_getBlockByHash

Available
Params
[hash, fullTransactions?]
Returns
block, or null

As above, addressed by hash.

Simulation and sending

eth_call

Available
Params
[callObject]
Returns
hex return data

Simulates against the latest state. Reads from, to, data or input, and value.

Differs from Ethereum. gas, gasPrice, nonce and the block parameter are all ignored - simulation always runs at the 30M block gas limit against latest state. A revert comes back as JSON-RPC error -32000 with the message "execution reverted: 0x<returndata>", not as a successful result carrying revert data, and error.data is absent, so a client cannot decode a custom error.

Errors. -32000 on revert, -32005 over 128 KiB of call data or when the heavy-read budget is exhausted

eth_estimateGas

Available
Params
[callObject]
Returns
hex quantity

Simulates on a copy-on-write clone, adds 12.5% headroom in the geth convention, floors at 21,000 and caps at the block gas limit.

Differs from Ethereum. Same ignored fields as eth_call. A revert surfaces as -32000.

eth_sendRawTransaction

Available
Params
[rawHex]
Returns
transaction hash

Decodes, recovers the signer, and submits to the execution coordinator. The call BLOCKS until the transaction has executed or failed - it does not merely enqueue, so a successful return already means executed.

Differs from Ethereum. Size is checked on the hex string before decoding, so anything over 128 KiB is rejected as a limit rather than a decode failure.

Errors. -32005 admission queue full; -32005 timed out after a 6 s wait; -32000 with the execution message on decode, signature, consensus or state failure; -32603 on a write-ahead-log or coordinator failure

Transactions and receipts

eth_getTransactionByHash

Available
Params
[hash]
Returns
transaction, or null

Carries three non-standard extras: raw (the full transaction, while the body is still indexed), miniBlockNumber and miniBlockHash.

Differs from Ethereum. type is always "0x0" and there is a single flat gasPrice, whatever the real envelope type - no maxFeePerGas, maxPriorityFeePerGas or accessList is reported. blockHash and blockNumber are null for a transaction that has executed but whose EVM block has not sealed yet.

eth_getTransactionReceipt

Available
Params
[hash]
Returns
receipt, or null

A receipt exists within the mini-block scheduling target of sending, while blockNumber and blockHash stay null until the EVM seal. Also carries miniBlockNumber and miniBlockHash.

Differs from Ethereum. cumulativeGasUsed is this transaction's own gasUsed, NOT a running block total. logsBloom is 512 zeros. type is always "0x0".

eth_getBlockReceipts

Available
Params
[tag]
Returns
receipt array, or null

Silently omits any transaction whose receipt has been evicted from the index, so the array can be shorter than the block's transaction list.

Logs and filters

eth_getLogs

Available
Params
[filterObject]
Returns
log array

address may be a string or an array; topics is positional, each entry null, a string or an array. An absent fromBlock defaults to the earliest RETAINED block, an absent toBlock to the tip.

Differs from Ethereum. logIndex is enumerated per transaction, not per block. The tags pending, safe and finalized all resolve to the tip, and earliest resolves to the earliest retained block rather than block 0.

Errors. -32602 when toBlock precedes fromBlock; -32005 for a span of 5,000 blocks or more; -32005 above 10,000 matches; -32005 when the heavy-read budget is exhausted

eth_newFilter

Available
Params
[filterObject]
Returns
filter id

Ids are sequential hex from a per-node counter. Takes the same shape as eth_getLogs.

Errors. -32005 at the filter limit (1024 by default)

eth_newBlockFilter

Available
Params
none
Returns
filter id

Buffers new block hashes for polling.

eth_newPendingTransactionFilter

Available
Params
none
Returns
filter id

Buffers transaction hashes.

Differs from Ethereum. "Pending" is a misnomer here. A hash is published only AFTER the transaction has executed and been indexed, because there is no public mempool to be pending in.

eth_getFilterChanges

Available
Params
[filterId]
Returns
array of new entries

Drains: everything since your last poll, and nothing twice.

Errors. -32602 "filter not found" for an unknown or expired id; -32602 "filter id" when it will not parse

eth_getFilterLogs

Available
Params
[filterId]
Returns
log array

Does NOT drain. For a log filter it re-scans the retained index from the filter's fromBlock to the tip, so a fresh filter answers with history rather than an empty array.

eth_uninstallFilter

Available
Params
[filterId]
Returns
boolean

True if the id existed, false for an unknown or malformed one.

Node introspection

pickle_stats

Available
Params
none
Returns
node counters

Role, heights, index sizes, admission depth, L1 batch and bridge counts, uptime, the explorer spool, and a latency block. Deliberately carries no file paths, upstream URLs or key material, and a test asserts that.

pickle_metrics

Available
Params
none
Returns
node counters

The same handler as pickle_stats, under a second name.

pickle_snapshot

Dev build
Params
none
Returns
{ ok, bytes }

Forces a state checkpoint. Needs the dev-admin cargo feature, which is not in the default set - without it the method answers -32601.

Refused by design

eth_sendTransaction

Refused
Params
any
Returns
-32601

Refused. The node holds no user keys; sign locally and use eth_sendRawTransaction.

eth_sign

Refused
Params
any
Returns
-32601

Refused, for the same reason.

personal_sign

Refused
Params
any
Returns
-32601

Refused, for the same reason.

eth_coinbase

Refused
Params
none
Returns
-32601

Refused, even though a sealed block does report a miner - that value is the fee treasury and is readable from the block.

Stubs and methods that cannot succeed

eth_createAccessList

Stub
Params
ignored
Returns
{ accessList: [], gasUsed: "0x0" }

A constant. It looks at neither the parameters nor the state.

Differs from Ethereum. There is no access-list computation. Anything relying on the result to pre-warm slots is relying on nothing.

eth_accounts

Available
Params
none
Returns
[]

Always empty. The node manages no keys.

eth_mining

Available
Params
none
Returns
false

Always false.

pickle_startStress

Cannot succeed
Params
any
Returns
-32601 or -32603

Registered but unusable in every build: -32601 without the dev-admin feature, and -32603 "in-process stress driver is not wired in this build" with it. Use the harnesses under scripts/ instead.