# Use the ROKO Network

Start here for the current testnet, public deployments, node roles, install guides, and temporal examples.

Use the ROKO Network This is the public entry point for ROKO users, node operators, time-service operators, and application developers. ROKO is currently a testnet. Chain state, endpoints, and enrollment rules can change before mainnet. Read the checked network-manifest.json before following an operational guide. The September 10 network update explains the latest managed correction, public package availability and maintenance checks. The public RPC node runs 3.0.0-dev-764f8c18114 ; the public download selector still serves the September 8 nightly. Runtime spec 286 remains active on the configured testnet. Select software using the upgrade guide and verified artifact metadata rather than treating these three states as one release. The v1.1.0 package and v1.0.22 validator notice remain historical references. Choose a path I want to… Start here set up a wallet and claim test ROKO Wallets and faucet review proposals, conversations, votes, and stake Governance and Agora use public RPC, WebSocket, boot, or NTP services Public services choose a full, archive, validator, or observer role Node roles install a full, archive, observer, or candidate node Guided node install upgrade an existing native or Docker node Upgrade a node help distribute snapshots and releases BitTorrent seeding prepare an isolated validator Run a validator choose affordable validator key protection Validator key custody join the PTP² mesh without authoring blocks PTP² observer serve time to computers on my private LAN Private NTP server query and use nanosecond temporal data Temporal RPC quickstart read committed ROKO time from Solidity Temporal EVM precompile Three protocols, three jobs NTP disciplines a computer's system clock. ROKO provides a public NTPv4 source at time.roko.network . ROKO PTP² measures and exchanges clock observations between ROKO libp2p peers. It is not IEEE 1588 PTP. Temporal JSON-RPC exposes mesh quality and canonical on-chain nanosecond timestamps to applications. Joining one does not silently enable the others. Public-document boundary These guides intentionally contain only public DNS names, public ports, public chain identity, public peer identity, released software references, and generic topologies. They do not describe ROKO's origin addresses, internal hosts, private peer layout, management network, tunnels, credentials, or secret-store layout. Never post a seed phrase, private key, node-key file, credential, private topology, or unredacted service log in a support issue. Validation status The public RPC identity, finalized runtime, package metadata and governance availability were rechecked on 2026-09-10. See the dated manifest and update for the package/deployment gap and remaining qualification limits. Bootstrap, test, and edge commands target Linux with systemd and Chrony. Timebeat is the endorsed official validator timing partner, and maximum-tier validator payout eligibility requires a licensed Timebeat deployment plus participation in the Timebeat PTP² Mesh. Install the node from the public GHCR image or from the checksum-verified native binary distributed by HTTPS or BitTorrent. Public node operation never requires access to the private source repository. The current chain-spec bootstrap is testnet-only. Recheck the public RPC identity against the manifest: node scripts/validate-public-network.mjs Validator wallet alternative Use the local node-wallet guide when browser signing cannot complete validator registration. It includes funding, the four native transaction steps, finalized receipts, and recovery instructions.

---

# September 10 Network Update

Managed recovery, public download availability, finalized runtime and validator maintenance checks.

September 10 network and operator update The configured testnet is producing and finalizing blocks after the September 10 recovery and managed node rollout. This page records a dated observation, not a promise that a future maintenance window will be interruption-free. Recheck live finalized state before acting. Node software, downloads and runtime These are three separate facts: Surface Verified state on September 10 Managed node deployment and public RPC node 3.0.0-dev-764f8c18114 , source 764f8c18114386efa1587731e76c185b3f992280 Public releases/current download selector nightly-3eb6295b-20260908 , source 3eb6295b06aef11e87a01a7b22e36e166af2cb72 Finalized on-chain runtime mainnet spec 286 , transaction version 4 ; unchanged by this node rollout The immutable v1.1.0 package remains available as historical release evidence. Neither that package nor the September 8 public nightly contains the September 10 managed correction. A public package promotion for 764f8c1 is not established by this documentation update. Check metadata, artifact checksums, architecture, compatibility and the operator-approved revision before choosing an upgrade. Do not downgrade a newer managed node to match an older example or moving link. The dated values are also in the network manifest . Corrections and qualification The managed build includes a bounded transaction-pool wait and cancellation handling so stale-parent work cannot hold the authoring path indefinitely. It also classifies local receipt/storage lookup failures separately from protocol rejection. Qualification exercised real-runtime BABE reorganization, transaction retention after a competing head, and recovery after peer loss. Captured pending transactions finalized once after the competing tip was retracted in the successful rehearsal. The rollout preserved the existing chain history, genesis, identities, keys, authority membership and runtime. Every managed node passed independent canonical-finality checks, and the active managed validators produced fresh finalized blocks. A slow startup exposed an automation defect: RPC version availability alone was an insufficient baseline. The corrected deployment helper waits for the expected genesis and version, connected peers and completed sync before measuring finality, and retains failed canonical-check evidence alongside a verified rollback. This evidence does not establish the exact blocked task in the original live incident or resolve the separate receipt-history divergence problem. A successful service restart also does not qualify an abrupt power loss or every host's cold-boot sequence. Verify progress, not just readiness system_health , AUTHORED and readyToAuthor can remain reassuring while finality is stalled. Check the height of the authorship proof and require a fresh finalized block after startup. Resolve each chain_getFinalizedHead hash with chain_getHeader , sample again after an observation interval, and compare a common finalized height with an independent trusted node. A configured validator can be an unelected candidate. Keep registration, queued keys, active session membership and observed authorship separate. A non-authoring full node should not fail a health check merely because it has no validator keys or authored block. Maintenance and clocks Upgrade or reboot one active validator at a time, with enough other elected authority weight online to preserve quorum. Use a graceful systemd stop and verify the process exits before shutting down the host. Preserve the keystore, node identity, data volume and old executable; check encrypted-volume unlock, mount ordering, clock startup gates and dependent services before the window. After startup, require completed sync, independent finality agreement and fresh authorship appropriate to the node's active role. The managed validators retain the explicitly temporary early-testnet participation profile. It is not the strict software default and does not permit bypassing synchronization, active-key or fresh authority evidence. Do not change timing enforcement, quorum or membership as an incidental recovery step. Follow the upgrade and recovery guide . Explorer, wallets and governance Explorer routing and loading recovery have also been corrected. Check the named finalized source and freshness of displayed data; an HTTP success or loading indicator does not prove a current index. Agora supports participant review and the separately available wallet flows; governance.roko.network remains a wallet-free read-only evidence surface. A healthy proposal index is not execution authority. An EVM wallet's ability to send Ethereum transactions does not establish support for Agora's Substrate extrinsic signing. Follow wallet compatibility before generating an enrollment package, then verify finalized candidacy and selection through the validator guide .

---

# Services & URIs

Explorer, RPC, WebSocket, faucet, names, claims, governance/Agora, read-only IPFS evidence, validator self-join, nodes, liquidity, payment, staking, downloads, snapshots, torrent, bootnode, and NTP endpoints.

Public ROKO services Use the values in network-manifest.json as the machine-readable source of truth. This page explains how to use them. Service catalog Name Purpose Protocol explorer.roko.network blocks, transactions, tokens, validators HTTPS rpc.roko.network safe chain and temporal queries JSON-RPC over HTTPS/WSS faucet.roko.network testnet ROKO for user-controlled wallets HTTPS name.roko.network register, resolve, and manage .roko names HTTPS and wallet RPC claim.roko.network Ethereum holder recognition claims HTTPS and wallet RPC holders.roko.network holder snapshots, analytics, and exports HTTPS nodes.roko.network guided node install and operator handoff HTTPS agora.roko.network participant UI for review, wallet actions, staking, and validator self-join HTTPS and wallet RPC agora.roko.network/ipfs/<CID> read-only configured-testnet governance evidence HTTPS download governance.roko.network wallet-free, read-only governance evidence HTTPS clowder.roko.network testnet pools, swaps, and liquidity view HTTPS and wallet RPC payments.roko.network non-custodial payment request builder HTTPS and wallet RPC stake.roko.network pwROKO lock, unlock, and staking portal HTTPS and wallet RPC downloads.roko.network native and offline-container releases HTTPS snapshots.roko.network verified full/archive bootstrap data HTTPS and BitTorrent downloads.roko.network/torrent public artifact seeding guide HTTPS and BitTorrent boot.roko.network initial peer discovery ROKO libp2p multiaddress over TCP time.roko.network public UTC time source NTPv4 over UDP/123 The DNS names deliberately hide implementation details. Do not depend on a resolved address remaining fixed. Explorer, faucet, and artifacts Browse the chain at explorer.roko.network . Add testnet funds at faucet.roko.network . The faucet requires a wallet-signed proof of address control; the signature does not authorize a transaction or fee. Register and manage ROKO-local names at name.roko.network . .roko names resolve in ROKO-aware applications; confirm the displayed address before signing. Check Ethereum holder recognition at claim.roko.network . The active claim page links to the exact holder-intelligence snapshot used for eligibility. Browse published holder snapshots, analytics, source exports, and the ROKO testnet holder view at holders.roko.network . Launch or hand off a guided node setup at nodes.roko.network . Review governance without connecting a wallet at governance.roko.network , or use agora.roko.network for the participant experience and separately reviewed wallet actions. Read Governance and Agora for the capability and availability boundary before signing. Retrieve content-addressed governance evidence through the read-only https://agora.roko.network/ipfs/<CID> path. The gateway accepts only CIDv1/raw/sha2-256 identifiers and forces responses to download. It has no public upload or administrative API and does not fetch unknown content from the public IPFS network. Use clowder.roko.network for testnet liquidity and swap workflows. Create inspectable non-custodial payment requests at payments.roko.network . Manage pwROKO locking and unlocking at stake.roko.network . The current testnet validator walkthrough uses a 50-pwROKO self-bond. Follow Become a validator for claim, lock, bond, keys, candidacy, and activation checks; the live technical minimum is presently unset and must not be presented as a zero-bond recommendation. If your wallet is not configured yet, follow Wallets and faucet before claiming. Browse release artifacts at downloads.roko.network and verify the current release with SHA256SUMS . Bootstrap from a verified normal or archive snapshot at snapshots.roko.network . Use the peer-assisted download guide for the official torrent and magnet distribution guide. To help other operators download artifacts, follow BitTorrent seeding . Seeders only share public release and snapshot files; they do not need validator keys or source access. The explorer-compatible Ethereum JSON-RPC endpoint is https://explorer.roko.network/api/eth-rpc . Prefer https://rpc.roko.network for native Substrate and temporal methods. Bootnode A hostname is not a complete libp2p address. A bootnode multiaddress also contains its transport, port, and stable peer ID: /dns4/boot.roko.network/tcp/30333/ws/p2p/12D3KooWKSBZRtSiGKo8ueJtazCHT89LaBi6ZAtzgbeznf4NtVGj Pass that entire value to --bootnodes . Allow outbound TCP/30333. A node that will accept inbound peers must also allow its configured P2P listen port and advertise a reachable public multiaddress. This is libp2p traffic, not HTTPS JSON-RPC. An HTTP reverse proxy or ordinary Cloudflare Tunnel is not automatically a libp2p transport. HTTPS JSON-RPC Query basic health: curl --fail --silent --show-error https://rpc.roko.network \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}' Verify chain identity: curl --fail --silent --show-error https://rpc.roko.network \ -H 'content-type: application/json' \ --data '[ {"jsonrpc":"2.0","id":1,"method":"system_chain","params":[]}, {"jsonrpc":"2.0","id":2,"method":"chain_getBlockHash","params":[0]}, {"jsonrpc":"2.0","id":3,"method":"eth_chainId","params":[]} ]' Compare the genesis hash and EVM chain ID to the manifest. A DNS name and TLS certificate are not enough to establish that an endpoint serves the intended chain. Query mesh time: curl --fail --silent --show-error https://rpc.roko.network \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"temporal_getConsensusTime","params":[]}' The public endpoint is for safe methods. Never send a seed, secret URI, keystore operation, authoring/admin request, or unsigned transaction containing private material to it. Method discovery is not proof that a method is authorized. Use timeouts, exponential backoff, and more than one provider for a production application. Run your own full/archive node for high volume, privacy, historical-state guarantees, or independence from public rate limits. WebSocket Use wss://rpc.roko.network for subscriptions. A Polkadot.js example: import { ApiPromise, WsProvider } from "@polkadot/api"; const api = await ApiPromise.create({ provider: new WsProvider("wss://rpc.roko.network"), }); const unsubscribe = await api.rpc.chain.subscribeFinalizedHeads((header) => { console.log(header.number.toString(), header.hash.toHex()); }); process.on("SIGINT", async () => { unsubscribe(); await api.disconnect(); }); Applications should act on finalized heads when a reorganization would be unsafe. Public NTP Use ROKO as one of several independent, permitted sources: # /etc/chrony/sources.d/roko.sources server time.roko.network iburst pool pool.ntp.org iburst maxsources 3 Then reload and inspect: sudo chronyc reload sources chronyc sources -v chronyc tracking Do not add nts to the ROKO line until the manifest says ntsVerified: true . Do not mix leap-smeared and non-smeared sources. Respect server rate limiting and Kiss-o'-Death responses; aggressive polling harms the public service. NTP transports time to a host. It does not prove an on-chain event timestamp; use temporal RPC for that. Reporting a problem Report the problem through the operator form , the ROKO Telegram , or the ROKO Discord . Include: the public DNS name and protocol; UTC observation time; client software/version; sanitized error and retry behavior; and the manifest genesis hash you expected. Remove local addresses, peer lists, credentials, headers/tokens, and unrelated logs.

