Zetachain x Sui Gateway

https://github.com/zeta-chain/protocol-contracts-sui
Admin
This repository hosts smart contracts on the SUI network enabling ZetaChain's cross-chain...
Tokens:9,500
Snippets:39
Trust Score:9.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get Gateway Nonce

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Retrieves the current nonce value from the Gateway contract. The nonce is a monotonically increasing counter used for transaction sequencing or other internal logic.

```sui
public fun nonce(gateway: &Gateway): u64 {
    gateway.nonce
}
```

--------------------------------

### Coin Name Function in Sui

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Returns the string representation of a coin type. This function is a helper to get a consistent string identifier for different token types.

```sui
fun coin_name<T>(): String {
    into_string(get<T>())
}
```

--------------------------------

### Get Active Whitelist Cap ID

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Returns the object ID of the currently active WhitelistCap in the Gateway contract. This ID can be used to reference or interact with the active whitelisting capability.

```sui
public fun active_whitelist_cap(gateway: &Gateway): ID {
    gateway.active_whitelist_cap
}
```

--------------------------------

### Get Active Withdraw Cap ID

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Returns the object ID of the currently active WithdrawCap in the Gateway contract. This ID can be used to reference or interact with the active withdrawal capability.

```sui
public fun active_withdraw_cap(gateway: &Gateway): ID {
    gateway.active_withdraw_cap
}
```

--------------------------------

### Run Unit Tests

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/README.md

Executes the unit tests for the smart contracts using the SUI toolchain.

```sh
sui move test
```

--------------------------------

### Initialize Gateway Contract

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Initializes the gateway contract by creating and transferring necessary capability objects (WithdrawCap, WhitelistCap, AdminCap) and sharing the Gateway object. It also whitelists SUI by default.

```move
<b>fun</b> init(ctx: &<b>mut</b> TxContext) {
    <b>let</b> withdraw_cap = WithdrawCap {
        id: object::new(ctx),
    };
    <b>let</b> whitelist_cap = WhitelistCap {
        id: object::new(ctx),
    };
    <b>let</b> admin_cap = AdminCap {
        id: object::new(ctx),
    };
    <b>let</b> <b>mut</b> gateway = Gateway {
        id: object::new(ctx),
        vaults: bag::new(ctx),
        nonce: 0,
        active_withdraw_cap: object::id(&withdraw_cap),
        active_whitelist_cap: object::id(&whitelist_cap),
        deposit_paused: <b>false</b>,
    };
    whitelist_impl&lt;SUI&gt;(&<b>mut</b> gateway, &whitelist_cap);
    transfer::transfer(withdraw_cap, tx_context::sender(ctx));
    transfer::transfer(whitelist_cap, tx_context::sender(ctx));
    transfer::transfer(admin_cap, tx_context::sender(ctx));
    transfer::share_object(gateway);
}
```

--------------------------------

### Gateway Module Functions

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

This section details the various functions available within the Gateway module. It includes initialization, nonce management, deposit and withdrawal operations, whitelisting, pausing, and status checks.

