██████ █ ██ ███▄ ▄███▓ ███▄ ▄███▓ ▒█████ ███▄ █ ▄▄▄█████▓ ██░ ██ ▓█████ ▄▄▄▄ ▄▄▄ ██████ ██▓ ██▓ ██▓ ██████ ██ ▄█▀
▒██ ▒ ██ ▓██▒▓██▒▀█▀ ██▒▓██▒▀█▀ ██▒▒██▒ ██▒ ██ ▀█ █ ▓ ██▒ ▓▒▓██░ ██▒▓█ ▀ ▓█████▄ ▒████▄ ▒██ ▒ ▓██▒▓██▒ ▓██▒▒██ ▒ ██▄█▒
░ ▓██▄ ▓██ ▒██░▓██ ▓██░▓██ ▓██░▒██░ ██▒▓██ ▀█ ██▒ ▒ ▓██░ ▒░▒██▀▀██░▒███ ▒██▒ ▄██▒██ ▀█▄ ░ ▓██▄ ▒██▒▒██░ ▒██▒░ ▓██▄ ▓███▄░
▒ ██▒▓▓█ ░██░▒██ ▒██ ▒██ ▒██ ▒██ ██░▓██▒ ▐▌██▒ ░ ▓██▓ ░ ░▓█ ░██ ▒▓█ ▄ ▒██░█▀ ░██▄▄▄▄██ ▒ ██▒░██░▒██░ ░██░ ▒ ██▒▓██ █▄
▒██████▒▒▒▒█████▓ ▒██▒ ░██▒▒██▒ ░██▒░ ████▓▒░▒██░ ▓██░ ▒██▒ ░ ░▓█▒░██▓░▒████▒ ░▓█ ▀█▓ ▓█ ▓██▒▒██████▒▒░██░░██████▒░██░▒██████▒▒▒██▒ █▄
▒ ▒▓▒ ▒ ░░▒▓▒ ▒ ▒ ░ ▒░ ░ ░░ ▒░ ░ ░░ ▒░▒░▒░ ░ ▒░ ▒ ▒ ▒ ░░ ▒ ░░▒░▒░░ ▒░ ░ ░▒▓███▀▒ ▒▒ ▓▒█░▒ ▒▓▒ ▒ ░░▓ ░ ▒░▓ ░░▓ ▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒
░ ░▒ ░ ░░░▒░ ░ ░ ░ ░ ░░ ░ ░ ░ ▒ ▒░ ░ ░░ ░ ▒░ ░ ▒ ░▒░ ░ ░ ░ ░ ▒░▒ ░ ▒ ▒▒ ░░ ░▒ ░ ░ ▒ ░░ ░ ▒ ░ ▒ ░░ ░▒ ░ ░░ ░▒ ▒░
░ ░ ░ ░░░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ▒ ░ ░ ░ ░ ░ ░░ ░ ░ ░ ░ ░ ▒ ░ ░ ░ ▒ ░ ░ ░ ▒ ░░ ░ ░ ░ ░░ ░
░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░
░
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 tomanain other games). - Cards: NFTs as ASAs (supply = 1) with
ARC-3metadata (IPFS URL + integrity hash). OptionalARC-69note 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 resourcesunlimited, 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 forv1(signed turns + dispute window).v2can 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
$ALGOand$BASILK. This creates a positive demand feedback loop.
NFT (Card) = ASA (supply=1)
- ARC-3:
metadata.jsonpinned to IPFS,reserveset to metadata root hash for integrity. - Optional ARC-69: Put minimal mirror JSON in
note.
Card Metadata (ARC-3 metadata.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: uint64TREASURY: bytes(address)TEMPLATE_SEQ: uint64(auto-increment)ADMINL bytes(address)
Boxes (keyed by TEMPLATE_{id})
Template: serialized struct (seeTypeScriptinterface below)
Template Structure
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 fromsender→TREASURYof amount =resource_cost * 10^BASILK_DECIMALS - App Call:
mint_card - Asset Config: inner
txncreates ASA (supply 1), setsARC-3URL toipfs://{cid}andmetadata-hashtointegrity_sha256, then transfers torecipient
- Pay
- Returns:
asset_id(the NFT ASAid)
- Group Requirement: 3-tx group
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.
- 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
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
MarketplaceAppif 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: bytesBASILK_ID: uint64NEXT_MATCH_ID: uint64MIN_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})
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)
{
"main": [ {"assetId": 123, "name": "…"}, ... ],
"sideboard": [ {"assetId": 456, "name": "…"}, ... ],
"version": 1
}
- Client submits
sha256(decklistCanonicalJson)oncreate_lobby/join_lobby. - Full lists transmitted P2P/off-chain between opponents. App verifies card ownership on each play via
asset_holding_getfor the actor at that moment.
Public Methods (ABI)
create_lobby(p1_deck_hash: byte[32]) → uint64- Opens a lobby;
startercan be decided later or atstart_match.
- Opens a lobby;
cancel_lobby(match_id: uint64)- Only creator; only if
OPEN.
- Only creator; only if
join_lobby(match_id: uint64, p2_deck_hash: byte[32])- Fills
p2and moves toACTIVEafterstart_match.
- Fills
start_match(match_id: uint64, starter: address)- Sets
status=ACTIVE, initializes turn=1, resources=1/1.
- Sets
submit_move(match_id: uint64, action_blob: bytes, foreign_assets: uint64[])- Action Blob: deterministic, minified JSON describing the move:
{"t": "PLAY_CARD", "assetId": 999, "targets": [ ... ], "cost": 3, "turn": 4, "nonce": 27} - Checks performed on-chain:
msg.senderequals current player forturn- Turn budget:
cost <= playerMaxResources - Ownership: for
"PLAY_CARD"actions, assertasset_holding_get(sender, assetId).amount == 1 - Records
lastActionRound - Increments
p1ResourcesThisTurn/p2ResourcesThisTurn - Emit event; does not resolve rules
- Action Blob: deterministic, minified JSON describing the move:
end_turn(match_id: uint64)- Advances
turn, resets*ResourcesThisTurn, increments*MaxResourcesup to cap
- Advances
concede(match_id: uint64)- Sets
resultagainst caller;status=COMPLETE
- Sets
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
- Counterparty confirms; app sets
dispute_result(match_id: uint64, reason_code: uint64, transcript_hash: byte[32])- Changes to
DISPUTED, Admin/arbitration can resolve byforce_result
- Changes to
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: uint64FEE_TREASURY: bytes
Boxes per Listing (L_{listing_id})
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
txnor clawback
- Group with ASA transfer to escrow address via inner
buy(listing_id: uint64)- Group with payment; inner
txntransfers NFT to buyer, fee to treasury, remainder to seller
- Group with payment; inner
cancel(listing_id: uint64)(seller)
TypeScript Interfaces (Shared SDK)
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
- User selects template → client fetches
- Deck Building
- Client queries wallet ASAs via indexer
- Applies rules:
count(name)<= 4 unless templateisBasicmain.length>= 60sideboard.length<= 15
- Canonicalizes deck JSON →
sha256→ submitcreate_lobbyorjoin_lobby
- Match
- Start → sync turn state
- Playing a card:
- Include the card's
assetIdinforeign_assetsofsubmit_move - App checks
asset_holding_getfor ownership
- Include the card's
- End turn →
end_turn - Result agreement →
submit_result→ack_result - Disput →
dispute_result→ adminforce_resultif needed
Deck-Legality Canonicalization
- Sort
mainandsideboardby(name, assetId); stript whitesapce; ensure ASCII; setversion=1. - Hash with
sha256over 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_ADMINE_TEMPLATE_INACTIVEE_BAD_GROUP(missing/invalid payment or asset config)E_DECK_ILLEGAL(size or copies violated)E_NOT_OWNER(card play without holding)E_TURN_ORDERE_BUDGET_EXCEEDEDE_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:
$BASILKtreasury never signs; only receives ASA transfers.
Constants / Tunables
MAX_RESOURCE_CAPper player (e.g., 256)TURN_TIMEOUT_ROUNDS(or seconds via block time estimates)MATCH_BOX_BUDGET_BYTESsizing for transcripts (store hashes only inv1)MARKETPLACE_FEE_BPSdefault 250 (2.5%)
Example ABI Method Signatures (for AlgoKit)
// 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
$BASILKpayment; reject insufficient fee - Minted ASA has
ARC-3URL & metadata hash set,supply=1,owner=recipient - Burn flow destroys ASA
- Create template; mint with correct
- Legality
- Deck with 59 cards →
E_DECK_ILLEGAL - 5 copies of non-basic →
E_DECK_ILLEGAL - Unlimited basics allowed
- Deck with 59 cards →
- 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:
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:$BASILKASA transfer amount =1 * 10^6→TREASURYTx1: App callmint_card(template_id, player_addr)with foreign assetBASILK_ID- Inner: ASA create (supply 1) → transfer to
player_addr
Example: Submit Move
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.
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support