@0xobelisk/sui-common 1.2.0-pre.98 → 2.0.0

package/src/codegen/utils/renderMove/generateResources.ts

@@ -1,14 +1,74 @@
-import { DubheConfig } from '../../types';
-import { ComponentType } from '../../types';
+import { DubheConfig, ComponentType, Component } from '../../types';
 import { formatAndWriteMove } from '../formatAndWrite';
 
+// For the dubhe framework package itself, use package-internal dapp_service functions.
+// For DApp packages, use the public dapp_system API.
 function getDappModuleName(projectName: string): string {
   return projectName === 'dubhe' ? 'dapp_service' : `dapp_system`;
 }
 
+// Returns the inline auth argument for dapp_system write functions.
+// dapp_system::set_record / set_field / delete_record / delete_field all require a DappKey
+// value as the first argument so that only code inside the DApp's own package (where
+// dapp_key::new() is public(package)) can supply it, preventing external bypass.
+// dapp_service functions (used by dubhe's own code) have no such parameter.
+function authArg(projectName: string): string {
+  return projectName !== 'dubhe' ? 'dapp_key::new(), ' : '';
+}
+
+// dapp_system::set_record, set_field, set_global_record, and set_global_field no longer
+// require &DappHub — fee rates and debt ceilings are hardcoded as constants in dapp_system
+// and updated via package upgrade. These helpers always return empty strings.
+function dappHubArg(_projectName: string, _isGlobal: boolean): string {
+  return '';
+}
+
+function dappHubParam(_projectName: string, _isGlobal: boolean): string {
+  return '';
+}
+
+// Returns the Move storage object type based on whether the resource is global.
+function getStorageType(isGlobal: boolean): string {
+  return isGlobal ? 'DappStorage' : 'UserStorage';
+}
+
+// Returns the storage param name used in generated function signatures.
+function getStorageParamName(isGlobal: boolean): string {
+  return isGlobal ? 'dapp_storage' : 'user_storage';
+}
+
+// Returns the correct record-access function names based on global flag and project.
+function getRecordFns(projectName: string, isGlobal: boolean) {
+  const mod = getDappModuleName(projectName);
+  if (isGlobal) {
+    return {
+      set_record: `${mod}::set_global_record`,
+      set_field: `${mod}::set_global_field`,
+      get_field: `${mod}::get_global_field`,
+      has_record: `${mod}::has_global_record`,
+      ensure_has: `${mod}::ensure_has_global_record`,
+      ensure_has_not: `${mod}::ensure_has_not_global_record`,
+      delete_record: `${mod}::delete_global_record`,
+      delete_field: `${mod}::delete_global_field`
+    };
+  }
+  return {
+    set_record: `${mod}::set_record`,
+    set_field: `${mod}::set_field`,
+    get_field: `${mod}::get_field`,
+    has_record: `${mod}::has_record`,
+    ensure_has: `${mod}::ensure_has_record`,
+    ensure_has_not: `${mod}::ensure_has_not_record`,
+    delete_record: `${mod}::delete_record`,
+    delete_field: `${mod}::delete_field`
+  };
+}
+
 export async function generateResources(config: DubheConfig, path: string) {
   console.log('\n📦 Starting Resources Generation...');
 
+  if (!config.resources) return;
+
   for (const [componentName, resource] of Object.entries(config.resources)) {
     console.log(`     └─ ${componentName}: ${JSON.stringify(resource)}`);
 
@@ -31,7 +91,16 @@ export async function generateResources(config: DubheConfig, path: string) {
       resource.keys = [];
     }
 
-    const code = generateComponentCode(config.name, componentName, resource);
+    const baseCode = generateComponentCode(config.name, componentName, resource);
+    const extensionCode = generateAnnotationExtensions(
+      config,
+      componentName,
+      resource as Component
+    );
+
+    // Merge extension functions into the base module
+    const code = extensionCode ? baseCode.replace(/^}$/m, `\n${extensionCode}\n}`) : baseCode;
+
     await formatAndWriteMove(code, `${path}/${componentName}.move`, 'formatAndWriteMove');
   }
 }
