composable-move-functions

composable-move-functions

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

概要

Sui のトランザクションでは、単一のプログラマブルトランザクションブロック（PTB）内で複数の関数呼び出しを連結できます。オブジェクトを返す代わりに内部で転送する関数は、このコンポーザビリティを損ないます。このスキルでは、PTB でうまく機能する関数の設計方法を説明します。

すべてのパターンは https://move-book.com/guides/code-quality-checklist を参照しています。

public entry は使用しない

関数は、public（コンポーザブルで、他のモジュールや PTB から呼び出せる）または entry（トランザクションのエンドポイント専用）のいずれかにしてください。public entry を併用してはいけません。

// WRONG — public entry is redundant and limits composability
public entry fun do_something() { }

// CORRECT — public for composable functions that return values
public fun mint(ctx: &mut TxContext): NFT { }

// CORRECT — entry for intentionally non-composable endpoints
entry fun mint_and_keep(ctx: &mut TxContext) { }

entry を使用する場合： 意図的にコンポーザブルにしない利便性重視のエンドポイントに限ります。コンポーザブルな public 関数をラップし、送信者への転送を処理する関数が該当します。

内部で転送せず、オブジェクトを返す

公開関数は、ctx.sender() に転送するのではなく、呼び出し元に値を返す必要があります。これにより、呼び出し元が結果の扱いを決められるようになり、PTB でコンポーザブルに利用できます。

// WRONG — couples minting with transfer, can't compose
public fun mint_and_transfer(ctx: &mut TxContext) {
    let nft = NFT { id: object::new(ctx) };
    transfer::transfer(nft, ctx.sender());
}

// CORRECT — returns the object, caller decides
public fun mint(ctx: &mut TxContext): NFT {
    NFT { id: object::new(ctx) }
}

// If you need a convenience entry point, add a separate entry wrapper:
entry fun mint_and_keep(ctx: &mut TxContext) {
    let nft = mint(ctx);
    transfer::transfer(nft, ctx.sender());
}

返り値による CLI への影響

drop ではない値を返す関数は、sui client call から呼び出せません。CLI には返り値を消費する方法がないため、UnusedValueWithoutDrop エラーが発生します。代わりに sui client ptb を使用してください。ここでは --assign と --transfer-objects を連結して、返り値を処理できます。

sui client ptb \
  --move-call @pkg::module::create_thing --assign thing \
  --transfer-objects "[thing]" @sender

CLI から頻繁に呼び出される関数の場合は、内部で転送するラッパー用の entry 関数を用意することを検討してください（上記を参照）。

これは幅広く当てはまります。

• add_liquidity は LP コインと余剰コインを転送せずに返す
• remove_liquidity は両方のコインを返す
• swap は出力コインを転送せずに返す
• borrow は借り入れた資産を返す

パラメーターの順序

関数のパラメーターは、次の厳格な順序に従います。

1. オブジェクトが先 — 操作対象となる主なオブジェクト
2. ケイパビリティが次 — AdminCap などの認可トークン
3. プリミティブ値 — 金額、フラグ、アドレス
4. Clock — 常に末尾（ctx の前）。オブジェクトを先にするルールの例外
5. ctx: &mut TxContext を最後に — 常に最終パラメーターとし、すべてのプリミティブ値およびその他の引数の後に置く

// WRONG — cap before object, primitives mixed in
public fun authorize_action(
    cap: &AdminCap,
    value: u8,
    app: &mut App,
    ctx: &mut TxContext,
) { }

// CORRECT — object first, cap second, primitives third, ctx last
public fun authorize_action(
    app: &mut App,
    cap: &AdminCap,
    value: u8,
    ctx: &mut TxContext,
) { }

Clock の例外

オブジェクトであるにもかかわらず、Clock は末尾近くの ctx の直前に置きます。

public fun timed_action(
    app: &mut App,
    cap: &AppCap,
    value: u8,
    clock: &Clock,
    ctx: &mut TxContext,
) { }

クイックリファレンス

パターン	ルール
可視性	コンポーザブルな関数には public、エンドポイントには entry を使用します。public entry は併用しません。
返り値	公開関数はオブジェクトを返します。内部で送信者に転送しないでください。
Entry ラッパー	public 関数を呼び出して転送する、独立した entry 関数を用意します。
パラメーターの順序	オブジェクト → ケイパビリティ → プリミティブ値 → Clock → TxContext