```APIDOC
APIDOC:

Module: gateway::gateway

Functions:

- init(coin_type: ascii::String, treasury_cap: sui::coin::TreasuryCap<T>, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Initializes the Gateway module.
  - Parameters:
    - coin_type: The string representation of the coin type.
    - treasury_cap: The TreasuryCap for managing coin balances.
    - admin_cap: The AdminCap for administrative privileges.
    - ctx: The transaction context.
  - Returns: The initialized Gateway object.

- increase_nonce(gateway: &mut Gateway, ctx: &mut sui::tx_context::TxContext)
  - Increments the gateway's nonce.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - ctx: The transaction context.

- withdraw(gateway: &mut Gateway, withdraw_cap: WithdrawCap, coin_type: ascii::String, amount: u64, receiver: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Initiates a withdrawal from the gateway.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - withdraw_cap: The WithdrawCap for authorizing the withdrawal.
    - coin_type: The string representation of the coin type to withdraw.
    - amount: The amount to withdraw.
    - receiver: The address or identifier of the receiver.
    - ctx: The transaction context.

- whitelist(gateway: &mut Gateway, whitelist_cap: WhitelistCap, address: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Adds an address to the whitelist.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - whitelist_cap: The WhitelistCap for authorizing the whitelisting.
    - address: The address to whitelist.
    - ctx: The transaction context.

- unwhitelist(gateway: &mut Gateway, whitelist_cap: WhitelistCap, address: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Removes an address from the whitelist.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - whitelist_cap: The WhitelistCap for authorizing the unwhitelisting.
    - address: The address to unwhitelist.
    - ctx: The transaction context.

- issue_withdraw_and_whitelist_cap(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Issues new WithdrawCap and WhitelistCap.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- pause(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Pauses deposit operations.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- unpause(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Unpauses deposit operations.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- reset_nonce(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Resets the gateway's nonce to 0.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- deposit(gateway: &mut Gateway, coin: Coin<T>, receiver: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Deposits a coin into the gateway.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - coin: The coin to deposit.
    - receiver: The recipient of the deposit.
    - ctx: The transaction context.

- deposit_and_call(gateway: &mut Gateway, coin: Coin<T>, receiver: ascii::String, module: ascii::String, function: ascii::String, args: vector::Vector<ascii::String>, ctx: &mut sui::tx_context::TxContext)
  - Deposits a coin and calls a specified function.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - coin: The coin to deposit.
    - receiver: The recipient of the deposit.
    - module: The module to call.
    - function: The function to call.
    - args: Arguments for the called function.
    - ctx: The transaction context.

- donate(gateway: &mut Gateway, coin: Coin<T>, ctx: &mut sui::tx_context::TxContext)
  - Donates a coin to the gateway's treasury.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - coin: The coin to donate.
    - ctx: The transaction context.

- check_receiver_and_deposit_to_vault(gateway: &mut Gateway, coin: Coin<T>, receiver: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Checks receiver validity and deposits coin to the vault.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - coin: The coin to deposit.
    - receiver: The recipient of the deposit.
    - ctx: The transaction context.

- withdraw_impl(gateway: &mut Gateway, withdraw_cap: WithdrawCap, coin_type: ascii::String, amount: u64, receiver: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for withdrawal.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - withdraw_cap: The WithdrawCap for authorization.
    - coin_type: The string representation of the coin type.
    - amount: The amount to withdraw.
    - receiver: The receiver's address or identifier.
    - ctx: The transaction context.

- whitelist_impl(gateway: &mut Gateway, whitelist_cap: WhitelistCap, address: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for whitelisting.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - whitelist_cap: The WhitelistCap for authorization.
    - address: The address to whitelist.
    - ctx: The transaction context.

- unwhitelist_impl(gateway: &mut Gateway, whitelist_cap: WhitelistCap, address: ascii::String, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for unwhitelisting.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - whitelist_cap: The WhitelistCap for authorization.
    - address: The address to unwhitelist.
    - ctx: The transaction context.

- issue_withdraw_and_whitelist_cap_impl(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for issuing capability tokens.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- pause_impl(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for pausing deposits.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- unpause_impl(gateway: &mut Gateway, admin_cap: AdminCap, ctx: &mut sui::tx_context::TxContext)
  - Internal implementation for unpausing deposits.
  - Parameters:
    - gateway: A mutable reference to the Gateway object.
    - admin_cap: The AdminCap for authorization.
    - ctx: The transaction context.

- nonce(gateway: &Gateway) -> u64
  - Returns the current nonce of the gateway.
  - Parameters:
    - gateway: A reference to the Gateway object.
  - Returns: The current nonce value.

- active_withdraw_cap(gateway: &Gateway) -> sui::object::ID
  - Returns the ID of the active withdraw capability.
  - Parameters:
    - gateway: A reference to the Gateway object.
  - Returns: The ID of the active withdraw capability.

- active_whitelist_cap(gateway: &Gateway) -> sui::object::ID
  - Returns the ID of the active whitelist capability.
  - Parameters:
    - gateway: A reference to the Gateway object.
  - Returns: The ID of the active whitelist capability.

- vault_balance&lt;T&gt;(gateway: &Gateway, vault_id: sui::object::ID) -> u64
  - Returns the balance of a specific vault.
  - Parameters:
    - gateway: A reference to the Gateway object.
    - vault_id: The ID of the vault.
  - Returns: The balance of the vault.

- is_paused(gateway: &Gateway) -> bool
  - Checks if deposit operations are paused.
  - Parameters:
    - gateway: A reference to the Gateway object.
  - Returns: True if paused, false otherwise.

- is_whitelisted(gateway: &Gateway, address: ascii::String) -> bool
  - Checks if an address is whitelisted.
  - Parameters:
    - gateway: A reference to the Gateway object.
    - address: The address to check.
  - Returns: True if whitelisted, false otherwise.

- coin_name(gateway: &Gateway) -> ascii::String
  - Returns the name of the coin managed by the gateway.
  - Parameters:
    - gateway: A reference to the Gateway object.
  - Returns: The coin name.

```

