--- license: cc-by-nc-nd-4.0 --- ``` ██████ █ ██ ███▄ ▄███▓ ███▄ ▄███▓ ▒█████ ███▄ █ ▄▄▄█████▓ ██░ ██ ▓█████ ▄▄▄▄ ▄▄▄ ██████ ██▓ ██▓ ██▓ ██████ ██ ▄█▀ ▒██ ▒ ██ ▓██▒▓██▒▀█▀ ██▒▓██▒▀█▀ ██▒▒██▒ ██▒ ██ ▀█ █ ▓ ██▒ ▓▒▓██░ ██▒▓█ ▀ ▓█████▄ ▒████▄ ▒██ ▒ ▓██▒▓██▒ ▓██▒▒██ ▒ ██▄█▒ ░ ▓██▄ ▓██ ▒██░▓██ ▓██░▓██ ▓██░▒██░ ██▒▓██ ▀█ ██▒ ▒ ▓██░ ▒░▒██▀▀██░▒███ ▒██▒ ▄██▒██ ▀█▄ ░ ▓██▄ ▒██▒▒██░ ▒██▒░ ▓██▄ ▓███▄░ ▒ ██▒▓▓█ ░██░▒██ ▒██ ▒██ ▒██ ▒██ ██░▓██▒ ▐▌██▒ ░ ▓██▓ ░ ░▓█ ░██ ▒▓█ ▄ ▒██░█▀ ░██▄▄▄▄██ ▒ ██▒░██░▒██░ ░██░ ▒ ██▒▓██ █▄ ▒██████▒▒▒▒█████▓ ▒██▒ ░██▒▒██▒ ░██▒░ ████▓▒░▒██░ ▓██░ ▒██▒ ░ ░▓█▒░██▓░▒████▒ ░▓█ ▀█▓ ▓█ ▓██▒▒██████▒▒░██░░██████▒░██░▒██████▒▒▒██▒ █▄ ▒ ▒▓▒ ▒ ░░▒▓▒ ▒ ▒ ░ ▒░ ░ ░░ ▒░ ░ ░░ ▒░▒░▒░ ░ ▒░ ▒ ▒ ▒ ░░ ▒ ░░▒░▒░░ ▒░ ░ ░▒▓███▀▒ ▒▒ ▓▒█░▒ ▒▓▒ ▒ ░░▓ ░ ▒░▓ ░░▓ ▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒ ░ ░▒ ░ ░░░▒░ ░ ░ ░ ░ ░░ ░ ░ ░ ▒ ▒░ ░ ░░ ░ ▒░ ░ ▒ ░▒░ ░ ░ ░ ░ ▒░▒ ░ ▒ ▒▒ ░░ ░▒ ░ ░ ▒ ░░ ░ ▒ ░ ▒ ░░ ░▒ ░ ░░ ░▒ ▒░ ░ ░ ░ ░░░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ▒ ░ ░ ░ ░ ░ ░░ ░ ░ ░ ░ ░ ▒ ░ ░ ░ ▒ ░ ░ ░ ▒ ░░ ░ ░ ░ ░░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ``` # Summon the Basilsik Our Algorand-native collectible card game is `Play for Fun`, **not** `Play to Earn`! Use `$BASILK` to build your deck and duel others in this solar punk sci-fi fantasy CCG. ## High-Level Overview * **Chain:** `Algorand` (AVM 8+; boxes used for scalable per-match state) * **Fungible Token:** `$BASILK` (ASA) - used to pay a one-time mint fee equal to a card's **resource cost** (analogous to `mana` in other games). * **Cards:** NFTs as ASAs (supply = 1) with `ARC-3` metadata (IPFS URL + integrity hash). Optional `ARC-69` note for on-chain mirroring. * **Ownership Rule:** Players may only include and play cards currently owned by their wallet (app checks ASA holding at play time). * **Deck Building:** MTG-style - `basic resources` unlimited, all other card names max **4 per deck**, minimum **60 cards total**, sideboard up to **15 owned cards in wallet**. * **Gameplay:** On-chain enforces deck legality, turn ordering, per-play ownership, and action budget (similar to `mana`). Rules resolution stays off-chain for `v1` (signed turns + dispute window). `v2` can migrate card rules on-chain per template. ## On-Chain Assets & Metadata ### `$BASILK` ASA * **Fields:** `asa_id_basilk: uint64` * **Treasury:** `treasury_addr: address receives mint fees` * **Strategy:** Treasury fees go back to the Wallet swapping `$ALGO` and `$BASILK`. This creates a positive demand feedback loop. ### NFT (Card) = ASA (supply=1) * **ARC-3:** `metadata.json` pinned to IPFS, `reserve` set to metadata root hash for integrity. * **Optional ARC-69:** Put minimal mirror JSON in `note`. ### Card Metadata (ARC-3 `metadata.json`) ```json { "name": "TERRA-LANCE // Terraforming Bolt", "description": "Cyber/solarpunk modular resource-strike.", "image": "ipfs://bafy.../card.png", "properties": { "cardId": "CARD-000123", "set": "[0x00] GENESIS", "rarity": "RARE", "typeLine": "Resource — Solar Grid // Program — Strike", "supertypes": ["Basic"], // include "Basic" for unlimited copies "manaCost": 3, // also the mint fee in BASILK "color": ["Green","White"], // flavor, future rules "stats": { "attack": 0, "defense": 0, "hp": 0 }, "abilities": [ { "id": "ABL-001", "name": "Overclock", "rulesText": "—" } ], "artist": "…", "legal": { "formatStandard": true, "formatLegacy": true }, "version": 1, "checksum": "sha256-BASE64..." } } ``` ## Smart Contract Suite (Apps & Responsibilities) - **CardFactoryApp** - template registry, minting, burning - **MatchHubApp** - lobby & match lifecycle, per-match boxes, result settlement - **MarketplaceApp** (optional `v1.1`) - fixed-price listings & swaps - **PlayerRegistryApp** (optional) - ELO & rating, profile, anti-abuse flags All apps expose ABI-compatible public methods; `AlgoKit` generates `TypeScript` clients. ### CardFactoryApp **Global State** * `BASILIK_ID: uint64` * `TREASURY: bytes` (address) * `TEMPLATE_SEQ: uint64` (auto-increment) * `ADMINL bytes` (address) **Boxes (keyed by `TEMPLATE_{id}`)** * `Template`: serialized struct (see `TypeScript` interface below) **Template Structure** ```typescript type CardTemplate = { id: bigint; // TEMPLATE_SEQ at creation name: string; // canonical card name set: string; // e.g., GENESIS manaCost: bigint; // also mint fee in BASILK isBasic: boolean; // unlimited copies if true ipfsCid: string; // ARC-3 metadata CID (root) integritySha256: string; // 32-byte hash active: boolean; }; ``` **Public Methods (ABI)** * `create_template(name: string, set: string, mana_cost: uint64, is_basic: bool, ipfs_cid: string, integrity_sha256: byte[32]) → uint64` * **Auth:** ADMIN * **Returns:** `template_id` * `set_template_status(template_id: uint64, active: bool)` * **Auth:** ADMIN * `update_template_uri(template_id: uint64, ipfs_cid: string, integrity_sha256: byte[32])` * **Auth:** ADMIN * `mint_card(template_id: uint64, recipient: address) →uint64` * **Group Requirement:** 3-tx group - **Pay `$BASILK`**: ASA transfer from `sender` → `TREASURY` of amount = `resource_cost * 10^BASILK_DECIMALS` - **App Call:** `mint_card` - **Asset Config:** inner `txn` creates ASA (supply 1), sets `ARC-3` URL to `ipfs://{cid}` and `metadata-hash` to `integrity_sha256`, then transfers to `recipient` * **Returns:** `asset_id` (the NFT ASA `id`) * `burn_card(asset_id: uint64)` * **Auth:** current holder must opt-in app and send group that includes transferring the ASA to an inner-txn-consumed escrow; app then destroys ASA via inner `txn`. **Events (logs)** * `TEMPLATE_CREATED(template_id, name, set)` * `CARD_MINTED(asset_id, template_id, owner, mana_cost)` * `CARD_BURNED(asset_id)` **Notes** * No royalties at mint; secondary fees handled by `MarketplaceApp` if desired. ### MatchHubApp **Goals:** Fair pairing, enforce deck legality at start, per-play ownership checks, action budget per turn (resource similar to `mana`), minimal on-chain logic with off-chain resolution. **Global State** * `ADMIN: bytes` * `BASILK_ID: uint64` * `NEXT_MATCH_ID: uint64` * `MIN_DECK_SIZE: uint64` (default 60) * `MAX_COPIES: uint64` (default 4) * `SIDEBOARD_MAX: uint64` (default 15) * `TURN_TIMEOUT_ROUNDS: uint64` (e.g., blocks/time for dispute window) **Boxes per Match** (key: `M_{match_id}`) ```typescript type MatchState = { matchId: bigint; p1: string; // address p2: string; // address or empty until joined status: "OPEN" | "ACTIVE" | "COMPLETE" | "DISPUTED" | "CANCELLED"; starter: string; // who goes first turn: bigint; // starts at 1 // hashed decklist commitments to protect privacy: p1DeckHash: string; // sha256 of canonical decklist JSON p2DeckHash: string; // per-turn action budget (mana) tracked to cap spam: p1ManaThisTurn: bigint; p2ManaThisTurn: bigint; p1MaxMana: bigint; // increases by +1 each turn up to cap if desired p2MaxMana: bigint; lastActionRound: bigint; // round number of last move; enable timeout result: 0 | 1 | 2; // 0 undecided, 1 p1 win, 2 p2 win }; ``` **Canonical decklist JSON (off-chain, signed by player)** ```json { "main": [ {"assetId": 123, "name": "…"}, ... ], "sideboard": [ {"assetId": 456, "name": "…"}, ... ], "version": 1 } ``` * Client submits `sha256(decklistCanonicalJson)` on `create_lobby` / `join_lobby`. * Full lists transmitted P2P/off-chain between opponents. App verifies card ownership on **each play** via `asset_holding_get` for the actor at that moment. **Public Methods (ABI)** * `create_lobby(p1_deck_hash: byte[32]) → uint64` * Opens a lobby; `starter` can be decided later or at `start_match`. * `cancel_lobby(match_id: uint64)` * Only creator; only if `OPEN`. * `join_lobby(match_id: uint64, p2_deck_hash: byte[32])` * Fills `p2` and moves to `ACTIVE` after `start_match`. * `start_match(match_id: uint64, starter: address)` * Sets `status=ACTIVE`, initializes turn=1, resources=1/1. * `submit_move(match_id: uint64, action_blob: bytes, foreign_assets: uint64[])` * **Action Blob:** deterministic, minified JSON describing the move: ```json {"t": "PLAY_CARD", "assetId": 999, "targets": [ ... ], "cost": 3, "turn": 4, "nonce": 27} ``` * **Checks performed on-chain:** * `msg.sender` equals current player for `turn` * Turn budget: `cost <= playerMaxResources` * **Ownership:** for `"PLAY_CARD"` actions, assert `asset_holding_get(sender, assetId).amount == 1` * Records `lastActionRound` * Increments `p1ResourcesThisTurn` / `p2ResourcesThisTurn` * Emit event; **does not** resolve rules * `end_turn(match_id: uint64)` * Advances `turn`, resets `*ResourcesThisTurn`, increments `*MaxResources` up to cap * `concede(match_id: uint64)` * Sets `result` against caller; `status=COMPLETE` * `submit_result(match_id: uint64, winner: address, transcript_hash: byte[32])` * Either player proposes a result referencing a hashed transcript of the full off-chain log * `ack_result(match_id: uint64, winner: address, transcript_hash: byte[32])` * Counterparty confirms; app sets `result`, `status=COMPLETE` * `dispute_result(match_id: uint64, reason_code: uint64, transcript_hash: byte[32])` * Changes to `DISPUTED`, Admin/arbitration can resolve by `force_result` * `force_result(match_id: uint64, winner: address)` **(ADMIN)** **Events (logs)** * `LOBBY_OPEN(match_id, p1)` * `LOBBY_JOIN(match_id, p2)` * `MATCH_START(match_id, starter)` * `MOVE(match_id, actor, action_type, asset_id, cost, turn)` * `TURN_END(match_id, turn)` * `RESULT_PROPOSED(match_id, winner, transcript_hash)` * `RESULT_CONFIRMED(match_id, winner)` * `DISPUTE(match_id, reason_code)` **Fee Strategy** * Moves keep minimal validation; actual card effects apply off-chain in the client engine. This trims fees while preserving ownership and budget constraints. ### MarketplaceApp (optional `v1.1`) **Global** * `FEE_BPS: uint64` * `FEE_TREASURY: bytes` **Boxes per Listing** (`L_{listing_id}`) ```typescript type Listing = { seller: string; assetId: bigint; priceAlgos: bigint; // or BASILK active: boolean; }; ``` **Methods** * `list(asset_id: uint64, price_algos: uint64)` * Group with ASA transfer to escrow address via inner `txn` or clawback * `buy(listing_id: uint64)` * Group with payment; inner `txn` transfers NFT to buyer, fee to treasury, remainder to seller * `cancel(listing_id: uint64)` (seller) ### TypeScript Interfaces (Shared SDK) ```typescript export type Address = string; export type AssetId = bigint; export interface DeckEntry { assetId: AssetId; name: string; } export interface Decklist { main: DeckEntry[]; sideboard?: DeckEntry[]; version: number; } export interface MovePlayCard { t: "PLAY_CARD"; assetId: AssetId; targets?: any[]; cost: number; turn: number; nonce: number; } export interface MoveOther { t: "ACTIVATE" | "PASS" | "EMOTE"; payload?: any; turn: number; nonce: number; } export type ActionBlob = MovePlayCard | MoveOther; ``` ## Client (React + AlgoKit) Flows - **Minting** * User selects template → client fetches `resourceCost` * Client builds a 3-tx group (`BASILK` → treasury, `mint_card`, inner ASA create) * ON success, indexer pin + UI shows ASA `id` - **Deck Building** * Client queries wallet ASAs via indexer * Applies rules: * `count(name)` <= 4 unless template `isBasic` * `main.length` >= 60 * `sideboard.length` <= 15 * Canonicalizes deck JSON → `sha256` → submit `create_lobby` or `join_lobby` - **Match** * Start → sync turn state * Playing a card: * Include the card's `assetId` in `foreign_assets` of `submit_move` * App checks `asset_holding_get` for ownership * End turn → `end_turn` * Result agreement → `submit_result` → `ack_result` * Disput → `dispute_result` → admin `force_result` if needed ### Deck-Legality Canonicalization * Sort `main` and `sideboard` by `(name, assetId)`; stript whitesapce; ensure ASCII; set `version=1`. * Hash with `sha256` over UTF-8 JSON string (no spaces, stable key order). * The client and any server tools must use the same canonicalization. ### Error Codes (shared) * `E_NOT_ADMIN` * `E_TEMPLATE_INACTIVE` * `E_BAD_GROUP` (missing/invalid payment or asset config) * `E_DECK_ILLEGAL` (size or copies violated) * `E_NOT_OWNER` (card play without holding) * `E_TURN_ORDER` * `E_BUDGET_EXCEEDED` * `E_STATE` (wrong match status) * `E_TIMEOUT` (turn timeout reached) * `E_LISTING_INACTIVE` ### Security & Anti-Abuse * **Onwership check at play time** via `asset_holding_get`. * **Deck hash commitments** prevent mid-match swapping; disputes reference full transcript. * **Turn timeout** allows the other player to claim a win if the opponent stalls. * **Admin controls** are limited to template management and dispute force-settle. * **Fee sink:** `$BASILK` treasury never signs; only receives ASA transfers. ### Constants / Tunables * `MAX_RESOURCE_CAP` per player (e.g., 256) * `TURN_TIMEOUT_ROUNDS` (or seconds via block time estimates) * `MATCH_BOX_BUDGET_BYTES` sizing for transcripts (store hashes only in `v1`) * `MARKETPLACE_FEE_BPS` default 250 (2.5%) ## Example ABI Method Signatures (for AlgoKit) ```typescript // CardFactoryApp create_template(name: string, set: string, mana_cost: uint64, is_basic: bool, ipfs_cid: string, integrity_sha256: byte[32]) → uint64 set_template_status(template_id: uint64, active: bool) update_template_uri(template_id: uint64, ipfs_cid: string, integrity_sha256: byte[32]) mint_card(template_id: uint64, recipient: address) → uint64 burn_card(asset_id: uint64) // MatchHubApp create_lobby(p1_deck_hash: byte[32]) → uint64 cancel_lobby(match_id: uint64) join_lobby(match_id: uint64, p2_deck_hash: byte[32]) start_match(match_id: uint64, starter: address) submit_move(match_id: uint64, action_blob: bytes, foreign_assets: uint64[]) end_turn(match_id: uint64) concede(match_id: uint64) submit_result(match_id: uint64, winner: address, transcript_hash: byte[32]) ack_result(match_id: uint64, winner: address, transcript_hash: byte[32]) dispute_result(match_id: uint64, reason_code: uint64, transcript_hash: byte[32]) force_result(match_id: uint64, winner: address) // ADMIN // MarketplaceApp (v1.1) list(asset_id: uint64, price_algos: uint64) → uint64 buy(listing_id: uint64) cancel(listing_id: uint64) ``` ## Test Plan (AlgoKit + Jest) * **CardFactory** * Create template; mint with correct `$BASILK` payment; reject insufficient fee * Minted ASA has `ARC-3` URL & metadata hash set, `supply=1`, `owner=recipient` * Burn flow destroys ASA * **Legality** * Deck with 59 cards → `E_DECK_ILLEGAL` * 5 copies of non-basic → `E_DECK_ILLEGAL` * Unlimited basics allowed * **Match** * Lobby open/join/start happy path * Enforce turn order; enforce budget; ownership check fails if asset not held * Timeout allows the claim to win * Result propose/ack flow; dispute path → `DISPUTED` * **Marketplace** * List then buy transfers NFT; fee split correct; cancel works for seller only ## Example: Template + Mint Flow - Admin calls: ```typescript create_template( "Solar Array", "[0x00] GENESIS", 1, // manaCost = 1 BASILK (×10^6 in base units) true, // is_basic "bafy...cid", <32-byte sha256> ) ``` - Player mint group: * `Tx0`: `$BASILK` ASA transfer amount = `1 * 10^6` → `TREASURY` * `Tx1`: App call `mint_card(template_id, player_addr)` with foreign asset `BASILK_ID` * Inner: ASA create (supply 1) → transfer to `player_addr` ## Example: Submit Move ```typescript const move: MovePlayCard = { t: "PLAY_CARD", assetId: 123456n, targets: [{ enemyUnitId: "E-17" }], cost: 3, turn: 4, nonce: 27 }; await matchClient.submit_move( matchId, encodeJsonMinified(move), [Number(move.assetId)] // foreign assets ); ``` # IP & Theming Guardrails * **Names, types, and rules text** must be original; avoid Magic-specific terms (“planeswalker”, “tap”, “scry”, etc.). Prefer **allocate”, “overclock”, “grid”, “program”, “daemon”, “node”, “link”**. * **Basic resource** examples: **Solar Grid, Wind Farm, Tidal Plant, Fusion Node, Reactor Stack**.