---

# Historical v1.0.22 Upgrade

Archived August rollout notice; consult the current network update before choosing software.

Historical notice: v1.0.22 validator upgrade This notice records the earlier rollout and is not a current upgrade instruction. Read the September 10 update and upgrade guide for the current software/runtime distinction. Original notice: Validator action required ROKO Network v1.0.22 is the required validator release before runtime spec 285 is activated. The release fixes the runtime mismatch that left the temporal EVM precompile unavailable at 0x0600 and preserves the native burn precompile already active at 0x0800 . Release identity Field Required value Release v1.0.22 Source revision e63656b14135e47bdeacbebd659754e42b920af6 Runtime after activation mainnet spec 285 Upgrade deadline 2026-08-12 20:00 UTC Architectures Linux amd64 and arm64 Native artifacts https://downloads.roko.network/releases/v1.0.22/ Container registry ghcr.io/roko-network/roko-node ABI https://downloads.roko.network/releases/v1.0.22/ITemporal.json Support and completion reports roko/roko_network#95 Treat this as a priority validator maintenance release and complete it as soon as practical, no later than the deadline above. The live configured testnet runs the mainnet runtime flavor. Operators on this network must therefore select the mainnet archive or image, even though the network remains explicitly test-only. Required action Read the current node upgrade procedure . Download only the architecture-matched mainnet artifact from the immutable release directory. Verify SHA256SUMS , BUILD-METADATA.json , the release ID, and the exact source revision before touching the service. Record the current binary or image digest, trusted genesis, finalized head, peer count, authority identity, and PTP² mesh state. Replace software only. Preserve the chain spec, database, node identity, seven session keys, temporal key, and service credentials. Require the full post-upgrade gate: expected revision, unchanged genesis, isSyncing: false , restored peers, advancing finality, correct active authority mapping, non-null producer index, and converged PTP² mesh. Upgrade validators one at a time. Stop if the network is degraded and do not move to the next validator until the current node passes every gate. Retain the v1.0.21 executable or exact image digest until spec 285 and the EVM canary pass. Installing v1.0.22 does not activate the precompile by itself. ROKO operators will submit the separately verified runtime upgrade only after the controlled fleet is ready. Report completion or a failed gate on issue #95 with the public node role, architecture, artifact checksum or image digest, and health result. Never post private keys, node keys, session keys, credentials, full service environments, or private topology.

---

# Wallets and Faucet

Add ROKO Testnet to popular EVM wallets and claim faucet funds safely.

Wallets and faucet Use this guide to add the current ROKO testnet to an EVM wallet and obtain test ROKO through either the Ethereum-holder claim or the public faucet. ROKO is currently a testnet. Test ROKO has no cash value, the faucet rules can change, and chain state may be reset before mainnet. Local alternative for validator enrollment If browser signing is failing, use the local validator wallet guide . It creates an encrypted node-generated staking account and runs the native lock, bond, set-keys, and validate calls from the operator’s terminal. It does not import a Talisman account: fund the new public address before proceeding. Automated and live read-only checks passed; funded end-to-end enrollment with this command remains unverified. Choose a signer before generating an enrollment package Agora staking and governance require a browser extension that signs Substrate transactions with an Ethereum-format 20-byte ( 0x... ) account. Ordinary MetaMask/EVM mode can display ROKO balances and handle EVM transactions, but it does not provide this signing interface. Opening MetaMask in the same browser or adding chain ID 52370 does not supply it. Talisman is a documented browser setup path, but validators have reported that they cannot complete the required transactions. Earlier success reports do not establish compatibility for every current account or wallet version. Confirm that the extension exposes your intended account and supports the exact ROKO network before proceeding; this is not a guarantee for every wallet version or account type. A watch-only account cannot sign, and a new account does not inherit the existing account's balance or enrollment. Use Talisman's custom-network instructions to add a Substrate network using wss://rpc.roko.network , then verify the full genesis and current metadata in Agora. Enable CheckMetadataHash as directed by the network setup panel. A web-only wallet or the ROKO wallet has not been verified as a replacement for Agora's injected signer. Keep signing in the owner's wallet: never give an agent a private key or paste wallet recovery material into a website or script. Connect and verify the wallet network before creating the short-lived public node package. If it expires during setup, use the supported refresh/reissue procedure. Do not edit its expiry or encoded key tuple; expiry alone does not mean another key rotation is required. Connection messages No Substrate wallet extension detected: enable a compatible extension in the same browser and for the Agora site, then retry. EVM wallet available: the current provider lacks the signing interface required by this flow; opening it again will not resolve the mismatch. No extension granted access: check the compatible extension's site permissions and approve the connection. No compatible account: expose the intended Ethereum-format account with signing capability, not an unrelated account or a watch-only entry. Network values for EVM transfers and claims Use the values below exactly. Field Value Network name ROKO Testnet Native currency ROKO Decimals 18 Chain ID 52370 Chain ID hex 0xcc92 RPC URL https://rpc.roko.network Explorer https://explorer.roko.network Faucet https://faucet.roko.network Holder claim https://claim.roko.network If a wallet asks for an Ethereum JSON-RPC endpoint and rejects the main RPC, use https://explorer.roko.network/api/eth-rpc . Before you claim Create or choose an EVM account with a 0x... address. The faucet uses a signed message to prove address control. That signature is not a token approval, not a transfer, and should not cost gas. Never paste a seed phrase, private key, hardware-wallet recovery words, or node operator secret into the faucet, a support chat, or a troubleshooting form. ROKO support only needs your public wallet address, transaction hash, wallet name, browser or app version, and the UTC time of the attempt. Holder recognition claim The holder claim is different from the faucet and can provide the allocation needed by an eligible validator wallet. Open claim.roko.network . Paste the public Ethereum address into Check eligibility . This does not connect the wallet or sign anything. If eligible, select Connect wallet and choose that exact same account. Review the displayed snapshot block, allocation, contract, and service status. Select Claim , approve adding or switching to ROKO Testnet if asked, and confirm the transaction in the wallet. Wait for Claim confirmed on ROKO testnet and open the receipt. An address absent from the published snapshot cannot use another wallet to claim its allocation. An already-claimed allocation cannot be claimed twice. The app never needs an Ethereum-mainnet transaction or token approval. MetaMask MetaMask supports custom networks in the browser extension and mobile app. Step Action 1 Open MetaMask. 2 Open the network selector. 3 Choose Add network or Add a network manually . 4 Enter the ROKO network values from this page. 5 Save the network and switch to ROKO Testnet . 6 Open faucet.roko.network . 7 Connect MetaMask, select the account to fund, sign the faucet message, and submit the claim. 8 Confirm the claim on explorer.roko.network . If MetaMask reports an invalid or missing chain ID, re-open the custom network entry and confirm the Chain ID is 52370 , not the hex value. MetaMask reference: How to add a custom network RPC . Rabby Rabby is a desktop browser-extension wallet for EVM chains and works well for custom RPC testing. Step Action 1 Open the Rabby extension. 2 Open the network selector. 3 Choose Custom Network or Add Custom Network . 4 Enter the ROKO network values from this page. 5 Save, switch to ROKO Testnet , and verify your selected account address. 6 Open faucet.roko.network , connect Rabby, sign the faucet message, and submit the claim. If Rabby warns that the RPC chain ID does not match, stop and verify the RPC URL and Chain ID against this page before signing. Rabby reference: Ledger guide for adding a Rabby custom network . Coinbase Wallet / Base app Coinbase Wallet branding and menus change over time; current Coinbase guidance refers users to the Base app or extension for custom EVM networks. Step Action 1 Open the wallet app or extension. 2 Go to Settings . 3 Open Networks . 4 Select the plus icon or Add network . 5 Enter the ROKO network values from this page. 6 Save and switch to ROKO Testnet . 7 Open faucet.roko.network , connect the wallet, sign the faucet message, and submit the claim. If the app does not show custom network controls, use MetaMask or Rabby for the faucet claim and keep the same public address for testing. Coinbase reference: Layer 2 networks and sidechains . Trust Wallet Trust Wallet supports custom EVM networks on mobile. Step Action 1 Open Trust Wallet. 2 Open the asset or network management screen. 3 Select the plus icon. 4 Choose the Network tab, not the token tab. 5 Enter the ROKO network values from this page. 6 Save and switch to ROKO Testnet . 7 Open faucet.roko.network in the wallet browser or a browser that can connect to Trust Wallet. 8 Connect, sign the faucet message, and submit the claim. Trust Wallet reference: How to add a custom network . Rainbow Rainbow supports custom networks in its browser extension. Rainbow's own documentation says custom networks are not supported in the mobile app. Step Action 1 Use the Rainbow browser extension. 2 Open settings and add a custom network. 3 Enter the ROKO network values from this page. 4 Save and switch to ROKO Testnet . 5 Open faucet.roko.network , connect Rainbow, sign the faucet message, and submit the claim. If you are on Rainbow mobile, use MetaMask, Rabby, Trust Wallet, or another EVM wallet that supports custom RPC networks. Rainbow reference: Custom Networks on the Browser Extension . Faucet flow Step Action 1 Open faucet.roko.network . 2 Connect the wallet account you want to fund. 3 Confirm that the displayed account is your intended 0x... address. 4 Sign the faucet proof message. 5 Submit the claim. 6 Open the returned transaction or address in explorer.roko.network . Keep one wallet account per tester when possible. Reusing a shared address makes support, allowance limits, and troubleshooting harder. The standard faucet is for basic testnet use and fees; it does not promise the 50 ROKO plus fees used by the current validator walkthrough. If an ineligible validator candidate lacks that balance, contact support with only the public address instead of repeating faucet requests or sharing wallet secrets. Troubleshooting If the faucet cannot connect to your wallet, reload the page, unlock the wallet, disconnect old site permissions for faucet.roko.network , and reconnect. If the wallet says the network is wrong, switch to ROKO Testnet and confirm Chain ID 52370 . If the faucet says your address was already funded, wait for the displayed cooldown or use the support channel listed in Public services . If the explorer does not show funds immediately, wait for finality, refresh the address page, and confirm the wallet is displaying the ROKO network rather than Ethereum mainnet or another EVM chain.

---

# Governance and Agora

Review finalized proposals, disclosures, conversations, voters, stake, and the exact boundary for wallet participation.