--------------------------------

### Sui Module Imports

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Lists the various modules imported from the Sui framework and standard library for use within the Gateway module.

```rust
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;
use sui::address;
use sui::bag;
use sui::balance;
use sui::coin;
use sui::config;
use sui::deny_list;
use sui::dynamic_field;
use sui::dynamic_object_field;
use sui::event;
use sui::hex;
use sui::object;
use sui::party;
use sui::sui;
use sui::table;
use sui::transfer;
use sui::tx_context;
use sui::types;
use sui::url;
use sui::vec_map;
use sui::vec_set;
```

--------------------------------

### Publish Smart Contracts

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/README.md

Publishes the smart contracts to the SUI network using the SUI client.

```sh
sui client publish
```

--------------------------------

### Whitelist Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Adds a token to the gateway's whitelist. Requires a gateway mutable reference and a WhitelistCap. It calls an internal implementation function `whitelist_impl`.

```sui
entry fun whitelist<T>(gateway: &mut Gateway, cap: &WhitelistCap) {
    whitelist_impl<T>(gateway, cap)
}
```

--------------------------------

### Deposit and Call Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Handles depositing coins and executing a call with a given payload. It includes checks for payload length and emits a DepositAndCallEvent upon successful execution. Dependencies include the gateway module, sui::coin, std::ascii::String, vector, and sui::tx_context.

```sui
public entry fun deposit_and_call<T>(
    gateway: &mut Gateway,
    coins: Coin<T>,
    receiver: String,
    payload: vector<u8>,
    ctx: &mut TxContext,
) {
    assert!(payload.length() <= PayloadMaxLength, EPayloadTooLong);
    let amount = coins.value();
    let coin_name = coin_name<T>();
    check_receiver_and_deposit_to_vault(gateway, coins, receiver);
    // Emit deposit event
    event::emit(DepositAndCallEvent {
        coin_type: coin_name,
        amount: amount,
        sender: tx_context::sender(ctx),
        receiver: receiver,
        payload: payload,
    });
}
```

--------------------------------

### APIDOC: Gateway EVM Functions

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/evm.md

API documentation for functions within the Gateway EVM module, including address validation and hex character checking.

```APIDOC
Module gateway::evm

Functions:

- is_valid_evm_address(addr: std::ascii::String): bool
  Checks if a given string is a valid Ethereum address.
  An Ethereum address must be 42 characters long, start with '0x', and the remaining characters must be hexadecimal.

- is_hex_vec(input: vector<u8>): bool
  Checks if a vector of bytes contains only hexadecimal characters (0-9, a-f, A-F).
  This is a helper function used by `is_valid_evm_address`.
```

