create-dubhe 1.2.0-pre.98 → 2.0.0

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/dapp_key.move

@@ -0,0 +1,46 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::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::with_defining_ids<DappKey>().into_string()
+    }
+
+    public fun package_id(): address {
+        let package_id_str = type_name::with_defining_ids<DappKey>().address_string();
+        address::from_ascii_bytes(package_id_str.as_bytes())
+    }
+
+    public fun eq<DappKey1: copy + drop, DappKey2: copy + drop>(_: &DappKey1, _: &DappKey2): bool {
+        type_name::with_defining_ids<DappKey1>() == type_name::with_defining_ids<DappKey2>()
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/enums/crop_type.move

@@ -0,0 +1,47 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::crop_type {
+    use sui::bcs::{BCS, to_bytes, peel_enum_tag};
+
+    public enum CropType has copy, drop, store {
+        Carrot,Corn,None,Pumpkin,Wheat
+    }
+
+    public fun new_carrot(): CropType {
+        CropType::Carrot
+    }
+
+    public fun new_corn(): CropType {
+        CropType::Corn
+    }
+
+    public fun new_none(): CropType {
+        CropType::None
+    }
+
+    public fun new_pumpkin(): CropType {
+        CropType::Pumpkin
+    }
+
+    public fun new_wheat(): CropType {
+        CropType::Wheat
+    }
+
+    public fun encode(self: CropType): vector<u8> {
+        to_bytes(&self)
+    }
+
+    public fun decode(bytes: &mut BCS): CropType {
+        match(peel_enum_tag(bytes)) {
+            0 => CropType::Carrot,
+            1 => CropType::Corn,
+            2 => CropType::None,
+            3 => CropType::Pumpkin,
+            4 => CropType::Wheat,
+            _ => abort,
+        }
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/enums/egg_type.move

@@ -0,0 +1,42 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::egg_type {
+    use sui::bcs::{BCS, to_bytes, peel_enum_tag};
+
+    public enum EggType has copy, drop, store {
+        Common,None,Rare,Seasonal
+    }
+
+    public fun new_common(): EggType {
+        EggType::Common
+    }
+
+    public fun new_none(): EggType {
+        EggType::None
+    }
+
+    public fun new_rare(): EggType {
+        EggType::Rare
+    }
+
+    public fun new_seasonal(): EggType {
+        EggType::Seasonal
+    }
+
+    public fun encode(self: EggType): vector<u8> {
+        to_bytes(&self)
+    }
+
+    public fun decode(bytes: &mut BCS): EggType {
+        match(peel_enum_tag(bytes)) {
+            0 => EggType::Common,
+            1 => EggType::None,
+            2 => EggType::Rare,
+            3 => EggType::Seasonal,
+            _ => abort,
+        }
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/enums/pet_rarity.move

@@ -0,0 +1,37 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::pet_rarity {
+    use sui::bcs::{BCS, to_bytes, peel_enum_tag};
+
+    public enum PetRarity has copy, drop, store {
+        Common,Rare,Uncommon
+    }
+
+    public fun new_common(): PetRarity {
+        PetRarity::Common
+    }
+
+    public fun new_rare(): PetRarity {
+        PetRarity::Rare
+    }
+
+    public fun new_uncommon(): PetRarity {
+        PetRarity::Uncommon
+    }
+
+    public fun encode(self: PetRarity): vector<u8> {
+        to_bytes(&self)
+    }
+
+    public fun decode(bytes: &mut BCS): PetRarity {
+        match(peel_enum_tag(bytes)) {
+            0 => PetRarity::Common,
+            1 => PetRarity::Rare,
+            2 => PetRarity::Uncommon,
+            _ => abort,
+        }
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/enums/pet_species.move

@@ -0,0 +1,52 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::pet_species {
+    use sui::bcs::{BCS, to_bytes, peel_enum_tag};
+
+    public enum PetSpecies has copy, drop, store {
+        Bunny,Chick,Deer,Dragon,Fox,None
+    }
+
+    public fun new_bunny(): PetSpecies {
+        PetSpecies::Bunny
+    }
+
+    public fun new_chick(): PetSpecies {
+        PetSpecies::Chick
+    }
+
+    public fun new_deer(): PetSpecies {
+        PetSpecies::Deer
+    }
+
+    public fun new_dragon(): PetSpecies {
+        PetSpecies::Dragon
+    }
+
+    public fun new_fox(): PetSpecies {
+        PetSpecies::Fox
+    }
+
+    public fun new_none(): PetSpecies {
+        PetSpecies::None
+    }
+
+    public fun encode(self: PetSpecies): vector<u8> {
+        to_bytes(&self)
+    }
+
+    public fun decode(bytes: &mut BCS): PetSpecies {
+        match(peel_enum_tag(bytes)) {
+            0 => PetSpecies::Bunny,
+            1 => PetSpecies::Chick,
+            2 => PetSpecies::Deer,
+            3 => PetSpecies::Dragon,
+            4 => PetSpecies::Fox,
+            5 => PetSpecies::None,
+            _ => abort,
+        }
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/error.move

@@ -0,0 +1,110 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::error {
+    #[error]
+    const EAlreadyRegistered: vector<u8> = b"Player already registered";
+    public fun already_registered(condition: bool) { assert!(condition, EAlreadyRegistered) }
+
+    #[error]
+    const ENotRegistered: vector<u8> = b"Player not registered";
+    public fun not_registered(condition: bool) { assert!(condition, ENotRegistered) }
+
+    #[error]
+    const EPlotNotFound: vector<u8> = b"Farm plot not found";
+    public fun plot_not_found(condition: bool) { assert!(condition, EPlotNotFound) }
+
+    #[error]
+    const EPlotAlreadyPlanted: vector<u8> = b"Farm plot already has a crop growing";
+    public fun plot_already_planted(condition: bool) { assert!(condition, EPlotAlreadyPlanted) }
+
+    #[error]
+    const EPlotNotReady: vector<u8> = b"Crop is not ready to harvest yet";
+    public fun plot_not_ready(condition: bool) { assert!(condition, EPlotNotReady) }
+
+    #[error]
+    const EPlotIsEmpty: vector<u8> = b"No crop planted on this plot";
+    public fun plot_is_empty(condition: bool) { assert!(condition, EPlotIsEmpty) }
+
+    #[error]
+    const EMaxPlotsReached: vector<u8> = b"Maximum farm plots already owned";
+    public fun max_plots_reached(condition: bool) { assert!(condition, EMaxPlotsReached) }
+
+    #[error]
+    const EInsufficientGold: vector<u8> = b"Not enough gold";
+    public fun insufficient_gold(condition: bool) { assert!(condition, EInsufficientGold) }
+
+    #[error]
+    const EInsufficientSeeds: vector<u8> = b"Not enough seeds to plant";
+    public fun insufficient_seeds(condition: bool) { assert!(condition, EInsufficientSeeds) }
+
+    #[error]
+    const EInsufficientCrops: vector<u8> = b"Not enough crops";
+    public fun insufficient_crops(condition: bool) { assert!(condition, EInsufficientCrops) }
+
+    #[error]
+    const ECrowNoCharges: vector<u8> = b"No crow charges remaining";
+    public fun crow_no_charges(condition: bool) { assert!(condition, ECrowNoCharges) }
+
+    #[error]
+    const ECrowTargetProtected: vector<u8> = b"Target farm is protected by a scarecrow";
+    public fun crow_target_protected(condition: bool) { assert!(condition, ECrowTargetProtected) }
+
+    #[error]
+    const EInvalidCropType: vector<u8> = b"Invalid crop type";
+    public fun invalid_crop_type(condition: bool) { assert!(condition, EInvalidCropType) }
+
+    #[error]
+    const ESeasonNotActive: vector<u8> = b"No active season";
+    public fun season_not_active(condition: bool) { assert!(condition, ESeasonNotActive) }
+
+    #[error]
+    const ENotAdmin: vector<u8> = b"Caller is not the DApp admin";
+    public fun not_admin(condition: bool) { assert!(condition, ENotAdmin) }
+
+    #[error]
+    const EHatchSlotBusy: vector<u8> = b"Already incubating an egg";
+    public fun hatch_slot_busy(condition: bool) { assert!(condition, EHatchSlotBusy) }
+
+    #[error]
+    const ENoEggIncubating: vector<u8> = b"No egg is currently incubating";
+    public fun no_egg_incubating(condition: bool) { assert!(condition, ENoEggIncubating) }
+
+    #[error]
+    const EEggNotReady: vector<u8> = b"Egg is not ready to hatch yet";
+    public fun egg_not_ready(condition: bool) { assert!(condition, EEggNotReady) }
+
+    #[error]
+    const EPetNotFound: vector<u8> = b"Pet not found in your ranch";
+    public fun pet_not_found(condition: bool) { assert!(condition, EPetNotFound) }
+
+    #[error]
+    const EPetSlotNotFound: vector<u8> = b"Pet slot does not exist";
+    public fun pet_slot_not_found(condition: bool) { assert!(condition, EPetSlotNotFound) }
+
+    #[error]
+    const EPetSlotOccupied: vector<u8> = b"Pet slot already has a pet";
+    public fun pet_slot_occupied(condition: bool) { assert!(condition, EPetSlotOccupied) }
+
+    #[error]
+    const EPetSlotEmpty: vector<u8> = b"No pet in that slot";
+    public fun pet_slot_empty(condition: bool) { assert!(condition, EPetSlotEmpty) }
+
+    #[error]
+    const EMaxPetSlotsReached: vector<u8> = b"Maximum pet slots already owned";
+    public fun max_pet_slots_reached(condition: bool) { assert!(condition, EMaxPetSlotsReached) }
+
+    #[error]
+    const EInsufficientEggs: vector<u8> = b"Not enough eggs of that type";
+    public fun insufficient_eggs(condition: bool) { assert!(condition, EInsufficientEggs) }
+
+    #[error]
+    const EInvalidEggType: vector<u8> = b"Invalid egg type";
+    public fun invalid_egg_type(condition: bool) { assert!(condition, EInvalidEggType) }
+
+    #[error]
+    const EInvalidPetSlot: vector<u8> = b"Invalid pet slot index";
+    public fun invalid_pet_slot(condition: bool) { assert!(condition, EInvalidPetSlot) }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/genesis.move

@@ -0,0 +1,33 @@
+#[allow(lint(share_owned))]
+module harvest::genesis {
+    use sui::clock::Clock;
+    use dubhe::dapp_service::{DappHub, DappStorage};
+    use harvest::dapp_key;
+    use dubhe::dapp_system;
+    use std::ascii::string;
+
+    // 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 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"harvest"), string(b"Harvest - Full-chain casual farming game with light PvP"), 1, clock, ctx);
+
+        // Set up initial DApp state (e.g. default resource values).
+        harvest::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/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/init_test.move

@@ -0,0 +1,23 @@
+#[test_only]
+
+module harvest::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<harvest::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<harvest::dapp_key::DappKey>(owner, ctx)
+  }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/permits/world.move

@@ -0,0 +1,125 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::world {
+    use dubhe::dapp_service::{Self, DappStorage};
+    use harvest::dapp_key;
+    use harvest::dapp_key::DappKey;
+
+    const PERMIT_TYPE: vector<u8> = b"world";
+
+    #[error]
+    const EPermitNotExpiredYet: vector<u8> = b"Scene permit is still active";
+
+    /// Phantom type that distinguishes this permit from others at compile time.
+    public struct World has copy, drop {}
+
+    public fun meta(permit: &dubhe::dapp_service::ScenePermit<World>): &dubhe::dapp_service::PermitMetadata {
+        dapp_service::scene_permit_meta(permit)
+    }
+
+    public fun is_active(permit: &dubhe::dapp_service::ScenePermit<World>, now_ms: u64): bool {
+        dapp_service::is_scene_active(dapp_service::scene_permit_meta(permit), now_ms)
+    }
+
+    public fun is_participant(permit: &dubhe::dapp_service::ScenePermit<World>, addr: address): bool {
+        dubhe::dapp_system::is_scene_permit_participant<World>(permit, addr)
+    }
+
+    public(package) fun new_world(
+        dapp_storage:     &DappStorage,
+        participants:     vector<address>,
+        expires_at:       std::option::Option<u64>,
+        max_participants: std::option::Option<u64>,
+        ctx:              &mut TxContext,
+    ): dubhe::dapp_service::ScenePermit<World> {
+        dubhe::dapp_system::new_scene_permit<DappKey, World>(
+            dapp_key::new(), dapp_storage, PERMIT_TYPE, participants, expires_at, max_participants, ctx
+        )
+    }
+
+    public(package) fun new_world_with_invitations(
+        dapp_storage:      &DappStorage,
+        invitees:          vector<address>,
+        invites_expire_at: std::option::Option<u64>,
+        scene_expires_at:  std::option::Option<u64>,
+        max_participants:  std::option::Option<u64>,
+        ctx:               &mut TxContext,
+    ): dubhe::dapp_service::ScenePermit<World> {
+        dubhe::dapp_system::new_scene_permit_with_invitations<DappKey, World>(
+            dapp_key::new(), dapp_storage, PERMIT_TYPE, invitees, invites_expire_at, scene_expires_at, max_participants, ctx
+        )
+    }
+
+    public(package) fun share_world(permit: dubhe::dapp_service::ScenePermit<World>) {
+        dubhe::dapp_system::share_scene_permit<DappKey, World>(
+            dapp_key::new(), permit
+        );
+    }
+
+    public(package) fun create_world(
+        dapp_storage:     &DappStorage,
+        participants:     vector<address>,
+        expires_at:       std::option::Option<u64>,
+        max_participants: std::option::Option<u64>,
+        ctx:              &mut TxContext,
+    ) {
+        dubhe::dapp_system::create_and_share_scene_permit<DappKey, World>(
+            dapp_key::new(), dapp_storage, PERMIT_TYPE, participants, expires_at, max_participants, ctx
+        );
+    }
+
+    public(package) fun create_world_with_invitations(
+        dapp_storage:      &DappStorage,
+        invitees:          vector<address>,
+        invites_expire_at: std::option::Option<u64>,
+        scene_expires_at:  std::option::Option<u64>,
+        max_participants:  std::option::Option<u64>,
+        ctx:               &mut TxContext,
+    ) {
+        dubhe::dapp_system::create_and_share_scene_permit_with_invitations<DappKey, World>(
+            dapp_key::new(), dapp_storage, PERMIT_TYPE, invitees, invites_expire_at, scene_expires_at, max_participants, ctx
+        );
+    }
+
+    public(package) fun accept_world(
+        permit:       &mut dubhe::dapp_service::ScenePermit<World>,
+        user_storage: &dubhe::dapp_service::UserStorage,
+        ctx:          &TxContext,
+    ) {
+        dubhe::dapp_system::accept_scene_permit_invitation<DappKey, World>(
+            dapp_key::new(), permit, user_storage, ctx
+        );
+    }
+
+    public(package) fun join_world(
+        permit:       &mut dubhe::dapp_service::ScenePermit<World>,
+        user_storage: &dubhe::dapp_service::UserStorage,
+        ctx:          &TxContext,
+    ) {
+        dubhe::dapp_system::join_scene_permit<DappKey, World>(dapp_key::new(), permit, user_storage, ctx);
+    }
+
+    public(package) fun leave_world(
+        permit:       &mut dubhe::dapp_service::ScenePermit<World>,
+        user_storage: &dubhe::dapp_service::UserStorage,
+        ctx:          &TxContext,
+    ) {
+        dubhe::dapp_system::leave_scene_permit<DappKey, World>(dapp_key::new(), permit, user_storage, ctx);
+    }
+
+    public(package) fun expire_world(
+        permit: dubhe::dapp_service::ScenePermit<World>,
+        ctx:    &TxContext,
+    ) {
+        assert!(
+            !dapp_service::is_scene_active(dapp_service::scene_permit_meta(&permit), ctx.epoch_timestamp_ms()),
+            EPermitNotExpiredYet
+        );
+        dubhe::dapp_system::destroy_scene_permit<DappKey, World>(
+            dapp_key::new(), permit
+        );
+    }
+}

package/templates/nextjs/sui-farm/packages/contracts/src/harvest/sources/codegen/resources/carrot.move

@@ -0,0 +1,136 @@
+// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Autogenerated file. Do not edit manually. */
+
+module harvest::carrot {
+    use sui::bcs::{to_bytes};
+    use dubhe::dapp_service::{UserStorage, DappStorage};
+    use dubhe::dapp_system;
+    use harvest::dapp_key;
+    use harvest::dapp_key::DappKey;
+
+
+    const TABLE_NAME: vector<u8> = b"carrot";
+    const OFFCHAIN: bool = false;
+
+    public fun has(user_storage: &UserStorage): bool {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        dapp_system::has_record<DappKey>(user_storage, key_tuple)
+    }
+
+    public fun ensure_has(user_storage: &UserStorage) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        dapp_system::ensure_has_record<DappKey>(user_storage, key_tuple)
+    }
+
+    public fun ensure_has_not(user_storage: &UserStorage) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        dapp_system::ensure_has_not_record<DappKey>(user_storage, key_tuple)
+    }
+  
+
+    public(package) fun delete(user_storage: &mut UserStorage, ctx: &TxContext) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        dapp_system::delete_record<DappKey>(dapp_key::new(), user_storage, key_tuple, vector[b"amount"], ctx);
+    }
+
+    public fun get(user_storage: &UserStorage): u64 {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        let amount_raw = dapp_system::get_field<DappKey>(user_storage, key_tuple, b"amount");
+        let mut amount_bcs = sui::bcs::new(amount_raw);
+        let value = sui::bcs::peel_u64(&mut amount_bcs);
+        value
+    }
+
+    public(package) fun set(user_storage: &mut UserStorage, value: u64, ctx: &mut TxContext) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        let field_names = vector[b"amount"];
+        let value_tuple = encode(value);
+        dapp_system::set_record<DappKey>(dapp_key::new(), user_storage, key_tuple, field_names, value_tuple, OFFCHAIN, ctx);
+    }
+
+    public fun encode(value: u64): vector<vector<u8>> {
+        let mut value_tuple = vector::empty();
+        value_tuple.push_back(to_bytes(&value));
+        value_tuple
+    }
+
+
+    // ─── fungible add / sub ─────────────────────────────────────────────
+    #[error]
+    const EInsufficientAmount: vector<u8> = b"Insufficient amount";
+
+    public(package) fun add(user_storage: &mut UserStorage, amount: u64, ctx: &mut TxContext) {
+        let current = if (has(user_storage)) { get(user_storage) } else { 0 };
+        set(user_storage, current + amount, ctx);
+    }
+
+    public(package) fun sub(user_storage: &mut UserStorage, amount: u64, ctx: &mut TxContext) {
+        let current = get(user_storage);
+        assert!(current >= amount, EInsufficientAmount);
+        set(user_storage, current - amount, ctx);
+    }
+
+    // ─── listable: market protocol (fungible) ──────────────────────────
+    // Package-level helpers: call these from your system functions.
+    // Add pause checks, access control, and custom logic there.
+    public(package) fun list<CoinType>(
+        user_storage: &mut UserStorage,
+        amount:       u64,
+        price:        u64,
+        listed_until: std::option::Option<u64>,
+        ctx:          &mut TxContext,
+    ) {
+        dubhe::dapp_system::take_fungible_record<DappKey, CoinType>(
+            dapp_key::new(),
+            user_storage,
+            b"carrot",
+            { let mut k = vector::empty(); k.push_back(TABLE_NAME); k },
+            b"amount",
+            amount,
+            price,
+            listed_until,
+            ctx,
+        );
+    }
+
+    public(package) fun buy<CoinType>(
+        dh:            &dubhe::dapp_service::DappHub,
+        dapp_storage:  &mut DappStorage,
+        listing:       dubhe::dapp_service::Listing<CoinType>,
+        user_storage:  &mut UserStorage,
+        payment:       sui::coin::Coin<CoinType>,
+        ctx:           &mut TxContext,
+    ): sui::coin::Coin<CoinType> {
+        dubhe::dapp_system::buy_fungible_record<DappKey, CoinType>(
+            dapp_key::new(), dh, dapp_storage, listing, user_storage, payment, ctx
+        )
+    }
+
+    public(package) fun cancel_listing<CoinType>(
+        listing:      dubhe::dapp_service::Listing<CoinType>,
+        user_storage: &mut UserStorage,
+        ctx:          &TxContext,
+    ) {
+        dubhe::dapp_system::cancel_fungible_listing<DappKey, CoinType>(
+            dapp_key::new(), listing, user_storage, ctx
+        );
+    }
+
+    public(package) fun expire_listing<CoinType>(
+        listing:      dubhe::dapp_service::Listing<CoinType>,
+        user_storage: &mut UserStorage,
+        ctx:          &TxContext,
+    ) {
+        dubhe::dapp_system::expire_fungible_listing<DappKey, CoinType>(
+            dapp_key::new(), listing, user_storage, ctx
+        );
+    }
+}