Governance and Agora ROKO governance is available on the configured testnet at two deliberate entry points: governance.roko.network is the wallet-free, read-only evidence view. Use it when you only want to inspect. agora.roko.network is the participant experience. It can connect an injected browser wallet for supported actions, but it never receives a recovery phrase or private key. Both sites identify the network as chain ID 52370 ( 0xcc92 ) with genesis 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb . Runtime spec 286 activated at finalized block 839462 on 2026-08-28. The fastest safe path Open the read-only proposal list without a wallet. Select a proposal and review its lifecycle, exact call or runtime payload, disclosure metadata, source-code reference, signed conversation ledger, provenance, voters, vote direction, and committed stake. Missing or unverified evidence is shown as unavailable rather than guessed. Resolve a public account through its verified .roko name when one exists. The canonical address remains visible and authoritative. Check public governance status . Require the expected genesis, runtime spec 286 or later, matching finalized and indexed heights, fresh: true , and executionAuthorized: false . Only when you intend to act, open Agora , connect your own wallet, confirm the network and account, review the exact call and fees, and sign that one action in the wallet. An empty proposal list is a valid chain state, not a loading failure. The configured-testnet projection began from a verified empty governance boundary and follows finalized state from there. What is public now finalized-first proposal, referendum, participant, validator, vote, stake, disclosure, deliberation, and provenance views; stable detail URLs that can be bookmarked or shared; machine-readable, bounded governance and validator APIs; wallet-free inspection through governance.roko.network ; browser-wallet participation surfaces in Agora, including staking, nomination, and permissionless validator candidacy; and bounded, read-only retrieval of independently pinned IPFS evidence through Agora; and explicit unavailable, stale, gap, and integrity-failure states. The public support API is deliberately read-only and has no signer, transaction constructor, Sudo authority, unsafe RPC, or chain-mutation credential. executionAuthorized: false describes that service boundary; it does not make a user-signed wallet transaction read-only. Configured-testnet support boundary Proposal disclosure/conversation publication and the finite participant faucet are active configured-testnet services. Check them before acting: GET https://agora.roko.network/api/v1/governance/publication/status GET https://agora.roko.network/api/v1/governance/faucet/status Both return HTTP 200 only while their exact genesis, spec-286 metadata, state, capacity, and dependencies are ready. The UI fails closed on a typed HTTP 503, runtime drift, replica disagreement, stale/gapped governance history, exhausted faucet capacity, or failed restart reconciliation. Publication verifies a participant signature and identical IPFS readback; it does not submit a chain transaction. The faucet signs only its finite 1,000,000-ROKO transfer after a wallet-possession challenge. Neither service can vote, approve a validator, author a runtime upgrade, use Sudo/treasury, or act on mainnet. Content-addressed evidence Agora serves exact CIDv1/raw/sha2-256 objects at https://agora.roko.network/ipfs/<CID> . Responses are forced downloads with nosniff and CSP sandboxing. The primary and verifier repositories pin the same operator-approved bytes independently; neither exposes an administrative API, swarm listener, or public upload path. Both replicas currently share one testnet host, so this is availability and byte-equality evidence, not a claim of multi-operator production durability. The fixed public availability probe is: bafkreidsfg624r66x6bcy3ljkqyez6xm73ddbyvdxkwobdxp4ltoznl7bq The dedicated ipfs.roko.network origin is staged but is not yet a public DNS contract. Use the Agora path until the dedicated hostname passes DNS and HTTPS verification. Signed proposal metadata A proposal disclosure can include public author-supplied contacts (such as an email address or project contact URL), supporting HTTPS resources, and one immutable source reference. The source reference is either a Git repository URL containing an exact 40-hex commit or a tar/gzip/zstd source archive with an exact SHA-256 digest and, for IPFS, an exact CID. These fields are part of the author's canonical signed disclosure; they are not endorsements by ROKO. Moving branch/tag links, credential-bearing URLs, active media, duplicate contacts, unsafe schemes, digest/CID mismatch, and oversized metadata are rejected before signing. A material metadata correction creates a new signed lineage version; it does not replace bytes already published. Public HTTP API The finalized read API is wallet-free and read-only: Route Result GET /api/v1/governance/status finalized RPC identity, indexed cursor/hash, lag, freshness, gap status, and executionAuthorized: false GET /api/v1/governance/records bounded finalized records with cursor pagination and lowercase filters GET /api/v1/governance/records/{recordKey} one exact finalized record GET /api/v1/governance/gaps bounded projection diagnostics GET /api/v1/governance/referenda/{index}/status direct finalized Referenda state GET /api/v1/governance/referenda/{index}/sponsorship-pools bounded live custody plus finalized sponsorship history GET /api/v1/governance/proposals/{recordKey}/review digest-verified disclosure, conversation, moderation, and provenance GET /api/v1/validators/{account}/economics finalized rewards, payout/claim state, fees, and slash evidence GET /api/v1/validators/{account}/economics.csv the same economics rows as quoted UTF-8 CSV Record page limits are 1–100. Invalid identifiers return a value-free 400; absent records return 404; unavailable/stale history returns a typed 503 rather than partial current truth. Validator economics never infer profit, APY, fiat value, private operating cost, or future rewards. Agora-origin mutation support uses bounded JSON requests: Route Purpose POST /api/v1/publications publish an allowed signed disclosure, deliberation entry, or receipt-metadata envelope POST /api/v1/formal-disclosures/prepare and /finalize preview, sign, and pin exact proposal disclosure POST /api/v1/initial-conversations/prepare and /finalize preview, sign, and pin the opening conversation GET /api/v1/formal-disclosures/{cid}/status inspect exact publication state GET /api/v1/formal-disclosures/{cid}/sponsorship retrieve submission-sponsorship material GET /api/v1/faucet/status?address=0x… inspect claim eligibility/capacity POST /api/v1/faucet/challenges and /claims prove wallet possession and request one finalized transfer Publication bodies are at most 64 KiB; faucet bodies are at most 4 KiB. Wrong origin/content type returns 403, rate exhaustion returns 429, malformed input returns 400, and unavailable dependencies return 503. Validator self-enrollment uses direct, separately reviewed wallet calls and a short-lived public enrollment package generated on the operator's node. Follow Prepare a validator for the exact journey and evidence required at each state. Accessibility, reliability, and recovery You can inspect public governance without a wallet, account, or extension. Use the page headings, landmarks, skip link, and ordinary links with a keyboard or screen reader. Status, errors, and unavailable evidence must be conveyed in text and never by color alone. Canonical addresses, transaction hashes, block numbers, proposal identifiers, content digests, and source links remain selectable and copyable. Refresh from the canonical URL after a transient failure. A proposal detail URL should remain stable; return to the proposal list if an identifier does not exist. If the status API reports a gap, stale projection, wrong genesis/runtime, or unequal indexed/finalized boundary, pause participation and use the read-only explorer or RPC to verify finalized chain state. Never enter a seed phrase, private key, keystore, reusable signature, or OpenBao credential into a site, support request, chat, or AI agent. Human review before a consequential action Deterministic checks cover network identity, payload and digest equality, metadata shape, signatures, balances, lifecycle state, finalized receipts, projection freshness, and accessibility automation. A person should still decide whether the proposal's intent, tradeoffs, risks, real-world references, source changes, social consequences, and requested authority are acceptable. The wallet confirmation is the final authorization for that exact transaction.

---

# Choose a Node Role

Compare full, archive, validator, observer, and private time-service roles.

Choose a ROKO node role One process can technically combine roles, but separation limits failure and attack impact. Role Keeps Publishes Authors blocks Typical use full/pruned current state plus bounded history P2P; local RPC no independent wallet/app RPC, network peer archive all retained block state P2P; local or deliberately protected RPC no indexer, historical queries validator state needed to validate/author private/reserved P2P only yes, after activation block production PTP² observer full or archive data by choice P2P clock announcement no contribute measurements, lab/home time node public boot/RPC sentry full or archive by policy public P2P and safe RPC preferably no external gateway Full versus archive A full node is the default for most users. Pruning bounds historical state growth, but old state queries may not work. An archive node uses --pruning archive . Capacity is an ongoing commitment: chain data grows, compaction needs temporary headroom, and indexers add their own database. Prefer a dedicated SSD/NVMe volume, monitor both bytes and inodes, and intervene before utilization reaches 80%. Do not place a growing archive on a small system/root volume. Verify an archive by successfully querying old state after synchronization. The process flag alone is not evidence. Validator separation A validator should not be the public bootnode, archive gateway, explorer RPC, or public time server. Put public peers and clients on full/sentry nodes and connect the validator through reserved/private P2P paths. Chrony is suitable for bootstrap, testnet validation, and edge systems. Eligibility for the maximum validator payout tier requires the endorsed licensed Timebeat profile and participation in the Timebeat PTP² Mesh, subject to measured performance and current program rules. See Run a validator . Observer separation An observer has a dedicated ptp2 identity and advertises clock measurements, but it is not a validator and does not enter authority convergence. It can separately serve NTP to a private LAN if Chrony is configured as a server. See PTP² observer .

---

# Guided Node Install

Use the white-glove installer for a full, archive, observer, or validator-candidate node.

Install a ROKO node with the guided installer This is the recommended path for a full, archive, observer, or validator-candidate node on the current ROKO testnet. The installer asks every question before changing the host, shows a complete plan, installs a verified runtime, waits for the clock and chain to synchronize, and writes a readiness report. For a visual walkthrough, use the ROKO Guided Install article . This page is the durable technical version of the same white-glove process. Use an AI agent The installer includes a public, model-neutral agent execution contract . You can also copy this bounded handoff into your preferred coding or operations agent: Install a ROKO testnet node using the public, audited installer. 1. Clone or update https://github.com/Roko-Network/roko-edge-tools 2. Start at docs/time-authority/README.md and read docs/time-authority/docset.yaml. Follow only the Pagenbar route matching my role, then read installer/AGENT-INSTALL.md and the selected setup.aiwg.io/v1 manifest. 3. Ask me for every required choice first: hobbyist or professional scope, geography, node name, role, runtime, whether NTP will be served, Chrony or Timebeat, sync timeout, and report path. 4. Help me select at least two sources: ntp01.roko.network may be one; another must be a geographically close Stratum 1 or 2 authority in a different failure domain. 5. Inspect the referenced scripts. Do not improvise replacement commands. 6. Run bin/roko-guided-install with the chosen time stack and --dry-run. 7. Show me the complete plan and wait for my explicit approval before running it without --dry-run. 8. Report success only after the docset acceptance gate passes, including source strata, selectable source count, leap state, matching genesis, peers > 0, isSyncing false, stable peer identity, and advancing finality. Include the readiness-report path. Do not expose RPC, open firewall ports, reset chain data, handle or reveal keys/licences, sign for me, or enable authoring. A validator-candidate must remain non-authoring until active-session membership is verified. After node readiness, you may guide me through the manifest's wallet, claim, 50-pwROKO lock/bond, and enrollment handoff; I perform every wallet confirmation. Stop and ask before any action outside the printed plan. For Timebeat, ask only for local package, licence, and reviewed configuration paths. Never request or print their contents. The configuration must use public or operator-owned authorities and must not depend on private ROKO timing topology. Required policy: establish independent time authority before joining, keep at least two selectable sources, inspect their stratum and root distance, and never lower the ROKO two-source gate. The agent may inspect, plan, execute the approved installer, and report evidence. It must collect every choice before the first change and must not expand the task into public exposure, destructive recovery, secret handling, or premature validator activation. For a candidate, it may continue through the manifest's interactive public wallet and enrollment guidance after node readiness. AIWG is optional on the node. The manifests follow the setup.aiwg.io/v1 contract, and the bundled launcher provides the compatible execution path for agents without AIWG installed. The visual guide provides the same prompt with a copy button: Give this to my agent . What you need a supported Linux host with systemd; a dedicated chain-data volume; outbound Internet access; git ; and a terminal with sudo access. Public node installation does not require private source-repository access or a container-registry login. 1. Start with the dry run git clone https://github.com/Roko-Network/roko-edge-tools.git cd roko-edge-tools ./bin/roko-guided-install --time-stack chrony --dry-run The launcher asks for: a public node name; the node role; native or Docker runtime; the maximum synchronization wait; and the readiness-report path. It then prints the complete ordered plan. A dry run performs no installation step. The plan also shows three separate connectivity outcomes: Layer Default behavior ROKO blockchain P2P Every role connects through the public bootnode. ROKO PTP² ( /roko/timesync/1 ) Every node runs the protocol; the observer role additionally advertises authenticated measurements using its dedicated ptp2 key. Timebeat PTP² Mesh Joined only when the operator selects the licensed Timebeat profile and supplies a reviewed vendor configuration. Choose observer with --time-stack timebeat when the intended result is a non-authoring node connected to ROKO chain P2P, advertising on ROKO PTP², and participating in the separate Timebeat PTP² Mesh. 2. Choose a role Role Use it for Initial storage plan full the recommended first node; verifies current chain state 200 GiB archive historical state, indexing, and archival infrastructure 1 TiB observer a full node plus a dedicated ROKO PTP² observer key 200 GiB validator-candidate a fully synchronized peer ready for open staking candidacy 200 GiB These are planning floors, not permanent capacity guarantees. Monitor actual growth and alert before the data volume reaches 80%. The validator-candidate role remains non-authoring during installation. After readiness, the guided installer offers wallet, claim, lock/bond, and session-registration handoff prompts. It never receives wallet secrets or claims that bonding alone activated the validator. 3. Choose one clock owner Bootstrap, testing, and edge nodes: Chrony Chrony is the no-licence bootstrap path for testnet evaluation, edge nodes, labs, and initial synchronization: ./bin/roko-guided-install --time-stack chrony The installer may configure ntp01.roko.network as one source alongside a geographically close Stratum 1 or 2 authority in a different failure domain. It requires at least two selectable sources, waits for host-clock synchronization, and only then starts the chain node. Official validator timing partner: Timebeat Timebeat is ROKO Network's endorsed official precision-time partner. Validator operators targeting eligibility for the maximum payout tier must run a licensed Timebeat deployment and join the Timebeat PTP² Mesh. Payout eligibility also depends on measured performance and the current network program rules. Obtain the stable package, per-node licence, and a reviewed timebeat.yml directly from: Timebeat software downloads Timebeat installation guide Timebeat initial configuration Timebeat PTP² Mesh basics Save the package, licence, and reviewed configuration as local files on the target host, then run: ./bin/roko-guided-install --time-stack timebeat --dry-run ./bin/roko-guided-install --time-stack timebeat The launcher asks for those local paths. It does not place licence or configuration contents in logs, Git, environment files, command arguments, or the readiness report. During qualification, Chrony remains the system-clock owner and must select at least two independent sources. Timebeat runs with adjust_clock: false for licensed PTP² mesh participation and evidence. The installer rejects active ntpd or ptp4l daemons. Never run multiple clock-steering daemons together. The reviewed Timebeat configuration must use public or operator-owned timing authorities. It must not depend on private ROKO timing topology. Timebeat PTP² Mesh and the ROKO built-in PTP² observer are separate layers. In the qualification profile, Timebeat participates in the licensed partner mesh and records timing evidence while Chrony owns the system clock. This provides the partner-mesh requirement for maximum-tier validator eligibility. The ROKO observer participates in authenticated ROKO mesh observation; running it does not replace the Timebeat requirement. 4. Approve the installation After the dry run looks correct, run the same command without --dry-run . The installer: checks the Linux platform, architecture, runtime, and storage; installs and synchronizes the chosen clock stack; downloads and verifies the ROKO native bundle or immutable image; installs the current testnet chain specification; configures a hardened, non-authoring systemd service; inserts a dedicated observer key when the observer role is selected; waits for peer and chain synchronization; and writes a value-free readiness report. RPC stays local by default. The installer does not open firewall ports or make the host a public gateway. 5. Require the readiness gate Installation is complete only when the launcher proves: testnet genesis is 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb ; at least one peer is connected; the ROKO time-mesh RPC is available and the node remains non-authoring; isSyncing is false; the local peer ID is stable; Chrony reports at least two selectable sources with a normal leap state; and finalized heads advance. Keep the generated readiness report. It contains operational results but no private keys or licence values. After a host reboot, confirm the data volume mounted, the chosen clock owner synchronized, and the node resumed finality. Re-run the launcher if a gate fails; the scripts are idempotent where practical and do not provide a destructive chain-reset path. Get help or continue to validator enrollment Validator preparation and current-v2 enrollment Validator key custody PTP² observer operation Snapshot bootstrap Telegram Discord Validator interest form Advanced reference The guided path is intentionally the default. Operators who need manual systemd construction, raw Docker commands, custom storage, public gateways, or detailed diagnostics can use Advanced node operations . Existing operators should use Upgrade a ROKO node for the current immutable release, native and Docker procedures, rollback, validator identity gates, and the bounded agentic upgrade contract. The audited installer scripts and AIWG manifests are also available in the public ROKO Edge Tools repository .

