composable-move-functions

composable-move-functions

MCP tool: When available in your environment, also query the Sui documentation MCP server (https://sui.mcp.kapa.ai) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Overview

Sui transactions can chain multiple function calls in a single Programmable Transaction Block (PTB). Functions that transfer objects internally instead of returning them break this composability. This skill covers how to design functions that work well in PTBs.

All patterns sourced from https://move-book.com/guides/code-quality-checklist

No public entry

Functions should be either public (composable, can be called from other modules and PTBs) or entry (transaction endpoint only). Never use public entry together.

// 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) { }

When to use entry: Only for convenience endpoints that are intentionally non-composable — functions that wrap a composable public function and handle transfers to sender.

Return Objects, Don't Transfer Internally

Public functions should return values to the caller rather than transferring them to ctx.sender(). This makes them composable in PTBs — the caller decides what to do with the result.

// 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());
}