XerisCoinXerisCoin
Protocol specificationProtocol specification

1Introduction

XerisCoin is a Layer 1 in Rust (xrs-node 0.1.1). One 4 s slot runs three mechanisms (§2): a Proof-of-History hash chain orders events locally and is not a consensus input; a stake-weighted draw over validators holding at least 1,000 XRS selects the leader; Scrypt Proof-of-Work (N = 4,096, r = 4, p = 1; 2 MiB per hash) produces the block.

The runtime executes 62 native instruction variants (0–61) under one fee and replay model (§3, Appendix B). Contracts are 23 typed templates, no bytecode; 15 are user-deployable, 8 protocol-managed singletons (§5, Appendix C). SubDelegate, ZkPrivateTransfer, ZkIdentityProof and PqSignedTransfer are refused at the dispatcher (§12.2).

From slot 1 every block carries a hybrid Ed25519 + ML-DSA-65 (Dilithium3, FIPS 204) proposer signature; both components must verify (§9.1). Transactions are Ed25519 only. Finality is 64 blocks, ≈ 4.3 min (§2.4). Mainnet will launch as a federated beta: three roster keys, public self-staking closed (§12).

2Consensus

Each 4 s slot runs one pipeline: a Proof-of-History recorder ticks once and supplies the local slot number, a hash and a wall-clock timestamp; a stake-weighted draw over validators holding at least 1,000 XRS names the leader; the producer searches for a Scrypt Proof-of-Work solution for at most 3.9 s, under the leader target or, as a non-leader, under a target four times harder. The block carries a hybrid Ed25519 + ML-DSA-65 proposer signature and is broadcast. Validators recompute the leader, the target and the work; they do not recompute the PoH chain. Fork choice is by summed work and a reorganisation replaces at most 64 blocks.

2.1Proof-of-History

The recorder is a SHA-256 chain seeded with SHA-256("XERIS_V1_MAINNET_GENESIS_SEED_2026"). The producer loop ticks it once per 4 s iteration, not continuously, and the tick counter is the local slot clock. Each tick mixes the elapsed nanoseconds of the monotonic Instant clock into the preimage, so two nodes never produce the same hash for the same slot (XWC-27).

Validators do not replay the chain. Consensus checks the PoH fields of a block as listed below and nothing else. The poh_hash value is bound into the PoW preimage and the proposer signature; it is proposer-chosen bytes committed by work and signature, never recomputed by a peer.

2.2Proof-of-Work

Every block is mined and verified with Scrypt N = 4,096, r = 4, p = 1, empty salt, 32-byte output (2 MiB per hash). Two earlier parameter sets remain in scrypt_params_for_slot and cannot fire: SCRYPT_V2_SLOT and SCRYPT_UPGRADE_SLOT are both 0.

The preimage is domain-tagged and length-prefixed from POW_PREIMAGE_V2_SLOT = 1, so one solution binds one parent, one timestamp and one transaction set (XWC-05). The target is 32 bytes of which only target[0] is non-zero; a larger byte is an easier target. The nonce starts at a random u64 and increments.

Mining stops at 3.9 s. The producer forfeits the slot and the template's transactions return to the mempool. The difficulty target is recomputed before every block from poh_timestamp values and the running difficulty committed after the parent, in integer arithmetic. Startup replay rebuilds it from 0x1f block by block; reorg simulation seeds it from the ancestor's recorded verdict.

Slot continuity is exact. On every admission path (live, peer, replay, reorg) block.slot == parent.slot + 1, or the block is rejected (XWC-10). A proposer cannot choose among candidate child slots or advance slot-gated state such as unbonding.

A block whose proposer is not the expected leader must meet the non-leader target: the base target shifted right by two bits (base >> 2, 4× harder). Validators enforce this from LEADER_ENFORCEMENT_ACTIVATION_SLOT = 1: a block passes under the leader target if its proposer is the leader, under the non-leader target otherwise, and fails under neither (XWC-04). The producer mines as a non-leader only after NON_LEADER_GRACE_SLOTS = 2, that is 8,000 ms of chain silence; this is a liveness convention of the producer, not a consensus rule.

2.3Leader election

The leader of a slot is a deterministic function of the stake table after the parent block, the parent hash and the slot number. One function computes it on the producer, at live and peer admission, in startup replay, in reorg simulation and in the recovery scorer.

Eligibility is stake of at least 1,000 XRS and nothing else; there is no activity window. The seed uses the parent's PoW hash, not a PoH hash, so predicting a leader requires mining the parent (C-1). Admission re-checks the proposer's stake against the same threshold from slot 1 on every path. On mainnet only the three roster keys can hold stake, so the draw selects among them (§12.1).

2.4Finality and fork choice

