@0xobelisk/sui-cli 1.2.0-pre.118 → 1.2.0-pre.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xobelisk/sui-cli",
-  "version": "1.2.0-pre.118",
+  "version": "1.2.0-pre.119",
   "description": "Tookit for interacting with move eps framework",
   "keywords": [
     "sui",
@@ -47,8 +47,8 @@
     "yargs": "^17.7.1",
     "zod": "^3.22.3",
     "zod-validation-error": "^1.3.0",
-    "@0xobelisk/sui-client": "1.2.0-pre.118",
-    "@0xobelisk/sui-common": "1.2.0-pre.118"
+    "@0xobelisk/sui-client": "1.2.0-pre.119",
+    "@0xobelisk/sui-common": "1.2.0-pre.119"
   },
   "devDependencies": {
     "@types/cli-progress": "^3.11.5",

package/src/commands/build.ts

@@ -4,7 +4,7 @@ import nodePath from 'path';
 import chalk from 'chalk';
 import { DubheConfig, loadConfig } from '@0xobelisk/sui-common';
 import { handlerExit } from './shell';
-import { getDefaultNetwork, switchEnv } from '../utils';
+import { getDefaultNetwork, switchEnv, lintSystemGuards, formatLintWarnings } from '../utils';
 
 type Options = {
   'config-path': string;
@@ -78,6 +78,12 @@ const commandModule: CommandModule<Options, Options> = {
       console.log('🚀 Running move build');
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
       await switchEnv(network);
+
+      const projectPath = nodePath.join(process.cwd(), 'src', dubheConfig.name);
+      const lintResults = lintSystemGuards(projectPath);
+      const warnings = formatLintWarnings(lintResults);
+      if (warnings) process.stdout.write(warnings);
+
       const output = await buildHandler(dubheConfig, network, dumpBytecodeAsBase64);
       console.log(output);
       exec(`pnpm dubhe convert-json --config-path ${configPath}`);

package/src/commands/convertJson.ts

@@ -10,6 +10,33 @@ type Options = {
   'output-path': string;
 };
 
+const RUNTIME_FIELDS = [
+  'original_package_id',
+  'dubhe_object_id',
+  'original_dubhe_package_id',
+  'dapp_key',
+  'start_checkpoint'
+];
+
+export function mergeConfigJsonRuntimeFields(
+  schemaJson: Record<string, unknown>,
+  existing: Record<string, unknown>
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...schemaJson };
+  for (const field of RUNTIME_FIELDS) {
+    if (existing[field] !== undefined) {
+      merged[field] = existing[field];
+    }
+  }
+  // If dapp_key is missing but original_package_id is present, compute it.
+  // This handles configs created before dapp_key was introduced.
+  if (!merged['dapp_key'] && merged['original_package_id']) {
+    const hex = (merged['original_package_id'] as string).replace(/^0x/i, '').padStart(64, '0');
+    merged['dapp_key'] = `${hex}::dapp_key::DappKey`;
+  }
+  return merged;
+}
+
 const commandModule: CommandModule<Options, Options> = {
   command: 'convert-json',
   describe: 'Convert JSON from Dubhe config to config.json',
@@ -34,14 +61,6 @@ const commandModule: CommandModule<Options, Options> = {
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
       const schemaJson = JSON.parse(generateConfigJson(dubheConfig));
 
-      // Preserve runtime fields written by publishHandler (package IDs, checkpoint, etc.)
-      // so that re-running convert-json after publish does not wipe deployment info.
-      const RUNTIME_FIELDS = [
-        'original_package_id',
-        'dubhe_object_id',
-        'original_dubhe_package_id',
-        'start_checkpoint'
-      ];
       let existing: Record<string, unknown> = {};
       if (fs.existsSync(outputPath)) {
         try {
@@ -50,12 +69,7 @@ const commandModule: CommandModule<Options, Options> = {
           // ignore parse errors – start fresh
         }
       }
-      const merged: Record<string, unknown> = { ...schemaJson };
-      for (const field of RUNTIME_FIELDS) {
-        if (existing[field] !== undefined) {
-          merged[field] = existing[field];
-        }
-      }
+      const merged = mergeConfigJsonRuntimeFields(schemaJson, existing);
 
       fs.writeFileSync(outputPath, JSON.stringify(merged, null, 2));
     } catch (error: any) {

package/src/commands/generate.ts

@@ -1,5 +1,5 @@
 import type { CommandModule } from 'yargs';
-import { schemaGen, loadConfig, DubheConfig } from '@0xobelisk/sui-common';
+import { codegen, loadConfig, DubheConfig } from '@0xobelisk/sui-common';
 import chalk from 'chalk';
 import path from 'node:path';
 import { handlerExit } from './shell';
@@ -8,11 +8,13 @@ import { getDefaultNetwork } from '../utils';
 type Options = {
   'config-path'?: string;
   network?: 'mainnet' | 'testnet' | 'devnet' | 'localnet' | 'default';
+  mode?: 'user_pays' | 'dapp_subsidizes';
 };
 
 const commandModule: CommandModule<Options, Options> = {
+  command: 'generate',
   // 'schemagen' kept as a deprecated alias for backward compatibility
-  command: 'generate|schemagen',
+  aliases: ['schemagen'],
 
   describe: 'Generate Move code from dubhe.config.ts',
 
@@ -27,10 +29,16 @@ const commandModule: CommandModule<Options, Options> = {
       choices: ['mainnet', 'testnet', 'devnet', 'localnet', 'default'] as const,
       default: 'default',
       desc: 'Node network (mainnet/testnet/devnet/localnet)'
+    },
+    mode: {
+      type: 'string',
+      choices: ['user_pays', 'dapp_subsidizes'] as const,
+      default: 'user_pays',
+      desc: 'Initial settlement mode for this DApp (only applies on first generate)'
     }
   },
 
-  async handler({ 'config-path': configPath, network }) {
+  async handler({ 'config-path': configPath, network, mode }) {
     try {
       if (!configPath) throw new Error('Config path is required');
       if (network == 'default') {
@@ -39,7 +47,8 @@ const commandModule: CommandModule<Options, Options> = {
       }
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
       const rootDir = path.dirname(configPath);
-      await schemaGen(rootDir, dubheConfig, network);
+      const initialMode: 0 | 1 = mode === 'dapp_subsidizes' ? 0 : 1;
+      await codegen(rootDir, dubheConfig, network, initialMode);
       handlerExit();
     } catch (error: any) {
       console.log(chalk.red('Generate failed!'));

package/src/commands/publish.ts

@@ -1,8 +1,15 @@
 import type { CommandModule } from 'yargs';
 import { logError } from '../utils/errors';
-import { getDefaultNetwork, publishHandler } from '../utils';
+import {
+  getDefaultNetwork,
+  publishHandler,
+  lintSystemGuards,
+  formatLintWarnings,
+  confirm
+} from '../utils';
 import { loadConfig, DubheConfig } from '@0xobelisk/sui-common';
 import { execSync } from 'child_process';
+import { join as pathJoin } from 'path';
 import { handlerExit } from './shell';
 import chalk from 'chalk';
 
@@ -51,6 +58,21 @@ const commandModule: CommandModule<Options, Options> = {
         console.log(chalk.yellow(`Use default network: [${network}]`));
       }
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
+
+      const projectPath = pathJoin(process.cwd(), 'src', dubheConfig.name);
+      const lintResults = lintSystemGuards(projectPath);
+      if (lintResults.length > 0) {
+        process.stdout.write(formatLintWarnings(lintResults));
+        const proceed = await confirm(
+          'Some entry functions are missing ensure_latest_version. Proceed with publish anyway?'
+        );
+        if (!proceed) {
+          console.log(chalk.red('Publish cancelled.'));
+          handlerExit(1);
+          return;
+        }
+      }
+
       execSync(`pnpm dubhe convert-json --config-path ${configPath}`, { encoding: 'utf-8' });
       await publishHandler(dubheConfig, network, force, gasBudget);
     } catch (error: any) {

package/src/commands/test.ts

@@ -2,6 +2,7 @@ import type { CommandModule } from 'yargs';
 import { execFileSync, execSync } from 'child_process';
 import { DubheConfig, loadConfig } from '@0xobelisk/sui-common';
 import { handlerExit } from './shell';
+import { lintSystemGuards, formatLintWarnings } from '../utils';
 
 /**
  * Returns the active Sui client environment (e.g. "localnet", "testnet").
@@ -135,6 +136,11 @@ const commandModule: CommandModule<CliOptions, CliOptions> = {
       console.log(list ? '🚀 Listing Move unit tests' : '🚀 Running move test');
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
 
+      const projectPath = `${process.cwd()}/src/${dubheConfig.name}`;
+      const lintResults = lintSystemGuards(projectPath);
+      const warnings = formatLintWarnings(lintResults);
+      if (warnings) process.stdout.write(warnings);
+
       const activeEnv = getActiveSuiEnv();
       const buildEnv = activeEnv === 'localnet' || activeEnv === 'devnet' ? 'testnet' : undefined;
 

package/src/commands/upgrade.ts

@@ -3,12 +3,14 @@ import { logError } from '../utils/errors';
 import { upgradeHandler } from '../utils/upgradeHandler';
 import { DubheConfig, loadConfig } from '@0xobelisk/sui-common';
 import { handlerExit } from './shell';
-import { getDefaultNetwork } from '../utils';
+import { getDefaultNetwork, lintSystemGuards, formatLintWarnings, confirm } from '../utils';
+import { join as pathJoin } from 'path';
 import chalk from 'chalk';
 
 type Options = {
   network: any;
   'config-path': string;
+  'bump-version': boolean;
 };
 
 const commandModule: CommandModule<Options, Options> = {
@@ -28,18 +30,38 @@ const commandModule: CommandModule<Options, Options> = {
         type: 'string',
         default: 'dubhe.config.ts',
         decs: 'Path to the config file'
+      },
+      'bump-version': {
+        type: 'boolean',
+        default: false,
+        desc: 'Force a version bump even when no new resources were added (use for breaking logic changes or security fixes that must invalidate old clients)'
       }
     });
   },
 
-  async handler({ network, 'config-path': configPath }) {
+  async handler({ network, 'config-path': configPath, 'bump-version': bumpVersion }) {
     try {
       if (network == 'default') {
         network = await getDefaultNetwork();
         console.log(chalk.yellow(`Use default network: [${network}]`));
       }
       const dubheConfig = (await loadConfig(configPath)) as DubheConfig;
-      await upgradeHandler(dubheConfig, dubheConfig.name, network);
+
+      const projectPath = pathJoin(process.cwd(), 'src', dubheConfig.name);
+      const lintResults = lintSystemGuards(projectPath);
+      if (lintResults.length > 0) {
+        process.stdout.write(formatLintWarnings(lintResults));
+        const proceed = await confirm(
+          'Some entry functions are missing ensure_latest_version. Proceed with upgrade anyway?'
+        );
+        if (!proceed) {
+          console.log(chalk.red('Upgrade cancelled.'));
+          handlerExit(1);
+          return;
+        }
+      }
+
+      await upgradeHandler(dubheConfig, dubheConfig.name, network, bumpVersion);
     } catch (error: any) {
       logError(error);
       handlerExit(1);

package/src/utils/publishHandler.ts

@@ -493,6 +493,7 @@ async function publishContract(
       network,
       startCheckpoint,
       packageId,
+      packageId, // originalPackageId: first publish, so original == current
       frameworkDappHubId,
       upgradeCapId,
       version,
@@ -517,6 +518,10 @@ async function publishContract(
     config.original_dubhe_package_id =
       dubheConfig.name === 'dubhe' ? packageId : await getOriginalDubhePackageId(network);
     config.start_checkpoint = startCheckpoint;
+    // Canonical dapp_key type string: stable across upgrades, no "0x" prefix, padded to 64 hex chars.
+    // Matches the Move type_name::with_defining_ids<DappKey>().into_string() format.
+    const pkgHex = packageId.replace(/^0x/i, '').padStart(64, '0');
+    config.dapp_key = `${pkgHex}::dapp_key::DappKey`;
     // Persist the DappStorage object ID so store-config can include it in deployment.ts
     // and upgrade transactions can reference it without reading from .history.
     if (dappStorageId) {
@@ -601,8 +606,6 @@ export async function publishDubheFramework(
 
   let modules: any, dependencies: any;
   try {
-    // For localnet: use --build-env testnet (no pubfile needed — dubhe has no local deps).
-    // For testnet/mainnet: use -e <network> as usual.
     [modules, dependencies] = buildContract(projectPath, network);
   } finally {
     // Always restore Published.toml and Move.toml (successful build or error)
@@ -683,6 +686,7 @@ export async function publishDubheFramework(
     network,
     startCheckpoint,
     packageId,
+    packageId, // originalPackageId: first publish, original == current
     dappHubId,
     upgradeCapId,
     version,

package/src/utils/storeConfig.ts

@@ -3,9 +3,19 @@ import { dirname } from 'path';
 import { DubheConfig } from '@0xobelisk/sui-common';
 import { getDeploymentJson, getDubheDappHubId, getOriginalDubhePackageId } from './utils';
 
+/** Derive the stable dapp_key type string from the original (genesis) package ID.
+ *  Matches the Move-side `type_name::with_defining_ids<DappKey>().into_string()` output:
+ *  "<hex64>::dapp_key::DappKey"  (no "0x" prefix, address zero-padded to 64 hex chars).
+ */
+function buildDappKey(originalPackageId: string): string {
+  const hex = originalPackageId.replace(/^0x/i, '').padStart(64, '0');
+  return `${hex}::dapp_key::DappKey`;
+}
+
 async function storeConfig(
   network: string,
   packageId: string,
+  originalPackageId: string,
   dappStorageId: string,
   outputPath: string
 ) {
@@ -25,10 +35,16 @@ async function storeConfig(
       ? `\n// Published package ID of the dubhe framework — required for proxy operations.\nexport const FrameworkPackageId: string | undefined = '${frameworkPackageId}';\n`
       : `\n// Published package ID of the dubhe framework — required for proxy operations.\n// For testnet/mainnet the SDK resolves this automatically via getDefaultConfig().\nexport const FrameworkPackageId: string | undefined = undefined;\n`;
 
+  const dappKey = buildDappKey(originalPackageId);
+
   const code = `type NetworkType = 'testnet' | 'mainnet' | 'devnet' | 'localnet';
 
 export const Network: NetworkType = '${network}';
 export const PackageId = '${packageId}';
+/** The first-published (original) package ID — stable across upgrades. Used for dapp_key and indexer filtering. */
+export const OriginalPackageId = '${originalPackageId}';
+/** Canonical dapp_key type string derived from OriginalPackageId. Pass to the Dubhe SDK and GraphQL queries. */
+export const DappKey = '${dappKey}';
 export const DappHubId = '${dappHubId}';
 export const DappStorageId = '${dappStorageId}';
 ${frameworkIdLine}`;
@@ -57,9 +73,13 @@ export async function storeConfigHandler(
   const path = process.cwd();
   const contractPath = `${path}/src/${dubheConfig.name}`;
   const deployment = await getDeploymentJson(contractPath, network);
+  // Prefer the persisted originalPackageId; fall back to packageId for old deployments
+  // that were created before this field was introduced.
+  const originalPackageId = deployment.originalPackageId ?? deployment.packageId;
   await storeConfig(
     deployment.network,
     deployment.packageId,
+    originalPackageId,
     deployment.dappStorageId ?? '',
     outputPath
   );

package/src/utils/upgradeHandler.ts

@@ -75,7 +75,8 @@ function replaceEnvField(
 export async function upgradeHandler(
   config: DubheConfig,
   name: string,
-  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  bumpVersion: boolean = false
 ) {
   await switchEnv(network);
 
@@ -103,13 +104,15 @@ export async function upgradeHandler(
   });
 
   const tables = pendingMigration.map((migration) => migration.name);
-  // When new resources are detected, generate the migrate_to_vN entry function in
-  // migrate.move so the on-chain migration transaction can register the new package
-  // ID and version via dapp_system::upgrade_dapp.
-  // Note: the current framework stores data as dynamic fields and does NOT use
-  // register_table; genesis::migrate() is intentionally left empty and is called
-  // from migrate_to_vN solely to keep the extension point for future use.
-  if (tables.length > 0) {
+  // Trigger migration when new resources were detected (schema change) OR when the
+  // caller explicitly requested a version bump (--bump-version flag). The latter
+  // covers breaking logic changes and security fixes that must invalidate old clients
+  // even though no new resources were added.
+  const needsMigration = tables.length > 0 || bumpVersion;
+  if (needsMigration) {
+    if (bumpVersion && tables.length === 0) {
+      console.log(chalk.yellow('--bump-version: forcing version bump with no schema changes.'));
+    }
     appendMigrateFunction(projectPath, config.name, oldVersion + 1);
   }
 
@@ -278,6 +281,7 @@ export async function upgradeHandler(
       network,
       startCheckpoint,
       newPackageId,
+      original_published_id, // originalPackageId: stable across all upgrades
       dappHubId,
       upgradeCap,
       oldVersion + 1,
@@ -287,16 +291,26 @@ export async function upgradeHandler(
       dappStorageId || undefined
     );
 
-    // Only run the migration transaction if there are pending schema changes.
-    // A "bug-fix" upgrade with no new fields does not need a migration call.
-    // The migrate_to_vX function is only generated by `dubhe generate` when
-    // new components / resources are added.
-    if (pendingMigration.length > 0) {
-      console.log(`\n🚀 Starting Migration Process...`);
-      pendingMigration.forEach((migration) => {
-        console.log('📋 Added Fields:', JSON.stringify(migration, null, 2));
-      });
-      await new Promise((resolve) => setTimeout(resolve, 5000));
+    // Only run the migration transaction if there are pending schema changes or a
+    // forced version bump was requested via --bump-version.
+    // A pure "bug-fix" upgrade with no new fields and no --bump-version flag does
+    // not need a migration call — old and new package can coexist safely.
+    if (needsMigration) {
+      if (pendingMigration.length > 0) {
+        console.log(`\n🚀 Starting Migration Process...`);
+        pendingMigration.forEach((migration) => {
+          console.log('📋 Added Fields:', JSON.stringify(migration, null, 2));
+        });
+      } else {
+        console.log(`\n🚀 Starting Migration Process (forced version bump)...`);
+      }
+
+      // On localnet the indexer may lag behind the chain; give it time to register
+      // the newly upgraded package before the migration transaction references it.
+      // On testnet/mainnet the validator processes state immediately — no delay needed.
+      if (network === 'localnet') {
+        await new Promise((resolve) => setTimeout(resolve, 5000));
+      }
 
       if (!dappStorageId) {
         console.warn(
@@ -314,8 +328,7 @@ export async function upgradeHandler(
         arguments: [
           migrateTx.object(dappHubId),
           migrateTx.object(dappStorageId),
-          migrateTx.pure.address(newPackageId),
-          migrateTx.pure.u32(newVersion)
+          migrateTx.pure.address(newPackageId)
         ]
       });
 
@@ -335,7 +348,9 @@ export async function upgradeHandler(
       console.log(`\n✅ No schema changes — migration step skipped.`);
       // Brief delay to allow localnet to index the upgraded package before
       // subsequent on-chain queries.
-      await new Promise((resolve) => setTimeout(resolve, 2000));
+      if (network === 'localnet') {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+      }
     }
   } catch (error: any) {
     // Restore Published.toml to original state on failure (persistent networks only)