LayerZero V2

The Call Module supports structured, multi-level coordination through parent-child relationships. This allows for complex workflows where a single root call can trigger multiple batches of child calls.

Coordination Rules

• Sequential Batches: A new batch (Batch N+1) cannot begin until the previous batch (Batch N) is complete.
• Parallel Children: All calls within a single batch can execute concurrently.
• FIFO Destruction: Child calls must be destroyed in the exact order they were created (First-In, First-Out).
• Completion Propagation: A parent call cannot reach the Completed state until all of its children have been destroyed.

Workflow Example Structure

Root Call (A→B)
├── Batch 1 (nonce=1)
│   ├── Child Call 1 (B→C)    [parallel execution]
│   └── Child Call 2 (B→D)    [parallel execution]
├── Batch 2 (nonce=2)         [sequential after Batch 1]
│   └── Child Call 3 (B→E)

The Call<Param, Result> struct is the primary 'hot-potato' resource used for cross-contract communication in the IOTA Call module. It encapsulates the state of a call, including its identity, participants, and lifecycle status.

Key fields include:

• id: Globally unique identifier derived from the object ID.
• caller & callee: The originating and target contract addresses.
• one_way: Determines if the callee or the caller is responsible for destroying the resource.
• param: Type-safe input parameters of type Param.
• mutable_param: A boolean flag indicating if the callee is authorized to modify parameters.
• result: An Option<Result> containing the output after complete() is called.
• status: A CallStatus enum tracking the lifecycle (Active, Creating, Waiting, Completed).

public struct Call<Param, Result> {
    id: address,                    // Globally unique call identifier
    caller: address,                // Originating contract address
    callee: address,                // Target contract address for processing
    one_way: bool,                  // Destruction authorization mode
    param: Param,                   // Type-safe input parameters
    mutable_param: bool,           // Whether callee can modify parameters (default: false)
    result: Option<Result>,         // Optional result (Some after completion)
    parent_id: address,             // Parent call ID (ROOT_CALL_PARENT_ID for roots)
    batch_nonce: u64,               // Monotonic batch sequence number
    child_batch: vector<address>,   // FIFO-ordered child call identifiers
    status: CallStatus,             // Automatically managed lifecycle state
}

The Call Module provides a way to perform dynamic dispatch in the IOTA Move VM, which otherwise requires all function calls to be statically resolved at compile time. It uses a hot-potato pattern to simulate runtime contract selection and method invocation without requiring the caller to have compile-time dependencies on all possible callees.

Key Capabilities

• Runtime Library Selection: Select message libraries based on runtime configuration.
• Extensible Architecture: Integrate new libraries without modifying existing contracts.
• Type-Safe Generics: Uses Move's type system via <Param, Result> parameters to ensure safety.
• Hierarchical Coordination: Supports complex, multi-level workflows (parent-child call relationships) with structured batching.

// Runtime target determination with compile-time safety
let call = call::create<SendParams, Receipt>(
    &caller_cap,
    resolve_library_address(config),  // Runtime resolution
    false,                            // Bidirectional communication
    send_params,
    ctx
);

// Type-safe parameter passing and result collection
// ... call flows to selected library ...
call.complete(&library_cap, receipt);

// Guaranteed result extraction
let (callee_addr, params, receipt) = call.destroy(&caller_cap);

The Call<Param, Result> object implements a hot-potato pattern, meaning it is a non-droppable resource that must be handled through a specific lifecycle to ensure safety and completion.

Lifecycle Stages

1. Creation: The caller instantiates the call with typed parameters.
2. Processing: The callee receives and processes the call.
3. Delegation (Optional): The callee can create child calls for complex workflows.
4. Completion: The callee provides a typed result via complete().
5. Destruction: The authorized party extracts the result and consumes the call via destroy().

State Transitions

The CallCap object provides authorization for state-modifying call operations. It supports two identity resolution modes via the CapType enum:

1. Individual Capability (CapType::Individual): Uses the specific CallCap.id.to_address() as the identifier. This is used for single capability instance operations.
2. Package Capability (CapType::Package(address)): Uses the provided package address as the identifier. This allows protocol-level operations across all instances from the same package and requires a one-time witness for creation.

All state-modifying operations require a CallCap to be passed as an argument.

public struct CallCap has key, store {
    id: UID,                        // Sui object identifier
    cap_type: CapType,              // Determines identity resolution mechanism
}

public enum CapType has copy, drop, store {
    Individual,                     // Uses UID address as identifier
    Package(address),               // Uses package address as identifier
}

The Call<Param, Result> object implements a hot-potato pattern to ensure mandatory resource handling. Because the object is non-droppable and follows linear typing, every call must reach a terminal state (destruction) to prevent resources from being lost or ignored.

Lifecycle States and Transitions

Coordination Rules

• FIFO Child Destruction: Child calls must be destroyed in the order they were created (First-In, First-Out).
• Batch Completion: All children in a batch must be destroyed before the parent call can return to the Active state.
• Sequential Batches: A new batch can only be initiated when the call is in the Active status.
• Authorization: Every operation (creation, completion, destruction) requires the appropriate CallCap object for access control.

The Call Module provides a way to perform dynamic dispatch in the Sui Move VM, which otherwise requires all function calls to be statically resolved at compile time. It uses a hot-potato pattern to allow a contract to select a target module at runtime and invoke it without having a compile-time dependency on that module.

Key Capabilities

• Runtime Library Selection: Choose which module to interact with based on runtime configuration (e.g., selecting a specific Message Library).
• Extensible Architecture: Integrate new modules without upgrading or modifying existing dependent contracts.
• Type-Safe Generics: Uses Move's type system with <Param, Result> parameters to ensure that parameters passed to the callee and results returned to the caller are type-safe.
• Hierarchical Workflows: Supports complex, multi-level coordination where a call can trigger child calls in batches (parallel or sequential).

// Runtime target determination with compile-time safety
let call = call::create<SendParams, Receipt>(
    &caller_cap,
    resolve_library_address(config),  // Runtime resolution
    false,                            // Bidirectional communication
    send_params,
    ctx
);

// ... call flows to selected library ...

// Type-safe parameter passing and result collection
call.complete(&library_cap, receipt);

// Guaranteed result extraction
let (callee_addr, params, receipt) = call.destroy(&caller_cap);

The PTB (Programmable Transaction Block) Move Call system is a dynamic construction mechanism for LayerZero V2 on IOTA. It solves the problem of runtime component selection (like choosing specific message libraries or workers) and cross-PTB argument passing in a language (Move) that typically requires static dispatch.

It uses two primary mechanisms:

1. Dynamic PTB Generation: Builder modules expand high-level "Builder Calls" into sequences of low-level "Direct Calls". This expansion can be recursive (nested).
2. Global ID System: A system of unique identifiers that allows arguments to flow between different PTB fragments during the construction process before they are assembled into a single, atomic transaction.

Execution Flow:

1. Root PTB Construction: Developer defines a root PTB with direct or builder calls.
2. Off-chain Simulation: Builder calls are routed to component builders.
3. PTB Expansion: Builders produce call sequences (which may include more builder calls).
4. PTB Assembly: All produced calls are combined into the root PTB.
5. Recursive Expansion: The process repeats until only direct calls remain.
6. Blockchain Submission: The final, fully expanded PTB is executed atomically on-chain.