Obscura documentation

Everything you need to understand and run Obscura (OBX), a privacy cryptocurrency with a global anonymity set.

Overview

Obscura is a proof-of-work privacy coin that replaces ring signatures with a transparent zk-STARK membership proof over a chain-wide commitment tree and class-group accumulator. Instead of hiding a spend among a small ring of decoys, Obscura proves in zero knowledge that the spent output is a member of the set of all outputs, so the anonymity set is the whole chain and grows with adoption.

• Ticker: OBX · Decimals: 12 (1 OBX = 10¹² atomic units)
• Block time: 120s · Difficulty: LWMA · PoW: RandomX (canonical, KAT-verified — the default build; light mode, ~256 MiB cache per seed epoch) with an epoch PoW seed
• Emission: smooth decreasing reward with a perpetual ~0.6 OBX/block tail; soft cap ≈ 18.4M OBX
• Stack: full node, CLI wallet, standalone miner — pure Go, CGO-free, single static binaries

Privacy model

Four independent layers hide the four things a transaction would otherwise reveal:

• Recipient → stealth addresses. Each output gets a fresh one-time key P = H(r·A)·G + B with tx key R = r·G. Your long-term address never appears on chain. A 1-byte view tag accelerates scanning.
• Amount → confidential transactions. Values live in Pedersen commitments C = a·G + v·H; bit-decomposition range proofs prevent negatives/overflow and a conservation proof shows inputs = outputs + fee.
• Sender → global anonymity set. A transparent zk-STARK proves the spent output is a member of the class-group accumulator of all outputs, with a recipient-secret nullifier (nf=H(nk,rho)) preventing double-spends and binding ownership so a sender can neither steal nor link the spend.
• Origin → network layer. Optional Tor transport and Dandelion++ stem/fluff relay hide which node a transaction came from.

The accumulator (no trusted setup)

The membership accumulator runs over a group of unknown order, with two interchangeable backends:

• Imaginary-quadratic class group — needs no trusted setup whatsoever (no ceremony, no toxic waste).
• RSA-2048, a faster nothing-up-my-sleeve modulus (the RSA challenge number), offered as a transparent alternative backend.

It uses Boneh–Bünz–Fisch techniques: add-only accumulation, Wesolowski proofs of exponentiation (PoE), NI-PoKE2, and hash-to-prime. Membership proofs are constant-size and verify in O(log) work regardless of how large the set grows.

Transactions

A transaction can carry transparent inputs, anonymous inputs, and swap legs, with confidential outputs. Coins are accumulated into an epoch-sharded commitment tree of fixed proof depth; an anonymous spend proves membership against a recent commitment-tree root via a transparent zk-STARK, so verification cost is bounded and there is no decoy selection to leak.

Fork choice is most-cumulative-work with a lowest-hash tie-break, bounded reorg depth, and snapshot/replay reorgs. Median-time-past guards timestamps.

Network privacy

Peers gossip over a hardened protocol (magic + version handshake, read/write deadlines, peer and per-IP caps, ban scoring, PEX auto-discovery).

• Dandelion++ relays new transactions through a private "stem" before "fluffing" them to the whole network, hiding the origin.
• Tor transport routes P2P over a SOCKS5 proxy and can advertise an .onion address, with fail-closed onion-only peer handling.

Quickstart

Build all three binaries (requires Go 1.24+):

go build -o bin/obscura-node   ./cmd/obscura-node
go build -o bin/obscura-wallet ./cmd/obscura-wallet
go build -o bin/obscura-miner  ./cmd/obscura-miner

Create an encrypted wallet, run a mining node, and send a confidential payment:

# 1. create an encrypted wallet (prints a Base58 address)
./bin/obscura-wallet new --passphrase "your secret"

# 2. start a node that mines to that address
./bin/obscura-node --mine --mine-address <your-address>

# 3. check status & balance
./bin/obscura-wallet status
./bin/obscura-wallet balance

