How to run and verify xOneC, the C++ XDC client

What is xOneC?

xOneC is an XDC execution client written in C++23, with its own EVM, XDPoS V1 and V2 consensus, a libmdbx store and its own devp2p. It ships as one binary, xonec. The xOneC overview explains the design. The CHANGELOG lists what v0.1.0 contains. Its README status line is out of date.

How do I get xonec?

Build it from source, or download the release binary. Build needs clang 19 or newer, clang-format, clang-tidy, CMake 3.28 or newer, Ninja and Python 3 (README). The presets are dev, asan-ubsan, tsan, fuzz and release (CMakePresets.json).

cmake --preset release && cmake --build --preset release
build/release/xonec --version

The v0.1.0 release has the assets xonec-v0.1.0-linux-amd64 and SHA256SUMS. Check the file before you run it.

sha256sum -c SHA256SUMS

The chain specification is inside the binary (test), so --network selects a network.

How do I follow net2040?

Start xonec with --network net2040 and a bootnode list. The node has no peer discovery: peers come from --bootnodes and are redialled every 5 s (CHANGELOG). The command below is from net2040-node.md.

xonec --network net2040 --datadir <datadir> --port <p2p-port> --bootnodes '<enode-url>,...' \
  --http --http.addr 127.0.0.1 --http.port <http-port> --http.api eth,net,web3,XDPoS \
  --ws --ws.addr 127.0.0.1 --ws.port <ws-port> --ws.api eth,net,web3 \
  --metrics --metrics.addr 127.0.0.1 --metrics.port <metrics-port>

To report to a board, add --ethstats name:secret@host:port. Pass the secret from the environment, not from a file. For a snap node on net2040, add --syncmode snap and --snap.gap-rpc to the same flags (net2040-snap.md). Stop the node with kill -TERM <pid>. It stops within 15 s.

How do I follow Apothem?

Use --network apothem --syncmode snap. The documented node syncs from geth-XDC and Nethermind peers (Besu did not stay connected). It needs no xOne peer (apothem-snap.md).

xonec --network apothem --datadir <datadir> --syncmode snap \
  --snap.gap-rpc http://127.0.0.1:<gap-rpc-port> --port <p2p-port> --bootnodes '<enode-url>,...' \
  --http --http.addr 127.0.0.1 --http.port <http-port> --http.api eth,net,web3,XDPoS \
  --metrics --metrics.addr 127.0.0.1 --metrics.port <metrics-port>

--snap.gap-rpc reads the 0x88 pool state of the gap blocks from an archive RPC that serves eth_getProof. The node checks each proof against the header, so it does not trust that RPC. The documented unit sets SSL_CERT_FILE, because without it the ethstats TLS handshake fails silently.

The documented run needed about 85 GB of disk at its peak. The final datadir was 42 GB. Do not use --mine unless a seated validator owns the key. Apothem allows --mine. Mainnet (chain 50) refuses it.

Which sync mode do I choose?

Use --syncmode full (the default, from config.cpp) to replay from genesis, --syncmode snap for an empty datadir, --minimal after a snapshot import, and --gcmode archive for history. fast is an alias of snap. An archive needs an empty datadir and --syncmode full. The sync modes post compares all four clients.

How do I verify a node?

Check five things, in this order.

1. Version stamp. xonec --version prints xOneC/v<semver>-<commit8>-<DDMMYYYY>/<os>-<arch>/clang<version>. The date is the commit date. A stamp with 00000000 is a failed build. The stamp has no -dirty marker (how stamps work; release.md). The v0.1.0 build prints xOneC/v0.1.0-331920a3-14112026/linux-x86_64/clang19.1.7.
2. Board. A node that runs a release must show the same stamp as clientVersion on its board entry. web3_clientVersion, the P2P hello and xone_build_info use the same value.
3. Head against a reference. Compare the hash of the head block with a reference node. For Apothem, the docs compare with https://erpc.apothem.network.
4. Health. /livez answers 200 while the process runs. /readyz answers 200 only with a recent head and no sync in progress.
5. Replay record. Gate B replays net2040 and Apothem from genesis on the node's own state. The gates page records 0 mismatches for net2040 1..21,600 and Apothem 1..432,000. The CHANGELOG records net2040 1..23,400. See the replay gate post.

curl -s -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]}' http://127.0.0.1:<http-port>
curl -s http://127.0.0.1:<metrics-port>/metrics | grep -E 'xone_build_info|xone_head_block_number|xone_peers'
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<metrics-port>/readyz

How does it perform?

performance.md gives the numbers. All come from a release build on a shared 20-core host with a load average of 31-48.

How do other clients compare for operators?

The rows describe different clients on different networks. They are not a speed comparison.

What does xOneC not do yet?

• Receipts over RPC. eth_getTransactionReceipt, eth_getBlockReceipts and eth_getLogs do not answer from stored receipts. Issue #94 is open.
• Peer discovery. Peers come from --bootnodes only.
• Precompiles. EIP-2537 (BLS12-381), the XDCx ring signature and bulletproof stay refused. The bn254 precompiles 0x06-0x08 are in v0.1.0.
• Release gate. The release was not re-gated on its own commit. The last full gate is 528b4d7.
• Mint and mainnet. Apothem minting and a mainnet follower need an owner decision. Mainnet minting is out of scope.

Frequently asked questions

Is xOneC public?

No. The repository is private, so the source, release assets and issue links need access.

Which compiler does xOneC need?

clang 19 or newer. The configure step refuses any other compiler (release.md).

How do I know the binary I run is the release?

Run sha256sum -c SHA256SUMS on the file. Then compare xonec --version with the board clientVersion.

Can I read transaction receipts from an xOneC node?

Not over JSON-RPC today. The node serves receipts to peers. Issue #94 tracks the RPC path.

Can I run xOneC on mainnet?

The docs cover net2040 and Apothem only. A mainnet follower needs an owner decision.