@zktx.io/sui-move-builder

Upstream source: MystenLabs/sui (see sui-version.json)

Build Move packages in web or Node.js with Sui CLI-compatible dependency resolution and compilation.

Features

• ✅ Sui CLI Compatible: Identical dependency resolution algorithm as Sui CLI
• ✅ Verified Parity: Audited against sui-04dd source code (Jan 2026), byte-level module comparison
• ✅ Address Resolution: Supports original_id for compilation, published_at for metadata (CLI-identical)
• ✅ Lockfile Support: Reads Move.lock v0/v3/v4 for faster, deterministic builds
• ✅ Move.lock V4 Output: Generates V4 format with CLI-compatible lexicographical sorting and manifest_digest
• ✅ Published.toml Support: Reads deployment records per environment
• ✅ Per-Package Editions: Each package can use its own Move edition (legacy, 2024.alpha, 2024.beta)
• ✅ Monorepo Support: Handles local dependencies in monorepo structures
• ✅ Version Conflict Detection: Matches Sui CLI behavior for conflicting dependency versions
• ✅ Browser & Node.js: Works in both environments with WASM-based compilation
• ✅ GitHub Integration: Fetches dependencies directly from git repositories
• ✅ GitHub Token Support: Optional token to raise rate limits (API calls only; raw fetch remains CORS-safe)

📖 For detailed CLI behavior documentation, see CLI_PIPELINE.md

Install

npm install @zktx.io/sui-move-builder

Lite vs Full Version

The package comes in two variants:

1. Full Version (Default): ~12MB. Includes move-unit-test, sui-move-natives, and testing capabilities.
2. Lite Version: ~5.1MB. Build-only. Recommended for frontend applications where testing infrastructure is not needed.

Using the Full Version (Default)

import {
  initMoveCompiler,
  buildMovePackage,
  testMovePackage,
} from "@zktx.io/sui-move-builder";

Using the Lite Version

import {
  initMoveCompiler,
  buildMovePackage,
} from "@zktx.io/sui-move-builder/lite";

Quick start (Node.js or browser)

import { initMoveCompiler, buildMovePackage } from "@zktx.io/sui-move-builder";

// 1) Load the WASM once
await initMoveCompiler();

// 2) Prepare files as an in-memory folder (Move.toml + sources/*)
const files = {
  "Move.toml": `
[package]
name = "hello_world"
version = "0.0.1"

[addresses]
hello_world = "0x0"
`,
  "sources/hello_world.move": `
module hello_world::hello_world {
  // your code...
}
`,
};

// 3) Compile
const result = await buildMovePackage({
  files,
  // optional: bump GitHub API limits during dependency resolution
  githubToken: process.env.GITHUB_TOKEN,
  // optional: silence warnings from Move compiler (default: false)
  silenceWarnings: false,
  // optional: enable test mode (include #[test_only] modules)
  testMode: false,
  // optional: set linting level (default: "all")
  lintFlag: "all",
});

if (result.success) {
  // Compilation outputs
  console.log("Modules:", result.modules); // Array<string>: Base64-encoded bytecode
  console.log("Dependencies:", result.dependencies); // Array<string>: Hex-encoded package IDs
  console.log("Digest:", result.digest); // Array<number>: Package digest bytes

  // Lockfile outputs
  console.log("Move.lock:", result.moveLock); // string: V4 lockfile content (CLI-compatible)
  console.log("Environment:", result.environment); // string: e.g., "mainnet"

  // Migration output (V3 → V4)
  if (result.publishedToml) {
    console.log("Published.toml:", result.publishedToml); // string: Migrated from legacy Move.lock
  }

  // Warnings (if silenceWarnings: false)
  if (result.warnings) {
    console.warn("Warnings:", result.warnings);
  }
} else {
  console.error("Build failed:", result.error);
}

Running Tests

You can run Move unit tests using the testMovePackage function (available in the full version).

import { testMovePackage } from "@zktx.io/sui-move-builder";

const result = await testMovePackage({
  files,
  network: "mainnet",
});

if ("error" in result) {
  console.error("Test failed to run:", result.error);
} else {
  console.log("Tests Passed:", result.passed);
  console.log("Output:", result.output);
}

Build Options (BuildInput)

