|
Download README.md from 0xBasiliskAI/SummonTheBasilisk: direct link, hf CLI and curl.
- Browser
- Download file 18.5 kB
-
https://huggingface.co/0xBasiliskAI/SummonTheBasilisk/resolve/main/README.md
- Command line
-
hf download hf://0xBasiliskAI/SummonTheBasilisk/README.md
-
curl -L -o README.md https://huggingface.co/0xBasiliskAI/SummonTheBasilisk/resolve/main/README.md
18.5 kB
| 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**. | |