--------------------------------

### Withdraw Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Implements the withdrawal logic for tokens from the gateway. It verifies the withdraw capability, token whitelist status, and nonce for replay protection. It then withdraws the specified amount of the token and the required SUI for gas. Dependencies include gateway, sui::coin, sui::sui, bag, and object modules.

```sui
public fun withdraw_impl<T>(
    gateway: &mut Gateway,
    amount: u64,
    nonce: u64,
    gas_budget: u64,
    cap: &WithdrawCap,
    ctx: &mut TxContext,
): (Coin<T>, Coin<sui::sui::SUI>) {
    assert!(gateway.active_withdraw_cap == object::id(cap), EInactiveWithdrawCap);
    assert!(is_whitelisted<T>(gateway), ENotWhitelisted);
    assert!(nonce == gateway.nonce, ENonceMismatch); // prevent replay
    gateway.nonce = nonce + 1;
    // Withdraw the coin from the vault
    let coin_name = coin_name<T>();
    let vault = bag::borrow_mut<String, Vault<T>>(&mut gateway.vaults, coin_name);
    let coins_out = coin::take(&mut vault.balance, amount, ctx);
    // Withdraw SUI to cover the gas budget
    let sui_vault = bag::borrow_mut<String, Vault<sui::sui::SUI>>(
        &mut gateway.vaults,
        coin_name<sui::sui::SUI>(),
    );
    let coins_gas_budget = coin::take(&mut sui_vault.balance, gas_budget, ctx);
    (coins_out, coins_gas_budget)
}
```

--------------------------------

### Whitelist Asset Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Adds or updates an asset to the whitelist in the Gateway contract. It asserts that the provided whitelist capability is active and the asset is not already whitelisted. If a vault for the asset exists, it marks it as whitelisted; otherwise, it creates a new vault.

```sui
public fun whitelist_impl<T>(gateway: &mut Gateway, cap: &WhitelistCap) {
    assert!(gateway.active_whitelist_cap == object::id(cap), EInactiveWhitelistCap);
    assert!(is_whitelisted<T>(gateway) == false, EAlreadyWhitelisted);
    // if the vault already exists, set it to whitelisted, otherwise create a new vault
    if (bag::contains_with_type<String, Vault<T>>(&gateway.vaults, coin_name<T>())) {
        let vault = bag::borrow_mut<String, Vault<T>>(&mut gateway.vaults, coin_name<T>());
        vault.whitelisted = true;
    } else {
        let vault_name = coin_name<T>();
        let vault = Vault<T> {
            balance: balance::zero<T>(),
            whitelisted: true,
        };
        bag::add(&mut gateway.vaults, vault_name, vault);
    }
}
```

--------------------------------

### DepositAndCallEvent Structure

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines the structure for a deposit and call event, including coin type, amount, sender, receiver, and payload.

```move
<b>public</b> <b>struct</b> DepositAndCallEvent <b>has</b> <b>copy</b>, drop {
coin_type: std::ascii::String,
amount: u64,
sender: <b>address</b>,
receiver: std::ascii::String,
payload: vector&lt;u8&gt;
}
```

--------------------------------

### Issue Withdraw and Whitelist Cap Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Issues new withdraw and whitelist capabilities. It takes a gateway mutable reference, an AdminCap, and the transaction context. It calls `issue_withdraw_and_whitelist_cap_impl` and transfers the resulting capabilities to the sender.

```sui
entry fun issue_withdraw_and_whitelist_cap(
    gateway: &mut Gateway,
    _cap: &AdminCap,
    ctx: &mut TxContext,
) {
    let (withdraw_cap, whitelist_cap) = issue_withdraw_and_whitelist_cap_impl(gateway, _cap, ctx);
    transfer::transfer(withdraw_cap, tx_context::sender(ctx));
    transfer::transfer(whitelist_cap, tx_context::sender(ctx));
}
```