There is no vote-based finality. Fork choice is by summed work, and a reorganisation replaces at most MAX_REORG_DEPTH = 64 blocks (≈ 4.3 min at 4 s). A block 64 or more below the tip is final on the public path; the producer roster of §12.1 is an operational gate, not a consensus vote.

The header gate checks dimensions, PoH fields, Merkle root and hybrid signature and recomputes the PoW before a block enters the buffer. ForkBuffer holds at most 256 blocks and 260 MiB. A recovery thread assembles branches of at most 65 blocks from a canonical ancestor within 64 blocks and replays the candidate and the reference chain into isolated scratch ledgers through the production block validator.

Work is scored from the target each block was validated against, leader or non-leader, not from realised hash values or height. A candidate is adopted only if it is strictly heavier. Publication renames the candidate ledger over the canonical file, fsyncs the directory, swaps the in-memory ledger, journals the displaced transactions and resets the PoH recorder to the new tip.

3Blocks, transactions and execution

A block is a signed header over a Merkle-committed list of at most 40,000 transactions. A transaction is a Solana-format message, Ed25519-signed, carrying account keys, a recent blockhash and at most 16 instructions. One admission gate runs at RPC and P2P ingress; block validation runs the same structural caps again. Every transaction pays one flat fee before its first instruction (§3.4) and its instructions commit one at a time (§3.5).

3.1Block structure

A block travels as bincode inside a 4-byte big-endian length frame of at most 5 MiB and is stored as one JSON line per block in ledger.dat, fsynced before the block is committed. The signed header is about 5.6 KiB; the producer reserves that footprint before filling the transaction list. hybrid_proposer_sig and the inline proposer_dilithium3_pk are mandatory from slot 1 (§9.1; registry binding from slot 2, §8.2). Slot 0 is not mined: the PoH recorder ticks from 0 to 1 before the first proposal, and a slot-0 block must carry zero transactions.

3.2Limits

The per-transaction caps are one set of constants shared by ingress and block validation, so a producer cannot place in a block what the mempool would refuse (XWC-15).

3.3Transaction admission

Every ingress path, POST /submit and both P2P transaction handlers, runs one gate in a fixed order. sanitize() must pass; num_required_signatures is at least 1; signatures.len() equals it; the instruction list is non-empty and within the caps of Table 5; every instruction decodes as a XerisInstruction or a SystemInstruction. Then tx.verify() checks the Ed25519 signatures. Then a stateless semantics gate rejects the legacy SystemInstruction::Transfer, a NativeTransfer whose to is not a canonical public key or names a reserved __* key, a zero amount on NativeTransfer, TokenMint or RWATransfer, an AgentExecute or ConditionalOrder that nests another, and SubDelegate (XWC-82).

State checks follow. The first signature must be absent from the processed set and from the mempool. recent_blockhash must be one of the last 150 block hashes, evaluated at the slot of the next block. A payer whose balance is below BASE_TX_FEE is routed to the underfunded population cap rather than the normal queue, unless the transaction is a fee-exempt attestation (§4.4). The mainnet Stake gate is in §12.1.

Transactions in an in-flight proposal are reserved for the mine-to-commit window and count as present for deduplication (XWC-17). Ordering and eviction are in §10.4; write-RPC limits in §10.5.

3.4Fees and replay

The fee is BASE_TX_FEE = 1,000,000 lamports (0.001 XRS) per transaction, independent of instruction count or size. It is debited from account_keys[0] before instruction 0 and credited to the block proposer. Fees are not burned; XRS leaves supply only through slashing. A transaction whose payer cannot cover the fee is skipped without execution, the block stays valid, and its signature is still recorded as processed. The only exemption is a transaction whose sole instruction is a ValidatorAttestation that passes every rule of Table 10 (XWC-60).

The blockhash is the block's Scrypt hash, served by getLatestBlockhash (Table 21). The processed-signature set is written into every snapshot (§10.3).

3.5Execution semantics

Instructions execute in message order. Each produces one outcome (signature, index, ok) that defaults to failed and is set to ok only when the handler commits. A failed instruction changes no state and the next instruction still runs: commit is per instruction, with no transaction-level rollback. Inside a handler every check precedes the first mutation (contract calls: §5.1). The per-block work budgets of Table 5 can reject an otherwise valid instruction, which then fails like any other.

A transaction skipped at the fee gate is not recorded and is never reported as history. Outcomes and receipts live in a SQLite store derived from execution; consensus never reads them (§10.5). An integrator that needs atomicity sends one instruction per transaction.

4Economics

XRS has 9 decimals; 1 XRS is 1,000,000,000 lamports. Genesis credits the treasury 8evPjjozSHNcoGRcv7zzxwan9sf3ubJ8q9CFzms6AK97 with 200,000,000 XRS, of which 1,000 XRS is staked and 199,999,000 XRS is liquid. Every other XRS is minted as a reward against one budget, MAX_EMISSION_SUPPLY = 500,000,000 XRS, shared by mining, staking and attestation. The nominal total is 700,000,000 XRS.

