Add the source of sui example package

example/.gitignore

@@ -0,0 +1,7 @@
+.idea
+.vscode
+
+build/*
+source/dependencies
+*.key
+.DS_Store

example/Makefile

@@ -0,0 +1,16 @@
+.PHONY: clean build
+
+# Clean build directory
+clean:
+	rm -rf Move.lock build/
+
+# Build the package and generate bytecode
+build:
+	sui move build
+
+# Help target
+help:
+	@echo "Available targets:"
+	@echo "  clean  - Remove build directory"
+	@echo "  build  - Build the example package and generate bytecode"
+	@echo "  help   - Show this help message"

example/Move.toml

@@ -0,0 +1,37 @@
+[package]
+name = "example"
+edition = "2024.beta" # edition = "legacy" to use legacy (pre-2024) Move
+# license = ""           # e.g., "MIT", "GPL", "Apache 2.0"
+# authors = ["..."]      # e.g., ["Joe Smith ([email protected])", "John Snow ([email protected])"]
+
+[dependencies]
+gateway = { local = "../"}
+
+# For remote import, use the `{ git = "...", subdir = "...", rev = "..." }`.
+# Revision can be a branch, a tag, and a commit hash.
+# MyRemotePackage = { git = "https://some.xwremote/host.git", subdir = "remote/path", rev = "main" }
+
+# For local dependencies use `local = path`. Path is relative to the package root
+# Local = { local = "../path/to" }
+
+# To resolve a version conflict and force a specific version for dependency
+# override use `override = true`
+# Override = { local = "../conflicting/version", override = true }
+
+[addresses]
+example = "0x0"
+gateway = "0x0"
+
+# Named addresses will be accessible in Move as `@name`. They're also exported:
+# for example, `std = "0x1"` is exported by the Standard Library.
+# alice = "0xA11CE"
+
+[dev-dependencies]
+# The dev-dependencies section allows overriding dependencies for `--test` and
+# `--dev` modes. You can introduce test-only dependencies here.
+# Local = { local = "../path/to/dev-build" }
+
+[dev-addresses]
+# The dev-addresses section allows overwriting named addresses for the `--test`
+# and `--dev` modes.
+# alice = "0xB0B"

example/README.md

@@ -0,0 +1,95 @@
+# SUI WithdrawAndCall with PTB Transactions
+
+This document explains how the SUI `withdrawAndCall` functionality works using Programmable Transaction Blocks (PTB) in the ZetaChain protocol.
+
+## Overview
+
+The `withdrawAndCall` operation in ZetaChain allows users to withdraw tokens from ZEVM to the Sui blockchain and simultaneously calls a `on_call` function in the `connected` module on the Sui side.
+
+This is implemented as a single atomic transaction using Sui's Programmable Transaction Blocks (PTB).
+
+## Transaction Flow
+
+1. **User Initiates Withdrawal**: A user initiates a withdrawal from ZEVM to Sui with a `on_call` payload.
+
+2. **ZEVM Processing**: The ZEVM gateway processes the withdrawal request and prepares the transaction.
+
+3. **PTB Construction**: A Programmable Transaction Block is constructed with the following steps:
+   - **Withdraw**: The first command in the PTB is the `withdraw_impl` function call, which:
+     - Verifies the withdrawal parameters
+     - Withdraw and returns two coin objects: the main withdrawn coins and the gas budget coins
+   - **Gas Budget Transfer**: The second command transfers the gas budget coins to the TSS address to cover transaction fees.
+     - The gas budget is the SUI coin withdrawn from sui vault, together with withdrawn CCTX's coinType.
+     - The gas budget needs to be forwarded to TSS address to cover the transaction fee.
+   - **Set Message Context**: The third command in the PTB is `set_message_context`
+     - It sets the `sender` and `target` in message context object right before calling `on_call` function in the `target` package.
+     - It allows the `on_call` function to perform authentication checks for the call.
+   - **Connected Module Call**: The fourth command calls the `on_call` function in the connected module, passing:
+     - The withdrawn coins
+     - The call payload from the user
+     - Any additional parameters required by the connected module
+   - **Reset Message Context**: The fifth command in the PTB is `reset_message_context`
+     - It clears the `sender` and `target` in message context object right after calling `on_call` function in the `target` package.
+     - This is to ensure that each `withdrawAndCall` use independent message context information.
+
+4. **Transaction Execution**: The entire PTB is executed atomically on the Sui blockchain.
+
+## PTB Structure
+
+The PTB for a `withdrawAndCall` transaction consists of five commands:
+
+```text
+PTB {
+    // Command 0: Withdraw Implementation
+    MoveCall {
+        package: gateway_package_id,
+        module: gateway_module,
+        function: withdraw_impl,
+        arguments: [
+            gateway_object_ref,
+            withdraw_cap_object_ref,
+            coin_type,
+            amount,
+            nonce,
+            gas_budget
+        ]
+    }
+
+    // Command 1: Gas Budget Transfer
+    TransferObjects {
+        from: withdraw_impl_result[1], // Gas budget coins
+        to: tss_address
+    }
+
+    // Command 2: Set Message Context
+    MoveCall {
+        package: gateway_package_id,
+        module: gateway_module,
+        function: set_message_context,
+        arguments: [
+            message_context,
+            zevm_sender,
+            target_package_id
+        ]
+    }
+
+    // Command 3: Connected Module Call
+    MoveCall {
+        package: target_package_id,
+        module: connected_module,
+        function: on_call,
+        arguments: [
+            withdraw_impl_result[0], // Main withdrawn coins
+            on_call_payload
+        ]
+    }
+
+    // Command 4: Reset Message Context
+    MoveCall {
+        package: gateway_package_id,
+        module: gateway_module,
+        function: reset_message_context,
+        arguments: [message_context]
+    }
+}
+```

example/sources/example.move

@@ -0,0 +1,137 @@
+module example::connected;
+
+use std::ascii;
+use std::ascii::String;
+use sui::address::from_bytes;
+use sui::coin::Coin;
+use gateway::gateway::{Gateway, MessageContext, active_message_context, message_context_sender, message_context_target};
+
+// === Errors ===
+
+const EInvalidPayload: u64 = 1;
+
+const EUnauthorizedSender: u64 = 2;
+
+// ENonceMismatch is a fabricated nonce mismatch error code emitted from the on_call function
+// zetaclient should be able to differentiate this error from real withdraw_impl nonce mismatch
+const ENonceMismatch: u64 = 3;
+
+const EInactiveMessageContext: u64 = 4;
+
+const EPackageMismatch: u64 = 5;
+
+// stub for shared objects
+public struct GlobalConfig has key {
+    id: UID,
+    called_count: u64,
+}
+
+public struct Partner has key {
+    id: UID,
+}
+
+public struct Clock has key {
+    id: UID,
+}
+
+public struct Pool<phantom CoinA, phantom CoinB> has key {
+    id: UID,
+}
+
+// share objects
+fun init(ctx: &mut TxContext) {
+    let global_config = GlobalConfig {
+        id: object::new(ctx),
+        called_count: 0,
+    };
+    let pool = Pool<sui::sui::SUI, example::token::TOKEN> {
+        id: object::new(ctx),
+    };
+    let partner = Partner {
+        id: object::new(ctx),
+    };
+    let clock = Clock {
+        id: object::new(ctx),
+    };
+
+    transfer::share_object(global_config);
+    transfer::share_object(pool);
+    transfer::share_object(partner);
+    transfer::share_object(clock);
+}
+
+public entry fun on_call<SOURCE_COIN>(
+    gateway: &Gateway,
+    message_context: &MessageContext,
+    in_coins: Coin<SOURCE_COIN>,
+    cetus_config: &mut GlobalConfig,
+    // Note: this pool type is hardcoded as <SUI, TOKEN> and therefore causes type mismatch error in the
+    // fungible token withdrawAndCall test, where the SOURCE_COIN type is FAKE_USDC instead of TOKEN.
+    // Disabling the pool object for now is the easiest solution to allow the E2E tests to go through.
+    // _pool: &mut Pool<SOURCE_COIN, TARGET_COIN>,
+    _cetus_partner: &mut Partner,
+    _clock: &Clock,
+    data: vector<u8>,
+    _ctx: &mut TxContext,
+) {
+    // check if the message is "revert" and revert with faked ENonceMismatch if so
+    if (data == b"revert") {
+        assert!(false, ENonceMismatch);
+    };
+
+    // check if the message context is active
+    let active_message_context = active_message_context(gateway);
+    assert!(active_message_context == object::id(message_context), EInactiveMessageContext);
+
+    // decode the sender, target package, and receiver from the payload
+    let (authenticated_sender, target_package, receiver) = decode_sender_target_and_receiver(data);
+
+    // check if the sender is the authorized sender
+    let actual_sender = message_context_sender(message_context);
+    assert!(authenticated_sender == actual_sender, EUnauthorizedSender);
+
+    // check if the target package is my own package
+    // this prevents other package routing TSS calls to my package
+    let actual_target = message_context_target(message_context);
+    assert!(actual_target == target_package, EPackageMismatch);
+
+    // transfer the coins to the provided address
+    transfer::public_transfer(in_coins, receiver);
+
+    // increment the called count
+    cetus_config.called_count = cetus_config.called_count + 1;
+}
+
+// decode the sender, target package, and receiver from the payload data
+fun decode_sender_target_and_receiver(data: vector<u8>): (String, address, address) {
+    // [42-byte ZEVM sender] + [32-byte Sui target package] + [32-byte Sui receiver] = 106 bytes
+    assert!(vector::length(&data) >= 106, EInvalidPayload);
+
+    // extract ZEVM sender address (first 42 bytes)
+    // this allows E2E test to feed a custom authenticated address
+    let sender_bytes = extract_bytes(&data, 0, 42);
+    let sender_str = ascii::string(sender_bytes);
+
+    // extract target package address (bytes 42-74)
+    let target_bytes = extract_bytes(&data, 42, 74);
+    let target_package = from_bytes(target_bytes);
+
+    // extract receiver address (bytes 74-106)
+    let receiver_bytes = extract_bytes(&data, 74, 106);
+    let receiver = from_bytes(receiver_bytes);
+
+    (sender_str, target_package, receiver)
+}
+
+// helper function to extract a subslice of bytes from a vector
+fun extract_bytes(data: &vector<u8>, start: u64, end: u64): vector<u8> {
+    let mut result = vector::empty<u8>();
+    let mut i = start;
+
+    while (i < end) {
+        vector::push_back(&mut result, *vector::borrow(data, i));
+        i = i + 1;
+    };
+
+    result
+}

example/sources/token.move

@@ -0,0 +1,29 @@
+module example::token;
+
+use sui::coin::{Self, TreasuryCap};
+
+public struct TOKEN has drop {}
+
+fun init(witness: TOKEN, ctx: &mut TxContext) {
+    let (treasury, metadata) = coin::create_currency(
+        witness,
+        6,
+        b"TOKEN",
+        b"",
+        b"",
+        option::none(),
+        ctx,
+    );
+    transfer::public_freeze_object(metadata);
+    transfer::public_transfer(treasury, ctx.sender())
+}
+
+public entry fun mint(
+    treasury_cap: &mut TreasuryCap<TOKEN>,
+    amount: u64,
+    recipient: address,
+    ctx: &mut TxContext,
+) {
+    let coin = coin::mint(treasury_cap, amount, ctx);
+    transfer::public_transfer(coin, recipient)
+}