--------------------------------

### Issue Withdraw and Whitelist Caps Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Issues new WithdrawCap and WhitelistCap objects and updates the gateway's active cap IDs. This function requires an AdminCap to authorize the operation and a TxContext for object creation.

```sui
public fun issue_withdraw_and_whitelist_cap_impl(
    gateway: &mut Gateway,
    _cap: &AdminCap,
    ctx: &mut TxContext,
): (WithdrawCap, WhitelistCap) {
    let withdraw_cap = WithdrawCap {
        id: object::new(ctx),
    };
    let whitelist_cap = WhitelistCap {
        id: object::new(ctx),
    };
    gateway.active_withdraw_cap = object::id(&withdraw_cap);
    gateway.active_whitelist_cap = object::id(&whitelist_cap);
    (withdraw_cap, whitelist_cap)
}
```

--------------------------------

### Check Receiver and Deposit to Vault

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

A helper function to validate a receiver address and deposit coins into the appropriate vault. It checks for valid EVM addresses, whitelisted token types, and if deposits are paused. Dependencies include gateway, sui::coin, bag, balance, and evm modules.

```sui
fun check_receiver_and_deposit_to_vault<T>(
    gateway: &mut Gateway,
    coins: Coin<T>,
    receiver: String,
) {
    assert!(evm::is_valid_evm_address(receiver), EInvalidReceiverAddress);
    assert!(is_whitelisted<T>(gateway), ENotWhitelisted);
    assert!(!gateway.deposit_paused, EDepositPaused);
    // Deposit the coin into the vault
    let coin_name = coin_name<T>();
    let vault = bag::borrow_mut<String, Vault<T>>(&mut gateway.vaults, coin_name);
    balance::join(&mut vault.balance, coins.into_balance());
}
```

--------------------------------

### Deposit Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Handles the deposit of assets into the gateway. It takes a gateway mutable reference, a Coin of generic type T, a receiver string, and the transaction context. It checks the receiver and deposits to the vault, emitting a DepositEvent.

```sui
public entry fun deposit<T>(
    gateway: &mut Gateway,
    coins: Coin<T>,
    receiver: String,
    ctx: &mut TxContext,
) {
    let amount = coins.value();
    let coin_name = coin_name<T>();
    check_receiver_and_deposit_to_vault(gateway, coins, receiver);
    // Emit deposit event
    event::emit(DepositEvent {
        coin_type: coin_name,
        amount: amount,
        sender: tx_context::sender(ctx),
        receiver: receiver,
    });
}
```

--------------------------------

### DonateEvent Structure

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines the structure for a donation event, including coin type, amount, and sender.

```move
<b>public</b> <b>struct</b> DonateEvent <b>has</b> <b>copy</b>, drop {
coin_type: std::ascii::String,
amount: u64,
sender: <b>address</b>
}
```

--------------------------------

### Validate EVM Address

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/evm.md

Implementation to check if a given string is a valid Ethereum address. It verifies the length, the '0x' prefix, and that the remaining characters are hexadecimal.

```rust
use std::ascii;
use std::option;
use std::vector;

public fun is_valid_evm_address(addr: std::ascii::String): bool {
    if (addr.length() != 42) {
        return false
    };
    let mut addrBytes = addr.into_bytes();
    // check prefix 0x, 0=48, x=120
    if (addrBytes[0] != 48 || addrBytes[1] != 120) {
        return false
    };
    // remove 0x prefix
    addrBytes.remove(0);
    addrBytes.remove(0);
    // check if remaining characters are hex (0-9, a-f, A-F)
    is_hex_vec(addrBytes)
}
```

--------------------------------

### Protocol Constants

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines various error codes and constants used within the protocol, such as EAlreadyWhitelisted, EInvalidReceiverAddress, and PayloadMaxLength.