4.1Emission

Every accepted block credits its proposer with a mining reward. The reward is BASE_BLOCK_REWARD = 10 XRS right-shifted once per 25,000,000 slots (HALVING_INTERVAL), the shift capped at 63. One epoch is 25,000,000 slots × 4 s ≈ 3.17 years. The reward is then clamped to the emission remaining after all earlier rewards and the attestation rewards already granted in the same block.

Within one block the budget is consumed in a fixed order: attestation rewards as transactions execute, then the mining reward, then staking rewards. Each step is capped by what the earlier steps left. total_mined is the sum of all three and is the only counter the cap reads.

4.2Staking rewards

At every slot that is a multiple of 900 (STAKING_REWARD_INTERVAL, one hour) each account with at least 100 XRS staked receives 7 % per year pro rata on its own stake. BLOCKS_PER_YEAR is 7,884,000, so there are exactly 8,760 payouts per year. The reward is credited to the liquid balance; it does not compound. Stakers are paid in Pubkey byte order; when the emission remainder cannot cover all of them, earlier keys are paid in full and the last payable key receives the truncated remainder (XWC-52).

4.3Stake and unbonding

Stake (9) and Unstake (10) require the signer to equal pubkey. Stake moves lamports from the liquid balance to the stake table and counts at the next leader draw and payout. Unstake moves them to an unbonding entry that matures 151,200 slots later (UNBONDING_PERIOD_SLOTS, 7 days). After each applied block the node releases every matured entry to the liquid balance; no instruction claims it. Unbonding stake earns nothing, elects nothing and remains slashable. A rejected Stake or Unstake is a failed instruction (§3.5); its fee is still charged. On mainnet a Stake naming a key outside the three-producer roster is rejected at every ingress and validation path (§12.1).

4.4Light-client attestation

ValidatorAttestation (12) pays 0.01 XRS (ATTESTATION_REWARD) to a staked validator that names a recent block by slot and full 32-byte hash. The reward is credited to the liquid balance and counted against the emission budget. A transaction whose only instruction is a valid attestation pays no fee (XWC-60).

4.5Slashing

SlashReport (38) is the only slashing path. The offence is a double-sign: two distinct block headers at one slot by one proposer. Any account other than the offender may report. The evidence is a JSON array of exactly two Block values with empty transaction lists; the handler rebuilds each canonical signing payload and verifies the proposer signature under the regime active at that slot, the hybrid Ed25519 + ML-DSA-65 check using the PQ key bound to the owner at that slot (XWC-53). Evidence older than 302,400 slots (PQ_KEY_HISTORY_RETENTION_SLOTS, 14 days) is rejected; the evidence limit is in Table 5.

The dedup key is recorded in the protocol contract xeris_slashing_registry, so one offence slashes once regardless of how the evidence is encoded or labelled (XWC-30). The slashed share of an unbonding entry is reduced in place and is never released. A report whose applied slash is zero fails and records no key, so the offence stays reportable (XWC-13). This path has no minimum slash amount.

5The contract engine

A contract is a typed state machine. The engine defines 23 ContractType variants, each with a fixed state struct and a fixed method set; there is no bytecode, no virtual machine and no user-supplied code. ContractDeploy (5) creates an instance from a type string and a JSON parameter object; ContractCall (4) invokes one method by name. Fifteen types are user-deployable. Eight are protocol-managed singletons under reserved xeris_* ids, created by the protocol and driven only by their dedicated instructions: DeviceRegistry, ZkVerifierRegistry, PqKeyRegistry, ConditionalOrderBook, DisputeRegistry, DealRegistry, TaskBoard, StateChannelRegistry. Appendix C lists every type with its aliases.

5.1Deploy and call rules

Every deployment and every call passes the rules below before type-specific logic runs. The caller a contract sees is the transaction fee payer. A transaction pays the flat 0.001 XRS fee and nothing more; there is no deploy or call fee. Mutating calls execute against a clone of the contract and the clone replaces the stored contract only when the method returns Ok.

5.2TimeLock, Escrow, Vesting, MultiSig

Four custody types hold a token balance and release it under one rule each. They move token_balances only, so native XRS enters them as wrapped xrs_native (WrapXrs, 13). TimeLock, Escrow and Vesting refuse an RWA token at deploy; a MultiSig transfer of one passes the compliance gate of §7.2. Timestamps are block poh_timestamp values in milliseconds; TimeLock does not range-check unlock_timestamp, and a value in the past is releasable at once.

5.3Swap

