xOneRS serves 15 methods in the XDPoS RPC namespace. They read consensus state: snapshots, signers, masternodes, epochs, missed rounds and V2 block data. A test fixes the set: if a method is added or removed, the_xdpos_method_set_is_exactly_the_issue_list fails (crates/xone-rpc/tests/rpc.rs). The reference for every answer is geth-XDC at a pinned commit (spec/rpc/xdpos-namespace.md).

For the whole RPC surface see the xOne RPC surface. For the consensus terms see epoch switches and QC, TC and timeouts.

Which XDPoS methods does xOne serve?

These 15, from xdpos::METHODS in crates/xone-rpc/src/xdpos.rs. number? means an optional block number; no value or latest is the head.

REFERENCE TABLEScroll to explore all columns →
Method Parameters Answer
XDPoS_getSnapshot number? The V1 snapshot: number, hash, signers, recents, votes (null when empty), tally
XDPoS_getSnapshotAtHash hash The same, by hash
XDPoS_getSigners number? The snapshot's signers, ascending by address
XDPoS_getSignersAtHash hash The same, by hash
XDPoS_getCandidates number? The snapshot's signers, as getSigners (the geth-XDC body is the same)
XDPoS_getMasternodes number? The masternode list of the header's epoch
XDPoS_getMasternodesByNumber number? An object with Epoch, Number, Round, MasternodesLen, Masternodes, PenaltyLen, Penalty, the tier lists when not empty, and Error
XDPoS_getV2BlockByNumber number? hash, number, round, masternodes, encodedQC (the QC, RLP in base64)
XDPoS_getV2BlockByHash hash The same shape, by hash
XDPoS_getBlockInfoByEpochNum epoch (a JSON number) hash, round, firstBlock, lastBlock of the epoch
XDPoS_getEpochNumbersBetween begin, end The epoch switch block numbers in the range
XDPoS_getMissedRoundsInEpochByBlockNum number? EpochRound, EpochBlockNumber, MissedRounds (null when none)
XDPoS_getLatestPoolStatus none {votePool: 0, timeoutPool: 0}
XDPoS_networkInformation none networkId, xdcValidators, epoch, v2SwitchBlock
XDPoS_getRewardByAccount account, begin, end An error today (see below)

Are the method names case-sensitive?

Yes. The namespace is XDPoS, written exactly so, and the method name starts with a lower-case letter, as geth-XDC registers it. xdpos_getSigners, XDPOS_getSigners, XDPoS_GetSigners, xDPoS_getSigners and XDPoS_getsigners all answer error -32601 with the method <name> does not exist/is not available. The test xdpos_names_are_pascal_case_and_case_sensitive checks each of these five names.

curl -s -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"XDPoS_networkInformation","params":[]}' \
  http://127.0.0.1:8545

What do the edge cases return?

From the spec, which follows the geth-XDC source line by line:

  • Unknown block. getSnapshot answers -32000 unknown block. getV2BlockByNumber answers an object with hash 0x0, number null, round 0 and error: "block not found".
  • V1 blocks. At or below the V2 switch block, getV2BlockByNumber gives round 0, masternodes null and encodedQC "". getEpochNumbersBetween answers -32000 not supported in the v1 consensus. getMasternodesByNumber gives empty lists and Round 0.
  • Range limit. getEpochNumbersBetween refuses a range of more than 1,000 epochs with -32000. It returns [] when begin equals end.
  • Mainnet shape. On chain id 50, getMasternodesByNumber returns the older shape: no Epoch, and Standbynodes always present.
  • Pool status. getLatestPoolStatus always answers zeros, because the pinned geth-XDC source does not read the pools either.
  • Reward history. getRewardByAccount reads reward files that geth-XDC writes with --store-reward. xOne does not write these files, so the method answers -32000 reward folder not configured; start node with --store-reward to enable reward history, the same error as an archive node without the folder.
  • Pruned history. A block below the retained window answers -32000 unsupported history: ... with class, block, firstRetained and pivot in data.

How does the set compare with geth-XDC and xOneGo?

REFERENCE TABLEScroll to explore all columns →
geth-XDC (pinned) xOneGo xOneRS
XDPoS_ read methods the reference set 13 15 (the 13 plus getV2BlockByNumber and getV2BlockByHash)
XDPoSAdmin (propose, discard) in the source not served not served
Names case-exact yes not checked here yes, by test

xOne does not serve XDPoSAdmin, because Propose writes validator state. The other xOne clients serve a smaller set; see the RPC surface post.

Do xOne's answers match geth-XDC?

They are compared row by row with recorded archive answers by the parity sweep (conformance/rpc-parity). Two limits:

  • On the archives, geth-XDC's getSigners, getSnapshot and getCandidates answer an error (invalid signature recovery id or extra-data 65 byte suffix signature missing) on every V2 block and on many V1 blocks (33 of 50 net2040 rows). The sweep reports a different xOne answer as differ, not as a pass.
  • On net2040 the sweep has recorded raw blocks only, so XDPoS snapshot reads are not-backed there. See RPC parity in numbers and run the sweep against your node.

Frequently asked questions

Why does xdpos_getSigners return "method does not exist"?

The namespace is case-exact. Use XDPoS_getSigners.

Can I get validator rewards from xOne over RPC?

Not yet. XDPoS_getRewardByAccount answers the "reward folder not configured" error, because xOne does not write reward files.

Which method gives the current epoch length and V2 switch block?

XDPoS_networkInformation. It returns epoch and v2SwitchBlock, with networkId and xdcValidators.

Can I propose or discard a validator through xOne RPC?

No. The XDPoSAdmin namespace is not served.

Sources