Docs

Overview

Salt Wars is moving toward a modular on-chain game. Worms and sticks are NFTs, $DIRT is the fixed-supply ecosystem token, drop zones point to vault-backed prize tables, and every real action should be verifiable from contracts and indexed events.

Resources

$DIRT

The first fixed-supply ecosystem token. Placeholder supply is 1B DIRT, and mining releases existing supply.

$SALT

Reserved for later. The resource system should leave room for it without slowing the first build.

Packages

Drop tables should track prize packages like 500 x 10, 5k x 5, 100k x 2, and NFT #1 x 1.

NFTs

Worms come first and should be their own NFT contract. Sticks come later as a separate collection using the same unit pattern.

• Each unit has base stats, metadata, home state, and current action state.
• Each unit should support a token-bound wallet, similar to ERC-6551.
• Token-bound wallets let rewards and inventory travel with the NFT.
• Health rules depend on whether death mode is on or off.

Worm Minting

Minting worms consumes $DIRT through a rising price curve. Placeholder v0 pricing starts at 1,000 DIRT, adds 250 DIRT per mint, caps at 25,000 DIRT, and cools one step every 15 minutes. At launch, mint spend is split 50% burn, 45% treasury, and 5% dev wallet.

Maps & Drops

Maps and drops should be records in registries, not one contract per zone.

RNG & Claims

When a unit starts walking, GameActions locks route data and Claims kicks off the roll. The frontend can reveal the prize later, but the claim result is already tied to the action.

Preferred v0 RNG is DiceEntropy/Dice Protocol through a Salt Wars adapter. drand stays as the fallback, DERP is only for optional low-stakes or themed modes, and Chainlink VRF is reserved for later if it becomes native on Robinhood Chain.

1. Validate owner, unit availability, map, drop, vault, and route.
2. Lock action id, map version, path hash, RNG provider, drop table hash, vault inventory hash, start time, and arrival time.
3. Request randomness when walking starts.
4. Store entropy in the callback, then settle the prize from the locked snapshots.
5. Release token prizes to the player wallet after tax splits.
6. Release NFT prizes directly to the player wallet.

Pathing

The backend computes the shortest valid route on the canonical 2D grid, then a configured route authority signs the action envelope. V0 uses deterministic BFS with 4-way movement, equal cell costs, and fixed tie-break order. Rivers are blocked unless an active bridge covers the cells; mountains, blocked objects, and broken bridges are not walkable.

The frontend can smooth the route visually so movement does not look blocky, but travel time uses the committed route length. The route authority envelope locks chain id, GameActions address, player, unit, map id, map version, pathing hash, bridge state, target drop, route hash, and route length.

The current backend helper is lib/route-authority.js, with a CLI wrapper at scripts/route-authority-sign.js. The local dev server exposes /api/sign-route, /api/dev-seed, /api/send-unit-to-drop, /api/action-state, /api/complete-action, and /api/chain-events, and local deploys write data/dev-chain.json so the browser can request a signed Solidity route payload, submit a local GameActions transaction, complete a local claim, and read local chain events without holding the signer key.

The hosted Robinhood testnet build currently exposes /api/sign-route with an intentionally insecure Worker test signer at 0x834231592D065B2434731E7b6eb3925Fe6735Aa4. This is only for iteration; before economic production it must become a secret-backed signer that reads canonical map data server-side, checks live map/drop/egg/unit state, rate limits requests, and logs every signature.

Health

Modules

Build Specs

The first concrete specs cover the foundation contracts, map/drop/vault accounting, claims, and GameActions dispatch.

Audit Notes

The first audit flags the big unresolved items before contracts: admin wallet vault trust, DiceEntropy verification, route proof strategy, final ERC-6551 support, and confirming the placeholder $DIRT allocation and mint curve.

Deploy

The public site is prepared for Cloudflare with a static build and a production-safe Worker shell. Run npm run site:build to create dist/site, then npm run cf:deploy when Cloudflare auth and DNS are ready.

The Cloudflare build excludes local chain state and local signer endpoints. Production currently exposes /api/health, /api/config, /api/indexer-status, and /api/chain-events. The chain-events endpoint reports missing config now, then reads raw contract logs once RPC and deployed addresses are set.

Current Worker URL: https://salt-wars.notabunnyrbx.workers.dev. Deployment notes live in docs/cloudflare-deploy.md. The target routes are saltwars.io/* and www.saltwars.io/*, with test.saltwars.io reserved for staging if we want a separate preview route.

Planning Files

Website docs and markdown plans should stay paired. When the plan changes in docs/blockchain, update this page. When this page changes, update the matching markdown plan.

Local chain test flow: run npm run contracts:node, npm run contracts:deploy:local, and npm run dev:server. Use the chain-aware local URL when testing signed routes and local GameActions.sendUnitToDrop() submissions.