create-dubhe 1.2.0-pre.98 → 2.0.0

package/templates/nextjs/sui-template/packages/contracts/src/dubhe/sources/core/dapp_service.move

@@ -1,203 +1,1842 @@
 module dubhe::dapp_service {
-    use std::ascii::String;
-    use sui::object_table;
-    use sui::object_table::ObjectTable;
+    use std::ascii::{String, string};
+    use std::type_name::{Self, TypeName};
+    use sui::bcs;
+    use sui::bag::{Self, Bag};
+    use sui::balance::{Self, Balance};
     use sui::dynamic_field;
-    use dubhe::data_key::DataKey;
-    use std::type_name;
-    use dubhe::dubhe_events::{emit_store_set_record, emit_store_delete_record};
+    use dubhe::error;
+    use dubhe::dubhe_events::{
+        emit_store_set_record,
+        emit_store_set_field,
+        emit_store_delete_record,
+        emit_store_delete_field,
+        emit_object_created,
+        emit_scene_created,
+        emit_scene_permit_created,
+        emit_scene_permit_join,
+        emit_dapp_fee_state_updated,
+        emit_dapp_revenue_state_updated,
+    };
 
-        /// Error codes
-    const EInvalidKey: u64 = 2;
-    const ENoPermissionPackageId: u64 = 6;
+    // ─── Error codes — all delegated to dubhe::error ──────────────────────────
 
+    // ─── UserStorage registry key ─────────────────────────────────────────────
+    //
+    // Stored as a dynamic field on DappStorage to track which addresses already
+    // have a UserStorage for a given DApp.  Using a dedicated struct as the key
+    // prevents any collision with DApp game-data dynamic fields (which use
+    // vector<vector<u8>> keys).
 
-    public struct AccountData has key, store { id: UID }
+    public struct UserStorageRegistryKey has copy, drop, store { owner: address }
 
-    public struct AccountKey has copy, drop, store {
-        account: String,
-        dapp_key: String,
+    // ─── PermitMetadata — authorization token for reactive writes ─────────────
+    //
+    // Embedded in every codegen-generated typed SceneStorage struct.
+    // Reactive write functions require a &ScenePermit<T> to verify that both
+    // the initiator and the target are registered participants and that the
+    // scene is still active.
+    //
+    // Participants are stored as dynamic fields on the scene object's UID
+    // (key = ParticipantKey { addr }, value = bool true).  This gives O(1)
+    // join / leave / check instead of the old O(n) vector scan, and prevents
+    // unbounded vector growth regardless of participant count.
+    // PermitMetadata retains participant_count for max_participants enforcement.
+
+    /// Dynamic-field key marking a confirmed participant in a scene.
+    public struct ParticipantKey has copy, drop, store { addr: address }
+
+    public struct PermitMetadata has store, copy, drop {
+        expires_at:        Option<u64>,
+        /// Addresses that have been invited but have not yet called accept_<scene>.
+        /// Used by create_<scene>_with_invitations + accept_<scene> flow to support
+        /// all wallet types (including zkLogin) without requiring off-chain signatures.
+        invitees:          vector<address>,
+        /// Optional deadline for accepting invitations (epoch ms).
+        /// None = invitations never expire. Once passed, accept_<scene> aborts.
+        invites_expire_at: Option<u64>,
+        /// Maximum number of confirmed participants allowed in this scene.
+        /// None = unlimited. Enforced on participant add.
+        max_participants:  Option<u64>,
+        /// Current confirmed participant count — updated by add/remove.
+        participant_count: u64,
     }
 
-    public(package) fun new_account_key<DappKey: copy + drop>(account: String): AccountKey {
-        AccountKey {
-            account,
-            dapp_key: type_name::get<DappKey>().into_string(),
+    public(package) fun new_scene_meta(
+        expires_at:       Option<u64>,
+        max_participants: Option<u64>,
+    ): PermitMetadata {
+        PermitMetadata {
+            expires_at,
+            invitees:          vector::empty(),
+            invites_expire_at: option::none(),
+            max_participants,
+            participant_count: 0,
         }
     }
 
-    public(package) fun new_account_data(ctx: &mut TxContext): AccountData {
-        AccountData { id: object::new(ctx) }
+    public(package) fun new_scene_meta_with_invitations(
+        invitees:          vector<address>,
+        invites_expire_at: Option<u64>,
+        scene_expires_at:  Option<u64>,
+        max_participants:  Option<u64>,
+    ): PermitMetadata {
+        PermitMetadata {
+            expires_at:        scene_expires_at,
+            invitees,
+            invites_expire_at,
+            max_participants,
+            participant_count: 0,
+        }
+    }
+
+    public fun scene_expires_at(meta: &PermitMetadata): Option<u64> {
+        meta.expires_at
+    }
+
+    public fun scene_invitees(meta: &PermitMetadata): &vector<address> {
+        &meta.invitees
     }
 
-    /// Storage structure
+    public fun scene_invites_expire_at(meta: &PermitMetadata): Option<u64> {
+        meta.invites_expire_at
+    }
+
+    public fun scene_max_participants(meta: &PermitMetadata): Option<u64> {
+        meta.max_participants
+    }
+
+    public fun scene_participant_count(meta: &PermitMetadata): u64 {
+        meta.participant_count
+    }
+
+    public fun is_scene_invitee(meta: &PermitMetadata, addr: address): bool {
+        meta.invitees.contains(&addr)
+    }
+
+    /// O(1) participant check via dynamic field existence.
+    public fun is_scene_participant(id: &UID, addr: address): bool {
+        dynamic_field::exists_(id, ParticipantKey { addr })
+    }
+
+    /// Returns true if the scene is still active (not expired).
+    /// A scene with expires_at = None is considered permanently active.
+    public fun is_scene_active(meta: &PermitMetadata, now_ms: u64): bool {
+        if (option::is_none(&meta.expires_at)) { return true };
+        now_ms < *option::borrow(&meta.expires_at)
+    }
+
+    // ─── ObjectEntityId registry key ─────────────────────────────────────────
+    //
+    // Stored as a dynamic field on DappStorage to enforce entity_id uniqueness
+    // within a specific type_tag (e.g., b"guild", b"boss").
+    // Different type_tags can share the same entity_id value without conflict.
+
+    public struct ObjectEntityIdKey has copy, drop, store {
+        type_tag:  vector<u8>,
+        entity_id: vector<u8>,
+    }
+
+    public(package) fun register_object_entity_id(
+        ds:        &mut DappStorage,
+        type_tag:  vector<u8>,
+        entity_id: vector<u8>,
+        object_id: address,
+    ) {
+        let key = ObjectEntityIdKey { type_tag, entity_id };
+        error::entity_id_already_exists(!dynamic_field::exists_(&ds.id, key));
+        dynamic_field::add(&mut ds.id, key, object_id);
+    }
+
+    public(package) fun unregister_object_entity_id(
+        ds:        &mut DappStorage,
+        type_tag:  vector<u8>,
+        entity_id: vector<u8>,
+    ) {
+        let key = ObjectEntityIdKey { type_tag, entity_id };
+        if (dynamic_field::exists_(&ds.id, key)) {
+            let _: address = dynamic_field::remove(&mut ds.id, key);
+        };
+    }
+
+    #[test_only]
+    public fun has_object_entity_id(
+        ds:        &DappStorage,
+        type_tag:  vector<u8>,
+        entity_id: vector<u8>,
+    ): bool {
+        dynamic_field::exists_(&ds.id, ObjectEntityIdKey { type_tag, entity_id })
+    }
+
+    #[test_only]
+    public fun get_object_entity_id(
+        ds:        &DappStorage,
+        type_tag:  vector<u8>,
+        entity_id: vector<u8>,
+    ): address {
+        let key = ObjectEntityIdKey { type_tag, entity_id };
+        error::entity_not_found(dynamic_field::exists_(&ds.id, key));
+        *dynamic_field::borrow<ObjectEntityIdKey, address>(&ds.id, key)
+    }
+
+    // ─── FrameworkFeeConfig ───────────────────────────────────────────────────
+
+    const MAX_FEE_HISTORY: u64 = 20;
+
+    /// Snapshot of a fee update stored in the rolling fee history.
+    /// Both fee components are recorded together so the history is self-contained.
+    public struct FeeHistoryEntry has store, copy, drop {
+        base_fee:          u256,
+        bytes_fee:         u256,
+        effective_from_ms: u64,
+    }
+
+    public struct FrameworkFeeConfig has store, drop {
+        /// Flat charge per write operation (applied to every write regardless of size).
+        base_fee_per_write:     u256,
+        /// Per-byte charge applied to on-chain writes (offchain writes pay base_fee only).
+        bytes_fee_per_byte:     u256,
+        /// Pending base_fee change (0 when no change is scheduled).
+        pending_base_fee:       u256,
+        /// Pending bytes_fee change (0 when no change is scheduled).
+        pending_bytes_fee:      u256,
+        /// When both pending fees become effective (ms). Shared across both components.
+        fee_effective_at_ms:    u64,
+        treasury:               address,
+        /// Pending treasury address for two-step rotation. @0x0 means no pending transfer.
+        pending_treasury:       address,
+        fee_history:            vector<FeeHistoryEntry>,
+        /// The coin type currently accepted for credit recharges.
+        /// None signals "not yet initialised" (deploy_hook hasn't run).
+        accepted_coin_type:          Option<TypeName>,
+        /// Pending coin type after a propose_coin_type call. None = no change in flight.
+        pending_coin_type:           Option<TypeName>,
+        /// Epoch-ms timestamp when pending_coin_type becomes committable (0 = no pending).
+        coin_type_effective_at_ms:   u64,
+    }
+
+    // ─── FrameworkConfig — operational params managed by framework admin ──────
+    //
+    // Kept separate from FrameworkFeeConfig so that financial controls (treasury)
+    // and operational controls (admin) can be managed independently and rotated
+    // separately.
+
+    public struct FrameworkConfig has store, drop {
+        /// Default virtual free credit (MIST) automatically granted to every new DApp
+        /// at creation time. 25 SUI = 25_000_000_000 MIST. 0 disables auto-grant.
+        default_free_credit:             u256,
+        /// Duration (ms) for which the default free credit is valid.
+        /// 0 = never expires. 6 months ≈ 15_778_800_000 ms.
+        default_free_credit_duration_ms: u64,
+        /// Framework admin address (manages operational params).
+        /// Distinct from treasury which manages financial operations.
+        admin:                           address,
+        /// Pending admin for two-step rotation. @0x0 means no pending transfer.
+        pending_admin:                   address,
+        /// Default write-fee DApp share (bps) assigned to newly created DApps.
+        /// Controls how write-operation fees are split between the DApp and the framework treasury.
+        /// Framework admin can override per-DApp with set_dapp_write_fee_share.
+        /// e.g. 3000 = 30% to DApp developer; remaining 70% to framework treasury.
+        default_write_fee_dapp_share_bps:  u64,
+        /// Absolute ceiling on the per-DApp unsettled write limit.
+        /// DApp admins cannot set write_limit above this value.
+        /// Default 2_000; updatable by framework admin via set_framework_max_write_limit.
+        framework_max_write_limit:       u64,
+        /// Global marketplace transaction fee in basis points (e.g. 300 = 3%).
+        /// Applied to every listing purchase across all DApps.
+        /// Framework admin can change via update_marketplace_fee.
+        marketplace_fee_bps:             u64,
+        /// Of the marketplace fee, how many bps go to the DApp (remainder to framework).
+        /// e.g. 5000 = 50% of fee to DApp, 50% to framework treasury.
+        /// Framework admin can change via update_marketplace_dapp_share.
+        marketplace_dapp_share_bps:      u64,
+    }
+
+    // ─── DappHub — global registry ────────────────────────────────────────────
+
     public struct DappHub has key, store {
-        /// The unique identifier of the DappStore instance
-        id: UID,
-        /// Accounts 
-        accounts: ObjectTable<AccountKey, AccountData>,
+        id:         UID,
+        fee_config: FrameworkFeeConfig,
+        config:     FrameworkConfig,
+        /// Framework version used for upgrade version gating.
+        /// After a framework upgrade, call bump_framework_version to
+        /// increment this value; all version-gated functions using the
+        /// old FRAMEWORK_VERSION constant will then abort.
+        version:    u64,
+    }
+
+    // ─── DappStorage — per-DApp shared object ─────────────────────────────────
+
+    public struct DappStorage has key, store {
+        id:                      UID,
+        dapp_key:                String,
+        // ─── Metadata (stored directly, no dynamic field overhead) ──────────
+        name:                    String,
+        description:             String,
+        website_url:             String,
+        cover_url:               vector<String>,
+        partners:                vector<String>,
+        package_ids:             vector<address>,
+        created_at:              u64,
+        admin:                   address,
+        pending_admin:           address,
+        version:                 u32,
+        paused:                  bool,
+        // ─── Fee / credit ────────────────────────────────────────────────────
+        /// Virtual free credit granted by framework admin (MIST, no SUI backing).
+        /// Consumed before credit_pool during settlement (free-first priority).
+        /// Set to 0 when exhausted or revoked.
+        free_credit:             u256,
+        /// Expiry timestamp (epoch ms) for free_credit. 0 = never expires.
+        /// Expired free credit is treated as 0 in settlement and unsuspend checks.
+        free_credit_expires_at:  u64,
+        credit_pool:             u256,
+        /// Cumulative amount settled, used for off-chain analytics.
+        /// NOTE: the metric differs by settlement mode:
+        ///   DAPP_SUBSIDIZES — sum of paid_used (credit_pool deductions, excludes free_credit).
+        ///   USER_PAYS       — sum of total user payment (fw + dapp portions combined).
+        total_settled:           u256,
+        // ─── Per-DApp fee rates ───────────────────────────────────────────────
+        /// Flat charge per write operation (MIST). Copied from DappHub defaults
+        /// at creation time; updated via sync_dapp_fee.
+        base_fee_per_write:      u256,
+        /// Per-byte charge for on-chain writes (MIST). Same lifecycle as above.
+        bytes_fee_per_byte:      u256,
+        // ─── Settlement mode ─────────────────────────────────────────────────
+        /// 0 = DAPP_SUBSIDIZES (default), 1 = USER_PAYS.
+        /// Bidirectional switch: can be changed freely by the DApp admin.
+        settlement_mode:         u8,
+        /// Write-fee DApp share (basis points).
+        /// Controls how write-operation fees are split between DApp and framework treasury.
+        /// In USER_PAYS mode: share_bps of total_cost goes to DApp revenue; remainder to treasury.
+        /// In DAPP_SUBSIDIZES mode: framework collects (10_000 - share_bps) / 10_000 of total_cost
+        /// from the DApp's credit pool; the DApp effectively retains its share.
+        /// Set exclusively by the framework admin via set_dapp_write_fee_share.
+        write_fee_dapp_share_bps:  u64,
+    }
+
+    // ─── UserStorage — per-user shared key object ─────────────────────────────
+    //
+    // UserStorage is a shared object so that:
+    //   1. Canonical owner can write to it directly from their wallet.
+    //   2. An authorized session key (ephemeral frontend wallet) can write on
+    //      their behalf without any object transfer.
+    //   3. Canonical owner can revoke or update the session key at any time
+    //      because the shared object is always reachable by both parties.
+    //
+    // session_key == @0x0  → no active session (canonical owner only).
+    // session_expires_at   → expiry deadline in epoch-clock ms (≈24h granularity
+    //                        on mainnet/testnet, ≈1h on devnet). In production,
+    //                        this is always >0 because activate_session enforces
+    //                        a minimum duration. The value 0 only appears in test
+    //                        helpers and means "no active session" when combined
+    //                        with session_key == @0x0.
+
+    public struct UserStorage has key {
+        id:                 UID,
+        dapp_key:           String,
+        canonical_owner:    address,
+        session_key:        address,
+        session_expires_at: u64,
+        /// Total number of write operations (offchain + onchain). Incremented on
+        /// every set_record / set_field call regardless of offchain flag.
+        write_count:        u64,
+        settled_count:      u64,
+        /// Cumulative bytes of on-chain data written (offchain writes contribute 0).
+        /// Used together with write_count to compute the total settlement charge:
+        ///   cost = base_fee × unsettled_writes + bytes_fee × unsettled_bytes
+        write_bytes:        u256,
+        settled_bytes:      u256,
+        /// Snapshot of the framework's effective write_limit at creation or last explicit sync.
+        /// set_record / set_field enforce unsettled_count < write_limit.
+        /// Call sync_user_write_limit to pick up changes made to DappHub.
+        write_limit:        u64,
+    }
+
+    // ─── ObjectStorage — DApp-managed typed shared entity ─────────────────────
+    //
+    // A Framework-owned shared object that holds arbitrary key-value data for a
+    // single DApp entity (e.g. a guild, a boss, an item).  The phantom type
+    // parameter ObjType (a DApp-package-local struct) distinguishes GuildStorage
+    // from BossStorage at the Move compiler level, preserving compile-time type
+    // safety while keeping the underlying struct in the framework package.
+    //
+    // Data is stored as BCS bytes (vector<u8>) in the Bag — the same model as
+    // UserStorage — enabling the framework to emit Dubhe_Object_SetField events
+    // for off-chain indexing.
+
+    public struct ObjectStorage<phantom ObjType> has key {
+        id:          UID,
+        dapp_key:    String,      // used for dapp-key mismatch checks and event emission
+        object_type: vector<u8>, // human-readable type tag, e.g. b"guild"
+        entity_id:   vector<u8>,
+        data:        Bag,         // key: vector<u8> field name → value: vector<u8> BCS bytes
+    }
+
+    // ─── ScenePermit / SceneStorage ───────────────────────────────────────────
+    //
+    // ScenePermit owns participant membership and lifecycle metadata for a
+    // session. SceneStorage is pure data storage, symmetric to ObjectStorage.
+    // A permit-bound SceneStorage records both the permit type tag and the
+    // concrete permit object id to prevent same-type session instances from
+    // authorizing each other.
+
+    public struct ScenePermit<phantom PermType> has key {
+        id:          UID,
+        dapp_key:    String,
+        permit_type: vector<u8>,
+        meta:        PermitMetadata,
+    }
+
+    public struct SceneStorage<phantom SceneType> has key {
+        id:                     UID,
+        dapp_key:               String,
+        scene_type:             vector<u8>,
+        authorized_permit_id:   Option<address>,
+        data:                   Bag,
+    }
+
+    // ─── ObjectStorage / SceneStorage accessors ───────────────────────────────
+
+    public fun object_storage_dapp_key<T>(s: &ObjectStorage<T>): String { s.dapp_key }
+    public fun object_storage_type<T>(s: &ObjectStorage<T>): &vector<u8> { &s.object_type }
+    public fun object_storage_entity_id<T>(s: &ObjectStorage<T>): &vector<u8> { &s.entity_id }
+    public fun object_storage_id<T>(s: &ObjectStorage<T>): &UID { &s.id }
+    public(package) fun object_storage_id_mut<T>(s: &mut ObjectStorage<T>): &mut UID { &mut s.id }
+
+    public fun scene_permit_dapp_key<T>(p: &ScenePermit<T>): String { p.dapp_key }
+    public fun scene_permit_type<T>(p: &ScenePermit<T>): &vector<u8> { &p.permit_type }
+    public fun scene_permit_meta<T>(p: &ScenePermit<T>): &PermitMetadata { &p.meta }
+    public(package) fun scene_permit_meta_mut<T>(p: &mut ScenePermit<T>): &mut PermitMetadata { &mut p.meta }
+    public fun scene_permit_id<T>(p: &ScenePermit<T>): &UID { &p.id }
+    public(package) fun scene_permit_id_mut<T>(p: &mut ScenePermit<T>): &mut UID { &mut p.id }
+
+    public fun scene_storage_dapp_key<T>(s: &SceneStorage<T>): String { s.dapp_key }
+    public fun scene_storage_type<T>(s: &SceneStorage<T>): &vector<u8> { &s.scene_type }
+    public fun scene_storage_authorized_permit_id<T>(s: &SceneStorage<T>): &Option<address> {
+        &s.authorized_permit_id
+    }
+    public fun scene_storage_id<T>(s: &SceneStorage<T>): &UID { &s.id }
+    public(package) fun scene_storage_id_mut<T>(s: &mut SceneStorage<T>): &mut UID { &mut s.id }
+
+    public fun dapp_storage_id(ds: &DappStorage): &UID { &ds.id }
+    public fun user_storage_id(us: &UserStorage): &UID { &us.id }
+
+    // ─── ScenePermit participant helpers ─────────────────────────────────────
+
+    public(package) fun accept_invitation_in_scene_permit<T>(
+        permit: &mut ScenePermit<T>,
+        addr:   address,
+    ) {
+        let (found, idx) = permit.meta.invitees.index_of(&addr);
+        error::not_participant(found);
+        permit.meta.invitees.remove(idx);
+        add_participant_in_scene_permit(permit, addr);
+    }
+
+    public(package) fun add_participant_in_scene_permit<T>(
+        permit: &mut ScenePermit<T>,
+        addr:   address,
+    ) {
+        if (dynamic_field::exists_(&permit.id, ParticipantKey { addr })) { return };
+        if (permit.meta.max_participants.is_some()) {
+            error::scene_full(
+                permit.meta.participant_count < *option::borrow(&permit.meta.max_participants)
+            );
+        };
+        dynamic_field::add(&mut permit.id, ParticipantKey { addr }, true);
+        permit.meta.participant_count = permit.meta.participant_count + 1;
+    }
+
+    public(package) fun remove_participant_in_scene_permit<T>(
+        permit: &mut ScenePermit<T>,
+        addr:   address,
+    ) {
+        if (!dynamic_field::exists_(&permit.id, ParticipantKey { addr })) { return };
+        let _: bool = dynamic_field::remove(&mut permit.id, ParticipantKey { addr });
+        permit.meta.participant_count = permit.meta.participant_count - 1;
+    }
+
+    public fun is_participant_in_scene_permit<T>(
+        permit: &ScenePermit<T>,
+        addr:   address,
+    ): bool {
+        dynamic_field::exists_(&permit.id, ParticipantKey { addr })
+    }
+
+    // ─── ObjectStorage CRUD (package-internal, called by dapp_system) ─────────
+
+    public(package) fun new_object_storage<ObjType>(
+        dapp_key:    String,
+        object_type: vector<u8>,
+        entity_id:   vector<u8>,
+        ctx:         &mut TxContext,
+    ): ObjectStorage<ObjType> {
+        let storage = ObjectStorage<ObjType> {
+            id: object::new(ctx),
+            dapp_key,
+            object_type,
+            entity_id,
+            data: bag::new(ctx),
+        };
+        emit_object_created(
+            storage.dapp_key,
+            storage.object_type,
+            object::uid_to_address(&storage.id),
+            storage.entity_id,
+        );
+        storage
+    }
+
+    /// Create a ScenePermit with an initial participant list.
+    /// Participants are stored as Dynamic Fields on the permit's UID.
+    public(package) fun new_scene_permit_with_participants<PermType>(
+        dapp_key_str:     String,
+        permit_type:      vector<u8>,
+        participants:     vector<address>,
+        expires_at:       Option<u64>,
+        max_participants: Option<u64>,
+        ctx:              &mut TxContext,
+    ): ScenePermit<PermType> {
+        let mut permit = ScenePermit<PermType> {
+            id:          object::new(ctx),
+            dapp_key:    dapp_key_str,
+            permit_type,
+            meta:        new_scene_meta(expires_at, max_participants),
+        };
+        let mut i = 0;
+        let len = participants.length();
+        while (i < len) {
+            add_participant_in_scene_permit(&mut permit, *participants.borrow(i));
+            i = i + 1;
+        };
+        let permit_id = object::uid_to_address(&permit.id);
+        emit_scene_permit_created(
+            permit.dapp_key,
+            permit.permit_type,
+            permit_id,
+            permit.meta.expires_at,
+            permit.meta.invites_expire_at,
+            permit.meta.max_participants,
+            permit.meta.participant_count,
+        );
+        let mut j = 0;
+        while (j < len) {
+            emit_scene_permit_join(
+                permit.dapp_key,
+                permit.permit_type,
+                permit_id,
+                *participants.borrow(j),
+            );
+            j = j + 1;
+        };
+        permit
+    }
+
+    /// Create a ScenePermit with an invitation list (no confirmed participants yet).
+    public(package) fun new_scene_permit_with_invitations<PermType>(
+        dapp_key_str:      String,
+        permit_type:       vector<u8>,
+        invitees:          vector<address>,
+        invites_expire_at: Option<u64>,
+        scene_expires_at:  Option<u64>,
+        max_participants:  Option<u64>,
+        ctx:               &mut TxContext,
+    ): ScenePermit<PermType> {
+        let permit = ScenePermit<PermType> {
+            id:          object::new(ctx),
+            dapp_key:    dapp_key_str,
+            permit_type,
+            meta:        new_scene_meta_with_invitations(
+                             invitees, invites_expire_at, scene_expires_at, max_participants
+                         ),
+        };
+        emit_scene_permit_created(
+            permit.dapp_key,
+            permit.permit_type,
+            object::uid_to_address(&permit.id),
+            permit.meta.expires_at,
+            permit.meta.invites_expire_at,
+            permit.meta.max_participants,
+            permit.meta.participant_count,
+        );
+        permit
+    }
+
+    /// Create a system-controlled SceneStorage with no permit authorization.
+    public(package) fun new_scene_storage_system<SceneType>(
+        dapp_key_str: String,
+        scene_type:   vector<u8>,
+        ctx:          &mut TxContext,
+    ): SceneStorage<SceneType> {
+        let storage = SceneStorage<SceneType> {
+            id:                     object::new(ctx),
+            dapp_key:               dapp_key_str,
+            scene_type,
+            authorized_permit_id:   option::none(),
+            data:                   bag::new(ctx),
+        };
+        emit_scene_created(
+            storage.dapp_key,
+            storage.scene_type,
+            object::uid_to_address(&storage.id),
+            b"system",
+            storage.authorized_permit_id,
+        );
+        storage
+    }
+
+    /// Create a SceneStorage bound to a concrete ScenePermit object.
+    public(package) fun new_scene_storage_with_permit<PermType, SceneType>(
+        dapp_key_str: String,
+        scene_type:   vector<u8>,
+        permit:       &ScenePermit<PermType>,
+        ctx:          &mut TxContext,
+    ): SceneStorage<SceneType> {
+        let storage = SceneStorage<SceneType> {
+            id:                     object::new(ctx),
+            dapp_key:               dapp_key_str,
+            scene_type,
+            authorized_permit_id:   option::some(object::uid_to_address(scene_permit_id(permit))),
+            data:                   bag::new(ctx),
+        };
+        emit_scene_created(
+            storage.dapp_key,
+            storage.scene_type,
+            object::uid_to_address(&storage.id),
+            b"permit",
+            storage.authorized_permit_id,
+        );
+        storage
     }
 
-    /// Create a new storage instance
+    /// Set (insert or overwrite) a native-typed field in an ObjectStorage Bag.
+    /// `T` must be `store + copy + drop` so Bag can hold it and bcs::to_bytes can encode it.
+    public(package) fun set_object_field<ObjType, T: store + copy + drop>(
+        storage:    &mut ObjectStorage<ObjType>,
+        field_name: vector<u8>,
+        value:      T,
+    ) {
+        if (bag::contains_with_type<vector<u8>, T>(&storage.data, field_name)) {
+            *bag::borrow_mut<vector<u8>, T>(&mut storage.data, field_name) = value;
+        } else {
+            bag::add(&mut storage.data, field_name, value);
+        }
+    }
+
+    /// Get a native-typed field from an ObjectStorage Bag. Aborts if not present.
+    public(package) fun get_object_field<ObjType, T: store + copy + drop>(
+        storage:    &ObjectStorage<ObjType>,
+        field_name: vector<u8>,
+    ): T {
+        *bag::borrow<vector<u8>, T>(&storage.data, field_name)
+    }
+
+    /// Check if a native-typed field exists in an ObjectStorage Bag.
+    public(package) fun has_object_field<ObjType, T: store + copy + drop>(
+        storage:    &ObjectStorage<ObjType>,
+        field_name: vector<u8>,
+    ): bool {
+        bag::contains_with_type<vector<u8>, T>(&storage.data, field_name)
+    }
+
+    /// Remove and return a native-typed field from an ObjectStorage Bag.
+    public(package) fun remove_object_field<ObjType, T: store + copy + drop>(
+        storage:    &mut ObjectStorage<ObjType>,
+        field_name: vector<u8>,
+    ): T {
+        bag::remove<vector<u8>, T>(&mut storage.data, field_name)
+    }
+
+    /// Consume and destroy an ObjectStorage whose Bag is empty.
+    public(package) fun destroy_object_storage<ObjType>(storage: ObjectStorage<ObjType>) {
+        let ObjectStorage { id, dapp_key: _, object_type: _, entity_id: _, data } = storage;
+        bag::destroy_empty(data);
+        object::delete(id);
+    }
+
+    /// Set (insert or overwrite) a native-typed field in a SceneStorage Bag.
+    public(package) fun set_scene_field<SceneType, T: store + copy + drop>(
+        storage:    &mut SceneStorage<SceneType>,
+        field_name: vector<u8>,
+        value:      T,
+    ) {
+        if (bag::contains_with_type<vector<u8>, T>(&storage.data, field_name)) {
+            *bag::borrow_mut<vector<u8>, T>(&mut storage.data, field_name) = value;
+        } else {
+            bag::add(&mut storage.data, field_name, value);
+        }
+    }
+
+    /// Get a native-typed field from a SceneStorage Bag. Aborts if not present.
+    public(package) fun get_scene_field<SceneType, T: store + copy + drop>(
+        storage:    &SceneStorage<SceneType>,
+        field_name: vector<u8>,
+    ): T {
+        *bag::borrow<vector<u8>, T>(&storage.data, field_name)
+    }
+
+    /// Check if a native-typed field exists in a SceneStorage Bag.
+    public(package) fun has_scene_field<SceneType, T: store + copy + drop>(
+        storage:    &SceneStorage<SceneType>,
+        field_name: vector<u8>,
+    ): bool {
+        bag::contains_with_type<vector<u8>, T>(&storage.data, field_name)
+    }
+
+    /// Remove and return a native-typed field from a SceneStorage Bag.
+    public(package) fun remove_scene_field<SceneType, T: store + copy + drop>(
+        storage:    &mut SceneStorage<SceneType>,
+        field_name: vector<u8>,
+    ): T {
+        bag::remove<vector<u8>, T>(&mut storage.data, field_name)
+    }
+
+    /// Consume and destroy a SceneStorage whose Bag is empty.
+    public(package) fun destroy_scene_storage<SceneType>(storage: SceneStorage<SceneType>) {
+        let SceneStorage {
+            id,
+            dapp_key: _,
+            scene_type: _,
+            authorized_permit_id: _,
+            data,
+        } = storage;
+        bag::destroy_empty(data);
+        object::delete(id);
+    }
+
+    /// Consume and destroy a ScenePermit whose participant DFs are empty.
+    public(package) fun destroy_scene_permit<PermType>(permit: ScenePermit<PermType>) {
+        let ScenePermit { id, dapp_key: _, permit_type: _, meta: _ } = permit;
+        object::delete(id);
+    }
+
+    // ─── Share wrappers ────────────────────────────────────────────────────────
+    //
+    // transfer::share_object is restricted to the module that defines the type.
+    // ObjectStorage, ScenePermit and SceneStorage are defined here, so these package-internal
+    // wrappers let dapp_system (same package, different module) share them.
+
+    /// Share a newly-created ObjectStorage shared object.
+    public(package) fun share_object_storage<ObjType>(storage: ObjectStorage<ObjType>) {
+        sui::transfer::share_object(storage);
+    }
+
+    /// Share a newly-created ScenePermit shared object.
+    public(package) fun share_scene_permit<PermType>(permit: ScenePermit<PermType>) {
+        sui::transfer::share_object(permit);
+    }
+
+    /// Share a newly-created SceneStorage shared object.
+    public(package) fun share_scene_storage<SceneType>(storage: SceneStorage<SceneType>) {
+        sui::transfer::share_object(storage);
+    }
+
+    // ─── Constructors ─────────────────────────────────────────────────────────
+
     public(package) fun new(ctx: &mut TxContext): DappHub {
         DappHub {
             id: object::new(ctx),
-            accounts: object_table::new(ctx),
+            fee_config: FrameworkFeeConfig {
+                base_fee_per_write:  0,
+                bytes_fee_per_byte:  0,
+                pending_base_fee:    0,
+                pending_bytes_fee:   0,
+                fee_effective_at_ms: 0,
+                // @0x0 signals "not yet initialised"; deploy_hook::run sets the real
+                // treasury address via initialize_framework_fee on first genesis::run.
+                treasury:            @0x0,
+                pending_treasury:    @0x0,
+                fee_history:         vector::empty(),
+                accepted_coin_type:          option::none(),
+                pending_coin_type:           option::none(),
+                coin_type_effective_at_ms:   0,
+            },
+            config: FrameworkConfig {
+                // New DApps automatically receive 25 SUI of free credit that never expires.
+                // 25 SUI = 25_000_000_000 MIST; duration_ms = 0 means no expiry.
+                default_free_credit:             25_000_000_000,
+                default_free_credit_duration_ms: 0,
+                admin:                           ctx.sender(),
+                pending_admin:                   @0x0,
+                // @0 signals "not yet initialised"; deploy_hook::run sets the real
+                // values via initialize_framework_fee on first genesis::run.
+                default_write_fee_dapp_share_bps:     0,
+                framework_max_write_limit:           2_000,
+                // Marketplace fee: 3% total, 50/50 split (1.5% framework, 1.5% DApp).
+                marketplace_fee_bps:                 300,
+                marketplace_dapp_share_bps:          5_000,
+            },
+            version: 1,
         }
     }
 
-    public(package) fun set_record<DappKey: copy + drop>(
-        self: &mut DappHub,
-        _: DappKey,
-        key: vector<vector<u8>>,
-        value: vector<vector<u8>>,
-        account: String,
-        offchain: bool,
-        ctx: &mut TxContext,
+    public(package) fun new_dapp_storage<DappKey: copy + drop>(
+        name:                   String,
+        description:            String,
+        package_ids:            vector<address>,
+        created_at:             u64,
+        admin:                  address,
+        free_credit:            u256,
+        free_credit_expires_at: u64,
+        base_fee_per_write:     u256,
+        bytes_fee_per_byte:     u256,
+        settlement_mode:            u8,
+        write_fee_dapp_share_bps:   u64,
+        ctx:                        &mut TxContext,
+    ): DappStorage {
+        DappStorage {
+            id:                      object::new(ctx),
+            dapp_key:                type_name::with_defining_ids<DappKey>().into_string(),
+            name,
+            description,
+            website_url:             string(b""),
+            cover_url:               vector::empty(),
+            partners:                vector::empty(),
+            package_ids,
+            created_at,
+            admin,
+            pending_admin:           @0x0,
+            version:                 1,
+            paused:                  false,
+            free_credit,
+            free_credit_expires_at,
+            credit_pool:             0,
+            total_settled:           0,
+            base_fee_per_write,
+            bytes_fee_per_byte,
+            settlement_mode,
+            write_fee_dapp_share_bps,
+        }
+    }
+
+    public(package) fun new_user_storage<DappKey: copy + drop>(
+        owner:       address,
+        write_limit: u64,
+        ctx:         &mut TxContext,
+    ): UserStorage {
+        UserStorage {
+            id:                 object::new(ctx),
+            dapp_key:           type_name::with_defining_ids<DappKey>().into_string(),
+            canonical_owner:    owner,
+            session_key:        @0x0,
+            session_expires_at: 0,
+            write_count:        0,
+            settled_count:      0,
+            write_bytes:        0,
+            settled_bytes:      0,
+            write_limit,
+        }
+    }
+
+    // ─── DappHub: fee config accessors ────────────────────────────────────────
+
+    public fun get_fee_config(dh: &DappHub): &FrameworkFeeConfig {
+        &dh.fee_config
+    }
+
+    public(package) fun get_fee_config_mut(dh: &mut DappHub): &mut FrameworkFeeConfig {
+        &mut dh.fee_config
+    }
+
+    public fun base_fee_per_write(cfg: &FrameworkFeeConfig): u256  { cfg.base_fee_per_write }
+    public fun bytes_fee_per_byte(cfg: &FrameworkFeeConfig): u256  { cfg.bytes_fee_per_byte }
+    public fun pending_base_fee(cfg: &FrameworkFeeConfig): u256    { cfg.pending_base_fee }
+    public fun pending_bytes_fee(cfg: &FrameworkFeeConfig): u256   { cfg.pending_bytes_fee }
+    public fun fee_effective_at_ms(cfg: &FrameworkFeeConfig): u64  { cfg.fee_effective_at_ms }
+    public fun treasury(cfg: &FrameworkFeeConfig): address         { cfg.treasury }
+    public fun pending_treasury(cfg: &FrameworkFeeConfig): address { cfg.pending_treasury }
+
+    public fun accepted_coin_type(cfg: &FrameworkFeeConfig): &Option<TypeName> {
+        &cfg.accepted_coin_type
+    }
+    public fun pending_coin_type(cfg: &FrameworkFeeConfig): &Option<TypeName> {
+        &cfg.pending_coin_type
+    }
+    public fun coin_type_effective_at_ms(cfg: &FrameworkFeeConfig): u64 {
+        cfg.coin_type_effective_at_ms
+    }
+
+    public(package) fun set_base_fee_per_write(cfg: &mut FrameworkFeeConfig, fee: u256) {
+        cfg.base_fee_per_write = fee;
+    }
+    public(package) fun set_bytes_fee_per_byte(cfg: &mut FrameworkFeeConfig, fee: u256) {
+        cfg.bytes_fee_per_byte = fee;
+    }
+    public(package) fun set_pending_base_fee(cfg: &mut FrameworkFeeConfig, fee: u256) {
+        cfg.pending_base_fee = fee;
+    }
+    public(package) fun set_pending_bytes_fee(cfg: &mut FrameworkFeeConfig, fee: u256) {
+        cfg.pending_bytes_fee = fee;
+    }
+    public(package) fun set_fee_effective_at_ms(cfg: &mut FrameworkFeeConfig, ts: u64) {
+        cfg.fee_effective_at_ms = ts;
+    }
+    public(package) fun set_treasury(cfg: &mut FrameworkFeeConfig, addr: address) {
+        cfg.treasury = addr;
+    }
+    public(package) fun set_pending_treasury(cfg: &mut FrameworkFeeConfig, addr: address) {
+        cfg.pending_treasury = addr;
+    }
+
+    public(package) fun set_accepted_coin_type(cfg: &mut FrameworkFeeConfig, t: TypeName) {
+        cfg.accepted_coin_type = option::some(t);
+    }
+    public(package) fun set_pending_coin_type(cfg: &mut FrameworkFeeConfig, t: Option<TypeName>) {
+        cfg.pending_coin_type = t;
+    }
+    public(package) fun set_coin_type_effective_at_ms(cfg: &mut FrameworkFeeConfig, ms: u64) {
+        cfg.coin_type_effective_at_ms = ms;
+    }
+
+    public(package) fun push_fee_history(
+        cfg:      &mut FrameworkFeeConfig,
+        base_fee: u256,
+        bytes_fee: u256,
+        ts:       u64,
+    ) {
+        cfg.fee_history.push_back(FeeHistoryEntry {
+            base_fee,
+            bytes_fee,
+            effective_from_ms: ts,
+        });
+        if (cfg.fee_history.length() > MAX_FEE_HISTORY) {
+            cfg.fee_history.remove(0);
+        };
+    }
+
+    /// Return the full fee-change history ring buffer (most recent at the back).
+    /// Useful for off-chain explorers and billing tools that need to determine
+    /// the applicable fee rate for a historical write operation.
+    public fun fee_history(cfg: &FrameworkFeeConfig): &vector<FeeHistoryEntry> {
+        &cfg.fee_history
+    }
+    /// Base fee that was committed in this history entry (MIST per write).
+    public fun fee_history_base_fee(e: &FeeHistoryEntry): u256  { e.base_fee }
+    /// Bytes fee that was committed in this history entry (MIST per byte).
+    public fun fee_history_bytes_fee(e: &FeeHistoryEntry): u256 { e.bytes_fee }
+    /// Epoch-ms timestamp from which this history entry's rates became effective.
+    public fun fee_history_effective_from_ms(e: &FeeHistoryEntry): u64 { e.effective_from_ms }
+
+    public fun is_fee_config_initialized(dh: &DappHub): bool {
+        dh.fee_config.treasury != @0x0
+    }
+
+    // ─── DappHub: framework config accessors ─────────────────────────────────
+
+    public fun get_config(dh: &DappHub): &FrameworkConfig {
+        &dh.config
+    }
+
+    public(package) fun get_config_mut(dh: &mut DappHub): &mut FrameworkConfig {
+        &mut dh.config
+    }
+
+    public fun default_free_credit(cfg: &FrameworkConfig): u256             { cfg.default_free_credit }
+    public fun default_free_credit_duration_ms(cfg: &FrameworkConfig): u64  { cfg.default_free_credit_duration_ms }
+    public fun framework_admin(cfg: &FrameworkConfig): address              { cfg.admin }
+    public fun pending_framework_admin(cfg: &FrameworkConfig): address      { cfg.pending_admin }
+
+    public(package) fun set_default_free_credit(cfg: &mut FrameworkConfig, amount: u256, duration_ms: u64) {
+        cfg.default_free_credit             = amount;
+        cfg.default_free_credit_duration_ms = duration_ms;
+    }
+    public(package) fun set_framework_admin(cfg: &mut FrameworkConfig, addr: address) {
+        cfg.admin = addr;
+    }
+    public(package) fun set_pending_framework_admin(cfg: &mut FrameworkConfig, addr: address) {
+        cfg.pending_admin = addr;
+    }
+
+    public fun default_write_fee_dapp_share_bps(cfg: &FrameworkConfig): u64 {
+        cfg.default_write_fee_dapp_share_bps
+    }
+
+    public(package) fun set_default_write_fee_dapp_share_bps(cfg: &mut FrameworkConfig, val: u64) {
+        cfg.default_write_fee_dapp_share_bps = val;
+    }
+
+    public fun framework_max_write_limit(cfg: &FrameworkConfig): u64 {
+        cfg.framework_max_write_limit
+    }
+
+    public(package) fun set_framework_max_write_limit_cfg(cfg: &mut FrameworkConfig, val: u64) {
+        cfg.framework_max_write_limit = val;
+    }
+
+    public fun marketplace_fee_bps(cfg: &FrameworkConfig): u64 {
+        cfg.marketplace_fee_bps
+    }
+
+    public fun marketplace_dapp_share_bps(cfg: &FrameworkConfig): u64 {
+        cfg.marketplace_dapp_share_bps
+    }
+
+    public(package) fun set_marketplace_fee_bps(cfg: &mut FrameworkConfig, val: u64) {
+        cfg.marketplace_fee_bps = val;
+    }
+
+    public(package) fun set_marketplace_dapp_share_bps(cfg: &mut FrameworkConfig, val: u64) {
+        cfg.marketplace_dapp_share_bps = val;
+    }
+
+
+    // ─── DappHub: version accessors ──────────────────────────────────────────
+
+    public fun framework_version(dh: &DappHub): u64 { dh.version }
+
+    public(package) fun set_framework_version(dh: &mut DappHub, v: u64) {
+        dh.version = v;
+    }
+
+    // ─── DappStorage: metadata accessors ─────────────────────────────────────
+
+    public fun dapp_storage_dapp_key(ds: &DappStorage): String       { ds.dapp_key }
+    public fun dapp_name(ds: &DappStorage): String                   { ds.name }
+    public fun dapp_description(ds: &DappStorage): String            { ds.description }
+    public fun dapp_website_url(ds: &DappStorage): String            { ds.website_url }
+    public fun dapp_cover_url(ds: &DappStorage): vector<String>      { ds.cover_url }
+    public fun dapp_partners(ds: &DappStorage): vector<String>       { ds.partners }
+    public fun dapp_package_ids(ds: &DappStorage): vector<address>   { ds.package_ids }
+    public fun dapp_created_at(ds: &DappStorage): u64                { ds.created_at }
+    public fun dapp_admin(ds: &DappStorage): address                 { ds.admin }
+    public fun dapp_pending_admin(ds: &DappStorage): address         { ds.pending_admin }
+    public fun dapp_version(ds: &DappStorage): u32                   { ds.version }
+    public fun dapp_paused(ds: &DappStorage): bool                   { ds.paused }
+
+    public(package) fun set_dapp_name(ds: &mut DappStorage, v: String)                { ds.name = v; }
+    public(package) fun set_dapp_description(ds: &mut DappStorage, v: String)         { ds.description = v; }
+    public(package) fun set_dapp_website_url(ds: &mut DappStorage, v: String)         { ds.website_url = v; }
+    public(package) fun set_dapp_cover_url(ds: &mut DappStorage, v: vector<String>)   { ds.cover_url = v; }
+    public(package) fun set_dapp_partners(ds: &mut DappStorage, v: vector<String>)    { ds.partners = v; }
+    public(package) fun set_dapp_package_ids(ds: &mut DappStorage, v: vector<address>) { ds.package_ids = v; }
+    public(package) fun set_dapp_admin(ds: &mut DappStorage, v: address)              { ds.admin = v; }
+    public(package) fun set_dapp_pending_admin(ds: &mut DappStorage, v: address)      { ds.pending_admin = v; }
+    public(package) fun set_dapp_version(ds: &mut DappStorage, v: u32)               { ds.version = v; }
+    public(package) fun set_dapp_paused(ds: &mut DappStorage, v: bool)               { ds.paused = v; }
+
+    // ─── DappStorage: fee/credit accessors ───────────────────────────────────
+
+    public fun free_credit(ds: &DappStorage): u256              { ds.free_credit }
+    public fun free_credit_expires_at(ds: &DappStorage): u64    { ds.free_credit_expires_at }
+    public fun credit_pool(ds: &DappStorage): u256              { ds.credit_pool }
+    public fun total_settled(ds: &DappStorage): u256            { ds.total_settled }
+
+    /// Returns the usable free credit at the given timestamp.
+    /// Returns 0 if the free credit has expired (expires_at != 0 and now >= expires_at).
+    public fun effective_free_credit(ds: &DappStorage, now_ms: u64): u256 {
+        let expires = ds.free_credit_expires_at;
+        if (expires == 0 || now_ms < expires) { ds.free_credit } else { 0 }
+    }
+
+    public(package) fun set_free_credit(ds: &mut DappStorage, amount: u256, expires_at: u64) {
+        ds.free_credit            = amount;
+        ds.free_credit_expires_at = expires_at;
+    }
+
+    public(package) fun deduct_free_credit(ds: &mut DappStorage, amount: u256) {
+        ds.free_credit = ds.free_credit - amount;
+    }
+
+    public(package) fun add_credit(ds: &mut DappStorage, amount: u256) {
+        ds.credit_pool = ds.credit_pool + amount;
+    }
+
+    public(package) fun deduct_credit(ds: &mut DappStorage, amount: u256) {
+        ds.credit_pool = ds.credit_pool - amount;
+    }
+
+    public(package) fun add_total_settled(ds: &mut DappStorage, count: u256) {
+        ds.total_settled = ds.total_settled + count;
+    }
+
+    // ─── DappStorage: per-DApp fee rate accessors ─────────────────────────────
+
+    public fun dapp_base_fee_per_write(ds: &DappStorage): u256 { ds.base_fee_per_write }
+    public fun dapp_bytes_fee_per_byte(ds: &DappStorage): u256 { ds.bytes_fee_per_byte }
+
+    public(package) fun set_dapp_base_fee_per_write(ds: &mut DappStorage, fee: u256) {
+        ds.base_fee_per_write = fee;
+    }
+    public(package) fun set_dapp_bytes_fee_per_byte(ds: &mut DappStorage, fee: u256) {
+        ds.bytes_fee_per_byte = fee;
+    }
+
+    // ─── DappStorage: settlement mode accessors ───────────────────────────────
+
+    public fun settlement_mode(ds: &DappStorage): u8                  { ds.settlement_mode }
+    public fun dapp_write_fee_share_bps(ds: &DappStorage): u64        { ds.write_fee_dapp_share_bps }
+
+    public(package) fun set_settlement_mode(ds: &mut DappStorage, mode: u8) {
+        ds.settlement_mode = mode;
+    }
+    public(package) fun set_write_fee_dapp_share_bps(ds: &mut DappStorage, bps: u64) {
+        ds.write_fee_dapp_share_bps = bps;
+    }
+
+    // ─── DappRevenueKey — dynamic field key for DApp revenue balance ──────────
+
+    /// Key for the DApp revenue Balance<CoinType> stored as a dynamic field on DappStorage.
+    public struct DappRevenueKey<phantom CoinType> has copy, drop, store {}
+
+    public(package) fun add_dapp_revenue<CoinType>(ds: &mut DappStorage, bal: Balance<CoinType>) {
+        let key = DappRevenueKey<CoinType> {};
+        if (!dynamic_field::exists_(&ds.id, key)) {
+            dynamic_field::add(&mut ds.id, key, bal);
+        } else {
+            let stored: &mut Balance<CoinType> = dynamic_field::borrow_mut(&mut ds.id, key);
+            balance::join(stored, bal);
+        };
+    }
+
+    public(package) fun take_dapp_revenue<CoinType>(ds: &mut DappStorage): Balance<CoinType> {
+        let key = DappRevenueKey<CoinType> {};
+        if (!dynamic_field::exists_(&ds.id, key)) {
+            balance::zero<CoinType>()
+        } else {
+            let stored: &mut Balance<CoinType> = dynamic_field::borrow_mut(&mut ds.id, key);
+            balance::withdraw_all(stored)
+        }
+    }
+
+    public fun dapp_revenue_balance<CoinType>(ds: &DappStorage): u64 {
+        let key = DappRevenueKey<CoinType> {};
+        if (!dynamic_field::exists_(&ds.id, key)) {
+            0
+        } else {
+            balance::value(dynamic_field::borrow<DappRevenueKey<CoinType>, Balance<CoinType>>(&ds.id, key))
+        }
+    }
+
+    // ─── UserStorage: accessors ───────────────────────────────────────────────
+
+    public fun user_storage_dapp_key(us: &UserStorage): String { us.dapp_key }
+    public fun canonical_owner(us: &UserStorage): address { us.canonical_owner }
+    public fun session_key(us: &UserStorage): address { us.session_key }
+    public fun session_expires_at(us: &UserStorage): u64 { us.session_expires_at }
+    public fun write_count(us: &UserStorage): u64    { us.write_count }
+    public fun settled_count(us: &UserStorage): u64  { us.settled_count }
+    public fun write_bytes(us: &UserStorage): u256   { us.write_bytes }
+    public fun settled_bytes(us: &UserStorage): u256 { us.settled_bytes }
+    public fun unsettled_count(us: &UserStorage): u64  { us.write_count - us.settled_count }
+    public fun unsettled_bytes(us: &UserStorage): u256 { us.write_bytes - us.settled_bytes }
+    public fun user_write_limit(us: &UserStorage): u64 { us.write_limit }
+
+    public(package) fun set_user_write_limit(us: &mut UserStorage, val: u64) {
+        us.write_limit = val;
+    }
+
+    /// Compute the monetary value of unsettled writes using the provided fee rates.
+    /// Useful for off-chain monitoring tools and explorers.
+    /// Note: the framework write-limit guard uses UserStorage.write_limit (a write count),
+    /// not this monetary value. This function is informational only.
+    public fun compute_unsettled_charge(
+        us:         &UserStorage,
+        base_fee:   u256,
+        bytes_fee:  u256,
+    ): u256 {
+        base_fee * ((us.write_count - us.settled_count) as u256)
+            + bytes_fee * (us.write_bytes - us.settled_bytes)
+    }
+
+    /// Returns true if `sender` is allowed to write to this UserStorage right now.
+    ///
+    /// Authorised callers:
+    ///   - canonical_owner: always allowed.
+    ///   - session_key: allowed when session_key != @0x0, sender matches, and
+    ///     the session has not yet expired.
+    ///
+    /// `now_ms` should be ctx.epoch_timestamp_ms() (≈24h granularity on mainnet/
+    /// testnet, ≈1h on devnet).  Session expiry is therefore a soft deadline with
+    /// up to one epoch of tolerance.  The canonical owner can always revoke early
+    /// via deactivate_session.
+    ///
+    /// NOTE: In normal usage, session_expires_at is always > 0 because
+    /// activate_session enforces a minimum duration (MIN_SESSION_DURATION_MS).
+    /// The only way to reach session_expires_at == 0 with a non-zero session_key
+    /// is via test helpers, which represents a "never expires" state used only in
+    /// tests.
+    public fun is_write_authorized(us: &UserStorage, sender: address, now_ms: u64): bool {
+        if (sender == us.canonical_owner) { return true };
+        if (us.session_key == @0x0)       { return false };
+        if (sender != us.session_key)     { return false };
+        if (us.session_expires_at > 0 && now_ms >= us.session_expires_at) { return false };
+        true
+    }
+
+    public(package) fun set_session_key(us: &mut UserStorage, key: address) {
+        us.session_key = key;
+    }
+
+    public(package) fun set_session_expires_at(us: &mut UserStorage, ts: u64) {
+        us.session_expires_at = ts;
+    }
+
+    /// Clear the active session (set key to @0x0 and expiry to 0).
+    public(package) fun clear_session(us: &mut UserStorage) {
+        us.session_key        = @0x0;
+        us.session_expires_at = 0;
+    }
+
+    public(package) fun increment_write_count(us: &mut UserStorage) {
+        us.write_count = us.write_count + 1;
+    }
+
+    /// Accumulate `bytes` into write_bytes (called for on-chain writes only).
+    public(package) fun add_write_bytes(us: &mut UserStorage, bytes: u256) {
+        us.write_bytes = us.write_bytes + bytes;
+    }
+
+    public(package) fun add_settled_count(us: &mut UserStorage, count: u64) {
+        us.settled_count = us.settled_count + count;
+    }
+
+    public(package) fun add_settled_bytes(us: &mut UserStorage, bytes: u256) {
+        us.settled_bytes = us.settled_bytes + bytes;
+    }
+
+    public(package) fun set_settled_to_write(us: &mut UserStorage) {
+        us.settled_count = us.write_count;
+        us.settled_bytes = us.write_bytes;
+    }
+
+    // ─── Global record operations (stored on DappStorage dynamic fields) ──────
+    //
+    // Storage layout — per-field model:
+    //   sentinel   dynamic_field  key = record_key               value type = bool
+    //   field data dynamic_field  key = [record_key, field_name]  value type = vector<u8>
+    //
+    // record_key = [TABLE_NAME, key_field0, key_field1, ...]
+    //
+    // This makes field access order-independent: reordering fields in
+    // dubhe.config.ts has zero effect on stored data.
+
+    public(package) fun set_global_record<DappKey: copy + drop>(
+        ds:          &mut DappStorage,
+        mut key:     vector<vector<u8>>,
+        field_names: vector<vector<u8>>,
+        values:      vector<vector<u8>>,
+        offchain:    bool,
     ) {
-        let dapp_key = type_name::get<DappKey>().into_string();
+        let len = field_names.length();
+        error::length_mismatch(len == values.length());
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
         if (offchain) {
-            emit_store_set_record(dapp_key, account, key, value);
+            emit_store_set_record(dapp_key_str, dapp_key_str, key, values);
             return
         };
-        let account_key = new_account_key<DappKey>(account);
-        if (!self.accounts.contains(account_key)) {
-            let mut account_data = new_account_data(ctx);
-            dynamic_field::add(&mut account_data.id, key, value);
-            self.accounts.add(account_key, account_data);
-        } else {
-            let account_data = self.accounts.borrow_mut(account_key);
-            if (dynamic_field::exists_(&account_data.id, key)) {
-                *dynamic_field::borrow_mut(&mut account_data.id, key) = value;
+        // Write sentinel to mark record as existing.
+        if (!dynamic_field::exists_(&ds.id, key)) {
+            dynamic_field::add(&mut ds.id, key, true);
+        };
+        // Write each field at [key..., field_name]. Mutate key in-place to avoid
+        // allocating a separate field_key vector on every iteration.
+        let mut i = 0u64;
+        while (i < len) {
+            let fv = *values.borrow(i);
+            key.push_back(*field_names.borrow(i));
+            if (dynamic_field::exists_(&ds.id, key)) {
+                *dynamic_field::borrow_mut<vector<vector<u8>>, vector<u8>>(&mut ds.id, key) = fv;
             } else {
-                dynamic_field::add(&mut account_data.id, key, value);
+                dynamic_field::add(&mut ds.id, key, fv);
             };
+            key.pop_back();
+            i = i + 1;
         };
-        std::debug::print(&std::ascii::string(b"set_record"));
-        std::debug::print(&key);
-        std::debug::print(&value);
-        emit_store_set_record(dapp_key, account, key, value);
+        emit_store_set_record(dapp_key_str, dapp_key_str, key, values);
     }
 
-    /// Set a field
-    public(package) fun set_field<DappKey: copy + drop>(
-        self: &mut DappHub,
-        _: DappKey,
-        key: vector<vector<u8>>,
-        field_index: u8,
+    /// Update a single named field within an existing record.
+    /// Aborts with EInvalidKey if the sentinel (record) does not exist — callers
+    /// must call set_global_record first to create the record.
+    public(package) fun set_global_field<DappKey: copy + drop>(
+        ds:          &mut DappStorage,
+        mut key:     vector<vector<u8>>,
+        field_name:  vector<u8>,
         field_value: vector<u8>,
-        account: String,
     ) {
-       let dapp_key = type_name::get<DappKey>().into_string();
-       let account_key = new_account_key<DappKey>(account);
-       let account_data = self.accounts.borrow_mut(account_key);
-       let value = dynamic_field::borrow_mut<vector<vector<u8>>, vector<vector<u8>>>(&mut account_data.id, key);
-       *value.borrow_mut(field_index as u64) = field_value;
-       emit_store_set_record(dapp_key, account, key, *value)
+        // Require sentinel to exist: prevent ghost fields that have no parent record.
+        error::invalid_key(dynamic_field::exists_(&ds.id, key));
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        key.push_back(field_name);
+        if (dynamic_field::exists_(&ds.id, key)) {
+            *dynamic_field::borrow_mut<vector<vector<u8>>, vector<u8>>(&mut ds.id, key) = field_value;
+        } else {
+            dynamic_field::add(&mut ds.id, key, field_value);
+        };
+        key.pop_back();
+        emit_store_set_field(dapp_key_str, dapp_key_str, key, field_name, field_value);
     }
 
-    /// Get a record
-    public fun get_record<DappKey: copy + drop>(
-        self: &DappHub,
-        account: String,
-        key: vector<vector<u8>>
+    #[allow(unused_type_parameter)]
+    public fun get_global_field<DappKey: copy + drop>(
+        ds:         &DappStorage,
+        mut key:    vector<vector<u8>>,
+        field_name: vector<u8>,
     ): vector<u8> {
-        let account_key = new_account_key<DappKey>(account);
-        assert!(self.accounts.contains(account_key), EInvalidKey);
-        let account_data = self.accounts.borrow(account_key);
-        assert!(dynamic_field::exists_(&account_data.id, key), EInvalidKey);
-        let value = dynamic_field::borrow(&account_data.id, key);
-        std::debug::print(&key);
-        std::debug::print(value);
-        let mut result = vector::empty();
-        let mut i = 0;
-        while (i < vector::length(value)) {
-            let value = vector::borrow(value, i);
-            std::debug::print(value);
-            std::debug::print(&account);
-            vector::append(&mut result, *value);
+        key.push_back(field_name);
+        error::invalid_key(dynamic_field::exists_(&ds.id, key));
+        *dynamic_field::borrow<vector<vector<u8>>, vector<u8>>(&ds.id, key)
+    }
+
+    #[allow(unused_type_parameter)]
+    public fun has_global_record<DappKey: copy + drop>(
+        ds:  &DappStorage,
+        key: vector<vector<u8>>,
+    ): bool {
+        dynamic_field::exists_(&ds.id, key)
+    }
+
+    public fun ensure_has_global_record<DappKey: copy + drop>(
+        ds:  &DappStorage,
+        key: vector<vector<u8>>,
+    ) {
+        error::invalid_key(has_global_record<DappKey>(ds, key));
+    }
+
+    #[allow(unused_type_parameter)]
+    public fun ensure_has_not_global_record<DappKey: copy + drop>(
+        ds:  &DappStorage,
+        key: vector<vector<u8>>,
+    ) {
+        error::invalid_key(!has_global_record<DappKey>(ds, key));
+    }
+
+    /// Delete a record and all its named fields in a single call.
+    /// Emits DeleteRecord, then removes each field dynamic field followed by the sentinel.
+    ///
+    /// IMPORTANT — orphaned-field warning:
+    /// `field_names` must enumerate EVERY field name ever stored in this record across
+    /// all schema versions. Missing field names leave orphaned dynamic fields.
+    /// Always regenerate delete functions after a schema upgrade.
+    public(package) fun delete_global_record<DappKey: copy + drop>(
+        ds:          &mut DappStorage,
+        mut key:     vector<vector<u8>>,
+        field_names: vector<vector<u8>>,
+    ) {
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        error::invalid_key(dynamic_field::exists_(&ds.id, key));
+        emit_store_delete_record(dapp_key_str, dapp_key_str, key);
+        // Remove each per-field dynamic field before the sentinel.
+        let len = field_names.length();
+        let mut i = 0u64;
+        while (i < len) {
+            key.push_back(*field_names.borrow(i));
+            if (dynamic_field::exists_(&ds.id, key)) {
+                let _: vector<u8> = dynamic_field::remove(&mut ds.id, key);
+            };
+            key.pop_back();
             i = i + 1;
         };
-        result
+        let _: bool = dynamic_field::remove(&mut ds.id, key);
     }
 
-    /// Get a field
-    public fun get_field<DappKey: copy + drop>(
-        self: &DappHub,
-        account: String,
-        key: vector<vector<u8>>,
-        field_index: u8
+    /// Delete a single named field. Silently skips if the field does not exist.
+    #[allow(unused_type_parameter)]
+    public(package) fun delete_global_field<DappKey: copy + drop>(
+        ds:         &mut DappStorage,
+        mut key:    vector<vector<u8>>,
+        field_name: vector<u8>,
+    ) {
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let account = dapp_key_str;
+        key.push_back(field_name);
+        if (dynamic_field::exists_(&ds.id, key)) {
+            let _: vector<u8> = dynamic_field::remove(&mut ds.id, key);
+            key.pop_back();
+            emit_store_delete_field(dapp_key_str, account, key, field_name);
+        } else {
+            key.pop_back();
+        };
+    }
+
+    // ─── User record operations (stored on UserStorage dynamic fields) ─────────
+    //
+    // Same per-field layout as global records, but stored on UserStorage.id.
+
+    public(package) fun set_user_record<DappKey: copy + drop>(
+        us:          &mut UserStorage,
+        mut key:     vector<vector<u8>>,
+        field_names: vector<vector<u8>>,
+        values:      vector<vector<u8>>,
+        offchain:    bool,
+    ) {
+        let len = field_names.length();
+        error::length_mismatch(len == values.length());
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let account = us.canonical_owner.to_ascii_string();
+        if (offchain) {
+            emit_store_set_record(dapp_key_str, account, key, values);
+            return
+        };
+        if (!dynamic_field::exists_(&us.id, key)) {
+            dynamic_field::add(&mut us.id, key, true);
+        };
+        let mut i = 0u64;
+        while (i < len) {
+            let fv = *values.borrow(i);
+            key.push_back(*field_names.borrow(i));
+            if (dynamic_field::exists_(&us.id, key)) {
+                *dynamic_field::borrow_mut<vector<vector<u8>>, vector<u8>>(&mut us.id, key) = fv;
+            } else {
+                dynamic_field::add(&mut us.id, key, fv);
+            };
+            key.pop_back();
+            i = i + 1;
+        };
+        emit_store_set_record(dapp_key_str, account, key, values);
+    }
+
+    /// Update a single named field within an existing record.
+    /// Aborts with EInvalidKey if the sentinel (record) does not exist.
+    public(package) fun set_user_field<DappKey: copy + drop>(
+        us:          &mut UserStorage,
+        mut key:     vector<vector<u8>>,
+        field_name:  vector<u8>,
+        field_value: vector<u8>,
+    ) {
+        // Require sentinel to exist: prevent ghost fields that have no parent record.
+        error::invalid_key(dynamic_field::exists_(&us.id, key));
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let account = us.canonical_owner.to_ascii_string();
+        key.push_back(field_name);
+        if (dynamic_field::exists_(&us.id, key)) {
+            *dynamic_field::borrow_mut<vector<vector<u8>>, vector<u8>>(&mut us.id, key) = field_value;
+        } else {
+            dynamic_field::add(&mut us.id, key, field_value);
+        };
+        key.pop_back();
+        emit_store_set_field(dapp_key_str, account, key, field_name, field_value);
+    }
+
+    #[allow(unused_type_parameter)]
+    public fun get_user_field<DappKey: copy + drop>(
+        us:         &UserStorage,
+        mut key:    vector<vector<u8>>,
+        field_name: vector<u8>,
     ): vector<u8> {
-        let account_key = new_account_key<DappKey>(account);
-        assert!(self.accounts.contains(account_key), EInvalidKey);
-        let account_data = self.accounts.borrow(account_key);
-        assert!(dynamic_field::exists_(&account_data.id, key), EInvalidKey);
-        let value = dynamic_field::borrow(&account_data.id, key);
-        let field = vector::borrow(value, field_index as u64);
-        *field
-    }
-
-    public fun has_record<DappKey: copy + drop>(
-        self: &DappHub,
-        account: String,
-        key: vector<vector<u8>>
+        key.push_back(field_name);
+        error::invalid_key(dynamic_field::exists_(&us.id, key));
+        *dynamic_field::borrow<vector<vector<u8>>, vector<u8>>(&us.id, key)
+    }
+
+    #[allow(unused_type_parameter)]
+    public fun has_user_record<DappKey: copy + drop>(
+        us:  &UserStorage,
+        key: vector<vector<u8>>,
     ): bool {
-        let account_key = new_account_key<DappKey>(account);
-        if (!self.accounts.contains(account_key)) {
-            return false
-        };
-        let account_data = self.accounts.borrow(account_key);
-        dynamic_field::exists_(&account_data.id, key)
+        dynamic_field::exists_(&us.id, key)
     }
 
-    public(package) fun delete_record<DappKey: copy + drop>(
-        self: &mut DappHub,
-        _: DappKey,
+    public fun ensure_has_user_record<DappKey: copy + drop>(
+        us:  &UserStorage,
         key: vector<vector<u8>>,
-        account: String,
-    ): vector<vector<u8>> {
-        let dapp_key = type_name::get<DappKey>().into_string();
-        let account_key = new_account_key<DappKey>(account);
-        assert!(self.accounts.contains(account_key), EInvalidKey);
-        let account_data = self.accounts.borrow_mut(account_key);
-        emit_store_delete_record(dapp_key, account, key);
-        dynamic_field::remove(&mut account_data.id, key)
+    ) {
+        error::invalid_key(has_user_record<DappKey>(us, key));
     }
 
-    public fun ensure_has_record<DappKey: copy + drop>(
-        self: &DappHub,
-        account: String,
-        key: vector<vector<u8>>
+    public fun ensure_has_not_user_record<DappKey: copy + drop>(
+        us:  &UserStorage,
+        key: vector<vector<u8>>,
     ) {
-        assert!(has_record<DappKey>(self, account, key), EInvalidKey);
+        error::invalid_key(!has_user_record<DappKey>(us, key));
     }
 
-    public fun ensure_has_not_record<DappKey: copy + drop>(
-        self: &DappHub,
-        account: String,
-        key: vector<vector<u8>>
+    /// Delete a user record and all its named fields in a single call.
+    ///
+    /// IMPORTANT — orphaned-field warning:
+    /// `field_names` must enumerate EVERY field name that was ever stored in this
+    /// record across all schema versions. Fields not listed here are silently skipped
+    /// and left as orphaned dynamic fields on the object, wasting storage and
+    /// making future record recreation inconsistent.
+    /// Always regenerate delete functions after a schema upgrade (new fields added).
+    public(package) fun delete_user_record<DappKey: copy + drop>(
+        us:          &mut UserStorage,
+        mut key:     vector<vector<u8>>,
+        field_names: vector<vector<u8>>,
     ) {
-        assert!(!has_record<DappKey>(self, account, key), EInvalidKey);
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let account = us.canonical_owner.to_ascii_string();
+        error::invalid_key(dynamic_field::exists_(&us.id, key));
+        emit_store_delete_record(dapp_key_str, account, key);
+        let len = field_names.length();
+        let mut i = 0u64;
+        while (i < len) {
+            key.push_back(*field_names.borrow(i));
+            if (dynamic_field::exists_(&us.id, key)) {
+                let _: vector<u8> = dynamic_field::remove(&mut us.id, key);
+            };
+            key.pop_back();
+            i = i + 1;
+        };
+        let _: bool = dynamic_field::remove(&mut us.id, key);
     }
 
-    fun init(ctx: &mut TxContext) {
-        sui::transfer::public_share_object(
-            new(ctx)
+    /// Delete a single named field. Silently skips if the field does not exist.
+    #[allow(unused_type_parameter)]
+    public(package) fun delete_user_field<DappKey: copy + drop>(
+        us:         &mut UserStorage,
+        mut key:    vector<vector<u8>>,
+        field_name: vector<u8>,
+    ) {
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let account = us.canonical_owner.to_ascii_string();
+        key.push_back(field_name);
+        if (dynamic_field::exists_(&us.id, key)) {
+            let _: vector<u8> = dynamic_field::remove(&mut us.id, key);
+            key.pop_back();
+            emit_store_delete_field(dapp_key_str, account, key, field_name);
+        } else {
+            key.pop_back();
+        };
+    }
+
+    // ─── Genesis registry (one-shot guard per DApp) ───────────────────────────
+    //
+    // Stored as a dynamic field on DappHub keyed by the phantom DappKey type.
+    // Using a phantom type parameter (rather than a String) avoids the type-name
+    // conversion and is checked at compile time.
+    //
+    // Prevents genesis::run → create_dapp from being called more than once per
+    // DApp, even if someone rewrites genesis.move to drop the guard.
+
+    public struct DappGenesisKey<phantom DappKey> has copy, drop, store {}
+
+    /// Mark that genesis has been executed for the given DApp type.
+    public(package) fun set_dapp_genesis_done<DappKey: copy + drop>(dh: &mut DappHub) {
+        dynamic_field::add(&mut dh.id, DappGenesisKey<DappKey> {}, true);
+    }
+
+    /// Returns true iff genesis has already been executed for the given DApp type.
+    public fun is_dapp_genesis_done<DappKey: copy + drop>(dh: &DappHub): bool {
+        dynamic_field::exists_(&dh.id, DappGenesisKey<DappKey> {})
+    }
+
+    // ─── UserStorage registry (one-per-address enforcement) ──────────────────
+
+    /// Mark that `owner` has a UserStorage for this DApp.
+    /// Called exactly once per address, inside create_user_storage.
+    public(package) fun register_user_storage(ds: &mut DappStorage, owner: address) {
+        dynamic_field::add(&mut ds.id, UserStorageRegistryKey { owner }, true);
+    }
+
+    /// Returns true iff `owner` already has a registered UserStorage for this DApp.
+    public fun has_registered_user_storage(ds: &DappStorage, owner: address): bool {
+        dynamic_field::exists_(&ds.id, UserStorageRegistryKey { owner })
+    }
+
+    // ─── Listing — marketplace protocol shared object ─────────────────────────
+    //
+    // A Listing holds a BCS-encoded item record taken atomically from a seller's
+    // UserStorage.  It is a shared object so any buyer can reference it.
+    //
+    // Key properties:
+    //   • No `copy` or `drop` — Move linear types guarantee exactly one owner.
+    //   • Consumed atomically on buy or cancel_listing — no data duplication.
+    //   • `listed_until: None` means the listing never auto-expires.
+
+    public struct Listing<phantom CoinType> has key {
+        id:             UID,
+        /// Field values taken from seller's UserStorage (one inner vector per field, each BCS-encoded).
+        record_data:    vector<vector<u8>>,
+        /// The resource table name this record belongs to (e.g. b"weapon").
+        record_type:    vector<u8>,
+        /// The item's key tuple identifying the specific record slot.
+        record_key:     vector<vector<u8>>,
+        /// The field names stored in this record (for restoring on cancel).
+        field_names:    vector<vector<u8>>,
+        /// Seller address — gets item back on cancel or funds on buy.
+        seller:         address,
+        /// Price in CoinType units.
+        price:          u64,
+        /// Optional expiry (epoch ms). None = never auto-expires.
+        listed_until:   Option<u64>,
+        /// The DApp this listing belongs to (type name string of DappKey).
+        dapp_key:       std::ascii::String,
+        /// true for fungible resources; false for unique items.
+        /// Guards restore_record to prevent it being called on fungible listings
+        /// (which use cancel_fungible_listing for additive-merge semantics).
+        is_fungible:    bool,
+    }
+
+    public(package) fun new_listing<CoinType>(
+        record_data:    vector<vector<u8>>,
+        record_type:    vector<u8>,
+        record_key:     vector<vector<u8>>,
+        field_names:    vector<vector<u8>>,
+        seller:         address,
+        price:          u64,
+        listed_until:   Option<u64>,
+        dapp_key_str:   std::ascii::String,
+        is_fungible:    bool,
+        ctx:            &mut TxContext,
+    ): Listing<CoinType> {
+        Listing {
+            id:             object::new(ctx),
+            record_data,
+            record_type,
+            record_key,
+            field_names,
+            seller,
+            price,
+            listed_until,
+            dapp_key:       dapp_key_str,
+            is_fungible,
+        }
+    }
+
+    public fun listing_record_data<CoinType>(l: &Listing<CoinType>): &vector<vector<u8>>        { &l.record_data }
+    public fun listing_record_type<CoinType>(l: &Listing<CoinType>): &vector<u8>            { &l.record_type }
+    public fun listing_record_key<CoinType>(l: &Listing<CoinType>): &vector<vector<u8>>     { &l.record_key }
+    public fun listing_field_names<CoinType>(l: &Listing<CoinType>): &vector<vector<u8>>    { &l.field_names }
+    public fun listing_id<CoinType>(l: &Listing<CoinType>): &UID                            { &l.id }
+    public fun listing_seller<CoinType>(l: &Listing<CoinType>): address                      { l.seller }
+    public fun listing_price<CoinType>(l: &Listing<CoinType>): u64                           { l.price }
+    public fun listing_listed_until<CoinType>(l: &Listing<CoinType>): Option<u64>            { l.listed_until }
+    public fun listing_dapp_key<CoinType>(l: &Listing<CoinType>): std::ascii::String         { l.dapp_key }
+    public fun listing_is_fungible<CoinType>(l: &Listing<CoinType>): bool                    { l.is_fungible }
+
+    public fun is_listing_expired<CoinType>(l: &Listing<CoinType>, now_ms: u64): bool {
+        if (option::is_none(&l.listed_until)) { return false };
+        now_ms >= *option::borrow(&l.listed_until)
+    }
+
+    /// Destructure a Listing, returning all fields for further processing.
+    /// Called by buy / cancel_listing / expire_listing entry functions.
+    public(package) fun destroy_listing<CoinType>(l: Listing<CoinType>): (
+        vector<vector<u8>>, vector<u8>, vector<vector<u8>>, vector<vector<u8>>,
+        address, u64, Option<u64>, std::ascii::String,
+    ) {
+        let Listing {
+            id,
+            record_data,
+            record_type,
+            record_key,
+            field_names,
+            seller,
+            price,
+            listed_until,
+            dapp_key,
+            is_fungible: _,
+        } = l;
+        object::delete(id);
+        (record_data, record_type, record_key, field_names, seller, price, listed_until, dapp_key)
+    }
+
+    /// Share a freshly created Listing as a shared object.
+    public(package) fun share_listing<CoinType>(l: Listing<CoinType>) {
+        sui::transfer::share_object(l);
+    }
+
+    // ─── Share helper ─────────────────────────────────────────────────────────
+
+    /// Publish UserStorage as a shared object.
+    /// Must be called from the defining module since UserStorage lacks `store`.
+    /// After sharing, any transaction can reference the object; write access is
+    /// controlled by is_write_authorized.
+    public(package) fun share_user_storage(us: UserStorage) {
+        sui::transfer::share_object(us);
+    }
+
+    // ─── Fee state snapshot ───────────────────────────────────────────────────
+
+    /// Emit a dedicated DappFeeStateUpdated event that snapshots the current
+    /// credit-pool / fee-rate state of this DApp.  The indexer handles this via
+    /// the hardcoded non-schema-backed path (like marketplace / session events),
+    /// so no entry in dubhe.config.json is required.
+    /// Called by dapp_system after every operation that mutates credit/fee-rate state.
+    public(package) fun emit_fee_state_record<DappKey: copy + drop>(ds: &DappStorage) {
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        emit_dapp_fee_state_updated(
+            dapp_key_str,
+            ds.base_fee_per_write,
+            ds.bytes_fee_per_byte,
+            ds.free_credit,
+            ds.credit_pool,
+            ds.total_settled,
         );
     }
 
+    /// Emit a dedicated DappRevenueStateUpdated event that snapshots the current
+    /// pending-revenue balance of this DApp.  The indexer handles this via the
+    /// hardcoded non-schema-backed path.
+    /// Called by dapp_system after every operation that changes the revenue balance.
+    public(package) fun emit_revenue_state_record<DappKey: copy + drop, CoinType>(
+        ds: &DappStorage,
+    ) {
+        let dapp_key_str = type_name::with_defining_ids<DappKey>().into_string();
+        let coin_type_str = type_name::with_defining_ids<CoinType>().into_string();
+        let revenue = dapp_revenue_balance<CoinType>(ds);
+        emit_dapp_revenue_state_updated(dapp_key_str, revenue, coin_type_str);
+    }
+
+    // ─── Module init ─────────────────────────────────────────────────────────
+
+    fun init(ctx: &mut TxContext) {
+        // Share DappHub — this must happen before any other framework call.
+        sui::transfer::public_share_object(new(ctx));
+    }
+
+    // ─── Test helpers ─────────────────────────────────────────────────────────
+
+    #[test_only]
+    use sui::sui::SUI;
+
     #[test_only]
     public(package) fun create_dapp_hub_for_testing(ctx: &mut TxContext): DappHub {
         DappHub {
             id: object::new(ctx),
-            accounts: object_table::new(ctx),
+            fee_config: FrameworkFeeConfig {
+                base_fee_per_write:  1000,
+                bytes_fee_per_byte:  10,
+                pending_base_fee:    0,
+                pending_bytes_fee:   0,
+                fee_effective_at_ms: 0,
+                treasury:            ctx.sender(),
+                pending_treasury:    @0x0,
+                fee_history:         vector::empty(),
+                accepted_coin_type:          option::some(type_name::with_defining_ids<SUI>()),
+                pending_coin_type:           option::none(),
+                coin_type_effective_at_ms:   0,
+            },
+            config: FrameworkConfig {
+                default_free_credit:             0,
+                default_free_credit_duration_ms: 0,
+                admin:                           ctx.sender(),
+                pending_admin:                   @0x0,
+                default_write_fee_dapp_share_bps:  3000,
+                framework_max_write_limit:          2_000,
+                marketplace_fee_bps:                300,
+                marketplace_dapp_share_bps:         5_000,
+            },
+            version: 1,
+        }
+    }
+
+    #[test_only]
+    public fun destroy_dapp_hub(dh: DappHub) {
+        let DappHub { id, fee_config: _, config: _, version: _ } = dh;
+        object::delete(id);
+    }
+
+    // Alias for backwards-compat with existing tests
+    #[test_only]
+    public fun destroy(dh: DappHub) {
+        destroy_dapp_hub(dh);
+    }
+
+    /// Free-tier DappHub (both fees = 0) — for storage tests that do not test fee logic.
+    #[test_only]
+    public(package) fun create_free_dapp_hub_for_testing(ctx: &mut TxContext): DappHub {
+        DappHub {
+            id: object::new(ctx),
+            fee_config: FrameworkFeeConfig {
+                base_fee_per_write:  0,
+                bytes_fee_per_byte:  0,
+                pending_base_fee:    0,
+                pending_bytes_fee:   0,
+                fee_effective_at_ms: 0,
+                treasury:            ctx.sender(),
+                pending_treasury:    @0x0,
+                fee_history:         vector::empty(),
+                accepted_coin_type:          option::some(type_name::with_defining_ids<SUI>()),
+                pending_coin_type:           option::none(),
+                coin_type_effective_at_ms:   0,
+            },
+            config: FrameworkConfig {
+                default_free_credit:             0,
+                default_free_credit_duration_ms: 0,
+                admin:                           ctx.sender(),
+                pending_admin:                   @0x0,
+                default_write_fee_dapp_share_bps:  3000,
+                framework_max_write_limit:          2_000,
+                marketplace_fee_bps:                300,
+                marketplace_dapp_share_bps:         5_000,
+            },
+            version: 1,
         }
     }
 
     #[test_only]
-    public fun destroy(self: DappHub) {
-        let DappHub { id, accounts } = self;
+    public fun create_dapp_storage_for_testing<DappKey: copy + drop>(ctx: &mut TxContext): DappStorage {
+        new_dapp_storage<DappKey>(
+            string(b"Test DApp"),
+            string(b""),
+            vector::empty(),
+            0,
+            ctx.sender(),
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            ctx,
+        )
+    }
+
+    #[test_only]
+    public fun destroy_dapp_storage(ds: DappStorage) {
+        let DappStorage { id, .. } = ds;
+        object::delete(id);
+    }
+
+    #[test_only]
+    public fun create_user_storage_for_testing<DappKey: copy + drop>(
+        owner: address,
+        ctx:   &mut TxContext,
+    ): UserStorage {
+        new_user_storage<DappKey>(owner, 1_000, ctx)
+    }
+
+    #[test_only]
+    public fun set_session_key_for_testing(us: &mut UserStorage, key: address, expires_at: u64) {
+        us.session_key        = key;
+        us.session_expires_at = expires_at;
+    }
+
+    #[test_only]
+    public fun destroy_user_storage(us: UserStorage) {
+        let UserStorage { id, .. } = us;
         object::delete(id);
-        sui::transfer::public_freeze_object(accounts);
     }
-}
+
+    #[test_only]
+    public fun create_scene_permit_for_testing<DappKey: copy + drop, PermType>(
+        participants:     vector<address>,
+        expires_at:       std::option::Option<u64>,
+        max_participants: std::option::Option<u64>,
+        ctx:              &mut TxContext,
+    ): ScenePermit<PermType> {
+        let mut permit = ScenePermit<PermType> {
+            id:          object::new(ctx),
+            dapp_key:    type_name::with_defining_ids<DappKey>().into_string(),
+            permit_type: b"test",
+            meta:        new_scene_meta(expires_at, max_participants),
+        };
+        participants.do!(|addr| { add_participant_in_scene_permit(&mut permit, addr) });
+        permit
+    }
+
+    #[test_only]
+    public fun create_scene_permit_with_invitations_for_testing<DappKey: copy + drop, PermType>(
+        invitees:          vector<address>,
+        invites_expire_at: std::option::Option<u64>,
+        expires_at:        std::option::Option<u64>,
+        ctx:               &mut TxContext,
+    ): ScenePermit<PermType> {
+        ScenePermit<PermType> {
+            id:          object::new(ctx),
+            dapp_key:    type_name::with_defining_ids<DappKey>().into_string(),
+            permit_type: b"test",
+            meta:        new_scene_meta_with_invitations(invitees, invites_expire_at, expires_at, option::none()),
+        }
+    }
+
+    #[test_only]
+    public fun destroy_scene_permit_for_testing<PermType>(permit: ScenePermit<PermType>) {
+        let ScenePermit { id, dapp_key: _, permit_type: _, meta: _ } = permit;
+        object::delete(id);
+    }
+
+}