パッケージをアップグレードする

コントラクトを公開した後で「バグを直したい」「機能を追加したい」と思うことはよくあります。Suiでは パッケージのアップグレード という仕組みで、既存のパッケージを更新できます。手順を一つずつ見ていきましょう。

UpgradeCap とは？

sui client publish でパッケージを公開すると、トランザクションの結果として UpgradeCap というオブジェクトが発行されます。

このオブジェクトが「アップグレードの鍵」です。

通常は、UpgradeCap を管理している主体だけがパッケージをアップグレードできます
誰かに譲渡することも、破棄することもできます（破棄するとアップグレード不可になります）
アップグレードすると 新しい Package ID が発行されます（古いIDのコントラクトはそのまま動き続けます）

sui client publish が成功するとプロジェクトルートに Published.toml というファイルが自動生成されます。このファイルに UpgradeCap のオブジェクトIDが記録されるため、アップグレード時に手動で指定する必要はありません。

このファイルはソース管理にコミットすることが推奨されています。

内容はこのようになっています：

# Generated by Move
# This file SHOULD be committed to source control

[published.devnet]
chain-id = "3d6c67b7"
published-at = "0x36d821b7..."
original-id = "0xbe356beb..."
version = 1
toolchain-version = "1.68.0"
build-config = { flavor = "sui", edition = "2024" }
upgrade-capability = "0xe569f7ab..."

published-at: 現在のパッケージID（アップグレードごとに新しいIDに更新される）
original-id: 最初に公開したときのパッケージID（変わらない）
version: アップグレードのたびにインクリメントされる番号
upgrade-capability: UpgradeCap のオブジェクトID

コードを修正する

アップグレードの例として、reset 関数を追加してみましょう。L16 で作成した counter モジュールに以下の関数を追加します。

entry fun reset(counter: &mut Counter, _ctx: &mut TxContext) {
    counter.value = 0;
}

アップグレードの制約

すでに公開したコードでは、次の変更はできません：

公開した module を削除すること
既にある public 関数の名前・引数・返り値を変えること
既にある struct に項目を追加・変更・並び替えすること

一方で、新しい関数や struct の追加、関数内の処理の書き換えは自由にできます。

アップグレードを実行する

コードの修正が終わったら、以下のコマンドでアップグレードします。

sui client upgrade

UpgradeCap を持つアドレスがアクティブアドレスであれば、このコマンドだけでアップグレードできます。

アップグレードを確認する

Published.toml で確認する

アップグレードが成功すると、Published.toml が自動的に更新されます。

[published.devnet]
published-at = "0xNEW_PACKAGE_ID..."   # ← 新しいパッケージIDに更新される
original-id = "0xbe356beb..."          # ← 変わらない
version = 2                             # ← インクリメントされる
upgrade-capability = "0xe569f7ab..."   # ← 変わらない

published-at が新しい Package ID に変わっていれば、アップグレード成功です。

Sui Explorer で確認する

suiscan.xyz でトランザクションを確認することもできます。

アップグレードのトランザクションダイジェストで検索する
「Object Changes」セクションを開く
type: "published" のエントリに新しい Package ID が表示されていることを確認する

この新しい Package ID が、アップグレードされたパッケージのアドレスです。今後はこちらのIDを使ってコントラクトを呼び出します。

ヒント

古い Package ID のコントラクトは引き続き動作します。ただし、既存のクライアントコードや依存先は自動では新しい Package ID に切り替わりません。新しいバージョンを使いたい場合は、参照先の Package ID を更新する必要があります。

お疲れさまでした！これでパッケージのアップグレードができるようになりました。上級コースでは TypeScript を使って、コントラクトをプログラムから操作する方法を学びます。

UpgradeCap とは？​

コードを修正する​

アップグレードを実行する​

アップグレードを確認する​

Published.toml で確認する​

Sui Explorer で確認する​