Build
Connected Chains
Solana

To interact with universal applications from Solana, use the Solana Gateway. The Solana Gateway supports:

  • Depositing SOL to a universal app or an account on ZetaChain
  • Depositing supported SPL tokens
  • Depositing SOL and calling a universal app
  • Depositing supported SPL tokens and calling a universal app

To deposit SOL to an EOA or a universal contract, call the deposit instruction of the Solana Gateway program:

pub fn deposit(ctx: Context<Deposit>, amount: u64, receiver: [u8; 20]) -> Result<()>

The deposit instruction accepts SOL (in lamports) which will then be sent to a receiver on ZetaChain. Note that 1 SOL equals 1,000,000,000 lamports, so ensure you convert SOL amounts to lamports when specifying the amount parameter.

The receiver can be either an externally-owned account (EOA) or a universal app address on ZetaChain. Even if the receiver is a universal app contract with the standard receive function, the deposit instruction will not trigger a contract call. If you want to deposit and call a universal app, use the deposit_and_call instruction instead.

After the deposit is processed, the receiver receives the ZRC-20 version of the deposited token—for example, ZRC-20 SOL.

To deposit SPL tokens to an EOA or a universal contract, call the deposit_spl_token instruction:

pub fn deposit_spl_token(ctx: Context<DepositSplToken>, amount: u64, receiver: [u8; 20]) -> Result<()>

Only supported SPL tokens can be deposited. The receiver gets the ZRC-20 version of the deposited token (e.g., ZRC-20 USDC.SOL). SPL tokens must be whitelisted before they can be deposited through the gateway.

The amount specifies the quantity of SPL tokens to deposit.

To deposit SOL and call a universal app contract, use the deposit_and_call instruction:

pub fn deposit_and_call(ctx: Context<Deposit>, amount: u64, receiver: [u8; 20], message: Vec<u8>) -> Result<()>

After the cross-chain transaction is processed, the onCall function of the universal app contract is executed.

The receiver must be the address of a universal app contract.

When calling a universal app, the message is passed to onCall.

The deposit_spl_token_and_call instruction can be used to call a universal app contract and send SPL tokens:

pub fn deposit_spl_token_and_call(ctx: Context<DepositSplToken>, amount: u64, receiver: [u8; 20], message: Vec<u8>) -> Result<()>

Here, amount specifies the quantity of SPL tokens to deposit.

In the current version of the protocol, only one SPL token can be deposited at a time.

To withdraw ZRC-20 tokens and call a Solana program from a universal app on ZetaChain, use the withdrawAndCall function of the ZetaChain Gateway. The program being called on Solana must implement an on_call function.

The on_call function must have the following signature:

pub fn on_call(
    ctx: Context<OnCall>,
    amount: u64,
    sender: [u8; 20],
    data: Vec<u8>,
) -> Result<()>

The function receives:

  • amount: The amount of tokens being withdrawn
  • sender: The address of the universal app on ZetaChain that initiated the call
  • data: Additional data passed from the universal app

The program can handle both SOL and SPL token withdrawals. For SPL tokens, the program must include the necessary token accounts and mint account in its context.

When calling a Solana program from ZetaChain, the message payload must include both the program accounts and the data to be passed to the program. The payload is ABI-encoded as a tuple containing:

  1. An array of account metadata, where each account is specified as:

    • publicKey: The Solana public key of the account
    • isWritable: Whether the account can be modified by the program

  2. The data to be passed to the program's on_call function

The accounts array must include all required accounts for the program's on_call function.

For SOL token withdrawals, the accounts array must include:

  • Program PDA (writable)
  • Gateway PDA (read-only)
  • System program (read-only)

For SPL token withdrawals, the accounts array must include:

  • Program PDA (writable)
  • Program's associated token account (writable)
  • Mint account (read-only)
  • Gateway PDA (read-only)
  • Token program (read-only)
  • System program (read-only)

The data field can be any bytes that your program's on_call function expects to receive.

For a complete example of how to call a Solana program from a universal app, including message encoding and program implementation, check out the Solana example in the ZetaChain examples repository (opens in a new tab).

A deposit fee of 2,000,000 lamports (0.002 SOL) is charged for all deposits.

The Solana Gateway program includes several error codes to handle different failure scenarios:

  • SignerIsNotAuthority: The signer is not authorized to perform the action.
  • DepositPaused: Deposits are currently paused.
  • NonceMismatch: The provided nonce does not match the expected nonce.
  • TSSAuthenticationFailed: The TSS signature verification failed.
  • DepositToAddressMismatch: The deposit destination address does not match.
  • MessageHashMismatch: The message hash verification failed.
  • MemoLengthExceeded: The memo length exceeds the maximum allowed size.
  • SPLAtaAndMintAddressMismatch: The SPL token account address does not match the expected address.
  • EmptyReceiver: The receiver address is empty.
  • InvalidInstructionData: The instruction data is invalid.

The Solana Gateway supports transaction reverting in case of failures. If a cross-chain call fails on the ZetaChain side, the deposited tokens will be reverted back to the original sender on Solana.

To learn more about using the Solana Gateway in practice to deposit to and call universal apps, check out the Solana tutorial.