{"id":35452873,"url":"https://github.com/zktx-io/sui-move-builder","last_synced_at":"2026-05-10T08:13:21.669Z","repository":{"id":331830231,"uuid":"1126502167","full_name":"zktx-io/sui-move-builder","owner":"zktx-io","description":"WASM-based compiler to build Move packages in the browser or Node.js, with GitHub dependency resolution and automatic Sui system packages.","archived":false,"fork":false,"pushed_at":"2026-01-25T07:09:09.000Z","size":20651,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T21:59:16.237Z","etag":null,"topics":["blockchain","move","sui","wasm","web"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@zktx.io/sui-move-builder","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zktx-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T03:32:20.000Z","updated_at":"2026-01-25T07:07:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zktx-io/sui-move-builder","commit_stats":null,"previous_names":["zktx-io/sui-move-builder"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/zktx-io/sui-move-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zktx-io%2Fsui-move-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zktx-io%2Fsui-move-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zktx-io%2Fsui-move-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zktx-io%2Fsui-move-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zktx-io","download_url":"https://codeload.github.com/zktx-io/sui-move-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zktx-io%2Fsui-move-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32530178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","move","sui","wasm","web"],"created_at":"2026-01-03T04:09:31.225Z","updated_at":"2026-05-10T08:13:21.660Z","avatar_url":"https://github.com/zktx-io.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @zktx.io/sui-move-builder\n\n\u003e **Upstream source:** [MystenLabs/sui](https://github.com/MystenLabs/sui) (see `sui-version.json`)\n\nBuild Sui Move package snapshots in browser or Node.js with WASM artifacts built from pinned Sui source.\n\nThis package compiles source snapshots and prepares bytecode payload data. It does not sign transactions, choose gas, execute transactions, fetch RPC data, or scan a host filesystem package root.\n\n## Install\n\n```bash\nnpm install @zktx.io/sui-move-builder\n```\n\n## Entries\n\n| Entry        | Import path                              | Use                                                                   |\n| ------------ | ---------------------------------------- | --------------------------------------------------------------------- |\n| Lite         | `@zktx.io/sui-move-builder`              | Build, publish preparation, upgrade preparation                       |\n| Full         | `@zktx.io/sui-move-builder/full`         | Lite APIs plus `testMovePackage`                                      |\n| Verification | `@zktx.io/sui-move-builder/verification` | Rebuild source and compare it with caller-provided reference bytecode |\n\nThe verification entry bundles the current verifier and decoded-bytecode-version 6 verifier artifacts. It selects the verifier from the decoded bytecode version in `reference.modules`.\n\n## Build A Package\n\n```ts\nimport {\n  initMovePackageBuilder,\n  dumpMovePackage,\n} from \"@zktx.io/sui-move-builder\";\n\nawait initMovePackageBuilder();\n\nconst files = {\n  \"Move.toml\": `\n[package]\nname = \"hello_world\"\nversion = \"0.0.1\"\n\n[addresses]\nhello_world = \"0x0\"\n`,\n  \"sources/hello_world.move\": `\nmodule hello_world::hello_world {\n  public fun hello() {}\n}\n`,\n};\n\nconst result = await dumpMovePackage({ files });\n\nif (\"error\" in result) {\n  console.error(result.category, result.error);\n} else {\n  console.log(result.modules);\n  console.log(result.dependencies);\n  console.log(result.digest);\n  console.log(result.moveLock);\n}\n```\n\n`dumpMovePackage` returns base64 modules, dependency package IDs, package digest bytes, generated `Move.lock` content, and compiler warnings when available.\n\n## Prepare Publish Or Upgrade\n\n```ts\nimport {\n  initMovePackageBuilder,\n  prepareMovePackagePublish,\n  prepareMovePackageUpgrade,\n} from \"@zktx.io/sui-move-builder\";\n\nawait initMovePackageBuilder();\n\nconst publish = await prepareMovePackagePublish({\n  files,\n  network: \"mainnet\",\n});\n\nconst upgrade = await prepareMovePackageUpgrade({\n  files,\n  network: \"mainnet\",\n});\n```\n\nThese APIs prepare bytecode payload data only. The calling app remains responsible for wallet flow, transaction construction, signing, execution, and persistence.\n\n## Update Publication Files\n\nAfter a successful external publish or upgrade transaction, use `updateMovePackagePublication` to update caller-owned package files.\n\n```ts\nimport {\n  prepareMovePackagePublish,\n  updateMovePackagePublication,\n} from \"@zktx.io/sui-move-builder\";\n\nconst prepared = await prepareMovePackagePublish({ files, network: \"testnet\" });\nif (\"error\" in prepared) throw new Error(prepared.error);\n\nconst filesWithLock = { ...files, \"Move.lock\": prepared.moveLock };\n\n// Build, sign, and execute the transaction in your app.\nconst result = await signAndExecuteTransaction({ transaction });\nconst { chainIdentifier } = await client.core.getChainIdentifier();\n\nconst updated = await updateMovePackagePublication({\n  files: filesWithLock,\n  prepared,\n  result,\n  network: \"testnet\",\n  chainId: chainIdentifier,\n});\n```\n\nUpgrade publication updates require existing publication data for the selected environment so the original package ID and UpgradeCap ID can be preserved.\n\n## Run Move Unit Tests\n\n`testMovePackage` is available from the full entry.\n\n```ts\nimport {\n  initMovePackageBuilder,\n  testMovePackage,\n} from \"@zktx.io/sui-move-builder/full\";\n\nawait initMovePackageBuilder();\n\nconst result = await testMovePackage({\n  files,\n  network: \"mainnet\",\n});\n```\n\n`testMovePackage` returns the Move unit-test runner stdout in `output`. It does not expose CLI test-runner flags such as filter, list, thread count, statistics, or random-test options.\n\n## Verify Source Against Reference Bytecode\n\n```ts\nimport {\n  initMovePackageVerifier,\n  verifyMovePackageProvenance,\n} from \"@zktx.io/sui-move-builder/verification\";\n\nawait initMovePackageVerifier();\n\nconst result = await verifyMovePackageProvenance({\n  files,\n  intent: \"publish\",\n  reference: {\n    modules: publishModules,\n    dependencies: publishDependencies,\n    packageId,\n  },\n});\n```\n\nUse `intent: \"publish\"` for publish transaction modules or publish `.mv` artifacts. Use `intent: \"upgrade\"` for upgrade transaction modules or upgrade preparation output.\n\nFor publish transaction payload modules that keep the package self address as `0x0`, provide `reference.packageId` as deployed package metadata and do not provide `reference.rootAddress`. Do not pass both `reference.packageId` and `reference.rootAddress` when verifying normal publish transaction payload modules whose package self address is `0x0`. Use `reference.rootAddress` only when the reference bytecode already contains the published package address as the module self address; it explicitly rewrites the current build's module identity for semantic comparison.\n\n`verified` with `exact_bytecode_match` means the rebuilt raw modules match the reference bytes. Other statuses and verdicts are comparison evidence, not transaction execution results. See [VERIFICATION.md](./VERIFICATION.md).\n\n## Fetch From GitHub\n\n```ts\nimport {\n  fetchMovePackageFromGitHub,\n  dumpMovePackage,\n  initMovePackageBuilder,\n} from \"@zktx.io/sui-move-builder\";\n\nawait initMovePackageBuilder();\n\nconst input = await fetchMovePackageFromGitHub(\n  \"https://github.com/\u003cowner\u003e/\u003crepo\u003e/tree/\u003cref\u003e/\u003cpath-to-move-package\u003e\",\n  {\n    githubToken: process.env.GITHUB_TOKEN,\n  }\n);\n\nconst result = await dumpMovePackage(input);\n```\n\nFor local or custom dependency sources, provide package snapshots through `fetcher`. Browser builds should not assume direct host filesystem access.\n\n## Browser Loading\n\nModern bundlers usually serve the bundled `sui_move_wasm_bg.wasm` next to the generated JS. If you host the WASM file yourself, pass its URL:\n\n```ts\nawait initMovePackageBuilder({\n  wasm: new URL(\"/assets/sui_move_wasm_bg.wasm\", window.location.origin),\n});\n```\n\nThe verification entry can also lazy-load decoded-bytecode-version 6 verifier modules. Browser deployments that use `@zktx.io/sui-move-builder/verification` must publish the routed verifier JS and WASM files with the app assets:\n\n- `v6/classic/sui_move_wasm.js`\n- `v6/classic/sui_move_wasm_bg.wasm`\n- `v6/v7source-2024/sui_move_wasm.js`\n- `v6/v7source-2024/sui_move_wasm_bg.wasm`\n\nIf your bundler emits the verification entry under `/assets`, these files are requested under `/assets/v6/...`. A missing routed verifier JS file fails before source comparison with a dynamic import error.\n\nIf your app hosts routed verifier files under a browser asset prefix, pass a root-relative or absolute HTTP(S) base URL:\n\n```ts\nconst result = await verifyMovePackageProvenance({\n  files,\n  intent: \"publish\",\n  reference,\n  verifierAssetBaseUrl: \"/assets\",\n});\n```\n\n`verifierAssetBaseUrl` accepts values such as `/assets`, `/assets/`, and `https://cdn.example.com/assets`. Plain relative paths such as `assets`, `./assets`, and `../assets` are rejected. If you pass a custom `wasm` override, routed verifier asset loading is skipped.\n\nServe `.wasm` files with `Content-Type: application/wasm`. The loader retries transient route JS and WASM fetch failures such as `503`, but missing assets such as `404` still fail.\n\nBrowser deployment checklist:\n\n- Keep each routed `sui_move_wasm.js` next to its `sui_move_wasm_bg.wasm` file under the same route directory.\n- If your bundler or CDN moves package assets away from the verification entry chunk, set `verifierAssetBaseUrl` to the deployed root-relative or absolute HTTP(S) asset base.\n- Probe the routed JS and WASM URLs after deploy, including both `v6/classic` and `v6/v7source-2024`.\n- Treat `404` as an asset packaging or path error. Retry only covers transient network, gateway, or warmup failures.\n- Fix `application/octet-stream` or missing WASM MIME settings to `application/wasm`; otherwise browsers fall back to slower non-streaming initialization and still fail on non-OK responses.\n- Browser apps must pass source snapshots and dependency snapshots or a `fetcher`; they should not rely on host filesystem package roots.\n\n## Main Input Options\n\n| Option                        | Type                                 | Notes                                                              |\n| ----------------------------- | ------------------------------------ | ------------------------------------------------------------------ |\n| `files`                       | `Record\u003cstring, string\u003e`             | Required virtual package files such as `Move.toml` and `sources/*` |\n| `network`                     | `\"mainnet\" \\| \"testnet\" \\| \"devnet\"` | Defaults to `mainnet`                                              |\n| `githubToken`                 | `string`                             | Optional GitHub API token                                          |\n| `fetcher`                     | `MovePackageFetcher`                 | Optional host loader for git and local dependency snapshots        |\n| `silenceWarnings`             | `boolean`                            | Suppress compiler warnings                                         |\n| `withUnpublishedDependencies` | `boolean`                            | Compile unpublished dependencies as `0x0` package IDs              |\n| `modes`                       | `string[]`                           | Move compiler modes                                                |\n| `lintFlag`                    | `\"none\" \\| \"default\" \\| \"all\"`       | Defaults to `none`                                                 |\n| `ansiColor`                   | `boolean`                            | Enable ANSI output                                                 |\n| `stripMetadata`               | `boolean`                            | Reserved; currently passed through but not applied                 |\n| `onProgress`                  | `(event) =\u003e void`                    | Build progress callback                                            |\n| `verifierAssetBaseUrl`        | `string \\| URL`                      | Verification-only browser asset base for routed verifier files     |\n\nBuild and test failures return `{ error, category, code? }`. `category` is a broad stage label; `error` is the detailed diagnostic.\n\n## Practical Limits\n\n- Source snapshots are required. Bytecode-only dependency fallback is not supported.\n- Publish and upgrade helpers prepare bytecode payload data; they do not execute transactions.\n- Older `Move.lock` graph formats are not used as pinned dependency graphs. Supported packages fall back to manifest resolution.\n- Browser-compatible WASM builds use declared compatibility replacements for some host and native crates.\n\n## More Documentation\n\n| Document                                                     | Role                                                                  |\n| ------------------------------------------------------------ | --------------------------------------------------------------------- |\n| [VERIFICATION.md](./VERIFICATION.md)                         | Verification input, status, verdict, decoded bytecode version routing |\n| [PACKAGE_BEHAVIOR.md](./PACKAGE_BEHAVIOR.md)                 | Package resolution behavior, output fields, limitations               |\n| [DEVELOPMENT.md](./DEVELOPMENT.md)                           | Build, test, and release checks for this repository                   |\n| [CLI_PIPELINE.md](./CLI_PIPELINE.md)                         | Implementation boundaries and covered CLI/WASM comparison stages      |\n| [SECURITY.md](./SECURITY.md)                                 | WASM runtime boundary and compatibility replacement inventory         |\n| [BYTECODE_VERSION_HISTORY.md](./BYTECODE_VERSION_HISTORY.md) | Decoded bytecode version source records used for verifier selection   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzktx-io%2Fsui-move-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzktx-io%2Fsui-move-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzktx-io%2Fsui-move-builder/lists"}