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:

1. subscribe to or poll finalized heads;
2. resolve the finalized block number/hash;
3. call temporal_getBlockTransactionTimestamps;
4. correlate substrateHash or ethHash;
5. 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.