RougeChain Documentation

Welcome to RougeChain — a post-quantum secure Layer 1 blockchain built with real NIST-approved cryptography.

Current Status

RougeChain is post-quantum-secured at the L1 level. The current production XRGE bridge remains on the hardened R1 architecture, which still relies on classical authorization on the Base side. A V3 XRGE bridge using ML-DSA-65 post-quantum authorization has been built and rehearsed; it is not deployed and awaits an external audit. Details: Status & Roadmap · Security Overview.

What is RougeChain?

RougeChain is among the first blockchains designed from the ground up to be resistant to quantum computer attacks. It uses:

• ML-DSA-65 (CRYSTALS-Dilithium) for digital signatures
• ML-KEM-768 (CRYSTALS-Kyber) for key encapsulation
• SHA-256 for hashing

All cryptographic primitives are NIST FIPS 204/203 compliant.

Key Features

Quick Links

• Status & Roadmap
• Security Overview
• Getting Started
• Running a Node
• API Reference
• P2P Networking
• Staking & Validators
• Browser Extensions
• CLI Wallet
• SDK
• Architecture
• GitHub (Node Source)

Network Info

Mainnet is live (chain-id rougechain-mainnet-1) alongside the public testnet.

A local node's default --api-port is 5101.

Tokens

XRGE

XRGE is the native token that powers transactions, secures the network through staking, and fuels the post-quantum economy.

XRGE on Base: ERC-20 at 0x147120faEC9277ec02d957584CFCD92B56A24317 (Base mainnet, chain id 8453). XRGE trades on Base DEXs (for example Aerodrome), so it can be swapped from any Base-compatible wallet, including Coinbase Wallet / the Base app. Always verify the contract address above. XRGE bought on Base is an ERC-20 until you move it to RougeChain through the XRGE Bridge.

The XRGE bridge in production is the hardened R1 bridge (BridgeVaultV2), with classical authorization on the Base side. The post-quantum V3 XRGE bridge is built but not activated.

qETH

qETH is a bridged representation of ETH on RougeChain. It uses 6 decimal places and can be bridged in from Base mainnet or withdrawn back.

qUSDC

qUSDC is a bridged representation of USDC (Base mainnet) on RougeChain, using the same RougeBridge contract. See USDC Bridge.

qETH and qUSDC use classical Base-side authorization and are outside the scope of the V3 post-quantum XRGE bridge.

Fees

EIP-1559 Fee Model: The base fee adjusts ±12.5% per block based on transaction volume (target: 10 txs/block), floor 0.001 XRGE (where mainnet has sat since September 2026). 50% of the base fee is burned; the remaining tip pool is split proposer 20% / validators 70% (stake-weighted) / treasury 10%. The 0.1 XRGE minimum-tip floor in the code draws from a reserve that is empty on mainnet, so it pays nothing. Check current fees via GET /api/fee.

Burn Address

Tokens can be permanently burned by sending to the official burn address:

XRGE_BURN_0x000000000000000000000000000000000000000000000000000000000000DEAD

Burned tokens are tracked on-chain and can be queried via the /api/burned endpoint.

Security

Client-Side Signing

RougeChain uses a secure v2 API where all transactions are signed client-side:

1. Your wallet creates a transaction payload
2. The payload is signed locally using ML-DSA-65
3. Only the signature and public key are sent to the server
4. Your private key never leaves your browser

This ensures maximum security even when interacting with untrusted nodes.

Status & Roadmap

This page is the single source of truth for what is live versus what is built but not activated. If another page disagrees with this one, this page wins — please open an issue.

Last reviewed: 2026-10-16 (mainnet height 261).

RougeChain is post-quantum-secured at the L1 level. The current production XRGE bridge remains on the hardened R1 architecture. A V3 XRGE bridge using ML-DSA-65 post-quantum authorization has been built and rehearsed; it is not deployed and awaits an external audit.

⚠️ Current node release: 1.6.8 (blocks 235, 245 and 260 have passed)

Mainnet activated mintable tokens and contract royalty reads at block 235, the monetary-integrity rule at block 245 (2026-10-05) and AMM_INTEGRITY at block 260 (2026-10-10). Every mainnet node must run release 1.6.7 or later to follow the chain (release 1.6.7). Release 1.6.8 (2026-10-15) fixes a bug that could stop a node producing and importing blocks while processing certain public NFT mints. It is not a consensus change, is recommended for every node, and is what the operator nodes run (release notes). Nodes installed with the one-line installer update themselves. The full schedule is in Upgrade schedule.

Suspended since block 245

The monetary-integrity rule makes a block invalid if it carries one of these transaction types: shield, shielded_transfer, unshield, token_lock, token_unlock, create_staking_pool, token_stake, token_unstake, create_proposal, cast_vote, execute_proposal, delegate, undelegate, token_approve, token_transfer_from. The features behind them — shielded transfers, token locking, token staking pools, on-chain governance and voting, vote delegation — are therefore not available, however an older page or client describes them.

• Why. Their ledger effects were applied without the state checks they depend on. The V1 shielded pool's proof established value balance only and did not bind a withdrawal to a specific note, and its prover has no zero-knowledge mode, so it did not deliver privacy. The other types were never used on mainnet. The mainnet shielded pool was empty when it was suspended; no funds are affected.
• What replaces them. A redesigned shielded pool (V2) is specified and in development: a Plonky3-based STARK with a hiding mode (proofs of about 190 KB, verify about 6 ms, prove about 3 s on a phone), launching under a 1,000,000 XRGE pool cap before the external audit. It is not audited, and nothing may claim audited privacy until it is. The other types are being rebuilt with their checks in consensus; no activation height exists. Token allowances are unaffected (approve / transfer_from stay enabled). Treasury decisions for Regenerate use the node-hosted votes in the meantime.

Earlier mandatory node upgrade (block 49)

If you run a RougeChain mainnet node or validator, you must upgrade. On 2026-09-18 mainnet activated a protocol upgrade at block 49 (bridge security hardening and a fix to validator-stake accounting). The upgraded code is on the public repository: rougechain-node main.

A node running a build from before 2026-09-18 may show the correct block height, but it executes blocks with the old rules and ends up with incorrect balances and validator state. There is no partial fix: upgrade and resync. Stake is unaffected — an un-upgraded validator simply is not participating.

sudo systemctl stop rougechain-validator
cp -a ~/.quantum-vault/mainnet ~/.quantum-vault/mainnet.backup     # keep a backup
cd ~/rougechain && git pull --ff-only
source ~/.cargo/env && cd core && cargo build --release --locked -p quantum-vault-daemon
mv ~/.quantum-vault/mainnet ~/.quantum-vault/mainnet.old
mkdir -p ~/.quantum-vault/mainnet
cp ~/.quantum-vault/mainnet.backup/node-keys.json ~/.quantum-vault/mainnet/
sudo systemctl start rougechain-validator

Paths and the service name are those of a source-build install (repository in ~/rougechain, data in ~/.quantum-vault/mainnet); adjust them to your setup. A node installed with the current install-validator.sh runs a signed release binary instead (/usr/local/bin/quantum-vault-daemon, with the rougechain CLI from the same release in /usr/local/bin/rougechain; data in /var/lib/rougechain/mainnet) and is upgraded by re-running the installer, which verifies the release signature before installing anything — see Signed releases. node-keys.json is your validator identity — keep it and never share it. A fresh sync takes under a minute.

Verify you are on the canonical chain:

• block 49 has hash 4c7ec92d9fc4dd24146036474128072d07d146d5cde93a0d31c0462eea895abb (curl -s "localhost:5100/api/blocks?limit=100")
• state_root from curl -s localhost:5100/api/stats equals the one at https://api.rougechain.io/api/stats at the same height

Live today

The production XRGE bridge still relies on classical (ECDSA / Safe multisig) authorization on the Base side. It is hardened, capped and monitored, but it is not post-quantum on Base. The ETH/USDC contract is owned by a single operator hot key. No bridge component has been externally audited.

Validators and staking, as they run today

Built and tested — NOT activated

Consensus redesign — decided 2026-10-06, NOT built

A redesign of consensus was decided on 2026-10-06. Nothing of it is implemented or scheduled; it is gated on a consensus simulator and an independent review, and will ship as staged forks A–E whose heights will be announced in advance. It supersedes the earlier "Release 2b" and "Release 3" plans.

FINALITY_V2_ACTIVATION_HEIGHT is 150 (active). V3_BRIDGE_ACTIVATION_HEIGHT is None: no activation height has been chosen for the V3 bridge.

Scope of V3

• V3 changes the XRGE withdrawal authorization path on Base to ML-DSA-65.
• qETH and qUSDC are outside the V3 scope. They stay on RougeBridge with classical Base-side authorization.
• The Bitcoin bridge is a separate system and is not part of V3. See Bitcoin Bridge.

Roadmap

Activation will be announced in advance with the exact block heights. Until then, nothing on this page in the "not activated" table protects user funds.

Security Overview

An honest summary of what is post-quantum-secured today and what is not. For live/pending status see Status & Roadmap. Last reviewed: 2026-10-06.

RougeChain L1 — post-quantum-secured

• Accounts, transactions, validator block signatures and staking operations use ML-DSA-65 (FIPS 204). Messaging and mail use ML-KEM-768 (FIPS 203).
• Transactions are signed client-side; private keys do not leave the wallet.
• In the web wallet, setting a password (min 8 characters) is required to finish creating or importing a wallet, and keys are written to browser storage only encrypted (AES-256-GCM). A wallet an older version stored unencrypted must be secured with a password before it can be used again. See Create a Wallet.
• Messages and mail are encrypted to each participant's long-term ML-KEM-768 key. There is no forward secrecy: anyone who later obtains that key can decrypt the stored messages and mail it was used for, both received and sent.
• These algorithms are quantum-resistant under current cryptographic understanding. No system can promise more than that, and implementation bugs remain possible.
• Shielded transfers are not available. The V1 shielded pool is suspended since block 245: its STARK proof established value balance only, did not bind a withdrawal to a specific note, and its prover has no zero-knowledge mode, so it did not deliver privacy. The mainnet pool was empty. A redesigned pool (V2, Plonky3-based with a hiding mode, launching under a 1,000,000 XRGE cap) is in development and unaudited; nothing may claim audited privacy until an external audit covers it.
• Messenger and mail are node-hosted, not on-chain. Since node release 1.6.3 a directory entry can be replaced only by the signing key that owns it, an encryption key registered to another wallet is refused, and the unauthenticated legacy read routes return 410 Gone. Nodes before 1.6.3 do not enforce this.

Signatures commit to the network

Mainnet (rougechain-mainnet-1) and testnet (rougechain-devnet-1) accept the same keys, and the web wallet uses one key on both. From node release 1.6.4 and the wallet releases listed in the changelog, every payload a wallet signs for a node — transactions and signed requests (mail, messenger, names, votes) — carries the chain id of the network it is meant for (chainId; chain_id in a rougechain CLI envelope), inside the signed bytes. A signature therefore commits to one network.

• Node rule (release 1.6.4, no fork). A node refuses a signed payload that names another chain id (CHAIN_ID_MISMATCH), at the API, at mempool admission and when producing. A payload that names no network is still accepted while wallets update; operators turn on REQUIRE_SIGNED_CHAIN_ID to refuse those too (CHAIN_ID_REQUIRED).
• Wallets take the chain id from their network setting, compare it once per session with the node's GET /api/health → chain_id, and refuse to sign if the two differ. The extension and Qwalla show the network a request is for and refuse one for a network other than the selected one.
• Consensus rule (CHAIN_ID_BINDING, not scheduled). From an activation height to be announced, a block is invalid if any transaction's signed bytes do not commit to the chain id; node-signed transactions switch to a network-bound signing format at the same height. Until then consensus is unchanged. See the upgrade schedule.
• Sign-in messages already carry a Chain ID line; verifiers must check it (Wallet Authentication).
• Contracts that verify signatures themselves can read the chain id with host_get_chain_id from the CONTRACT_CHAIN_ID upgrade (not scheduled) — see Smart Contracts.

Bridges — mixed

So: assets held on RougeChain are protected by post-quantum signatures. The Base-side custody of bridged assets is not post-quantum today. The bridges are operator-run (deposit watcher, relayers and the bridge_mint key), the ETH/USDC contract is owned by a single hot key, and no bridge component has been externally audited. ETH/USDC deposits go through the contract's depositETH / depositERC20 and are claimed automatically; the manual claim route is closed at the public endpoint. Bitcoin deposits are live; Bitcoin withdrawals are switched off in the site.

What V3 will change (not activated)

The V3 XRGE bridge changes the XRGE authorization path on Base to on-chain-verified ML-DSA-65 signatures from an M-of-N authority. It has been built, frozen as an audit candidate and rehearsed, but is not deployed or activated, and it has not yet been externally audited.

• qETH and qUSDC remain outside the V3 post-quantum scope.
• The Bitcoin bridge is separate from the Base bridge architecture and from V3.

Finality

Verified BFT finality (FINALITY_V2) is live since block 150: every block carries a certificate of ML-DSA-65 precommits from more than two thirds of stake for its parent, and nodes reject blocks without one. Stake is still concentrated in few keys — three validators are staked and one holds more than 99.9 % of the stake, so its own vote is the quorum — which limits what any BFT guarantee means until the validator set broadens.

No slashing is active. Missed-block slashing is frozen since block 100, the legacy slash transaction is rejected since block 245, and evidence-based slashing does not exist yet. The 10,000 XRGE minimum stake is enforced by the node API, not by consensus.

Decentralization

Validator stake and bridge operation are currently concentrated in a small operator set. This is a known limitation and part of the roadmap: a consensus redesign (rotating proposers, a capped validator set, a consensus-enforced minimum stake, evidence-based slashing) was decided on 2026-10-06 and is not built; see Status & Roadmap.

Getting Started

This guide will help you get up and running with RougeChain in minutes.

Prerequisites

• A modern web browser (Chrome, Firefox, Edge, Safari)
• For running a node: Rust toolchain (1.80+)

Quickest Path

1. Visit rougechain.io
2. Click "Wallet" in the sidebar
3. Create (or import) a wallet and set a password when asked (required, min 8 chars) — your keys are encrypted at rest with AES-256-GCM (PBKDF2, 600k iterations) and are never stored unencrypted in the browser. Save a .pqcbackup as well (see Create a Wallet)
4. Use the faucet to get free testnet XRGE

That's it! You now have a quantum-secure wallet.

What's Next?

• Quick Start Guide - Detailed walkthrough
• Create a Wallet - Understanding your keys
• Get Test Tokens - Using the faucet
• Running a Node - Participate in the network

Quick Start

Get started with RougeChain in 5 minutes.

Step 1: Access the Web App

Visit rougechain.io or run locally:

git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node
npm install
npm run dev

Open http://localhost:5173 in your browser.

Step 2: Create Your Wallet

