GET
/api/node/state
Returns chain ID, node mode, active tip, issued atoms, and pending mempool count.
Developer reference / Public REST API
The public HTTP interface for one hosted, append-only testnet node. Read endpoints expose that node's persisted state; signed submissions are validated before atomic database writes.
GET
Returns chain ID, node mode, active tip, issued atoms, and pending mempool count.
GET
Returns the expected next header, minimum timestamp, height-based subsidy, coinbase for the supplied miner address, and selected valid mempool transactions.
{
"chainId": "ravelnonce-testnet-v1",
"mode": "single-hosted-testnet",
"tip": { "height": 0, "hash": "<64 lowercase hex>", "timestamp": 0, "target": "<64 lowercase hex>" },
"issuedAtoms": "0",
"mempoolCount": 0
}POST
Accepts one regular transaction after input lookup, address/key matching, Ed25519 signature verification, value checks, and pending outpoint reservation.
POST
Accepts a candidate block only after header, target, proof of work, timestamp, merkle, coinbase, transaction, and UTXO checks.
{
"type": 1,
"version": 1,
"chainId": "ravelnonce-testnet-v1",
"inputs": [{ "txid": "<64 lowercase hex>", "outputIndex": 0, "publicKey": "<64 lowercase hex>", "signature": "<128 lowercase hex>" }],
"outputs": [{ "amountAtoms": "1250000000", "address": "<79-character rvtest1 address>" }]
}{
"error": "An input is already reserved by a pending transaction.",
"code": "double_spend"
}GET
Returns the latest 20 stored blocks and transactions, including the configured genesis block.
GET
Looks up a block by its 64-character lowercase header hash; an unknown valid hash returns HTTP 404.
GET
Looks up a pending or confirmed signed transaction by its 64-character lowercase ID.
GET
Returns confirmed spendable UTXOs, balance atoms, and recent transactions for a checksummed testnet address.
GET
Returns current values from this node's persisted tip and the testnet fee rule. Peer handshake status is available from /api/node/peers.
GET / POST
GET returns peer origins, connection freshness, safe last-error codes, and each peer's latest announced remote tip. POST attempts a bounded, rate-limited check of configured and discovered peers.
POST
Accepts a bounded ravelnonce-peer-v1 handshake authenticated by the shared peer secret in the Authorization: Bearer header. It records peer metadata and returns known HTTPS origins only; it accepts no transactions or blocks.
POST
Accepts an authenticated, at-most-4-KiB tip announcement from a compatible peer, stores the announced peer metadata, then requests any missing canonical ranges through the bounded block GET endpoint. Each received batch is validated atomically; the announcement itself is never trusted as a block.
GET
Serves one canonical block by height, or an inclusive range with startHeight and endHeight, to an authenticated peer with a recent compatible handshake. Requests are limited to eight blocks and fail without partial data when any requested height is outside the canonical chain.
POST
Accepts an authenticated batch of 1–8 blocks from a recently handshaken peer (body limit 16 MiB). It validates each block and its transactions in height order in one database transaction; any invalid or out-of-order block rejects the whole batch. A 201 response is returned only after commit.
{
"protocolVersion": "ravelnonce-peer-v1",
"chainId": "ravelnonce-testnet-v1",
"origin": "https://node-one.example",
"knownPeers": ["https://node-two.example"]
}{
"protocolVersion": "ravelnonce-peer-v1",
"chainId": "ravelnonce-testnet-v1",
"origin": "https://node-one.example",
"height": 12,
"hash": "<64 lowercase hexadecimal characters>"
}Send the shared secret as Authorization: Bearer …; it is never returned by either endpoint. Configure the public HTTPS origin in NEXT_PUBLIC_APP_URL, bootstrap origins in RAVELNONCE_PEER_SEEDS, and the same server-only RAVELNONCE_PEER_SHARED_SECRET on each node. See the node guide for setup details. Connected nodes exchange their persisted validated tip on handshake and after local block acceptance. The `/api/node/peers` response includes this as nullable `remoteTip` metadata with a local receipt time. An announcement alone is not proof of a remote block and does not change this node's ledger. A connected peer can request a bounded range of this node's validated canonical blocks with the GET endpoint, then submit blocks through the authenticated batch endpoint above.
Successful read responses include Cache-Control: no-store. The browser UI validates all responses through the shared Zod contracts before rendering them.
Each deployment has its own PostgreSQL state. Authenticated peers can submit bounded contiguous block batches. When a peer announces a higher tip, the node pulls the missing canonical range in batches of up to eight and validates each batch before commit. Nodes do not relay transactions, store side branches, choose forks, or reorganize. The public faucet remains a pending-request recorder; it does not create or send funds.
For complete byte layouts, issuance vectors, transaction rules, and target calculation, read the testnet protocol page. To run a local server and signed demo, follow the node guide.