```move
<b>const</b> EAlreadyWhitelisted: u64 = 0;
<b>const</b> EInvalidReceiverAddress: u64 = 1;
<b>const</b> ENotWhitelisted: u64 = 2;
<b>const</b> ENonceMismatch: u64 = 3;
<b>const</b> EPayloadTooLong: u64 = 4;
<b>const</b> EInactiveWithdrawCap: u64 = 5;
<b>const</b> EInactiveWhitelistCap: u64 = 6;
<b>const</b> EDepositPaused: u64 = 7;
<b>const</b> PayloadMaxLength: u64 = 1024;
```

--------------------------------

### Gateway Module Structs

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines the core data structures used within the Gateway module, including Vault, Gateway, and various capability and event structs.

```APIDOC
APIDOC:

Module: gateway::gateway

Structs:

- Vault&lt;T&gt;
  - Represents a vault holding a balance and whitelisting status.
  - Fields:
    - balance: sui::balance::Balance&lt;T&gt; - The balance of the vault.
    - whitelisted: bool - Indicates if the vault is whitelisted.

- Gateway
  - The main Gateway object managing operations.
  - Fields:
    - id: sui::object::UID - The unique identifier for the Gateway.
    - vaults: sui::bag::Bag - A bag storing associated vaults.
    - nonce: u64 - A counter for transaction nonces.
    - active_withdraw_cap: sui::object::ID - The ID of the currently active withdraw capability.
    - active_whitelist_cap: sui::object::ID - The ID of the currently active whitelist capability.
    - deposit_paused: bool - Flag indicating if deposit operations are paused.

- WithdrawCap
  - Capability token for authorizing withdrawals.
  - Fields:
    - id: sui::object::UID - The unique identifier for the WithdrawCap.

- WhitelistCap
  - Capability token for authorizing whitelisting operations.
  - Fields:
    - id: sui::object::UID - The unique identifier for the WhitelistCap.

- AdminCap
  - Capability token for administrative privileges.
  - Fields:
    - id: sui::object::UID - The unique identifier for the AdminCap.

- DepositEvent
  - Event emitted upon a successful deposit.
  - Fields:
    - coin_type: std::ascii::String - The type of coin deposited.
    - amount: u64 - The amount of coin deposited.
    - sender: address - The address of the sender.
    - receiver: std::ascii::String - The recipient of the deposit.

- DepositAndCallEvent
  - Event emitted upon a successful deposit and subsequent function call.
  - Fields:
    - coin_type: std::ascii::String - The type of coin deposited.
    - amount: u64 - The amount of coin deposited.
    - sender: address - The address of the sender.
    - receiver: std::ascii::String - The recipient of the deposit.
    - module: std::ascii::String - The module that was called.
    - function: std::ascii::String - The function that was called.
    - args: vector::Vector&lt;std::ascii::String&gt; - Arguments passed to the called function.

- WithdrawEvent
  - Event emitted upon a successful withdrawal.
  - Fields:
    - coin_type: std::ascii::String - The type of coin withdrawn.
    - amount: u64 - The amount of coin withdrawn.
    - sender: address - The address initiating the withdrawal.
    - receiver: std::ascii::String - The recipient of the withdrawal.

- NonceIncreaseEvent
  - Event emitted when the gateway's nonce is increased.
  - Fields:
    - nonce: u64 - The new nonce value.
    - sender: address - The address that triggered the nonce increase.

- DonateEvent
  - Event emitted upon a successful donation.
  - Fields:
    - coin_type: std::ascii::String - The type of coin donated.
    - amount: u64 - The amount of coin donated.
    - sender: address - The address of the donor.

```

--------------------------------

### Donate Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Allows users to donate coins to the protocol. This function deposits the provided coins into the vault, using a zero address as the receiver to signify a donation. It emits a DonateEvent upon completion. Dependencies include the gateway module, sui::coin, and sui::tx_context.