---

# Advanced Node Operations

Manual runtimes, storage, services, gateways, and detailed diagnostics.

Run a full or archive ROKO node This testnet guide targets a supported Linux distribution with systemd and Chrony. Use a dedicated machine or VM, service account, and data volume. 1. Prepare capacity Measure instead of relying on a permanent minimum: sustained P2P bandwidth and latency; database write latency and IOPS; memory pressure and swap activity; file descriptors; data-volume bytes/inodes and growth per day. For an archive, use a dedicated fast volume and alert before 80% utilization. The OS/root volume should have enough independent space to boot, update, and log even when chain data is large. 2. Obtain trusted software and chain identity Public node operators do not need access to the private ROKO source repositories. Choose one published runtime: the architecture-specific image from ghcr.io/roko-network/roko-node ; or the native Linux binary from downloads.roko.network , obtained over HTTPS or through the official torrent. Detect the host architecture: case "$(uname -m)" in x86_64) ROKO_ARCH=amd64 ;; aarch64|arm64) ROKO_ARCH=arm64 ;; *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;; esac Use the upgrade guide to select an explicitly approved immutable native archive or architecture-specific image, verify its checksum and full source revision, and preserve the existing installation. Its artifact selection and verification steps also apply to a new node. The public download selector predates the latest managed correction; see the dated network update before selecting software. Use the peer-assisted download guide for the torrent or magnet associated with that same verified release. Do not combine an old hard-coded torrent filename with a moving release directory. Do not use third-party binaries, guessed image names, curl | sh , or instructions that ask you to clone the private node repository. Recommended: verified one-off scripts Download all scripts with their checksum manifest, verify them, and inspect the runtime installer before execution: mkdir roko-install && cd roko-install ROKO_SCRIPTS=https://downloads.roko.network/scripts for file in SHA256SUMS install-roko-native.sh install-roko-docker.sh \ bootstrap-roko-chain-spec.sh install-roko-service.sh; do curl --fail --location --remote-name "$ROKO_SCRIPTS/$file" done sha256sum --check SHA256SUMS less install-roko-native.sh bash install-roko-native.sh bash bootstrap-roko-chain-spec.sh bash install-roko-service.sh \ --runtime native --node-name YOUR_NODE --start For Docker, inspect and run install-roko-docker.sh , then select --runtime docker in the service step. For a registry-free installation, download the matching roko-node-testnet-docker-*.tar.gz , verify it against the release SHA256SUMS , and pass it as install-roko-docker.sh --archive FILE . Every script supports --help and --dry-run . Never pipe a remote script directly into a shell. Until a release publishes the current testnet chain spec as a pinned artifact, it can be exported from the public RPC for testnet use: ROKO_RPC_URL=https://rpc.roko.network curl --fail --silent --show-error --max-time 30 "$ROKO_RPC_URL" \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"sync_state_genSyncSpec","params":[true]}' \ --output /tmp/roko-sync-spec-response.json python3 - <<'PY' import json from pathlib import Path response = json.loads(Path("/tmp/roko-sync-spec-response.json").read_text()) if response.get("error") is not None or not isinstance(response.get("result"), dict): raise SystemExit("RPC did not return a chain-spec object") Path("/tmp/roko-testnet-v2.json").write_text( json.dumps(response["result"], indent=2) + "\ " ) PY sudo install -d -o root -g root -m 0755 /etc/roko sudo install -o root -g root -m 0644 /tmp/roko-testnet-v2.json \ /etc/roko/roko-testnet-v2.json sha256sum /etc/roko/roko-testnet-v2.json This bootstrap depends on the public RPC and is therefore testnet-only. A production launch must publish and pin the chain spec independently. Do not pipe the chain spec through a JSON implementation that rounds wide integers. 3. Bootstrap the clock Configure at least three or four permitted, diverse Chrony sources. ROKO's public NTP service can be one input: server time.roko.network iburst pool pool.ntp.org iburst maxsources 3 makestep 0.1 3 rtcsync Restart Chrony, then require healthy tracking before starting the chain: sudo systemctl restart chrony chronyc waitsync 60 0.01 chronyc tracking chronyc sources -v waitsync 60 0.01 waits for a correction below 10 ms. Validators should set a tighter gate supported by their sources and deployment. 4. Create the service account and data path Example: sudo useradd --system --home-dir /var/lib/roko --create-home \ --shell /usr/sbin/nologin roko sudo install -d -o roko -g roko -m 0750 /var/lib/roko Mount the intended chain-data volume at /var/lib/roko before the service starts. Use a stable filesystem identifier in /etc/fstab and test a reboot. 5. Create a full-node service # /etc/systemd/system/roko-node.service [Unit] Description=ROKO full node Wants=network-online.target After=network-online.target chrony.service RequiresMountsFor=/var/lib/roko [Service] Type=simple User=roko Group=roko ExecStartPre=/usr/bin/chronyc waitsync 60 0.01 ExecStart=/usr/local/bin/roko-node \ --chain /etc/roko/roko-testnet-v2.json \ --base-path /var/lib/roko \ --name <NODE_NAME> \ --bootnodes /dns4/boot.roko.network/tcp/30333/ws/p2p/12D3KooWKSBZRtSiGKo8ueJtazCHT89LaBi6ZAtzgbeznf4NtVGj \ --port 30333 \ --rpc-port 9944 \ --rpc-methods Safe Restart=on-failure RestartSec=10 LimitNOFILE=65536 NoNewPrivileges=true PrivateTmp=true ProtectSystem=strict ReadWritePaths=/var/lib/roko [Install] WantedBy=multi-user.target RPC remains loopback-only because --rpc-external is absent. Allow inbound TCP/30333 only if you want other peers to dial this node. Do not expose RPC, Prometheus, a database, or administration ports without a separate reviewed gateway policy. For an archive, add: --pruning archive Do not run full and archive services concurrently against the same base path. Enable and inspect: sudo systemctl daemon-reload sudo systemctl enable --now roko-node sudo systemctl status roko-node journalctl -u roko-node --since today 6. Verify before relying on the node Query loopback RPC: curl --fail --silent http://127.0.0.1:9944 \ -H 'content-type: application/json' \ --data '[ {"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}, {"jsonrpc":"2.0","id":2,"method":"system_localPeerId","params":[]}, {"jsonrpc":"2.0","id":3,"method":"system_syncState","params":[]}, {"jsonrpc":"2.0","id":4,"method":"chain_getBlockHash","params":[0]}, {"jsonrpc":"2.0","id":5,"method":"chain_getFinalizedHead","params":[]} ]' The genesis hash must match 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb . Wait until isSyncing is false and the finalized head advances. Record the peer ID, restart the host, and verify: the data volume mounted; Chrony synchronized before the node started; the peer ID is unchanged; peers reconnect; and the finalized head continues to advance. The libp2p identity lives under the base path. Back it up as sensitive material, but never print or pass its secret with --node-key . 7. Upgrade or rebuild Use the complete Upgrade a ROKO node procedure. It covers the current immutable release, native and Docker rollouts, one-validator-at-a- time gates, rollback, and a bounded agentic upgrade contract. For every upgrade, verify the new artifact, stop only the intended service, preserve the base path and node identity, replace the native binary atomically or update the recorded container digest, start, and repeat all health checks. Keep the previous checksum-matched binary or image digest for rollback. Chain data is reconstructible from peers; identities and operator-owned keys are not. A database copy taken while the node is writing is not automatically a valid backup. Prefer a clean stop or a storage snapshot with documented consistency behavior. References Polkadot SDK CLI reference Polkadot SDK network parameters Polkadot SDK node-key safety Polkadot SDK pruning Polkadot SDK RPC safety model Chrony configuration reference

---

# Upgrade a Node

Upgrade native or Docker nodes safely with manual and agentic procedures, rollback, and validator identity gates.

