0xobelisk/dubhe/dubhe-dapp

Dubhe DApp Development

This skill covers the full lifecycle of building a DApp on the Dubhe framework: from defining the schema in dubhe.config.ts, generating Move code, writing system functions, deploying on Sui, and interacting with the chain from TypeScript.

Reference Files

Load the relevant reference file(s) based on the user's question. Each file is self-contained.

Read multiple files when the question spans several topics. When in doubt about which to load, start with quickstart.md for new-user questions and dapp-api.md for API questions.

Key Concepts

Three-tier storage: DappHub (framework global) → DappStorage (per-DApp shared) → UserStorage (per-user shared object, one per user per DApp). DApp contracts never receive a raw address to identify users; the user passes their own UserStorage object, and the framework verifies ownership via canonical_owner.

Extended storage (codegen-driven): objects in dubhe.config.ts generates ObjectStorage<T> — DApp-controlled named entities (guilds, bosses). permits generates ScenePermit<T> — participant authorization objects used to gate reactive writes and permit-type scene field writes. scenes generates SceneStorage<T> — multi-user time-bounded shared objects (PvP matches, dungeon runs).

Code generation: dubhe.config.ts drives dubhe generate to produce all boilerplate under sources/codegen/. Never edit generated files by hand — change the config and regenerate.

Version guard: Every public entry function must call dapp_system::ensure_latest_version<DappKey>(dapp_storage, migrate::on_chain_version()) to prevent stale clients from writing after an upgrade.

Credits: Storage writes consume credits from DappStorage.credit_pool. Call dapp_system::settle_writes periodically to settle user debt. Top up with recharge_credit. The per-user unsettled write limit is MAX_UNSETTLED_WRITES = 2_000.

Quick Patterns

Minimal system function

module my_game::player_system;
 
use dubhe::dapp_service::{DappStorage, UserStorage};
use dubhe::dapp_system;
use my_game::dapp_key::DappKey;
use my_game::migrate;
use my_game::player;
 
public entry fun create_player(
    dapp_storage: &DappStorage,
    user_storage: &mut UserStorage,
    ctx: &mut TxContext
) {
    dapp_system::ensure_latest_version<DappKey>(dapp_storage, migrate::on_chain_version());
    player::set(user_storage, 100, 10, 1, ctx);
}

TypeScript client (recommended)

import { createClient } from '@0xobelisk/client/sui';
import latest from './.history/sui_testnet/latest.json';
import metadata from './metadata.json';
const client = createClient({
  network: 'testnet',
  packageId: latest.packageId,
  metadata,
  credentials: { secretKey: process.env.PRIVATE_KEY }
});
await client.contract.tx.player_system.create_player({ tx });