1. Game Config
One address registry points to the active MapRegistry, DropRegistry, Worms, Sticks, VaultManager, RNGProvider, GameActions, resources, items, and indexer schema versions.
Salt Wars
Map Data
Waiting for live map snapshot...High Level Blockchain Plan
Salt Wars should build the chain layer as a modular game protocol: stable ownership contracts for creatures and resources, swappable registries for maps and drops, vault-backed prize custody, deterministic action records, and indexed events that the frontend can render cleanly. We will plan each component first, audit the combined design, then build.
2. Worm NFTs First
Worms should be their own NFT contract, similar to sticks but not trapped inside stick assumptions. Worms get base metadata, stats, assignment state, future modifier hooks, and token-bound wallets.
3. Sticks Later
Sticks can follow the same unit pattern after worms: ownable NFTs, effective stats, home assignment, action locks, route visualization, cargo, and claim state.
4. Maps And Zones
Maps, terrain hashes, drop zone records, egg slots, bridges, and project positions live in registries. A drop zone is a record, not its own contract.
5. Drop Tables And Vaults
Drop zones point to drop tables and prize vaults. Vaults hold the real NFTs/tokens, while drop tables declare batches like 500 x 10, 5k x 5, NFT #1 x 1.
6. RNG And Claims
Roll when a unit starts walking, lock the claim result against the action, animate suspense on the frontend, then transfer the prize when the unit arrives.
7. Actions And Pathing
GameActions validates ownership, map activity, drop activity, route hash, terrain rules, travel time, unit availability, and immutable action records.
8. Stats And Items
Base stats stay stable, while approved future modules can add bounded item, consumable, event, or project modifiers to worms and sticks.
9. Indexer And Data
The frontend should read a clean indexed state model: maps, zones, vault inventory, rolls, claims, units, eggs, projects, balances, and activity history.
Resource Token Direction
$DIRT is the first ecosystem token. It should be harvested through gameplay, claimed from drop zones, transferable, visible in wallets, and spendable to mint more worms. $SALT should be reserved as a later token, not forced into v0.
| Piece | Direction | Why |
|---|---|---|
| $DIRT | ERC-20 style ecosystem token on Robinhood Chain. | Feels closer to pons-style token launches than an internal-only game balance. |
| Worm minting | Spend or burn $DIRT through a WormMinter module. | Lets harvested dirt become the loop for creating more worms. |
| $SALT | Reserve as a later resource token. | Keeps v0 focused while leaving the schema ready. |
| Token-bound accounts | Worms and sticks should support NFT-owned wallets. | Lets rewards and inventory travel with the NFT, similar to StonkBrokers ERC-6551 accounts. |
| Drop packages | Track package counts like 500 x 10, 5k x 5, 100k x 2. | Lets vault validation prove the drop table can actually pay its prizes. |
Execution Planning Files
We will keep the high-level plan in one markdown file, then create one focused sub-plan per component. Each sub-plan should include the contract responsibility, state shape, admin controls, events, failure cases, and audit questions.
| Component | Markdown Plan Path | Purpose |
|---|---|---|
| High-level plan | docs/blockchain/high-level-plan.md | Overall architecture, build order, audit flow, and component map. |
| Game config | docs/blockchain/game-config.md | Swappable module addresses, admin model, timelock path, pause controls. |
| Worm NFTs | docs/blockchain/worm-nfts.md | First unit NFT contract, metadata, base stats, current assignment, future modifiers. |
| Stick NFTs | docs/blockchain/stick-nfts.md | Second unit NFT contract using the same unit/action/stat pattern. |
| Map registry | docs/blockchain/map-registry.md | Map ids, terrain/object hashes, bridge states, egg slots, zone positions, active flags. |
| Drop registry | docs/blockchain/drop-registry.md | Drop zone records, drop table ids, vault links, depletion, active flags. |
| Vault manager | docs/blockchain/vault-manager.md | Prize vault custody, inventory validation, batch accounting, recovery, transfers. |
| RNG and claims | docs/blockchain/rng-claims.md | Roll timing, prize selection, reveal flow, claim records, randomness provider swaps. |
| Game actions | docs/blockchain/game-actions.md | Assigning units, deterministic paths, travel time, mining, return, claim/deposit flow. |
| Resources | docs/blockchain/resources.md | $DIRT, future $SALT, token package accounting, worm mint cost, ERC-20/pool direction. |
| Stats and items | docs/blockchain/stats-items.md | Base stats, effective stats, module allowlist, consumables, temporary modifiers. |
| Eggs and projects | docs/blockchain/eggs-projects.md | Egg slots, home state, bridge rebuilds, contribution accounting, leaderboards. |
| Indexer and API | docs/blockchain/indexer-api.md | Event-derived read model, frontend data shape, cache/update strategy. |
| Audit checklist | docs/blockchain/audit-checklist.md | Centralization risk, stuck assets, RNG fairness, accounting, permissions, path determinism. |
Extensibility Layer For Items And Consumables
The stick NFT should not need a contract migration every time we invent a new potion, tool, tattoo, map buff, event rule, or limited-time effect. The safer pattern is stable base stats plus a controlled modifier layer.
| Layer | What It Stores | Who Can Change It | Why |
|---|---|---|---|
| Base identity | species, team/home egg, permanent tats, permanent base stat seed | Stick NFT contract at mint or explicit admin/game migration | This is the durable identity of the NFT. |
| Equipped items | item ids, equipment slots, fixed trait items, inventory items | owner actions routed through approved game/item contracts | Lets gear affect stats without rewriting the NFT itself. |
| Temporary modifiers | stat deltas, multiplier bps, start/end time, source contract, reason | approved modules only: consumables, events, quests, projects | Lets us add limited-time buffs/debuffs later. |
| Computed stats | attack, speed, carry, luck, tax bonus, regen, resource bonus | read-only function or indexer derived from base + modifiers | Frontend and contracts can agree on the effective result. |
| Module permissions | allowlist of contracts and which stat keys each can modify | owner/governance/multisig/world controller | Prevents random contracts from mutating NFT power. |
Recommended Extensible Contract Shape
- StickNFT: owns token identity, base traits, ownership, metadata pointer, and exposes current/effective stats.
- StatsRegistry: defines stat keys and formulas so future stats can be added without breaking old sticks.
- ModifierManager: stores active modifiers per stick: source, stat key, operation, value, expiry, stack rule.
- Module allowlist: only approved contracts can add/remove modifiers, and each module can be scoped to specific stat keys.
- Item/Consumable contracts: call the modifier manager instead of directly editing the StickNFT.
- Events: every modifier add/remove/expire emits an event so the indexer can explain why a stick’s stats changed.
Stat Modifier Rules To Decide Later
| Question | Recommended Default | Why We Can Defer Details |
|---|---|---|
| Flat vs percentage modifiers? | Support both: flat add and basis-point multiplier. | The storage shape can support both before we design every item. |
| Can buffs stack? | Each modifier has a stack group and max stacks. | We can launch with max 1, then loosen by module later. |
| How do time limits work? | Store expiry timestamp or expiry block. | Consumables can be built later without changing stick ownership. |
| Who can mutate stats? | Only approved module contracts, never arbitrary callers. | This gives expansion room while keeping the NFT safe. |
| Where does final math live? | Contract view for canonical math, indexer mirrors for fast UI. | Game can read fast while chain remains source of truth. |
Chain State Buckets
- Ownership: wallets own stick NFTs, egg NFTs/accounts, resource tokens, and possibly map/project permissions.
- Map state: map id, terrain hash/version, object hash, bridge state, project states, and current active ruleset.
- Stick state: NFT metadata plus current trip, route hash, cargo, target, home egg, ETA, and claim readiness.
- Modifier state: active item/consumable/event modifiers by stick id, source contract, stat key, value, and expiry.
- Economy state: resource balances per wallet/egg/project/drop and tax splits.
- Activity state: event log for who did what, when, with which NFT, from which drop, and into which egg/project.
What Needs To Be True Before Mainnet
| Area | Decision | Why It Matters |
|---|---|---|
| Chain | Pick target chain and token standards. | Determines NFT/token interfaces, gas costs, wallet UX, and indexer stack. |
| Stick NFTs | Decide which metadata is mutable on-chain vs rendered by indexer. | Trip/cargo state changes often; permanent traits should not churn metadata unnecessarily. |
| Stats | Separate base stats from active modifiers and effective stats. | Lets future item/consumable contracts change behavior without replacing the stick NFT contract. |
| Resources | Choose ERC-20 style tokens, ERC-1155 style resources, or internal balances. | This determines how expensive mining, depositing, taxing, and trading will be. |
| $DIRT | Decide fixed-supply/pool launch vs controlled gameplay emission. | This determines whether $DIRT behaves like a pons-style ecosystem token, a mined reward token, or a hybrid. |
| Token-bound wallets | Decide ERC-6551-style accounts for worms and sticks. | Unit-owned wallets make NFT inventory and reward delivery much cleaner, but add integration complexity. |
| Pathing | Commit to grid path hash, route cells, and duration formula. | Movement must be deterministic and cannot secretly change after assignment. |
| Drops | Define depletion, randomness, enemy behavior, and drop-table proofs. | Players need to trust that rewards and remaining supply are not arbitrary. |
| Projects | Define contribution accounting and unlock conditions. | Bridge repair and egg goals need contributor leaderboards and clear state transitions. |
| Indexer | Build a canonical read model from events. | The game page should read fast indexed state, not scrape contract storage for everything. |
Recommended Build Order
- Update high-level plan: define the component list, boundaries, trust model, and markdown files for each sub-plan.
- Write sub-plans: fill each component doc with responsibilities, state, events, permissions, and unresolved decisions.
- Cross-component audit: check that ownership, drops, vaults, RNG, resources, paths, eggs, and modifiers agree with each other.
- Local simulator schema: make the current game emit the same state shape the contracts and indexer will later expose.
- Contracts v0: build GameConfig, $DIRT, WormNFT, MapRegistry, DropRegistry, VaultManager, RNG/Claims, GameActions, and Resources.
- Indexer v0: consume contract events and serve the same readable state this page expects.
- Frontend wiring: move the game from local state to indexed chain state while keeping smooth animation and suspense reveals.
- Testnet and audit: run accounting, stuck-asset, permission, pathing, RNG, and claim-flow tests before mainnet.
Blockchain Visualization Plan
- World state: map id, dimensions, terrain/design version, backend path version, bridge state version, and feature counts.
- Drop state: each drop zone has a stable id, drop table id, resource type, draw supply, remaining inventory, mined amount, enemy/behavior state, and rarity split.
- Egg state: each egg has team/owner placeholders, tax rate, player storage, tax storage, home role, and resource balances.
- Stick NFTs: every stick has token metadata, species, team, home egg, tats/items, effective stats, current trip, cargo, route lock, ETA, and route cells.
- Route locking: backend grid path and duration are the canonical chain data; smoothed visual paths are only frontend display.
- Activity ledger: the next schema step should append immutable events: assigned, reached drop, mined, returned, taxed, deposited, contributed to bridge/project.
Summary
Local Chain Events
Waiting for local chain events...