Upgrade a ROKO node First compare the September 10 network update and network manifest with the artifact you intend to install. The managed correction 764f8c1 , public September 8 nightly, and historical v1.1.0 package are different revisions. Do not downgrade to match an older guide or promote an unqualified build by changing a download pointer. Use an explicitly approved immutable release path or architecture-specific image digest. The live configured testnet uses runtime spec 286 ( mainnet ), which is independent of a package's name. Verify the selected artifact's compatibility with the exact genesis and on-chain runtime; a testnet label alone neither establishes nor disproves that compatibility. The runtime was activated at finalized block 839462 on 2026-08-28. A node binary replacement does not call System.setCode . Query runtime version at a finalized block rather than inferring activation from the executable version. Upgrade validators one at a time. Full, archive, sentry, and observer nodes may be upgraded in parallel only while independent RPC, boot, and time-mesh capacity remains online. This procedure replaces software only. It must not replace the chain spec, base path, node identity, session keys, temporal key, or service credentials. Preflight Record the following before stopping anything: release tag, source revision, and artifact SHA-256 or image digest; installed unit and current executable or image digest; genesis hash, finalized head, peer count, sync state, and node role; authority index and PTP² mesh state for a validator; and the expected stash and all seven public session keys from the approved enrollment manifest for a validator. A healthy unit, correct genesis, peers, and isSyncing: false prove that a host is a synchronized peer. They do not prove that it owns an active authority slot. Confirm finality is advancing and the remaining authorities can retain quorum. Stop if the network is already degraded. The examples use roko-node.service , /usr/local/bin/roko-node , and loopback RPC on port 9944. Discover the real values from the installed unit instead of guessing them. : "${ROKO_RELEASE:?Set the approved immutable release ID}" : "${ROKO_SOURCE_REVISION:?Set the approved full source revision}" ROKO_SERVICE=roko-node.service ROKO_RPC=http://127.0.0.1:9944 systemctl show "$ROKO_SERVICE" -p FragmentPath -p ExecStart -p ActiveState chronyc tracking chronyc sources -v curl --fail --silent --show-error "$ROKO_RPC" \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}' curl --fail --silent --show-error "$ROKO_RPC" \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"chain_getFinalizedHead","params":[]}' curl --fail --silent --show-error "$ROKO_RPC" \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"temporal_getMeshState","params":[]}' Manual native-binary upgrade Download the architecture-matched bundle and checksum manifest into a new private staging directory: ROKO_RELEASE_BASE="https://downloads.roko.network/releases/${ROKO_RELEASE}" case "$(uname -m)" in x86_64) ROKO_ARCH=amd64 ;; aarch64|arm64) ROKO_ARCH=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac : "${ROKO_BUNDLE:?Set the compatible architecture-matched archive from release metadata}" mkdir -m 0700 "roko-upgrade-${ROKO_RELEASE}" cd "roko-upgrade-${ROKO_RELEASE}" curl --fail --location --remote-name "${ROKO_RELEASE_BASE}/${ROKO_BUNDLE}" curl --fail --location --remote-name "${ROKO_RELEASE_BASE}/SHA256SUMS" curl --fail --location --remote-name "${ROKO_RELEASE_BASE}/BUILD-METADATA.json" sha256sum --check --ignore-missing SHA256SUMS jq -e --arg release "$ROKO_RELEASE" --arg source "$ROKO_SOURCE_REVISION" \ '.release_id == $release and .source_revision == $source' \ BUILD-METADATA.json tar -xzf "$ROKO_BUNDLE" ./roko-node --version Require an OK checksum and the expected revision before touching the service. Stage the binary on the same filesystem and preserve the previous executable: sudo install -o root -g root -m 0755 roko-node \ /usr/local/bin/roko-node.new sudo systemctl stop "$ROKO_SERVICE" sudo cp --preserve=mode,ownership,timestamps \ /usr/local/bin/roko-node \ "/usr/local/bin/roko-node.before-${ROKO_RELEASE}" sudo mv /usr/local/bin/roko-node.new /usr/local/bin/roko-node sudo systemctl start "$ROKO_SERVICE" Do not delete the previous binary until the observation window passes. Manual Docker upgrade Use an architecture-specific immutable tag only to discover the image, then pin the resolved digest in the service environment: : "${ROKO_RELEASE:?Set the approved immutable release ID}" : "${ROKO_SOURCE_REVISION:?Set the approved full source revision}" case "$(uname -m)" in x86_64) ROKO_ARCH=amd64 ;; aarch64|arm64) ROKO_ARCH=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac : "${ROKO_CANDIDATE:?Set the approved compatible architecture-specific image reference}" docker pull "$ROKO_CANDIDATE" ROKO_IMAGE_DIGEST="$(docker image inspect "$ROKO_CANDIDATE" \ --format '{{index .RepoDigests 0}}')" ROKO_IMAGE_REVISION="$(docker image inspect "$ROKO_CANDIDATE" \ --format '{{index .Config.Labels "org.opencontainers.image.revision"}}')" case "$ROKO_IMAGE_DIGEST" in *@sha256:*) ;; *) echo "Image did not resolve to a registry digest" >&2; exit 1 ;; esac test "$ROKO_IMAGE_REVISION" = "$ROKO_SOURCE_REVISION" printf 'digest=%s\ revision=%s\ ' \ "$ROKO_IMAGE_DIGEST" "$ROKO_IMAGE_REVISION" docker run --rm "$ROKO_IMAGE_DIGEST" --version Record the digest, preserve the previous environment file, set ROKO_IMAGE to the digest rather than the tag, and restart only the node unit: sudo cp -a /etc/roko/node-image.env \ "/etc/roko/node-image.env.before-${ROKO_RELEASE}" printf 'ROKO_IMAGE=%s\ ' "$ROKO_IMAGE_DIGEST" | sudo tee /etc/roko/node-image.env >/dev/null sudo systemctl restart "$ROKO_SERVICE" Post-upgrade acceptance Inspect the unit and recent logs, then repeat the preflight RPC checks: sudo systemctl status "$ROKO_SERVICE" --no-pager sudo journalctl -u "$ROKO_SERVICE" --since '-10 minutes' --no-pager Wait for the expected version and genesis, connected peers and completed sync before starting the finality measurement window. RPC availability alone is not a successful startup. Retain failed checks and the verified rollback result. Require all of the following before moving to another validator: expected version and revision are running; genesis is unchanged and isSyncing becomes false; best and finalized heads advance across multiple observations and match an independent trusted node at a common finalized height; peers return to the expected range; Chrony is healthy and temporal_getMeshState returns Converged after warm-up; the expected authority role and non-null time quality are present, with a fresh finalized authorship proof after restart for an elected validator; and there are no repeated BABE, GRANDPA, database, time-source, OOM, or restart errors. AUTHORED and readyToAuthor can retain historical evidence during a stall. Check proof height and observation time. For an unelected candidate or a full node, validate its intended role instead of requiring active authorship. Acceptance for an elected validator is an identity join. At the same finalized head, prove: host keystore public filenames match the approved seven-key manifest; session.nextKeys(expected_stash) matches that manifest byte for byte; the expected stash is in session.validators , not only staking.invulnerables , staking.validators , or session.queuedKeys ; active BABE, GRANDPA, and temporal keys map to that host; and the host authors blocks and has the correct non-null producer authority index and temporal_getValidatorTimeQuality result. Record configured, queued, and active membership separately. Session changes are protocol-timed; do not declare success while only the configured or queued set matches. Rollback Restore only the saved executable or prior image digest. Do not roll back chain data after an upgraded node writes to it unless release notes explicitly state that the database format is backward compatible. Repeat every acceptance check after rollback and record the reason. Agentic upgrade contract An automation agent may perform this upgrade only after the operator supplies or approves the target hosts, release tag, immutable artifact, and rollout order. Give the agent this bounded contract: Upgrade my ROKO node to the explicitly approved immutable release and source revision using the public ROKO upgrade guide. Discover the actual unit, executable or image, chain spec, base path, node identity, role, and loopback RPC before changing anything. Capture preflight evidence without printing secrets. Verify the immutable checksum or image digest and embedded source revision. Preserve the chain spec, data, node identity, keystore, temporal key, credentials, and a tested rollback target. For validators, upgrade one host at a time. Stop if finality, peers, clock, storage, memory, or another validator is unhealthy. After restart, wait for sync, advancing finality, correct active authority identity, authorship, and PTP² convergence before continuing. Compare the complete intended set with session.validators and session.queuedKeys; validator count or staking.invulnerables alone is insufficient. A synced host absent from the active session may be a candidate; record that role without claiming active authorship. Stop on the first failed gate. Do not rotate keys, change chain spec, delete data, move a release tag, submit governance, or widen network exposure. Produce a value-free receipt with host, old and new revisions, artifact digest, timestamps, health results, and rollback disposition. The agent must ask before any action outside that contract.

---

# BitTorrent Seeding

Help distribute verified snapshots and releases with a safe, automated torrent client.

Seed ROKO artifacts with BitTorrent ROKO publishes node releases and chain snapshots over HTTPS and BitTorrent. Running a seeder helps other operators download large artifacts without putting all traffic on one public server. Seeding is optional. It does not make your machine a validator, RPC node, bootnode, or time observer. It only means your BitTorrent client keeps verified public files available to other peers. What to seed Artifact Best for Public source Normal snapshot most full nodes, validators before enrollment, lightweight seed boxes https://snapshots.roko.network/mainnet/normal/normal-latest.torrent Archive snapshot explorers, indexers, analytics operators, high-disk seed boxes https://snapshots.roko.network/mainnet/archive-latest.torrent Node release bundle users installing native binaries or offline container archives https://downloads.roko.network/releases/current/ If you can only seed one thing, seed the normal snapshot. If you have spare disk and bandwidth, add archive snapshots and the current node release bundle. Host expectations Area Recommendation Uptime Always-on or mostly-on host. A home lab, small VPS, NAS, or spare Linux box is fine. Disk Enough for the current artifacts you choose plus temporary download space. Keep at least 20% free. Network Public inbound TCP/51413 and UDP/51413 when possible. Seeding still works behind NAT, but it helps less. Permissions Run the torrent client as an unprivileged user. Do not run it as root unless your OS package does so through its own service isolation. Secrets None required. Never place validator keys, wallet seeds, node keys, or live database directories inside a torrent download path. Install a torrent client Transmission is simple to automate on Linux: sudo apt update sudo apt install transmission-daemon curl coreutils jq python3 sudo systemctl enable --now transmission-daemon On Fedora, RHEL, Rocky, or AlmaLinux: sudo dnf install transmission-daemon curl coreutils jq python3 sudo systemctl enable --now transmission-daemon Create a seed directory that the Transmission daemon can write. On Debian/Ubuntu packages the service user is usually debian-transmission ; on RHEL-family packages it is commonly transmission . sudo install -d -o debian-transmission -g debian-transmission \ /srv/roko-seed/snapshots /srv/roko-seed/releases If your distribution uses a different service user, replace debian-transmission with that user. Desktop users may use qBittorrent, Transmission, Deluge, or another client. Add the .torrent files or magnet links from snapshots.roko.network and downloads.roko.network , choose a stable download folder, and leave the client running. Seed the current normal snapshot transmission-remote 127.0.0.1:9091 \ --add https://snapshots.roko.network/mainnet/normal/normal-latest.torrent \ --download-dir /srv/roko-seed/snapshots If your Transmission RPC requires credentials, add --auth USERNAME:PASSWORD to the command or configure TR_AUTH=USERNAME:PASSWORD in the helper script environment. Verify completed payloads BitTorrent verifies pieces during transport. ROKO still expects operators to verify the published checksum before restoring or running an artifact. For snapshots: curl --fail --location https://snapshots.roko.network/mainnet/normal/normal-latest.json \ | jq -r '"\(.archive.sha256) \(.archive.file)"' \ > /tmp/roko-normal-latest.sha256 cd /srv/roko-seed/snapshots sha256sum -c /tmp/roko-normal-latest.sha256 For node releases: curl --fail --location \ --output /tmp/roko-release-SHA256SUMS \ https://downloads.roko.network/releases/current/SHA256SUMS cd /srv/roko-seed/releases sha256sum -c /tmp/roko-release-SHA256SUMS Do not restore a snapshot, execute a binary, or load an offline image until the checksum passes. Use the helper script The public tools repository includes roko-seed-refresh , which adds current ROKO torrents to Transmission and verifies completed downloads when checksum files are available. git clone https://github.com/Roko-Network/roko-edge-tools.git cd roko-edge-tools ROKO_SEED_PROFILES="normal releases" ./bin/roko-seed-refresh Profiles: Profile Behavior normal Adds the current normal snapshot torrent. archive Adds the current archive snapshot torrent. Use only when you have enough disk. releases Discovers the current node release torrent from downloads.roko.network and adds it. The script is intentionally non-destructive. It does not delete old downloads or remove torrents from your client. Prune manually after a newer artifact is downloaded, verified, and seeding. Automate refresh with systemd Install the tools and copy the example units: sudo git clone https://github.com/Roko-Network/roko-edge-tools.git \ /opt/roko-edge-tools sudo install -d -o debian-transmission -g debian-transmission \ /srv/roko-seed/snapshots /srv/roko-seed/releases sudo install -m 0644 /opt/roko-edge-tools/examples/roko-seed-refresh.service \ /etc/systemd/system/roko-seed-refresh.service sudo install -m 0644 /opt/roko-edge-tools/examples/roko-seed-refresh.timer \ /etc/systemd/system/roko-seed-refresh.timer sudo systemctl daemon-reload sudo systemctl enable --now roko-seed-refresh.timer By default the timer checks every 30 minutes. That is frequent enough for normal use because ROKO’s publisher promotes snapshot torrent metadata after verified public snapshots appear. Daily seeders can run the script from cron instead. To include archive snapshots, edit the service environment: Environment=ROKO_SEED_PROFILES=normal archive releases Then reload: sudo systemctl daemon-reload sudo systemctl restart roko-seed-refresh.timer When to update Event What to do New snapshot published Add the new .torrent or let roko-seed-refresh pick it up. Keep the old file only if you have space. New node release published Add the new release torrent from downloads.roko.network/releases/current/ . Low disk Remove old torrents from the client without deleting live node data. In Transmission use “remove torrent” first, then delete only files inside your seed directory. Bandwidth pressure Set an upload cap in your torrent client. A stable capped seeder is more useful than an intermittent overloaded one. Restoring a node Stop the node, verify the snapshot SHA-256, restore into the chain data path, then restart. Never torrent directly into a live database directory. Firewall notes Forward or allow: TCP/51413 UDP/51413 Only expose the torrent peer port. Do not expose Transmission RPC to the internet. Keep RPC on loopback or a private management network with authentication. Support checklist If you ask for help, include: the artifact profile you are seeding: normal, archive, releases; your torrent client and version; whether TCP/51413 and UDP/51413 are reachable; output from transmission-remote 127.0.0.1:9091 -l ; and checksum verification output. Remove usernames, private IP details you do not want public, tokens, RPC passwords, wallet material, and node keys before posting logs.

---

# Prepare a Validator

Claim funds, lock and bond 50 pwROKO, register keys, and verify open validator candidacy.

