# VOIDRUN game specification

**Legacy identifiers:** technical paths, `CITADEL_*` configuration, `citadel_session`, `X-Citadel-CSRF`, `urn:citadel` / `citadel-local-test` namespaces and deterministic seeds remain unchanged for compatibility.

**Status: development foundation, local access/movement and opt-in duel prototype with simulated points.** This document describes intended product behavior and development-only rules, not a deployed protocol, security guarantee, token offer, contract specification or reward backend. The implemented [local agent API](agent-api.md) verifies EOA wallet signatures and explicitly configured local ownership fixtures, requires an NFT access code, and supports gameplay-only deployment/movement/status/stop. Default real ownership/deployment remains unavailable. This is not production chain/NFT verification or an audited authentication service. Existing root planning/research material remains historical reference rather than automatically verified fact.

## Selected network and funding direction

The selected network is **Robinhood Chain**, with **USDG** as the intended reward asset and the official project token as the upgrade-burn asset. No asset contract or token decimals are configured. Production network configuration and official asset identities must be verified before use; approved test assets must be identified separately.

The proposed funding source is a **2% trading fee/tax** associated with the official token. A token/USDG pair alone does not route such a fee to the treasury. The exchange/pool must support the chosen mechanism; fees received in project tokens require a separately reviewed conversion process with slippage and price-risk controls. Only confirmed USDG receipts, not volume estimates or unsold fee tokens, can back USDG task allocations. No guaranteed yield or fixed earning rate is promised.

## Scope and access

VOIDRUN may be viewed publicly. Deployment of an agent is intended to be restricted to a verified NFT holder. The intended collection size is **1,000**, but that is neither evidence that 1,000 NFTs have been minted nor proof that the system can support 1,000 active agents.

A future deployment flow must require all of the following before protected gameplay actions:

1. A wallet signs a challenge bound to the relying-party domain, a unique nonce, an issued-at time, and a short expiry.
2. The service verifies the signature and the official chain, collection contract, and token ID. None is currently configured in this prototype.
3. The service issues a revocable credential scoped to that NFT, its current owner, and the current season. The credential permits gameplay only; it must not grant wallet spending, transfer, burn, or claim authority.

Credentials must be rejected when absent, expired, revoked, incorrectly scoped, or no longer matched to current ownership. Credentials and signature challenges require secure server-side handling and durable replay prevention; browser storage is not a credential authority.

## NFT ownership and deployment lifecycle

A future authoritative service must recheck ownership before protected actions and monitor ownership transfers with chain-finality awareness. It must account for chain reorganizations before treating observed ownership as final. Only one active run may exist for an NFT at a time. Where ownership, finality, credential scope, or credential revocation cannot be verified, protected actions fail closed.

**Provisional transfer-run policy:** when an NFT transfer is detected or ownership becomes uncertain, suspend its active run, revoke the old holder's gameplay credential, and prevent further earning actions until the implementation resolves the run. A sale must not automatically bank carried loot, and an old credential must never continue earning for the former holder. Exact disposition of carried cargo during a transfer is intentionally unresolved pending the authoritative backend, settlement model, and user-facing policy.

## Authoritative gameplay

The browser is presentation only. A future server must authoritatively validate and resolve movement, tasks, combat, death, recovery, and vault arrival. Client-provided coordinates, task completions, combat results, and balances are not authoritative.

Action submission must use replay-safe identifiers and sequencing, per-action and per-credential rate limits, and durable event/ledger records. State transitions need idempotency and transactional handling so retries cannot duplicate a task result, kill result, deposit, settlement, or claim.

## Implemented local duel test — separate from intended economics

With explicit `CITADEL_LOCAL_ACCESS=1 CITADEL_LOCAL_COMBAT=1`, two independently authorized deployed agents can challenge/accept a pairwise local duel. Both start with 100 HP; the server applies fixed 10-damage attacks with a one-second cooldown, one-station-tile range in pixel coordinates and collision-aware line of sight. Movement is locked after acceptance. These test constants ignore chassis/level advantages and are not final balancing.

