wikideck/README.md

Wikideck

Production roadmap: see the production delivery plan for XMR-native pricing, custodial-market implementation, fixed-price-first launch scope and release gates. New v3 listings use exact native-XMR prices; historical v2 USD records keep their original terms. All payments remain simulated. The custodial design and implementation status distinguish the sandbox ledger from future live custody.

Wikideck is an NFT blockchain where mining a block rewards the miner with a collectible card based on a Wikipedia page. Build collections, trade cards with other collectors, or host a peer with its own marketplace. Trading card games (TCGs), including custom games hosted by peers, are planned for a later release.

Mining uses RandomX, the proof-of-work algorithm also used by Monero, designed to keep general-purpose consumer CPUs competitive. Wikideck is an independent blockchain, not part of Monero or its mining/security network. Hardware, total network hashpower and difficulty determine results; no particular mining reward rate or profitability is guaranteed.

This is a local test network, not a public mainnet or an investment product. No public bootnodes or hosted network are provided. Test NFTs have no promised value. Do not use funds or valuable assets. This project is not affiliated with Wikipedia or the Wikimedia Foundation.

Collect, trade, and build your own community

• Mine Wikipedia cards. Each accepted block mints a native NFT for the miner from a random illustrated English Wikipedia article. The card records the article snapshot and mint-time statistics. The same page can appear on more than one distinct card. The reward is a card representing a page—not ownership of the page, its copyright, or a payment to Wikipedia.
• Build collections. Assemble a broad cabinet of discoveries or focus on a subject, series or theme. Browse public decks and exchange up to eight cards on each side in one atomic trade.
• Buy and sell in peer-hosted markets. Running a peer lets you host a market for the shared chain's cards. Your community can be general-purpose or focus on a particular collection. Listings, auctions and orders belong to that market host; card ownership and mined transfers are shared through the blockchain.
• Support the host and project author. Sales allocate a configurable hosting fee to the peer's market operator (2.5% by default) and a separate hardcoded 1% author fee to the project's fixed XMR address. Both are deducted from seller proceeds; the default total is 3.5%. In the intended cryptocurrency settlement model the host retains its fee, while the author allocation is paid separately. Today all payment, fee and payout accounting is simulated.
• Cryptocurrency checkout. New market prices are quoted directly in Monero (XMR) atomic units. The current testnet checkout is mock-only: no real cryptocurrency is accepted or sent.
• Play TCGs — planned. The roadmap is to use these same cards in trading card games and let peers host custom TCG experiences. There is no playable game engine, match system, deck legality or custom rules hosting yet. Current card stats are not a promise of future game balance.

Peer ownership and customization

Understand the market before trading: Payment flow and buyer/seller protections explains who controls cards and funds, both fees, deadlines, refund/reorg limits, privacy and host accountability. Current payments are mock-only; seller delivery still transfers the actual card. No guaranteed refund, insurance or built-in arbitration is provided.

The project's open-source direction is to give peer operators substantial freedom to adapt their own market: presentation, community focus, curation and future game rules. A collection-focused community can run the current general listing interface today; built-in collection filters, moderation/admission tooling and custom TCG hosting are future work, not existing operator controls. Operators can already configure their hosting fee and run their own local marketplace journal.

Market customization does not let one peer rewrite shared NFT ownership or unilaterally change consensus for other peers. Compatible peers must follow the same network rules. The author fee is hardcoded in the distributed implementation; it is not a hosting configuration option. Any source modifications and redistribution must respect the eventual project license and third-party licenses.

Licensing status: this checkout does not yet contain a project LICENSE file. Source availability alone does not grant open-source modification/redistribution rights. Publishing an appropriate license is still required before describing those freedoms as legally granted. Wikipedia text/images and dependencies retain their separate licenses; a Wikideck software license would not replace them.

What's available now

Available in the testnet	Planned / not enabled
RandomX mining and illustrated Wikipedia NFT rewards	Reviewed production network launch
Encrypted local wallets, collections and atomic card trades	Playable TCGs and peer-hosted custom games
Per-peer fixed-price listings and timed auctions	Built-in collection-specific curation/admission controls
Mock native-XMR checkout and host/author fee accounting	Real cryptocurrency settlement and production custody operations

Run the three-node testnet (Docker)

Install Docker Desktop with Linux containers and Docker Compose v2. From the repository root, start three connected nodes:

docker compose -f compose.testnet.yaml up --build -d
docker compose -f compose.testnet.yaml ps
docker compose -f compose.testnet.yaml logs -f node-a

Open http://127.0.0.1:3101. The other nodes are at http://127.0.0.1:3102 and http://127.0.0.1:3103. Each node validates blocks independently and stores its ledger in a separate Docker volume. Mining does not start automatically. A healthy node is not necessarily connected to its peers; check the peer status in the interface or request /api/peers. Nodes need outbound access to Wikipedia when generating mining templates and capturing mint-time statistics. If that data is unavailable, the node returns an error and mining can be retried.

Stop the nodes with:

docker compose -f compose.testnet.yaml down

The target block interval is 15 minutes. The volumes persist across stops and rebuilds. Do not add -v unless you intend to delete all three ledgers. Back up wallets separately. Protocol v6 adds atomic multi-card trades and a new chain identity; earlier v2–v5 ledgers and encrypted backups are not compatible. To keep old Docker data intact while trying v6, use a separate Compose project name, for example docker compose -p wikideck-v6 -f compose.testnet.yaml up --build -d, and use the same -p wikideck-v6 for subsequent Compose commands. The default docker compose up --build -d uses compose.yaml: it starts one isolated node on port 3001 with a different volume.

For an existing host install, keep the old data directory intact and set WIKIDECK_DATA_DIR to a new empty directory before starting protocol v6. The node intentionally fails closed on an old-protocol ledger; it does not reset or migrate it. A v6 JSON ledger is imported into SQLite on first startup and left in place as a recovery copy.

Run on your host

Optional custody accounting preview

Optional market hosting: set WIKIDECK_MARKET_ENABLED=0 to suppress public listings/new trading, or WIKIDECK_MARKET_TRADING_ENABLED=0 for a browsable paused market. Configure hosting-fee payouts with WIKIDECK_MARKET_HOST_FEE_ADDRESS (defaults to the author wallet); the fixed 1% author fee remains separate. Existing orders/balance resolution stay accessible. See host configuration for strict values, signed recipient snapshots and safe container recreation.

For a persistent PostgreSQL-backed local stack, use the deployment guide and compose.custody.yaml, or the VS Code Start persistent custody sandbox task. It starts PostgreSQL plus Wikideck at port 3422, with generated scoped credentials, verified database TLS and explicit migrations. Existing single/three-node commands are unchanged. This uses separate volumes and does not migrate existing SQLite custody or enable real payments.

The marketplace's Custody preview tab is separate from existing mock checkout. Explicit WIKIDECK_CUSTODY_MODE=sandbox on the server enables fictitious test balances, signed fixed-price reservations and withdrawal holds on testnet only. Default is off; live modes and mainnet sandbox fail closed. Use a disposable data directory and configure PUBLIC_ORIGIN to the exact browser origin. No Monero addresses, wallet RPC or real withdrawals are available. PostgreSQL financial storage is selectable with WIKIDECK_CUSTODY_STORAGE=postgres, explicit schema/role setup and a secret-file connection configuration; existing SQLite custody requires a stopped-node import, never automatic fallback.

Reservations stop at awaiting-lock because reviewed NFT sale-lock consensus rules are not implemented. They can be cancelled while their outbox intent is blocked; they do not deliver cards. Local SQLite custody is included by stopped-node backup/restore when present; PostgreSQL-bound nodes require coordinated database/node backups and the SQLite-only backup command refuses them. Real treasury observation/settlement, signing controls and production review remain future work. See the implementation record.

Requirements: Node.js 24, npm, Git, CMake 3.24+, and a C/C++17 toolchain. The first native-engine configuration downloads the pinned RandomX source over HTTPS. On Windows, install a compatible toolchain (for example, MinGW-w64 and make) and use the matching CMake generator. Do not change generators in an existing native/build directory; use a fresh build directory when switching toolchains.

Install dependencies and build the native RandomX engine:

npm install
npm run native:configure
npm run native:build
npm run test:native
npm run build
npm start

On Windows with MinGW, configure with npm run native:configure -- -G "MinGW Makefiles". If PowerShell blocks the npm shim, use npm.cmd; follow your organization's execution policy rather than bypassing it. The optional platform scripts are scripts/build-randomx.ps1 and scripts/build-randomx.sh. See native engine setup and protocol for toolchain details.