Become a ROKO testnet validator This is the beginner route from an ordinary wallet and synchronized node to a validator candidate. ROKO uses open staking enrollment: you do not need a ROKO operator to approve a normal candidacy transaction. Selection is still competitive and is not guaranteed. Which address goes where These values are for the current ROKO testnet , checked September 13, 2026: chain ID 52370 ( 0xcc92 ), 18 decimal places, genesis 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb . The live runtime reports mainnet spec 286; that internal name does not make this production mainnet. Verify the chain ID and genesis together. What you are doing Address or value to use Where it belongs Fund your validator or look up its balance Your own staking wallet's full 0x account address The sending wallet's recipient field, an explorer account lookup, or the node-wallet --account option View or import the pwROKO token; use its EVM lock/unlock interface 0x0000000000000000000000000000000000000500 Token import or the supported pwROKO application; symbol pwROKO , decimals 18 Identify the EVM staking interface 0x0000000000000000000000000000000000000700 Supported staking application contract configuration; this is not your staking account Lock and bond through the node wallet No contract address The tool selects native pwRoko.lock and staking.bond from chain metadata Register session keys and declare validator intent No contract address Native session.setKeys and staking.validate , signed by your staking account Register the public session tuple The package's session.encodedKeys value The session-key field; this long public value is not an account address Tell peers how to reach your node Your public P2P multiaddress ending in your peer ID Enrollment's --public-address ; this is not an RPC URL or wallet address The two fixed addresses above are precompiles : interfaces implemented by the chain runtime. Use the whole address when copying it. Never send a plain ROKO transfer to a precompile to lock or bond. Those actions require a method call. Keep native ROKO in your own account for fees after locking. Use Agora's validator enrollment or the local node-wallet guide for the complete sequence. The EVM staking precompile does not expose session.setKeys or staking.validate ; importing it into MetaMask cannot complete enrollment. Several staking selectors are runtime-specific, so a generic Solidity ABI is not a substitute for the supported application. The local wallet avoids this ABI issue by encoding native calls from metadata. Rewards and exit are separate native staking actions, including staking.payoutStakers , staking.chill , staking.unbond , and staking.withdrawUnbonded ; they do not require another recipient contract. The enrollment-only node-wallet command does not implement these maintenance actions. Follow the rewards and exit guidance below before changing a live validator. Unbonding stake and completing a pwROKO unlock are separate waits. For eligible snapshot claims, use the claim application with the eligible account. A claim is not a transfer to either precompile, and a newly generated node wallet does not inherit another account's eligibility. Check the network before signing Run this read-only command in a terminal with curl installed. It does not need a wallet and does not send a transaction: curl --fail --show-error --silent https://rpc.roko.network \ -H 'Content-Type: application/json' \ --data '[{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]},{"jsonrpc":"2.0","id":2,"method":"chain_getBlockHash","params":[0]}]' Find "id":1 with "result":"0xcc92" and "id":2 with the full genesis above. The responses may appear in either order. Stop if either differs. Public HTTPS RPC is for this check; local node-wallet signing uses ws://127.0.0.1:9944 on the validator host. Using the terminal in this guide Open a terminal on your computer and connect to your validator using the SSH login supplied by your hosting provider. In ssh YOUR_USER@YOUR_SERVER , replace both capitalized labels with your actual Linux username and server hostname or IP address. Confirm the server's SSH fingerprint using your provider's console before accepting a first connection. Run node and wallet commands in that SSH session, on the validator. Open Agora and the explorer in your computer's browser. Copy one command block at a time. Lines ending in \ are one command continued on the next line; copy the entire block. Do not type a leading $ prompt. A sudo prompt asks for your Linux login password; the wallet prompt asks for the wallet password you created. Neither displays characters as you type. If a command fails, read its message and resolve that step before continuing. Start with the guided node installation , choosing validator-candidate . Wait for its readiness checks to pass before creating session keys or staking. The local node-wallet walkthrough then covers software checks, wallet creation, funding, reviewing a transaction plan, and confirming each finalized result. What the words mean State What has happened Synced node The node follows the chain but does not author blocks. Locked Native ROKO was reserved 1:1 and the wallet received pwROKO. Bonded pwROKO was committed to staking. Candidate Session keys are registered and staking.validate is on-chain. Queued The staking election selected the candidate for a future session. Active validator The account is in session.validators and the node authors/finalizes. The --validator flag changes the node's local role. It does not skip any on-chain step. Before you start You need: a dedicated Linux host and the guided validator-candidate installation; a staking signer: either the local encrypted node wallet or a compatible Substrate-signing browser extension exposing the intended Ethereum-format 0x... account; 50 ROKO to lock and bond, plus liquid ROKO for fees ; safe local access to the node RPC; and a recovery copy of wallet and session-key material that no agent or support person can read. The live runtime currently reports an on-chain minValidatorBond of zero. That is an unset technical floor, not the recommended amount. ROKO's genesis and enrollment tooling use 50 pwROKO as the current testnet self-bond. Do not advertise zero-bond validation. The chain should be upgraded to encode the intended minimum before this becomes a mainnet economic rule. 1. Install and synchronize the node Follow Guided node install , choose validator-candidate , and wait for the readiness report. Continue only when: genesis is 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb ; system_health.isSyncing is false ; the finalized head advances; the peer ID survives a restart; and system_nodeRoles still reports Full during bootstrap. Keep RPC on loopback. Never run a full-node process and validator process against the same database at the same time. Select the signed tool and node separately Use signed enrollment tooling 1.4.1 with runtime 286 and a qualified Linux amd64 node build: source 086baf26c0e0db666526b8f649269facd1c37da7 ( nightly-086baf26-20260913 ) or be8920f47d282da73297c17875791c4e3d444625 ( v1.1.0 ). Keep the qualified current node; do not downgrade to make its release number match the tool. A node display such as 3.0.0-dev-086baf26c0e is a build identifier, not the enrollment-tool version. Compare binary digests against the signed release and qualification record . Tooling 1.4.0 first corrected the guarded RPC probe and portable offline checksum; 1.4.1 adds guarded reuse of an existing tuple. The v1.1.0 and v1.3.0 historical offline sidecars contain absolute build paths. Download the fixed archive and sidecar together, run sha256sum --check --strict in that directory, and still authenticate the pinned signed manifest before installing. Before restarting an existing installation, complete the existing-install preflight . Preserve the effective service, PHC device mappings/flags, clock/readiness checks, base path and peer/session identity. Generic Chrony defaults do not qualify a custom PHC image. The helper requires its supported policy-variable unit contract; a hardcoded Safe unit needs a reviewed adaptation preserving those settings. Do not rotate keys to refresh an expired package. 2. Set up the staking wallet Browser signing failing? Follow the local node-wallet alternative for account creation, funding, transaction planning, execution, and recovery. It performs the same four native calls locally. After candidate registration, return here for election, validator-mode, and authorship verification. Browser wallet path Complete wallet signing compatibility and setup before generating the short-lived enrollment package. Ordinary MetaMask/EVM mode cannot sign Agora staking or session-key calls, even with the right balance. Validators have reported current Talisman transaction failures. For the browser path, verify it exposes your intended Ethereum-format account, add ROKO as a custom Substrate network using wss://rpc.roko.network , and verify the full genesis and current metadata in Agora. A watch-only or newly created account is not a substitute for the intended signer. If the package expires during setup, use the supported refresh/reissue procedure without editing the expiry or tuple; do not assume new keys are needed. Never paste a seed phrase or private key into a terminal, chat, form, or AI agent. It is safe to share the public wallet address and transaction hashes. 3. Obtain testnet ROKO There are two different funding paths: If the wallet address was included in the Ethereum holder snapshot, open claim.roko.network , check the address, connect the same wallet, and press the claim button. The app switches or adds ROKO Testnet and waits for a receipt. Otherwise use faucet.roko.network for basic transaction funds. The standard faucet amount is not a validator bond. If the balance remains below 50 ROKO plus fees, use the support route in Public services and provide only the public address. Check the address in the explorer before continuing. 4. Generate the public enrollment package Install and verify the enrollment helper Keep the synchronized node non-authoring. Download the current installer with the signed SHA256SUMS manifest and the published release signing key. Require the key fingerprint to be exactly 62297562B1C7053088F405DB0117DAAA677A5BF2 , verify the manifest signature, then verify the installer against the signed manifest before running it. BASE=https://downloads.roko.network/validator-tools/current curl -fLO "$BASE/install-roko-validator-enroll.sh" curl -fLO "$BASE/SHA256SUMS" curl -fLO "$BASE/SHA256SUMS.asc" curl -fLO "$BASE/roko-release-signing-key.asc" gpg --import roko-release-signing-key.asc gpg --fingerprint 62297562B1C7053088F405DB0117DAAA677A5BF2 gpg --verify SHA256SUMS.asc SHA256SUMS sha256sum --check --strict --ignore-missing SHA256SUMS bash ./install-roko-validator-enroll.sh INSTALL_PATH="$(readlink -f "$(command -v roko-validator-enroll)")" printf '%s\ ' "$INSTALL_PATH" "$INSTALL_PATH" --version Do not run the installer if the fingerprint differs or either verification command fails. The printed path and version confirm the shell resolves the installed helper before you use it. Use the guarded session-key workflow from the signed tool release. The normal Safe RPC policy intentionally rejects direct key generation. The supported helper briefly opens a local key-management window, restores Safe, and checks restoration. Read its isolation requirements before running it; do not expose or forward port 9944. For --public-address , replace the example DNS name with your node's public DNS name and the peer-ID placeholder with this node's public peer ID from the readiness report. If using IPv4 rather than DNS, use the /ip4/ADDRESS/tcp/30333/p2p/PEER_ID form. These public node identifiers are different from your staking account. Keep the generated roko-validator-enrollment.json where the enrollment command can read it, and require the helper's Safe restoration check to pass. If you already generated keys, use the helper's --reuse-session-keys option with the unchanged public tuple and a new output filename. This verifies custody and refreshes the package without rotation, then restores exact Safe policy. A custody failure never triggers replacement keys. The CLI requires the exact configured-testnet genesis, advancing finality, a fully synchronized node, peers, a synchronized host clock, non-authoring mode, loopback-only author RPC, a reachable advertised P2P address, and proof that the generated public session tuple exists in this node's local keystore. Its default package expires after 30 minutes. The JSON is public but integrity-sensitive. It contains the public peer ID, advertised multiaddresses, binary/runtime/metadata digests, readiness facts, and seven public session identifiers. It must not contain a mnemonic, secret URI, private key, keystore, node-key bytes, wallet material, token, or OpenBao credential. ROKO's current metadata requires the seven-key order GRANDPA, BABE, ImOnline, authority discovery, Mixnet, BEEFY, and Temporal, plus explicit legacy-empty proof bytes 0x . The CLI and Agora fail closed if this contract changes. 5. Import in Agora, lock, bond, and declare intent Open Agora validator self-join : import roko-validator-enrollment.json and require Package verified ; connect the staking wallet and confirm chain ID 52370 , the canonical account, exact genesis, runtime, fees, and consequences; review and finalize pwRoko.lock(50 ROKO) ; review and finalize staking.bond(50 ROKO, Staked) ; review and finalize session.setKeys(public_tuple, 0x) ; and select commission and nomination preference, then review and finalize staking.validate(...) . Each is a separate wallet action. The encoded tuple comes only from the verified package and is not editable. Agora records the public digest as consumed after session registration; generate a fresh package for rotation. No ROKO operator, incumbent validator, Tally form, or Sudo call approves normal candidacy. If the connected account has zero balance and the finite configured-testnet faucet is available, Agora can grant exactly 1,000,000 ROKO after a wallet possession challenge. The signature is not a vote or transaction. Do not rely on the faucet for mainnet or as a statement of validator economics. After the calls finalize, verify the node/wallet handoff locally: roko-validator-enroll \ --rpc http://127.0.0.1:9944 \ --check-account 0xYOUR_STAKING_ACCOUNT \ --expected-session-keys 0xPUBLIC_ENCODED_KEYS Exit status 0 proves finalized bond, intent, matching next-session keys, and local custody. It does not prove election, active membership, or authorship. 6. Switch to the validator profile After all required enrollment calls finalize: record the working full-node service and rollback command; stop it and prove the process/database lock is gone; load only this node's session keystore; start the release-matched service with --validator , loopback-only safe RPC, and the reviewed reserved-peer policy; and keep the host clock synchronized and monitored. Understand the two time-source checks You do not need GPS/PPS hardware for testnet bootstrap. The guided Chrony profile uses public Internet NTP servers. chronyc sources -v should show one selected source ( ^* ) and at least one other usable combined source ( ^+ ). That is separate from temporal_getConsensusTime.peerCount . The temporal RPC counts mapped ROKO /roko/timesync/1 peers, not NTP servers. If it says zero: verify chronyc -c tracking succeeds in the node's own environment; when using an isolated service/container, verify chronyc exists there and chronyc -h /run/chrony/chronyd.sock -c tracking can read the explicitly mounted, read-only Chrony socket; confirm the service flag names the same socket path; and separately confirm connections to at least two current ROKO authorities whose time-protocol announcements map to their on-chain keys. Do not install hardware merely to make peerCount increase. Hardware improves clock quality tiers; it does not replace ROKO temporal peer connectivity. The current public bootnode is non-authoring. A node can therefore be fully synced through it while seeing zero mapped temporal authorities. Before authoring, the candidate must have a publicly reachable P2P multiaddress (or an approved outbound-dial arrangement) and direct ROKO P2P sessions with at least two active authorities. Never publish RPC, SSH, or Prometheus to solve this; only the libp2p port and peer ID belong in the public multiaddress. If those authority multiaddresses are not present in the published network manifest, this is a network-topology blocker owned by ROKO operations—not a mistake the beginner can fix by changing Chrony. Operations must either publish at least two safe validator/sentry-authority P2P endpoints or configure two active authorities to persistently dial the candidate's advertised address. 7. Verify selection and activation Registration does not guarantee an active slot. A candidate must win the runtime staking election and wait for the relevant era/session boundary. Call the node active only when all of these are true: the account has validate intent in staking storage; its expected keys appear in session.nextKeys ; it becomes queued and then appears in session.validators ; BABE, GRANDPA, and Temporal authority views include it; finalized blocks continue to advance; and the node authors a finalized block with non-null time quality. Use Agora validators to inspect the named finalized source, canonical account, candidate/waiting/queued/active state, bonds, session readiness, preferences, nominators, recent finalized authorship, and temporal-quality availability. The explorer is a helpful second display, but active on-chain session membership is the authority. 8. Reconcile rewards, payout state, and costs Open the validator's Agora detail page to inspect finalized credited payouts, extrinsic-wide fees, slashes, and exact era claim state. The same evidence is downloadable as canonical JSON from /api/v1/validators/{account}/economics and accessible CSV from /api/v1/validators/{account}/economics.csv . If an era has an unclaimed runtime page, Agora constructs only that exact permissionless payout call. The submitting wallet pays the network fee and the runtime sends rewards only to the configured payees. After finalization, Agora refreshes the runtime state and disables repeat submission when no unclaimed page remains. A credited payout is not a profitability claim. Public chain records do not contain private infrastructure, timing, labor, capital, tax, downtime, or risk costs. Export the finalized evidence and reconcile every attributable cost and loss before describing historical net income. Never present testnet results as an APY, forecast, guarantee, or mainnet economics. 9. Rotate, maintain, or exit For software maintenance or a host reboot, follow the September 10 maintenance checks and upgrade guide . Historical AUTHORED readiness does not prove current finality; require a fresh finalized authorship proof after restart when the node is elected. Keep the remaining elected authority weight online. Agora supports preference updates, fresh-package key rotation, chill, unbond, unlocking-era review, and mature withdrawal. During rotation, keep old keys until the replacement is active and has authored a finalized block. During exit, keep an active node online after staking.chill until finalized session state proves it is no longer active. Then unbond, wait the runtime bonding duration, and use staking.withdrawUnbonded when the chunks mature. Neither Agora nor the CLI automatically purges keys. Stop or delete material only after the corresponding safe finalized state is independently verified. What an assisting agent should do An agent may inspect public balances, transaction receipts, node health, and public session keys. It should explain one action at a time and name the state reached after each action. It must never ask for or handle a seed phrase, private key, keystore archive, wallet file, or reusable signature, and it must not report “validator active” from a successful bond or --validator alone. For hardened topology, timing, maintenance, and recovery guidance, read Validator key custody .