Option	Type	Description
files	Record<string, string>	Required. Virtual file system with Move.toml and sources
network	"mainnet" | "testnet" | "devnet"	Network environment (default: "mainnet")
githubToken	string	GitHub API token to increase rate limits
silenceWarnings	boolean	Suppress compiler warnings (default: false)
testMode	boolean	Compile in test mode (include #[test_only] modules)
lintFlag	string	Linting level (e.g., "all", "none")
ansiColor	boolean	Enable ANSI color codes in output
stripMetadata	boolean	Strip metadata from bytecode (useful for size optimization)
onProgress	(event) => void	Callback for build progress events

Build Output Reference

Field	Type	Description
modules	string[]	Base64-encoded compiled bytecode modules
dependencies	string[]	Hex-encoded package IDs for linking
digest	number[]	Package digest bytes (32 bytes)
moveLock	string	Generated Move.lock V4 content
environment	string	Build environment (e.g., "mainnet", "testnet")
publishedToml	string?	Migrated Published.toml (if V3→V4 migration)
warnings	string?	Compiler warnings (if silenceWarnings: false)

Fetching packages from GitHub

import {
  fetchPackageFromGitHub,
  buildMovePackage,
  initMoveCompiler,
} from "@zktx.io/sui-move-builder";

await initMoveCompiler();

// Fetch a package from GitHub URL
const files = await fetchPackageFromGitHub(
  "https://github.com/MystenLabs/sui/tree/framework/mainnet/crates/sui-framework/packages/sui-framework",
  {
    githubToken: process.env.GITHUB_TOKEN, // optional
  }
);

// Compile directly
const result = await buildMovePackage({
  files,
  githubToken: process.env.GITHUB_TOKEN, // optional
});

How it works

Dependencies are automatically resolved from Move.toml:

1. Tries Move.lock first: If a valid Move.lock exists, dependencies are loaded from it (faster, deterministic)
2. Falls back to manifests: If lockfile is missing/invalid, resolves dependencies from Move.toml files
3. Validates digests: Checks manifest digests to detect changes
4. Handles monorepos: Converts local dependencies to git dependencies automatically
5. Injects system packages: Automatically adds Sui, MoveStdlib, SuiSystem, and Bridge packages if missing

import { initMoveCompiler, buildMovePackage } from "@zktx.io/sui-move-builder";

await initMoveCompiler();

const files = {
  "Move.toml": `
[package]
name = "my_package"
edition = "2024.beta"

[dependencies]
dep_name = { git = "https://github.com/org/repo.git", subdir = "packages/dep_name", rev = "main" }
`,
  "sources/main.move": "...",
};

const result = await buildMovePackage({ files });

if (result.success) {
  console.log("Modules:", result.modules); // Base64-encoded bytecode
  console.log("Dependencies:", result.dependencies); // Hex-encoded IDs
  console.log("Digest:", result.digest); // Package digest
} else {
  console.error("Build failed:", result.error);
}

Package Management Logic

This builder follows the official Sui CLI precedence rules for package management:

1. CLI Overrides: Explicit options (e.g., network) take highest precedence.
2. Move.lock: If present and valid, dependencies are resolved exactly as pinned in the lockfile. This ensures deterministic builds.
   • The addresses of dependencies (e.g., Sui, Std) are determined by the lockfile's [move.package.addresses] section for the active environment (e.g., devnet, mainnet).
3. Move.toml: Used if no lockfile exists or if it is invalid. Defines direct dependencies and their sources.
4. Published.toml:
   • Used to resolve the published-at address (original ID) for the root package if available.
   • Does not override dependency resolution; it is primarily an output record of deployment.
   • If a package is listed in Published.toml with a matching id, the builder uses that ID for linking, similar to how the Sui CLI handles upgrades.

Dependency caching and reuse

For faster builds when compiling multiple times with the same dependencies, you can resolve dependencies once and reuse them:

import {
  initMoveCompiler,
  resolveDependencies,
  buildMovePackage,
} from "@zktx.io/sui-move-builder";

await initMoveCompiler();

const files = {
  "Move.toml": `...`,
  "sources/main.move": "...",
};

// 1. Resolve dependencies once
const deps = await resolveDependencies({ files, network: "mainnet" });

// 2. Build multiple times without re-resolving dependencies
const result1 = await buildMovePackage({
  files,
  network: "mainnet",
  githubToken: process.env.GITHUB_TOKEN, // optional
  resolvedDependencies: deps, // Skip dependency resolution
});

// Modify source code
files["sources/main.move"] = "// updated code...";

// 3. Build again with cached dependencies (much faster!)
const result2 = await buildMovePackage({
  files,
  network: "mainnet",
  githubToken: process.env.GITHUB_TOKEN, // optional
  resolvedDependencies: deps, // Reuse same dependencies
});

Benefits:

• ⚡ Faster builds when dependencies haven't changed
• 🔄 Useful for watch mode or iterative development
• 💾 Reduce network requests by caching dependency resolution

Limitations

• Dependencies are always compiled from source. Bytecode-only deps (.mv fallback used by the Sui CLI when sources are missing) are not supported in the wasm path.

Best Practices

Input Sanitization

When preparing the files object for buildMovePackage, exclude build artifacts (e.g., the build/ directory) and version control folders (.git/). Including these can cause:

• Compilation Errors: Duplicate modules or incorrect edition parsing (e.g., dependency files treated as root sources).
• Performance Issues: Unnecessary processing of large binary files.

Example filtering logic:

if (entry.name === "build" || entry.name === ".git") continue;

Local test page

npm run serve:test   # serves ./test via python -m http.server
# open http://localhost:8000/test/index.html

Fidelity Tests

This package includes byte-level comparison tests against the official Sui CLI output:

npm run test:lite   # Run fidelity tests (lite version)
npm test            # Run full integration tests

Test Cases (verified against sui-mainnet-v1.63.3):

Package	Modules	Dependencies	Digest	Lockfile
nautilus	✅	✅	✅	✅
deepbook	✅	✅	✅	✅ (mainnet + testnet)
deeptrade	✅	✅	✅	✅ (diamond deps)

All tests verify:

• ✅ Module bytecode (identical to CLI .mv output)
• ✅ Dependency IDs (exact match with CLI)
• ✅ Package digest (identical hash)
• ✅ Move.lock V4 content (all environments preserved)
• ✅ manifest_digest calculation (CLI-compatible)

Roadmap

• ✅ Move.lock V4 Generation: CLI-compatible with deterministic sorting and manifest_digest
• ✅ Multi-Environment Support: Preserves all environments from existing Move.lock
• ✅ V3→V4 Migration: Automatically generates Published.toml from legacy Move.lock
• Published.toml Generation: Generate Published.toml after successful deployment
• Bytecode Dependencies: Support for .mv-only dependencies (CLI fallback path)