The node listens at http://127.0.0.1:3001 by default. For development, npm run dev starts the API on port 3001 and Vite on http://127.0.0.1:5173. Keep both services on loopback; Vite proxies the browser's /api requests to the API. The native miner should connect directly to the API port, not Vite.

Wallets and backups

Open the wallet panel to explicitly create an encrypted local P-256 wallet, unlock an existing vault, or encrypt a legacy plaintext wallet without changing its identity. Nothing is silently generated or unlocked at startup. Choose a strong local password of at least 12 characters. Wallet backup & recovery downloads a separately password-encrypted portable backup; keep the file outside the repository and its password separately, and test recovery in another browser profile.

New/migrated local vaults encrypt the key in IndexedDB; the unlocked key remains exportable in tab memory for signing and backup. Manual locking, five-minute inactivity, a four-hour absolute lifetime, reload, or hiding/leaving the tab ends the session. Same-origin compromise can still capture passwords or abuse an unlocked signer. Forgotten local passwords cannot be reset: recover from a usable backup. Legacy disk copies may retain old plaintext keys even after migration. Wallets are scoped to an origin (scheme, hostname, and port), so a backup must be restored at another origin to use the same identity there. Recovery does not move assets between chains. See encrypted wallet lifecycle and remaining risks.

The current testnet wallet is separate from any wallet used by an older demo. There is no automatic migration. See consensus, wallets, and operational limits and the in-app backup warnings for more detail.

Mine Wikipedia cards with RandomX

Mining uses the native CPU RandomX engine. First build the engine, download an encrypted wallet backup, then run the CLI from an interactive terminal and enter the password at its hidden prompt:

npm run miner -- --wallet "path/to/encrypted-backup.json" --consent --node http://127.0.0.1:3101 --blocks 3

Use port 3001 for the default single host/Docker node, or 3101–3103 for the three-node Docker testnet. The command above uses node-a. The miner defaults to one worker, light mode, and one block; --blocks 3 requests up to three accepted blocks. Press Ctrl+C to stop it. Do not put the backup password in a command, environment variable, or repository file. The backup and password are decrypted locally and are not sent to the node.

Each template request asks English Wikipedia for up to ten random pages and retries at most three times to find one with an image and readable extract. The same page may be selected again. The node also captures page size, language-link count, revision, pageviews, and derived scores for the mint-time snapshot. If Wikipedia cannot supply the article or its metadata, template creation returns an error; there is no fixed-article fallback. Validators check and commit the included snapshot without contacting Wikipedia during consensus validation.

Light mode needs a 256 MiB cache plus scratchpad and process overhead. --fast is optional and needs over 2.3 GiB per miner process. Mining consumes CPU, power, and time; RandomX is not a guarantee of ASIC resistance. Do not expose an HTTP miner endpoint remotely; use HTTPS. Detailed resource, native build, and line-protocol notes are in docs/randomx-native.md.

What the app shows

• Discover shows preview examples until the node has mined blocks; previews are not owned NFTs. Minted cards can reference the same page, but each carries its own captured stats snapshot.
• My collection shows NFTs owned by the active local wallet on the connected node's canonical chain.
• Block explorer distinguishes block IDs, NFT token IDs, and RandomX proof hashes. A submitted transfer is pending until a block confirms it. Reorganizations can change canonical ownership and confirmations.
• Trade decks lets you look up another public wallet by receive address, select up to eight cards on each side, prepare a signed offer, and accept another player's offer. Offers are shared as JSON for the other player to review; they are not submitted until accepted. The two parties sign the same card list, and validators apply the whole bundle atomically or reject it entirely. Offers are not reservations: before acceptance the app re-checks ownership, maturity, sequences, and pending activity; stale offers must be recreated.
• Marketplace is the connected peer's market: new fixed-price listings and timed auctions use native XMR amounts; historical USD listings remain read-only. Checkout, fees and payouts are simulated. Sales allocate a configurable fee to the hosting operator (default 2.5%) and a hardcoded 1% author fee (3.5% total by default). Sellers still sign real card delivery after the mock payment step. Never send real XMR: no payable checkout address or live processor is enabled. Listings/orders are local to the selected market host, not gossiped; listing does not lock a card on-chain. See peer markets, fees and payment status.
• Each minted card shows current Wikipedia statistics alongside its immutable at-mint snapshot: pageviews, article size, language links, revision, and derived scores. Current values may change; at-mint values are committed to the block. Missing pageview data stays unavailable, not zero.
• The appearance selector offers Catppuccin Mocha, Macchiato, Frappé, and Latte themes.