```sui
public entry fun donate<T>(
    gateway: &mut Gateway,
    coins: Coin<T>,
    ctx: &mut TxContext,
) {
    let amount = coins.value();
    let coin_name = coin_name<T>();
    // use check_receiver_and_deposit_to_vault to deposit and provide the zero address as receiver
    // receiver is only passed to the function to ensure the address is valid
    check_receiver_and_deposit_to_vault(gateway, coins, string(b"0x0000000000000000000000000000000000000000"));
    // Emit donate event
    event::emit(DonateEvent {
        coin_type: coin_name,
        amount: amount,
        sender: tx_context::sender(ctx),
    });
}
```

--------------------------------

### Vault Balance Function in Sui

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Retrieves the balance of a specific token's vault. It first checks if the token is whitelisted and returns 0 if not. Otherwise, it fetches the vault and returns its balance value.

```sui
public fun vault_balance<T>(gateway: &gateway::gateway::Gateway): u64 {
    if (!is_whitelisted<T>(gateway)) {
        return 0
    };
    let coin_name = coin_name<T>();
    let vault = bag::borrow<String, Vault<T>>(&gateway.vaults, coin_name);
    balance::value(&vault.balance)
}
```

--------------------------------

### Pause Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Pauses the gateway operations. Requires a gateway mutable reference and an AdminCap. It calls the internal `pause_impl` function.

```sui
entry fun pause(gateway: &mut Gateway, cap: &AdminCap) {
    pause_impl(gateway, cap)
}
```

--------------------------------

### WithdrawEvent Structure

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines the structure for a withdrawal event, including coin type, amount, sender, receiver, and nonce.

```move
<b>public</b> <b>struct</b> WithdrawEvent <b>has</b> <b>copy</b>, drop {
coin_type: std::ascii::String,
amount: u64,
sender: <b>address</b>,
receiver: <b>address</b>,
nonce: u64
}
```

--------------------------------

### NonceIncreaseEvent Structure

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Defines the structure for a nonce increase event, including the sender and the new nonce value.

```move
<b>public</b> <b>struct</b> NonceIncreaseEvent <b>has</b> <b>copy</b>, drop {
sender: <b>address</b>,
nonce: u64
}
```

--------------------------------

### Unwhitelist Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Removes a token from the gateway's whitelist. Requires a gateway mutable reference and an AdminCap. It calls an internal implementation function `unwhitelist_impl`.

```sui
entry fun unwhitelist<T>(gateway: &mut Gateway, cap: &AdminCap) {
    unwhitelist_impl<T>(gateway, cap)
}
```

--------------------------------

### Unwhitelist Asset Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Removes an asset from the whitelist in the Gateway contract. It asserts that the asset is currently whitelisted before proceeding to mark its vault as not whitelisted.

```sui
public fun unwhitelist_impl<T>(gateway: &mut Gateway, _cap: &AdminCap) {
    assert!(is_whitelisted<T>(gateway), ENotWhitelisted);
    let vault = bag::borrow_mut<String, Vault<T>>(&mut gateway.vaults, coin_name<T>());
    vault.whitelisted = false;
}
```

--------------------------------

### Pause Deposits Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Sets the deposit_paused flag to true for the Gateway contract, effectively pausing all incoming deposits. This operation requires an AdminCap.

```sui
public fun pause_impl(gateway: &mut Gateway, _cap: &AdminCap) {
    gateway.deposit_paused = true;
}
```

--------------------------------

### Withdraw Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Handles the withdrawal of assets from the gateway. It takes the gateway, amount, nonce, receiver address, gas budget, a withdraw capability, and transaction context as input. It returns transferred coins and gas budget coins.

