Reference / Mining
Run the Ravelnonce testnet node
Each deployment runs an independent hosted HTTP node with a local CPU mining demo. Configured nodes can discover one another and verify authenticated HTTPS handshakes. After an authenticated peer announces a higher tip, nodes request and validate the missing canonical block ranges in batches of up to eight. Transactions are not relayed. This is not a production mainnet, audited implementation, or wallet for real funds.
Requirements and startup
- Node.js 20.18.1 or newer and npm.
- A disposable PostgreSQL database reachable through
DATABASE_URL. NEXT_PUBLIC_APP_URL=http://localhost:3000for local development. These values belong in your local environment, never in committed files.
# Use a disposable PostgreSQL database. Never point this demo at production data.
export DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DISPOSABLE_DB?sslmode=require'
export NEXT_PUBLIC_APP_URL='http://localhost:3000'
export SEO_INDEXABLE='true'
npx prisma db push
npm run devThe first node request configures the deterministic height-0 genesis block. The existing auth and faucet models are preserved by this additive schema change. No hand-written database migration is used.
Mine and submit a complete example
The CLI creates ephemeral Ed25519 keys in memory, asks for a block template, mines within the testnet target, submits the reward block, signs and submits a spend, then mines that transaction into the next block. It also attempts a competing spend, an invalid signature, and a block with the wrong target. It prints public IDs and balances only; private key material is neither printed nor saved.
# In a second terminal, from this repository:
npm run test -- tests/unit/ravelnonce-consensus.test.ts tests/unit/ravelnonce-peer-sync-integration.test.ts
node scripts/ravelnonce-testnet.mjs demo --base-url http://localhost:3000
npm run test
BASE_URL=http://localhost:3000 npm run test:e2e
npm run lint
SKIP_ENV_VALIDATION=1 npm run build
npm run typecheckThe CLI demo mutates the node by design. Run it only against a disposable database. It may add two valid blocks to a node that already contains testnet history.
Miner hardware assumptions
The local CPU proof-of-work demo needs the documented Node.js 20.18.1 or newer and npm, plus access to a disposable PostgreSQL database. The repository specifies no minimum CPU core count or memory amount, no GPU or ASIC requirement, and no hashrate or target performance. This example makes no performance guarantee; proof-of-work speed depends on the machine running it.
Verified miner connection: the HTTP API
The checked-in demo requests a block template with GET /api/node/template?address={address} and submits its mined block with POST /api/node/blocks. These are the app's implemented HTTP routes. The protocol guide documents the testnet consensus details, and the API reference describes the request contracts.
GET /api/node/template?address={address}
POST /api/node/blocksIllustrative only: generic Stratum-style pool fields
url = "stratum+tcp://pool.invalid:PORT_PLACEHOLDER"
wallet = "YOUR_TESTNET_ADDRESS_PLACEHOLDER"
worker = "WORKER_NAME_PLACEHOLDER"
password = "PASSWORD_PLACEHOLDER"The reserved .invalid host and every placeholder value are illustrative. Use the verified HTTP routes above for this app; a real pool example would require settings supplied by an actual pool operator.
What the node demonstrates
- Confirmed UTXO reads, Ed25519 transaction signatures, pending input reservations, and atomic block acceptance.
- SHA-256d transaction and block identifiers, ordered merkle roots, bounded proof of work, subsidy and fee validation.
- Explorer records and status readings from the same persisted chain state.
- Stable HTTP 400 validation/consensus errors, HTTP 409 conflicts, HTTP 413 request size limits, and generic HTTP 500 errors.
See the testnet protocol rules for byte layouts and consensus choices, or the REST API reference for requests. The explorer and status page expose only this node's append-only history.
Configure testnet peers
For each separately deployed node, set NEXT_PUBLIC_APP_URL to that node's public HTTPS origin and set RAVELNONCE_PEER_SEEDS to one or more comma-separated HTTPS origins. This app uses a managed RAVELNONCE_PEER_SHARED_SECRET; configure the same secret on every participating node deployment and preserve it across redeploys. Keep it server-side; it is sent only in the authenticated handshake header.
export NEXT_PUBLIC_APP_URL='https://node-one.example'
export RAVELNONCE_PEER_SEEDS='https://node-two.example'
# Inject the existing managed RAVELNONCE_PEER_SHARED_SECRET as a server-side secret.Configure the same seed list and managed secret on the other nodes, then open /status and select “Check peer connections.” The status view reports connected peers after a successful handshake and retains the last success time when a later attempt fails. Automated checks are scheduled every 15 minutes; manual checks have a 60-second cooldown. A handshake verifies compatible peer protocol and chain identity only. A recently handshaken peer can submit up to eight blocks at a time to /api/node/peers/blocks; blocks and transactions are validated and committed together in height order. A higher tip announcement also prompts the receiving node to request and validate missing ranges. Nodes do not relay transactions.
Testnet limitations
Peer discovery and authenticated HTTPS handshakes are available when seed origins and the shared secret are configured. Authenticated peers can submit bounded block batches and higher-tip announcements trigger bounded catch-up. There is no transaction relay, side-branch storage, fork choice, or reorganization. The timestamp rule has no future-time check. Browser key generation, key backup/recovery, scripts, and multisig are not supported. The existing faucet only records pending requests and does not deliver funds. These choices do not establish a production mainnet protocol.