The browser interface trusts the connected node's reported state. It does not independently verify the chain or provide an SPV client. Transfers are irreversible once confirmed; check the recipient address carefully.

Mainnet candidate · launch gated

Production status: NO-GO pending remediation and independent review. See the security review and operator launch checklist. A read-only launch:preflight script reports blockers and local gate status without launching or granting approval.

A separate mainnet profile has its own network/genesis identity, ledger and market directories, browser wallet, backup checks, and opt-in Compose definition. It preserves the existing testnet chain and does not migrate testnet cards. No production network has been launched or certified by this work. Startup requires explicit chain-specific approval, an operator review attestation, the candidate genesis time, HTTPS origins and multiple configured peers. Real payments remain blocked even then. See the candidate launch gates and production checklist.

Tests and development checks

Offline preparation tools: analyze:consensus reports deterministic retarget/timestamp scenarios; benchmark:randomx runs a bounded native benchmark only with explicit --consent. Neither launches a node nor changes consensus or approval settings. See calibration evidence and limitations before interpreting rates or illustrative targets.

npm test
npm run build
npm run test:native

npm test runs the application test suite, including fast test-only proof tests. npm run test:native runs the real upstream RandomX known-vector test and requires a native build configured with tests enabled; the documented npm run native:configure command enables them. The Docker build also builds RandomX and runs its native test.

The Dockerfile also provides a test target containing Node 24, development dependencies, the tests, and the compiled Linux-native RandomX binary. Build that target and run the resulting image to exercise the full native HTTP suite without relying on a host-platform binary. TypeScript compilation enforces erasable syntax because the production runtime strips types directly.

To explicitly test propagation and transfer behavior across the three local Docker nodes, first build the host native engine and start the three-node testnet, then run:

node --experimental-strip-types scripts/testnet-smoke.ts --consent

This mines three real blocks using disposable identities. It changes the testnet, and is not run automatically.

Network and safety limits

Live XMR payments are not implemented. The selected custody design uses direct Monero wallet/daemon observation and a pooled liability ledger; no real deposits, credits, withdrawals, or sale settlement are enabled. See the custodial market design and launch hold points.

Deployment and recovery preparation includes explicit trusted-proxy configuration, opt-in loopback-only diagnostics and ops:check, plus stopped-node paired node:backup create/verify/new-directory restore tooling. Backups contain sensitive market data and require external encryption/access control. Tools do not configure TLS/alerts or authorize production launch/restore.

Stage-1 node resource controls bound global RPC admission, response bytes and canonical page sizes. The UI reuses paged history; legacy full-state responses stop beyond 128 blocks. A consent-gated loopback-only smoke-load script is available as test:rpc-load. This does not resolve long-chain/DAG storage limits or establish production capacity.

Nodes use only explicitly configured peers; there is no discovery service or public bootstrap network. The peer, storage, and HTTP configuration is documented in docs/testnet-consensus.md. The implementation is experimental: it has no consensus transaction fees or established economic security (market fees are off-chain simulations), and remains vulnerable to resource exhaustion, isolation/eclipsing, censorship, majority-hashpower attacks, and reorganizations. The ledger now uses transactional SQLite/WAL storage and sparse per-block NFT-state deltas, but nodes still retain DAG block records in memory, rebuild state roots over the full NFT set, and revalidate all proofs at startup. It is not yet an archival-scale production design. HTTPS, container hardening, and passing tests do not constitute a security audit.

Before considering any broader deployment, the protocol and cryptography would need independent audits, adversarial network testing, hardened abuse controls, and tested recovery procedures. Do not expose a public node or use valuable assets on this experimental network.

Attribution

The four original starter summaries in the interface are preview examples only; they are not mintable. Mined cards contain short snapshots from Wikipedia contributors, licensed under CC BY-SA 4.0, and a Wikimedia-hosted picture. Open each card's Image & license link and review the file-specific license and attribution before reuse. A native NFT does not grant copyright or exclusive rights to article text or images.