A Swap is a constant-product pool of two distinct non-RWA tokens. Deploy debits amount_a and amount_b from the deployer and mints isqrt(amount_a × amount_b) shares, which must exceed 1,000; 1,000 shares go to a dead address and are never redeemable. fee_bps defaults to 30 and may be set from 0 to 10,000 at deploy. The fee stays in the reserves and accrues to liquidity providers; the protocol takes no cut of swaps. add_liquidity and remove_liquidity take signed minimums and fail below them. Shares are entries in the pool state, not a token.

5.4Launchpad

A Launchpad creates the token lp_<id> and sells part of its supply on a constant-product curve with virtual reserves. The token is LaunchpadManaged: its supply is minted only by curve buys and TokenMint is refused. Nothing is debited at deploy. liquidity_bps of the supply (default 2,000; clamped to 500–4,000) is reserved for the graduation pool and the curve sells the remainder; the virtual reserves are chosen so the curve price at sellout equals the opening price of the pool. Every buy and sell pays 1 % to the creator, accrued until claim_rewards, and 0.77 % to the treasury address, credited in the same call. Buyers pay in wrapped xrs_native. A launchpad contract id is at most 116 characters so that the pool id fits in 128.

finalize_curve is permissionless once xrs_collected ≥ T. The ledger credits the pseudo-account __launchpad_pool__ with the collected XRS and the tranche L and deploys the Swap above; the shares belong to that non-signable account, so the liquidity cannot be withdrawn. If the pool id already exists or seeding fails, the finalisation reverts and the launchpad stays open. Launchpad methods execute only through a direct ContractCall: AgentExecute and conditional-order inner calls to a launchpad are refused. vesting_enabled: true is rejected at deploy.

5.5Standing orders

ConditionalOrder (23) places a standing order in the singleton xeris_conditional_orders. The order escrows locked_amount from the signer's native balance into __escrow_order_<id>; the minimum is the refundable 0.01 XRS storage bond, and an inner NativeTransfer must be covered by it. An order lives at most 650,000 slots (≈ 30 days); an owner holds at most 100 live orders, the book at most 10,000; the inner instruction is at most 2,048 bytes of bincode. The protocol evaluates every live order once per block after all transactions and executes triggered orders in order_id order; there are no keepers. A failed or expired order is cancelled and its escrow refunded. CancelConditionalOrder (24) refunds the owner.

A pool price is observed once per block, after transactions, for the at most 64 pools referenced by live price orders: spot = reserve_b × 10^9 / reserve_a, skipped and the window cleared when either reserve is below 1,000. The trigger price is the median of the last 61 observations and exists only after 20. Moving the median requires holding an off-market price for 31 consecutive blocks against arbitrage.

6The Ari agent layer

Ari (Autonomous Runtime Infrastructure) is a set of registries reached by dedicated instructions: self-sovereign identities with per-category reputation, bounded delegation from an owner key to agent keys, capability listings, escrowed tasks, stake-weighted dispute panels, two-party deals, payment channels, staked oracle feeds, attested devices, model records and liveness heartbeats. Each registry is a contract created on first use under the id in Table 14; Appendix C marks which types are protocol-managed. SubDelegate (22) is refused at ingress and skipped at the dispatcher; delegation is one tier deep and there is no agent hierarchy (XWC-82).

6.1Agent delegation

RegisterAgent (15) is signed by the owner and writes an AgentEntry into the registry of that owner. A registry holds at most 50 agents. UpdateAgent (16) changes any limit and sets or clears revoked; revocation is the kill switch and the owner may reverse it.

AgentExecute (17) is signed by the agent and carries a bincode-encoded inner instruction that executes as the owner. The inner instruction must be one of NativeTransfer, TokenTransfer, ContractCall, WrapXrs, UnwrapXrs, Stake, Unstake, TokenMint, TokenBurn; any other variant is refused. The spend of a transfer, wrap, stake, mint or burn is its amount. The spend of a ContractCall is derived from the method, and a method whose spend cannot be bounded is refused.

Validation runs in this order: the agent is registered, not revoked and not expired; the spend is at most max_per_tx; the window resets after 21,600 slots and the spend is at most max_daily minus daily_spent; the contract allowlist applies to a ContractCall target; the operation allowlist applies to the operation name. The budget is recorded only after the inner instruction succeeds. A delegated call to an agent registry, a sealed protocol method, a Launchpad contract or an RWA contract is refused. A nested AgentExecute or ConditionalOrder is refused at ingress.

6.2Identity and reputation

CreateIdentity (18) creates one contract per public key; the signer must be the identity. identity_type is one of agent, device, service, human; display_name is at most 128 B and metadata_json at most 4,096 B. A non-empty parent_identity must co-sign the transaction, and the child is appended to the parent, which holds at most 200 children. UpdateIdentity (19) changes name and metadata; deactivated: true is one-way and there is no reactivation path. An active identity gates capability listings, task claims, model records, heartbeats and bound devices.