The server owns health, cooldown, winner and result. Completing a duel atomically creates one wallet-bound simulated point with **no monetary value**. The earning wallet's signed-in session can mark that entitlement claimed once; gameplay keys cannot. Completed entitlements survive restart and later NFT transfers. This local acknowledgement is not the future on-chain claim described below and has no asset, transaction, custody or settlement integration.

Unresolved duels cancel without reward on stop, access/key/session loss, revocation, logout or restart. Consent expires after 60 seconds; combat expires after 30 seconds without a valid hit or five minutes total. No timeout/forfeit winner is created. Defeated agents must explicitly stop and redeploy. Broader combat, tasks, loot, extraction and funded rewards remain unimplemented. See [agent-api.md](agent-api.md) for the actual local API and authority boundaries.

## Reward accounting and custody model

No real USDG funding, allocation, payout, or claim exists in this repository. If approved and implemented, value must move through explicit states:

```text
received funding
  -> reserved task allocation
  -> carried
  -> dropped/recovered OR deposited
  -> pending settlement
  -> claimable
  -> claimed
```

All accounting uses integer base units after the official asset and decimals are verified. Rounding must be deterministic and specified before implementation. The ledger must conserve funding: a unit of funded value may be in exactly one applicable state and must never be duplicated or created by a protection calculation. Death and deposit transitions must be atomic, including the disposition of all carried value.

Deposited earnings are protected at every level and remain assigned to the wallet that earned them even if the NFT is sold later. Cargo protection, if adopted, splits an existing allocation between protected and at-risk portions; it never generates additional money. Carried value remains subject to the authoritative run and transfer policies above until a valid deposit.

Claims require an explicit transaction authorized by the earning wallet. Selling the NFT must not prevent that wallet from claiming its already-settled earnings; current NFT ownership gates deployment, not redemption of an existing entitlement. An agent credential cannot spend from a wallet or claim on a holder's behalf. A future settlement service must document its trusted parties, pause controls, reconciliation process, and defenses against double claims and replayed claims. This design does not claim zero error, trustlessness, or elimination of operational trust.

## Levels, burns, and development rules

Agents begin at level 0 and are capped at level 10. A future upgrade must permanently burn the approved asset, validate current NFT ownership, atomically record the level increment, and apply changed stats only to the next deployment. Upgrade burns do **not** fund USDG rewards.

The shared development module is [`../src/game-rules.js`](../src/game-rules.js). It exports frozen, versioned configuration and pure functions. Its amounts are whole-token quantities, not guessed on-chain base units; conversion must wait for verified official token decimals.

| Upgrade target | Whole official-token burn cost | Status |
| --- | ---: | --- |
| 1–9 | `target level × 10,000` | Development rule |
| 10 | `200,000` | **Provisional development proposal** |

The provisional sample stat curve for a valid level `L` (0–10) is:

| Stat | Formula | Level-0 to level-10 range | Status |
| --- | --- | --- | --- |
| Health | `100 + 10L` | 100–200 | Provisional balancing |
| Power | `10 + L` | 10–20 | Provisional balancing |
| Capacity | `600 + 40L` | 600–1,000 | Provisional balancing |
| Cargo protection | `4L%` | 0–40% | Provisional balancing |

The final-level cost and all stat/cargo-protection curves are not finalized contract economics. The rules module has disabled wallet, chain, and settlement integrations and has no DOM, network, wallet, time, storage, or settlement side effects.

## Unresolved release gates

Resolve the following as applicable before each integration milestone, using separately approved test assets for testnet. Independent security/economic review and explicit deployment approval are required before enabling real funds:

- Official NFT collection, token, USDG contract addresses, supported chains, and token decimals.
- A verified exchange/pool mechanism compatible with the proposed 2% trading-fee funding idea. No fee mechanism is verified or implemented here.
- Whether OpenSea Drops supports the intended minting path. Marketplace support is not proof of minting support.
- Treasury custody, funding, settlement, claim, pause, recovery, and operational-control design.
- A reviewed wallet-signature/session implementation, authoritative durable backend, adversarial accounting/action tests, audit, and explicit deployment approval.

No production-chain action, real burn, real payout, or real claim has occurred.