@@ -42,81 +111,106 @@ function generateSimpleComponentCode(
   valueType: string,
   type: ComponentType = 'Onchain'
 ): string {
-  // Check if it's an enum type
   const isEnum = !isBasicType(valueType);
   const enumModule = isEnum ? `${toSnakeCase(valueType)}` : '';
   const isOffchain = type === 'Offchain';
+  // Simple types default to global=false (user storage)
+  const isGlobal = false;
+  const storageType = getStorageType(isGlobal);
+  const storageParam = getStorageParamName(isGlobal);
+  const fns = getRecordFns(projectName, isGlobal);
 
-  // For offchain resources, only generate set and encode functions
   const readFunctions = !isOffchain
     ? `
-    public fun has(dapp_hub: &DappHub, resource_account: String): bool {
+    public fun has(${storageParam}: &${storageType}): bool {
         let mut key_tuple = vector::empty();
         key_tuple.push_back(TABLE_NAME);
-        ${getDappModuleName(
-          projectName
-        )}::has_record<DappKey>(dapp_hub, resource_account, key_tuple)
+        ${fns.has_record}<DappKey>(${storageParam}, key_tuple)
     }
 
-    public(package) fun delete(dapp_hub: &mut DappHub, resource_account: String) {
+    public fun ensure_has(${storageParam}: &${storageType}) {
         let mut key_tuple = vector::empty();
         key_tuple.push_back(TABLE_NAME);
-        ${getDappModuleName(
-          projectName
-        )}::delete_record<DappKey>(dapp_hub, dapp_key::new(), key_tuple, resource_account);
+        ${fns.ensure_has}<DappKey>(${storageParam}, key_tuple)
     }
 
-    public fun get(dapp_hub: &DappHub, resource_account: String): (${
-      valueType === 'string' || valueType === 'String' ? 'String' : valueType
-    }) {
+    public fun ensure_has_not(${storageParam}: &${storageType}) {
         let mut key_tuple = vector::empty();
         key_tuple.push_back(TABLE_NAME);
-        let value_tuple = ${getDappModuleName(
-          projectName
-        )}::get_record<DappKey>(dapp_hub, resource_account, key_tuple);
-        let mut bsc_type = sui::bcs::new(value_tuple);
-        ${
-          valueType === 'string' || valueType === 'String'
-            ? `let value = dubhe::bcs::peel_string(&mut bsc_type);`
-            : valueType === 'vector<String>'
-            ? `let value = dubhe::bcs::peel_vec_string(&mut bsc_type);`
-            : isEnum
-            ? `let value = ${projectName}::${enumModule}::decode(&mut bsc_type);`
-            : `let value = sui::bcs::peel_${getBcsType(valueType)}(&mut bsc_type);`
-        }
+        ${fns.ensure_has_not}<DappKey>(${storageParam}, key_tuple)
+    }
+
+    public(package) fun delete(${storageParam}: &mut ${storageType}, ctx: &TxContext) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        ${fns.delete_record}<DappKey>(${authArg(
+        projectName
+      )}${storageParam}, key_tuple, vector[b"value"], ctx);
+    }
+
+    public fun get(${storageParam}: &${storageType}): (${
+        valueType === 'string' || valueType === 'String' ? 'String' : valueType
+      }) {
+        let mut key_tuple = vector::empty();
+        key_tuple.push_back(TABLE_NAME);
+        let value_raw = ${fns.get_field}<DappKey>(${storageParam}, key_tuple, b"value");
+        let mut value_bcs = sui::bcs::new(value_raw);
+        let value = ${buildParseExpr(
+          projectName,
+          valueType,
+          'value_bcs',
+          isEnum ? [{ type: valueType, module: enumModule }] : []
+        )};
         (value)
     }
 `
     : '';
 
-  return `module ${projectName}::${componentName} { 
-    use sui::bcs::{to_bytes};
-    use std::ascii::{string, String, into_bytes};
-    use dubhe::table_id;
-    use dubhe::dapp_service::{Self, DappHub};
+  const storageImport = isGlobal
+    ? `use dubhe::dapp_service::DappStorage;`
+    : `use dubhe::dapp_service::UserStorage;`;
+
+  // Imports are conditional on the value type:
+  //   - to_bytes: needed for basic types and vectors (not for enum types)
+  //   - std::ascii:
+  //       String type: {String, into_bytes}  (string fn unused - decode uses fully qualified path)
+  //       vector<String>: {String}           (into_bytes fn unused - encode uses fully qualified path)
+  //       enum: nothing
+  const isEnumType = isEnum && valueType !== 'string' && valueType !== 'String';
+  const needsToBytesImport = !isEnumType;
+  const toBytesImport = needsToBytesImport ? `\n    use sui::bcs::{to_bytes};` : '';
+  const asciiImport =
+    valueType === 'string' || valueType === 'String'
+      ? `\n    use std::ascii::{String, into_bytes};`
+      : valueType === 'vector<String>'
+      ? `\n    use std::ascii::String;`
+      : '';
+
+  return `module ${projectName}::${componentName} {${toBytesImport}${asciiImport}
+    ${storageImport}
     use dubhe::dapp_system;
     use ${projectName}::dapp_key;
     use ${projectName}::dapp_key::DappKey;
-${
-  isEnum && valueType !== 'string' && valueType !== 'String'
-    ? `    use ${projectName}::${enumModule};
-    use ${projectName}::${enumModule}::{${valueType}};`
-    : ''
-}
+${isEnumType ? `    use ${projectName}::${enumModule}::{${valueType}};` : ''}
 
     const TABLE_NAME: vector<u8> = b"${componentName}";
     const OFFCHAIN: bool = ${type === 'Offchain'};
 
 ${readFunctions}
-    public(package) fun set(dapp_hub: &mut DappHub, resource_account: String, value: ${
-      valueType === 'string' || valueType === 'String' ? 'String' : valueType
-    }, ctx: &mut TxContext) {
+    public(package) fun set(${dappHubParam(
+      projectName,
+      isGlobal
+    )}${storageParam}: &mut ${storageType}, value: ${
+    valueType === 'string' || valueType === 'String' ? 'String' : valueType
+  }, ctx: &mut TxContext) {
         let mut key_tuple = vector::empty();
         key_tuple.push_back(TABLE_NAME);
+        let field_names = vector[b"value"];
         let value_tuple = encode(value);
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, resource_account, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+    projectName,
+    isGlobal
+  )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN, ctx);
     }
 
     public fun encode(value: ${
@@ -145,11 +239,13 @@ function generateComponentCode(projectName: string, componentName: string, resou
   const fields = resource.fields;
   const keys = resource.keys || [];
   const offchain = resource.offchain || false;
-  const global = (resource as any).global || false;
+  const global = resource.global || false;
   const type: ComponentType = offchain ? 'Offchain' : 'Onchain';
 
-  // Check if it's global: offchain=true OR global=true
-  const isGlobal = offchain || global;
+  const isGlobal = global;
+  const storageType = getStorageType(isGlobal);
+  const storageParam = getStorageParamName(isGlobal);
+  const fns = getRecordFns(projectName, isGlobal);
 
   // Check if all fields are keys
   const isAllKeys = Object.keys(fields).every((name) => keys.includes(name));
@@ -161,7 +257,7 @@ function generateComponentCode(projectName: string, componentName: string, resou
   // If there is only one value field, do not generate struct
   const isSingleValue = valueFieldNames.length === 1;
 
-  // Get all enum type fields and their corresponding module names
+  // Enum types from value fields only (used for encode/decode logic)
   const enumTypes = valueFields
     .filter(([_, type]) => !isBasicType(type as string) && type !== 'string' && type !== 'String')
     .map(([_, type]) => ({
@@ -170,6 +266,15 @@ function generateComponentCode(projectName: string, componentName: string, resou
     }))
     .filter((item, index, self) => self.findIndex((t) => t.type === item.type) === index);
 
+  // All enum types (key + value) for import statement generation
+  const allEnumTypes = Object.entries(fields)
+    .filter(([_, type]) => !isBasicType(type as string) && type !== 'string' && type !== 'String')
+    .map(([_, type]) => ({
+      type: type as string,
+      module: `${toSnakeCase(type as string)}`
+    }))
+    .filter((item, index, self) => self.findIndex((t) => t.type === item.type) === index);
+
   // Generate table related functions
   const tableFunctions = generateTableFunctions(
     projectName,
@@ -179,27 +284,62 @@ function generateComponentCode(projectName: string, componentName: string, resou
     !isAllKeys && !isSingleValue,
     enumTypes,
     type,
-    isGlobal
+    isGlobal,
+    storageType,
+    storageParam,
+    fns
   );
 
+  // listable buy() still takes dapp_storage: &mut DappStorage; reactive no longer does
+  const storageImport = isGlobal
+    ? `use dubhe::dapp_service::DappStorage;`
+    : resource.listable
+    ? `use dubhe::dapp_service::{UserStorage, DappStorage};`
+    : `use dubhe::dapp_service::UserStorage;`;
+  const scenePermitImport = resource.reactive ? `\n    use dubhe::dapp_service::ScenePermit;` : '';
+
+  // Determine if any field uses ascii String type (controls std::ascii import)
+  const allFieldTypes = Object.values(fields) as string[];
+  // to_bytes needed when any value field is NOT a pure enum type
+  const nonEnumValueFields = valueFieldNames.filter((name) => {
+    const t = fields[name] as string;
+    return isBasicType(t) || t === 'string' || t === 'String';
+  });
+  const needsToBytesImport = nonEnumValueFields.length > 0 || keys.length > 0;
+  const toBytesImport = needsToBytesImport ? `\n    use sui::bcs::{to_bytes};` : '';
+  // String type needed when any field is string/String/vector<String>
+  const hasStringField = allFieldTypes.some((t) => t === 'string' || t === 'String');
+  const hasVecStringField = allFieldTypes.some((t) => t === 'vector<String>');
+  // Whether String appears in value fields (not just key fields)
+  const hasStringValueField = valueFieldNames.some((n) => {
+    const t = fields[n] as string;
+    return t === 'string' || t === 'String';
+  });
+  // Single-value / all-keys path: into_bytes only needed when value field is String.
+  //   Key encoding uses to_bytes(&key) directly (String is BCS-serialisable).
+  //   Decode uses dubhe::bcs::peel_string (fully qualified), no 'string' fn alias needed.
+  const asciiImportSimple = hasStringValueField
+    ? `\n    use std::ascii::{String, into_bytes};`
+    : hasStringField || hasVecStringField
+    ? `\n    use std::ascii::String;`
+    : '';
+  // Multi-field struct path: decode calls string(peel_vec_u8(...)) so 'string' fn alias needed.
+  const asciiImportMulti = hasStringValueField
+    ? `\n    use std::ascii::{string, String, into_bytes};`
+    : hasStringField || hasVecStringField
+    ? `\n    use std::ascii::String;`
+    : '';
+
   // If all fields are keys or there is only one value field, do not generate struct related code
   if (isAllKeys || isSingleValue) {
-    return `module ${projectName}::${componentName} { 
-    use sui::bcs::{to_bytes};
-    use std::ascii::{string, String, into_bytes};
-    use dubhe::table_id;
-    use dubhe::dapp_service::{Self, DappHub};
+    return `module ${projectName}::${componentName} {${toBytesImport}${asciiImportSimple}
+    ${storageImport}${scenePermitImport}
     use dubhe::dapp_system;
     use ${projectName}::dapp_key;
     use ${projectName}::dapp_key::DappKey;
 ${
-  enumTypes.length > 0
-    ? enumTypes
-        .map(
-          (e) => `    use ${projectName}::${e.module};
-    use ${projectName}::${e.module}::{${e.type}};`
-        )
-        .join('\n')
+  allEnumTypes.length > 0
+    ? allEnumTypes.map((e) => `    use ${projectName}::${e.module}::{${e.type}};`).join('\n')
     : ''
 }
 
@@ -273,22 +413,14 @@ ${tableFunctions}
     )
     .join('\n\n');
 
-  return `module ${projectName}::${componentName} { 
-    use sui::bcs::{to_bytes};
-    use std::ascii::{string, String, into_bytes};
-    use dubhe::table_id;
-    use dubhe::dapp_service::{Self, DappHub};
+  return `module ${projectName}::${componentName} {${toBytesImport}${asciiImportMulti}
+    ${storageImport}${scenePermitImport}
     use dubhe::dapp_system;
     use ${projectName}::dapp_key;
     use ${projectName}::dapp_key::DappKey;
 ${
-  enumTypes.length > 0
-    ? enumTypes
-        .map(
-          (e) => `    use ${projectName}::${e.module};
-    use ${projectName}::${e.module}::{${e.type}};`
-        )
-        .join('\n')
+  allEnumTypes.length > 0
+    ? allEnumTypes.map((e) => `    use ${projectName}::${e.module}::{${e.type}};`).join('\n')
     : ''
 }
 
@@ -319,6 +451,7 @@ function isBasicType(type: string): boolean {
     'address',
     'bool',
     'u8',
+    'u16',
     'u32',
     'u64',
     'u128',
@@ -328,6 +461,7 @@ function isBasicType(type: string): boolean {
     'vector<address>',
     'vector<bool>',
     'vector<u8>',
+    'vector<u16>',
     'vector<vector<u8>>',
     'vector<u32>',
     'vector<u64>',
@@ -337,6 +471,47 @@ function isBasicType(type: string): boolean {
   ].includes(type);
 }
 
+// Build a BCS peel expression for a single field, reading from bcsVar.
+function buildParseExpr(
+  projectName: string,
+  fieldType: string,
+  bcsVar: string,
+  enumTypes: Array<{ type: string; module: string }>
+): string {
+  const isEnum = !isBasicType(fieldType);
+  const enumType = isEnum ? enumTypes.find((e) => e.type === fieldType) : null;
+  if (fieldType === 'string' || fieldType === 'String') {
+    return `dubhe::bcs::peel_string(&mut ${bcsVar})`;
+  }
+  if (fieldType === 'vector<String>') {
+    return `dubhe::bcs::peel_vec_string(&mut ${bcsVar})`;
+  }
+  if (isEnum && enumType) {
+    return `${projectName}::${enumType.module}::decode(&mut ${bcsVar})`;
+  }
+  return `sui::bcs::peel_${getBcsType(fieldType)}(&mut ${bcsVar})`;
+}
+
+// Generate the three-line sequence that reads one named field from storage.
+// Uses ${fieldName}_raw / ${fieldName}_bcs as readable temporary variable names.
+function buildFieldReadLines(
+  projectName: string,
+  fns: ReturnType<typeof getRecordFns>,
+  storageParam: string,
+  fieldName: string,
+  fieldType: string,
+  _idx: number,
+  enumTypes: Array<{ type: string; module: string }>
+): string {
+  const rawVar = `${fieldName}_raw`;
+  const bcsVar = `${fieldName}_bcs`;
+  return [
+    `let ${rawVar} = ${fns.get_field}<DappKey>(${storageParam}, key_tuple, b"${fieldName}");`,
+    `let mut ${bcsVar} = sui::bcs::new(${rawVar});`,
+    `let ${fieldName} = ${buildParseExpr(projectName, fieldType, bcsVar, enumTypes)};`
+  ].join('\n        ');
+}
+
 function generateTableFunctions(
   projectName: string,
   componentName: string,
@@ -345,7 +520,10 @@ function generateTableFunctions(
   includeStruct: boolean = true,
   enumTypes: Array<{ type: string; module: string }> = [],
   type: ComponentType = 'Onchain',
-  isGlobal: boolean = false
+  isGlobal: boolean = false,
+  storageType: string = 'UserStorage',
+  storageParam: string = 'user_storage',
+  fns: ReturnType<typeof getRecordFns> = getRecordFns('dubhe', false)
 ): string {
   // Separate key fields and non-key fields
   const valueFields = Object.entries(fields)
@@ -373,72 +551,62 @@ function generateTableFunctions(
       : `let mut key_tuple = vector::empty();
         key_tuple.push_back(TABLE_NAME);`;
 
-  // For global resources, use package_id() as resource_account
-  const resourceAccountParam = isGlobal ? '' : 'resource_account: String';
-  const resourceAccountArg = isGlobal
-    ? 'dapp_key::package_id().to_ascii_string()'
-    : 'resource_account';
-
-  // Add comma after resourceAccountParam only if both exist
-  const paramSeparator = resourceAccountParam && keyParams ? ', ' : '';
+  // ctx helpers: global write functions (set_global_record, set_global_field) do not take
+  // a TxContext parameter — fees are handled inside those functions without needing ctx.
+  // Non-global write functions (set_record, set_field, delete_record) DO take ctx.
+  const ctxParam = isGlobal ? '' : ', ctx: &mut TxContext';
+  const ctxArg = isGlobal ? '' : ', ctx';
 
   // Generate has series functions - skip for offchain
   const hasFunctions = !isOffchain
-    ? `    public fun has(dapp_hub: &DappHub${
-        resourceAccountParam || keyParams ? ', ' : ''
-      }${resourceAccountParam}${paramSeparator}${keyParams}): bool {
+    ? `    public fun has(${storageParam}: &${storageType}${
+        keyParams ? ', ' : ''
+      }${keyParams}): bool {
         ${keyTupleCode}
-        ${getDappModuleName(
-          projectName
-        )}::has_record<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple)
+        ${fns.has_record}<DappKey>(${storageParam}, key_tuple)
     }
 
-    public fun ensure_has(dapp_hub: &DappHub${
-      resourceAccountParam || keyParams ? ', ' : ''
-    }${resourceAccountParam}${paramSeparator}${keyParams}) {
+    public fun ensure_has(${storageParam}: &${storageType}${keyParams ? ', ' : ''}${keyParams}) {
         ${keyTupleCode}
-        ${getDappModuleName(
-          projectName
-        )}::ensure_has_record<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple)
+        ${fns.ensure_has}<DappKey>(${storageParam}, key_tuple)
     }
 
-    public fun ensure_has_not(dapp_hub: &DappHub${
-      resourceAccountParam || keyParams ? ', ' : ''
-    }${resourceAccountParam}${paramSeparator}${keyParams}) {
+    public fun ensure_has_not(${storageParam}: &${storageType}${
+        keyParams ? ', ' : ''
+      }${keyParams}) {
         ${keyTupleCode}
-        ${getDappModuleName(
-          projectName
-        )}::ensure_has_not_record<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple)
+        ${fns.ensure_has_not}<DappKey>(${storageParam}, key_tuple)
     }
   `
     : '';
 
-  // Generate delete function - skip for offchain
+  // Generate delete function - skip for offchain.
+  // Pass all field names to delete_record so it cleans up fields and the sentinel in one call.
+  const fieldNamesLiteral = `vector[${valueNames.map((n) => `b"${n}"`).join(', ')}]`;
   const deleteFunction = !isOffchain
-    ? `    public(package) fun delete(dapp_hub: &mut DappHub${
-        resourceAccountParam || keyParams ? ', ' : ''
-      }${resourceAccountParam}${paramSeparator}${keyParams}) {
+    ? `    public(package) fun delete(${storageParam}: &mut ${storageType}${
+        keyParams ? ', ' : ''
+      }${keyParams}${isGlobal ? '' : ', ctx: &TxContext'}) {
         ${keyTupleCode}
-        ${getDappModuleName(
-          projectName
-        )}::delete_record<DappKey>(dapp_hub, dapp_key::new(), key_tuple, ${resourceAccountArg});
+        ${fns.delete_record}<DappKey>(${authArg(
+        projectName
+      )}${storageParam}, key_tuple, ${fieldNamesLiteral}${isGlobal ? '' : ', ctx'});
     }`
     : '';
 
-  // Generate getter and setter functions, only generated when there are multiple value fields
-  // For offchain, skip all getter and setter functions
+  // Generate individual getter / setter functions for each value field.
+  // Only generated when there are multiple value fields; skipped for offchain.
   const getterSetters =
     !isSingleValue && !isOffchain
       ? valueNames
           .map((name) => {
-            const index = valueNames.indexOf(name);
             const fieldType = fields[name];
             const isEnum = !isBasicType(fieldType as string);
             const enumType = isEnum ? enumTypes.find((e) => e.type === fieldType) : null;
 
-            return `    public fun get_${name}(dapp_hub: &DappHub${
-              resourceAccountParam || keyParams ? ', ' : ''
-            }${resourceAccountParam}${paramSeparator}${keyParams}): ${
+            return `    public fun get_${name}(${storageParam}: &${storageType}${
+              keyParams ? ', ' : ''
+            }${keyParams}): ${
               fieldType === 'string' || fieldType === 'String'
                 ? 'String'
                 : fieldType === 'vector<String>'
@@ -446,31 +614,22 @@ function generateTableFunctions(
                 : fieldType
             } {
         ${keyTupleCode}
-        let value = ${getDappModuleName(
-          projectName
-        )}::get_field<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple, ${index});
-        let mut bsc_type = sui::bcs::new(value);
-        ${
-          fieldType === 'string' || fieldType === 'String'
-            ? `let ${name} = dubhe::bcs::peel_string(&mut bsc_type);`
-            : fieldType === 'vector<String>'
-            ? `let ${name} = dubhe::bcs::peel_vec_string(&mut bsc_type);`
-            : isEnum
-            ? `let ${name} = ${projectName}::${enumType?.module}::decode(&mut bsc_type);`
-            : `let ${name} = sui::bcs::peel_${getBcsType(fieldType)}(&mut bsc_type);`
-        }
+        let ${name}_raw = ${fns.get_field}<DappKey>(${storageParam}, key_tuple, b"${name}");
+        let mut ${name}_bcs = sui::bcs::new(${name}_raw);
+        let ${name} = ${buildParseExpr(projectName, fieldType as string, `${name}_bcs`, enumTypes)};
         ${name}
     }
 
-    public(package) fun set_${name}(dapp_hub: &mut DappHub${
-              resourceAccountParam || keyParams ? ', ' : ''
-            }${resourceAccountParam}${paramSeparator}${keyParams}, ${name}: ${
+    public(package) fun set_${name}(${dappHubParam(
+              projectName,
+              isGlobal
+            )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}, ${name}: ${
               fieldType === 'string' || fieldType === 'String'
                 ? 'String'
                 : fieldType === 'vector<String>'
                 ? 'vector<String>'
                 : fieldType
-            }) {
+            }${ctxParam}) {
         ${keyTupleCode}
         let value = ${
           fieldType === 'string' || fieldType === 'String'
@@ -481,172 +640,177 @@ function generateTableFunctions(
             ? `${projectName}::${enumType?.module}::encode(${name})`
             : `to_bytes(&${name})`
         };
-        ${getDappModuleName(
-          projectName
-        )}::set_field(dapp_hub, dapp_key::new(), key_tuple, ${index}, value, ${resourceAccountArg});
+        ${fns.set_field}<DappKey>(${authArg(projectName)}${dappHubArg(
+              projectName,
+              isGlobal
+            )}${storageParam}, key_tuple, b"${name}", value${ctxArg});
     }`;
           })
           .join('\n\n')
       : '';
 
+  // Build the field-name vector literal used in set_record calls.
+  const fieldNamesVec = `vector[${valueNames.map((n) => `b"${n}"`).join(', ')}]`;
+
   // Generate get and set functions
   const getSetFunctions = isAllKeys
-    ? `    public(package) fun set(dapp_hub: &mut DappHub${
-        resourceAccountParam || keyParams ? ', ' : ''
-      }${resourceAccountParam}${paramSeparator}${keyParams}, ctx: &mut TxContext) {
+    ? `    public(package) fun set(${dappHubParam(
+        projectName,
+        isGlobal
+      )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}${ctxParam}) {
         ${keyTupleCode}
-        let value_tuple = vector::empty();
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        let field_names: vector<vector<u8>> = vector[];
+        let value_tuple: vector<vector<u8>> = vector[];
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+        projectName,
+        isGlobal
+      )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
     : isSingleValue
     ? !isOffchain
-      ? `    public fun get(dapp_hub: &DappHub${
-          resourceAccountParam || keyParams ? ', ' : ''
-        }${resourceAccountParam}${paramSeparator}${keyParams}): ${
+      ? `    public fun get(${storageParam}: &${storageType}${
+          keyParams ? ', ' : ''
+        }${keyParams}): ${
           Object.values(valueFields)[0] === 'string' || Object.values(valueFields)[0] === 'String'
             ? 'String'
             : Object.values(valueFields)[0]
         } {
         ${keyTupleCode}
-        let value = ${getDappModuleName(
-          projectName
-        )}::get_field<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple, 0);
-        let mut bsc_type = sui::bcs::new(value);
-        ${
-          Object.values(valueFields)[0] === 'string' || Object.values(valueFields)[0] === 'String'
-            ? `let value = dubhe::bcs::peel_string(&mut bsc_type);`
-            : Object.values(valueFields)[0] === 'vector<String>'
-            ? `let value = dubhe::bcs::peel_vec_string(&mut bsc_type);`
-            : !isBasicType(Object.values(valueFields)[0] as string)
-            ? `let value = ${projectName}::${
-                enumTypes.find((e) => e.type === Object.values(valueFields)[0])?.module
-              }::decode(&mut bsc_type);`
-            : `let value = sui::bcs::peel_${getBcsType(
-                Object.values(valueFields)[0] as string
-              )}(&mut bsc_type);`
-        }
+        let ${valueNames[0]}_raw = ${fns.get_field}<DappKey>(${storageParam}, key_tuple, b"${
+          valueNames[0]
+        }");
+        let mut ${valueNames[0]}_bcs = sui::bcs::new(${valueNames[0]}_raw);
+        let value = ${buildParseExpr(
+          projectName,
+          Object.values(valueFields)[0] as string,
+          `${valueNames[0]}_bcs`,
+          enumTypes
+        )};
         value
     }
 
-    public(package) fun set(dapp_hub: &mut DappHub${
-      resourceAccountParam || keyParams ? ', ' : ''
-    }${resourceAccountParam}${paramSeparator}${keyParams}, value: ${
+    public(package) fun set(${dappHubParam(
+      projectName,
+      isGlobal
+    )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}, value: ${
           Object.values(valueFields)[0] === 'string' || Object.values(valueFields)[0] === 'String'
             ? 'String'
             : Object.values(valueFields)[0]
-        }, ctx: &mut TxContext) {
+        }${ctxParam}) {
         ${keyTupleCode}
+        let field_names = vector[b"${valueNames[0]}"];
         let value_tuple = encode(value);
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+          projectName,
+          isGlobal
+        )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
-      : `    public(package) fun set(dapp_hub: &mut DappHub${
-          resourceAccountParam || keyParams ? ', ' : ''
-        }${resourceAccountParam}${paramSeparator}${keyParams}, value: ${
+      : `    public(package) fun set(${dappHubParam(
+          projectName,
+          isGlobal
+        )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}, value: ${
           Object.values(valueFields)[0] === 'string' || Object.values(valueFields)[0] === 'String'
             ? 'String'
             : Object.values(valueFields)[0]
-        }, ctx: &mut TxContext) {
+        }${ctxParam}) {
         ${keyTupleCode}
+        let field_names = vector[b"${valueNames[0]}"];
         let value_tuple = encode(value);
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+          projectName,
+          isGlobal
+        )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
     : !isOffchain
-    ? `    public fun get(dapp_hub: &DappHub${
-        resourceAccountParam || keyParams ? ', ' : ''
-      }${resourceAccountParam}${paramSeparator}${keyParams}): (${Object.values(valueFields)
+    ? `    public fun get(${storageParam}: &${storageType}${
+        keyParams ? ', ' : ''
+      }${keyParams}): (${Object.values(valueFields)
         .map((t) => (t === 'string' || t === 'String' ? 'String' : t))
         .join(', ')}) {
         ${keyTupleCode}
-        let value_tuple = ${getDappModuleName(
-          projectName
-        )}::get_record<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple);
-        let mut bsc_type = sui::bcs::new(value_tuple);
         ${valueNames
-          .map((name) => {
-            const fieldType = fields[name];
-            const isEnum = !isBasicType(fieldType as string);
-            const enumType = isEnum ? enumTypes.find((e) => e.type === fieldType) : null;
-            return `let ${name} = ${
-              fieldType === 'string' || fieldType === 'String'
-                ? `dubhe::bcs::peel_string(&mut bsc_type)`
-                : fieldType === 'vector<String>'
-                ? `dubhe::bcs::peel_vec_string(&mut bsc_type)`
-                : isEnum
-                ? `${projectName}::${enumType?.module}::decode(&mut bsc_type)`
-                : `sui::bcs::peel_${getBcsType(fieldType)}(&mut bsc_type)`
-            };`;
-          })
+          .map((name, i) =>
+            buildFieldReadLines(projectName, fns, storageParam, name, fields[name], i, enumTypes)
+          )
           .join('\n        ')}
         (${valueNames.join(', ')})
     }
 
-    public(package) fun set(dapp_hub: &mut DappHub${
-      resourceAccountParam || keyParams ? ', ' : ''
-    }${resourceAccountParam}${paramSeparator}${keyParams}, ${valueNames
+    public(package) fun set(${dappHubParam(
+      projectName,
+      isGlobal
+    )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}, ${valueNames
         .map(
           (n) => `${n}: ${fields[n] === 'string' || fields[n] === 'String' ? 'String' : fields[n]}`
         )
-        .join(', ')}, ctx: &mut TxContext) {
+        .join(', ')}${ctxParam}) {
         ${keyTupleCode}
+        let field_names = ${fieldNamesVec};
         let value_tuple = encode(${valueNames.join(', ')});
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+        projectName,
+        isGlobal
+      )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
-    : `    public(package) fun set(dapp_hub: &mut DappHub${
-        resourceAccountParam || keyParams ? ', ' : ''
-      }${resourceAccountParam}${paramSeparator}${keyParams}, ${valueNames
+    : `    public(package) fun set(${dappHubParam(
+        projectName,
+        isGlobal
+      )}${storageParam}: &mut ${storageType}${keyParams ? ', ' : ''}${keyParams}, ${valueNames
         .map(
           (n) => `${n}: ${fields[n] === 'string' || fields[n] === 'String' ? 'String' : fields[n]}`
         )
-        .join(', ')}, ctx: &mut TxContext) {
+        .join(', ')}${ctxParam}) {
         ${keyTupleCode}
+        let field_names = ${fieldNamesVec};
         let value_tuple = encode(${valueNames.join(', ')});
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+        projectName,
+        isGlobal
+      )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`;
 
   // Generate struct related functions
   const structFunctions = includeStruct
     ? !isOffchain
-      ? `    public fun get_struct(dapp_hub: &DappHub${
-          resourceAccountParam || keyParams ? ', ' : ''
-        }${resourceAccountParam}${paramSeparator}${keyParams}): ${toPascalCase(componentName)} {
+      ? `    public fun get_struct(${storageParam}: &${storageType}${
+          keyParams ? ', ' : ''
+        }${keyParams}): ${toPascalCase(componentName)} {
         ${keyTupleCode}
-        let value_tuple = ${getDappModuleName(
-          projectName
-        )}::get_record<DappKey>(dapp_hub, ${resourceAccountArg}, key_tuple);
-        decode(value_tuple)
+        ${valueNames
+          .map((name, i) =>
+            buildFieldReadLines(projectName, fns, storageParam, name, fields[name], i, enumTypes)
+          )
+          .join('\n        ')}
+        ${toPascalCase(componentName)} { ${valueNames.join(', ')} }
     }
 
-    public(package) fun set_struct(dapp_hub: &mut DappHub${
-      resourceAccountParam || keyParams ? ', ' : ''
-    }${resourceAccountParam}${paramSeparator}${keyParams}, ${componentName}: ${toPascalCase(
-          componentName
-        )}, ctx: &mut TxContext) {
+    public(package) fun set_struct(${dappHubParam(
+      projectName,
+      isGlobal
+    )}${storageParam}: &mut ${storageType}${
+          keyParams ? ', ' : ''
+        }${keyParams}, ${componentName}: ${toPascalCase(componentName)}${ctxParam}) {
         ${keyTupleCode}
+        let field_names = ${fieldNamesVec};
         let value_tuple = encode_struct(${componentName});
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+          projectName,
+          isGlobal
+        )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
-      : `    public(package) fun set_struct(dapp_hub: &mut DappHub${
-          resourceAccountParam || keyParams ? ', ' : ''
-        }${resourceAccountParam}${paramSeparator}${keyParams}, ${componentName}: ${toPascalCase(
-          componentName
-        )}, ctx: &mut TxContext) {
+      : `    public(package) fun set_struct(${dappHubParam(
+          projectName,
+          isGlobal
+        )}${storageParam}: &mut ${storageType}${
+          keyParams ? ', ' : ''
+        }${keyParams}, ${componentName}: ${toPascalCase(componentName)}${ctxParam}) {
         ${keyTupleCode}
+        let field_names = ${fieldNamesVec};
         let value_tuple = encode_struct(${componentName});
-        ${getDappModuleName(
-          projectName
-        )}::set_record(dapp_hub, dapp_key::new(), key_tuple, value_tuple, ${resourceAccountArg}, OFFCHAIN, ctx);
+        ${fns.set_record}<DappKey>(${authArg(projectName)}${dappHubArg(
+          projectName,
+          isGlobal
+        )}${storageParam}, key_tuple, field_names, value_tuple, OFFCHAIN${ctxArg});
     }`
     : '';
 
@@ -704,7 +868,7 @@ function generateTableFunctions(
     }
 
     public fun decode(data: vector<u8>): ${toPascalCase(componentName)} {
-        let mut bsc_type = sui::bcs::new(data);
+        let mut bcs_type = sui::bcs::new(data);
         ${valueNames
           .map((n) => {
             const fieldType = fields[n];
@@ -712,12 +876,12 @@ function generateTableFunctions(
             const enumType = isEnum ? enumTypes.find((e) => e.type === fieldType) : null;
             return `let ${n} = ${
               fieldType === 'string' || fieldType === 'String'
-                ? `string(sui::bcs::peel_vec_u8(&mut bsc_type))`
+                ? `string(sui::bcs::peel_vec_u8(&mut bcs_type))`
                 : fieldType === 'vector<String>'
-                ? `dubhe::bcs::peel_vec_string(&mut bsc_type)`
+                ? `dubhe::bcs::peel_vec_string(&mut bcs_type)`
                 : isEnum
-                ? `${projectName}::${enumType?.module}::decode(&mut bsc_type)`
-                : `sui::bcs::peel_${getBcsType(fieldType)}(&mut bsc_type)`
+                ? `${projectName}::${enumType?.module}::decode(&mut bcs_type)`
+                : `sui::bcs::peel_${getBcsType(fieldType)}(&mut bcs_type)`
             };`;
           })
           .join('\n        ')}
@@ -770,15 +934,12 @@ function generateTableFunctions(
 }
 
 function toPascalCase(str: string): string {
-  // Split the underscore-separated string into words
   return str
     .split('_')
     .map((word, _index) => {
-      // If the word is a pure number, return it as is
       if (/^\d+$/.test(word)) {
         return word;
       }
-      // Otherwise, capitalize the first letter and lowercase the rest
       return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
     })
     .join('');
@@ -819,3 +980,494 @@ function getBcsType(type: string): string {
       return type;
   }
 }
+
+// ─── Annotation-based code extensions ────────────────────────────────────────
+
+/**
+ * Generate additional Move functions for a resource based on its annotations.
+ * Returns a string of extra function bodies to inject into the module, or '' if none.
+ */
+function generateAnnotationExtensions(
+  config: DubheConfig,
+  componentName: string,
+  comp: Component
+): string {
+  const parts: string[] = [];
+  const projectName = config.name;
+  const mod = getDappModuleName(projectName);
+  const auth = authArg(projectName);
+
+  const fields = comp.fields;
+  const keys = comp.keys ?? [];
+  const valueFields = Object.entries(fields).filter(([n]) => !keys.includes(n));
+  const valueNames = valueFields.map(([n]) => n);
+  const keyParams = keys.length > 0 ? keys.map((k) => `${k}: ${fields[k]}`).join(', ') : '';
+
+  // ── fungible: true ────────────────────────────────────────────────────────
+  if (comp.fungible && valueNames.length === 1) {
+    const [_vName, vType] = valueFields[0];
+    parts.push(`
+    // ─── fungible add / sub ─────────────────────────────────────────────
+    #[error]
+    const EInsufficientAmount: vector<u8> = b"Insufficient amount";
+
+    public(package) fun add(user_storage: &mut UserStorage, amount: ${vType}, 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: ${vType}, ctx: &mut TxContext) {
+        let current = get(user_storage);
+        assert!(current >= amount, EInsufficientAmount);
+        set(user_storage, current - amount, ctx);
+    }`);
+  }
+
+  // ── keys: auto-generate mint for any keyed resource ─────────────────────
+  // Developer provides all key values — ID strategy is intentionally caller-decided.
+  if (keys.length > 0 && !comp.offchain && !comp.global) {
+    const allKeyParams = keys.map((k) => `${k}: ${fields[k]}`).join(', ');
+    const valueParams = valueNames.map((n) => `${n}: ${fields[n]}`).join(', ');
+    const allParams = [allKeyParams, valueParams].filter(Boolean).join(', ');
+    const keyArgs = keys.join(', ');
+    const setArgs = [...keys, ...valueNames].join(', ');
+
+    parts.push(`
+    // ─── keys: mint (developer provides keys; framework ensures no duplicate) ─
+    // Choosing the ID strategy (fresh address, counter, coordinate pack, etc.)
+    // is intentionally left to the caller.
+    public(package) fun mint(
+        user_storage: &mut UserStorage,
+        ${allParams},
+        ctx: &mut TxContext,
+    ) {
+        ensure_has_not(user_storage, ${keyArgs});
+        set(user_storage, ${setArgs}, ctx);
+    }`);
+  }
+
+  // ── reactive: true ────────────────────────────────────────────────────────
+  if (comp.reactive) {
+    const keyTupleCode =
+      keys.length > 0
+        ? `let mut key_tuple = vector::empty();\n        key_tuple.push_back(TABLE_NAME);\n        ${keys
+            .map((k) => `key_tuple.push_back(sui::bcs::to_bytes(&${k}));`)
+            .join('\n        ')}`
+        : `let mut key_tuple = vector::empty();\n        key_tuple.push_back(TABLE_NAME);`;
+
+    // Full reactive set
+    if (valueNames.length > 1) {
+      const params = valueNames.map((n) => `${n}: ${fields[n]}`).join(', ');
+      parts.push(`
+    // ─── reactive: cross-user write variants ───────────────────────────
+    // Package-level helpers: add pause checks and access control in your system
+    // functions before calling these.
+    public(package) fun set_reactive<PermType>(
+        permit: &ScenePermit<PermType>,
+        from:   &mut UserStorage,
+        target: &mut UserStorage,
+        ${keyParams ? keyParams + ', ' : ''}${params},
+        ctx:    &mut TxContext,
+    ) {
+        ${keyTupleCode}
+        let field_names = vector[${valueNames.map((n) => `b"${n}"`).join(', ')}];
+        let value_tuple = encode(${valueNames.join(', ')});
+        ${mod}::set_record_reactive<DappKey, PermType>(${auth}permit, from, target, key_tuple, field_names, value_tuple, ctx);
+    }`);
+    }
+
+    // Per-field reactive setters
+    for (const [fName, fType] of valueFields) {
+      const encodeExpr =
+        fType === 'string' || fType === 'String'
+          ? `sui::bcs::to_bytes(&std::ascii::into_bytes(${fName}))`
+          : `sui::bcs::to_bytes(&${fName})`;
+      parts.push(`
+    public(package) fun set_${fName}_reactive<PermType>(
+        permit: &ScenePermit<PermType>,
+        from:   &mut UserStorage,
+        target: &mut UserStorage,
+        ${keyParams ? keyParams + ', ' : ''}${fName}: ${
+        fType === 'string' || fType === 'String' ? 'String' : fType
+      },
+        ctx:    &mut TxContext,
+    ) {
+        ${keyTupleCode}
+        let value = ${encodeExpr};
+        ${mod}::set_field_reactive<DappKey, PermType>(${auth}permit, from, target, key_tuple, b"${fName}", value, ctx);
+    }`);
+    }
+  }
+
+  // ── transferable: true — generate transfer functions ─────────────────────
+  if (comp.transferable) {
+    const objects = config.objects ?? {};
+    const scenes = config.scenes ?? {};
+    const isFungible = !!comp.fungible;
+    // Trigger for any non-fungible keyed resource
+    const isKeyed = !isFungible && keys.length > 0;
+    const idField = isKeyed ? keys[0] : null;
+
+    for (const [objKey, objCfg] of Object.entries(objects)) {
+      if (!(objCfg.accepts ?? []).includes(componentName)) continue;
+      // Use fully-qualified ObjectStorage<Marker> type
+      const objMarker = toPascalCase(objKey);
+      const ObjStruct = `dubhe::dapp_service::ObjectStorage<${projectName}::${objKey}::${objMarker}>`;
+      const objMod = objKey;
+
+      if (isFungible && valueNames.length === 1) {
+        const [, vType] = valueFields[0];
+        parts.push(`
+    // ─── transferable: User ↔ ${objMarker}Storage (fungible) ─────────────
+    public(package) fun transfer_user_to_${objKey}(
+        user:   &mut UserStorage,
+        target: &mut ${ObjStruct},
+        amount: ${vType},
+        ctx:    &mut TxContext,
+    ) {
+        sub(user, amount, ctx);
+        ${projectName}::${objMod}::add_${componentName}(target, amount);
+    }
+
+    public(package) fun transfer_${objKey}_to_user(
+        source: &mut ${ObjStruct},
+        user:   &mut UserStorage,
+        amount: ${vType},
+        ctx:    &mut TxContext,
+    ) {
+        ${projectName}::${objMod}::sub_${componentName}(source, amount);
+        add(user, amount, ctx);
+    }`);
+      } else if (isKeyed && idField) {
+        if (valueNames.length === 1) {
+          const [, svType] = valueFields[0];
+          const encodeRaw =
+            svType === 'string' || svType === 'String'
+              ? `to_bytes(&std::ascii::into_bytes(get(user, ${idField})))`
+              : `to_bytes(&get(user, ${idField}))`;
+          const enumTypes = Object.entries(config.enums ?? {}).map(([n]) => ({
+            type: toPascalCase(n),
+            module: n
+          }));
+          const peelExpr = buildParseExpr(projectName, svType, 'bcs', enumTypes);
+          parts.push(`
+    // ─── transferable: User ↔ ${objMarker}Storage (keyed) ──────────────
+    public(package) fun transfer_user_to_${objKey}(
+        user:     &mut UserStorage,
+        target:   &mut ${ObjStruct},
+        ${idField}: u64,
+        ctx:      &TxContext,
+    ) {
+        ensure_has(user, ${idField});
+        // Guard before any mutation: abort if target already holds this item.
+        dubhe::error::item_already_owned(!${projectName}::${objMod}::has_${componentName}(target, ${idField}));
+        let raw = ${encodeRaw};
+        delete(user, ${idField}, ctx);
+        ${projectName}::${objMod}::set_${componentName}_data(target, ${idField}, raw);
+    }
+
+    public(package) fun transfer_${objKey}_to_user(
+        source:   &mut ${ObjStruct},
+        user:     &mut UserStorage,
+        ${idField}: u64,
+        ctx:      &mut TxContext,
+    ) {
+        // Guard before any mutation: abort if user already owns this item.
+        ensure_has_not(user, ${idField});
+        let raw = ${projectName}::${objMod}::remove_${componentName}_data(source, ${idField});
+        let mut bcs = sui::bcs::new(raw);
+        let value = ${peelExpr};
+        set(user, ${idField}, value, ctx);
+    }`);
+        } else {
+          parts.push(`
+    // ─── transferable: User ↔ ${objMarker}Storage (keyed, multi-field) ──
+    public(package) fun transfer_user_to_${objKey}(
+        user:     &mut UserStorage,
+        target:   &mut ${ObjStruct},
+        ${idField}: u64,
+        ctx:      &TxContext,
+    ) {
+        ensure_has(user, ${idField});
+        // Guard before any mutation: abort if target already holds this item.
+        dubhe::error::item_already_owned(!${projectName}::${objMod}::has_${componentName}(target, ${idField}));
+        let data = encode_struct(get_struct(user, ${idField}));
+        delete(user, ${idField}, ctx);
+        let raw: vector<u8> = sui::bcs::to_bytes(&data);
+        ${projectName}::${objMod}::set_${componentName}_data(target, ${idField}, raw);
+    }
+
+    public(package) fun transfer_${objKey}_to_user(
+        source:   &mut ${ObjStruct},
+        user:     &mut UserStorage,
+        ${idField}: u64,
+        ctx:      &mut TxContext,
+    ) {
+        // Guard before any mutation: abort if user already owns this item.
+        ensure_has_not(user, ${idField});
+        let raw = ${projectName}::${objMod}::remove_${componentName}_data(source, ${idField});
+        let decoded = decode(raw);
+        set_struct(user, ${idField}, decoded, ctx);
+    }`);
+        }
+      }
+    }
+
+    for (const [sceneKey, sceneCfg] of Object.entries(scenes)) {
+      if (!(sceneCfg.accepts ?? []).includes(componentName)) continue;
+      // Use fully-qualified SceneStorage<Marker> type
+      const sceneMarker = toPascalCase(sceneKey);
+      const SceneStruct = `dubhe::dapp_service::SceneStorage<${projectName}::${sceneKey}::${sceneMarker}>`;
+      const sceneMod = sceneKey;
+      const scenePermitType =
+        sceneCfg.authorization.kind === 'permit'
+          ? `dubhe::dapp_service::ScenePermit<${projectName}::${
+              sceneCfg.authorization.permit
+            }::${toPascalCase(sceneCfg.authorization.permit)}>`
+          : '';
+      const scenePermitParam =
+        sceneCfg.authorization.kind === 'permit' ? `        permit: &${scenePermitType},\n` : '';
+      const scenePermitArg = sceneCfg.authorization.kind === 'permit' ? 'permit, ' : '';
+      // Permit-authorized scene writes identify the caller via their UserStorage,
+      // which for these transfers is the `user` side of the transfer itself.
+      const sceneUserCall = sceneCfg.authorization.kind === 'permit' ? 'user, ' : '';
+      const sceneCtxArg = sceneCfg.authorization.kind === 'permit' ? ', ctx' : '';
+
+      if (isFungible && valueNames.length === 1) {
+        const [, vType] = valueFields[0];
+        parts.push(`
+    // ─── transferable: User ↔ ${sceneMarker}Storage (fungible) ──────────
+    public(package) fun transfer_user_to_${sceneKey}(
+${scenePermitParam}        user:   &mut UserStorage,
+        target: &mut ${SceneStruct},
+        amount: ${vType},
+        ctx:    &mut TxContext,
+    ) {
+        sub(user, amount, ctx);
+        ${projectName}::${sceneMod}::add_${componentName}(${scenePermitArg}target, ${sceneUserCall}amount${sceneCtxArg});
+    }
+
+    // ★ No expiry check on withdraw direction — prevents asset lock-in expired scenes.
+    public(package) fun transfer_${sceneKey}_to_user(
+${scenePermitParam}        source: &mut ${SceneStruct},
+        user:   &mut UserStorage,
+        amount: ${vType},
+        ctx:    &mut TxContext,
+    ) {
+        ${projectName}::${sceneMod}::sub_${componentName}(${scenePermitArg}source, ${sceneUserCall}amount${sceneCtxArg});
+        add(user, amount, ctx);
+    }`);
+      } else if (isKeyed && idField) {
+        if (valueNames.length === 1) {
+          const [, svType] = valueFields[0];
+          const encodeRaw =
+            svType === 'string' || svType === 'String'
+              ? `to_bytes(&std::ascii::into_bytes(get(user, ${idField})))`
+              : `to_bytes(&get(user, ${idField}))`;
+          const enumTypes = Object.entries(config.enums ?? {}).map(([n]) => ({
+            type: toPascalCase(n),
+            module: n
+          }));
+          const peelExpr = buildParseExpr(projectName, svType, 'bcs', enumTypes);
+          parts.push(`
+    // ─── transferable: User ↔ ${sceneMarker}Storage (keyed) ─────────────
+    public(package) fun transfer_user_to_${sceneKey}(
+${scenePermitParam}        user:   &mut UserStorage,
+        target: &mut ${SceneStruct},
+        ${idField}: u64,
+        ctx:    &TxContext,
+    ) {
+        ensure_has(user, ${idField});
+        // Guard before any mutation: abort if target already holds this item.
+        dubhe::error::item_already_owned(!${projectName}::${sceneMod}::has_${componentName}(target, ${idField}));
+        let raw = ${encodeRaw};
+        delete(user, ${idField}, ctx);
+        ${projectName}::${sceneMod}::set_${componentName}_data(${scenePermitArg}target, ${sceneUserCall}${idField}, raw${sceneCtxArg});
+    }
+
+    public(package) fun transfer_${sceneKey}_to_user(
+${scenePermitParam}        source: &mut ${SceneStruct},
+        user:   &mut UserStorage,
+        ${idField}: u64,
+        ctx:    &mut TxContext,
+    ) {
+        // Guard before any mutation: abort if user already owns this item.
+        ensure_has_not(user, ${idField});
+        let raw = ${projectName}::${sceneMod}::remove_${componentName}_data(${scenePermitArg}source, ${sceneUserCall}${idField}${sceneCtxArg});
+        let mut bcs = sui::bcs::new(raw);
+        let value = ${peelExpr};
+        set(user, ${idField}, value, ctx);
+    }`);
+        } else {
+          parts.push(`
+    // ─── transferable: User ↔ ${sceneMarker}Storage (keyed, multi-field) ─
+    public(package) fun transfer_user_to_${sceneKey}(
+${scenePermitParam}        user:   &mut UserStorage,
+        target: &mut ${SceneStruct},
+        ${idField}: u64,
+        ctx:    &TxContext,
+    ) {
+        ensure_has(user, ${idField});
+        // Guard before any mutation: abort if target already holds this item.
+        dubhe::error::item_already_owned(!${projectName}::${sceneMod}::has_${componentName}(target, ${idField}));
+        let data = encode_struct(get_struct(user, ${idField}));
+        delete(user, ${idField}, ctx);
+        let raw: vector<u8> = sui::bcs::to_bytes(&data);
+        ${projectName}::${sceneMod}::set_${componentName}_data(${scenePermitArg}target, ${sceneUserCall}${idField}, raw${sceneCtxArg});
+    }
+
+    public(package) fun transfer_${sceneKey}_to_user(
+${scenePermitParam}        source: &mut ${SceneStruct},
+        user:   &mut UserStorage,
+        ${idField}: u64,
+        ctx:    &mut TxContext,
+    ) {
+        // Guard before any mutation: abort if user already owns this item.
+        ensure_has_not(user, ${idField});
+        let raw = ${projectName}::${sceneMod}::remove_${componentName}_data(${scenePermitArg}source, ${sceneUserCall}${idField}${sceneCtxArg});
+        let decoded = decode(raw);
+        set_struct(user, ${idField}, decoded, ctx);
+    }`);
+        }
+      }
+    }
+  }
+
+  // ── listable: true ────────────────────────────────────────────────────────
+  if (comp.listable) {
+    const isFungible = !!comp.fungible;
+    // Any keyed non-fungible listable resource gets record-based marketplace helpers.
+    const isKeyed = !isFungible && keys.length > 0;
+    const isUnique = isKeyed;
+    const idField = isUnique ? keys[0] : null;
+    const tableNameExpr = `b"${componentName}"`;
+
+    if (isFungible && valueNames.length === 1) {
+      // Fungible listing helpers — package-visible so developers must expose them
+      // through their own system functions where they can add custom guards
+      // (pause checks, access control, etc.).
+      parts.push(`
+    // ─── 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,
+            ${tableNameExpr},
+            { let mut k = vector::empty(); k.push_back(TABLE_NAME); k },
+            b"${valueNames[0]}",
+            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
+        );
+    }`);
+    } else if (isUnique && idField) {
+      // Build key params and record_key bytes using ALL keys (not just idField/keys[0])
+      const listKeyParams = keys.map((k) => `${k}:   ${fields[k] as string}`).join(',\n        ');
+      const listRecordKeyLines = keys
+        .map((k) => `record_key.push_back(sui::bcs::to_bytes(&${k}));`)
+        .join('\n        ');
+      parts.push(`
+    // ─── listable: market protocol (keyed) ──────────────────────────────
+    // 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,
+        ${listKeyParams},
+        price:        u64,
+        listed_until: std::option::Option<u64>,
+        ctx:          &mut TxContext,
+    ) {
+        let mut record_key = vector::empty();
+        record_key.push_back(TABLE_NAME);
+        ${listRecordKeyLines}
+        dubhe::dapp_system::take_record<DappKey, CoinType>(
+            dapp_key::new(),
+            user_storage,
+            ${tableNameExpr},
+            record_key,
+            vector[${valueNames.map((n) => `b"${n}"`).join(', ')}],
+            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_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::restore_record<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_listing<DappKey, CoinType>(
+            dapp_key::new(), listing, user_storage, ctx
+        );
+    }`);
+    }
+  }
+
+  return parts.join('\n');
+}