AttestReputation (20) requires an active attestor identity and refuses self-attestation. The category is one of reliability, accuracy, speed, honesty, safety, general; the score is clamped to 0–100 and the identity keeps a running average per category. An identity holds at most 100 credentials. AgentMessage (21) is checked for type, payload size (≤ 8,192 B) and an active sender, and writes no contract state; the message exists only in the block.

6.3Capabilities and tasks

RegisterCapability (28) and UpdateCapability (29) are signed by the provider_identity, which must be active. A listing is keyed provider:category and holds tags, region (default global), description ≤ 2,048 B, price_per_unit, max_concurrent, metadata_json ≤ 4,096 B and reputation_snapshot, the reliability average of the provider at registration. A provider holds at most 100 listings; 50,000 may be active. QueryCapabilities (30) is a no-op in a block; discovery is GET /capabilities/search.

PostTask (31) escrows reward from the poster. min_reputation must be 0; expires_at_slot lies within 648,000 slots (≈ 30 days) of the posting slot; verification is poster_confirm or oracle, where the oracle is a named approver key, and automatic is removed (XWC-74). At most 100,000 tasks are live. ClaimTask (32) requires the claimant to be the signer, to hold an active identity and, when required_category is set, an active listing in that category carrying at least one required_tag. ResolveTask (33) carries one of the resolutions below.

6.4Oracles, devices, models and heartbeats

Four further registries follow the same pattern: a dedicated instruction, a signer bound to the record and a fixed cap. The device registry is protocol-managed and is created only after the first attestation proof verifies.

6.5Disputes

OpenDispute (36) names a defendant and posts a bond; the bond is at least 1 XRS for a deal dispute and may be 0 otherwise. The panel is a snapshot of every validator staked at least 1,000 XRS at the opening slot, minus the two parties, weighted by stake; an empty panel is refused. At most 10,000 disputes are open.

ResolveDispute (37) carries one action. During the 21,600-slot challenge window (≈ 1 day) only evidence from the disputer and defendant_evidence from the defendant are accepted. After it, vote_disputer, vote_defendant and vote_dismiss are accepted from panel members whose stake is still at least 1,000 XRS; one vote per validator, the latest counts. The dispute is ruled when one option reaches an absolute majority of the snapshot weight. A ruling moves only the bond: refunded when the disputer wins, forfeited otherwise. expire after 648,000 slots (≈ 30 days) refunds the bond.

6.6Deals

A deal escrows the same amount from each party; the pot is deposit_a + deposit_b. Every instruction after CreateDeal carries the deal instance, a counter that is never reused. At most 100,000 deals are live.

6.7State channels

OpenChannel (42) escrows the deposit of the opener; the counterparty joins through ContractCall join. CloseChannel (43) carries the 64-byte Ed25519 signature of the other party over the close message below, and the final balances must sum exactly to the deposits. ForceCloseChannel (44) with state_sequence 0 claims the original split; with a newer signed state it opens a 1,000-slot challenge (≈ 67 min), during which challenge_update supersedes it with a newer signed state and after which finalize_dispute pays the recorded split. Expired channels settle automatically, at most 256 per block. At most 100,000 channels are unsettled.

7Alexandria real-world assets

An Alexandria token is a token-registry entry whose rwa_metadata binds it to an off-chain Ricardian document by SHA-256 hash. TokenCreateRWA (6) creates the entry; the signer must equal mint_authority; the registry seeds approved_holders with the issuer. The compliance gate reads this entry, not the issuer contract of §7.3, before every credit.

7.1Token metadata

RWAUpdateStatus (7), signed by mint_authority, writes any of the five statuses from any current one, appends a status_history tuple and replaces valuation, legal_doc_hash and legal_doc_uri when supplied.

7.2Compliance gate

enforce_rwa_credit runs before every credit of an RWA token: TokenMint (0), TokenTransfer (1), RWATransfer (8) and a MultiSig-approved transfer. A token without rwa_metadata passes. The checks run in this order; the first failure rejects the instruction.

• Roster larger than 1,024 entries: refused.
• status other than active: no mint, no transfer.
• transfer_restricted: the recipient must be an approved holder.
• accredited_only: every recipient, minted or transferred, must be an approved holder.

The fourth check applies even when transfer_restricted is false: the roster is the accreditation roster. RWATransfer adds amount > 0, from != to and signer == from; it is otherwise identical to TokenTransfer.

TimeLock, Escrow, Swap, Vesting, LimitOrder and DcaOrder refuse an RWA token on any leg. A block carries at most 256 units of RWA policy work (MAX_RWA_POLICY_WORK_PER_BLOCK): each RWA TokenMint or TokenTransfer, each RWATransfer and each approve_holder or revoke_holder call costs 1, also as a delegated or conditional inner instruction. A block over the limit fails preflight; an instruction that would exceed the total is rejected, and a triggered conditional order is deferred.

7.3Issuer contract

