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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xobelisk/sui-common",
-  "version": "1.2.0-pre.99",
+  "version": "2.0.0",
   "description": "Common low level logic shared between packages",
   "keywords": [
     "sui",
@@ -31,19 +31,6 @@
       ]
     }
   },
-  "scripts": {
-    "build": "pnpm run type-check && pnpm run build:js",
-    "build:js": "tsup && chmod +x ./dist/index.js",
-    "clean": "pnpm run clean:js",
-    "clean:js": "rimraf dist",
-    "dev": "tsup --watch",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint . --ext .ts",
-    "test": "vitest",
-    "type-check": "tsc --noEmit",
-    "validate": "pnpm format:check && pnpm type-check"
-  },
   "dependencies": {
     "chalk": "^5.0.1",
     "debug": "^4.3.4",
@@ -56,8 +43,6 @@
     "path": "^0.12.7",
     "prettier": "^3.1.1",
     "prettier-plugin-move-js": "^0.0.5",
-    "prettier-plugin-rust": "^0.1.9",
-    "prettier-plugin-solidity": "^1.1.2",
     "typescript": "^5.8.3",
     "yargs": "^17.7.1",
     "zod": "^3.22.3",
@@ -81,5 +66,18 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run type-check && pnpm run build:js",
+    "build:js": "tsup && chmod +x ./dist/index.js",
+    "clean": "pnpm run clean:js",
+    "clean:js": "rimraf dist",
+    "dev": "tsup --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . --ext .ts",
+    "test": "vitest",
+    "type-check": "tsc --noEmit",
+    "validate": "pnpm format:check && pnpm type-check"
   }
-}
+}

package/src/codegen/debug.ts

@@ -1,10 +1,6 @@
 import { debug as parentDebug } from '../debug';
 
 export const debug = parentDebug.extend('codegen');
-export const error = parentDebug.extend('codegen');
 
 // Pipe debug output to stdout instead of stderr
 debug.log = console.debug.bind(console);
-
-// Pipe error output to stderr
-error.log = console.error.bind(console);

package/src/codegen/types/index.ts

@@ -19,33 +19,69 @@ export type MoveType =
   | 'vector<u256>'
   | string;
 
-// Define the type of Schema
 export type Component = {
   offchain?: boolean;
+  global?: boolean;
   fields: Record<string, MoveType>;
   keys?: string[];
+  // Storage extension annotations
+  reactive?: boolean; // generate _reactive cross-user write variants
+  fungible?: boolean; // generate add/sub instead of set
+  transferable?: boolean; // generate cross-layer transfer functions
+  listable?: boolean; // generate list/buy/cancel_listing/expire_listing
 };
 
-// Empty object type, used to represent components with only id key
-export type EmptyComponent = Record<string, never>;
+/** Config for a DApp-owned named shared object (e.g. guild, boss). */
+export type ObjectConfig = {
+  fields: Record<string, MoveType>;
+  /** Resources (from the `resources` section) this object accepts for transfers. */
+  accepts?: string[];
+  /** Other objects/scenes whose data can be transferred into this object. */
+  acceptsFrom?: string[];
+  /** If true, only the DApp admin can call create_<key>. */
+  adminOnly?: boolean;
+};
+
+/** Config for a standalone ScenePermit (participant management only). */
+export type PermitConfig = {
+  // Reserved for future permit-level options.
+};
+
+export type SceneAuthorization = { kind: 'permit'; permit: string } | { kind: 'system' };
+
+/** Config for a SceneStorage object (pure data storage, symmetric to ObjectConfig). */
+export type SceneConfig = {
+  fields: Record<string, MoveType>;
+  /** Resources this scene accepts for transfers. */
+  accepts?: string[];
+  /** Other objects/scenes whose data can be transferred into this scene. */
+  acceptsFrom?: string[];
+  /** Explicit write authorization model for this SceneStorage. */
+  authorization: SceneAuthorization;
+};
+
+export type ErrorDefinition = {
+  message: string;
+};
+
+export type ErrorEntry = string | ErrorDefinition;
 
 export type DubheConfig = {
   name: string;
   description: string;
   enums?: Record<string, string[]>;
-  components: Record<string, Component | MoveType | EmptyComponent>;
-  resources: Record<string, Component | MoveType>;
-  errors?: Record<string, string>;
+  resources?: Record<string, Component | MoveType>;
+  objects?: Record<string, ObjectConfig>;
+  permits?: Record<string, PermitConfig>;
+  scenes?: Record<string, SceneConfig>;
+  errors?: Record<string, ErrorEntry>;
 };
 
 export type DubheMetadata = {
-  components: Record<string, Component | MoveType | EmptyComponent>;
   resources: Record<string, Component | MoveType>;
   enums: Record<string, string[]>;
 };
 
 export type BaseType = any;
