create-dubhe 1.2.0-pre.99 → 2.0.0

package/templates/contract/sui-template/src/dubhe/sources/tests/user_storage_test.move

@@ -0,0 +1,160 @@
+/// Unit tests — UserStorage creation and registration
+///
+/// Covers:
+///   create_user_storage: initial state, registration recorded, duplicate abort
+///   canonical_owner is set correctly on creation
+///   session fields initialized to zero/empty
+#[test_only]
+module dubhe::user_storage_test;
+
+use dubhe::dapp_service::{Self, DappHub, DappStorage};
+use dubhe::dapp_system;
+use sui::test_scenario;
+
+public struct UsTestKey has copy, drop {}
+
+const USER: address = @0x1234;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+fun setup(scenario: &mut test_scenario::Scenario): (DappHub, DappStorage) {
+    let ctx = test_scenario::ctx(scenario);
+    (
+        dapp_system::create_dapp_hub_for_testing(ctx),
+        dapp_system::create_dapp_storage_for_testing<UsTestKey>(ctx),
+    )
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Initial state
+// ═══════════════════════════════════════════════════════════════════════════════
+
+#[test]
+fun test_initial_write_counts_are_zero() {
+    let mut scenario = test_scenario::begin(USER);
+    {
+        let ctx = test_scenario::ctx(&mut scenario);
+        let us = dapp_service::create_user_storage_for_testing<UsTestKey>(USER, ctx);
+
+        assert!(dapp_service::write_count(&us) == 0);
+        assert!(dapp_service::settled_count(&us) == 0);
+        assert!(dapp_service::unsettled_count(&us) == 0);
+
+        dapp_service::destroy_user_storage(us);
+    };
+    scenario.end();
+}
+
+#[test]
+fun test_canonical_owner_set_on_creation() {
+    let mut scenario = test_scenario::begin(USER);
+    {
+        let ctx = test_scenario::ctx(&mut scenario);
+        let us = dapp_service::create_user_storage_for_testing<UsTestKey>(USER, ctx);
+        assert!(dapp_service::canonical_owner(&us) == USER);
+        dapp_service::destroy_user_storage(us);
+    };
+    scenario.end();
+}
+
+#[test]
+fun test_session_fields_cleared_on_creation() {
+    let mut scenario = test_scenario::begin(USER);
+    {
+        let ctx = test_scenario::ctx(&mut scenario);
+        let us = dapp_service::create_user_storage_for_testing<UsTestKey>(USER, ctx);
+        assert!(dapp_service::session_key(&us) == @0x0);
+        assert!(dapp_service::session_expires_at(&us) == 0);
+        dapp_service::destroy_user_storage(us);
+    };
+    scenario.end();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// create_user_storage (via dapp_system) — registration guard
+// ═══════════════════════════════════════════════════════════════════════════════
+
+#[test]
+fun test_create_user_storage_registers_address() {
+    let sender = @0xABC;
+    let mut scenario = test_scenario::begin(sender);
+    {
+        let (dh, mut ds) = setup(&mut scenario);
+        let ctx = test_scenario::ctx(&mut scenario);
+
+        assert!(!dapp_service::has_registered_user_storage(&ds, sender));
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+        assert!(dapp_service::has_registered_user_storage(&ds, sender));
+
+        dapp_system::destroy_dapp_hub(dh);
+        dapp_system::destroy_dapp_storage(ds);
+    };
+    scenario.end();
+}
+
+#[test]
+#[expected_failure]
+fun test_create_user_storage_twice_aborts() {
+    let sender = @0xABC;
+    let mut scenario = test_scenario::begin(sender);
+    {
+        let (dh, mut ds) = setup(&mut scenario);
+        let ctx = test_scenario::ctx(&mut scenario);
+
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+        // Second call from the same address must abort with user_storage_already_exists.
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+
+        dapp_system::destroy_dapp_hub(dh);
+        dapp_system::destroy_dapp_storage(ds);
+    };
+    scenario.end();
+}
+
+#[test]
+fun test_different_users_can_each_create_one_user_storage() {
+    let user_a = @0xAAAA;
+    let user_b = @0xBBBB;
+
+    let mut scenario = test_scenario::begin(user_a);
+    {
+        let (dh, mut ds) = setup(&mut scenario);
+
+        // user_a creates their storage.
+        let ctx = test_scenario::ctx(&mut scenario);
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+        assert!(dapp_service::has_registered_user_storage(&ds, user_a));
+
+        // user_b creates theirs in a new tx.
+        test_scenario::next_tx(&mut scenario, user_b);
+        let ctx = test_scenario::ctx(&mut scenario);
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+        assert!(dapp_service::has_registered_user_storage(&ds, user_b));
+
+        dapp_system::destroy_dapp_hub(dh);
+        dapp_system::destroy_dapp_storage(ds);
+    };
+    scenario.end();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Suspended DApp guard
+// ═══════════════════════════════════════════════════════════════════════════════
+
+#[test]
+fun test_create_user_storage_succeeds_after_registration_check() {
+    let sender = @0xABC;
+    let mut scenario = test_scenario::begin(sender);
+    {
+        let (dh, mut ds) = setup(&mut scenario);
+        let ctx = test_scenario::ctx(&mut scenario);
+
+        // Must succeed.
+        dapp_system::create_user_storage(UsTestKey {}, &dh, &mut ds, ctx);
+        assert!(dapp_service::has_registered_user_storage(&ds, sender));
+
+        dapp_system::destroy_dapp_hub(dh);
+        dapp_system::destroy_dapp_storage(ds);
+    };
+    scenario.end();
+}

package/templates/contract/sui-template/src/dubhe/sources/utils/math.move

@@ -1,6 +1,7 @@
 module dubhe::dubhe_math {
     use std::u128;
     use std::u64;
+    use dubhe::error;
 
     public fun min(x: u256, y: u256): u256 {
         if (x < y) x else y
@@ -9,12 +10,12 @@ module dubhe::dubhe_math {
     public fun safe_mul(a: u256, b: u256): u256 {
         if (a == 0 || b == 0) return 0;
         let c = a * b;
-        assert!(c / a == b, 0);
+        error::math_overflow(c / a == b);
         c
     }
 
     public fun safe_div(a: u256, b: u256): u256 {
-        assert!(b != 0, 0);
+        error::division_by_zero(b != 0);
         a / b
     }
 
@@ -108,7 +109,7 @@ module dubhe::dubhe_math {
     }
 
     public(package) fun windows(x: &vector<u256>, size: u64): vector<vector<u256>> {
-        assert!(size > 0, 0);
+        error::invalid_window_size(size > 0);
 
         let length = vector::length(x);
         let mut result = vector::empty<vector<u256>>();

package/templates/contract/sui-template/src/dubhe/sources/utils/type_info.move

@@ -29,11 +29,11 @@ module dubhe::type_info {
     }
 
     public fun get_package_id<T>(): address {
-        let type_name = type_name::get<T>().get_address();
+        let type_name = type_name::with_defining_ids<T>().address_string();
         address::from_ascii_bytes(type_name.as_bytes())
     }
 
     public fun get_type_name_string<T>(): String {
-        type_name::get<T>().into_string()
+        type_name::with_defining_ids<T>().into_string()
     }
 }

package/templates/contract/sui-template/src/template/Move.toml

@@ -0,0 +1,12 @@
+[package]
+name = "template"
+version = "1.0.0"
+edition = "2024"
+
+[dependencies]
+Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "mainnet-v1.68.1" }
+Dubhe = { git = "https://github.com/0xobelisk/dubhe.git", subdir = "framework/src/dubhe", rev = "v1.2.0-pre.112" }
+
+[addresses]
+sui = "0x2"
+template = "0x0"

package/templates/contract/sui-template/src/template/sources/codegen/dapp_key.move

@@ -0,0 +1,47 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+#[allow(unused_use)]
+
+/* Autogenerated file. Do not edit manually. */
+
+module template::dapp_key {
+    use std::type_name;
+    use sui::address;
+    use std::ascii::String;
+
+    /// DappKey — package-level authorization token for this DApp.
+    ///
+    /// SECURITY: `new()` is intentionally `public(package)`.
+    /// Only code compiled into this package can construct a DappKey instance.
+    /// All framework write functions (`set_record`, `set_field`,
+    /// `take_record`, `create_user_storage`, …) require `_auth: DappKey`
+    /// as proof that the call originated from inside this package — an
+    /// external PTB cannot fabricate that proof.
+    ///
+    /// NEVER change `new()` to `public`, and never accept a DappKey
+    /// value as a parameter from an external caller.  Either mistake removes
+    /// every package-level access guard, allowing any PTB to write arbitrary
+    /// user data or register UserStorages without going through the DApp's
+    /// own entry functions.
+
+    public struct DappKey has copy, drop {}
+
+    /// Constructs an authorization token. Callable only from within this package.
+    /// Pass the result as `_auth` to any framework function that requires it.
+    public(package) fun new(): DappKey {
+        DappKey {}
+    }
+
+    public fun to_string(): String {
+        type_name::get<DappKey>().into_string()
+    }
+
+    public fun package_id(): address {
+        let package_id_str = type_name::get<DappKey>().get_address();
+        address::from_ascii_bytes(package_id_str.as_bytes())
+    }
+
+    public fun eq<DappKey1: copy + drop, DappKey2: copy + drop>(_: &DappKey1, _: &DappKey2): bool {
+        type_name::get<DappKey1>() == type_name::get<DappKey2>()
+    }
+}

package/templates/contract/sui-template/src/template/sources/codegen/genesis.move

@@ -0,0 +1,34 @@
+#[allow(lint(share_owned))]
+module template::genesis {
+    use sui::clock::Clock;
+    use dubhe::dapp_service::{DappHub, DappStorage};
+    use template::dapp_key;
+    use dubhe::dapp_system;
+    use std::ascii::string;
+    use sui::transfer;
+
+    // The one-shot guard is enforced inside dapp_system::create_dapp, which
+    // records the DappKey type in DappHub before returning DappStorage.
+    // genesis.move does not need to carry its own guard.
+    public entry fun run(dapp_hub: &mut DappHub, clock: &Clock, ctx: &mut TxContext) {
+        // create_dapp aborts with dapp_already_initialized_error on repeated calls.
+        let dapp_key = dapp_key::new();
+        let mut ds = dapp_system::create_dapp(dapp_key, dapp_hub, string(b"template"), string(b"template"), 0, clock, ctx);
+
+        // Set up initial DApp state (e.g. default resource values).
+        template::deploy_hook::run(&mut ds, ctx);
+
+        // Share DappStorage so every transaction can access it.
+        transfer::public_share_object(ds);
+    }
+
+    // Called during contract upgrades to register newly added resource tables
+    // and run any custom migration logic. `dubhe upgrade` rewrites the region
+    // between the separator comments; do not edit that block manually.
+    public(package) fun migrate(_dapp_hub: &mut DappHub, _dapp_storage: &mut DappStorage, _ctx: &mut TxContext) {
+        // ==========================================
+        // Add custom migration logic here (e.g. initialise new resource defaults).
+        // migrate_to_vN in migrate.move calls this function automatically.
+        // ==========================================
+    }
+}

package/templates/contract/sui-template/src/template/sources/codegen/init_test.move

@@ -0,0 +1,23 @@
+#[test_only]
+
+module template::init_test {
+  use dubhe::dapp_system;
+
+  /// Create a DappHub for testing without sharing it.
+  /// Suitable for unit tests that need a DappHub context.
+  public fun create_dapp_hub_for_testing(ctx: &mut TxContext): dubhe::dapp_service::DappHub {
+    dapp_system::create_dapp_hub_for_testing(ctx)
+  }
+
+  /// Create a DappStorage for this DApp without sharing it.
+  /// Suitable for unit tests that exercise global-resource functions.
+  public fun create_dapp_storage_for_testing(ctx: &mut TxContext): dubhe::dapp_service::DappStorage {
+    dubhe::dapp_system::create_dapp_storage_for_testing<template::dapp_key::DappKey>(ctx)
+  }
+
+  /// Create a UserStorage for `owner` without sharing it.
+  /// Suitable for unit tests that exercise user-level resource functions.
+  public fun create_user_storage_for_testing(owner: address, ctx: &mut TxContext): dubhe::dapp_service::UserStorage {
+    dubhe::dapp_system::create_user_storage_for_testing<template::dapp_key::DappKey>(owner, ctx)
+  }
+}

package/templates/contract/sui-template/src/template/sources/codegen/user_storage_init.move

@@ -0,0 +1,27 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+#[allow(unused_use)]
+
+/* Autogenerated file. Do not edit manually. */
+
+module template::user_storage_init {
+  use dubhe::dapp_service::{DappHub, DappStorage};
+  use dubhe::dapp_system;
+  use template::dapp_key;
+  use template::dapp_key::DappKey;
+  use template::migrate;
+
+  /// Create a UserStorage for the transaction sender within this DApp.
+  /// Must be called once before the user can interact with any user-level resources.
+  /// Aborts if the DApp version does not match this package, the DApp is paused,
+  /// or the framework version has advanced.
+  #[allow(lint(public_entry))]
+  public entry fun init_user_storage(
+      dapp_hub: &DappHub,
+      dapp_storage: &mut DappStorage,
+      ctx: &mut TxContext,
+  ) {
+      dapp_system::ensure_latest_version<DappKey>(dapp_storage, migrate::on_chain_version());
+      dapp_system::create_user_storage(dapp_key::new(), dapp_hub, dapp_storage, ctx);
+  }
+}

package/templates/contract/sui-template/src/template/sources/scripts/deploy_hook.move

@@ -0,0 +1,13 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+#[allow(unused_use)]
+
+/* Autogenerated file. Do not edit manually. */
+
+module template::deploy_hook {
+    use dubhe::dapp_service::DappStorage;
+
+    public(package) fun run(_dapp_storage: &mut DappStorage, _ctx: &mut TxContext) {
+        // Initialise any DappStorage-level defaults here.
+    }
+}

package/templates/contract/sui-template/src/template/sources/scripts/migrate.move

@@ -0,0 +1,7 @@
+module template::migrate {
+    const ON_CHAIN_VERSION: u32 = 1;
+
+    public fun on_chain_version(): u32 {
+        ON_CHAIN_VERSION
+    }
+}

package/templates/nextjs/sui-card-duel/.gitignore_

@@ -0,0 +1,51 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# dubhe 
+contracts/dubhe-framework/.history
+contracts/dubhe-framework/Move.lock
+**/build/
+src/chain/key.ts
+indexer.db
+node_logs
+mprocs.log
+.data/

package/templates/nextjs/sui-card-duel/README.md

@@ -0,0 +1,213 @@
+# Card Duel — full-chain PvP card battles on Sui
+
+Card Duel is a Dubhe template that demonstrates every storage tier and
+authorization primitive of the framework in one playable game: 1v1 duels
+with gold stakes, multiplayer brawl rooms, a card marketplace, and an
+on-chain arena treasury that collects a rake from every match. All match
+actions are signed silently by a session key while every on-chain identity
+resolves to the player's main wallet.
+
+## Gameplay
+
+The game is a turn-based card battler with a closed gold economy.
+
+### Onboarding
+
+Connect a wallet, create your UserStorage, and register. Registration grants
+500 gold and a 5-card starter deck (3× Strike, 1× Fireball, 1× Shield).
+Activate a session key from the banner to play without wallet popups.
+
+### Cards and decks
+
+Every card has a kind and a rarity. Kinds decide what the card does; rarity
+multiplies its power.
+
+| Kind     | Effect               | Base power | Pack odds |
+| -------- | -------------------- | ---------- | --------- |
+| Strike   | damage to a target   | 12         | 40%       |
+| Fireball | damage to a target   | 18         | 25%       |
+| Heal     | restore your HP      | 10         | 20%       |
+| Shield   | absorb future damage | 8          | 15%       |
+
+| Rarity | Pack odds | Power bonus |
+| ------ | --------- | ----------- |
+| Common | 70%       | —           |
+| Rare   | 25%       | +1/3        |
+| Epic   | 5%        | +3/4        |
+
+Card packs cost 100 gold and mint one random card using `sui::random`.
+Your battle deck is exactly 5 distinct cards you own; editing the deck is
+free (ownership is verified on-chain).
+
+### Duel (1v1, direct invitation)
+
+Challenge a specific address with a gold stake. Your stake is escrowed into
+the match scene immediately; the opponent's stake joins the pot when they
+accept. Players alternate turns at 30 HP each, and every card can be played
+once per duel. Knock the opponent to 0 HP, then collect the pot minus the
+3% arena rake. Surrender concedes the pot; a player who stalls past the
+5-minute turn timeout can be claimed against. The challenger can cancel a
+pending invite for a full refund.
+
+### Brawl (1vN, open room)
+
+Open a room with an entry fee and a player cap (2–8). Anyone can join until
+the room is full; joining escrows the fee, and leaving an open room refunds
+it. Once at least two players are in, the host starts the match. Turns
+rotate through the alive list; attack cards require picking a target, and
+cards are reusable between turns. Eliminated players drop out of rotation,
+stalling players can be kicked on timeout, and the last player standing
+collects the whole pot (minus rake).
+
+### Market, leaderboard, and admin
+
+- **Market** — list cards (NFT-style records) or gold (fungible amounts)
+  for SUI. Purchases settle through the framework marketplace with
+  automatic fee splitting. Trades require the main wallet.
+- **Leaderboard** — ladder rating (1200 start, ±25 per match) read from the
+  indexer.
+- **Admin** — the deployer wallet configures the arena display data and the
+  game config (pack price, starting gold, rake, HP, turn timeout), and
+  withdraws the accumulated rake from the arena treasury into its own gold
+  balance.
+
+The economy loop: win matches to earn gold, spend gold on packs to chase
+Rare/Epic cards, build a stronger deck, and sell surplus cards for SUI.
+
+## Dubhe feature coverage
+
+Use this template as a reference when you need a working example of a
+specific framework capability.
+
+| Capability                          | Where it is demonstrated                                                                  |
+| ----------------------------------- | ----------------------------------------------------------------------------------------- |
+| UserStorage resources               | `gold`, `profile`, `deck`, `battle_state`, `card` (per-player state)                      |
+| Global resources                    | `game_config` (singleton, set by `deploy_hook` / `arena_system::set_game_config`)         |
+| ObjectStorage (named shared object) | `arena` treasury — created by `deploy_hook` (entity id `"main"`), admin-only field writes |
+| SceneStorage (multi-user object)    | `duel` and `brawl` matches (escrowed pot + turn state)                                    |
+| ScenePermit: direct invitations     | `duel_system::create_duel` — only the invited opponent can accept                         |
+| ScenePermit: open invitations       | `brawl_system::create_brawl` — anyone joins until the room is full                        |
+| Reactive writes (cross-user)        | combat damage and loss records written to the opponent's UserStorage                      |
+| Transferable resources              | gold moves User ⇄ Scene (stake escrow), Scene → Object (rake), Object → User (withdraw)   |
+| Listable resources / marketplace    | `market_system` — card NFTs and fungible gold listed for SUI                              |
+| Session keys + canonical owner      | every match action is session-signed; on-chain identity resolves to the main wallet       |
+| Randomness                          | `card_system::open_pack` uses `sui::random::Random`                                       |
+| Indexer system tables               | `dubheSceneStorages`, `dubheObjectStorages`, `dubheSessions`, marketplace tables          |
+| Deploy hook                         | `deploy_hook` initialises the game config and creates the shared arena at publish time    |
+
+## Session keys and identity
+
+Match actions (create, accept, attack, defend, finish, leave) are signed by
+an ephemeral session key once you activate one from the header — no wallet
+popup per move. The contracts never use the transaction sender as the player
+identity: every system resolves the player through
+`dapp_service::canonical_owner(user_storage)`, so permit participants, scene
+fields, profiles, and gold are always recorded under the main wallet address
+even when a session key signs. Revoking the session
+(`dapp_system::deactivate_session`) immediately removes its write access.
+
+On the client, session state is scoped per (network, main wallet address):
+each account keeps its own ephemeral keypair, switching accounts never shows
+another account's session, and the local state is revalidated against the
+indexer's `dubheSessions` table so sessions revoked elsewhere disappear
+automatically.
+
+Onboarding (UserStorage creation, registration, session activation) and
+marketplace trades still require the main wallet because they move SUI or
+establish the delegation itself.
+
+## Verified behaviour
+
+The template ships with two layers of tests, both runnable against this
+repository.
+
+### Move unit tests (29 cases, `pnpm test`)
+
+- **Duel lifecycle** — full flow from registration to knockout, settlement
+  (pot minus rake), profile/rating updates, and scene cleanup; cancel with
+  refund; surrender; timeout claims (success and "too early" failure).
+- **Session delegation** — a session key plays a full duel for its canonical
+  owner; an unauthorized signer is rejected.
+- **Guard rails** — self-challenge, zero stake, insufficient gold, uninvited
+  accept, out-of-turn attack, card reuse within a duel, attack card played
+  as defense, double-matching, loser attempting settlement, wrong deck size,
+  duplicate deck cards, double registration.
+- **Brawl lifecycle** — three-player flow with eliminations and pot
+  collection; entry-fee refunds on leave; full-room join rejection; host
+  leave/start restrictions; out-of-turn attacks; surrender deciding a match;
+  timeout kicks.
+
+### End-to-end scripts (against a running localnet stack)
+
+| Script                   | What it verifies                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `scripts/e2e-duel.ts`    | duel flow + indexer state (gold, profiles, scene destruction)                                     |
+| `scripts/e2e-brawl.ts`   | brawl flow + `open_pack` randomness + balance assertions                                          |
+| `scripts/e2e-session.ts` | session key plays a full duel; identity resolves to the main wallet; revoked sessions lose access |
+| `scripts/e2e-lobby.ts`   | the client's scene-discovery queries (dappKey-filtered) against live GraphQL                      |
+| `scripts/e2e-market.ts`  | card/gold listing, purchase, and listing closure                                                  |
+
+`open_pack` and the market system are covered by the e2e layer rather than
+unit tests because they depend on `sui::random` and marketplace settlement.
+
+## Requirements
+
+- Node.js 18.20+ and pnpm 9+
+- [Sui CLI](https://docs.sui.io/build/install)
+- Docker (for the indexer's PostgreSQL + GraphQL server)
+
+## Quick start
+
+Run everything (localnet node, contract deployment, indexer, GraphQL server,
+and the Next.js client) with one command from the template root:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` opens an mprocs dashboard with five processes: `node` (localnet),
+`contracts` (deploy + indexer), `graphql` (Docker), `client` (Next.js on
+http://localhost:3000), and an interactive `shell`. Wait until the client
+process reports "Ready", then open the app and connect a Sui wallet that is
+set to localnet.
+
+To seed a custom game configuration after deployment:
+
+```bash
+cd packages/contracts
+pnpm seed:localnet
+```
+
+## Project structure
+
+```
+packages/
+  contracts/
+    dubhe.config.ts          # resources, objects, scenes, permits, errors
+    src/card_duel/
+      sources/systems/       # player / card / duel / brawl / arena / market
+      sources/scripts/       # deploy_hook (game config + arena creation)
+      sources/tests/         # Move unit tests (pnpm test)
+    scripts/                 # seed, revenue, and e2e verification scripts
+  client/
+    src/app/                 # lobby, collection, duel/[id], brawl/[id],
+                             # market, leaderboard, admin
+    src/app/lib/             # bcs decoders, scene discovery, game constants
+    src/app/hooks/           # useGame (state + tx), useSessionKey
+```
+
+## Useful commands
+
+Run these from `packages/contracts` unless noted otherwise.
+
+| Command                                  | Purpose                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `pnpm test`                              | Move unit tests (29 cases)                                           |
+| `pnpm tsx scripts/e2e-duel.ts`           | Scripted 1v1 duel against a running localnet stack                   |
+| `pnpm tsx scripts/e2e-brawl.ts`          | Scripted brawl + pack opening                                        |
+| `pnpm tsx scripts/e2e-session.ts`        | Full duel played by a session key; verifies canonical-owner identity |
+| `pnpm tsx scripts/e2e-market.ts`         | Scripted card/gold listing and purchase                              |
+| `pnpm tsx scripts/e2e-lobby.ts`          | Verifies the client's indexer queries; seeds lobby data              |
+| `pnpm seed:localnet`                     | Re-apply the default game configuration                              |
+| `pnpm tsx scripts/query-dapp-revenue.ts` | Inspect DApp fee revenue                                             |