ContractDeploy (5) with type rwa by the token's mint_authority creates a RealWorldAsset contract for one token_id. asset_type, legal_doc_hash, legal_doc_uri, jurisdiction and approved_holders are copied from the registry; caller-supplied values are ignored. Every method is issuer-only and accepts a direct ContractCall (4) only; AgentExecute inner calls and conditional-order calls to an RWA contract are refused.

There are no on-chain distributions; distributions_enabled and distribution_history are never written. Either redeem or RWAUpdateStatus with redeemed redeems the asset.

8ZK and post-quantum cryptography

Three primitives are reachable from consensus: Ed25519, ML-DSA-65 (Dilithium3) and Groth16 on BN254; §9 gives the signing contexts. Groth16 verifies proofs against verification keys registered by staked validators and is classically secure only. crypto.rs also holds Pedersen commitments, a Schnorr proof, a range proof and a WOTS+/XMSS verifier; no dispatcher arm calls them.

8.1Groth16 verification

The registry xeris_zk_verifier is a protocol-managed singleton. A proof is accepted only against a verification key already registered in it. The verifier is arkworks Groth16::<Bn254>; a result other than Ok(true) is a failure.

The per-block cap of 64 Groth16 submissions is enforced by the validator and mirrored by the producer, which defers the transaction that would exceed it. A stored record carries hashes, not proof bytes, so verified cannot change after submission.

The ZK path refuses any post-quantum claim. A case-insensitive substring match over vk_id, claim_type, description, proof_system, proof_type and metadata_json against pq, post-quantum, post_quantum, postquantum, post quantum, dilithium, mldsa, ml-dsa and ml_dsa rejects the instruction (crypto-module XWC-13). A field containing the two letters pq in any word is rejected. PqAttest (53) is a self-asserted adoption marker: the node performs no cryptographic check, stores the record in the separate pq_attestations map with verified = false, and records the caller's flag under self_asserted.

ZkPrivateTransfer (48) and ZkIdentityProof (49) are disabled at the dispatcher (§12.2); no receipt is written. The nullifier table in the registry is never written by any live path.

8.2Post-quantum key registry

xeris_pq_keys maps an Ed25519 address to its current ML-DSA-65 public key and to the history of keys it has held. The only accepted algorithm string is dilithium3; a public key is 1,952 bytes, a secret key 4,032 bytes and a detached signature 3,309 bytes. The crate is pqcrypto-mldsa, which replaced pqcrypto-dilithium (RUSTSEC-2024-0380) with the same parameter set and byte lengths (crypto-module XWC-12).

Bindings in key_history are half-open intervals [valid_from_slot, valid_until_slot); a key installed in block R is admission-active from R + 1. Closed bindings are retained for 302,400 slots (14 days, twice the unbonding period) so slash evidence for a past slot is checked against the key active at that slot. An Ed25519-only compromise cannot replace a registered key: registration is one-shot and rotation requires the current ML-DSA-65 key.

From slot 2 (PQ_REGISTRY_BINDING_ACTIVATION_SLOT) the inline proposer_dilithium3_pk of every block must byte-equal the registry entry for block.proposer; a missing or mismatched entry rejects the block on live and replay paths and is advisory only on the reorg pre-filter. The slot-1 block auto-registers its proposer's inline key, with the capitalised string Dilithium3 as pq_algorithm, and seeds its history. Every other producer registers through PqKeyRegister before its first block.

9Signatures, hashing and the transaction format

Three signing contexts exist. A transaction carries Ed25519 signatures only. A block carries one hybrid Ed25519 + ML-DSA-65 (Dilithium3) proposer signature. A peer authenticates with an Ed25519 signature over a server nonce. Every message the node signs or hashes begins with a fixed ASCII domain tag, and every chain-bound message also mixes in the chain id xeris-mainnet-v1 or xeris-testnet-v1.

9.1The hybrid block signature

From HYBRID_SIG_ACTIVATION_SLOT = 1 every block carries proposer_dilithium3_pk and hybrid_proposer_sig. The signed message is built by hybrid_canonical_message with the purpose block. Every variable field is length-prefixed, so two field sets cannot share one byte string, and a signature under one purpose does not verify under another.

Both halves must verify; there is no classical-only path for a mined block. The ML-DSA-65 half is checked against the key carried in the block, and from slot 2 that key must byte-equal the xeris_pq_keys entry for the proposer (§8.2). The mining worker receives only the proposer's public key; the block is signed on the validator's owning thread after the search completes (XWC-26).

9.2Merkle root

A leaf commits to the whole canonical transaction from MERKLE_FULLTX_ACTIVATION_SLOT = 1 (XWC-07). A transaction with an empty signature vector is an error, never a sentinel: the producer abandons the template and requeues its transactions, and a validator rejects the block (XWC-08). An unpaired node is hashed with the tagged pad, not with a copy of itself, which removes the CVE-2012-2459 duplicate-leaf ambiguity.