# 4. send (auto fee) and back up your seed phrase
./bin/obscura-wallet send --to <addr> --amount 5 --fee auto
./bin/obscura-wallet mnemonic

Wallet CLI reference

All commands accept --wallet FILE (default ~/.obscura/wallet.seed) and, where they talk to a node, --node URL. Encrypted wallets need --passphrase or the OBSCURA_WALLET_PASSPHRASE environment variable.

Keys & addresses

new         [--passphrase P]              create a wallet (encrypts the seed if P given)
mnemonic                                  print the 24-word seed phrase
restore     --mnemonic "words..."         recreate a wallet from a phrase
address                                   print your Base58 address
subaddress                                generate a fresh unlinkable subaddress
uri         [--amount X] [--label L]      print a payment URI (for QR codes)
viewkey                                   export a view key (watch-only)
watch       --viewkey HEX                 create a watch-only wallet
passwd      --new-passphrase NEW          set / rotate the passphrase

Balance & spending

balance     [--node URL]                  show spendable balance
outputs     [--node URL]                  list unspent outputs (coin control)
send        --to ADDR --amount OBX [--fee OBX|auto]
sweep       --to ADDR [--fee OBX]         send the entire balance
history     [--node URL]                  list outgoing payments
bump        --txid T --fee OBX            replace-by-fee a stuck payment

Payment proofs

proof       --txid T                      prove you RECEIVED a payment
proofsent   --txid T                      prove you PAID a payment
checkproof  --address ADDR --proof HEX    verify a proof (offline)

Network & swaps

status      [--node URL]                  node / chain status
feerate     [--node URL]                  suggested fee-per-byte
mempool     [--node URL]                  pending-tx stats
peers       [--node URL]                  connected peers
offers      [--node URL]                  list cross-chain swap offers (OBX<->XNO live; OBX<->BTC planned/disabled)
offer       --give-asset A --give-amount N --get-asset B --get-amount M

Running a node

./bin/obscura-node \
  --datadir ~/.obscura \
  --p2p 0.0.0.0:18080 \
  --rpc 127.0.0.1:18081 \
  --seeds host1:18080,host2:18080 \
  --mine --mine-address <addr> \
  --tor-proxy 127.0.0.1:9050 --onion-address <you>.onion

The node serves the chain, mempool, P2P gossip, JSON-RPC, the swap order book, and external-miner endpoints. --coinbase-maturity is a network parameter all nodes must share (lower it only for devnets).

Mining

Two ways to mine. Built into the node with --mine, or with the standalone miner against any node's RPC:

./bin/obscura-miner --node http://127.0.0.1:18081 --address <your-address>

The miner fetches a block template (/blocktemplate), grinds RandomX PoW, and submits solved blocks (/submitblock), cancelling stale work when the chain advances. These are operator endpoints: a miner on the node's own machine (loopback) needs no auth, while a remote miner must pass the node's token — start the node with OBX_RPC_TOKEN set and run the miner with --token (or the same env var). Mining is currently solo; pools don't exist yet (roadmap).

Cross-chain swaps

Obscura runs trustless OBX<->XNO atomic swaps via a scriptless 2-of-2 adaptor. The OBX leg, the P2P order book, and the Nano (XNO) signer move real value: Obscura plays the scriptable side via adaptor signatures and a timelocked swap output. No bridge, no custodian, no admin. An OBX<->BTC SHA256-HTLC design also exists in the code, but it is gated off: BTC is not in the settleable-asset allowlist, so OBX<->BTC offers cannot be posted, taken, or gossiped, and the pair is not currently takeable.

• Split key material. The maker mints only its own shares (OBX claim share, XNO share, claim nonce) and the taker mints only its own; neither party ever holds the other's secrets. The joint OBX claim key and the joint XNO account are derived from public shares alone, each carrying a Schnorr proof-of-possession so the aggregation is rogue-key-safe.
• Adaptor signatures. The taker's adaptor point is forced to equal its XNO share, so publishing the full OBX claim signature reveals exactly that secret, which lets the maker independently sweep the XNO.
• On-chain swap output. A timelocked OBX output with a claim path (binds the aggregate nonce and adaptor point) before the unlock height, or a refund path (back to the maker) after it.
• Maker funds first. The maker locks OBX before any XNO moves, and the taker verifies that lock on-chain at the agreed terms before locking real XNO. A mismatch or abort strands nothing on either side.
• Decentralized liquidity. A P2P, signed, PoW-stamped, expiring order book (maker/taker, like Haveno/UnstoppableSwap). A settleability gate admits only OBX/XNO offers. No AMM is possible trustlessly across chains.

The handshake settles in order:

1. Init. The taker sends amounts, fee, its public shares and adaptor point to the maker, who verifies the terms (rejecting a fee that differs from its configured fee) and replies with its own public shares.
2. Maker funds OBX. The maker locks the agreed OBX to the joint claim key as a timelocked swap output (refundable to itself after the unlock height) and tells the taker the swap key and unlock height.
3. Taker verifies, then locks XNO. The taker independently confirms the on-chain OBX output (claim key, amount, unlock height, open claim window, bound nonce and adaptor point, maker refund key) and only then locks the real XNO to the joint XNO account.
4. Maker verifies the XNO lock. The maker reads the authoritative on-ledger destination and amount and requires it to pay exactly the joint account the exact agreed amount before co-signing.
5. Taker claims OBX. The taker pre-signs its half of the 2-of-2 claim; the maker verifies that half (with a nonce-reuse guard that refuses a second core hash) and releases its half. The taker adapts in its XNO secret, mines the full OBX claim, and receives the OBX. Publishing that signature reveals the secret.
6. Maker sweeps XNO. The maker recovers independently by scraping the on-chain claim signature, extracting the revealed secret, and sweeping the XNO to its destination. The optional completion relay is only a latency hint, drained and ignored; a withholding taker cannot freeze the maker's XNO.

Refund and abort are safe by construction. The maker's locked OBX is protected by the on-chain refund timelock, armed only once the unlock height passes with no claim mined; the watcher always prefers sweeping while a claim is still possible. The taker locks nothing unless the OBX is provably locked at the agreed terms. Swap state is persisted per phase, so a crashed maker resumes its sweep-or-refund watcher (carrying the durable co-sign guard) on restart.

The XNO leg is driven through an operator-configured Nano RPC: selectable presets are rainstorm (default, the only one that does work_generate), somenano and nanoto, or a custom URL. Obscura hardcodes no Nano endpoint. Funding the XNO side works either from a node wallet or by signing the funding send locally from a raw key.

Fees & replace-by-fee

Fee estimation is manipulation-resistant: it takes the median across a window of recent blocks of each block's marginal fee-rate, gated on congestion, floored and capped — so one miner stuffing a block can't move the suggestion, and it degrades to the floor on quiet chains. Light clients can reproduce it from recent blocks.

• send --fee auto sizes the fee from the node's estimate × your transaction's bytes.
• Miners select transactions by fee-rate (deterministically), so paying more genuinely buys priority.
• bump does BIP125-style replace-by-fee: a higher-fee replacement that re-spends the same inputs supersedes a stuck payment.

Security & key handling

• At-rest encryption. The seed and the scan-state are sealed with Argon2id (memory-hard KDF) + XChaCha20-Poly1305 (authenticated). Wrong passphrase or tampering is detected, never silently mis-decrypted. KDF parameters are bounded on read to prevent a hostile file from forcing a multi-hour unlock.
• Mnemonic. A 24-word checksummed phrase; a single mistyped word is rejected rather than producing a wrong wallet.
• View-only wallets. A view key grants visibility into incoming funds without any ability to spend.
• Verification. The implementation ships a critical-workflow test suite covering spend soundness, value conservation, and reorg recovery, and the header state-root lets light clients and snapshots verify all residual consensus state.