---

# Validator Key Custody

Select practical key protection without weakening operational boundaries.

Validator key custody without an expensive HSM ROKO operators can get meaningful hardware-assisted protection without a datacenter network HSM. The right device depends on which key is being protected and whether the node can ask the device to sign directly. Key types are not interchangeable Material Needed online? Main concern funding/bonding account rarely theft of stake/funds validator session keys while validating unauthorized consensus actions or downtime temporal/PTP² key while advertising false/unauthorized time announcements libp2p node identity while networking peer identity stability/impersonation disk/credential unlock at boot/service start offline theft of the keystore Keep funding/account keys offline or on a transaction-signing hardware wallet whenever the network workflow permits. Session keys and the libp2p identity have different availability and rotation requirements. Practical protection tiers Option What it can do well Important limit encrypted software keystore plus offline encrypted backup baseline confidentiality and recovery keys are usable in host memory while the node runs TPM 2.0 plus LUKS/systemd encrypted credentials bind disk/credential release to measured host state not automatically a Substrate session signer FIDO2/YubiKey-class token operator MFA and LUKS/credential unlock a security token is not automatically a direct validator HSM YubiHSM 2 PKCS#11, wrapping, attestation, compatible Ed25519/secp256k1 operations no documented sr25519; ROKO has no documented PKCS#11 session-signer adapter Nitrokey HSM 2 low-cost PKCS#11 smart-card HSM for supported RSA/ECC schemes no documented sr25519; integration must be implemented and tested network/cloud HSM centralized policy, audit, HA at organizational scale cost/latency/vendor integration; optional, not a prerequisite ROKO/Substrate session keys use more than one cryptographic scheme, including sr25519. Vendor algorithm lists for YubiKey PIV, YubiHSM 2, and Nitrokey HSM 2 do not establish sr25519 support. The current ROKO node uses its software keystore and does not document a PKCS#11 session signer. Therefore: do not claim that these devices keep every validator session key permanently inside hardware; use them today for operator authentication, encrypted-volume/credential unlock, backup wrapping, compatible account keys, and other supported roles; claim direct in-device session signing only after a signer adapter and every required key scheme pass integration, restart, throughput, failover, and rotation tests. “Hardware unlocks an encrypted software keystore” is valuable, but it is not the same as “the private signing key never leaves hardware.” A sensible low-cost design Enable secure boot and a TPM 2.0 when the host supports them. Put chain identities/keystore on encrypted storage. Bind unattended unlock to a reviewed TPM policy, or require a FIDO2 token when attended recovery is acceptable. Keep a second enrolled unlock/recovery method offline and physically separate. Keep the staking wallet separate from session/P2P identities. Use a hardware wallet/offline signer where compatible, or the encrypted local node-wallet alternative . Back up that encrypted wallet and password separately; never use session keys as wallet keys. Restrict USB devices with physical controls or allowlisting. A USB port is also an attack surface. Back up encrypted key material and test restoration on an isolated host. Rotate by activating a replacement before retiring the old key. Never make a single USB device, TPM-bound blob, motherboard, or passphrase the only recovery path. Secret handling Do not pass seed phrases or node keys as command-line flags. Do not put them in environment variables captured by service managers, diagnostics, or crash reports. Prefer an interactive prompt, restricted credential file, encrypted systemd credential, or local signer API. Decrypt only at service start into a root/service-readable runtime location, not a persistent world-readable file. Disable local unsafe key-management RPC after provisioning. Sanitize support bundles and monitoring labels. References Polkadot validator key management Polkadot SDK node-key warning YubiHSM 2 capabilities YubiKey PIV algorithms Nitrokey HSM 2 algorithms LUKS2 with PKCS#11, FIDO2, or TPM2 PKCS #11 v3.1

---

# Local Validator Wallet

Use an encrypted node-generated wallet to lock, bond, set session keys, and declare validator intent without a browser extension.

Enroll with a local node-generated wallet Use this alternative when Talisman or another browser wallet cannot complete validator enrollment. It signs the same native runtime transactions used by the managed validator setup: pwRoko.lock , staking.bond , session.setKeys , and staking.validate . The operator funds and controls the staking account. No administrator or sudo account is used. The staking wallet is an ECDSA account generated by roko-node key generate . It is separate from the node's seven session keys and P2P identity. This tool captures the exact raw node seed in memory, checks its public key, and saves only password-encrypted keyring JSON. It does not print a seed or mnemonic. Never substitute a session key, node key, or Ethereum-derived mnemonic. Addresses you will use Use testnet chain ID 52370 . Your wallet's public account is 0x followed by 40 hexadecimal characters. Copy it from the account field printed by create ; use that same value when funding the wallet and for every --account argument below. The tool checks that it matches the encrypted wallet. For reference, pwROKO is 0x0000000000000000000000000000000000000500 (symbol pwROKO , 18 decimals), and the EVM staking precompile is 0x0000000000000000000000000000000000000700 . Do not put either precompile in --account or send funds to it. This command uses native runtime calls and has no contract-address option. You do not need to import a token, enter an ABI, or approve an EVM spender to use this workflow. See the address and function reference . Verification status Published September 13, 2026. Encryption/recovery tests, the existing installer smoke suite, and read-only call encoding against testnet runtime 286 passed. A funded end-to-end enrollment with this new command remains unverified. Browser-wallet failures remain under investigation; this is a separate local signing path, not a claim that Talisman has been repaired. 1. Open the validator terminal and check software First complete the guided validator-candidate installation . Use your hosting provider's SSH login to open a terminal on the validator host . Keep this terminal open for the steps below. Commands run as your normal Linux user unless a step explicitly says sudo . Check the tools before installing the optional wallet command: python3 --version node --version npm --version git --version /usr/local/bin/roko-node --version Expect Python 3.x , Node v22.x or newer, version numbers for npm and Git, and a ROKO node version. If a command says command not found , install that prerequisite before continuing. On Ubuntu/Debian, Git and Python are available with sudo apt update followed by sudo apt install git python3 . For Node.js, use the official installation instructions and choose a supported LTS version 22 or newer with npm. Reopen the SSH session if the installer asks, then repeat the version checks. Do not assume the distribution's default Node package meets this minimum. If your verified node binary is somewhere else, replace /usr/local/bin/roko-node with that absolute path in this guide. A Docker-only installation also needs a verified matching host binary for wallet creation; follow the node installation guide's binary verification procedure first. The wallet command is available in the source checkout; the existing signed enrollment bundle does not install its Node.js dependencies. Use a dedicated checkout pinned to the reviewed wallet release: mkdir -p "$HOME/roko-tools" git clone https://github.com/Roko-Network/roko-edge-tools.git "$HOME/roko-tools/validator-wallet" cd "$HOME/roko-tools/validator-wallet" git checkout --detach 12c77a5d6ff276e271e587659946edaefde277a2 npm ci --ignore-scripts --prefix wallet npm test --prefix wallet bin/roko-validator-wallet --help The tests must pass and help must list create , plan , and enroll . If the clone destination already exists, do not delete it or overwrite files: use that checkout only after checking git status and its revision with git rev-parse HEAD . Save your own changes before updating a checkout. For each later SSH session, return here with cd "$HOME/roko-tools/validator-wallet" before running a bin/ command. Run the command as your normal operator user on the validator host. RPC must listen only on loopback, with WebSocket enabled on 127.0.0.1:9944 . Do not publish or forward RPC. Signing works with the node's normal Safe RPC policy; only session-key generation uses the existing guarded key-management window. 2. Create and fund the staking wallet install -d -m 700 "$HOME/.local/share/roko-validator" bin/roko-validator-wallet create \ --binary /usr/local/bin/roko-node \ --wallet "$HOME/.local/share/roko-validator/staking-wallet.json" Enter a unique password of at least 12 characters at the hidden prompt. The command prints JSON containing account , wallet , and encrypted: true . The account value is your public 0x address and refuses to overwrite an existing wallet. Back up the encrypted wallet and keep its password separately. Losing either prevents future staking transactions and withdrawal. Do not commit wallet files or send them to support. Fund the printed address with native ROKO on testnet (chain ID 52370 ). Enrollment defaults to 50 ROKO bonded and also needs native ROKO for each transaction fee and the existential deposit. The tool checks the current minimum validator bond and estimates each next transaction fee. If the minimum exceeds 50 ROKO, use --stake-planck with the desired integer amount in base units; one ROKO is 1000000000000000000 planck. This first version creates a new staking wallet. It does not migrate funds, import Talisman accounts, or replace an existing validator's wallet. Fund the new address through your existing funded account or the testnet funding route. 3. Prepare the public session package Complete the node readiness and guarded session-key workflow on this same node. Restore and verify Safe RPC before proceeding. The public roko-validator-enrollment.json must be fresh and identify this node, runtime, and testnet genesis: 0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb Keep the node in its non-authoring candidate configuration during enrollment. Use the existing session tuple when refreshing an expired package; do not rotate keys to retry a transaction. 4. Review the next transaction Keep the enrollment file in this checkout, or replace its filename in every command with its actual absolute path. Confirm it is present: pwd ls -l roko-validator-enrollment.json pwd should end in /roko-tools/validator-wallet . If ls reports No such file or directory , find the output path from the session-key workflow and use that path. This JSON contains public session facts; it is different from the encrypted staking-wallet.json and cannot replace it. Replace 0xYOUR_40_HEX_CHARACTER_ACCOUNT below with the complete account value printed at wallet creation. It is a placeholder, not an example account to fund. Copy the whole block after replacing it: bin/roko-validator-wallet plan \ --wallet "$HOME/.local/share/roko-validator/staking-wallet.json" \ --account 0xYOUR_40_HEX_CHARACTER_ACCOUNT \ --enrollment roko-validator-enrollment.json plan never opens the wallet or asks for its password. It checks the current loopback listener, chain, runtime metadata, node identity, synchronization, advancing finality, live minimum bond, pending nonce, and finalized staking state. It prints the next needed call, encoded call data, estimated fee, and native balance requirement. Review the full sequence: lock enough ROKO to reach the requested pwROKO balance, bond that amount with rewards set to Staked , register the package's session tuple with the current empty proof, then declare validator intent with zero commission and nominations unblocked. Existing validator preferences are preserved. Estimates are refreshed before each call; fee reserves are estimates, not a guarantee of future network fees. The JSON fields nextCall , estimatedFeePlanck , nativeRequiredPlanck , and nativeFreePlanck explain the next step. Amounts here are integer base units: 50000000000000000000 is 50 ROKO. plan checks one next transaction; rerun it after funding if it reports insufficient balance. It does not reserve funds. 5. Sign and wait for finalization This next command submits transactions . Continue only after checking the account, network, stake amount, and plan. The default is 50 ROKO; if you choose a different --stake-planck amount, use the same value for both plan and enroll . Keep the SSH session open while it runs. bin/roko-validator-wallet enroll --execute \ --wallet "$HOME/.local/share/roko-validator/staking-wallet.json" \ --account 0xYOUR_40_HEX_CHARACTER_ACCOUNT \ --enrollment roko-validator-enrollment.json The hidden password unlocks the wallet locally. Its derived address must match --account . Each submission reports its public transaction hash, waits for finalization, prints the finalized block receipt, then rechecks state before the next step. Avoid other transactions from this account during enrollment. 6. Confirm completion or recover from an interruption Insufficient funds: fund the displayed account, then rerun plan . Pending nonce or timeout: a transaction may still finalize. Inspect its explorer status and wait for pending activity to settle before rerunning. Do not create a second wallet or blindly resubmit from another tool. Dispatch failure: inspect the transaction's explorer receipt and resolve the runtime error. Earlier finalized calls remain effective. Expired package or runtime change: refresh the package with the same session keys using the guarded workflow, then rerun plan . Different registered keys or insufficient existing bond: stop and review the existing validator. This enrollment command does not rotate keys, increase existing bonds, change commissions, unbond, or withdraw. A successful enrollment prints "status":"candidate registration finalized" and a finalizedHash . Save the public transaction/block hashes so you can look them up in the explorer. This does not mean the validator is active. If your SSH connection drops, reconnect, return to the checkout with cd , and run plan before deciding whether to resume. Do not rerun create . For support, share the command name, exact error, public account and transaction hash; leave out wallet files and passwords. Rerunning checks finalized state and skips completed steps. A finalized candidate registration does not mean the node has been elected or authored a block. Continue the join and monitor procedure , verify the session tuple and custody on the node, then enable validator mode according to that procedure. Confirm election and authorship separately. Before enabling validator mode, use the installed roko-validator-enroll helper to verify finalized state and local custody under Safe RPC: roko-validator-enroll \ --rpc http://127.0.0.1:9944 \ --check-account 0xYOUR_40_HEX_CHARACTER_ACCOUNT \ --expected-session-keys "$(python3 -c 'import json; print(json.load(open("roko-validator-enrollment.json"))["session"]["encodedKeys"])')" The tuple is public. Require safeToEnableValidatorMode: true ; keep Safe RPC enabled. A not-ready result is not permission to skip custody verification. Older signed tool bundles may lack the Safe readiness fallback; use the source command above until a new signed bundle includes it.