9.3Domain-separated messages

Table 19 lists every tag reachable from consensus or the network layer. lp(x) is u32 LE len ‖ x. id(s) is 0x01 ‖ 32-byte key when s parses as a public key, otherwise 0x00 ‖ lp(s). Integers are little-endian unless marked.

A chain-bound signature from one network does not verify on the other. The chain id changes on every hard fork.

9.4Transaction wire format

A transaction is a legacy solana_sdk::transaction::Transaction serialised with bincode 1.x: fixed-width little-endian integers and short_vec (compact-u16) lengths. Versioned (v0) messages are not accepted. account_keys[0] is the signer and the fee payer. The node ignores program_id_index and accounts for a XerisInstruction; the reference wallet sets the program id to the all-zero key.

Instruction data is bincode of the XerisInstruction enum: a u32 LE variant index, then the fields in declaration order. String and Vec carry a u64 LE length; Option is 0x00 or 0x01 ‖ T; bool is one byte; [u8; 32] is raw. The decoder tolerates trailing bytes, but they change the signature and the Merkle leaf; a client emits canonical bincode.

getLatestBlockhash returns the hash as hex; the client converts it to 32 bytes before signing. A signed transaction is submitted as POST /submit with the body {"tx_base64"} (limits in §10.5). Every rejection is returned as HTTP 200 with {"error"}.

9.5Peer authentication

Peers exchange bincode NetworkMessage frames over plain TCP. The rustls, tokio-rustls and openssl crates in Cargo.toml are not referenced by the source.

The server admits a peer only after the signature verifies against the claimed key. The server does not prove its identity to the client; a roster producer does, through the signed tip of §10.2. On mainnet a non-roster peer is dropped after authentication (§12.1).

10Network, mempool and sync

Nodes exchange length-prefixed bincode frames over plain TCP. Every connection opens with the Ed25519 challenge and response of §9.5.

10.1Gossip and relay

The wire carries eight NetworkMessage variants; the legacy AuthRequest is rejected on receipt.

A mined block or an admitted transaction is relayed to ceil(sqrt(n)) outbound peers, clamped to 3–15, each over a fresh connection and handshake that carries one message and closes. Received blocks are not re-relayed. active_peers holds outbound addresses only, so an inbound-only peer is never a relay target.

10.2Sync

The accepting side advertises XRS-V2-SYNC-TURNS. A dialer that echoes it gets a duplex connection: the server sends one turn, then its own GetBlocks, which closes the turn and hands over the write side. A dialer answering XRS-V2 polls one way. History comes from the 1,000 blocks in memory or from a byte-indexed scan of ledger.dat under a 5 s budget.

A received block enters the live ledger only as the exact child of the tip; every other block goes to the recovery coordinator of §2.4 (Table 4). Networking never calls the live Ledger::reorg.

Deep sync is roster-only. A producer that proves a fresh signed tip can have the node spool its branch from slot 1 into blocks.jsonl, replay both chains from genesis and, if the branch wins on work, rename the candidate and exit with code 75 for restart. Spools share XRS_MAX_DEEP_SYNC_BYTES, default 512 GiB.

10.3State, snapshots and replay

ledger.dat is the authoritative state: one JSON block per line, appended and fsynced before the block counts as committed. Startup replays it from genesis and re-validates every block under the full rule set. Replay fails closed: a read error or undecodable record stops the node. Only a trailing record without a line terminator is tolerated and truncated (XWC-57).

ledger_snapshot.json is written every 10,000 blocks with balances, stakes, tokens, contracts, processed signatures and governance maps. It is not read at startup; replay is the only load path, and a reorganisation deletes it. contract_state.json is a diagnostic dump with no consensus role.

Recovery clones the ledger with cp --reflink=always on Linux and clonefile(2) on macOS, at startup and before every candidate replay. On a filesystem without reflinks, ext4 among them, the node refuses to start. XFS with reflink, btrfs and APFS qualify.

10.4Mempool

The mempool is a max-heap keyed by fee, and the fee is flat: mempool_priority_fee returns BASE_TX_FEE for every transaction. Order among residents is heap order, and there is no fee market. Eviction needs a strictly higher incoming fee, so a full pool admits nothing until pruning frees space. Every rejection happens before any mutation. Bounds are in Table 6.

Pruning runs after every accepted block: entries whose blockhash left the 150-block window or whose signature is committed are dropped, committed reservations are released and the underfunded set is reconciled. Transactions displaced by a reorganisation are journaled in SQLite, re-admitted 256 at a time and relayed 16 per 2 s until they commit or the chain passes reorg_height + 64.

10.5Node interfaces

