Developer reference / Public REST API

Ravelnonce testnet 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.

Node and mining reads

GET

/api/node/state

Returns chain ID, node mode, active tip, issued atoms, and pending mempool count.

GET

/api/node/template?address={address}

Returns the expected next header, minimum timestamp, height-based subsidy, coinbase for the supplied miner address, and selected valid mempool transactions.

Node state response shape
{
  "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
}

Signed transaction and block submissions

POST

/api/node/transactions

Accepts one regular transaction after input lookup, address/key matching, Ed25519 signature verification, value checks, and pending outpoint reservation.

POST

/api/node/blocks

Accepts a candidate block only after header, target, proof of work, timestamp, merkle, coinbase, transaction, and UTXO checks.

Regular transaction JSON shape
{
  "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>" }]
}
Stable mutation error shape
{
  "error": "An input is already reserved by a pending transaction.",
  "code": "double_spend"
}

Explorer and status reads

GET

/api/explorer

Returns the latest 20 stored blocks and transactions, including the configured genesis block.

GET

/api/explorer/blocks/{hash}

Looks up a block by its 64-character lowercase header hash; an unknown valid hash returns HTTP 404.

GET

/api/explorer/transactions/{txid}

Looks up a pending or confirmed signed transaction by its 64-character lowercase ID.

GET

/api/explorer/addresses/{address}

Returns confirmed spendable UTXOs, balance atoms, and recent transactions for a checksummed testnet address.

GET

/api/status

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

/api/node/peers

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

/api/node/peers/handshake

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

/api/node/peers/tip

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

/api/node/peers/blocks?origin={origin}&height={height}

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

/api/node/peers/blocks

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.

Authenticated peer handshake request body
{
  "protocolVersion": "ravelnonce-peer-v1",
  "chainId": "ravelnonce-testnet-v1",
  "origin": "https://node-one.example",
  "knownPeers": ["https://node-two.example"]
}
Authenticated peer tip announcement body
{
  "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.

Availability and operating limits

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.