Create (or import) a wallet and set a password when asked (required, min 8 characters — the wallet is saved only once it's encrypted). It includes:

• Address (rouge1...) — Your compact Bech32m address, share freely
• Private Key (ML-DSA-65) — Never share this!
• Encryption Key (ML-KEM-768) — For secure messaging

On the web, your keys are encrypted at rest with AES-256-GCM (PBKDF2, 600k iterations): the password is required, and until you set it during create / import the wallet exists only in the tab's sessionStorage (it is never written to localStorage unencrypted). While unlocked, the decrypted wallet is kept in sessionStorage (cleared when the tab closes). In the browser extension, the decrypted key lives in chrome.storage.session and only the encrypted vault is persisted (legacy plaintext extension wallets are force-migrated to encrypted storage on next unlock). Your 24-word phrase restores your messaging/mail key only for wallets created or imported from the phrase on the website (since 2026-10-01) or in Qwalla; for older website wallets and extension wallets, export a .pqcbackup too (details).

Step 3: Get Test Tokens

1. Click Wallet in the sidebar
2. Click Request from Faucet
3. Receive 10,000 XRGE instantly (24-hour cooldown per address)

Step 4: Send Your First Transaction

1. Click Send
2. Enter recipient address
3. Enter amount
4. Click Send XRGE

Transaction is signed with your ML-DSA-65 key and broadcast to the network.

Step 5: View on Blockchain

1. Click Blockchain in sidebar
2. See your transaction in the latest block
3. Verify the PQC signature

What's Next?

• Run your own node
• Stake and become a validator
• Create custom tokens
• Use encrypted messenger
• Send encrypted mail
• Install the browser extension
• Use the SDK

Troubleshooting

"Failed to fetch" Error

• Check if you're connected to the right network (Testnet vs Devnet)
• Ensure the node is running if using local devnet

"Insufficient balance"

• Transaction requires amount + 1 XRGE fee
• Use faucet to get more tokens

Wallet not loading

• Clear browser cache (do not clear site data / localStorage unless you have your seed phrase and .pqcbackup — it deletes a wallet stored in the browser)
• Check browser console for errors

Create a Wallet

You explicitly create (or import) your RougeChain wallet, and onboarding then asks you to set a password (at least 8 characters). The password is required: on the web, the wallet is saved in your browser only once it's encrypted with it. Here's what you need to know about your wallet.

Wallet Components

Your Address

RougeChain uses compact Bech32m addresses with the rouge1 prefix, derived from your ML-DSA-65 public key:

address = bech32m("rouge", SHA-256(signing_public_key))

Example address:

rouge1q8f3x7k2m4n9pvj5dz6ywl2cg8hs0kw9...

Addresses are ~63 characters — much shorter than the raw 3,904-char hex public key. The wallet, extension, and explorer all display this format.

Note: Some API endpoints still require the raw hex public key (see Address Format). The rouge1 address is for display, sharing, and QR codes.

Backup Your Wallet

CRITICAL: Your private key is only stored locally. If you clear browser data or lose your device, you lose access to your funds.

Encrypted Backup (.pqcbackup)

All RougeChain wallets use password-protected encrypted backups. Plaintext key exports are disabled across all platforms.

How to Export

How to Restore

1. Go to Wallet page (or Settings in the extension)
2. Click Restore or Import Wallet
3. Select your .pqcbackup file
4. Enter the password you used when exporting
5. Your wallet keys are decrypted and restored

Seed Phrase (Mnemonic)

Wallets also support 24-word BIP-39 mnemonic backup (256-bit entropy for post-quantum security):

1. Go to Settings → Reveal Seed Phrase
2. Write down all 24 words in order
3. Store securely — anyone with your seed phrase has full access to your wallet

Important: The seed phrase restores your signing key and address (and so your funds). Wallets created or imported from the phrase on rougechain.io (since 2026-10-01) or in Qwalla also get a messaging/mail encryption key derived from the phrase, so the phrase alone restores it — the same key in both apps. Wallets created on the website before that change have a random encryption key that the phrase cannot restore: keep their .pqcbackup file, which contains both keys, to read earlier messages and mail. The browser extension still generates a random encryption key, so keep a .pqcbackup for extension wallets too.

.pqcbackup File Format

The encrypted backup file uses industry-standard cryptography:

File Structure

{
  "version": 1,
  "salt": "<hex-encoded 16-byte random salt>",
  "iv": "<hex-encoded 12-byte random IV>",
  "ciphertext": "<hex-encoded AES-256-GCM encrypted wallet data>",
  "algorithm": "PBKDF2-SHA256-AES-256-GCM"
}

How It Works

1. Your password is stretched with PBKDF2-SHA256 (600,000 rounds) using a random salt
2. The derived 256-bit key encrypts your wallet data with AES-256-GCM
3. The salt, IV, and ciphertext are bundled into a .pqcbackup JSON file
4. Without the correct password, the file cannot be decrypted

Warning: There is no password recovery. If you forget your backup password, you can restore your address and funds from your seed phrase; your old messages and mail come back too only if the wallet's encryption key is seed-derived (see above).

Security Best Practices

1. Never share your private key or seed phrase
2. Backup your wallet immediately after creation
3. Use a strong, unique password for your .pqcbackup file
4. Store backups in multiple locations (password manager, USB, etc.)
5. Never screenshot your seed phrase or keys
6. Verify addresses before sending

Technical Details

Key Generation

// 24-word mnemonic (256-bit entropy — post-quantum safe)
const mnemonic = bip39.generateMnemonic(256);

// Derive 32-byte seed via HKDF-SHA256
const seed = hkdf(sha256, mnemonicToSeed(mnemonic), undefined, "rougechain-ml-dsa-65-v1", 32);

// Signing keypair (ML-DSA-65 / FIPS 204)
const signingKeypair = ml_dsa65.keygen(seed);

// Encryption keypair (ML-KEM-768 / FIPS 203) — derived from the phrase, identical to Qwalla.
// (No phrase, e.g. a private-key import: the signing private key hex is used instead.)
const kemSeed = sha512(utf8(`${mnemonic || signingPrivateKeyHex}|rougee-gram|kem-v1`)); // 64 bytes
const encryptionKeypair = ml_kem768.keygen(kemSeed);
// Wallets created on the website before 2026-10-01 keep their original random key.

Key Storage

Once you set a password, keys are encrypted at rest with AES-256-GCM (PBKDF2, 600,000 iterations).

On the web, a new or imported wallet is held only in the tab's sessionStorage until you set its password; nothing is written to localStorage before that, so if you close the tab during the recovery-phrase or password step the wallet is not kept (restore it from the recovery phrase). Setting the password stores the encrypted blob in localStorage. While the wallet is unlocked, the decrypted wallet is kept in sessionStorage, which the browser clears when the tab closes. Keep a .pqcbackup as well.

Older versions of the site saved a wallet without a password to localStorage unencrypted. If you still have such a wallet, rougechain.io asks you to set a password before you can keep using it (you can back it up first); the wallet is then encrypted and the unencrypted copy is deleted.

Terminal EVM Wallet (tools/evm-cli)

For Base/EVM operations there's a companion terminal wallet, rougechain-evm (tools/evm-cli). It derives your Base account from the same 24-word mnemonic (read from the ROUGECHAIN_MNEMONIC env var) and supports new, address, balance, send-eth, and send-token.

Get Test Tokens

The faucet distributes free XRGE tokens for testing on testnet.

Using the Web UI

1. Go to the Wallet page
2. Click Request from Faucet
3. Receive 10,000 XRGE instantly

Using the API

curl -X POST https://testnet.rougechain.io/api/faucet \
  -H "Content-Type: application/json" \
  -d '{"recipientPublicKey": "your-hex-public-key-here"}'

The field is recipientPublicKey and must be a raw hex public key, not a rouge1… address. The faucet is OFF by default and must be explicitly enabled with --faucet-enabled (or QV_FAUCET_ENABLED=1) — it is for dev/testnet only, and mainnet must never set it. When disabled, requests return "Faucet is disabled on this network."

Response:

{
  "success": true,
  "txId": "abc123...",
  "tx": { "...": "the faucet transfer (TxV1)" },
  "error": null
}

The signed POST /api/v2/faucet endpoint (used by the SDK) instead returns { "success": true, "message": "Faucet: 10000 XRGE sent" }, without a transaction id.

Rate Limits

The cooldown is shared by POST /api/faucet and POST /api/v2/faucet (one claim per key per 24 hours, whichever endpoint is used) and starts only after a successful payout. There is no per-IP rate limit. A request is also rejected if the recipient already has a pending faucet transaction, or if their balance exceeds the faucet threshold.

Whitelisting

The whitelist gates faucet access — it does not grant a higher rate. When QV_FAUCET_WHITELIST is set, only the listed addresses may use the faucet (both /api/faucet and the signed /api/v2/faucet, which returns 403); everyone else is blocked. Leave it unset to allow any address (subject to the 24-hour cooldown).

# Start node with the faucet enabled and a whitelist
./quantum-vault-daemon --mine --faucet-enabled \
  --faucet-whitelist "pubkey1,pubkey2,pubkey3"

# Or via environment variables
export QV_FAUCET_ENABLED=1
export QV_FAUCET_WHITELIST="pubkey1,pubkey2"
./quantum-vault-daemon --mine

Troubleshooting

"Rate limited"

Each address can request once every 24 hours. Wait for the cooldown to elapse or use a different address.

"Faucet disabled"

The node may not have faucet enabled. Check node configuration.

Transaction not appearing

1. Check the block explorer for your tx
2. Verify you're on the correct network
3. Wait for the next block (1-2 seconds)

Running a Node

Run your own RougeChain node to sync the chain, validate transactions, serve an API to others, and — if you stake — produce blocks and earn rewards.

The node software is open source on GitHub.

Node Types

A single node can be all three at once.

Minimum System Requirements

RougeChain's node is deliberately lightweight — the Rust daemon is a single ~23 MB binary and the live mainnet validator holds a steady ~40 MB of RAM. The heaviest part is building it, not running it.

To run a node

The daemon itself uses tens of MB of RAM; the extra headroom is for the OS, chain-data growth, and serving concurrent API traffic.

To build from source

A clean release build takes roughly 2–5 minutes depending on cores. If you only want to run a node and not build it, you can also use the Docker image.

Quick Start

# Clone and enter the workspace
git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node/core

# Build the daemon (release)
cargo build --release -p quantum-vault-daemon

Join Mainnet

Mainnet requires the mainnet genesis file (shipped in the repo) and the mainnet chain-id:

./target/release/quantum-vault-daemon \
  --genesis daemon/genesis-mainnet.json \
  --chain-id rougechain-mainnet-1 \
  --api-port 5100 \
  --data-dir ~/.quantum-vault/mainnet \
  --peers "https://api.rougechain.io/api" \
  --node-name my-node

Add --mine if you intend to validate. Your node only proposes once its key is staked (≥ 10,000 XRGE) and it is the designated proposer, i.e. it holds the most stake — see Staking.

Join Testnet

Testnet uses default parameters (no genesis file needed):

./target/release/quantum-vault-daemon \
  --chain-id rougechain-devnet-1 \
  --api-port 5101 \
  --data-dir ~/.quantum-vault/testnet \
  --peers "https://testnet.rougechain.io/api" \
  --node-name my-testnet-node

Running a Public Node (for other people)

If you want your node to serve an API/RPC to users, wallets, or apps, run it as a public node. Do not expose the daemon port directly — put a TLS reverse proxy (nginx) in front and keep the daemon bound to localhost or firewalled.

Recommended operator setup:

1. Bind and advertise — run with the default --host 127.0.0.1 and --api-port 5100, and set --public-url https://your-domain/api so peers can reach you through the proxy. Peers use the same REST API; there is no separate P2P port.
2. Terminate TLS at nginx — proxy https://your-domain/api → http://127.0.0.1:5100. A full nginx example is in Running a Public Node.
3. API keys (private nodes only) — --api-keys "<key1>,<key2>" makes every route that is not exempt return 401 unless the request sends X-API-Key or Authorization: Bearer. This covers reads too (e.g. /api/blocks, balances) and the peer routes (/api/blocks/import, /api/peers/register, /api/tx/broadcast); peers never send a key, so a keyed node stops accepting pushed blocks and transactions. Exempt: /, /api/health, /api/stats, /api/v2/*, /api/bridge/*, /api/messenger/*, /api/mail/*, /api/names/*, /api/finality/*, the faucet and the bot. Signed routes check their own signatures.
4. Rate-limit — e.g. --rate-limit-read-per-minute 600 --rate-limit-write-per-minute 60. All limits default to 0 (unlimited); --rate-limit-per-minute is a deprecated alias for both when neither is set. Limits are keyed by the connecting IP, so behind a reverse proxy every client shares one bucket unless you pass --trust-proxy, which keys loopback (proxied) requests by X-Real-IP / the rightmost X-Forwarded-For entry.
5. Run under systemd — so it restarts on crash/reboot. Example unit and hardening in Public Node and Configuration.
6. Monitor — poll /api/health (liveness) and /api/stats (height, peers, mining) from your uptime checker.

Security note: legacy v1 write endpoints that accept a raw private key are development-only (enabled with --dev) and return 410 Gone in a normal build — never run a public node with --dev.

Verify It's Working

curl http://127.0.0.1:5100/api/health

Expected response (mainnet):

{
  "status": "ok",
  "chain_id": "rougechain-mainnet-1",
  "height": 12345
}

Check sync progress and peers:

curl http://127.0.0.1:5100/api/stats

Next Steps

• Installation — detailed setup, per-OS
• Configuration — every CLI flag and environment variable
• Running a Public Node — full nginx + systemd operator guide
• Mining — block production and validator selection
• Staking — the 10,000 XRGE minimum and rewards

Installation

System Requirements

The daemon is a single Rust binary with low overhead. A $5/month VPS (Hetzner CX22, DigitalOcean Basic Droplet, Vultr Cloud Compute) is more than enough for testnet.

Docker (Fastest)

Run a node with a single command — no Rust toolchain needed:

docker run -d \
  --name rougechain-node \
  -p 127.0.0.1:5100:8900 \
  -v qv-data:/data/rougechain \
  rougechain/node \
  --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 \
  --mine --peers https://testnet.rougechain.io/api

Arguments after the image name replace the image's default command, so keep --data-dir /data/rougechain (the image's volume) and --api-port 8900 (the port the image's health check probes). See Docker.

Verify it's running:

curl http://127.0.0.1:5100/api/health

docker-compose

For a persistent setup, create a .env file:

API_PORT=5100
QV_PEERS=https://api.rougechain.io/api

The compose file always uses the mainnet genesis (chain id rougechain-mainnet-1; there is no chain-id setting) and always passes --mine, so point QV_PEERS at mainnet peers. The API is published on 127.0.0.1:${API_PORT} only; set API_BIND=0.0.0.0 to expose it on every interface.

Then start:

git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node
docker compose up -d

View logs:

docker compose logs -f node

Build the image locally

git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node
docker build -t rougechain/node .

Build from Source

Install and build manually if you prefer not to use Docker.

Prerequisites

Linux / macOS

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install build dependencies (Ubuntu/Debian)
sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev

# Install build dependencies (macOS)
xcode-select --install

Windows

1. Install Rust
2. Install Visual Studio Build Tools
3. Ensure cargo is in your PATH

Compile

# Clone the repository
git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node/core

# Build release binary
cargo build --release -p quantum-vault-daemon

# Binary location
./target/release/quantum-vault-daemon --help

Verify Installation

./target/release/quantum-vault-daemon --version

Expected output:

quantum-vault-daemon 0.1.0

First Run

Option A: Connect to Testnet

./target/release/quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api"

Option B: Start Local Devnet

./target/release/quantum-vault-daemon --mine --api-port 5100

Verify Node is Running

curl http://127.0.0.1:5100/api/health

Expected response:

{"status":"ok","chain_id":"rougechain-devnet-1","height":0}

Directory Structure

After first run, data is stored at:

Updating

Bring your node up to the latest main with one command — it fetches, fast-forwards, rebuilds the release binary, restarts the service, and health-checks:

cd rougechain-node
./scripts/update-node.sh

It refuses to run on a dirty working tree and only fast-forwards, so it never clobbers local changes. Override the defaults with env vars if your setup differs (systemd unit name, port, etc.):

ROUGECHAIN_SERVICE=my-node ROUGECHAIN_API_PORT=5100 ./scripts/update-node.sh

cd rougechain-node
git pull --ff-only
cd core
cargo build --release -p quantum-vault-daemon
sudo systemctl restart rougechain   # your service name

Troubleshooting

"cargo not found"

source ~/.cargo/env
# or restart your terminal

"OpenSSL not found"

# Ubuntu/Debian
sudo apt install libssl-dev pkg-config

# Fedora/RHEL
sudo dnf install openssl-devel

# macOS
brew install openssl

"Address already in use"

Another process is using port 5100:

# Find and kill it
lsof -i :5100
kill -9 <PID>

# Or use a different port
./quantum-vault-daemon --api-port 5101

Build fails on Windows

Ensure you have Visual Studio Build Tools with C++ workload installed.

Environment Variables

Some CLI flags can also be set via environment variables (others, such as --host, --api-port, --data-dir, --chain-id, --mine and the --rate-limit-* flags, are CLI-only):

Common CLI-only flags:

Running a Node on Windows

A step-by-step guide for building and running a RougeChain node on Windows.

Prerequisites

1. Install Rust

Download and run the installer from rustup.rs. Use the default options.

After installation, open a new PowerShell window and verify:

cargo --version
rustc --version

2. Install Visual Studio Build Tools

Download Visual Studio Build Tools and install the "Desktop development with C++" workload.

This provides the MSVC compiler and Windows SDK needed to build native Rust projects.

3. Install Git (if needed)

Download from git-scm.com or install via winget:

winget install Git.Git

Build the Node

Open PowerShell and run:

git clone https://github.com/cyberdreadx/rougechain-node.git
cd rougechain-node\core
cargo build --release -p quantum-vault-daemon

The first build takes 5-10 minutes. The binary will be at:

target\release\quantum-vault-daemon.exe

Run the Node

Connect to Testnet

.\target\release\quantum-vault-daemon.exe --api-port 5100 --peers "https://testnet.rougechain.io/api"

Run a Mining Node

.\target\release\quantum-vault-daemon.exe --mine --api-port 5100 --peers "https://testnet.rougechain.io/api"

Name Your Node

.\target\release\quantum-vault-daemon.exe --api-port 5100 --node-name "MyWindowsNode" --peers "https://testnet.rougechain.io/api"

Verify It's Working

In a separate PowerShell window:

Invoke-RestMethod http://127.0.0.1:5100/api/health

Expected output:

{
  "status": "ok",
  "chain_id": "rougechain-devnet-1",
  "height": 123
}

Visit http://localhost:5100 in your browser to see the built-in node dashboard.

Run as a Background Service

Option A: Task Scheduler

1. Open Task Scheduler → Create Task
2. General: Name it "RougeChain Node", check "Run whether user is logged on or not"
3. Trigger: At startup
4. Action: Start a program
   • Program: C:\path\to\quantum-vault-daemon.exe
   • Arguments: --mine --api-port 5100 --peers "https://testnet.rougechain.io/api"
   • Start in: C:\path\to\rougechain-node\core
5. Settings: Check "Restart if task fails", set to every 1 minute

Option B: NSSM (Non-Sucking Service Manager)

# Install NSSM
winget install NSSM.NSSM

# Create the service
nssm install rougechain "C:\path\to\quantum-vault-daemon.exe"
nssm set rougechain AppParameters "--mine --api-port 5100 --peers ""https://testnet.rougechain.io/api"""
nssm set rougechain AppDirectory "C:\path\to\rougechain-node\core"

# Start
nssm start rougechain

Windows Firewall

If you want your node to be publicly accessible, don't open the daemon's API port directly: the daemon binds to 127.0.0.1 by default, and a public node should sit behind a TLS reverse proxy (see Public Node). Open only the proxy's HTTPS port:

# Allow inbound HTTPS to the reverse proxy
New-NetFirewallRule -DisplayName "RougeChain Node (HTTPS)" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow

Docker Alternative

If you prefer Docker, install Docker Desktop for Windows and run:

docker run -d --name rougechain-node -p 127.0.0.1:5100:8900 -v qv-data:/data/rougechain rougechain/node --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 --mine --peers https://testnet.rougechain.io/api

Troubleshooting

"cargo not found"

Close and reopen PowerShell. Rust adds itself to PATH but it takes a new session to pick up.

Build errors about MSVC

Make sure Visual Studio Build Tools is installed with the C++ desktop workload. Restart your terminal after installing.

"Access denied" or antivirus blocking

• Run PowerShell as Administrator
• Add an antivirus exclusion for the rougechain-node directory
• Windows Defender may flag the newly built binary — allow it through

Node doesn't respond

• Check Windows Firewall isn't blocking the port
• Make sure you're using http://127.0.0.1:5100 (not localhost, which may resolve to IPv6)

Updating

cd rougechain-node
git pull
cd core
cargo build --release -p quantum-vault-daemon
# Restart the node

Docker

Run a RougeChain node without installing Rust or any build dependencies.

Requirements

Any VPS or machine with Docker installed. Minimum specs:

• 1 vCPU, 1 GB RAM, 5 GB SSD, 10 Mbps
• Recommended: 2 vCPU, 1–2 GB RAM, 20 GB SSD
• A $5/month VPS is enough for testnet

Quick Start

docker run -d \
  --name rougechain-node \
  -p 127.0.0.1:5100:8900 \
  -v qv-data:/data/rougechain \
  rougechain/node \
  --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 \
  --mine --peers https://testnet.rougechain.io/api

Inside the container the node listens on port 8900 and stores data in /data/rougechain (the image's volume). Arguments after the image name replace the image's default command (--data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 --mine), so always repeat --data-dir, --host and --api-port as above; otherwise the node binds to 127.0.0.1:5101 inside the container (unreachable), writes outside the volume, and fails the image's health check (which probes 8900). Publishing on 127.0.0.1 keeps the API off the public internet; put a reverse proxy in front if peers need to reach you (see Public Node).

Your node will:

• Sync with the testnet
• Produce blocks (--mine) whenever it is the designated proposer
• Persist chain data to the qv-data Docker volume
• Serve the REST API on host port 5100

Verify:

curl http://127.0.0.1:5100/api/stats | python3 -m json.tool

docker-compose

For a persistent production setup, clone the repo and use docker-compose:

git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node

Optionally create a .env file to override defaults:

API_PORT=5100
QV_PEERS=https://api.rougechain.io/api
QV_CORS_ORIGINS=https://yourdapp.com,https://rougechain.io

The compose file always starts the node from the mainnet genesis (--genesis /etc/rougechain/genesis.json), which sets the chain id to rougechain-mainnet-1 (there is no chain-id setting), so point QV_PEERS at mainnet peers; for another network use docker run with your own flags (see Custom Configuration). It also always passes --mine. API_PORT is the host port mapped to the container's 8900, published on 127.0.0.1 only; set API_BIND=0.0.0.0 to expose it on every interface (prefer a reverse proxy, see Public Node). The optional Prometheus service (--profile monitoring) is likewise published on 127.0.0.1:9090. If QV_CORS_ORIGINS is unset (or *), the node uses its built-in origin list.

Start:

docker compose up -d

View logs:

docker compose logs -f node

Stop:

docker compose down

Building the Image

Build locally instead of pulling from the registry:

docker build -t rougechain/node .

The Dockerfile uses a multi-stage build:

1. Builder stage — compiles the Rust daemon in a full Rust image
2. Runtime stage — copies the daemon (rougechain-node) and the rougechain CLI, plus the genesis files, into a minimal Debian image

Data Persistence

Chain data is stored at /data/rougechain inside the container (when the node runs with --data-dir /data/rougechain, as the image's default command and the examples here do). Mount a volume there to keep it across restarts:

# Named volume (recommended)
-v qv-data:/data/rougechain

# Host directory
-v /srv/rougechain-data:/data/rougechain

Data includes:

• Block database
• Validator state
• Pool/DEX state
• NFT collections
• Node keys (node-keys.json)

Custom Configuration

Pass CLI flags after the image name:

docker run -d \
  -p 127.0.0.1:5100:8900 \
  -v qv-data:/data/rougechain \
  rougechain/node \
  --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 \
  --mine \
  --peers https://testnet.rougechain.io/api \
  --chain-id rougechain-devnet-1 \
  --block-time-ms 400

Set CORS origins via environment variable:

docker run -d \
  -p 127.0.0.1:5100:8900 \
  -v qv-data:/data/rougechain \
  -e QV_CORS_ORIGINS="https://yourdapp.com" \
  rougechain/node \
  --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 \
  --mine --peers https://testnet.rougechain.io/api

Becoming a Validator

Once your Docker node is running and synced:

1. Fund your node's own key (/data/rougechain/node-keys.json) with ≥ 10,000 XRGE plus the fee
2. Stake from that key with the bundled CLI, e.g. docker exec rougechain-node rougechain --node-keys /data/rougechain/node-keys.json stake 10000 (add --network testnet for testnet). Staking from a browser wallet stakes the wallet's key, not the node's, and the node then never counts as a validator. See Becoming a Validator
3. Your node then votes on blocks, and proposes whenever it is the designated proposer (the validator with the most stake)

Your node earns:

• 20% of priority tips when it is the designated proposer
• A share of 70% of priority tips in every block, weighted by your stake
• A minimum tip floor of 0.1 XRGE/block is guaranteed from staking reserves

Health Checks

# Node health
curl http://127.0.0.1:5100/api/health

# Network stats (peers, height, mining status)
curl http://127.0.0.1:5100/api/stats

# Validator list
curl http://127.0.0.1:5100/api/validators

Updating

cd rougechain-node
git pull
docker compose build
docker compose up -d

Or if using docker run:

docker build -t rougechain/node .
docker stop rougechain-node
docker rm rougechain-node
docker run -d --name rougechain-node -p 127.0.0.1:5100:8900 -v qv-data:/data/rougechain rougechain/node --data-dir /data/rougechain --host 0.0.0.0 --api-port 8900 --mine --peers https://testnet.rougechain.io/api

The qv-data volume persists across container rebuilds, so your chain data is preserved.

Configuration

All node configuration is done via command-line flags or environment variables.

CLI Options

Browser access (CORS)

By default a node only accepts browser requests from a built-in allowlist (localhost:5173, localhost:4173, and the official rougechain.io / rougee.app origins). A dApp served from any other origin will get a CORS error in the browser (curl is unaffected). To allow your own front-end:

# Allowlist specific origins:
export QV_CORS_ORIGINS="https://mydapp.example.com,http://localhost:3000"

# Or, for local development, allow any origin:
./quantum-vault-daemon --dev --api-port 5100

QV_CORS_ORIGINS takes an explicit comma-separated list — setting it to "*" does not produce a wildcard. To serve a true Access-Control-Allow-Origin: * publicly (as api.rougechain.io does), terminate at a reverse proxy (nginx) that strips the node's CORS header and emits * itself.

Examples

Local Development Node

./quantum-vault-daemon --mine --api-port 5100

Syncing Node (No Mining)

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api"

Public Mining Node

./quantum-vault-daemon \
  --mine \
  --api-port 5100 \
  --node-name "MyNode" \
  --peers "https://testnet.rougechain.io/api" \
  --public-url "https://mynode.example.com"

Keep the default --host 127.0.0.1 and serve --public-url through a reverse proxy with TLS (see Public Node). Once running, visit http://localhost:5100 in your browser to see the built-in node dashboard with live stats, peer list, and block height.

Multiple Peers

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://node1.example.com,https://node2.example.com,https://node3.example.com"

Custom Data Directory

./quantum-vault-daemon \
  --mine \
  --api-port 5100 \
  --data-dir "/var/lib/rougechain"

Environment Variables

You can also use environment variables:

export QV_PEERS="https://testnet.rougechain.io/api"
export QV_PUBLIC_URL="https://mynode.example.com"
export QV_NODE_NAME="MyNode"
export QV_API_KEYS="key1,key2,key3"

./quantum-vault-daemon --mine --api-port 5100

Data Directory Structure

~/.quantum-vault/core-node/
├── node-keys.json       # Node / validator identity keypair
├── chain-db/            # Blocks (sled)
├── validators-db/       # Validator state (sled)
├── messenger-db/        # Messenger data (sled)
├── finality-db/         # Finality certificates (sled)
├── …-db/                # Other sled trees (mail, pools, NFTs, tokens, nonces, …)
├── replay_guard.json    # Seen-signature replay guard
└── finality-signing-journal  # Vote anti-equivocation journal

All databases are sled trees. A legacy chain.jsonl is only read once, to migrate an old data directory into chain-db (it is then renamed to chain.jsonl.bak).

Running with Systemd (Linux)

Create /etc/systemd/system/rougechain.service:

[Unit]
Description=RougeChain Node
After=network.target

[Service]
Type=simple
User=rougechain
ExecStart=/opt/rougechain/quantum-vault-daemon --mine --api-port 5100 --node-name "MyNode" --public-url "https://mynode.example.com" --peers "https://testnet.rougechain.io/api"
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable rougechain
sudo systemctl start rougechain
sudo journalctl -u rougechain -f  # View logs

Mining (Block Production)

RougeChain uses Proof of Stake, so "mining" refers to block production by validators rather than proof-of-work mining.

Enable Mining

Start your node with the --mine flag:

./quantum-vault-daemon --mine --api-port 5100

This tells the node to try to seal a block whenever it has pending transactions. The miner checks the mempool every --block-time-ms (default 400 ms) and wakes early when a new transaction arrives. Empty blocks are never produced, so blocks only appear when there are transactions, and only the designated proposer seals them (see below).

Requirements

How Block Production Works

1. Proposer selection — Since mainnet height 100, each height has exactly one designated proposer: the eligible validator (stake > 0, not jailed) with the most stake, ties going to the lowest raw public-key bytes. It is deterministic (no randomness, no rotation, no fallback). Every other node refuses to seal, and peers reject blocks from any other proposer. (GET /api/selection reports the same designated proposer for the next height.)
2. Block assembly — The designated proposer collects pending transactions from the mempool. Since height 150 it first waits for the commit certificate of the previous block (precommits from validators holding ⅔ of the stake)
3. Signing — The block is signed with the validator's ML-DSA-65 key
4. Voting — Validators automatically submit prevote and precommit attestations for each block
5. Propagation — The signed block is broadcast to all peers via POST /api/blocks/import
6. Verification — Receiving nodes verify the signature and block validity before accepting

Block Timing

--block-time-ms is how often the miner checks for pending transactions, not a fixed block cadence: a new transaction wakes the miner immediately, and nothing is produced while the mempool is empty. So it is an upper bound on how long a pending transaction waits before the designated proposer tries to seal it. Mainnet nodes run with the default (the block_time_ms value in the genesis file is not used for timing).

# Check the mempool less often (every 5 seconds)
./quantum-vault-daemon --mine --block-time-ms 5000

Mining with Peers

To mine as part of the network (not solo):

./quantum-vault-daemon \
  --mine \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api" \
  --public-url "https://mynode.example.com"

The --public-url flag is important — it lets other nodes discover and sync from you.

Monitoring

Check your validator status:

curl https://testnet.rougechain.io/api/validators

Check blocks produced:

curl https://testnet.rougechain.io/api/blocks?limit=10

Rewards

Every staked, non-jailed validator earns a stake-weighted share of the fees in every block; the proposer also gets a 20% share. Fees are credited when the block is applied to state. See Staking Rewards for details.

Troubleshooting

Node not producing blocks

• Ensure --mine flag is set
• Verify you have enough XRGE staked (min 10,000)
• Check that your node is synced: curl http://127.0.0.1:5100/api/health
• Check whether you are the designated proposer: designated_proposer_next in curl http://127.0.0.1:5100/api/stats. If it is another key, the log line not the designated proposer … — not sealing is expected
• If the log says waiting for the commit certificate of block …, validators holding ⅔ of the stake have not yet voted for the tip

Blocks not propagating

• Ensure --public-url is set and accessible from the internet
• Check firewall rules for your API port
• Verify peer connections: curl http://127.0.0.1:5100/api/peers

Producing blocks but no rewards

• Confirm your staking transaction was included in a block
• Check validator status via the API

Signed releases

Node releases are published as a prebuilt quantum-vault-daemon binary and the rougechain CLI (Linux x86_64), described by a signed release manifest. The installer, the automatic updater and anyone verifying by hand check the same thing: the manifest's signatures, then each file's sha256 and size against the manifest.

Where releases are published

<network> is mainnet or testnet. GitHub release assets are at https://github.com/cyberdreadx/rougechain-node/releases/download/v<version>/<name> (GitHub answers with a redirect to the file). The manifest and its signatures are mirrored as files of the repository, not as release assets. A mirror cannot weaken anything: a file from any source is used only if the manifest's signature verifies and the file's sha256 matches the manifest.

The manifest (schema: 1)

{
  "schema": 1,
  "network": "mainnet",
  "chain_id": "rougechain-mainnet-1",
  "version": "1.6.0",
  "released": "2026-10-01",
  "source_commit": "03613ef",
  "public_commit": "e048bf1",
  "binary": {
    "name": "quantum-vault-daemon-mint-royalty-03613ef",
    "url": "https://api.rougechain.io/releases/quantum-vault-daemon-mint-royalty-03613ef",
    "mirrors": ["https://github.com/cyberdreadx/rougechain-node/releases/download/v1.6.0/quantum-vault-daemon-mint-royalty-03613ef"],
    "sha256": "673bf7b1a469b7f9937b17228faab1e81ae48fb2a90aa32b2fd1b7fcc9cc2984",
    "size": 28463856
  },
  "cli": { "name": "rougechain-03613ef", "url": "…", "mirrors": ["…"], "sha256": "…", "size": 0 },
  "genesis": { "name": "genesis-mainnet.json", "url": "…", "mirrors": ["…"], "sha256": "…", "size": 4460 },
  "installer": { "name": "install-validator-2.1.0-1a2b3c4d.sh", "url": "…", "mirrors": ["…"], "sha256": "…", "size": 0 },
  "mandatory": true,
  "upgrade_before_height": 235,
  "activations": [ { "name": "token_minting", "height": 235 }, { "name": "contract_nft_royalty", "height": 235 } ],
  "notes_url": "https://docs.rougechain.io/running-a-node/mandatory-upgrade-2026-10.html",
  "min_installer_version": "2.0.0"
}

The example is abridged (…).

All URLs are https://. Unknown fields are not allowed in schema 1; installer is the one optional field (an addition that old installers ignore, so the schema number did not change). The current manifests (release 1.6.11) list the full schedule in activations (mainnet: 49, 90, 100, 150, 150, 160, 170, 190, 235, 235, 245, 260; testnet also carries validator_retirement at 1240 and, from 1.6.11, shield_v2 at 1480) — see the upgrade schedule. The example above is the 1.6.0 manifest, kept because it shows upgrade_before_height and mandatory set; the 1.6.11 mainnet manifest has mandatory: false and upgrade_before_height: null (no mainnet rule changes), and the 1.6.11 testnet manifest has mandatory: true and upgrade_before_height: 1480 (SHIELD_V2 activates there).

Signatures

The signed object is the manifest file itself: both signatures are over its exact bytes (no canonicalisation — a manifest that is re-formatted no longer verifies).

A release must carry both, and the installer and updater refuse a manifest without a well-formed copy of each. They always verify the Ed25519 signature (stock OpenSSL 3.0 of Ubuntu 22.04/24.04/26.04 and Debian 12). They verify the ML-DSA-65 signature with the installed rougechain CLI — rougechain release verify, CLI ≥ 1.2.0 — whenever one is installed, and refuse the release if it does not verify; details in Automatic updates — trust model. The release tooling and CI check both, and OpenSSL 3.5 or newer can check ML-DSA-65 by hand.

Public keys: releases/keys/release-ed25519.pub.pem (PEM) and releases/keys/release-mldsa65.pub (hex of the raw 1952-byte key). The private keys are held offline by the release owner; they are not on the release server.

Verify a release by hand

NET=mainnet
BASE=https://api.rougechain.io/releases
KEYS=https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/releases/keys

curl -fsSLO $BASE/manifest-$NET.json
curl -fsSLO $BASE/manifest-$NET.json.ed25519.sig
curl -fsSLO $KEYS/release-ed25519.pub.pem

# 1. The key is the one you expect (compare with the fingerprint table above)
openssl pkey -pubin -in release-ed25519.pub.pem -outform DER | tail -c 32 | sha256sum

# 2. The manifest is signed by that key  →  "Signature Verified Successfully"
base64 -d manifest-$NET.json.ed25519.sig > manifest.sig.bin
openssl pkeyutl -verify -pubin -inkey release-ed25519.pub.pem -rawin \
  -in manifest-$NET.json -sigfile manifest.sig.bin

# 3. The files are the ones the manifest describes  →  "OK" and "size OK" for each
for f in binary cli; do                      # drop "cli" if the manifest has "cli": null
  name=$(jq -r .$f.name manifest-$NET.json)
  curl -fL -o "$name" "$(jq -r .$f.url manifest-$NET.json)"     # or one of .$f.mirrors[]
  echo "$(jq -r .$f.sha256 manifest-$NET.json)  $name" | sha256sum -c
  test "$(stat -c %s "$name")" = "$(jq -r .$f.size manifest-$NET.json)" && echo "size OK"
done

Get the public key from the Git repository (or from a copy you saved earlier), not from the same server that serves the manifest.

ML-DSA-65 signature — with the rougechain CLI (≥ 1.2.0; offline, no wallet or node needed):

curl -fsSLO $BASE/manifest-$NET.json.mldsa65.sig
curl -fsSLO $KEYS/release-mldsa65.pub
rougechain release verify --manifest manifest-$NET.json --sig manifest-$NET.json.mldsa65.sig --pubkey release-mldsa65.pub
# VERIFIED: ML-DSA-65 signature of manifest-mainnet.json (release key ac449798…)     exit 0
# exit 1 = the signature does not verify, exit 2 = a file is missing or malformed

The fingerprint it prints is the SHA-256 of the raw public key — compare it with the table above.

or with OpenSSL ≥ 3.5 (e.g. Debian 13):

curl -fsSLO $BASE/manifest-$NET.json.mldsa65.sig
curl -fsSLO $KEYS/release-mldsa65.pub
tr -d '\n' < release-mldsa65.pub | xxd -r -p | sha256sum              # fingerprint
# raw key → SubjectPublicKeyInfo (the hex prefix is the fixed ML-DSA-65 header)
{ printf '308207b2300b0609608648016503040312038207a100'; tr -d '\n' < release-mldsa65.pub; } | xxd -r -p > mldsa65.der
openssl pkey -pubin -inform DER -in mldsa65.der -out mldsa65.pem
base64 -d manifest-$NET.json.mldsa65.sig > manifest.mldsa.bin
openssl pkeyutl -verify -pubin -inkey mldsa65.pem -in manifest-$NET.json -sigfile manifest.mldsa.bin

or, on any machine with Node.js ≥ 20, both signatures and the binary in one step from a checkout of the repository:

cd scripts/release && npm ci
node verify-manifest.mjs --binary /path/to/the/binary --cli /path/to/rougechain ../../releases/manifest-mainnet.json   # exit 0 = VERIFIED

What the installer does

scripts/install-validator.sh (Ubuntu 22.04 / 24.04 / 26.04, Debian 12; x86_64; run as root):

1. downloads manifest-<network>.json, its .ed25519.sig and its .mldsa65.sig from every source (the primary and the mirror);
2. verifies each copy's Ed25519 signature with openssl against the release key embedded in the script — it never downloads a key — and, when a rougechain CLI with release verify is already installed, its ML-DSA-65 signature against the embedded ML-DSA-65 key. It uses the newest release that verifies (a stale mirror cannot hold a node back) and stops if no source provides one;
3. checks the manifest is for the requested network, and is not older than the release already installed (ALLOW_DOWNGRADE=1 overrides);
4. downloads the node binary, the rougechain CLI (when the manifest has one), the genesis file and the updater script (when the manifest names one) — primary URL, then mirrors, following redirects — and requires size and sha256 of each to match the signed manifest;
5. installs, as described below, and keeps the previous binaries as <file>.prev. If the ML-DSA-65 signature could not be checked in step 2 (no CLI yet), it is checked now with the CLI just installed, before the service is started; a release that fails is removed again;
6. sets up automatic updates: the updater, rougechain-update, a systemd timer and /etc/rougechain/<network>/update.conf (AUTO_UPDATE=0 to opt out).

It never overwrites node-keys.json or chain data. --dry-run performs steps 1–4 and changes nothing.

The service runs as the system user rougechain (no login shell). The data directory is 0700, node-keys.json is 0600, both owned by that user. The systemd unit lets the node write only to its data directory (ProtectSystem=strict, ReadWritePaths=<data dir>) and removes privileges (NoNewPrivileges, empty capability set, PrivateTmp, PrivateDevices, ProtectHome, ProtectKernel*, RestrictAddressFamilies, UMask=0077). --mine is added only with VALIDATOR=1. Extra QV_* settings go in /etc/rougechain/<network>/node.env; the unit file itself is rewritten on every run.

The CLI and the node key. node-keys.json can be read only by the rougechain user (and root), so run the CLI as that user:

sudo -u rougechain rougechain --node-keys /var/lib/rougechain/mainnet/node-keys.json whoami      # also: stake 10000, validator-status

Without sudo, as root: runuser -u rougechain -- rougechain …. On testnet the commands are rougechain-testnet --network testnet --node-keys /var/lib/rougechain/testnet/node-keys.json …. The CLI submits to the network's public node (https://api.rougechain.io, or https://testnet.rougechain.io with --network testnet) through the signed /api/v2 routes; see CLI Wallet.

Settings: NETWORK, NODE_NAME, PUBLIC_URL, VALIDATOR, DATA_DIR, API_PORT, P2P_PORT, HOST, PEERS, AUTO_UPDATE, NO_START, ALLOW_DOWNGRADE, REPLACE_LEGACY_UNIT, RELEASE_BASE_URLS — see the header of the script.

Upgrading

Automatic — by default the node upgrades itself: see Automatic updates (what it checks, how to make it notify-only, pin a version or turn it off, and what happens when an update fails). rougechain-update status shows where a node stands.

By hand — re-run the installer; this always works, with auto-update on or off. It verifies the new signed release, replaces the binary and the CLI, and restarts the service (with NO_START=1 it installs without restarting, so you can restart at a time you choose: systemctl restart rougechain-validator). Unlike the updater, a manual run does not health-check the node afterwards or roll back. To go back to the previous binary:

sudo systemctl stop rougechain-validator
sudo cp -p /usr/local/bin/quantum-vault-daemon.prev /usr/local/bin/quantum-vault-daemon
sudo systemctl start rougechain-validator

A node installed with installer 2.0.0 (before auto-update existed) has no updater: re-run the installer once to get it. Whether that run can install the updater depends on the release — see where the updater comes from.

Nodes installed from source

A node set up with the earlier source-build installer (repository in ~/rougechain, data in ~/.quantum-vault/mainnet, unit rougechain-validator running as your login user) is not changed silently: the installer stops when it finds a unit it did not write. To move such a node to signed releases, keep its whole data directory — it holds node-keys.json (your validator identity) and the vote journal:

sudo systemctl stop rougechain-validator
cp -a ~/.quantum-vault/mainnet ~/mainnet.backup-$(date +%Y%m%d)        # backup, incl. node-keys.json
sudo useradd --system --user-group --home-dir /var/lib/rougechain --no-create-home --shell /usr/sbin/nologin rougechain
sudo mkdir -p /var/lib/rougechain
sudo mv ~/.quantum-vault/mainnet /var/lib/rougechain/mainnet
sudo chown -R rougechain:rougechain /var/lib/rougechain
curl -sSL https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/scripts/install-validator.sh \
  | sudo REPLACE_LEGACY_UNIT=1 VALIDATOR=1 PUBLIC_URL=https://node.example.com bash

Use the VALIDATOR / PUBLIC_URL / NODE_NAME values your node ran with (VALIDATOR=1 only if it ran with --mine). The old unit is kept as rougechain-validator.service.legacy. With REPLACE_LEGACY_UNIT=1 the installer refuses to continue if there is no node-keys.json in the data directory, so an existing node never ends up with a new identity. Never run two nodes with the same node-keys.json.

For the release owner

The release procedure (build, make-manifest, sign on your own machine, verify, publish, sync) is in scripts/release/README.md.

Automatic updates

A node installed with install-validator.sh keeps itself up to date: a systemd timer looks for a newer signed release every hour, installs it, restarts the node, checks that it is healthy, and puts the previous release back if it is not.

• It installs only signed releases — a manifest signed by the release keys, and files whose sha256 matches that manifest. It never builds anything and never runs code from main.
• You stay in control: MODE=notify only tells you about a release, PIN_VERSION holds the node on one release, MODE=off (or AUTO_UPDATE=0 at install time) turns it off.

rougechain-update status                 # installed / newest release, last result, next check
sudo rougechain-update check             # look now; change nothing
sudo rougechain-update run --now         # install a newer release now (no waiting)
journalctl -t rougechain-update          # everything the updater did, and why

On testnet add --network testnet (timer rougechain-update-testnet.timer).

What is installed

The updater runs as root because it replaces files in /usr/local/bin and restarts the service. What it downloads is data to it: manifests and API answers are read with jq and every value is validated before use; nothing downloaded is executed before its sha256 has matched a signed manifest; the ML-DSA-65 verifier and the --version probe of a new binary run as the unprivileged rougechain user. Release sources must be https://.

Trust model

The trust anchor is the pair of release keys (Ed25519 and ML-DSA-65; fingerprints in Signed releases). Both public keys are embedded in the installer/updater script. The private keys are offline on the release owner's machine; the servers that host releases do not have them.

A release server or a mirror that is compromised can therefore withhold a release, but it cannot make a node install anything the release owner did not sign.

ML-DSA-65 on a node whose CLI cannot verify it yet. The CLI shipped with node 1.6.0 has no release verify. Such a node updates on the Ed25519 signature alone; as soon as the new release's CLI is in place — and before the node is restarted — the updater verifies the ML-DSA-65 signature with it and undoes the installation if it does not verify. That second check uses a program delivered by the release being checked, so it catches mistakes, not an attacker who can forge Ed25519. From the first release whose CLI has release verify, every later manifest is verified with a CLI that an earlier verified release installed, before anything is downloaded.

Where the updater comes from (bootstrap)

The updater is a root program that runs unattended, so the bytes that become it must have a known origin. There are exactly three cases:

1. The release names it. Releases from 1.6.1 on carry an installer entry in the signed manifest (name, URL, sha256, size). The installer downloads that file, checks the sha256, and installs it as the updater — whichever way the installer itself was started. This chains to the release keys.
2. The release does not name it (1.6.0), and you ran the installer from a file (sudo bash install-validator.sh). That file becomes the updater. It is trusted exactly as much as you already trusted it by running it as root — it is not covered by a release signature. rougechain-update status says so (from: installer file run by the operator). The first update to a release that names an updater replaces it with the signed one.
3. The release does not name it, and the installer was piped (curl … | sudo bash). A piped script cannot read its own bytes, and downloading "the installer" a second time could yield different bytes that nobody verified. No updater is installed; the installer says so and tells you what to do: re-run the same command once a release with a signed updater is out, or download the installer to a file and run that.

Nodes installed before auto-update existed (installer 2.0.0) have no updater either: re-run the installer once.

What a run does

1. Ask every source (api.rougechain.io/releases and the GitHub mirror, or RELEASE_BASE_URLS) for manifest-<network>.json and both signature files. Verify each copy.
2. Take the newest valid one. A source that is down, stale, or serving something that does not verify is reported and ignored. A release that is not newer than the installed one is ignored.
3. Decide (MODE, PIN_VERSION, releases that failed before, the delay window — below).
4. If the release names a newer updater: verify it, replace the updater, continue as the new one.
5. Download the binary and the CLI (primary URL, then mirrors) and check size + sha256. Nothing on the node has changed up to here; a failure is just retried at the next run.
6. On a validator: wait if it is about to propose a block (below).
7. Swap the files in. The previous binary and CLI stay as <file>.prev.
8. Restart the service — only if the node binary changed and the service was running.
9. Health check. If it fails: roll back.

The unit file, node-keys.json, chain data and node.env are never touched. A release that changes the genesis file is refused (that is a different chain; do it by hand).

When (timing)

rougechain-update run --now skips the delay. rougechain-update status shows a pending release and the time it is scheduled for.

Validators. If the node produces blocks (--mine), is the designated proposer of the next block (designated_proposer_next in /api/stats is its own key) and has pending transactions (rougechain_mempool_size in /metrics), it is about to produce a block. The updater waits — at most PROPOSER_DEFER_MAX_SECS (5 min), then restarts anyway — unless the upgrade height is near. A restart takes a few seconds; on a network with one designated proposer that is a few seconds without blocks.

The health check

After the restart the updater requires, using only the node's public API:

1. GET /api/health answers within HEALTH_START_TIMEOUT_SECS (2 min);
2. /api/health and /api/stats report the chain id of the release;
3. /api/stats → upgrade_schedule has every activation of the manifest at the manifest's height (the one exception is canonical_ledger_fork, which nodes do not report);
4. within HEALTH_DEADLINE_SECS (5 min) the node agrees with a reference node and is not behind it. Reference nodes are the node's own --peers plus REFERENCE_URLS.
   • Agrees: at the lower of the two tips, c = min(local height, reference height), both nodes have block c — its hash must be the same (GET /api/block/c). When both are at the same height, the state roots in /api/stats must be equal too. A difference has to be seen twice in a row to count.
   • Not behind: reference height − local height ≤ HEALTH_MAX_LAG_BLOCKS (2). A node that was still syncing before the update passes if it has advanced since.
   • An idle chain (RougeChain produces blocks only when there are transactions) needs nothing special: both nodes simply sit at the same height, and block and state root are compared there.

A reference node that cannot be reached is not a reason to roll back. If no reference could be compared with for the whole deadline, the node passes on checks 1–3 plus "its height did not go backwards", and the result is logged as UNVERIFIED against a reference node. A reference node that reports another chain id is ignored. If two references disagree with each other, agreeing with one of them is enough (and the disagreement is logged).

Rollback

When a check fails — or a file cannot be written, or the new binary does not even run (--version), or the ML-DSA-65 signature turns out not to verify — the updater:

1. puts the previous binary, CLI and install record back (the failed files are kept as <file>.failed);
2. restarts the service and waits for the API;
3. records the release as failed — it is not tried again at the next run (no restart loop); a newer release is tried;
4. exits non-zero and logs UPDATE FAILED / ROLLING BACK / ROLLBACK: lines with the reason.

After fixing the cause: sudo rougechain-update run --retry-failed. The systemd unit shows the failure (systemctl status rougechain-update), and rougechain-update status names the failed release and the reason.

A rollback restores programs, not data. If a release ever changes the on-disk format in a way the previous binary cannot read, its notes will say so.

Settings: /etc/rougechain/<network>/update.conf

Plain KEY=VALUE lines; the file is read, never executed. Written once by the installer — your changes survive re-runs and updates. Something the updater does not understand is reported, and the safe reading is used (a bad MODE or PIN_VERSION installs nothing).

rougechain-update status:

RougeChain auto-update — mainnet
  mode               auto   (/etc/rougechain/mainnet/update.conf)
  pinned version     none
  installed release  1.6.1
  latest seen        1.6.1
  last check         2026-10-02 12:17:03 UTC
  last result        up to date (1.6.1)
  last update        2026-10-02 09:17:41 UTC — 1.6.0 -> 1.6.1: healthy: agrees with https://api.rougechain.io/api (…)
  failed releases    none
  timer              rougechain-update.timer: enabled
  next check         Fri 2026-10-02 13:17:00 UTC
  updater            v2.1.0  (/usr/local/lib/rougechain/install-validator.sh; from: signed release 1.6.1)

Turning it off, pinning, removing

# notify only: releases are reported in the journal and in `status`, nothing is installed
sudo sed -i 's/^MODE=.*/MODE=notify/' /etc/rougechain/mainnet/update.conf

# off — either of
sudo sed -i 's/^MODE=.*/MODE=off/' /etc/rougechain/mainnet/update.conf
sudo systemctl disable --now rougechain-update.timer

# at install time (also on a re-run): AUTO_UPDATE=0 sets MODE=off and disables the timer
curl -sSL https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/scripts/install-validator.sh | sudo AUTO_UPDATE=0 bash

# back on
sudo sed -i 's/^MODE=.*/MODE=auto/' /etc/rougechain/mainnet/update.conf
sudo systemctl enable --now rougechain-update.timer

# remove the updater completely (the node keeps running; upgrade by re-running the installer
# with AUTO_UPDATE=0 — a re-run without it would set the timer up again unless update.conf says MODE=off)
sudo systemctl disable --now rougechain-update.timer
sudo sed -i 's/^MODE=.*/MODE=off/' /etc/rougechain/mainnet/update.conf
sudo rm -f /etc/systemd/system/rougechain-update.timer /etc/systemd/system/rougechain-update.service \
  /usr/local/bin/rougechain-update && sudo systemctl daemon-reload

Re-running the installer without AUTO_UPDATE keeps your update.conf as it is — an opt-out stays an opt-out. With auto-update off (or pinned) you are responsible for installing mandatory releases before their upgrade height.

At a mandatory upgrade (fork)

A mandatory release has "mandatory": true and an upgrade_before_height. Every node must run it before the chain reaches that height; a node that does not stops following the chain there.

• MODE=auto: the node installs it within about an hour of publication (the timer) plus at most 10 minutes, and immediately once the chain is within 10 blocks of the height.
• MODE=notify / PIN_VERSION / a release that failed on this node: the updater does not install it and repeats, at every run, that a mandatory release is waiting and at which height. Watch the journal, or rougechain-update status (latest seen … (mandatory, before block N)).
• If the update fails its health check before the upgrade height, the node goes back to the previous release and keeps working until that height — you have until then to find out why (journalctl -t rougechain-update).
• Whatever the mode, the check to make yourself before the height is the one in each upgrade note: /api/stats → upgrade_schedule shows the new activation.

Not covered

• Nodes built from source, Docker nodes and Windows nodes: upgrade them as before.
• Changes to the systemd unit or to installer settings (VALIDATOR, PUBLIC_URL, ports): re-run the installer.
• The old git-pull "auto-deploy" script is retired: it built and ran whatever was on main.

Network upgrade schedule

Each protocol upgrade turns on at a block height. Mainnet and testnet have separate schedules: testnet ran old software through mainnet's upgrade heights, so it upgrades at its own, later heights. The node picks the schedule from its chain id at startup, prints it in the log ([upgrades] …) and reports it in GET /api/stats as upgrade_schedule. Source: core/daemon/src/upgrades.rs.

Every height in this table has been reached on both networks, except the not scheduled rows and SHIELD_V2 on testnet (mainnet passed 260 on 2026-10-10; testnet passed 1440 on 2026-10-09). SHIELD_V2 activates on testnet at block 1480 (scheduled 2026-10-19): every testnet node must run release 1.6.11 or later before that block (1.6.10 carried the height but was never published). It is not scheduled on mainnet. The other next consensus changes — restoring the types suspended at 245 and the consensus redesign decided on 2026-10-06 — have no heights yet and will be announced in advance (see Status & Roadmap).

Testnet validator cleanup (block 1240, testnet only): 99% of testnet's stake sat on validator 4e094d21…, whose key nobody holds, so it could never sign finality votes. At block 1240 its stake is returned to its balance and set to zero, and the testnet node's own key (staked beforehand) becomes the largest validator. The finality validator replay starts from the validator set recorded at that block, because testnet's earliest blocks predate stored receipts. Proposer selection and finality turn on at 1250. None of this exists on mainnet (validator_retirement is None there).

Rules for changing the schedule

• Mainnet heights are history and never change; a unit test (mainnet_schedule_is_pinned) fails if they do.
• To schedule an upgrade on either network: set its height in upgrades.rs above the current tip, rebuild, install on every node of that network before the height, and update this page.
• Mainnet and testnet share one binary: a release carries both schedules, so installing it on the primary updates both services — each still follows its own schedule.

Runbook: activating TOKEN_MINTING (together with CONTRACT_NFT_ROYALTY)

Completed: testnet 1360, mainnet 235. Kept as the template for the next scheduled upgrade.

TOKEN_MINTING is a hard fork: from its height, create_token may carry token_mintable / token_max_supply, mint_tokens is applied under the new rules, and once a mintable token exists the header state root also commits the mint ledger. An old node drops the two new fields when it reads a block and applies mint_tokens under the old rules, so from the first mintable token or mint it computes a different state root and rejects the block. Every node must run the new binary before the height.

Corrected 2026-10-06: an earlier version of this page said an old node rejects such a block because it "computes a different block tx_hash". That was wrong: what an old node disagrees on is the state root.

CONTRACT_NFT_ROYALTY is planned for the same height. It is a smaller fork: from its height every contract call links host_nft_royalty_bps / host_nft_royalty_recipient, so a call to a contract that imports them succeeds where an old node fails it (an old node then rejects the block). From the same height an nft_create_collection whose royaltyBps is above 10000 (over 100%) or not an exact integer is invalid (refused by the API, mempool and producer; a block carrying one is rejected) — an old node would accept that block, so this too requires the new binary everywhere. No transaction or state-root format changes. Activating both at one height means one coordinated install. They are two independent schedule fields — set both to the same H.

1. Pick the height — well above the network's current tip (curl -s localhost:5100/api/stats → network_height), leaving time to install everywhere (testnet first, then mainnet).
2. Set it in core/daemon/src/upgrades.rs: token_minting: Some(H) and contract_nft_royalty: Some(H) in TESTNET (and later in MAINNET via node::TOKEN_MINTING_ACTIVATION_HEIGHT and node::CONTRACT_NFT_ROYALTY_ACTIVATION_HEIGHT). Update mainnet_schedule_is_pinned / testnet_schedule_is_pinned to the chosen values, and this page's table.
3. Test in a clean worktree (never in the live build dir): cargo test -p quantum-vault-daemon -j 2 — includes token_minting_tests, the nft_royalty / nft_marketplace tests in game_ready_tests and the mainnet history replays — cargo test -p quantum-vault-vm -j 2, and cargo check (the default members; --workspace is refused on purpose, see core/Cargo.toml — and so is --all-targets with the daemon selected, for build, check and clippy alike, which is also what an editor runs by default: it builds the test targets next to the plain binary, the daemon's test dependencies bring in the shielded pool's prover, and the daemon refuses to compile with it; use cargo test -p quantum-vault-daemon for the tests).
4. Build and install on every node of that network (primary, node #2, any outside validator) before H; restart each. Confirm the startup log line [upgrades] … token minting Some(H), contract NFT royalty Some(H) and GET /api/stats → upgrade_schedule.token_minting == H and upgrade_schedule.contract_nft_royalty == H on every node.
5. At/after H, verify:
   • every node reports the same state_root at the same height (/api/stats);
   • create a test token with "mintable": true, "max_supply": …, then GET /api/token/<SYM>/metadata shows mintable: true on every node;
   • mint once as the creator: balance and total_minted move by exactly the amount on every node;
   • a mint by another key, a mint above the cap and a mint of a non-mintable token are refused;
   • CONTRACT_NFT_ROYALTY: POST /api/v2/nft/collection/create with "royaltyBps": 10001 is refused (royaltyBps must be an integer between 0 and 10000); 10000 is accepted.
   • CONTRACT_NFT_ROYALTY: publish contracts/nft_marketplace/nft_marketplace.wasm (it can be published before H, but its calls only run from H). On a test collection with a royalty, list, escrow the NFT with nft_transfer, then buy with the exact price attached: the royalty recipient gains exactly floor(price × bps / 10000) quanta, the seller the rest, the buyer owns the NFT; a buy with the wrong amount fails and is refunded (only gas is charged);
   • roots still agree after those blocks.
6. Then enable the SDK / site UI for mintable / max_supply / mint, and tell marketplace developers the royalty host functions are live.

Rollback before H is just reinstalling the previous binary. After a mintable token exists (or a call to a contract importing the royalty functions is included), a node without the upgrade cannot follow the chain.

Upgrade notice: CHAIN_ID_BINDING and CONTRACT_CHAIN_ID (not scheduled)

What it is. From node release 1.6.4 every wallet signs the chain id into its payloads, and nodes refuse a payload that names another network (node rule, no fork). CHAIN_ID_BINDING makes the same property a consensus rule; CONTRACT_CHAIN_ID gives contracts host_get_chain_id. Both are hard forks with no height on any network (upgrade_schedule.chain_id_binding / .contract_chain_id are null).

The rule, from height H. A block is invalid if any transaction's signed bytes do not commit to this chain's id:

Below H nothing changes: blocks are accepted, executed and stored exactly as by release 1.6.3, and the network-bound V1 encoding is not accepted (an older node would refuse it). Nodes start signing their own V1 transactions in the network-bound encoding at H automatically.

What must ship first, in this order.

1. Node release 1.6.4 on every node of the network (node rule; harmless to older wallets).
2. Wallets that sign chainId: the site, @rougechain/sdk 1.15.0 (and every dApp built on it, after a dependency bump), browser extension 1.9.0, Qwalla 1.3.0, rougechain CLI 1.3.0, the MCP server. Watch the node log / API errors for payloads still arriving without the field.
3. Operators turn on REQUIRE_SIGNED_CHAIN_ID (testnet first). Only then is a payload without a network refused everywhere.
4. Pick H (well above the tip), set chain_id_binding: Some(H) (and, if wanted at the same time, contract_chain_id: Some(H)) for testnet in core/daemon/src/upgrades.rs — mainnet via chain_binding::CHAIN_ID_BINDING_ACTIVATION_HEIGHT / node::CONTRACT_CHAIN_ID_ACTIVATION_HEIGHT — update mainnet_schedule_is_pinned / testnet_schedule_is_pinned and this page, build, and install on every node of that network before H. Confirm the startup line [upgrades] … chain id binding Some(H), contract chain id Some(H) and GET /api/stats → upgrade_schedule.chain_id_binding == H on each node.
5. Any transaction still in a mempool at H without a network-bound signature is dropped by the producer and must be signed again.

Upgrade notice: AMM_INTEGRITY (mainnet 260, testnet 1440)

What it is. A hard fork that changes how the four pool transaction types — create_pool, add_liquidity, remove_liquidity, swap — are executed. It activates on mainnet at height 260 (release 1.6.7; upgrade_schedule.amm_integrity is 260) and has been active on testnet since height 1440 (release 1.6.6). Mainnet nodes must run release 1.6.7 or later before block 260. Source: core/daemon/src/amm_integrity.rs.

Node release 1.6.4 already keeps pool transactions that cannot take effect out of the blocks a node produces. That protects a network only while every block producer runs it. AMM_INTEGRITY makes the same outcome a rule of the chain, so it no longer depends on who produces the block.

The rule, from height H. A pool transaction either takes its full effect or changes nothing: no fee is charged, no balance moves, no pool changes. It can never make its block invalid.

When a transaction takes effect, all of its parts are written together: the sender's debit, the pools on the route, and the credit. Amounts are computed with checked integer arithmetic; a value out of range means the transaction has no effect. The fee is counted as collected whenever it is charged (before H, the fee of a swap that pays out XRGE is taken from the sender but not distributed).

What does not change. Prices (constant product, 0.3% of the input stays in the pool), the LP minting and redemption formulas, XRGE pool amounts in whole XRGE, the state root layout, the /api/v2 request formats, and every block below H, which replays exactly as before.

For wallets and apps. No change is required. Two visible differences from H:

• A swap that misses its min_amount_out no longer costs the sender anything. Before H a node running 1.6.4 already leaves such a swap out of its blocks; from H the chain guarantees it.
• A transaction that has no effect is still included in a block when a producer includes it, and the chain does not record a per-transaction result. To learn whether a swap traded, compare balances or read the pool events (GET /api/pool/:pool_id/events).

Multi-pool routes are validated by the rule, but nodes do not yet accept a swap_path from the API (no wallet signs one); that is a later, node-level change.

Not part of this upgrade (candidates for a later one): locking the minimum liquidity of a new pool, taking only the matching amounts in add_liquidity with a signed minimum of LP tokens, committing pool reserves in the state root, a deadline on swaps.

Activation.

1. Pick H (well above the tip), set amm_integrity: Some(H) for testnet in core/daemon/src/upgrades.rs — mainnet via amm_integrity::AMM_INTEGRITY_ACTIVATION_HEIGHT — update mainnet_schedule_is_pinned / testnet_schedule_is_pinned and this page, build, and install on every node of that network before H. A node without the upgrade cannot follow the chain past the first block at or above H whose pool transactions the two rule sets judge differently.
2. Confirm the startup line [upgrades] … AMM integrity Some(H) and GET /api/stats → upgrade_schedule.amm_integrity == H on each node.
3. After H, on testnet: one swap that trades, one swap signed with a minimum it cannot meet (the sender's balances must be unchanged), one liquidity add and one removal.

RougeChain node release 1.6.11: testnet faucet fix; shielded pool V2 on testnet at block 1480 (2026-10)

Required for every testnet node before testnet block 1480. Recommended for mainnet nodes. Mainnet consensus is unchanged: the shielded pool V2 has no activation height on mainnet.

What changed

• Testnet: faucet payouts apply the same on every node. Testnet runs without a genesis file, so a node decided whether a faucet payout creates new coins by comparing the sender with its own key. Only the node holding the faucet key applied it as a mint; every other testnet node applied it as an ordinary transfer and rejected the block on its state root (first seen at testnet block 1467). From 1.6.11 a fixed testnet mint-authority key (the project's testnet node, 41d7fc30…, which signed every testnet faucet payout) decides on every testnet node. The producing node's result is unchanged, so testnet history is unchanged. Mainnet keeps its genesis authority set.
• Testnet: the shielded pool V2 (shield_v2, shielded_transfer_v2, unshield_v2) activates at testnet block 1480. From that block testnet nodes accept, verify and apply these transactions under the rules of the shielded pool V2 specification, and the POST /api/shield-v2/submit route added in 1.6.9 starts admitting them. A testnet node on an older release will reject the first block that carries one, so upgrade before block 1480.
• Mainnet: no change. The release replays mainnet history to the same state root as 1.6.9.
• Installer 2.1.1 (install-validator.sh): adds Ubuntu 26.04 to the supported systems. Nodes with auto-update replace their updater with this signed version. No other behaviour changes.
• quantum-vault-daemon --version reports 1.6.11. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.9 is included, and everything planned for 1.6.10 (which was never published).

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by manifests signed with the release keys (Signed releases). The testnet manifest marks the release mandatory with upgrade_before_height 1480, so testnet nodes with auto-update install it within minutes of seeing it.

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves. Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-testnetfix-c208989
echo "471567227439993159a169e5ab1c99b9a7373bb81cf7654cf2c5967ad59111b5  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.11" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.11, and on testnet GET /api/stats shows "shield_v2": 1480 in upgrade_schedule.

To go back, stop the node, restore the .pre-1.6.11 binary and start it again (on testnet only before block 1480).

RougeChain node release 1.6.10: shielded pool V2 on testnet at block 1480 (2026-10)

Superseded before publication by release 1.6.11. 1.6.10 was never published to the release server: a second testnet node rejected testnet block 1467 (a faucet payout) on its state root, and 1.6.11 fixes that. Install 1.6.11.

Required for every testnet node before testnet block 1480. Recommended for mainnet nodes. Mainnet consensus is unchanged: the shielded pool V2 has no activation height on mainnet.

What changed

• Testnet: the shielded pool V2 (shield_v2, shielded_transfer_v2, unshield_v2) activates at testnet block 1480. From that block testnet nodes accept, verify and apply these transactions under the rules of the shielded pool V2 specification, and the POST /api/shield-v2/submit route added in 1.6.9 starts admitting them. A testnet node still on 1.6.9 or older will reject the first block that carries one, so upgrade before block 1480.
• Mainnet: no change. The release replays mainnet history to the same state root as 1.6.9.
• Installer 2.1.1 (install-validator.sh): adds Ubuntu 26.04 to the supported systems. Nodes with auto-update replace their updater with this signed version. No other behaviour changes.
• quantum-vault-daemon --version reports 1.6.10. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.9 is included.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by manifests signed with the release keys (Signed releases). The testnet manifest marks the release mandatory with upgrade_before_height 1480, so testnet nodes with auto-update install it within minutes of seeing it.

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves. Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-shield1480-5afe534
echo "09042df42c321aac660d07b7191b1dd7ba6389c6c55127730c368719e20722df  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.10" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.10, and on testnet GET /api/stats shows "shield_v2": 1480 in upgrade_schedule.

To go back, stop the node, restore the .pre-1.6.10 binary and start it again (on testnet only before block 1480).

RougeChain node release 1.6.9: shielded pool V2 submit route (2026-10)

Recommended for every node, mainnet and testnet. No consensus rule changes and no new activation height.

What changed

• Adds POST /api/shield-v2/submit, the route wallets use to send shielded pool V2 transactions (shield_v2, shielded_transfer_v2, unshield_v2). It accepts those three types only and turns everything else away. The shielded pool V2 has no activation height on either network, so until one is set the node refuses every transaction sent there, exactly as before.
• A node that accepts such a transaction forwards it to its peers on the same route, so it reaches the block producer whichever node the wallet sent it to.
• quantum-vault-daemon --version reports 1.6.9. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.8 is included. The chain rules are unchanged; this binary replays mainnet and testnet history to the same state roots as 1.6.8.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves. Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-shieldsubmit-dc85da7
echo "d7e39beb1e8537182bebbf3f0f0bc94cf86615774970e73f90d763dc9020605f  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.9" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before and "$BIN" --version prints quantum-vault-daemon 1.6.9.

To go back, stop the node, restore the .pre-1.6.9 binary and start it again.

RougeChain node release 1.6.8 — NFT mint stability fix (2026-10)

Recommended for every node, mainnet and testnet. No consensus rule changes and no new activation height.

What changed

• Fixes a bug that could make a node stop producing and importing blocks, and stop answering its API, while it processed certain public NFT mints. A node that hit it stayed stuck until restarted, and would get stuck again on the same transaction. 1.6.8 processes those mints normally.
• Upgrade every node, including non-producing ones: a node still on an older release can get stuck importing a block that contains such a mint.
• quantum-vault-daemon --version reports 1.6.8. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.7 is included. The chain rules are unchanged; this binary replays mainnet and testnet history to the same state roots as 1.6.7.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves (node and CLI). Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-nftfix-290d4a2
echo "b8c11945ef9c94017e2b1cb46472a4855f609b0ef16cb2fa1532d7a7dabf36e2  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.8" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before and "$BIN" --version prints quantum-vault-daemon 1.6.8.

To go back, stop the node, restore the .pre-1.6.8 binary and start it again.

RougeChain node release 1.6.7 — AMM_INTEGRITY on mainnet at block 260 (2026-10)

Mandatory for every mainnet node before mainnet block 260. On testnet nothing changes: AMM_INTEGRITY has been active there since block 1440, and a testnet node on this release validates and produces exactly as on 1.6.6.

What changed

• AMM_INTEGRITY activates on mainnet at height 260 (upgrade_schedule.amm_integrity is 260 on mainnet and 1440 on testnet). From that block, pool transactions (create_pool, add_liquidity, remove_liquidity, swap) apply all-or-nothing: one that cannot take effect changes nothing, pays no fee and does not make the block invalid; swap routes are validated; a pair has one pool; amounts use checked integer arithmetic; the fee of a token-to-XRGE swap is counted as collected. See the upgrade schedule.
• A mainnet node on an older release cannot follow the chain past the first block at or above 260 whose pool transactions the old and the new rules judge differently. Installing this release and restarting is enough to catch up.
• quantum-vault-daemon --version reports 1.6.7. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.6 is included. Below block 260 the mainnet rules are unchanged, and this binary replays mainnet history from block 1 to the same state root as 1.6.6.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves (node and CLI). Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-amm-mainnet-260-c64c90c
echo "e9b4fbf188e28ac3d963f35b28589442d2062890508c47c0b403bbab74aa1626  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.7" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.7, and curl -s localhost:5100/api/stats | jq .upgrade_schedule.amm_integrity prints 260 on mainnet and 1440 on testnet.

To go back (mainnet before block 260 only), stop the node, restore the .pre-1.6.7 binary and start it again.

RougeChain node release 1.6.6 — AMM_INTEGRITY on testnet at block 1440 (2026-10)

Mandatory for every testnet node before testnet block 1440. Recommended on mainnet, where nothing activates: AMM_INTEGRITY has no mainnet height, so a mainnet node on this release validates and produces exactly as on 1.6.4 and 1.6.5.

What changed

• AMM_INTEGRITY activates on testnet at height 1440 (upgrade_schedule.amm_integrity is 1440 on testnet and null on mainnet). From that block, pool transactions (create_pool, add_liquidity, remove_liquidity, swap) apply all-or-nothing: one that cannot take effect changes nothing, pays no fee and does not make the block invalid; swap routes are validated; a pair has one pool; amounts use checked integer arithmetic; the fee of a token-to-XRGE swap is counted as collected. See the upgrade schedule.
• A testnet node on an older release cannot follow the chain past the first block at or above 1440 whose pool transactions the old and the new rules judge differently. Installing this release and restarting is enough to catch up.
• quantum-vault-daemon --version reports 1.6.6. The rougechain CLI is unchanged (1.3.0).

Everything in release 1.6.5 is included. The mainnet schedule is unchanged, and this binary replays mainnet history from block 1 to the same state root as 1.6.5.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves (node and CLI). Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-amm-testnet-1440-b7bf14b
echo "bdcfefda3db51fbfc8a100c5c6228c42e8836c96d4bec18dbf82e47d1c59f6db  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.6" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.6, and curl -s localhost:5100/api/stats | jq .upgrade_schedule.amm_integrity prints 1440 on testnet and null on mainnet.

To go back (mainnet, or testnet before block 1440), stop the node, restore the .pre-1.6.6 binary and start it again.

RougeChain node release 1.6.5 — AMM_INTEGRITY included, not scheduled (2026-10)

Recommended for every node. Nothing activates with this release: it carries the consensus rule AMM_INTEGRITY without an activation height, so a node that installs it validates and produces exactly as release 1.6.4 does, and a node that has not installed it keeps following the chain. Validators should install it now: the rule can only be given a height once every validator runs a release that contains it.

What changed

• AMM_INTEGRITY is in the node, unscheduled. From its activation height, pool transactions (create_pool, add_liquidity, remove_liquidity, swap) apply all-or-nothing:

  • a transaction that cannot take effect changes nothing, pays no fee and does not make the block invalid;
  • a swap route must name 2 to 4 tokens, start at the input token, end at the output token, use no pool twice, and every pool on it must exist and pay out;
  • a pair has one pool, whatever the order or letter case of the two symbols;
  • amounts are computed with checked integer arithmetic;
  • the fee of a token-to-XRGE swap is counted as collected.

  The rule and what it does not cover are described in the upgrade schedule. upgrade_schedule.amm_integrity in GET /api/stats is null on every network. The height will come in a later, announced release — testnet first.

• quantum-vault-daemon --version reports 1.6.5. The rougechain CLI is unchanged (1.3.0), rebuilt from the same commit.

Everything in release 1.6.4 is included; the upgrade schedule is unchanged (mainnet 235 / 235 / 245, testnet 1360 / 1360 / 1390, all active). This binary replays mainnet history from block 1 to the same state root as 1.6.4.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves (node and CLI). Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-amm-integrity-e433489
echo "d4ac78ef1082a0ff12af71734d67dab1caf9c5e267a7530c2264bd00f2a7da8f  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.5" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.5, and curl -s localhost:5100/api/stats | jq .upgrade_schedule shows amm_integrity as null.

To go back, stop the node, restore the .pre-1.6.5 binary and start it again.

RougeChain node release 1.6.4 — signatures commit to the network (2026-10)

Recommended for every node. Not a consensus change: no activation height, no state change, and a node that has not installed it keeps following the chain. Nodes that serve the public API should install it promptly — it is step 1 of the network-binding rollout.

What changed

• Signatures commit to the network. Wallets now put the network they sign for into the signed bytes (chainId in /api/v2 payloads and in signed mail, messenger, name and vote requests; chain_id in a rougechain CLI envelope). The node refuses a signed payload that names another network with CHAIN_ID_MISMATCH — at the API, in the mempool and when producing a block. A payload that names no network is still accepted. See Security.

• REQUIRE_SIGNED_CHAIN_ID (--require-signed-chain-id / QV_REQUIRE_SIGNED_CHAIN_ID, default off). When on, the node also refuses payloads that name no network (CHAIN_ID_REQUIRED). Leave it off for now: turn it on once the wallets your users sign with have shipped the field (site, @rougechain/sdk 1.15.0, extension 1.9.0, Qwalla 1.3.0, CLI 1.3.0) and your node no longer receives payloads without it — testnet first, announced in the upgrade schedule (rollout step 3).

• Batch submissions get the same checks as single ones. Every item of POST /api/v2/batch-submit now goes through the checks of a single /api/v2 submission: the 5-minute timestamp window, the signature replay guard (shared with the single routes and kept across restarts), the network rule, from = signer and the signed account_nonce. Verification is all-or-nothing: if any item fails, or the same signature appears twice, the whole batch is refused (success: false, accepted: 0, a result per item), nothing is queued and no signature is used up, so the valid items can be sent again unchanged. A batch that passes is offered to the mempool item by item, as before.

• Block producer and liquidity / swap requests. The block producer leaves out transactions that would fail and refuses malformed liquidity and swap requests:

  • a transaction whose application fails is dropped (and logged) and the block is produced with the others — one transaction no longer holds back the rest of the queue;
  • a pool, liquidity or swap transaction that would not take effect at its position in the block (for example a swap whose output would be below its min_amount_out) is left out instead of included, so it is not charged;
  • the node refuses, with AMM_REQUEST_REFUSED, requests with zero amounts, a pool with the same token on both sides, a pool for a pair that already has one (in either order), an addition that would mint no LP tokens, a withdrawal that would return nothing on one side, and swaps with a multi-hop path (swap_path, which the public API never sets).

  These are rules of the node that builds and admits transactions; what makes a block valid is unchanged, and blocks from nodes without this release are accepted exactly as before.

• Balances. GET /api/balance/:publicKey/XRGE returns the native XRGE balance (native: true); it used to answer 0. Both balance routes also return the stored integers as decimal strings (balance_raw + decimals; balance_quanta + token_balances_raw) — use these for any threshold check (Units and precision).

• Present but not active. The shielded pool V2 code is included and inactive (upgrade_schedule.shield_v2 is null on every network). The consensus rules CHAIN_ID_BINDING and CONTRACT_CHAIN_ID are included and unscheduled (chain_id_binding / contract_chain_id are null); each will get its height in a later, announced release.

• quantum-vault-daemon --version reports 1.6.4 (earlier binaries reported 0.1.0).

Everything in release 1.6.3 is included; the upgrade schedule is unchanged (mainnet 235 / 235 / 245, testnet 1360 / 1360 / 1390, all active). This binary replays mainnet and testnet history to the same state roots as 1.6.3.

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves (node and CLI). Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-network-binding-447abca
echo "48a43cad46388ede48179432a371a32819492aa59dbc2149653655a5f414e9c3  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.4" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before, "$BIN" --version prints quantum-vault-daemon 1.6.4, and curl -s localhost:5100/api/stats | jq .upgrade_schedule shows chain_id_binding, contract_chain_id and shield_v2 as null.

To go back, stop the node, restore the .pre-1.6.4 binary and start it again.

RougeChain node release 1.6.3 — messenger and mail hardening (2026-10)

Recommended for every node. Not a consensus change: no activation height, no state change, and a node that has not installed it keeps following the chain. Nodes that serve the public API should install it promptly.

What changed

• Messenger directory. A directory entry can only be replaced by the wallet that owns it, identified by the signing key that authenticates the request. An encryption key that is already registered to another wallet is refused. Mail names and mail folders follow the owning wallet only.
• Legacy read routes retired. GET /api/mail/inbox, /api/mail/sent, /api/mail/trash, /api/mail/message/:id, /api/messenger/conversations and /api/messenger/messages return 410 Gone (outside --dev). Clients use the signed routes: POST /api/v2/mail/folder, /api/v2/messenger/conversations/list and /api/v2/messenger/messages/list.
• Suspended transaction types are refused by the shielded API routes before any request data is processed, with this transaction type is suspended.

Everything in release 1.6.2 is included; the upgrade schedule is unchanged (mainnet 235 / 235 / 245, testnet 1360 / 1360 / 1390, all active).

Production binary

Built twice from clean; the two builds were byte-identical. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves. Otherwise:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-directory-hardening-8eacc0d
echo "58c0288fc0137f35f4b986be24b010589ff4783c58239bde229f6a7014ab6171  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.3" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart: the node follows the chain as before and curl -s -o /dev/null -w '%{http_code}\n' "localhost:5100/api/mail/inbox?walletId=x" prints 410.

To go back, stop the node, restore the .pre-1.6.3 binary and start it again.

RougeChain node release 1.6.2 — monetary-integrity rule (2026-10)

Mandatory upgrade for every mainnet validator and full node. Blocks 235 and 245 have both passed (mainnet was at height 251 on 2026-10-06), so a node on an older build is already stopped at the first block it cannot judge; installing this release — or 1.6.3, which contains it — and restarting is enough to catch up, no resync. This release contains the two changes that activated at 235 (see the previous notice) and one consensus rule that activated at 245.

A node on an older build stops following mainnet at the first block from 235 that uses a new feature, or at the first block from 245 that the new rule judges differently: it stays at the height before it and applies nothing wrong. Installing this build and restarting is enough to continue — no resync.

What the monetary-integrity rule does (≥ 245)

From block 245 a block is invalid if it carries a transaction that:

• has a fee that is not a finite number of zero or more;
• is of type slash;
• sets the faucet flag (mainnet has no faucet; testnet keeps its faucet);
• is of a suspended type: shield, shielded_transfer, unshield, token_lock, token_unlock, create_staking_pool, token_stake, token_unstake, create_proposal, cast_vote, execute_proposal, delegate, undelegate, token_approve, token_transfer_from.

Token allowances are not affected: /api/v2/token/approve and /api/v2/token/transfer-from use the approve and transfer_from transaction types, which stay enabled; token_approve and token_transfer_from are older types that no client sends.

The suspended features are switched off until a later release restores them. On mainnet the shielded pool is empty and none of the other types has ever been used, so no funds are affected. Transfers, validator staking, swaps and liquidity, tokens, minting and allowances, NFTs, contracts, the bridge, messaging and mail are unchanged. Nothing changes below the activation height; mainnet history replays identically.

Also in this build (no activation height): stricter verification on the manual bridge-deposit claim route, the gRPC faucet honours the faucet switch, and the node no longer accepts or produces transactions with an invalid fee.

Production binary

Built twice from clean; the two builds were byte-identical. The same binary carries testnet's schedule. The release is described by a manifest signed with the release keys (Signed releases).

Upgrade

Nodes installed with the one-line installer and auto-update install this release by themselves. Check with rougechain-update status.

Otherwise back up node-keys.json and the data directory, then install the release binary:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-monetary-integrity-2c96256
echo "c43773c898fa12897ace7d2dca80f95626da63d3bf5cf3c81fafb7a4a60f86a1  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-1.6.2" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

Check after the restart:

curl -s localhost:5100/api/stats | python3 -c "import json,sys;d=json.load(sys.stdin);u=d['upgrade_schedule'];print(d['network_height'], u['token_minting'], u['contract_nft_royalty'], u['monetary_integrity'])"

It should print the current height followed by 235 235 245, and the node's state_root should equal https://api.rougechain.io/api/stats at the same height.

To go back, stop the node, restore the .pre-1.6.2 binary and start it again. That is safe only below block 235.

RougeChain node release — mintable tokens and royalty-aware contracts (2026-10)

Mandatory upgrade for every mainnet validator and full node. Block 235 has passed; the current release is 1.6.3, which contains these changes and the block-245 rule. Two consensus changes activate at the same height:

A node on an older build stops following mainnet at the first block from 235 that uses either feature: it rejects that block and stays at the height before it. It does not apply anything wrong, so installing this build and restarting is enough to continue — no resync.

Both changes have been active on testnet since block 1360 (capped minting, creator-only minting, the royalty cap and a full marketplace sale paying exact royalty and seller amounts were all verified there).

Production binary

This exact binary runs on the operator nodes. It was built twice from clean and the two builds were byte-identical. The same binary also carries testnet's schedule (both features at 1360).

What changed

Mintable tokens (≥ 235). create_token accepts "mintable": true and an optional integer "max_supply" (at least the initial supply). The creator can then send signed mint_tokens transactions (1 XRGE fee). The node refuses a mint by any other wallet or past the cap and records the minted total in the chain state. Tokens created before 235 stay fixed-supply. See Token creation.

Royalty-aware contracts (≥ 235). Two read-only host functions, host_nft_royalty_bps(col) and host_nft_royalty_recipient(col, out, cap), let a contract read a collection's royalty and pay it with host_transfer. From the same height nft_create_collection with a royaltyBps above 10000 (or not an integer) is refused. See Smart Contracts.

Also in this build (no activation height): v2 faucet whitelist and cooldown, --trust-proxy and the --rate-limit-per-minute alias, rate-limited /api/finality/*, /api/selection showing the real designated proposer, rouge1 nonce lookups, and token supply fields on the token endpoints.

Upgrade

Back up node-keys.json and the data directory first. Then either install the release binary:

curl -fLo /tmp/quantum-vault-daemon https://api.rougechain.io/releases/quantum-vault-daemon-mint-royalty-03613ef
echo "673bf7b1a469b7f9937b17228faab1e81ae48fb2a90aa32b2fd1b7fcc9cc2984  /tmp/quantum-vault-daemon" | sha256sum -c
systemctl cat rougechain-validator | grep ExecStart      # the first path is the binary your node runs
BIN=/path/from/ExecStart/quantum-vault-daemon             # set this to that path
sudo systemctl stop rougechain-validator
sudo cp -p "$BIN" "$BIN.pre-235" && sudo install -m 755 /tmp/quantum-vault-daemon "$BIN"
sudo systemctl start rougechain-validator

or build the public repository yourself:

sudo systemctl stop rougechain-validator
cp -a ~/.quantum-vault/mainnet ~/.quantum-vault/mainnet.backup-$(date +%Y%m%d)
cd ~/rougechain && git pull --ff-only          # public rougechain-node main, e048bf1 or later
source ~/.cargo/env && cd core && cargo build --release --locked -p quantum-vault-daemon
sudo systemctl start rougechain-validator

(Your own build's sha256 differs from the release binary because build paths are embedded; the source commit is what matters.)

Check after the restart:

curl -s localhost:5100/api/stats | python3 -c "import json,sys;d=json.load(sys.stdin);u=d['upgrade_schedule'];print(d['network_height'], u['token_minting'], u['contract_nft_royalty'])"

It should print the current height followed by 235 235, and the node's state_root should equal https://api.rougechain.io/api/stats at the same height.

RougeChain node release — finality and game-ready contracts (2026-09-28)

Mandatory upgrade for every mainnet validator and full node. Three consensus changes are already active on mainnet:

A node without them cannot follow mainnet past block 150: from block 151 every block carries its parent's finality certificate, and from block 160 the header's state root also commits NFTs and contract state.

Production binary

This exact binary runs on both operator nodes. It was built twice from clean and the two builds were byte-identical.

Verify you are on the canonical chain:

• block 150 has hash 559e66ee9384aaeea91b5dc70285b3c1cbc2805dab1752632003c85007c81b52
• block 160 has hash 4592f38543195a6c619418f778e9897f09c99bab048a83afe29d8cdf5b5277c0
• state_root from curl -s localhost:5100/api/stats equals https://api.rougechain.io/api/stats at the same height

What changed

Exact JSON number parsing (required to follow block 177). A contract call's fee is gasLimit × 0.000001; for about 18% of gas limits that number prints with many digits (block 177: 0.0018369999999999999) and the previous build's JSON parser read it back one unit off, so nodes that receive blocks over the network rejected block 177. This build parses numbers exactly. It changes no rule and needs no activation height.

Finality (≥ 150). Validators sign ML-DSA-65 precommits; a block is final once signers holding more than two thirds of stake have signed it. From block 151 every block header carries parent_commit, the verified certificate for its parent, and a node refuses to import or build on a block without one. See Finality.

Player-signed contracts (≥ 150). contract_call and contract_deploy must be signed by the caller (POST /api/v2/contract/execute and /api/v2/contract/publish); the contract sees the verified signer as its caller, and the signer pays the fee (deploy 10 XRGE; call gasLimit × 0.000001 XRGE). Node-signed contract transactions are invalid. Contracts can read their call arguments.

Game-ready contracts (≥ 160). Contracts can hold and send custom tokens and NFTs, create their own NFT collection and mint to players, and draw per-transaction randomness (host_random). Moves made inside cross-contract calls are applied. The block state root also covers NFT collections and ownership and contract code and storage. See Smart Contracts.

API (no consensus change). POST /api/contract/:addr/query (free dry run), contract events paging (?before=&tx=), WebSocket topic contract:<addr>, receipts that report Failed when a contract call reverts, and the LP fee ledger (GET /api/pool/:id/earnings/:owner).

Upgrade

Stop the node, back up node-keys.json and the data directory, then build the public rougechain-node main branch and restart:

sudo systemctl stop rougechain-validator
cp -a ~/.quantum-vault/mainnet ~/.quantum-vault/mainnet.backup-$(date +%Y%m%d)
cd ~/rougechain && git pull --ff-only
source ~/.cargo/env && cd core && cargo build --release --locked -p quantum-vault-daemon
sudo systemctl start rougechain-validator

After the restart, compare the block 150 and 160 hashes and the state_root above with the public node. If anything differs, the node applied blocks under the old rules: resync from an empty data directory (keep node-keys.json).

RougeChain node release — consensus Release 1 (2026-09-23)

Mandatory upgrade for every mainnet validator and full node.

This release contains two consensus changes that are already active on mainnet:

Both rules are compiled constants in core/daemon/src/node.rs. A node that does not enforce them is not a mainnet node: it can accept blocks the network rejects, and if it mines it will fork itself off.

Production binary

This exact binary runs on the operator validators. It was built twice from clean checkouts and the two builds were byte-identical; the recipe is in "Reproducible build" below.

Minimum required release

Minimum: this release (binary d50f7e5d…, source commit 203507e or a later commit on the same line).

What changed (summary)

Transaction integrity (height ≥ 90). Every transaction has a single identity derived from the signer's public key and the exact bytes the signer signed. The fields a block executes must be the fields that were signed, and a transaction identity may be included in the chain at most once. This is enforced at the API, in the mempool, and as a block-validity rule, so a block that repeats or alters a signed transaction is rejected by every upgraded node.

Proposer selection, Release 1 (height ≥ 100). For each height H exactly one validator may propose: the eligible validator (stake > 0, not jailed at H) with the greatest stake in the canonical validator state after block H-1; ties go to the lowest raw public-key bytes. A correctly signed block from any other validator is rejected. Producers refuse to seal a slot that is not theirs, and keep a local, durable proposal journal so a restart can never sign two different blocks for the same slot. Legacy missed-block accounting (auto-slash / auto-jail for not proposing) is frozen from height 100, because non-designated validators are now required not to propose. There is no fallback proposer in Release 1: if the designated proposer is offline, no block is produced until it returns. Fallback selection is the subject of Release 2.

Read-only reporting. GET /api/stats now includes proposer_selection_activation_height, designated_proposer_next_height, proposer_selection_active_next and designated_proposer_next; the daemon logs one [consensus] proposer selection: … line at startup. Compare these across nodes.

Public API containment (unchanged by this release, still in force). POST /api/blocks/import, POST /api/peers/register, POST /api/tx/broadcast, /api/v2/contract/deploy, /api/v2/contract/call and /api/bridge/withdraw return 403 at the public edge (api.rougechain.io). Nodes sync by pulling GET /api/blocks; peering is arranged with the operator.

Design and evidence: core/daemon/TX_INTEGRITY_FORK.md and core/daemon/PROPOSER_SELECTION_DESIGN.md.

Upgrade instructions (existing validator or full node)

An old validator must upgrade before reconnecting to mainnet. Do not start an old binary against the network, with or without --mine.

1. Stop the node.

   systemctl stop <your-unit>      # e.g. rougechain-validator
   

2. Back up keys and data. node-keys.json in your data directory is your staked validator key.

   cp -a ~/.quantum-vault/mainnet ~/.quantum-vault/mainnet.backup-$(date +%Y%m%d)
   

3. Get the binary — download and verify, or build reproducibly (below).

   curl -fsSLO https://api.rougechain.io/releases/quantum-vault-daemon-proposer-selection-b69d0c9
   curl -fsSLO https://api.rougechain.io/releases/quantum-vault-daemon-proposer-selection-b69d0c9.sha256
   sha256sum -c quantum-vault-daemon-proposer-selection-b69d0c9.sha256      # must print: OK
   install -m 755 quantum-vault-daemon-proposer-selection-b69d0c9 /path/to/quantum-vault-daemon
   

4. Decide whether you need a resync. If your node ever ran an older binary past height 48, or its state root at any height differs from the network's, start from a fresh data directory (keep the backup; copy only node-keys.json back). If in doubt, resync. A resync from genesis replays the whole chain under the current rules and takes a few minutes at today's chain length.
5. Start without --mine. Remove --mine from your unit until the node is verified.

   systemctl start <your-unit>
   journalctl -u <your-unit> --since "-2min" | grep "proposer selection"
   # expect: [consensus] proposer selection: activation height Some(100); next height <tip+1> (rule ACTIVE); designated proposer for <tip+1>: 8ccf7878003b2668
   

6. Verify against the network at the same height:

   curl -s http://127.0.0.1:5101/api/stats | jq '{network_height, state_root, designated_proposer_next}'
   curl -s https://api.rougechain.io/api/stats | jq '{network_height, state_root, designated_proposer_next}'
   

   state_root must match at equal heights and designated_proposer_next must match. Only then is the node on mainnet.
7. Mining. Under Release 1 only the designated proposer may seal blocks, and the daemon refuses to seal any other slot, so a non-designated validator gains nothing from --mine. Leave it off unless your validator is the designated proposer. Staying staked and synchronized keeps your validator eligible for Release 2 fallback selection.

Reproducible build

git clone https://github.com/cyberdreadx/rougechain-node && cd rougechain-node
git checkout 203507e
export SOURCE_DATE_EPOCH=1790185445
export RUSTFLAGS="--remap-path-prefix=$PWD=/build/src --remap-path-prefix=$PWD/core/target=/build/target --remap-path-prefix=$HOME/.cargo=/build/cargo --remap-path-prefix=$HOME=/build/home"
cd core && cargo build --release --locked -p quantum-vault-daemon
sha256sum target/release/quantum-vault-daemon
# expected: d50f7e5d34d03200f6efc45c8b7b63c61079e7f9d5b5c70f5b3c3c3544105eba (rustc/cargo 1.94.0, x86_64 Linux)

Verified 2026-09-23: building commit 203507e of this repository with the recipe above (at the same source path as the release build) produced a byte-identical binary, sha256 d50f7e5d….

Cargo's metadata hash includes the package path, so two builds only match when they are made at the same absolute source path with the same remapping. A different absolute path yields a different, still valid, binary; compare against a second build at your own path if you want to check reproducibility locally.

Reporting problems

Open an issue in this repository with your /api/stats output, the startup [consensus] line and the rejecting log line if any. Do not post private keys or node-keys.json.

P2P Networking

RougeChain uses a peer-to-peer network for block propagation, transaction broadcasting, and peer discovery. All peer traffic runs over each node's HTTP REST API (--api-port, usually behind an HTTPS proxy); there is no separate P2P port.

How It Works

┌─────────────┐     blocks/txs      ┌─────────────┐
│   Node A    │ ◄─────────────────► │   Node B    │
│  (mining)   │                     │  (syncing)  │
└─────────────┘                     └─────────────┘
       ▲                                   ▲
       │           peer discovery          │
       └───────────────┬───────────────────┘
                       │
                       ▼
               ┌─────────────┐
               │   Node C    │
               │ (new peer)  │
               └─────────────┘

Features

Connecting to the Network

As a Syncing Node

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api"

As a Mining Node

./quantum-vault-daemon \
  --mine \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api"

Peer Discovery

Nodes automatically discover new peers every 30 seconds by:

1. Querying known peers via GET /api/peers
2. Adding any new peers to their list
3. Optionally registering themselves via POST /api/peers/register

Enable Self-Registration

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api" \
  --public-url "https://mynode.example.com"

This tells other nodes how to reach you.

API Endpoints

Next Steps

• Connecting to Peers
• Peer Discovery
• Running a Public Node

Connecting to Peers

Connect your RougeChain node to the network to sync blocks and broadcast transactions.

Connect to Testnet

The simplest way to join the network:

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api"

Your node will:

1. Download all blocks from the peer
2. Verify each block's PQC signatures
3. Build the local chain state
4. Start receiving new blocks in real-time

⚠️ Important: Your node is syncing but INVISIBLE to the network.

Without --public-url, your node pulls blocks from peers but never registers itself. Other nodes won't know it exists, and it won't appear on the network globe.

To be discoverable, add --public-url with your node's reachable address — the HTTPS URL of the reverse proxy in front of it (see Firewall & Exposure):

./quantum-vault-daemon \
  --api-port 5100 \
  --node-name "MyNode" \
  --public-url "https://your-server.com/api" \
  --peers "https://testnet.rougechain.io/api"

If running locally without a public IP, your node works fine for personal use — it just won't be visible to the rest of the network.

Connect to Multiple Peers

For better reliability, connect to multiple peers:

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://api.rougechain.io/api,https://node2.example.com,https://node3.example.com"

Or via environment variable:

export QV_PEERS="https://api.rougechain.io/api,https://node2.example.com"
./quantum-vault-daemon --api-port 5100

Verify Connection

Check that your node has peers:

curl http://127.0.0.1:5100/api/peers

Expected response:

{
  "peers": [
    "https://testnet.rougechain.io/api"
  ],
  "count": 1
}

Sync Status

Check if your node is synced:

curl http://127.0.0.1:5100/api/health

{
  "status": "ok",
  "chain_id": "rougechain-devnet-1",
  "height": 12345
}

Compare the height with the testnet to confirm you're in sync:

curl https://testnet.rougechain.io/api/health

Connection Flow

Your Node                                         Peer Node
    │                                                 │
    │── GET /api/blocks?from_height=0&limit=1000 ────►│  (fresh node; later polls
    │◄─── { blocks: [ block0, block1, ... ] } ───────│   use ?limit=1000)
    │                                                 │
    │   (verify signatures, apply)                    │
    │                                                 │
    │── GET /api/finality/:height ───────────────────►│
    │◄─── finality proof ────────────────────────────│
    │                                                 │
    │── GET /api/peers ──────────────────────────────►│
    │◄─── { peers: [...] } ──────────────────────────│
    │                                                 │
    │── POST /api/peers/register ────────────────────►│  (only with --public-url)
    │── GET /api/stats ──────────────────────────────►│  (peer name)

All peer traffic uses the same HTTP REST API that wallets use; there is no separate P2P protocol or port. New blocks and transactions are pushed with POST /api/blocks/import and POST /api/tx/broadcast.

Firewall & Exposure

Do not expose the daemon's REST API port (5100) to the public internet — it serves state-changing endpoints. Bind the daemon to 127.0.0.1 and put a reverse proxy (nginx + TLS) in front of it; open only the proxy's port 443. See Public Node Security.

# Expose ONLY the reverse proxy; keep the daemon API private:
sudo ufw allow 443/tcp
sudo ufw deny 5100/tcp

Troubleshooting

"Connection refused"

• Check that the peer URL is correct and reachable
• Verify the peer node is running
• Check for firewall restrictions

Node stuck syncing

• The initial sync may take time on long chains
• Monitor progress by watching the height increase via /api/health
• Try connecting to a different peer

"Chain ID mismatch"

• Ensure your --chain-id matches the network you're connecting to
• Testnet uses rougechain-devnet-1

Peer Discovery

RougeChain nodes automatically discover other nodes on the network through peer exchange over the HTTP API: each node polls GET /api/peers on the peers it knows.

How Discovery Works

1. Node A starts with seed peer(s) via --peers
2. Node A queries GET /api/peers on each known peer
3. Each peer returns its own list of known peers
4. Node A adds any new peers to its local list
5. If --public-url is set, Node A registers itself on peers
6. Repeat every 30 seconds

Over time, all nodes in the network discover each other, forming a mesh.

Discovery Interval

Peer discovery runs automatically every 30 seconds. No configuration is needed.

Seed Peers

The first peer(s) you connect to act as seeds for discovery. From them, your node learns about the rest of the network.

# Single seed
./quantum-vault-daemon --peers "https://testnet.rougechain.io/api"

# Multiple seeds for redundancy
./quantum-vault-daemon --peers "https://api.rougechain.io/api,https://backup.example.com"

Self-Registration

To make your node discoverable by others, set --public-url:

./quantum-vault-daemon \
  --api-port 5100 \
  --peers "https://testnet.rougechain.io/api" \
  --public-url "https://mynode.example.com"

Your node will call POST /api/peers/register on all known peers, announcing its presence. Other nodes will then include your URL in their peer lists.

Discovery API

Get Known Peers

curl http://127.0.0.1:5100/api/peers

{
  "peers": [
    "https://testnet.rougechain.io/api",
    "https://node2.example.com/api",
    "https://node3.example.com/api"
  ],
  "count": 3
}

Register as a Peer

curl -X POST https://testnet.rougechain.io/api/peers/register \
  -H "Content-Type: application/json" \
  -d '{"peerUrl": "https://mynode.example.com"}'

Discovery Diagram

         Seed Node
        ┌─────────┐
        │  Node A  │ ◄── your --peers target
        └────┬────┘
             │
     GET /api/peers
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
┌───────┐┌───────┐┌───────┐
│Node B ││Node C ││Node D │  ◄── discovered automatically
└───────┘└───────┘└───────┘
    │         │        │
    └─────────┼────────┘
              │
    More peers discovered
       from B, C, D...

Privacy Considerations

• Your node's IP/URL is shared with all peers when using --public-url
• Without --public-url, your node connects outward but is not discoverable by others
• Consider using a reverse proxy or domain name instead of exposing raw IP addresses

Running a Public Node

Run a RougeChain node that is publicly accessible and participates fully in the network.

Requirements

Setup

1. Build and Install

git clone https://github.com/cyberdreadx/rougechain-node
cd rougechain-node/core
cargo build --release -p quantum-vault-daemon
sudo cp target/release/quantum-vault-daemon /usr/local/bin/

2. Configure Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name mynode.rougechain.example.com;

    ssl_certificate /etc/letsencrypt/live/mynode.rougechain.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mynode.rougechain.example.com/privkey.pem;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:5100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Set client_max_body_size to at least 50M to support messenger media uploads.

By default the daemon keys rate limits by the connecting IP, which behind this proxy is always 127.0.0.1. Start it with --trust-proxy to key them by the X-Real-IP / X-Forwarded-For this proxy sets (honoured only for loopback connections). See Rate Limiting.

3. Start the Node

./quantum-vault-daemon \
  --mine \
  --host 127.0.0.1 \
  --api-port 5100 \
  --node-name "MyNode" \
  --peers "https://testnet.rougechain.io/api" \
  --public-url "https://mynode.rougechain.example.com"

Why --public-url is required: Without it, your node syncs blocks but never tells other nodes "I exist." It stays invisible — it won't appear on the network globe, other nodes can't sync from it, and it won't receive direct block broadcasts. The --public-url must be the URL that other nodes on the internet can reach.

Once running, visit http://127.0.0.1:5100 in your browser to see the built-in node dashboard with live block height, peers, mining status, and fees.

4. Run as a Service

Create /etc/systemd/system/rougechain.service:

[Unit]
Description=RougeChain Node
After=network.target

[Service]
Type=simple
User=rougechain
ExecStart=/usr/local/bin/quantum-vault-daemon --mine --host 127.0.0.1 --api-port 5100 --peers "https://testnet.rougechain.io/api" --public-url "https://mynode.rougechain.example.com"
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo useradd -r -s /bin/false rougechain
sudo systemctl enable rougechain
sudo systemctl start rougechain

Verify Your Node

Health Check

curl https://mynode.rougechain.example.com/api/health

Check Peers Can See You

curl https://testnet.rougechain.io/api/peers
# Your node's URL should appear in the list

Security Hardening

API Keys

--api-keys requires an X-API-Key (or Authorization: Bearer) header on every route that is not exempt — reads such as /api/blocks and balances included, not just writes:

./quantum-vault-daemon \
  --mine \
  --api-port 5100 \
  --api-keys "secret-key-1,secret-key-2"

Exempt routes: /, /api/health, /api/stats, /api/v2/*, /api/bridge/*, /api/messenger/*, /api/mail/*, /api/names/*, /api/finality/*, the faucet and the bot (signed routes check their own signatures). Peers never send an API key, so a keyed node also refuses the peer routes /api/blocks/import, /api/peers/register and /api/tx/broadcast — use API keys for a private node, not for a public one that should take part in peering.

Rate Limiting

The node has built-in rate limiting (disabled by default — every limit defaults to 0, unlimited). Set the read and write limits:

./quantum-vault-daemon --rate-limit-read-per-minute 600 --rate-limit-write-per-minute 60

GET requests count against the read limit and every other method against the write limit; --rate-limit-validator and --rate-limit-peer set separate limits for signed validator requests and registered peers. --rate-limit-per-minute is a deprecated alias that applies to both reads and writes when neither of those is set. Limits are keyed by the connecting IP, so behind the nginx proxy above all clients share one bucket unless you add --trust-proxy (env QV_TRUST_PROXY=true): then a request arriving from loopback is keyed by X-Real-IP (else the rightmost X-Forwarded-For entry), and any non-loopback connection still by its socket IP. Only enable it when the API port is reachable solely through that local proxy. All routes are limited, including /api/finality/*.

Firewall

Only expose the necessary port:

sudo ufw default deny incoming
sudo ufw allow ssh
sudo ufw allow 443/tcp
sudo ufw enable

Monitoring

Check Logs

sudo journalctl -u rougechain -f

Health Endpoint

Set up a monitoring tool (e.g., UptimeRobot) to poll:

https://mynode.rougechain.example.com/api/health

Metrics to Watch

Staking & Validators

RougeChain uses Proof of Stake (PoS) for consensus. Validators stake XRGE tokens to participate in block production and earn rewards.

How It Works

1. Stake tokens - Lock XRGE to become a validator
2. Propose and vote - The designated proposer (the validator with the most stake) proposes blocks; staked validators vote to finalize them
3. Earn rewards - Every staked validator earns a stake-weighted share of the fees in every block
4. Unstake - Wait for unbonding period to withdraw

Requirements

Become a Validator

Via Web UI

1. Go to the Validators page
2. Click Stake
3. Enter amount (min 10,000 XRGE)
4. Confirm transaction

Via SDK (Recommended)

import { RougeChain, Wallet } from '@rougechain/sdk';

const rc = new RougeChain('https://testnet.rougechain.io/api');
const wallet = Wallet.fromKeys(publicKey, privateKey);

await rc.stake(wallet, { amount: 10000 });

Via API (v2 Signed Request)

All write operations require ML-DSA-65 client-side signing. See Staking API for the full request format.

# The payload must be signed client-side with your ML-DSA-65 private key.
# Use the SDK or build the signed request manually:
curl -X POST https://testnet.rougechain.io/api/v2/stake \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "amount": 10000,
      "from": "your-public-key-hex",
      "timestamp": 1706745600000,
      "nonce": "random-hex"
    },
    "signature": "ml-dsa65-signature-hex",
    "public_key": "your-public-key-hex"
  }'

Check Your Stake

curl "https://testnet.rougechain.io/api/validators?publicKey=your-public-key"

Response:

{
  "validators": [
    {
      "publicKey": "your-public-key",
      "stake": 10000.0,
      "status": "active",
      "blocksProposed": 42
    }
  ]
}

Unstake

Via SDK

await rc.unstake(wallet, { amount: 5000 });

Via API (v2 Signed Request)

curl -X POST https://testnet.rougechain.io/api/v2/unstake \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "amount": 5000,
      "from": "your-public-key-hex",
      "timestamp": 1706745600000,
      "nonce": "random-hex"
    },
    "signature": "ml-dsa65-signature-hex",
    "public_key": "your-public-key-hex"
  }'

Validator Selection

Since mainnet height 100, each block has exactly one designated proposer: the eligible validator (stake > 0, not jailed) with the most stake, ties going to the lowest raw public-key bytes. Selection is deterministic — no randomness and no rotation — and there is no fallback proposer yet. Blocks from any other validator are rejected. See Becoming a Validator → Proposer selection.

GET /api/selection reports this designated proposer for the next height (rule: "designated_max_stake").

Rewards

Validators earn from an EIP-1559-inspired fee model:

Fees are credited when a block is applied to state. The validator share goes to every validator in the set by stake, with no check that the validator took part in finality. There is no block subsidy: with today's activity, rewards are small (about 541 XRGE of fees were collected over the whole chain up to 2026-10-06, before burning and splitting). See Validator Economics for detailed reward calculations.

PQC Security

All validator operations use ML-DSA-65 signatures:

• Block proposals are signed
• Stake/unstake transactions are signed
• Signatures are verified by all nodes

Block production and staking are therefore signed with quantum-resistant keys.

Finality: verified BFT finality (FINALITY_V2 — verified ML-DSA-65 votes, recomputed quorum, anti-equivocation journals) is active on mainnet since height 150. Every block from 151 carries a ⅔-stake commit certificate for its parent. See Finality.

Planned, not built: a consensus redesign decided on 2026-10-06 — rotating stake-weighted proposers, Tendermint-style rounds, an active set capped at 32, a consensus-enforced minimum of 100,000 XRGE (30-day grace for existing validators), 21-day unbonding and evidence-based slashing. Heights will be announced in advance; see Status & Roadmap. Until then, everything on this page describes the rules as they run today.

Becoming a Validator

Validators propose blocks and earn fees on RougeChain. This guide targets mainnet (rougechain-mainnet-1, real value, no faucet). To practice first, see Testing on testnet at the end.

Quick install (one command)

On a fresh Ubuntu 22.04 / 24.04 or Debian 12 server (x86_64; a ~$5/mo VPS is plenty), the installer downloads the current signed release of the node — nothing is compiled — sets it up as a systemd service under a dedicated user, and starts syncing:

curl -sSL https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/scripts/install-validator.sh | sudo bash

What it verifies. The installer fetches the release manifest and its signatures from api.rougechain.io and from the GitHub mirror, checks the Ed25519 signature with openssl against the release public key that is embedded in the script (and the ML-DSA-65 signature with the rougechain CLI of the release), and only then downloads the binary and checks its size and sha256 against the signed manifest. If anything does not match, it stops and installs nothing. See Signed releases. To check a release yourself, or to see what the script would do without changing anything:

curl -sSL https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/scripts/install-validator.sh | bash -s -- --dry-run

(--dry-run needs no root, but curl, openssl and jq must already be installed.) Verifying a release by hand with openssl is described in Signed releases.

What it sets up. Node /usr/local/bin/quantum-vault-daemon and the CLI /usr/local/bin/rougechain, both from the signed release; service rougechain-validator running as the system user rougechain; data and node-keys.json in /var/lib/rougechain/mainnet (key file mode 0600); API on 127.0.0.1:5100; and automatic updates from signed releases (timer rougechain-update.timer; AUTO_UPDATE=0 to opt out). It generates a node key only if there is none and never overwrites an existing key or chain data. Settings are environment variables placed after sudo, for example NODE_NAME=my-validator, NETWORK=testnet, NO_START=1 — the full list is in Signed releases.

It installs a full node, not yet a validator. Block production (--mine) stays off until you ask for it, because a node should not claim to produce blocks with a key that is not staked:

1. Run the installer (above). Back up /var/lib/rougechain/mainnet/node-keys.json offline.

2. Fund and stake ≥ 10,000 XRGE from that key with the installed rougechain CLI. The key file is readable only by the rougechain user, so run the CLI as that user:

   K=/var/lib/rougechain/mainnet/node-keys.json
   sudo -u rougechain rougechain --node-keys $K whoami            # your validator address
   # send ≥ 10,000 XRGE (+ 1 XRGE fee) to that address from your main wallet, then:
   sudo -u rougechain rougechain --node-keys $K stake 10000
   sudo -u rougechain rougechain --node-keys $K validator-status
   

   (Without sudo, as root: runuser -u rougechain -- rougechain ….) Details of each command are in Step 2 and Step 3 below.

3. Once validator-status shows ✓ Staked and ✓ In active set, turn on block production and give peers a URL they can reach over HTTPS (peers talk to each other over the REST API; there is no separate P2P port):

   curl -sSL https://raw.githubusercontent.com/cyberdreadx/rougechain-node/main/scripts/install-validator.sh \
     | sudo VALIDATOR=1 PUBLIC_URL=https://node.example.com bash
   

The node then votes on blocks automatically and proposes whenever it is the designated proposer. Upgrades are automatic: the node installs newer signed releases by itself, checks its own health afterwards and rolls back if the check fails — rougechain-update status shows where it stands, and Automatic updates explains the checks and how to switch to notify-only or pin a version. You can always upgrade by hand instead: re-run the installer (it verifies the new signed release, keeps the previous binary as quantum-vault-daemon.prev, and restarts the service; add NO_START=1 to restart later yourself). The rest of this page is the manual walkthrough if you would rather do each step yourself.

The one thing you must understand

Your validator identity is a single ML-DSA-65 keypair that does two jobs:

1. it holds your stake — staking from a key registers that key as a validator, and
2. it signs the blocks your node proposes.

Your node stores this keypair at <data-dir>/node-keys.json. The network rejects any block whose proposer is not a staked validator (and, since height 100, any block whose proposer is not the designated proposer) — so your node's node-keys.json key and your staked key must be the same key. If you stake from one key but run your node with a different (freshly generated) key, your blocks are rejected by every peer and you earn nothing, with no obvious error. This is the most common way to get validator setup wrong.

Security: this key signs blocks on an always-online, internet-facing server. Use a dedicated key that holds only your stake — never your main treasury wallet. If the server is compromised, the blast radius is limited to the staked amount.

Prerequisites

• ≥ 10,000 XRGE (+ 1 XRGE fee) — see minimum stake.
• A server — see system requirements and installation.
• The daemon (quantum-vault-daemon) and the CLI (rougechain).

Minimum stake

The 10,000 XRGE minimum is enforced by the node's API when it builds or accepts a stake request (/api/v2/stake and the CLI stake command), not by consensus: block apply accepts any positive stake that the balance covers, and one mainnet validator holds 9,000 XRGE. There are no validator tiers, no commission and no delegation — the delegate transaction type belonged to the suspended governance system (block 245) and never concerned staking. A consensus-enforced minimum of 100,000 XRGE, with a 30-day grace period for existing validators, is part of the consensus redesign decided on 2026-10-06, which is not built; see Status & Roadmap.

Mainnet has three staked validators (2026-10-06): about 100.09 M XRGE (the operator's producing validator), 10,000 XRGE and 9,000 XRGE. Only the largest produces blocks.

Step 1 — Install and generate your node identity

Install the daemon (installation guide), then start it once so it creates its identity keypair and begins syncing:

./quantum-vault-daemon \
  --genesis daemon/genesis-mainnet.json \
  --chain-id rougechain-mainnet-1 \
  --peers https://api.rougechain.io/api \
  --data-dir ~/.quantum-vault/mainnet \
  --api-port 5100 --port 4100 \
  --node-name my-validator

On first boot it logs:

[node] Generated and saved new node keys (pub: <your-node-pubkey>...)

Your identity keypair now lives at ~/.quantum-vault/mainnet/node-keys.json (fields: algorithm, public_key_hex, secret_key_hex). Back this file up, offline. Losing it means losing your validator identity — and the ability to unstake. Let the node sync to the chain tip before continuing.

Step 2 — Point the CLI at your node's key

No key copying needed — the CLI signs directly from your node's identity file with the --node-keys flag, so you act as exactly the key your node signs blocks with:

rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json whoami

This prints your validator's public key + rouge1… address — confirm it matches the key the daemon logged in Step 1. Every command below uses the same --node-keys flag. The CLI talks to the public mainnet node (https://api.rougechain.io) unless you pass --network testnet or --rpc <your node>; stake, unstake and transfer are submitted through the node's signed /api/v2 routes, so they work from any machine. This needs a CLI built from the current source (or the one the installer provides): older builds default to a retired host and post to a route the public node refuses.

Step 3 — Fund and stake

Send ≥ 10,000 XRGE (+ 1 XRGE fee) to your validator address (from whoami above) from your main wallet. Then stake it:

rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json stake 10000

The 10,000 minimum is enforced by the API on every stake call — a smaller top-up is rejected. Each additional stake must itself be ≥ 10,000; totals accumulate. It is not a consensus rule (see Minimum stake).

Verify with the built-in diagnostic — it checks funded / staked / active / producing in one shot:

rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json validator-status

You want ✓ Staked and ✓ In active set. (It prints the exact fix next to anything that's ✗.)

Step 4 — Start mining

Restart the daemon with --mine (same key, same data-dir), plus a public URL so peers can reach you:

./quantum-vault-daemon \
  --mine \
  --genesis daemon/genesis-mainnet.json \
  --chain-id rougechain-mainnet-1 \
  --peers https://api.rougechain.io/api \
  --data-dir ~/.quantum-vault/mainnet \
  --api-port 5100 --port 4100 \
  --node-name my-validator \
  --public-url https://my-validator.example.com

Because your node-keys.json key is now a staked validator, your node votes toward each block's commit certificate, and peers accept your blocks whenever you are the designated proposer. Check progress anytime with:

rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json validator-status

You're fully live once you're staked, in the active set and synced. ✓ Producing blocks counts blocks you have proposed, so it only turns green once you have been the designated proposer (the largest stake); see Proposer selection.

Proposer selection

Since mainnet height 100 (Release 1), each block has exactly one designated proposer: the eligible validator (stake > 0, not jailed) with the most stake; ties go to the lowest raw public-key bytes. Selection is deterministic: there is no randomness, no QRNG and no rotation, so a validator that does not hold the most stake does not propose blocks. Every staked, non-jailed validator still earns a stake-weighted share of the fees in every block (see Rewards). There is no fallback proposer yet: if the designated proposer is offline, no blocks are produced until it returns. See Adding a Validator for how this affects a new validator.

The designated proposer for the next height is designated_proposer_next in GET /api/stats, and proposer in GET /api/selection (which reports rule: "designated_max_stake" and no entropy fields once the rule is active).

Security & slashing — read before you go live

• Dedicated key. Keep only the stake in your validator key; never use your treasury wallet. (Done, if you followed Step 1.)
• One node per key. Never run two nodes with the same key — two nodes can sign two different blocks or votes at one height (equivocation). Slashing on equivocation evidence is part of the planned consensus redesign and does not exist yet.
• Back up node-keys.json offline. It is the only copy of your validator identity.
• Don't expose the daemon port. Bind to localhost, front it with nginx + TLS, and firewall the RPC/API port. See public-node security. Do not open port 5100 to the public internet.
• Stay online. No slashing is active today: automatic missed-block slashing is frozen since height 100 and the legacy slash transaction is rejected since height 245 (the 10 % / 20-block parameters remain in the code). But if you are the designated proposer and go offline, the chain stops producing blocks, and an offline validator's vote is missing from the ⅔-stake commit certificate. Alert on your node being offline or lagging the chain tip (/api/health height vs the network).
• Never run --dev on a mainnet node — it enables unsafe key-accepting endpoints.
• Upgrades. A node set up with the installer updates itself from signed releases only: it verifies the release keys' signatures, waits if your validator is the designated proposer with transactions pending, health-checks the node after the restart and rolls back if the check fails. If you would rather restart your validator yourself, set MODE=notify (or PIN_VERSION) in /etc/rougechain/mainnet/update.conf — then you must install mandatory releases before their upgrade height. Never use anything that builds and runs main unattended (the retired git-pull "auto-deploy" cron): that is unreviewed code, restarted at arbitrary times.

Increasing stake / leaving

• Add stake: rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json stake 10000 again (≥ 10,000 each time).
• Leave: rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json unstake <amount> enters the 500-block unbonding queue (wall-clock time depends on how often blocks are produced); dropping to 0 stake removes you from the active set. See Staking.

Testing on testnet first

Practice the whole flow with no real value: swap the mainnet flags for testnet — --chain-id rougechain-devnet-1, --peers https://testnet.rougechain.io/api, --data-dir ~/.quantum-vault/testnet — point the CLI at it with rougechain --network testnet …, and get test XRGE from the faucet (rougechain --network testnet --node-keys <path> faucet, 10,000 per key per 24 h — staking 10,000 needs 10,001 with the fee, so top up with a transfer from a second key or the wallet). Everything else is identical.

With the installer: curl -sSL …/install-validator.sh | sudo NETWORK=testnet bash (service rougechain-validator-testnet, data in /var/lib/rougechain/testnet, API on 127.0.0.1:5101, CLI installed as rougechain-testnet; run it as sudo -u rougechain rougechain-testnet --network testnet --node-keys /var/lib/rougechain/testnet/node-keys.json …).

Adding a Validator to a Live Chain

This note explains how a new validator joins a chain that is already running, and clears up a common misreading of the sync code. If you just want the step-by-step operator walkthrough, read Becoming a Validator first — this page explains why those steps are ordered the way they are, and what happens at the network level when you get it wrong.

The one invariant: stake before you propose

A block is accepted by other nodes only if its proposer is a staked validator in the on-chain validator set. So a new validator must stake first, confirm it is in the active set, and only then run --mine. Before you are staked-and-in-set, your node never holds a proposer slot.

Being staked is necessary but not sufficient to propose. Since mainnet height 100 (proposer selection, Release 1) exactly one validator may propose each block: the designated proposer, which is the eligible validator (stake > 0, not jailed) with the most stake, ties going to the lowest raw public-key bytes. The rule is deterministic: there is no randomness, no rotation and no fallback. A correctly signed block from any other validator is rejected, and a node that is not the designated proposer does not seal blocks at all. Since height 150 (FINALITY_V2) a block must also carry a commit certificate for its parent signed by validators holding ⅔ of the stake. See Finality.

Everything below is the mechanism behind these rules.

Myth vs. reality: "the chain becomes unjoinable after block 100"

You may hear — often from a tool reading the source — that RougeChain "becomes unjoinable the moment it passes block 100." This is false, and it comes from misreading one line in the P2P import path (core/daemon/src/node.rs, import_block):

#![allow(unused)]
fn main() {
let validators = self.list_validators().unwrap_or_default();
if !validators.is_empty() && block.header.height > PROPOSER_AUTH_ACTIVATION_HEIGHT {
    // proposer must be a staked validator (stake > 0), else reject this block
}
}

PROPOSER_AUTH_ACTIVATION_HEIGHT is 100. The rule this enforces is "past height 100, an imported block's proposer must be a staked validator" — not "past height 100, imported blocks are rejected." Whether it is a wall or a no-op depends entirely on who is producing the blocks:

• If blocks are produced by staked validators (genesis initial_validators, or anyone added later via a stake tx), then every syncing node rebuilds that same validator set from history as it replays the chain, recognizes the proposer, and accepts the block at any height. The chain stays fully joinable forever.
• The check only ever rejects a block whose proposer is not a staked validator — i.e. a genuine misconfiguration (a node mining with an unstaked key). That is the check doing its job. (From height 100 the stricter designated-proposer rule above applies as well.)

So the "cliff" is really the stake-before-propose invariant stated backwards. Growing the validator set is not blocked by this check — it is governed by it: stake correctly and joining works at height 100, 10,000, or 10,000,000.

How proposer authorization actually works

Two things combine:

1. The validator set is deterministic from history. Genesis seeds initial_validators (each with a stake), and every later stake / unstake transaction updates the on-chain validator store. Because a syncing node replays the exact same blocks in the exact same order, it derives the exact same validator-set membership at every height. There is no out-of-band "validator list" a joiner can be missing — it is a function of the chain it is already downloading.

2. A bootstrap grace window below height PROPOSER_AUTH_ACTIVATION_HEIGHT (100). Blocks at or below height 100 skip only the proposer-authorization check — they are not otherwise unvalidated. A block below 100 must still pass its proposer signature, block hash, and prev_hash, every transaction signature (verified at all heights), and — past the v2 fork height (18) — the committed state root and the contract-custody apply. Skipping proposer authorization just lets a brand-new network get off the ground before staking transactions have populated the set. Above height 100 the proposer check is enforced (once the set is non-empty — see below), so on a mature chain there is no grace period: a new validator must already be staked and in the set before its blocks will be accepted by peers.

Two edge cases in that gate. (a) The check is also short-circuited when the node's locally-derived validator set is empty (a defensive don't-brick fallback) — so it is meaningfully enforced only once the set is non-empty and height exceeds 100. (b) It gates imported blocks (the P2P sync path). Before proposer selection was active, a node's own freshly-produced block wasn't self-rejected, so an unstaked miner's height could climb locally while peers rejected the same blocks. Since height 100 that no longer happens: the miner refuses to seal any slot it is not the designated proposer for, so a misconfigured node simply stays at the network's height.

The grace window is a bootstrap aid, not something to rely on when adding a validator. On any chain past height 100 it does nothing for you. Always follow stake-before-propose regardless of current height.

Adding a validator to a running chain — the correct sequence

This mirrors Becoming a Validator, with the reason each step is load-bearing. Follow that guide for exact commands.

1. Generate the node identity and sync to the tip. Your node-keys.json key is both your stake-holding key and your block-signing key — they must be the same key. Let the node fully sync first so your stake tx builds on the current tip.
2. Fund the key, then stake ≥ min_stake (10,000 XRGE). The freshly-generated key starts empty — first send ≥ 10,000 XRGE (+ 1 XRGE fee) to the validator address, then submit the stake tx from that key and wait for it to be included in a block. (Staking from an unfunded key fails on the fee/balance check.) This is the step that puts your key into the on-chain validator set that every peer derives.
3. Confirm you are in the active set before mining:

   rougechain --node-keys ~/.quantum-vault/mainnet/node-keys.json validator-status
   

   You want ✓ Staked and ✓ In active set. Do not skip this — it is the difference between "my blocks are accepted" and "my blocks are silently rejected by every peer."
4. Only now start --mine — and make the node reachable. Start with --mine and a public URL (--public-url https://…) that peers can reach over HTTPS, exactly as Becoming a Validator Step 4 shows. Peers talk to each other over the REST API; there is no separate P2P port. Being staked makes you eligible: your node votes toward each block's commit certificate, and it proposes only while it is the designated proposer (the largest stake). Being reachable is what lets your votes and blocks propagate.

Do these out of order — mine with a key that is not staked, or not the designated proposer — and your node produces nothing: it logs not the designated proposer for height <h> … — not sealing and peers would reject any such block anyway. That, not a height cliff, is the real thing to understand.

Detecting the failure mode

Symptoms fall into two distinct buckets — don't conflate them:

Your key isn't staked / not in the active set (fix: stake it, or point the node at the staked key's node-keys.json):

• validator-status shows ✗ on Staked or In active set — the fix is printed next to it (usually: stake, top up, or wait for the stake tx to confirm).
• Peers log the rejection on the P2P import path — the inner error is Block <h> rejected: proposer <pk> not in validator set with active stake (where <pk> is the first 16 hex chars of the key), wrapped as [peer] Failed to import block <h>: ….

You are staked and in the active set, but your node never proposes. This is expected unless you hold the most stake. Your miner logs not the designated proposer for height <h> (designated: <pk>) — not sealing, and GET /api/stats shows designated_proposer_next. If a block from you does reach peers while another validator is designated, they reject it with proposer <pk> is not the designated proposer (<pk>). Staked validators still earn their stake-weighted share of fees in every block (see Rewards).

designated_proposer_next in /api/stats and proposer in GET /api/selection both name the designated proposer for the next height.

You are the designated proposer but blocks don't appear, or your node falls behind. Check reachability and finality:

• --public-url is not set, or points somewhere peers can't reach.
• The API port behind your proxy is firewalled, or you have no connected peers.
• Your miner logs waiting for the commit certificate of block <h> before sealing …: validators holding ⅔ of the stake have not voted for the tip yet, so no node can extend it.
• You've been jailed — jailed validators are out of the active set until the jail window passes. (Automatic missed-block slashing and jailing are frozen from height 100.)

Block acceptance itself has no reachability component (it's proposer-auth, the designated-proposer rule, the parent commit certificate, signatures, hash and state), so with green validator-status checks a node that is designated but not propagating points at the network, not the stake.

Constraints worth knowing

• min_stake: 10,000 XRGE, enforced by the stake CLI/RPC submission path (top-ups must each be ≥ 10,000; totals accumulate). Note this is a submission-time guard, not a consensus-level rejection.
• Active-set membership is stake > 0 and not-jailed — there is no minimum-stake threshold for being in the set. The 10,000 figure is an API-side minimum, not a membership cutoff; a validator with 0 < stake < 10,000 is still in the set. Which member proposes is decided by the designated-proposer rule (most stake), not by membership alone.
• max_validators (100 in genesis) is a declared parameter but is not currently enforced in the selection/sync path — every stake > 0, non-jailed validator is in the active set. Do not assume a top-100 cutoff exists today.
• One node per key. Two nodes signing with the same key is equivocation; slashing on equivocation evidence is planned, not active (see Becoming a Validator → Security & slashing).
• Unbonding is 500 blocks after unstake (blocks are only produced when there are transactions, so the wall-clock time depends on network activity); dropping to 0 stake (or being jailed) is what removes you from the active set.
• Slashing, key security, and public-node hardening are covered in Becoming a Validator → Security & slashing.

A note for anyone reading the source

The proposer key and the staking key are the same key (enforced by the gate above). If you're spelunking the daemon, ignore the stale comment in rebuild_proposer_counts that says "Block headers use node ephemeral keys as proposer, not validator staking keys" — that's legacy accounting for a misconfigured node, not a supported "node key ≠ stake key" mode. produce_block sets proposer_pub_key to the node's own key, and import_block requires that key to be staked (and, from height 100, to be the designated proposer).

Changing PROPOSER_AUTH_ACTIVATION_HEIGHT

The 100 is a protocol constant on the sync path, not a knob to tune per deployment. Changing its value changes which blocks a syncing node accepts, so a change must be rolled out like a coordinated fork — every node running the new value before any chain crosses the affected height — exactly as with V2_FORK_HEIGHT. Do not edit it casually.

See also

• Becoming a Validator — full operator walkthrough
• Staking Overview
• Running a Node
• Public-node security

Staking Rewards

Validators earn a share of the transaction fees in every block on RougeChain.

Reward Sources

There is no fixed block reward: validator income comes only from fees. The minimum-tip subsidy described below exists in the code but pays nothing on mainnet, because its reserve is empty.

How Rewards Work

1. The designated proposer (the eligible validator with the most stake) proposes a block when there are pending transactions
2. The proposer assembles pending transactions; each transaction's full signed fee is debited from its sender
3. Fees are split, not paid entirely to the proposer: up to half of the base fee per transaction is burned (burned = min(total fees, base fee × tx count ÷ 2)), and the remaining tip pool is distributed 20% to the proposer, 70% among all staked, non-jailed validators (stake-weighted), and 10% to the treasury. If the tip pool is below 0.1 XRGE the code tops it up from the __staking_rewards__ reserve — which holds 0 XRGE on mainnet (2026-10-06; it was never funded), so no top-up happens. Every validator in the set is paid its stake-weighted share whether or not it voted on the block.
4. Rewards are credited when the block is applied to state

Fee Structure

These are the fees the node binds to each signed transaction type (core/daemon/src/v2_binding.rs).

The tip portion of these fees (after the base-fee burn) is split across the proposer, all validators (stake-weighted), and the treasury — see How Rewards Work. Swap fees go to liquidity providers, not validators.

Estimated Returns

Rewards depend on:

• Your stake relative to total staked — determines your share of the 70% validator pool in every block
• Network activity — more transactions = more fees per block
• Whether you are the designated proposer — only the validator with the most stake proposes, and it also receives the 20% proposer share

Example

Your earnings are your ~10% share of the 70% validator pool in every block, whoever proposes it (plus the 20% proposer share only if you are the designated proposer). Blocks are produced as transactions arrive, so daily volume tracks real network activity — on a quiet chain that is low, and there is no fixed "blocks per day." These figures are illustrative, not a yield promise; actual returns vary with usage.

Compounding

Rewards are added to your balance, not your stake. To compound:

1. Periodically stake your accumulated rewards
2. This increases your share of the validator pool
3. Leading to more rewards (and, if your stake becomes the largest, the proposer slot)

Checking Rewards

Via Web UI

Go to the Validators page to see your validator stats including blocks proposed.

Via API

# Check your balance (includes accumulated rewards)
curl "https://testnet.rougechain.io/api/balance/your-public-key"

# Check blocks proposed
curl "https://testnet.rougechain.io/api/validators"

Tax Considerations

Staking rewards may be taxable income in your jurisdiction. Keep records of:

• Amount staked
• Rewards received (block by block)
• Token price at time of receipt
• Unstaking transactions

RougeChain does not provide tax advice. Consult a tax professional.

Finality

RougeChain uses verified BFT finality (FINALITY_V2) since block 150.

What mainnet enforces from block 151: every block header carries parent_commit, a finality certificate for its parent block — ML-DSA-65 precommits from validators holding more than two thirds of total stake, checked against the validator set for that height. A node rejects a block without a valid certificate, and a producer waits for its parent's certificate before building on it. Check any height with GET /api/finality/:height.

What Release 2a does not include: a fallback proposer, skip certificates, rotating proposers and slashing on evidence. Those were planned as "Release 2b" and "Release 3"; on 2026-10-06 they were folded into a broader consensus redesign (Tendermint-style rounds, rotating stake-weighted proposers, a capped active set, a consensus-enforced minimum stake, evidence-based slashing) that is decided but not built — see Status & Roadmap. If the designated proposer is offline, no block is produced until it returns. Three validators are staked and the largest holds more than 99.9 % of the stake, so the ⅔ quorum is currently met by that validator alone. No slashing of any kind is active; the legacy slash transaction is rejected since block 245.

Legacy behavior (blocks 0–149)

Blocks are proposed and signed with ML-DSA-65 by staked validators, and every node validates blocks and state independently. The finalized_height value and the /api/finality and /api/votes endpoints report a node-local, informational finality indicator. In the legacy implementation, votes are not cryptographically verified as a stake-weighted quorum and are not exchanged between validators.

Treat legacy "finalized" as a status display, not as a BFT guarantee. Nothing that moves funds (block validity, the bridge, payouts) depends on it. The production bridge relies on its own checks and confirmation depths instead.

How FINALITY_V2 works

FINALITY_V2 replaces the legacy indicator with verifiable finality:

• Verified votes. Each vote is an ML-DSA-65 signature by the validator's own staked key over a domain-separated message (chain id, vote type, height, round, block hash).
• Recomputed quorum. A finality proof is only valid if the verifier recomputes the stake of the signers against the validator set for that height and it exceeds ⅔ of total stake. Votes for different block hashes never combine. Proofs are self-verifying, so a node can check a proof received from any peer.
• Durable anti-equivocation journal. Before signing, a validator durably records the vote. After a crash or restart it will refuse to sign a conflicting vote for the same height and round.
• Validator-set provenance. The validator set used for a height is derived by deterministic replay from a pinned base, not taken from a peer's claim.
• Automatic vote propagation. Votes are gossiped between validators with bounded, rate-limited intake, and finality proofs are distributed to non-validators.
• Operator preflight. --finality-v2-preflight checks that a node's key is the staked validator key before activation.

FINALITY_V2 is a coordinated validator upgrade, tested on multi-node devnets before activation. It went live at block 150 (2026-09-28). It is a prerequisite of the V3 XRGE bridge, which only signs withdrawal roots for finalized blocks; V3 itself is not activated.

Bridge Overview

Status (2026-10-06): the R1 production bridge is LIVE on Base mainnet. XRGE, qETH and qUSDC paths have been tested end-to-end. ETH and USDC deposits through the site go through the RougeBridge contract's depositETH / depositERC20 and are claimed automatically (paused for a few days and reopened 2026-10-05); the manual claim route is closed at the public endpoint. The bridge is operator-run (deposit watcher, relayers, bridge_mint key) and has not been externally audited. Base-side authorization is classical: XRGE uses a Safe multisig plus a capped relayer key; qETH/qUSDC (RougeBridge) use a single operator owner/release key, with a 2-of-3 Safe multisig guardian that can pause the bridge and cancel queued large releases. The post-quantum V3 XRGE bridge is built but NOT activated — see V3 Post-Quantum XRGE Bridge and Status & Roadmap.

RougeChain has two separate bridge systems:

The rest of this page describes the Base bridge.

RougeChain supports bridging assets between Base mainnet (EVM, chain id 8453) and the RougeChain L1 network. The bridge uses a lock-and-mint / burn-and-release model with a dedicated smart contract. (Base Sepolia, chain id 84532, is supported for testing via BASE_CHAIN=sepolia.)

Supported Assets

XRGE uses the BridgeVaultV2 contract; ETH and USDC use the RougeBridge contract.

How It Works

Deposit (EVM → RougeChain)

1. User deposits ETH or USDC into RougeBridge, or XRGE into BridgeVaultV2, on Base
2. The deposit watcher in the relayer detects the deposit event and auto-claims it on L1 — the node verifies the deposit on-chain and mints the L1 asset (qETH, qUSDC or XRGE) to the recipient encoded in the deposit. No manual step is required.
3. The manual claim endpoint still exists in the node (and claims are deduped, so an auto- and a manual claim of one deposit cannot double-mint), but on the public mainnet endpoint it is closed at the reverse proxy; it is an operator fallback, not a user step.

Every claim is verified against the actual on-chain Base deposit (the Transfer to the custody contract / vault) — never a caller-supplied amount — and requires a valid EVM signature plus a confirmation depth (QV_BRIDGE_MIN_CONFIRMATIONS, default 6) before minting.

Withdrawal (RougeChain → EVM)

1. User submits a signed bridge_withdraw transaction on RougeChain, burning the wrapped token
2. The withdrawal is recorded in the pending withdrawals store with its owner key, token, and status
3. The bridge relayer polls for pending withdrawals and releases the corresponding asset on Base
4. Each withdrawal is paid at most once, and fulfillment is re-verified on Base at confirmation depth. If a release keeps failing, the relayer reports it and the withdrawal is handled by the operators. Automatic refunds are disabled in production as part of the R1 hardening; status (pending / failed / refunded) is exposed via the API and the Bridge page.

Security

See Bridge Security Model for the full trust model. In short:

• Client-side signing — Private keys never leave the browser. Withdraw transactions are signed locally using ML-DSA-65
• Classical Base-side authorization — releases on Base are authorized by ECDSA keys (capped hot relayer under a Safe multisig). This is hardened but not post-quantum; V3 changes it for XRGE only, once activated
• RougeBridge contract — Pausable, with guardian role for emergencies, timelock on large withdrawals
• Relayer authentication — The relayer uses a BRIDGE_RELAYER_SECRET for API authentication
• Replay protection — Claimed transaction hashes are persisted to prevent double-claims; refunds use a refund:<txId> key so they can't be issued twice
• EVM signature verification — manual ETH claims require an EVM personal_sign; auto-claims re-verify the deposit tx on-chain (sender, amount, confirmations)

Architecture

Base mainnet (EVM)              RougeChain L1
┌──────────────────┐           ┌──────────────────┐
│  RougeBridge.sol │  deposit  │  Node Daemon     │
│  - depositETH() │──watcher─▶│  - /deposit/      │
│  - depositERC20()│           │      auto-claim   │
│  - releaseETH() │◀─relayer──│  - /bridge/withdraw│
│  - releaseERC20()│  release  │  - withdraw store │
│  BridgeVaultV2   │           │  - /…/refund      │
│  - deposit()     │──watcher─▶│  - /bridge/xrge/* │
│  - release()     │◀─relayer──│                  │
└──────────────────┘           └──────────────────┘
       deposit watcher: Base → L1 auto-claim
       relayer release + refund: L1 → Base

XRGE Bridge

Bridge XRGE tokens between Base mainnet and RougeChain L1 using the BridgeVaultV2 contract.

Status: LIVE (hardened R1 bridge), tested end-to-end. Releases on Base are authorized with classical keys (a capped relayer key under a Safe 2-of-3 multisig). The post-quantum V3 XRGE bridge is built but not activated; nothing on this page uses it.

Overview

Unlike qETH/qUSDC (which are wrapped assets), XRGE is the native token of RougeChain. The XRGE bridge allows moving XRGE between its ERC-20 representation on Base and the L1 network.

XRGE token on Base mainnet: 0x147120faEC9277ec02d957584CFCD92B56A24317 BridgeVaultV2: 0x7BB10752E99e8872d7D2DE5D92bfd43cd935Cd2D

Amounts on RougeChain are whole XRGE; the ERC-20 uses 18 decimals.

Deposit (Base XRGE → L1 XRGE)

1. Approve the BridgeVaultV2 contract to spend your XRGE
2. Call deposit(amount, rougechainPubkey) on the vault
3. The vault locks your XRGE and emits a BridgeDeposit event carrying your L1 key
4. The relayer's deposit watcher detects the event and auto-claims it — XRGE is credited to your L1 wallet after the node verifies the on-chain transfer. No manual claim is needed.

The manual fallback endpoint /api/bridge/xrge/claim requires an evmSignature (sign the claim message with the wallet that sent the XRGE) and ignores any caller-supplied amount — the amount and depositor are derived from the actual on-chain Transfer(from → vault) log emitted by the XRGE token, and the deposit must reach the required confirmation depth (QV_BRIDGE_MIN_CONFIRMATIONS, default 6) before it mints.

Withdraw (L1 XRGE → Base XRGE)

1. Go to the Bridge page and use the XRGE Bridge Out tab
2. Enter the amount and your Base EVM address
3. Submit the signed withdrawal
4. The relayer calls release() on the vault to unlock your XRGE on Base, within the vault's per-transaction and daily caps. Each withdrawal is paid at most once.
5. If a release can't be completed, it is reported and handled by the operators. Automatic refunds are disabled in production. Status is shown on the Bridge page.

BridgeVaultV2 Contract

A lock-and-release contract owned by a Safe multisig (2-of-3), with a separate capped relayer role:

• deposit(amount, rougechainPubkey) — Lock XRGE, emit event for relayer
• release(to, amount, l1TxId) — relayer role only, within per-transaction and rolling daily caps, while unpaused
• vaultBalance() — View how much XRGE the vault holds
• Emergency withdrawal — multisig only, behind a 48-hour timelock

Liquidity in the vault = total XRGE locked by depositors minus released amounts.

ETH Bridge (qETH)

Bridge ETH from Base mainnet to RougeChain as qETH, and back.

Status: LIVE (hardened R1 bridge), tested end-to-end; deposits reopened 2026-10-05 through the contract's depositETH with automatic claiming. qETH uses classical Base-side authorization (the RougeBridge owner and release key is a single operator hot key; unaudited) and is outside the scope of the V3 post-quantum XRGE bridge.

Deposit (ETH → qETH)

Step 1: Send ETH to the Bridge

Connect your MetaMask (or other EVM wallet) to Base and call depositETH(rougechainPubkey) on the RougeBridge contract (the Bridge page does this for you), passing your RougeChain public key. This emits a BridgeDepositETH event carrying your recipient key.

Step 2: Automatic claim

The relayer's deposit watcher sees the event and claims it for you — qETH is minted to the RougeChain key you encoded in the deposit, once the deposit reaches the required confirmation depth (QV_BRIDGE_MIN_CONFIRMATIONS, default 6 Base confirmations). No manual claim step is needed.

The node verifies before minting:

• The transaction exists on Base and was sent to the correct contract
• The amount and sender match the deposit
• The transaction has at least the required confirmation depth (default 6)
• It hasn't been claimed before (auto-claim and manual claim share one dedup store)

Manual claim: the node's manual claim route (POST /api/bridge/claim, which needs a signature from the depositing EVM wallet) is closed at the public mainnet endpoint. A deposit that the watcher has not credited is handled by the operators; the Bridge page tracks the deposit until it is credited.

Conversion Rate

1 ETH = 1,000,000 qETH units (6 decimal precision). Deposit amounts should be multiples of 0.000001 ETH (1e12 wei); smaller remainders cannot be represented on L1.

For example, depositing 0.01 ETH gives you 10,000 qETH units.

Withdraw (qETH → ETH)

1. Go to the Bridge page and select the Bridge Out tab
2. Select ETH as the token
3. Enter the amount of qETH to bridge out
4. Enter the Base address to receive ETH
5. Click Bridge Out

The transaction is signed client-side (your private key never leaves the browser), then:

• qETH is burned on RougeChain
• A pending withdrawal is created
• The bridge relayer picks it up and sends ETH to your EVM address
• Release status (pending / failed / refunded) shows on the Bridge page. Automatic refunds are disabled in production; a release that can't be completed is handled by the operators.

A 0.1 XRGE fee is charged for the withdrawal transaction.

Fees

USDC Bridge (qUSDC)

Status: LIVE (hardened R1 bridge), tested end-to-end; deposits reopened 2026-10-05 through the contract's depositERC20 with automatic claiming (the manual claim route is closed at the public endpoint). qUSDC uses classical Base-side authorization (single operator hot key; unaudited) and is outside the scope of the V3 post-quantum XRGE bridge.

qUSDC is a 1:1 representation of USDC on Base mainnet on RougeChain, with 6 decimals. It uses the same RougeBridge contract as qETH (0x0c09C764AdC024497729cd452ECfeE8869d35d83).

USDC on Base mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Deposit (USDC → qUSDC)

1. Approve RougeBridge to spend your USDC.
2. Call depositERC20(usdc, amount, rougechainPubkey) (the Bridge page does this for you).
3. The relayer's deposit watcher claims the deposit automatically once it reaches the required confirmation depth (default 6). The node verifies the on-chain deposit before minting qUSDC.

Withdraw (qUSDC → USDC)

1. On the Bridge page choose Bridge Out and select USDC.
2. Enter the amount and your Base address, then submit the signed withdrawal.
3. qUSDC is burned on RougeChain and the relayer releases USDC on Base. Each withdrawal is paid at most once. Automatic refunds are disabled in production; failed releases are handled by the operators.

See Bridge Security Model.

Bitcoin Bridge (BTC ⇄ qBTC)

Status (2026-10-06): deposits live, withdrawals switched off. The Bitcoin bridge is independent of the Base bridge (R1) and is not part of the V3 XRGE bridge. On mainnet, BTC → qBTC deposits are verified and credited. qBTC → BTC withdrawals are disabled in the site because the Bitcoin relayer has been stopped since the F49 upgrade while a hardening of its payout path awaits deployment; a withdrawal submitted directly to the API would wait unpaid until the relayer is reopened. Do not send significant value; check Status & Roadmap.

Bridges native Bitcoin to qBTC on RougeChain L1 and back. qBTC held on RougeChain is controlled by ML-DSA-65 keys. The BTC backing it sits in a Bitcoin custody address protected by Bitcoin's own (classical) signatures, so the bridge custody itself is not post-quantum.

qBTC uses 8 decimals — 1 on-chain unit = 1 satoshi.

Why it's built differently from the ETH/USDC bridges

Bitcoin has no event logs and no EVM signatures, so none of the eth_getLogs / ECDSA machinery applies. Two design choices carry the security:

1. Recipient binding. Every deposit is bound to a RougeChain recipient before any qBTC is minted, in one of two ways:
   • Per-user deposit address (default). Each RougeChain address is assigned its own Bitcoin deposit address, stable per recipient. These addresses are derived (BIP84) from the BTC relayer's HD wallet and registered with the daemon, which only stores the address ↔ recipient binding and watches it. Send from any wallet, no OP_RETURN needed.
   • OP_RETURN fallback. A depositor sends to the custody address and writes their RougeChain address into an OP_RETURN output of that same transaction. The binding is baked into a signed Bitcoin transaction, so knowing a txid does not let anyone redirect the mint.
2. Two-provider cross-check. Every deposit is verified against two independent Esplora providers (mempool.space + blockstream.info by default). Both must agree on the custody amount and the recipient and both must meet the confirmation depth, so no single API can fabricate a deposit. If a provider is unreachable the daemon fails closed (the claim is idempotent and pollable, so an outage only delays).

The daemon holds no Bitcoin key. It only watches the custody address and the assigned deposit addresses. The hot keys (custody and the HD deposit wallet) live only in the external BTC relayer, which sweeps deposit addresses into custody and pays withdrawals out; the daemon then re-verifies each payout on the Bitcoin chain before marking it fulfilled.

Deposit flow (BTC → qBTC)

Per-user deposit address

1. The frontend calls POST /api/bridge/btc/deposit-address { recipient } with the user's RougeChain address and gets back that recipient's deposit address (the same one every time).
2. User sends BTC to it from any wallet — no OP_RETURN.
3. The daemon polls assigned addresses, cross-checks each deposit on both providers, and once it has the required confirmations mints qBTC (sats) to the bound recipient. No claim call is needed. Dedupe key: btcaddr:{txid}:{vout}.

OP_RETURN fallback

1. User sends BTC to the custody address with an OP_RETURN output containing their RougeChain address. (Wallets that support OP_RETURN: Sparrow, Electrum, BlueWallet advanced, bitcoinjs.)
2. User submits the txid to POST /api/bridge/btc/claim { btcTxid, recipientRougechainPubkey? }. The frontend polls this until it succeeds.
3. The daemon cross-checks both providers, then mints qBTC (sats) to the OP_RETURN recipient. Dedupe key: btc:{txid}.

Withdraw flow (qBTC → BTC)

1. User burns qBTC via POST /api/bridge/withdraw with tokenSymbol: "qBTC", evmAddress: <destination BTC address>, amountUnits: <sats> (signed). Amounts below the minimum (btcMinWithdrawSats, default 2 000 sats) are rejected before anything is burned.
2. The withdrawal appears in GET /api/bridge/btc/withdrawals. The BTC relayer (scripts/btc-bridge-relayer.ts) builds, signs, and broadcasts the Bitcoin payout from custody, sending the destination the burned amount minus the payout's Bitcoin network fee.
3. Once confirmed, the relayer calls DELETE /api/bridge/btc/withdrawals/:txId { btcTxid }. The daemon verifies the payout on-chain (custody-funded, enough confirmations, and paid the recipient the owed sats minus at most the capped network fee) before marking it fulfilled.

Fees and minimum

The withdrawer pays the Bitcoin network fee. For a withdrawal of N sats the relayer builds a payout transaction and sends the destination N − fee, where fee is that transaction's real network fee (its virtual size × the current fee rate, rounded up). Custody's change is inputs − N, so custody's balance falls by exactly the N sats that were burned.

Example: a 5 000-sat withdrawal at 1 sat/vB. A typical payout (one custody input, destination + change outputs) is 141 vB, so the fee is 141 sats and the destination receives 4 859 sats.

The site shows an estimate of the fee (mempool.space rate × ~141 vB) and "you receive ≈ amount − fee"; the exact fee depends on the transaction the relayer builds.

Node verification rule. A payout is accepted when it is funded by custody, has the required confirmations, pays the destination a non-zero amount, and either pays the full owed amount (the pre-fee-policy form, still accepted) or paid + fee ≥ owed with fee ≤ the cap. The node computes fee itself from the Bitcoin transaction data (sum of inputs minus sum of outputs, cross-checked against the provider's reported fee); it never takes the fee from the relayer.

Operators

Deployment and operations notes for the BTC relayer live in the repository's scripts/README.md.

Bridge Security Model

This page states plainly who can authorize what, today and under V3. See Status & Roadmap for what is live.

Today: the hardened R1 bridge (LIVE)

The trust assumption: releases on Base are authorized by classical ECDSA keys (the relayer key and the Safe owners). These are conventional, quantum-vulnerable signatures. The R1 bridge limits the damage a compromised relayer key can do (caps, pause, multisig control), but it does not make the Base side post-quantum. The bridge is also operated by a small team, not a decentralized set.

V3 (NOT ACTIVATED): XRGE only

V3 moves XRGE release authorization to an M-of-N ML-DSA-65 authority verified on-chain, on top of verified RougeChain finality. Classical keys keep only limited roles (pausing, and actions that are themselves gated by the post-quantum authority). Details: V3 Post-Quantum XRGE Bridge, Authority Rotation.

What V3 does not fix

• Base itself, the XRGE ERC-20, and users' EVM wallets use classical cryptography.
• qETH/qUSDC custody remains classical.
• Bitcoin custody uses Bitcoin's own (classical) signatures.
• V3 is unaudited until the external review completes.

V3 Post-Quantum XRGE Bridge

Status: AUDIT CANDIDATE — NOT ACTIVATED. BridgeVaultV3 is not deployed to Base mainnet and does not hold any XRGE. The production XRGE bridge is the R1 bridge described in XRGE Bridge. See Status & Roadmap.

What V3 changes

Today, XRGE is released on Base by a classical (ECDSA) relayer key under a Safe multisig. V3 replaces that authorization with ML-DSA-65 (FIPS 204) signatures verified on-chain on Base:

1. RougeChain finalizes blocks with verified validator votes (FINALITY_V2).
2. Finalized XRGE withdrawals are grouped into epochs. Each epoch has a deterministic Merkle root that any node can recompute from chain history.
3. An M-of-N post-quantum root authority signs the epoch root with ML-DSA-65. Each authority member independently reconstructs the root from finalized history before signing — a member never signs a root just because another machine supplied the hash.
4. BridgeVaultV3 accepts the root only if an on-chain verifier confirms the threshold of ML-DSA-65 signatures. No ECDSA signature, pairing check or SNARK wrapper is in the authorization path.
5. A user (or anyone on their behalf) releases XRGE with a Merkle proof against an accepted root. Each withdrawal can be released once.

The intended property: an attacker who holds every classical Base-side key (Safe, guardian, relayer, servers) but not the post-quantum authority threshold cannot get a forged root accepted, move XRGE, or weaken the vault's controls.

Verifier architecture (table-in-proof)

• The verifier contract is immutable and stateless (no owner, no upgrade path).
• Authority public keys live in immutable, content-addressed authority tables on Base. The proof names the table it uses; the vault stores only a commitment to the current authority set.
• Keys are held in canonical (sorted) order, and signer indexes must be strictly increasing, so a proof has one valid encoding.

What has been done

• Vault, verifier and ML-DSA-65 core are frozen as Audit Candidate 1 with pinned compilers, vendored dependencies and a byte-for-byte reproducible build.
• Test coverage includes NIST ACVP ML-DSA-65 vectors, cross-language differential tests (Rust ⇄ JavaScript ⇄ EVM), malformed-proof and attack suites, and end-to-end 2-of-3 and 3-of-5 runs with the real Rust signer.
• The exact audit-candidate bytecode was deployed and exercised on a local OP-stack devnet (real op-geth / op-node), using throwaway keys and a throwaway ERC-20. Measured gas is about 3.4M (2-of-3) to 5.0M (3-of-5) per root verification.

What has NOT been done

• No external audit yet.
• No deployment to Base mainnet (or any public network).
• No production authority keys; the authority size (e.g. 2-of-3 vs 3-of-5) is not decided.
• No activation height chosen; no XRGE migrated.

Out of scope

• qETH and qUSDC stay on RougeBridge with classical Base-side authorization.
• Bitcoin / qBTC is a separate bridge and is not part of V3.

Known limitations (to be reviewed by auditors)

• The Keccak-f[1600] helper used by the verifier is third-party raw EVM bytecode with no high-level source; it is pinned by code hash and covered by behavioural tests only.
• The ML-DSA-65 core is third-party assembly close to the EVM contract size limit.
• RougeChain validator stake is currently concentrated, which limits what finality proves.

Authority Rotation (V3)

Status: BUILT AND TESTED — NOT IN USE. This describes the V3 XRGE bridge, which is not activated. No production authority exists yet.

The V3 post-quantum root authority is an M-of-N set of ML-DSA-65 keys. Rotation replaces that set without upgrading any contract.

Design

• The vault and verifier are immutable. The vault stores a commitment to the current authority set (version, threshold and member key hashes).
• A new set is published as a new immutable authority table on Base, together with the pre-expanded key data the verifier needs.
• The current authority signs a rotation to the new commitment with ML-DSA-65. The vault enforces a 48-hour timelock between proposing and executing a rotation.
• A rotation manifest binds the Base-side rotation to a RougeChain-side authority schedule record, so every node derives the same "which authority signs which epoch" answer from chain history.

Safety checks before anything is signed

• The rotation signer reconstructs the new set commitment from the actual keys and the on-chain table contents before signing; it does not sign a supplied hash.
• Every member of the new set must take part in the ceremony, and at least two independent checkers must confirm the on-chain tables match the intended keys.
• A durable signing journal prevents signing two different rotations for the same version.
• Root signing for an epoch is refused until the matching schedule record and Base-side state are both observed (publication gate).

Known hazard

The vault cannot check that a new commitment is well-formed. A rotation to a wrong commitment would leave the new authority unable to sign (the bridge fails closed — funds cannot move, but they are not exposed). The checks above exist to prevent this, and the design is flagged for external review.

Rehearsal status

Rotation has been rehearsed in tests and proposed on a local OP-stack devnet. Execution after the real 48-hour timelock is the remaining rehearsal step.

RougeBridge Contract

The RougeBridge.sol contract is a multi-asset bridge contract deployed on Base mainnet (0x0c09C764AdC024497729cd452ECfeE8869d35d83) that handles ETH and ERC-20 deposits/releases with enhanced security features.

Features

• Multi-token support — ETH and any ERC-20 token (USDC, etc.)
• Pausable — Guardian can pause all operations in emergencies
• Timelock — Large withdrawals require a delay period before execution
• Guardian role — Separate from owner; can pause but cannot withdraw
• Replay protection — Processed L1 transaction IDs are tracked to prevent double-releases
• Ownership — The RougeBridge owner is currently a single operator key, not a multisig; that key also performs releases. The guardian role is held by a 2-of-3 Safe multisig, which can pause the bridge and cancel queued large releases. Other protections include the 24-hour timelock on large releases and daemon-side controls. Migrating ownership to multisig control is a planned security improvement.

Key Functions

Deposits

function depositETH(string calldata rougechainPubkey) external payable;
function depositERC20(address token, uint256 amount, string calldata rougechainPubkey) external;

Users call these to lock assets in the contract. Events are emitted for the relayer to pick up.

Releases (Owner Only)

function releaseETH(address to, uint256 amount, bytes32 l1TxId) external;
function releaseERC20(address token, address to, uint256 amount, bytes32 l1TxId) external;

The relayer (owner) calls these to release assets when a user burns their wrapped tokens on L1. If the amount exceeds largeWithdrawalThreshold, a timelock is queued instead.

Timelock

function executeTimelock(uint256 requestId) external;  // Owner, after delay
function cancelTimelock(uint256 requestId) external;    // Guardian

Large releases are queued with a configurable delay (default 24 hours). The guardian can cancel suspicious requests during the delay window.

Admin

function pause() external;                              // Guardian or Owner
function unpause() external;                             // Owner only
function setGuardian(address newGuardian) external;      // Owner
function setSupportedToken(address token, bool) external;// Owner
function setLargeWithdrawalThreshold(uint256) external;  // Owner

Events

Deployment

The XRGE bridge is live on Base mainnet (chain ID 8453) as BridgeVaultV2 at 0x7BB10752E99e8872d7D2DE5D92bfd43cd935Cd2D. Its owner is a Gnosis Safe multisig (2-of-3) — no single key can move or drain the vault. Routine releases are signed by a separate hot relayer key that may only call release() within on-chain per-transaction and rolling daily caps and only while unpaused; the multisig alone can rotate that key, change the caps, pause, or (behind a 48-hour timelock) emergency-withdraw. The ETH/USDC custody contract is at 0x0c09C764AdC024497729cd452ECfeE8869d35d83. Base Sepolia (chain ID 84532) is used only for testing.

BridgeVaultV3 (post-quantum XRGE vault) is not deployed on Base mainnet. See V3 Post-Quantum XRGE Bridge.

Migration note: the previous single-owner XRGE vault (0xb3f5…bFAb5) is being retired in favor of BridgeVaultV2; do not deposit to the old address.

Daemon Withdraw Guardrails

Independent of the on-chain contracts, the RougeChain daemon enforces its own withdraw controls (an operator pause, a per-transaction cap, and a required Base confirmation depth for deposit claims, default 6). Operator configuration is documented in the repository's scripts/README.md.

Bridge Relayer

The bridge relayer is an off-chain process that connects RougeChain L1 with Base. It fulfills withdrawals (L1 → Base), watches for deposits to auto-claim (Base → L1), and can refund withdrawals that cannot be released (disabled in production).

For the full configuration table and operational notes, see scripts/README.md.

How It Works

1. Polls the node for pending ETH, USDC and XRGE withdrawals and releases the corresponding asset on Base
2. Marks each release fulfilled; on repeated failure, reports it. Auto-refund exists but is disabled in production (AUTO_REFUND=false)
3. Deposit watcher: scans the bridge contracts for deposit events and auto-claims them on L1
4. Alerts (console + optional webhook) on repeated failures

Running the Relayer

The relayer and the daemon share bridge-relayer.env (copy from bridge-relayer.env.example):

# Key variables (see bridge-relayer.env.example for the full list)
CORE_API_URL="http://localhost:5100"
BRIDGE_CUSTODY_PRIVATE_KEY="0x..."   # EVM private key for the bridge wallet
BRIDGE_RELAYER_SECRET="your-secret"  # Shared secret for API authentication
BASE_CHAIN="mainnet"
BASE_RPC_URL="https://mainnet.base.org"   # NOTE: var name is BASE_RPC_URL
ROUGE_BRIDGE_ADDRESS="0x..."         # RougeBridge contract address
XRGE_BRIDGE_VAULT="0x..."            # BridgeVaultV2 contract address
AUTO_REFUND="false"                  # Production setting: failed withdrawals are handled manually
DEPOSIT_WATCHER="true"               # Auto-claim deposits
# ALERT_WEBHOOK_URL=                 # Optional Slack/Discord webhook

# Run as a singleton under a process supervisor — never run two relayers against one wallet
npx tsx scripts/bridge-relayer.ts

Authentication

The relayer authenticates with the node using the BRIDGE_RELAYER_SECRET environment variable. This is sent as the x-bridge-relayer-secret HTTP header when marking withdrawals as fulfilled.

Set the same secret on both the relayer and the node:

# On the node
export BRIDGE_RELAYER_SECRET="your-secret"

# On the relayer
export BRIDGE_RELAYER_SECRET="your-secret"

Contract Mode vs Legacy Mode

• With ROUGE_BRIDGE_ADDRESS — The relayer calls releaseETH() / releaseERC20() on the RougeBridge contract
• Without it — Falls back to raw ETH transfers from the custody wallet (legacy mode)
• With XRGE_BRIDGE_VAULT — Enables XRGE bridge support via the BridgeVault contract

Daemon Withdraw Guardrails

Independent of the on-chain contracts, the RougeChain daemon enforces its own withdraw controls (an operator pause, a per-transaction cap, and a required Base confirmation depth for deposit claims, default 6). Operator configuration is documented in the repository's scripts/README.md.

Security Considerations

• The relayer signs Base transactions with a classical ECDSA key. This is the R1 production design; the V3 XRGE bridge (not activated) removes this key from XRGE authorization

• The relayer's EVM private key should be stored securely (not in code)

• Use a dedicated wallet with limited funds for the relayer

• The RougeBridge owner is currently a single operator key, not a multisig; that key also performs releases. The guardian role is held by a 2-of-3 Safe multisig, which can pause the bridge and cancel queued large releases. Other protections include the 24-hour timelock on large releases and daemon-side controls. Migrating ownership to multisig control is a planned security improvement.

• The BRIDGE_RELAYER_SECRET should be a strong random string

DEX & AMM

RougeChain includes a built-in decentralized exchange (DEX) powered by an Automated Market Maker (AMM) using the constant product formula (x * y = k).

Overview

• Create pools for any token pair
• Swap between tokens with slippage protection
• Provide liquidity and earn fees from trades
• Multi-hop routing for tokens without direct pools

All operations are signed client-side with ML-DSA-65 — your private key never leaves the browser.

Fee Structure

The 0.3% swap fee is distributed to liquidity providers proportional to their share of the pool.

Pool Mechanics

Pools use the Constant Product Market Maker model:

reserve_a × reserve_b = k (constant)

When a user swaps token A for token B:

1. Token A is added to the pool
2. Token B is removed, maintaining the constant product
3. 0.3% fee is taken from the input amount
4. Price impact increases with larger trades relative to pool size

LP Tokens

When you provide liquidity, you receive LP tokens representing your share of the pool. When you remove liquidity, you burn LP tokens and receive your proportional share of both tokens in the pool.

Liquidity Pools

Creating a Pool

To create a new trading pool:

1. Go to the Swap page
2. Click Create Pool
3. Select two tokens (e.g., XRGE / qETH)
4. Enter the initial amounts for each token
5. Click Create Pool

The initial token ratio sets the starting price. A 10 XRGE fee is charged for pool creation.

Adding Liquidity

1. Go to the pool page
2. Click Add Liquidity
3. Enter the amount of one token — the other amount auto-calculates based on the current ratio
4. Confirm the transaction

You receive LP tokens proportional to your contribution.

Removing Liquidity

1. Go to the pool page
2. Click Remove Liquidity
3. Enter the LP token amount to withdraw
4. You receive your proportional share of both tokens

Impermanent Loss

If the price ratio changes significantly from when you deposited, you may experience impermanent loss compared to simply holding the tokens. This is standard AMM behavior.

Pool Stats

Each pool shows:

• Current reserves for both tokens
• Total LP tokens issued
• Your LP share percentage
• 24h volume and fees earned
• Price history chart

Swaps

Making a Swap

1. Go to the Swap page
2. Select the input token and output token
3. Enter the amount to swap
4. Review the quote (output amount, price impact, minimum received)
5. Click Swap

Slippage Protection

Set your maximum slippage tolerance to protect against price movements during your transaction. If the actual output would be less than your minimum, the transaction is rejected.

Default slippage: 0.5%

Price Impact

Price impact shows how much your trade will move the pool price. Large trades relative to pool size have higher price impact.

Multi-Hop Routing

If no direct pool exists between your tokens, the router automatically finds a path through XRGE:

TOKEN_A → XRGE → TOKEN_B

This uses two swaps internally but is handled in a single transaction.

Fees

• 0.3% of the input amount goes to liquidity providers
• 1 XRGE base transaction fee

Token Creation

Create custom tokens on RougeChain. Tokens can be traded on the built-in AMM/DEX.

Overview

Create a Token

Via Web UI

1. Navigate to the Token Explorer page
2. Click Create Token
3. Fill in token details:
   • Name — Full name (e.g., "My Token")
   • Symbol — Ticker symbol (e.g., "MTK")
   • Total Supply — Full supply, minted to you at creation
   • Logo — Upload an image or paste a URL (optional)
4. Confirm and sign the transaction

Uploaded logos are compressed to WebP (max 256×256) and stored on-chain as base64 data URIs. The node rejects an inline data: logo larger than 32 KiB (and a logo URL longer than 2,048 bytes), so for a detailed image host it and paste a URL. Logos display across the wallet, swap, pools, and explorer.

Via SDK

import { RougeChain, Wallet } from "@rougechain/sdk";

const rc = new RougeChain("https://testnet.rougechain.io/api");
const wallet = Wallet.generate();

await rc.createToken(wallet, {
  name: "My Token",
  symbol: "MTK",
  totalSupply: 1_000_000,
  image: "https://example.com/logo.png", // or a data:image/webp;base64,... URI
});

Via v2 API

The request body is the signed envelope { payload, signature, public_key }. The from, timestamp, and nonce fields go inside payload, and from must equal the signing public key.

curl -X POST https://testnet.rougechain.io/api/v2/token/create \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "token_name": "My Token",
      "token_symbol": "MTK",
      "initial_supply": 1000000,
      "image": "https://example.com/logo.png",
      "from": "your-public-key-hex",
      "timestamp": 1706745600000,
      "nonce": "random-hex"
    },
    "signature": "your-ml-dsa65-signature-hex",
    "public_key": "your-public-key-hex"
  }'

Raw-HTTP field names are snake_case: token_name (1–64 chars), token_symbol (1–10 chars, no whitespace, must be unused), initial_supply (> 0), plus optional image and description. The 100 XRGE fee is set by the node regardless of any fee in the payload. There is no decimals field.

Response

{
  "success": true,
  "token_symbol": "MTK",
  "message": "Token creation transaction submitted"
}

The token exists once the transaction is included in a block.

After Creation

Once created, the entire supply is credited to the creator's wallet. You can then:

1. Transfer tokens to other wallets
2. Create a liquidity pool to enable trading
3. Burn tokens by sending to the burn address

Mintable tokens (active since block 235)

Status: LIVE on mainnet since block 235 and on testnet since block 1360 (TOKEN_MINTING). GET /api/stats → upgrade_schedule.token_minting shows the height. On a network where the height has not been reached the node refuses mintable / max_supply on /api/v2/token/create with token minting is not active yet and refuses every /api/v2/token/mint.

A token can be created mintable, with an optional cap. Add to the signed create payload:

Rules (enforced by every node when the transaction is included in a block):

• Only the token's creator (the key that signed the create_token) can mint.
• Only tokens created mintable at or after the activation height can be minted; tokens created earlier stay fixed-supply.
• amount and max_supply are JSON integers (a float or string is refused), at most 9,007,199,254,740,991 (2^53 − 1). A mintable token's initial_supply has the same bound.
• initial_supply + total_minted + amount must stay ≤ max_supply when a cap is set. Burning does not free room: the cap bounds issuance, not circulating supply.
• A mint costs a 1 XRGE fee. A mint that breaks a rule when its block is built is skipped (no fee, no tokens); minting exactly up to the cap is allowed.
• total_minted is updated when the mint is included in a block, not when it is submitted.

# create (from activation)
curl -X POST https://testnet.rougechain.io/api/v2/token/create -H "Content-Type: application/json" -d '{
  "payload": { "token_name": "My Token", "token_symbol": "MTK", "initial_supply": 1000000,
               "mintable": true, "max_supply": 5000000,
               "from": "your-public-key-hex", "timestamp": 1706745600000, "nonce": "random-hex" },
  "signature": "...", "public_key": "your-public-key-hex" }'

# mint (creator only)
curl -X POST https://testnet.rougechain.io/api/v2/token/mint -H "Content-Type: application/json" -d '{
  "payload": { "token_symbol": "MTK", "amount": 250000,
               "from": "your-public-key-hex", "timestamp": 1706745600001, "nonce": "random-hex" },
  "signature": "...", "public_key": "your-public-key-hex" }'

GET /api/token/:symbol/metadata and GET /api/tokens report mintable (true only for a token a block created mintable), max_supply (null = uncapped), total_minted, and for a mintable token initial_supply and mint_enabled_height. GET /api/token/:symbol/holders counts minted supply in total_supply.

With the SDK (1.12.0+)

if (await rc.isTokenMintingActive()) {          // reads /api/stats upgrade_schedule.token_minting
  await rc.createToken(wallet, { name: "My Token", symbol: "MTK", totalSupply: 1_000_000,
                                 mintable: true, maxSupply: 5_000_000 });  // maxSupply optional
  await rc.mintTokens(wallet, { symbol: "MTK", amount: 250_000 });      // signed mint_tokens, 1 XRGE
}

The SDK validates the numbers before signing (integers, maxSupply ≥ totalSupply, at most 2^53 − 1) and returns { success: false, error } instead of posting an invalid request.

On rougechain.io

The Create a token dialog shows a Mintable option (and an optional Max supply) only on a network where the upgrade is active. On a mintable token's page in the Explorer, the token's creator sees Mint more (amount, room left under the cap, 1 XRGE fee); it signs with the local wallet or the connected extension / Qwalla. Everyone sees the initial, minted and max supply.

Creating a Liquidity Pool

To make your token tradeable on the DEX:

curl -X POST https://testnet.rougechain.io/api/v2/pool/create \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "token_a": "XRGE",
      "token_b": "MTK",
      "amount_a": 1000,
      "amount_b": 10000,
      "from": "your-public-key-hex",
      "timestamp": 1706745600001,
      "nonce": "random-hex"
    },
    "signature": "your-signature-hex",
    "public_key": "your-public-key-hex"
  }'

This creates an XRGE/MTK pool with an initial price of 0.1 XRGE per MTK.

Pool creation costs 10 XRGE.

Token Burning

Send tokens to the burn address to permanently remove them from circulation:

XRGE_BURN_0x000000000000000000000000000000000000000000000000000000000000DEAD

Burned amounts are tracked on-chain and queryable via GET /api/burned.

Listing on the DEX

Tokens are automatically listed on the DEX once a liquidity pool is created. Users can then:

• Swap between your token and XRGE
• Add/remove liquidity
• View price charts and pool stats

Token Metadata

Every token has on-chain metadata that the creator can manage:

Updating Metadata

Only the original creator can update metadata:

await rc.updateTokenMetadata(wallet, {
  symbol: "MTK",
  image: "data:image/webp;base64,UklGR...",
  description: "A community token for...",
  website: "https://mytoken.io",
  twitter: "@mytoken",
  discord: "discord.gg/mytoken",
});

Logo images can be:

• URLs — https://..., ipfs://...
• Data URIs — data:image/webp;base64,... (stored directly on-chain, persists forever)

The web UI provides an Upload button that compresses images to WebP and stores them as base64 on-chain.

Token Standards

RougeChain tokens are native protocol-level assets (not smart contract tokens). This means:

• No ERC-20 compatibility (different chain architecture)
• Transfers are first-class transactions
• All token operations are signed with ML-DSA-65
• Quantum-resistant by default

NFTs

RougeChain supports on-chain NFTs with collections, minting, transfers, and marketplace features — all secured by post-quantum cryptography.

Features

• Collections — Create NFT collections with configurable max supply, royalties, and metadata
• Minting — Mint single or batch NFTs with metadata URIs and custom attributes
• Transfers — Send NFTs to any RougeChain address with optional sale price tracking
• Burning — Permanently destroy NFTs
• Locking — Lock individual NFTs to prevent transfers
• Freezing — Freeze entire collections to prevent further minting

Fee Structure

Security

All NFT operations use the v2 signed transaction API — transactions are signed client-side with ML-DSA-65 and verified on-chain. Only collection creators can mint, and only token owners can transfer or burn.

NFT Collections

Creating a Collection

1. Go to the NFT Explorer page
2. Click Create Collection
3. Fill in:
   • Symbol — Short identifier (e.g., "ROGUE")
   • Name — Full collection name
   • Max Supply — Maximum number of NFTs (optional, 0 = unlimited)
   • Royalty — Royalty percentage in basis points (e.g., 500 = 5%)
   • Royalty recipient — (optional) wallet that receives royalties. Defaults to the creator when omitted.
   • Image — Collection cover image URL
   • Description — Collection description
4. Click Create

The collection ID is generated from creator_pubkey:SYMBOL.

Royalties

Set a royaltyBps (basis points — 500 = 5%, 1000 = 10%) when creating a collection to earn on secondary sales. From the CONTRACT_NFT_ROYALTY upgrade, royaltyBps must be an integer from 0 to 10000 (100%); a higher value is rejected at creation.

• When it's paid: on an nft_transfer that declares a salePrice > 0. The royalty is salePrice × royaltyBps / 10000, in XRGE.
• Who pays: the sender (the current owner initiating the transfer). It is deducted from their XRGE balance on top of the 1 XRGE transfer fee.
• Who receives: the collection's royaltyRecipient. If you didn't set one, this is the creator. If you set one at creation, it is that address — a wallet or a contract. The recipient is fixed at creation and cannot be changed afterward.

Routing royalties to another wallet or a contract

Pass royaltyRecipient at creation to send royalties somewhere other than the creator:

• A wallet — for example a shared payout wallet or a treasury. Anything the wallet's owner does with the royalty afterwards (such as splitting it) happens off-chain.
• A contract — for trustless on-chain splits. Since mainnet block 18 contracts hold XRGE and pay it out with their own code, so a royalty-splitter contract (see contracts/royalty_splitter and Contract XRGE custody) can receive royalties and fan them out to collaborators by fixed shares. Deploy the contract first and use its address.

⚠️ The node does not check the recipient address. Royalties sent to a mistyped address, or to a contract that has no way to pay XRGE out, cannot be recovered — only a contract's own code can move its XRGE. Double-check the address, and only use contracts whose payout function you have tested.

Note on enforcement: salePrice is self-declared in the transfer payload — there is no on-chain marketplace escrow. A transfer sent with no salePrice (or 0) pays no royalty. Royalties are honored by marketplaces/apps that populate salePrice, not enforced against every possible transfer.

Collection Properties

Freezing a Collection

Collection creators can freeze their collections to permanently prevent further minting. This is irreversible and signals to holders that the supply is final.

Browsing Collections

The NFT Explorer page shows all collections with their stats, floor price, and total items. Click any collection to view its individual tokens.

Minting & Trading NFTs

Minting

Single Mint

1. Open a collection page
2. Click Mint NFT
3. Enter the token name and optional metadata URI / attributes
4. Click Mint

Only the collection creator can mint new tokens.

Batch Mint

Mint multiple NFTs at once:

1. Open a collection page
2. Click Batch Mint
3. Provide a list of names (and optional URIs for each)
4. Click Mint All

Fee is 5 XRGE per NFT in the batch.

Per-token attributes in a batch mint are applied once the client signs them as the payload's attributes field (one entry per name). @rougechain/sdk 1.11.0 and later do this (rc.nft.batchMint(wallet, { ..., attributes: [...] })); SDK 1.10.0 and earlier, and site builds before this fix, sent them under batchAttributes, which the node ignores, so those batch-minted tokens have no attributes. Upgrade the SDK (or mint individually) if a token needs on-chain attributes.

Token Properties

Each NFT has:

Transferring

1. Open the NFT detail page
2. Click Transfer
3. Enter the recipient's RougeChain address (rouge1...)
4. Optionally set a sale price (for marketplace tracking)
5. Confirm

Locked NFTs cannot be transferred until unlocked by the owner.

Burning

Permanently destroy an NFT:

1. Open the NFT detail page
2. Click Burn
3. Confirm

Only the current owner can burn. This action is irreversible.

Locking

Lock an NFT to prevent it from being transferred:

1. Open the NFT detail page
2. Toggle Lock

Only the owner can lock/unlock their NFTs.

Block Explorer

RougeChain includes a built-in block explorer at rougechain.io for browsing blocks, transactions, addresses, tokens, and NFTs.

Features

• Block details — View block height, hash, timestamp, proposer, and all transactions
• Transaction details — View transaction type, sender, recipient, amount, fee, and status
• Address pages — View any address's balances, token holdings, and transaction history
• Token list — Browse all tokens created on RougeChain
• NFT Explorer — Browse NFT collections and individual tokens
• Global search — Search by address, transaction hash, or block height

Navigation

The explorer is integrated into the main RougeChain web app:

Block Explorer — Blocks

Block List

The Blockchain page shows all blocks in reverse chronological order with:

• Block height (index)
• Block hash (truncated)
• Timestamp
• Number of transactions
• Proposer address

Click any block to view its full details.

Block Detail Page

URL: /block/:height

Shows:

Below the header, all transactions in the block are listed with their type, sender, recipient, amount, and fee.

API

GET /api/blocks              — List all blocks (paginated)
GET /api/block/:height       — Get a specific block by height
GET /api/blocks/summary      — Block summary for charts

Block Explorer — Transactions

Transaction List

The Transactions page shows all transactions across the network with:

• Transaction hash
• Type (transfer, swap, stake, bridge, NFT, etc.)
• Sender and recipient
• Amount
• Block number
• Timestamp

Transaction Detail Page

URL: /tx/:hash

Shows the full transaction details:

Transaction Types

API

GET /api/txs                                    — List recent transactions
GET /api/tx/:hash                               — Get transaction by hash
GET /api/address/:public_key/transactions       — Get transactions for an address

Block Explorer — Addresses

Address Detail Page

URL: /address/:pubkey

Shows comprehensive information for any RougeChain address. Addresses are displayed in the compact rouge1... Bech32m format throughout the UI, derived from the SHA-256 hash of the raw ML-DSA-65 public key.

Balances

• XRGE balance
• All token balances (qETH, qUSDC, custom tokens)
• Staked amount (if any)

Transaction History

Paginated list of all transactions where this address is the sender or recipient, including:

• Transfers
• Swaps
• Staking operations
• Bridge operations
• NFT operations

NFTs Owned

List of all NFTs currently owned by this address, grouped by collection.

API

GET /api/balance/:public_key                    — XRGE balance
GET /api/balance/:public_key/:token_symbol      — Token balance
GET /api/address/:public_key/transactions       — Transaction history (paginated; covers the most recent 500 blocks)
GET /api/nft/owner/:pubkey                      — NFTs owned (hex public key)

Contracts

The Contracts Explorer lets you browse all WASM smart contracts deployed on RougeChain.

Contracts List (/contracts)

The contracts page displays:

• Total Contracts — Number of deployed contracts
• Total WASM Size — Combined bytecode size
• Search — Filter by contract address or deployer
• Sort — By newest, oldest, or size

Each contract card shows its address, deployer, WASM size, and deploy block. Click to view details.

Contract Detail (/contract/:addr)

The contract detail page has three sections:

Contract Information

• Contract address (hex)
• Deployer identity
• Deploy block and transaction
• WASM bytecode size

State Viewer

Live key-value table showing all data in the contract's persistent storage. Updates after each contract call.

Execute Contract

Interactive form to call contract methods directly from the browser:

Results display success/failure status, gas used, and return data.

Transaction Labels

Contract transactions appear throughout the explorer with distinct labels:

The transaction detail page shows a Contract Details card for these transactions with the contract address, method name, gas used, and WASM size.

API Reference

The RougeChain node exposes a REST API on the configured --api-port (default: 5101).

Important: All write operations (POST/PUT/DELETE) require v2 signed requests using ML-DSA-65 client-side signing. Legacy unsigned v1 write endpoints return 410 GONE in production. Private keys never leave your application.

Base URL

Local node:

http://127.0.0.1:5101/api

Public testnet: