BurnBounty

Own the cards. Burn for BCH. Or build your legendary collection.

A fully on-chain digital trading card pack system on Bitcoin Cash using native CashTokens and covenants.

100% open source • Transparent RNG • Instant 80% cash-out • True collectibles

---

What is BurnBounty?

BurnBounty turns digital collectible cards into a self-sustaining economy on Bitcoin Cash.

• Buy a 5-card pack for a fixed BCH price.
• Receive 5 designed NFTs with embedded BCH face values and static rarity borders.
• Instantly burn any card to receive 80% of its face value in BCH (house keeps 20% for pool economics).
• Or hold and trade ultra-rare cards on the secondary market.

The project is framed and marketed as collectibles, never as gambling.

Inspired by physical TCGs + viral digital card culture, built natively on BCH for low fees and ownership.

---

Core Features

• Static Rarity Borders — Bronze, Silver, Gold, Diamond.
• Embedded Real Value — Every card has a verifiable BCH face value (pennies -> high-tier hits).
• Instant Redemption — One-click burn -> 80% paid immediately via covenant logic.
• Self-Funding Prize Pool — 20% house edge feeds reserve pool dynamics.
• Secondary Market Ready — Royalty/pool feedback path documented for future phases.
• Fully Verifiable RNG — Public deterministic verifier included.

---

Sustainable Decay & Economy (v0.6)

BurnBounty now uses a sustainable long-horizon value system with controlled growth, controlled decay, and a hard floor.

Weekly Drift Ranges (x1000 precision)

Tier	Weekly Drift
Bronze	-3 to +1
Silver	-2 to +4
Gold	-1 to +6
Diamond	+1 to +8

Random Growth/Decay Cap Windows

Tier	Cap Weeks	Approx Years
Bronze	0-52	0-1 year
Silver	26-104	0.5-2 years
Gold	78-182	1.5-3.5 years
Diamond	130-260	2.5-5 years

Floor Rule

• Minimum multiplier floor: 0.40
• Cards never decay below 40% of original face value.

Redemption Formula

weeks = (currentBlockHeight - mintBlockHeight) / 1008
effectiveWeeks = min(weeks, randomCapWeeks)
multiplier = max(0.40, 1 + (weeklyDrift / 1000) * effectiveWeeks)
payout = faceValue * 0.80 * multiplier

Series Pricing

Series	Pack Price	Drift Perk
Genesis Beta (Series 1)	0.05 BCH	min drift +5
Founder Edition (Series 2)	0.02 BCH	min drift +1
Normal	0.008 BCH	standard drift rules

Pool Safety

• PrizePool.cash includes pro-rata payout logic when available reserve is below requested total.

Legacy Card Backfill (Retroactive Compatibility)

• Cards minted before drift/cap encoding are normalized at redemption time.
• Burn flow now deterministically derives missing weeklyDriftMilli, randomCapWeeks, and fallback mintBlockHeight from card entropy + tier.
• Result: previously minted cards remain burnable and participate in decay/growth math without manual re-minting.

In-Game Guide

• New Bounty Hunter Handbook modal explains decay, cap windows, floor, series perks, and quick math.
• Placeholder screenshot: docs/assets/game-guide-modal-placeholder.png

---

The RNG - Fully Auditable

Randomness uses commit-reveal + chain-linked entropy, implemented with deterministic replayability.

Security layers implemented in this repo:

1. Multi-source entropy — block references + commit-linked data + revealed seed/nonce.
2. 32-round PRNG mixing — repeated hash/xor diffusion pipeline.
3. 6-block reveal window — limits reveal grinding behavior.
4. Public verifier parity — anyone can recompute reveal output from transcript inputs.
5. Batch verification scaffolding — multi-pack reveal verification path exists.

See:

• lib/rng.ts
• lib/verify.ts
• docs/rng.md

---

Card Examples

(Replace placeholders with final AI/artist assets for launch media. Borders remain the hero element.)

---

Tech Stack

• Blockchain: Bitcoin Cash (CashTokens + covenants)
• Smart Contracts: CashScript (PackCommit, PackReveal, PrizePool, CardRedeemer)
• Frontend: Next.js 15 + Tailwind + shadcn/ui + Framer Motion + 3D reveal stack
• Wallet/Auth: Hybrid Option E (embedded wallet primary, external BCH signature auth secondary, optional Snap compatibility)
• Randomness: Commit-Reveal + block-linked deterministic entropy

Current status: working on chipnet/testnet POC.

---

Quick Start (Chipnet Demo)

1. Clone:

git clone https://github.com/pmb2/BurnBounty.git
cd BurnBounty

2. Install and run:

npm install
cp .env.example .env.local
npm run db:migrate
npm run contracts:compile
npm run contracts:deploy
npm run dev

3. Open http://localhost:3000 and run flow:

• / -> Play Now -> /auth -> /dashboard
• /dashboard?tab=play -> commit/reveal loop
• /dashboard?tab=inventory|market|ledger|settings -> burn, list, buy, wallet/session management

4. Scripted flow:

TEST_USER_WIF=<chipnet_wif> npm run test:flow

5. Demo-showcase recording mode:

# in .env.local set DEMO_SHOWCASE_MODE=true
TEST_USER_WIF=<chipnet_wif> npm run test:demo-flow

---

Roadmap

• POC (current): Unified Play + Armory flow with immersive 3D scene scaffolding.
• Next: Mainnet-hardening, production wallet UX, final art pipeline.
• Later: Secondary market hooks, royalty feedback, governance options.

---

3D Immersive Pipeline

BurnBounty now includes a staged 3D worlding path:

• Runtime world scaffold: components/BountyWorldScene.tsx
• Runtime readiness panel: components/ImmersiveAssetStatus.tsx
• Asset manifest: data/3d-assets.json
• Validation command:

npm run assets:3d:validate

• Asset directories:
  • public/3d/scenes
  • public/3d/props
  • public/3d/cards

Detailed pipeline doc:

• docs/3d-asset-pipeline.md

Runtime behavior:

• Scene slots (board, props, interactive) are manifest-driven.
• Missing or placeholder assets automatically fall back to synthetic primitives, so gameplay is never blocked.

---

Dev vs Live Environments

• Dev: local machine with .env.local (from .env.development.example)
• Live: https://bb.backus.agency with deploy/traefik/.env.live (from .env.live.example)

Local dev:

cp .env.development.example .env.local
npm install
npm run dev

Live deployment (Traefik):

cp .env.live.example deploy/traefik/.env.live
# edit live values
npm run live:up

Live deploy is also VCS-driven via GitHub Actions on push to main.

---

Hybrid Auth Architecture (Option E)

BurnBounty uses a BCH-native hybrid authentication model:

• Embedded wallet onboarding (primary): new users register/login quickly and receive an auto-provisioned embedded BCH wallet.
• External BCH wallet auth (power-user path): nonce challenge + signature verification for non-custodial login/link.
• Google OAuth onboarding: fast first-time account entry; an embedded wallet is provisioned automatically after OAuth login.
• MetaMask Snap (optional/experimental): compatibility bridge only, never the core BCH identity flow.

Why:

• BCH is UTXO-based and does not have a universal EVM-style injected provider standard for app identity.
• Product growth requires low-friction onboarding for first-time players.
• Crypto-native users still need bring-your-own-wallet proof-of-ownership paths.

Auth endpoints:

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me
• POST /api/auth/wallet/challenge
• POST /api/auth/wallet/verify
• POST /api/auth/wallet/link
• POST /api/auth/wallet/unlink
• POST /api/auth/wallet/embedded/create

Compatibility endpoints kept for existing clients:

• POST /api/auth/challenge
• POST /api/auth/verify

Legacy shim policy:

• compatibility-only wrappers around canonical auth service
• deprecated with sunset date: 2026-06-30

Security behavior:

• nonce-based challenge messages include purpose + domain + timestamp context
• one-time challenge enforcement with expiry
• replay rejection and purpose mismatch rejection
• wallet rebinding conflict checks
• middleware validates session signature + expiry for protected routes
• BCH address normalization is centralized (CashAddr/legacy resolve to one canonical key)
• embedded and external BCH auth both use the same signed-challenge verification primitives
• auth-message signatures are not blockchain transactions and do not spend BCH
• MetaMask Snap compatibility is isolated and non-core
• current BCH auth verification path is classic compact signed-message verification (BIP322 support is not yet enabled)
• dashboard header now shows compact hunter identity (username/avatar/rank), while external wallet linking is handled in /dashboard?tab=settings

Productionization (auth-critical):

• challenges, wallet bindings, sessions, audit events, and auth rate limits are DB-backed (Postgres/Supabase)
• challenge consumption is atomic and replay-safe under concurrency
• external wallet login concurrency conflicts recover to canonical owner resolution (no duplicate-identity race leakage)
• wallet identity uniqueness is enforced with durable DB constraints on canonical BCH storage key
• session revocation is durable (auth_sessions.revoked_at)
• sensitive actions use recent-auth checks (recent_auth_at)

Local Auth Testing

1. Start app:

npm run dev

Ensure DATABASE_URL (or SUPABASE_DB_URL) is set before running auth flows.

2. Go to /auth and run:

• Embedded quick-start register + login
• External BCH challenge-sign-verify login
• Link/unlink wallet checks

3. Run auth tests:

npm run test:auth

4. Run full auth release gate:

npm run release:auth-gate

---

Legal & Disclaimer

This is a collectible NFT project with utility mechanics.

It is not marketed as gambling.

This repository is a technical POC and not legal advice. Consult counsel before any mainnet launch, especially in regulated jurisdictions.

---

Contributing & Backers

Fully open source (MIT).

Contributions and technical reviews are welcome.

See:

• Contributing
• Code of Conduct
• Security Policy
• Changelog

---

Documentation Index

• System Overview
• Architecture
• Auth Architecture
• Auth Schema & Migration
• Auth + Trading Setup
• Auth Production Readiness
• Wallet Support Matrix
• Contract Specifications
• RNG Design & Security
• API Specifications
• Frontend Flow
• Deployment Guide
• VCS + Deploy Flow
• Verification Guide
• Runbooks
• Open Source Boundary
• Legal/Compliance Notes

---

Made for the Bitcoin Cash community