Tokenomics

Emission follows a smooth, shift-based decay (reward ≈ remainingSupply >> 19) until a perpetual tail floor (~0.6 OBX/block) takes over — front-loaded distribution with security funded forever, and no halving cliffs. Three reinforcing incentives:

• Mine. The base PoW reward secures the chain and is the source of all emission.
• Hold. 5% of each block's reward funds a bounded incentive pool; time-locking outputs earns a proportional, confidentiality-preserving share — redistribution, not new inflation.
• Grow. A capped, decaying referral bonus that never mints supply (it's a voluntary fee-share). Off by default for safety.

RPC API

JSON over HTTP (default 127.0.0.1:18081). Selected endpoints:

GET  /status          chain height, difficulty, supply, mempool size
GET  /height          tip height
GET  /block?height=N   serialized block
GET  /headers?from=&count=  header range (SPV light clients)
GET  /feerate?target=N  suggested fee-per-byte
GET  /mempool         pending-tx count, bytes, fee-rate min/median/max
GET  /peers           connected peers
GET  /offers          swap order book
POST /submittx        broadcast a transaction
POST /offer           publish a swap offer
GET  /blocktemplate?address=  unmined block for an external miner
POST /submitblock     submit a solved block

The /witness endpoint was deliberately removed — it leaked which output a wallet was interested in. Wallets build spends entirely offline.

Whitepaper (in brief)

Obscura's thesis: a privacy coin's anonymity should be a network effect, not a fixed per-transaction parameter. By accumulating every output into a group of unknown order and proving membership succinctly, the anonymity set becomes the entire UTXO set, with constant-size proofs and no trusted setup.

The honest trade-off is performance: class-group operations are slower than elliptic-curve math, and witness maintenance plus full zero-knowledge spends are heavier than a ring signature. Obscura accepts that cost in exchange for a qualitatively stronger, ever-growing anonymity guarantee and the elimination of decoy-selection leakage. Read the full scientific whitepaper for the complete construction, security arguments, and protocol specification.

FAQ

How is this different from Monero?

Monero hides a spend in a ring of ~16 decoys chosen by a heuristic. Obscura hides it among all outputs via an accumulator — no decoys, no selection heuristic to leak, constant-size proofs, and a set that grows with adoption. The cost is slower group math.

How is this different from Zcash?

Zcash pioneered shielded transactions with zk-SNARKs, but privacy is opt-in: only outputs moved into the shielded pool are private, so the effective anonymity set is just that shielded subset — and much on-chain activity stays transparent. Its original Sapling proofs also needed a trusted-setup ceremony (toxic waste that, if it leaked, would permit undetectable counterfeiting); later Orchard/Halo 2 removed it. Obscura is private by construction — every output joins the class-group accumulator, so the anonymity set is the entire UTXO set — and needs no trusted setup at all (a class group of unknown order plus transparent, hash-based zk-STARKs, which are also post-quantum-friendly). The trade-off is heavier group math and larger proofs than a SNARK.

Is there a trusted setup?

No. The class-group backend needs no ceremony at all. The RSA backend uses a public, nothing-up-my-sleeve modulus.

Can I run a watch-only wallet?

Yes — export a view key with viewkey and create one with watch. It sees incoming funds but cannot spend.

Can I prove I paid someone?

Yes. proofsent produces an offline-verifiable proof that you paid a specific amount to a specific address; recipients use proof. Both verify with checkproof and reveal nothing else.

What is the proof-of-work?

RandomX — the canonical, CPU-optimized memory-hard PoW (the default build, verified against the official known-answer vectors; light mode, ~256 MiB cache per seed epoch) with an epoch PoW seed and LWMA difficulty. Miners must also hold full block bodies (proof-of-retrievability), so mining and full-node operation are one and the same.

Built in Go · no trusted setup · global anonymity set. ← Back to home