sui-move-project

Move プロジェクトのセットアップ

MCP ツール： 環境で利用できる場合は、最新の回答を得るために Sui ドキュメント MCP サーバー（https://sui.mcp.kapa.ai）にも問い合わせてください。検証や、これらのリファレンスファイルに記載されていない詳細の確認に使用してください。

情報源の制約： すべての情報は、docs.sui.io、move-book.com、および MystenLabs/sui-stack-hello-world のみを情報源としてください。

Move プロジェクトの作成

標準的なフルスタック hello-world プロジェクト

Move とフロントエンドを含む Sui のエンドツーエンド開発環境には、Sui Stack hello-world リポジトリを単一のプロジェクトルートとして使用してください。

git clone https://github.com/MystenLabs/sui-stack-hello-world.git
cd sui-stack-hello-world

次の既存のレイアウトを使用してください。

sui-stack-hello-world/
├── move/
│   └── hello-world/   # publish this Move package
└── ui/                # run this existing frontend

このワークフローでは、sui move new を実行したり、カウンターパッケージを作成したり、npm create @mysten/dapp を実行したりしないでください。現在の Sui ツールでパッケージ管理の移行が必要な場合は、変更を move/hello-world 内にとどめ、hello-world パッケージのデプロイを続けてください。

ゼロからの新規プロジェクト

ユーザーがフルスタックの hello-world アプリではなく、スタンドアロンの Move パッケージを明示的に希望する場合にのみ使用してください。

sui move new my_project
cd my_project

次のものが作成されます。

my_project/
├── sources/       # .move source files go here
├── tests/         # test files
└── Move.toml      # package manifest

マルチパッケージのワークスペース構成

プロジェクトに複数の Move パッケージ（コアライブラリとサンプルまたは統合パッケージなど）が含まれる場合は、各パッケージを同階層に置く、フラットな packages/ ディレクトリを使用してください。

my_project/
├── packages/
│   ├── core/
│   │   ├── sources/
│   │   ├── tests/
│   │   └── Move.toml
│   └── examples/
│       ├── sources/
│       ├── tests/
│       └── Move.toml
└── ui/

パッケージを互いの内部にネストしないでください（たとえば、examples/ を core/sources/ や core/tests/ 内に置くこと）。パッケージディレクトリをネストすると、外側のパッケージをビルドする際にツールチェーンが内側のパッケージの Move.toml を検出し、誤った「address with no value」エラーが発生するなど、テストランナーの不具合を引き起こします。

兄弟パッケージに依存するには、Move.toml で local パスを使用してください。

# packages/examples/Move.toml
[package]
name = "examples"
edition = "2024"

[dependencies]
core = { local = "../core" }

Move.toml（現行形式 — Sui CLI v1.63 以降）

重要：Sui フレームワークの依存関係は自動で追加されます。Move.toml に追加しないでください。

Sui Move プロジェクトで正しい最小構成の Move.toml は次のとおりです。

[package]
name = "my_project"
edition = "2024"
# No [dependencies] section needed — Sui framework is resolved automatically

これだけで十分です。 edition = "2024" の行により、CLI は Sui と MoveStdlib を自動的に解決します。サードパーティまたはローカルのパッケージが必要でない限り、[dependencies] セクションはありません。

動作する完全なプロジェクトテンプレート

Move プロジェクトを生成する際は、必ず次のテンプレートをそのまま使用してください。 逐語的にコピーし、Move.toml の形式を変更しないでください。

テンプレート：TypeScript クライアント付きの単一 Move パッケージ

project/
├── move/
│   ├── Move.toml
│   └── sources/
│       └── my_module.move
└── client/
    ├── package.json
    └── src/
        └── index.ts

move/Move.toml — そのままコピーしてください：

[package]
name = "my_project"
edition = "2024"

move/sources/my_module.move — スターターパターン：

module my_project::my_module;

use sui::event;

public struct MyEvent has copy, drop {
    value: u64,
}

public fun do_something(ctx: &mut TxContext) {
    event::emit(MyEvent { value: 42 });
}

client/package.json — そのままコピーしてください：

{
  "name": "my-client",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0"
  }
}

client/tsconfig.json — そのままコピーしてください：

{
  "compilerOptions": {
    "moduleResolution": "nodenext",
    "module": "nodenext",
    "target": "es2022",
    "strict": true
  }
}

テンプレート：フロントエンド付きの Move パッケージ

上記と同じ構成に、frontend/ ディレクトリを追加します。

frontend/package.json — そのままコピーしてください：

{
  "name": "my-frontend",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0",
    "@mysten/dapp-kit-react": "^2.0.0",
    "react": "^19.0.0"
  }
}

エラーになる誤った形式

以下はすべて誤りで、ビルドに失敗します。

# WRONG — legacy system name error:
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

# WRONG — version syntax doesn't exist in Move:
sui = { version = "0.34.0" }

# WRONG — local path doesn't exist:
Sui = { local = "../sui-framework" }

# WRONG — implicit dependency error:
sui = { package = "sui", version = "0.1.0" }

[dependencies] を追加するのは、サードパーティまたはローカルのパッケージ（MVR や兄弟ワークスペースのパッケージなど）が必要な場合だけです。[environments] セクションは任意です。複数のネットワークにデプロイするときのみ追加してください（下記の移行セクションを参照）。