---

# PTP² Observer

Join the ROKO time-quality mesh without authoring blocks.

Join ROKO PTP² as a non-authoring observer An observer runs a fully synchronized ROKO node and advertises authenticated clock measurements without becoming a validator. What PTP² is—and is not ROKO PTP² is carried by the ROKO libp2p protocol /roko/timesync/1 . It is not IEEE 1588 PTP and does not use UDP/319 or UDP/320. All guided-install roles join the ROKO blockchain P2P network and run the ROKO time protocol. The observer role is the explicit opt-in that adds a dedicated host-scoped key and authenticated observer advertisement. An observer: has one dedicated host-scoped sr25519 key of type ptp2 ; is measured by peers; is excluded from validator convergence, consensus votes, temporal receipts, and block authoring; and does not become an authority unless separately enrolled and promoted. Joining PTP² does not discipline the host clock and does not make the host an NTP server. Chrony handles host discipline; optional LAN NTP is a separate configuration. Timebeat's licensed PTP² Mesh is also separate. An operator may select the Timebeat clock profile and the ROKO observer role together; that host then participates in Timebeat PTP² for clock delivery and advertises authenticated measurements on ROKO PTP² while remaining non-authoring. 1. Build a healthy non-authoring node Follow Run a node . Do not use --validator . Wait for: healthy Chrony tracking; at least one P2P peer; full synchronization; advancing finalized heads; and a controlled restart with the same libp2p peer ID. Use multiple independent time sources. time.roko.network can be one source, not the only source. 2. Insert the observer key locally Stop the node. Run the key insertion command as the node service user and omit --suri ; the CLI then prompts without putting the secret URI in the process list or shell history: sudo systemctl stop roko-node sudo -u roko /usr/local/bin/roko-node key insert \ --base-path /var/lib/roko \ --chain /etc/roko/roko-testnet-v2.json \ --key-type ptp2 \ --scheme sr25519 Generate the secret in a trusted offline workflow, enter it only at the prompt, and protect its recovery copy. Do not paste it into an issue, environment variable, service file, or command line. The observer startup contract is exactly one ptp2 key. Startup fails if it finds zero or more than one. Key replacement is therefore a stop, back up, replace, verify, and restart operation—not an unbounded additive insert. 3. Enable observer advertisement Add these flags to the existing node service: --timesync-time-source auto --timesync-advertise-observer If Chrony uses a non-default command socket, add: --timesync-chrony-socket <CHRONY_SOCKET> Grant the service only the minimum group/socket permission required to read Chrony health. Do not make the socket public. Keep the systemd clock gate: After=network-online.target chrony.service ExecStartPre=/usr/bin/chronyc waitsync 60 0.01 4. Verify After starting: chronyc tracking chronyc sources -v systemctl status roko-node journalctl -u roko-node --since today Query safe local RPC: curl --fail --silent http://127.0.0.1:9944 \ -H 'content-type: application/json' \ --data '[ {"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}, {"jsonrpc":"2.0","id":2,"method":"system_nodeRoles","params":[]}, {"jsonrpc":"2.0","id":3,"method":"temporal_getMeshState","params":[]}, {"jsonrpc":"2.0","id":4,"method":"temporal_getConsensusTime","params":[]} ]' Confirm the node role remains Full , not Authority . Mesh peer count and quality can change as the network measures peers; observer presence must not change the active authority count. Reboot and verify Chrony converges before the node, both identities persist, P2P resynchronizes, and the node remains non-authoring. Optional: serve your private network Continue with Private NTP server . This creates a separate path: independent NTP/NTS sources -> Chrony -> home LAN clients (NTP) | `-> ROKO PTP² (libp2p observer) References ROKO observer implementation: node/cli/src/cli.rs and node/cli/src/service.rs Chrony configuration reference NTPv4 NTP operational best practices

---

# Private NTP Server

Serve disciplined time safely to systems on a private LAN.

Serve time to a private LAN This guide turns the Chrony instance on a ROKO observer or ordinary Linux host into a restricted NTP server for home/lab computers. It does not expose ROKO PTP² to LAN clients. PTP² and NTP are separate protocols. Prerequisites the server has a stable LAN address; Chrony already uses at least three or four permitted, diverse sources; chronyc tracking reports synchronized; the host firewall can distinguish the LAN interface/subnet from the Internet. Use time.roko.network as one source, not the only source. Chrony configuration Create a dedicated fragment using your actual LAN values: # Upstream sources server time.roko.network iburst pool pool.ntp.org iburst maxsources 3 minsources 2 makestep 0.1 3 rtcsync # Serve only the private LAN allow <LAN_CIDR> binddevice <LAN_INTERFACE> # Disable the remote chronyc UDP command port cmdport 0 # Limit abusive/misconfigured clients ratelimit interval 3 burst 8 leak 2 Do not copy <LAN_CIDR> or <LAN_INTERFACE> literally. Use a narrow subnet; do not use allow all or 0/0 . cmdport 0 disables the remote UDP command interface. Local administration continues through Chrony's Unix socket. Firewall Permit UDP/123 only from <LAN_CIDR> on <LAN_INTERFACE> . Drop it on public interfaces. The exact command depends on your firewall manager; verify the effective rules after every reboot. Do not open UDP/319 or UDP/320. ROKO PTP² is not IEEE 1588 PTP. Validate the server On the server: sudo chronyc reload sources chronyc tracking chronyc sources -v chronyc clients On a LAN Linux client, add: server <LAN_TIME_SERVER> iburst Then inspect chronyc sources -v and chronyc tracking . macOS and Windows clients can use <LAN_TIME_SERVER> through their normal network time settings. Test both sides of the boundary: a LAN client receives NTP replies and converges; a host outside the allowed subnet receives no reply; a reboot restores firewall rules, upstream sync, and LAN service; if upstream sources are unhealthy, the server does not claim a false local reference clock. Security and accuracy notes NTP representation and actual accuracy are different. Wi-Fi, NAT, queueing, and asymmetric paths add error. Standard NTP is unauthenticated unless NTS or another authenticated design is configured. Do not add nts to a source that has not been verified to support it. Do not mix leap-smeared and non-smeared upstreams. Monitor loss of synchronization, root distance, falsetickers, reach, and unexpected client volume. Follow RFC 8633 and the Chrony configuration reference .

---

# Temporal RPC Quickstart

Query finalized temporal data without losing nanosecond precision.

Build with ROKO nanosecond time ROKO timestamps ordinary EVM and Substrate transactions automatically. A user does not submit a special “timed transaction” envelope. Know which time you are reading Value Meaning mesh consensus time the node's current PTP² mesh estimate canonical transaction timestamp timestamp assigned to a transaction transaction watermark highest canonical timestamp processed by chain state block nanosecond timestamp temporal metadata attached to a block EVM block.timestamp conventional EVM seconds, not ROKO nanoseconds Nanosecond representation does not promise nanosecond wall-clock accuracy. Inspect convergence, peer count, time quality, source distance, and application latency. Query mesh time curl --fail --silent --show-error https://rpc.roko.network \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","id":1,"method":"temporal_getConsensusTime","params":[]}' Current shape: { "consensusTimeNs": "1785196016508998403", "timeQuality": 7697, "convergenceState": "Converged", "peerCount": 5, "consensusOffsetNs": "-1062154" } Treat the value as authoritative for your use only when convergenceState == "Converged" and your policy accepts the quality and peer count. timeQuality uses 0..10,000, where 10,000 is 100%. Query a transaction Both a Substrate extrinsic hash and an Ethereum transaction hash are accepted: curl --fail --silent --show-error https://rpc.roko.network \ -H 'content-type: application/json' \ --data '{ "jsonrpc":"2.0", "id":1, "method":"temporal_getTransactionTimestamp", "params":["<32_BYTE_TRANSACTION_HASH>"] }' The result is a decimal nanosecond string or null when unknown. For finality-aware processing: subscribe to or poll finalized heads; resolve the finalized block number/hash; call temporal_getBlockTransactionTimestamps ; correlate substrateHash or ethHash ; store timestampNs as a decimal string or arbitrary-precision integer. Precision rules Unix nanoseconds are already larger than JavaScript's Number.MAX_SAFE_INTEGER . const ns = BigInt(response.result.consensusTimeNs); const seconds = ns / 1_000_000_000n; const subsecondNs = ns % 1_000_000_000n; Never call Number() on a full nanosecond value. Convert only a bounded display unit after checking its range. JSON.stringify also rejects BigInt , so serialize nanoseconds back to decimal strings. Python's int preserves these values: ns = int(result["consensusTimeNs"]) seconds, subsecond_ns = divmod(ns, 1_000_000_000) Current wire-format caveat Most current temporal RPC nanosecond fields are quoted decimal strings. The legacy temporal_getWatermarkInfo and temporal_getBlockMetadata responses can still contain unquoted JSON integers larger than JavaScript's safe range. Native JSON.parse() can round those values before application code sees them. Until those RPCs emit strings consistently, use a lossless/BigInt JSON parser or query them from a language such as Python with arbitrary-precision JSON integers. Useful methods Method Use temporal_getConsensusTime current mesh estimate and quality temporal_getMeshState convergence and per-peer measurement summary temporal_getWatermarkInfo current transaction watermark temporal_getTransactionTimestamp canonical timestamp by transaction hash temporal_getBlockMetadata temporal metadata for a block number temporal_getBlockTransactionTimestamps hashes and timestamps by extrinsic index temporal_getQueueStats local fee-priority queue statistics temporal_getTransactionWaitTime local queue timing for one transaction temporal_getRecentWaitTimes recent local wait-time samples Queue statistics are node-local and can reset on restart. Historical data may require an archive node. Examples See examples/temporal-rpc : Node.js reads string-encoded nanoseconds as BigInt ; Python preserves all JSON integer precision and polls finalized temporal block metadata. Failure handling null means “not available/known,” not timestamp zero. Reject malformed or non-32-byte transaction hashes. Apply an HTTP timeout and exponential backoff. Use finalized heads when reorganization would be harmful. Degrade gracefully when the mesh is initializing, converging, degraded, or below your minimum peer/quality policy. Verify chain genesis and EVM chain ID before trusting an endpoint.

---

# Temporal EVM Precompile

Read committed ROKO nanosecond timestamps from Solidity.

Read ROKO time from Solidity Runtime spec 285 introduced committed temporal state at the native EVM precompile below. It remains available in the active configured-testnet runtime spec 286: 0x0000000000000000000000000000000000000600 // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; interface ITemporal { function getConsensusTime() external view returns (uint128); function getMyTimestamp() external view returns (uint128); function getTransactionTimestamp(bytes32 substrateHash) external view returns (uint128); function getWatermark() external view returns (uint128); function getBlockTimestamp(uint64 blockNumber) external view returns (uint128); } Use getMyTimestamp() for the canonical timestamp of the currently executing transaction. It returns zero when that extrinsic has no temporal timestamp. getTransactionTimestamp(bytes32) is deliberately limited to the executing block's transient bundle and uses the Substrate extrinsic hash. Historical transaction lookup remains available through Temporal RPC rather than permanent consensus storage. getConsensusTime() is committed block metadata, not a live node clock. getWatermark() describes included state and does not independently assert GRANDPA finality. Applications requiring irreversibility must wait for the containing block to finalize. Call Selector getConsensusTime() 0x3937a0db getMyTimestamp() 0x8726a64f getTransactionTimestamp(bytes32) 0x2fbff520 getWatermark() 0xb819dedd getBlockTimestamp(uint64) 0x931672b8 Calls are read-only, reject msg.value , and return each timestamp as one 32-byte ABI word. Decode nanoseconds as JavaScript bigint , not number . Download the machine-readable ITemporal.json from this site or from the immutable v1.0.22 release directory and verify it against that release's SHA256SUMS .