A node runs three listeners: P2P, the write RPC and the explorer API with JSON-RPC (Table 20). XRS_LOCAL_ONLY=1 binds P2P and RPC to loopback; the explorer always binds 0.0.0.0 and allows any origin. Write endpoints take a body of at most 256 KiB, 30 requests per minute per IP, and reject a signature seen within 120 s.

Transaction history and receipts are derived data in tx_receipts.sqlite, never read by consensus. On testnet a node without a store keeps validating and serves no history; on mainnet an open failure stops startup and an indexing failure writes a rebuild marker and exits with code 75. Endpoints that return 501 are listed in §12.2.

11Governance

Governance is the protocol-managed Governance contract at xeris_governance. The first CreateProposal creates it with min_proposal_stake = 100 XRS. Three instructions reach it: CreateProposal (39), CastVote (40) and ExecuteProposal (41). The generic contract-call path cannot invoke propose, vote or execute; the instructions are the only entry.

11.1Proposals and votes

Vote weight is consensus stake, not a lock. An address without stake cannot propose, and its vote adds zero weight. A vote after voting_end_slot is rejected without changing the proposal. Quorum counts abstentions; passage needs quorum and a strict yes majority. Finalisation happens in the first ExecuteProposal after the window closes: there is no scheduling, no timelock and no second step.

A passed proposal records an outcome and changes nothing on-chain. parameter_json is stored and never read; no handler applies a parameter change. proposal_type is a free-form string with no enumeration. Statuses are voting, passed and rejected; executed and expired are named in the struct comment and never assigned.

11.2Activation slots

Consensus rules are gated on slot constants compiled into the node, not on proposals. Every gate is active from the first mined block of this chain (slot 0 is the genesis marker; the first block is slot 1), so the table states the launch posture, not a migration path. A rule change with a new slot gate ships as a node release.

11.3RPC surface

GET /governance/proposals reads xeris_governance and returns { proposals, total_proposals, total_executed }; it maps voting to Active, passed to Passed and rejected to Failed, and omits votes_abstain and voters. GET /governance/lock/{address} reads the unwritten maps and returns locked_amount 0 and delegate null. The four POST /governance/* routes return HTTP 501 (§12.2); governance writes are instructions 39–41 submitted to POST /submit.

12Mainnet, federation and the audit record

Mainnet is chain id xeris-mainnet-v1, run by xrs-node 0.1.1 with --mainnet. With it the node runs as a federated beta: three roster producers propose blocks, public self-staking is closed, and the surfaces in §12.2 are refused. The consensus rules of §2 are unchanged; participation is gated. The build is a mainnet candidate; mainnet has not launched as of this revision.

12.1The producer roster

The roster is an operational beta gate, not a consensus vote. A fixed set of three keys is admitted to every path that produces, relays or stakes; the table lists each gate. The roster is fixed for the chain: changing keys requires a reviewed epoch migration, not an edit of the variable on restart.

12.2Disabled surfaces

The surfaces below exist in the build and are refused. An instruction refused at ingress never enters the mempool. An instruction skipped at the dispatcher is included in the block, charged the base fee, and executes nothing. Every RPC write that once mutated state outside consensus answers with an error; the replacement is a signed transaction to POST /submit.

12.3The audit record

CertiK reviewed the node as three separately numbered modules. Each module starts at XWC-01, so an id identifies a finding only with its module name: consensus XWC-22 is reorg signature validation, crypto-module XWC-22 is mempool capacity. Id ranges: consensus to XWC-88, crypto to XWC-22, contracts and network to XWC-81. Xeris has deferred consensus XWC-36 (dependency upgrades) and XWC-86 (fee model, on CertiK's recommendation that gas pricing be redesigned rather than patched).

Every CertiK document the repository answers is titled "Preliminary Comments". No CertiK-authored report is in the repository; CertiK's interim statuses are known as relayed in Xeris's responses. The first comments are dated 2026-05-01 and the latest Xeris response 2026-10-07. This paper cites an id inline where a rule exists because of that finding.

AAppendix A. Constants

Every value below is read from xrs-node 0.1.1 at commit 243046d; paths are src/<file>:<line>. The lamport is the base unit: 1 XRS = 1,000,000,000 lamports (9 decimals). Values the code stores in lamports are shown in XRS.

BAppendix B. The instruction set

XerisInstruction has 62 variants. The bincode discriminant is the declaration index, encoded as u32 little-endian, so the index column is the wire tag. Signer rule names the field that must equal the first account key, or the rule the handler applies. Status is what the block dispatcher does with the variant; disabled arms skip the instruction and still charge the fee.

CAppendix C. Contract types

ContractType has 23 variants. ContractDeploy resolves contract_type_str through ContractType::from_str, which lower-cases the input, so every alias is case-insensitive. Eight types are protocol-managed: user deploy is refused and the protocol creates each singleton under a fixed xeris_* id on first use.