```sui
entry fun withdraw<T>(
    gateway: &mut Gateway,
    amount: u64,
    nonce: u64,
    receiver: address,
    gas_budget: u64,
    cap: &WithdrawCap,
    ctx: &mut TxContext,
) {
    let (coins, coins_gas_budget) = withdraw_impl<T>(gateway, amount, nonce, gas_budget, cap, ctx);
    transfer::public_transfer(coins, receiver);
    transfer::public_transfer(coins_gas_budget, tx_context::sender(ctx));
    // Emit event
    event::emit(WithdrawEvent {
        coin_type: coin_name<T>(),
        amount: amount,
        sender: tx_context::sender(ctx),
        receiver: receiver,
        nonce: nonce,
    });
}
```

--------------------------------

### Unpause Deposits Implementation

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Sets the deposit_paused flag to false for the Gateway contract, resuming all incoming deposits. This operation requires an AdminCap.

```sui
public fun unpause_impl(gateway: &mut Gateway, _cap: &AdminCap) {
    gateway.deposit_paused = false;
}
```

--------------------------------

### Unpause Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Unpauses the gateway operations. Requires a gateway mutable reference and an AdminCap. It calls the internal `unpause_impl` function.

```sui
entry fun unpause(gateway: &mut Gateway, cap: &AdminCap) {
    unpause_impl(gateway, cap)
}
```

--------------------------------

### Increase Nonce Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Increases the nonce for the gateway contract. It requires an active WithdrawCap and checks for nonce mismatch before incrementing and emitting a NonceIncreaseEvent.

```move
<b>entry</b> <b>fun</b> increase_nonce(gateway: &<b>mut</b> Gateway, nonce: u64, cap: &WithdrawCap, ctx: &TxContext) {
    <b>assert</b>!(gateway.active_withdraw_cap == object::id(cap), EInactiveWithdrawCap);
    <b>assert</b>!(nonce == gateway.nonce, ENonceMismatch);
    gateway.nonce = nonce + 1;
    event::emit(NonceIncreaseEvent {
        sender: tx_context::sender(ctx),
        nonce: gateway.nonce,
    });
}
```

--------------------------------

### Reset Nonce Function

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Resets the gateway's nonce to a new value. Requires a gateway mutable reference, the new nonce, and an AdminCap. It directly updates the gateway's nonce field.

```sui
entry fun reset_nonce(gateway: &mut Gateway, nonce: u64, _cap: &AdminCap) {
    gateway.nonce = nonce;
}
```

--------------------------------

### Check for Hexadecimal Characters in Vector

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/evm.md

Implementation to verify that a vector of bytes contains only hexadecimal characters. This function iterates through the vector and checks each byte against the valid hex ranges.

```rust
use std::ascii;
use std::option;
use std::vector;

fun is_hex_vec(input: vector<u8>): bool {
    let mut i = 0;
    let len = input.length();
    while (i < len) {
        let c = input[i];
        let is_hex = (c >= 48 && c <= 57) ||  // '0' to '9'
                     (c >= 97 && c <= 102) || // 'a' to 'f'
                     (c >= 65 && c <= 70);    // 'A' to 'F'
        if (!is_hex) {
            return false
        };
        i = i + 1;
    };
    true
}
```

--------------------------------

### Is Whitelisted Function in Sui

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Determines if a given token type is whitelisted in the gateway. It checks for the presence of the token's vault and then verifies the `whitelisted` status of that vault.

```sui
public fun is_whitelisted<T>(gateway: &gateway::gateway::Gateway): bool {
    let vault_name = coin_name<T>();
    if (!bag::contains_with_type<String, Vault<T>>(&gateway.vaults, vault_name)) {
        return false
    };
    let vault = bag::borrow<String, Vault<T>>(&gateway.vaults, vault_name);
    vault.whitelisted
}
```

--------------------------------

### Is Paused Function in Sui

Source: https://github.com/zeta-chain/protocol-contracts-sui/blob/main/docs/gateway.md

Checks if the deposit functionality is currently paused. This function directly accesses the `deposit_paused` boolean field of the Gateway object.

```sui
public fun is_paused(gateway: &gateway::gateway::Gateway): bool {
    gateway.deposit_paused
}
```
Tokens:
Raw