-export type ErrorData = any;
+export type ErrorData = Record<string, ErrorEntry>;
 export type EventData = any;
-export type SchemaData = any;
-export type SchemaType = any;

package/src/codegen/utils/config.ts

@@ -34,7 +34,7 @@ export async function loadConfig(configPath?: string): Promise<unknown> {
   }
 }
 
-export async function resolveConfigPath(configPath: string | undefined, toFileURL?: boolean) {
+async function resolveConfigPath(configPath: string | undefined, toFileURL?: boolean) {
   if (configPath === undefined) {
     configPath = await getUserConfigPath();
   } else {

package/src/codegen/utils/format.ts

@@ -28,9 +28,3 @@ export async function formatMove(content: string, prettierConfigPath?: string):
     return content;
   }
 }
-
-export async function formatTypescript(content: string): Promise<string> {
-  return prettier.format(content, {
-    parser: 'typescript'
-  });
-}

package/src/codegen/utils/formatAndWrite.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { formatTypescript } from './format';
 import { debug } from '../debug';
 
 export async function formatAndWriteMove(
@@ -9,19 +8,18 @@ export async function formatAndWriteMove(
   logPrefix?: string
 ): Promise<void> {
   const formattedOutput = output;
-  let schemaPrefix = `  // Copyright (c) Obelisk Labs, Inc.
-  // SPDX-License-Identifier: Apache-2.0
-  #[allow(unused_use)]
-  
-  /* Autogenerated file. Do not edit manually. */
-  
-  `;
+  const fileHeader = `// Copyright (c) Obelisk Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
 
-  let initPrefix = `#[test_only]`;
+/* Autogenerated file. Do not edit manually. */
 
-  let code = schemaPrefix + formattedOutput;
+`;
 
-  let deployHookPrefix = `#[allow(lint(share_owned))]`;
+  const initPrefix = `#[test_only]\n`;
+
+  let code = fileHeader + formattedOutput;
+
+  const deployHookPrefix = `#[allow(lint(share_owned))]\n`;
 
   if (
     fullOutputPath.includes('.toml') ||
@@ -29,7 +27,7 @@ export async function formatAndWriteMove(
     fullOutputPath.includes('migrate')
   ) {
     code = formattedOutput;
-  } else if (fullOutputPath.includes('init')) {
+  } else if (fullOutputPath.includes('init_test')) {
     code = initPrefix + formattedOutput;
   } else if (fullOutputPath.includes('genesis')) {
     code = deployHookPrefix + formattedOutput;
@@ -39,22 +37,3 @@ export async function formatAndWriteMove(
   await fs.writeFile(fullOutputPath, code);
   debug(`${logPrefix}: ${fullOutputPath}`);
 }
-
-/**
- * Formats typescript code using prettier and write it to a file
- * @param output typescript code
- * @param fullOutputPath full path to the output file
- * @param logPrefix prefix for debug logs
- */
-export async function formatAndWriteTypescript(
-  output: string,
-  fullOutputPath: string,
-  logPrefix: string
-): Promise<void> {
-  const formattedOutput = await formatTypescript(output);
-
-  await fs.mkdir(path.dirname(fullOutputPath), { recursive: true });
-
-  await fs.writeFile(fullOutputPath, formattedOutput);
-  debug(`${logPrefix}: ${fullOutputPath}`);
-}

package/src/codegen/utils/generateLock.ts

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+import { DubheConfig, Component, MoveType } from '../types';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import path from 'node:path';
+
+/** Snapshot of field definitions for a single resource/object/scene. */
+type FieldSnapshot = Record<string, string>;
+
+/** Top-level structure of a dubhe.lock.json file. */
+interface DubheLock {
+  version: 1;
+  resources: Record<string, FieldSnapshot>;
+  objects: Record<string, FieldSnapshot>;
+  scenes: Record<string, FieldSnapshot>;
+}
+
+/** Extract the field map for a resource entry (handles both shorthand and full form). */
+function resourceFields(entry: Component | MoveType): FieldSnapshot {
+  if (typeof entry === 'string') {
+    return { value: entry };
+  }
+  const fields: FieldSnapshot = {};
+  for (const [k, v] of Object.entries(entry.fields ?? {})) {
+    fields[k] = v as string;
+  }
+  return fields;
+}
+
+/** Extract the field map for an object or scene entry. */
+function objectOrSceneFields(entry: { fields: Record<string, MoveType> }): FieldSnapshot {
+  const fields: FieldSnapshot = {};
+  for (const [k, v] of Object.entries(entry.fields)) {
+    fields[k] = v as string;
+  }
+  return fields;
+}
+
+/** Build a full DubheLock snapshot from a DubheConfig. */
+function buildLock(config: DubheConfig): DubheLock {
+  const resources: Record<string, FieldSnapshot> = {};
+  for (const [name, entry] of Object.entries(config.resources ?? {})) {
+    resources[name] = resourceFields(entry);
+  }
+
+  const objects: Record<string, FieldSnapshot> = {};
+  for (const [name, entry] of Object.entries(config.objects ?? {})) {
+    objects[name] = objectOrSceneFields(entry);
+  }
+
+  const scenes: Record<string, FieldSnapshot> = {};
+  for (const [name, entry] of Object.entries(config.scenes ?? {})) {
+    scenes[name] = objectOrSceneFields(entry);
+  }
+
+  return { version: 1, resources, objects, scenes };
+}
+
+type SectionName = 'resources' | 'objects' | 'scenes';
+
+/** Compare old vs new field snapshots and throw on breaking changes. */
+function checkSection(
+  section: SectionName,
+  oldSection: Record<string, FieldSnapshot>,
+  newSection: Record<string, FieldSnapshot>
+): void {
+  for (const [name, newFields] of Object.entries(newSection)) {
+    const oldFields = oldSection[name];
+    if (!oldFields) continue; // New entry — allowed.
+
+    for (const [field, oldType] of Object.entries(oldFields)) {
+      if (!(field in newFields)) {
+        throw new Error(
+          `[dubhe] Breaking change detected in ${section}.${name}:\n` +
+            `  Field "${field}" was removed.\n\n` +
+            `Resources, objects, and scenes are stored as raw bytes on-chain.\n` +
+            `Removing fields corrupts existing data. Use a new name (e.g. "${name}_v2") for breaking changes.`
+        );
+      }
+      if (newFields[field] !== oldType) {
+        throw new Error(
+          `[dubhe] Breaking change detected in ${section}.${name}:\n` +
+            `  Field "${field}" type changed from "${oldType}" to "${newFields[field]}".\n\n` +
+            `Resources, objects, and scenes are stored as raw bytes on-chain.\n` +
+            `Changing field types corrupts existing data. Use a new name (e.g. "${name}_v2") for breaking changes.`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Read the existing lock file (if any), check for breaking changes against the
+ * current config, then write an updated lock file.
+ *
+ * Call this at the start of `codegen()` before any file generation begins.
+ *
+ * @param rootDir  The project root directory (same dir passed to `codegen()`).
+ * @param config   The parsed DubheConfig.
+ */
+export function checkAndUpdateLock(rootDir: string, config: DubheConfig): void {
+  const lockPath = path.join(rootDir, `${config.name}.lock.json`);
+  const newLock = buildLock(config);
+
+  if (existsSync(lockPath)) {
+    let oldLock: DubheLock;
+    try {
+      oldLock = JSON.parse(readFileSync(lockPath, 'utf-8')) as DubheLock;
+    } catch {
+      console.warn(
+        chalk.yellow('[dubhe]') + ` Could not parse ${chalk.bold(lockPath)}, skipping break-check.`
+      );
+      writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n', 'utf-8');
+      return;
+    }
+
+    checkSection('resources', oldLock.resources ?? {}, newLock.resources);
+    checkSection('objects', oldLock.objects ?? {}, newLock.objects);
+    checkSection('scenes', oldLock.scenes ?? {}, newLock.scenes);
+  }
+
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n', 'utf-8');
+}

package/src/codegen/utils/index.ts

@@ -1,6 +1,8 @@
 export * from './format';
 export * from './formatAndWrite';
-export * from './posixPath';
-export * from './renderMove/schemaGen';
+export * from './renderMove/codegen';
 export * from './renderMove/dapp';
+export * from './renderMove/generateObjects';
+export * from './renderMove/generateScenes';
 export * from './config';
+export * from './generateLock';

package/src/codegen/utils/renderMove/{schemaGen.ts → codegen.ts}

@@ -1,33 +1,43 @@
 import { DubheConfig } from '../../types';
 import { existsSync } from 'fs';
-// import { rmdirSync } from 'fs'; // Unused
 import { deleteFolderRecursive } from './common';
 import { generateToml } from './generateToml';
-// import { generateSchemaData, generateSchemaStructure } from './generateSchema';
 import { generateDeployHook, generateMigrate } from './generateScript';
 import { generateDappKey } from './generateDappKey';
-// import { generateSchemaEvent } from // Unused './generateEvent';
 import { generateSystemsAndTests } from './generateSystem';
-// import { generateSchemaHub } from // Unused './generateSchemaHub';
-import { generateSchemaError } from './generateError';
-// import { generateDefaultSchema } from // Unused './generateDefaultSchema';
+import { generateError } from './generateError';
 import { generateInitTest } from './generateInitTest';
-import { generateComponents } from './generateComponents';
 import { generateGenesis } from './generateGenesis';
 import { generateEnums } from './generateEnums';
 import { generateResources } from './generateResources';
+import { generateObjects } from './generateObjects';
+import { generatePermits } from './generatePermits';
+import { generateScenes } from './generateScenes';
+import { generateUserStorageInit } from './generateUserStorageInit';
+import { checkAndUpdateLock } from '../generateLock';
+import { validateConfig } from '../validateConfig';
 import path from 'node:path';
 
-export async function schemaGen(
+export async function codegen(
   rootDir: string,
   config: DubheConfig,
-  network?: 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+  network?: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  initialMode: 0 | 1 = 1
 ) {
-  console.log('\n🚀 Starting Schema Generation Process...');
+  console.log('\n🚀 Starting Code Generation Process...');
   console.log('📋 Project Configuration:');
   console.log(`     └─ Name: ${config.name}`);
   console.log(`     └─ Description: ${config.description || 'No description provided'}`);
   console.log(`     └─ Network: ${network || 'testnet'}`);
+  console.log(`     └─ Settlement Mode: ${initialMode === 1 ? 'USER_PAYS' : 'DAPP_SUBSIDIZES'}`);
+
+  // Validate config once here — defineConfig also validates on load, but that
+  // is the same process call, so we suppress duplicates by making this the
+  // single codegen-phase validation point.
+  validateConfig(config);
+
+  // Check for breaking field changes and update the lock file.
+  checkAndUpdateLock(rootDir, config);
 
   console.log(rootDir);
   const projectDir = path.join(rootDir, 'src', config.name);
@@ -42,7 +52,7 @@ export async function schemaGen(
 
   const genesisPath = path.join(projectDir, 'sources', 'codegen', 'genesis.move');
   if (!existsSync(genesisPath)) {
-    await generateGenesis(config, genesisPath);
+    await generateGenesis(config, genesisPath, initialMode);
   }
 
   const initTestPath = path.join(projectDir, 'sources', 'codegen', 'init_test.move');
@@ -57,22 +67,20 @@ export async function schemaGen(
 
   const deployHookPath = path.join(projectDir, 'sources', 'scripts', 'deploy_hook.move');
   if (!existsSync(deployHookPath)) {
-    await generateDeployHook(config, deployHookPath);
-  }
-
-  const componentsPath = path.join(projectDir, 'sources', 'codegen', 'components');
-  if (!existsSync(componentsPath)) {
-    await generateComponents(config, componentsPath);
-  } else {
-    await generateComponents(config, componentsPath);
+    await generateDeployHook(config, deployHookPath, initialMode);
   }
 
   const resourcesPath = path.join(projectDir, 'sources', 'codegen', 'resources');
-  if (!existsSync(resourcesPath)) {
-    await generateResources(config, resourcesPath);
-  } else {
-    await generateResources(config, resourcesPath);
-  }
+  await generateResources(config, resourcesPath);
+
+  const objectsPath = path.join(projectDir, 'sources', 'codegen', 'objects');
+  await generateObjects(config, objectsPath);
+
+  const permitsPath = path.join(projectDir, 'sources', 'codegen', 'permits');
+  await generatePermits(config, permitsPath);
+
+  const scenesPath = path.join(projectDir, 'sources', 'codegen', 'scenes');
+  await generateScenes(config, scenesPath);
 
   const enumsPath = path.join(projectDir, 'sources', 'codegen', 'enums');
   if (!existsSync(enumsPath)) {
@@ -80,12 +88,16 @@ export async function schemaGen(
   }
 
   if (config.errors) {
-    await generateSchemaError(config.name, config.errors, rootDir);
+    await generateError(config.name, config.errors, rootDir);
   }
 
-  // await generateDefaultSchema(config, rootDir);
-  // await generateInit(config, rootDir);
+  const userStorageInitPath = path.join(projectDir, 'sources', 'codegen', 'user_storage_init.move');
+  await generateUserStorageInit(config, userStorageInitPath);
+
   await generateSystemsAndTests(config, rootDir);
   await generateMigrate(config, rootDir);
-  console.log('\n✅  Schema Generation Process Complete!\n');
+  console.log('\n✅  Code Generation Complete!\n');
 }
+
+/** @deprecated Use `codegen` instead. */
+export const schemaGen = codegen;

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

@@ -1,4 +1,3 @@
-// import { MoveType } from '../../types'; // Unused
 import fs from 'fs';
 
 export function deleteFolderRecursive(path: string) {
@@ -14,67 +13,3 @@ export function deleteFolderRecursive(path: string) {
     fs.rmdirSync(path);
   }
 }
-
-export function capitalizeFirstLetter(input: string): string {
-  return input.charAt(0).toUpperCase() + input.slice(1);
-}
-
-/**
- *
- * @param values
- * @param prefixArgs
- * @return [ name, age, birth_time ]
- */
-export function getStructAttrs(values: Record<string, string> | string): string {
-  return Object.entries(values)
-    .map(([key, _]) => `${key}`)
-    .join(',');
-}
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function isAddress(str: string): boolean {
-  const regex = /^0x[a-fA-F0-9]+$/;
-  return regex.test(str);
-}
-
-/**
- *
- * @param values
- * @return ( bool , u64 , u64)
- */
-// export function getStructTypes(values: SchemaType): string {
-export function getStructTypes(values: Record<string, string>): string {
-  return `(${Object.entries(values).map(([_, type]) => `${type}`)})`;
-}
-
-/**
- *
- * @param values
- * @return Attributes and types of the struct. [ name: string, age: u64 ]
- */
-export function getStructAttrsWithType(values: Record<string, string>): string[] {
-  return Object.entries(values).map(([key, type]) => `${key}: ${type}`);
-}
-
-/**
- * @param values
- * @return [ data.name, data.age ]
- */
-export function getStructAttrsQuery(values: Record<string, string>): string[] {
-  return Object.entries(values).map(([key, _]) => `self.${key}`);
-}
-
-export function containsString(obj: Record<string, any>, searchString: string): boolean {
-  for (const key in obj) {
-    if (obj.hasOwnProperty(key)) {
-      const value = obj[key];
-      if (
-        (typeof value === 'string' && value === searchString) ||
-        (typeof value === 'string' && value.includes(searchString) && value.includes('>'))
-      ) {
-        return true;
-      }
-    }
-  }
-  return false;
-}

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

@@ -1,19 +1,7 @@
 import { DubheConfig } from '../../types';
-
-const checkDuplicateKeys = (config: DubheConfig): void => {
-  const componentKeys = Object.keys(config.components || {});
-  const resourceKeys = Object.keys(config.resources || {});
-
-  const duplicates = componentKeys.filter((key) => resourceKeys.includes(key));
-
-  if (duplicates.length > 0) {
-    throw new Error(
-      `Duplicate keys found between components and resources: ${duplicates.join(', ')}`
-    );
-  }
-};
+import { validateConfigErrors } from '../validateConfig';
 
 export const defineConfig = (config: DubheConfig): DubheConfig => {
-  checkDuplicateKeys(config);
+  validateConfigErrors(config);
   return config;
 };

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

@@ -3,30 +3,45 @@ import { formatAndWriteMove } from '../formatAndWrite';
 
 export async function generateDappKey(config: DubheConfig, path: string) {
   let code = `module ${config.name}::dapp_key {
-use std::type_name;
-  use sui::address;
-  use std::ascii::String;
+    use std::type_name;
+    use sui::address;
+    use std::ascii::String;
 
-  /// Authorization token for the app.
+    /// DappKey — package-level authorization token for this DApp.
+    ///
+    /// SECURITY: \`new()\` is intentionally \`public(package)\`.
+    /// Only code compiled into this package can construct a DappKey instance.
+    /// All framework write functions (\`set_record\`, \`set_field\`,
+    /// \`take_record\`, \`create_user_storage\`, …) require \`_auth: DappKey\`
+    /// as proof that the call originated from inside this package — an
+    /// external PTB cannot fabricate that proof.
+    ///
+    /// NEVER change \`new()\` to \`public\`, and never accept a DappKey
+    /// value as a parameter from an external caller.  Either mistake removes
+    /// every package-level access guard, allowing any PTB to write arbitrary
+    /// user data or register UserStorages without going through the DApp's
+    /// own entry functions.
 
-  public struct DappKey has copy, drop {}
+    public struct DappKey has copy, drop {}
 
-  public(package) fun new(): DappKey {
-    DappKey {  }
-  }
+    /// Constructs an authorization token. Callable only from within this package.
+    /// Pass the result as \`_auth\` to any framework function that requires it.
+    public(package) fun new(): DappKey {
+        DappKey {}
+    }
 
-  public fun to_string(): String {
-    type_name::get<DappKey>().into_string()
-  }
+    public fun to_string(): String {
+        type_name::with_defining_ids<DappKey>().into_string()
+    }
 
-  public fun package_id(): address {
-    let package_id_str = type_name::get<DappKey>().get_address();
-    address::from_ascii_bytes(package_id_str.as_bytes())
-  }
+    public fun package_id(): address {
+        let package_id_str = type_name::with_defining_ids<DappKey>().address_string();
+        address::from_ascii_bytes(package_id_str.as_bytes())
+    }
 
-  public fun eq<DappKey1: copy + drop, DappKey2: copy + drop>(_: &DappKey1, _: &DappKey2): bool {
-    type_name::get<DappKey1>() == type_name::get<DappKey2>()
-  }
+    public fun eq<DappKey1: copy + drop, DappKey2: copy + drop>(_: &DappKey1, _: &DappKey2): bool {
+        type_name::with_defining_ids<DappKey1>() == type_name::with_defining_ids<DappKey2>()
+    }
 }
 `;
   await formatAndWriteMove(code, path, 'formatAndWriteMove');