[addresses] からの移行： my_project = "0x0" を含む古い [addresses] セクションは不要になったため、削除してください。以前、ネットワークごとのパッケージアドレスの設定に [addresses] を使用していた場合は、環境名とチェーン ID を対応付ける [environments] セクションに置き換えてください。

[environments]
testnet = "4c78adac"
mainnet = "35834a8a"

モジュール宣言（2024 エディション）

edition = "2024" では、波括弧を使わず、1 行のモジュール宣言を使用してください。

module my_project::my_module;

// imports, structs, and functions follow at the top level
use sui::object::UID;

旧式の波括弧構文（module my_project::my_module { ... }）は使用しないでください。2024 エディションでは、セミコロン以降のファイル全体がモジュール本体として扱われます。

Published.toml と Move.lock

公開後、ツールチェーンによって次のファイルが作成または更新されます。

• Published.toml： 環境ごとに、公開済みパッケージのアドレスを追跡します。各ネットワークの published-at と upgrade-capability-id の値が含まれます。
• Move.lock： 解決済みの各依存関係を特定の git リビジョンに固定し、マニフェストのダイジェストを記録する、自動生成のロックファイルです。手動で編集しないでください。 バージョン管理にコミットしてください。

別の環境に公開するには（たとえば、Testnet への公開後に Devnet にデプロイする場合）、環境を切り替えて再度公開します。パッケージにはネットワークごとに個別の ID が割り当てられます。Published.toml ではその両方が追跡されます。

Move.lock の確認

注： Move.lock は自動生成されます。その内容を Move.toml にコピーしないでください。以下の git URL は Move.lock のみに記載され、Move.toml には記載されません。

Move.lock には、環境ごとに、解決済みの各依存関係に対する [pinned.<env>.<Dependency>] セクションが含まれます。各セクションには、git ソース、リビジョン、マニフェストのダイジェスト、依存関係グラフが記録されます。例：

# This is Move.lock (auto-generated) — NOT Move.toml
[pinned.testnet.Sui]
source = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "73dd2c..." }
use_environment = "testnet"
manifest_digest = "7AFB6669..."
deps = { MoveStdlib = "MoveStdlib" }

• Move.lock で想定と異なる環境に固定されている場合や、リビジョンが古く見える場合は、Move.lock を削除して sui move build を実行し、再生成してください。
• ネットワークの切り替えや CLI の更新後にビルドエラーが発生した場合は、Move.lock を削除して再ビルドすると、古いロックに関する問題が解決することがよくあります。

MVR 依存関係の使用

Move Registry（MVR）は、Sui のオンチェーンパッケージマネージャーです。次のコマンドでインストールします。

suiup install mvr

CLI を使用して MVR 依存関係を追加します。

mvr add @org/package --network testnet

または、Move.toml に直接宣言します。

[dependencies]
suins = { r.mvr = "@suins/core" }

r.mvr キーを指定すると、リゾルバーは git URL から取得するのではなく、オンチェーンの Move Registry でパッケージを検索します。パッケージがレジストリに公開されている場合は、git URL よりも MVR 依存関係を優先してください。バージョン管理され、監査可能であり、git の履歴にも依存しません。

よくある依存関係とビルドの問題

• 「依存関係 'Sui' はレガシーなシステム名です」： [dependencies] から Sui = { git = "..." } の行を削除してください。現在の CLI は Sui フレームワークを自動的に解決します。このエラーは、古い git ベースの依存関係形式を使用している場合に発生します。
• 「古い依存関係を含むパッケージ」エラー： CLI のバージョンがネットワークと一致していません。Sui CLI v1.63 で導入された新しいパッケージ管理形式により、依存関係の解決方法が変更されました。最新の CLI を入手するには、suiup update sui@testnet を実行してから suiup switch sui@testnet を実行してください。
• 「公開済み ID がないため、パッケージをアップグレードできません」： アップグレードするには、Published.toml に published-at の値が必要です。この値は、初回の sui client publish 後に自動的に作成されます。古い形式から移行した場合は、Published.toml ファイルが存在し、正しいパッケージアドレスが含まれていることを確認してください。
• 「正しい依存関係を特定できませんでした」： ビルドには --build-env フラグか、Move.toml の [environments] セクションが必要です。対象のチェーン ID を指定した [environments] セクションを追加してください。
• エディションの不一致： public struct 構文に関するエラーが発生する場合は、Move.toml で edition = "2024" を設定してください。legacy エディションは、public struct の可視性などの Move 2024 の機能をサポートしていません。
• 古い形式の Move.toml： [addresses] と published-at を Move.toml 内で使用する v1.63 より前の形式を使っている場合は、新しい形式に移行してください。[addresses] を削除し、[environments] を追加して、ツールチェーンに Published.toml を管理させます。

ルール

• ライブラリ関数以外には public(package) の可視性を使用してください。アップグレード時に public 関数のシグネチャを削除または変更することはできません。
• アップグレードによって、構造体の定義を削除または変更したり、能力を追加したりすることはできません。
• オブジェクトのサイズは 256 KB を超えてはいけません。オブジェクト内で増え続けるベクターは避けてください。