The wallet and minter programs have a set of accounts and instructions that you
can use to build with Gateway on Solana. The following sections describe the
main Program Derived Account (PDA) structures
and instructions for the Gateway programs.
For static Solana accounts, instruction arguments, and instruction definitions,
use the onchain IDLs as the source of truth. This page adds high-level Gateway
guidance and documents the dynamic gatewayMint remaining accounts that are not
represented statically in the IDL.
Mainnet program addresses
Devnet program addresses
Account structures
The following section describes the main Program Derived Account (PDA)
structures for the Gateway programs. You can find the full IDLs for the Gateway
Solana programs at the following links:
GatewayDeposit
A Gateway Wallet data account used to track the balance of a particular
depositor and token.
| Parameter | Type | Description |
|---|
bump | u8 | The bump seed for the GatewayDeposit PDA. |
depositor | Pubkey | The depositor of the GatewayDeposit. |
token_mint | Pubkey | The mint of the token being deposited. |
available_amount | u64 | The available amount of the token. |
withdrawing_amount | u64 | The amount of the token pending withdrawal. |
withdrawal_block | u64 | The block number at which the withdrawal was initiated. |
GatewayDelegate
A Gateway Wallet data account used to store delegates.
| Parameter | Type | Description |
|---|
bump | u8 | The bump seed for the GatewayDelegate PDA. |
status | DelegateStatus | The status of the delegate. |
closeable_at_block | u64 | The block number at which the delegate can be closed. |
token | Pubkey | The mint of the token being delegated. |
depositor | Pubkey | The depositor of the delegate. |
delegate | Pubkey | The delegate address. |
Denylist
A Gateway Wallet data account used to store a single denylisted account. The
address being denylisted is implied in the PDA address, and the account itself
stores no additional data.
UsedTransferSpecHash
A Gateway Wallet data account used to store whether a TransferSpecHash has
been used, to prevent replay. The used TransferSpecHash is implied in the PDA
address, and the account itself stores no additional data.
PDA derivation
The following PDAs are used by the Gateway Solana programs. Seed bytes are ASCII
strings unless otherwise noted.
GatewayWallet program PDAs
| PDA | Program | Seeds |
|---|
GatewayWallet | GatewayWallet | ["gateway_wallet"] |
GatewayWalletCustody | GatewayWallet | ["gateway_wallet_custody", token_mint] |
GatewayDeposit | GatewayWallet | ["gateway_deposit", token_mint, depositor] |
Denylist | GatewayWallet | ["denylist", account] |
GatewayDelegate | GatewayWallet | ["gateway_delegate", token_mint, depositor, delegate] |
GatewayMinter program PDAs
| PDA | Program | Seeds |
|---|
GatewayMinter | GatewayMinter | ["gateway_minter"] |
GatewayMinterCustody | GatewayMinter | ["gateway_minter_custody", token_mint] |
UsedTransferSpecHash | GatewayMinter | ["used_transfer_spec_hash", transfer_spec_hash] |
GatewayMinter
Stores general configuration for the GatewayMinter program.
| Parameter | Type | Description |
|---|
bump | u8 | The bump seed for the GatewayMinter PDA. |
owner | Pubkey | The owner of the GatewayMinter. |
pending_owner | Pubkey | The pending owner of the GatewayMinter. |
pauser | Pubkey | The pauser of the GatewayMinter. |
token_controller | Pubkey | The token controller of the GatewayMinter. |
paused | bool | Whether the GatewayMinter is paused. |
enabled_attesters | Vec<Pubkey> | The enabled attesters of the GatewayMinter. |
local_domain | u32 | The local domain of the GatewayMinter. |
version | u32 | The version of the GatewayMinter. |
supported_tokens | Vec<Pubkey> | The supported tokens of the GatewayMinter. |
custody_token_account_bumps | Vec<u8> | The custody token account bumps of the GatewayMinter. |
GatewayWallet
Stores general configuration for the GatewayWallet program.
| Parameter | Type | Description |
|---|
bump | u8 | The bump seed for the GatewayWallet PDA. |
owner | Pubkey | The owner of the GatewayWallet. |
pending_owner | Pubkey | The pending owner of the GatewayWallet. |
pauser | Pubkey | The pauser of the GatewayWallet. |
denylister | Pubkey | The denylister of the GatewayWallet. |
token_controller | Pubkey | The token controller of the GatewayWallet. |
fee_recipient | Pubkey | The fee recipient of the GatewayWallet. |
local_domain | u32 | The local domain of the GatewayWallet. |
version | u32 | The version of the GatewayWallet. |
withdrawal_delay | u64 | The withdrawal delay of the GatewayWallet. |
paused | bool | Whether the GatewayWallet is paused. |
supported_tokens | Vec<Pubkey> | The supported tokens of the GatewayWallet. |
custody_token_account_bumps | Vec<u8> | The custody token account bumps of the GatewayWallet. |
burn_signers | Vec<Pubkey> | The burn signers of the GatewayWallet. |
Instructions
The following section describes the main instructions for the Gateway programs.
Instruction data uses Anchor-style Borsh encoding.
gatewayMint
Mints tokens to a recipient on Solana based on a signed attestation produced by
the Gateway API. The instruction supports two parameter encodings:
- Full attestation mode: Pass the full ReducedMintAttestation message and
its ECDSA signature as returned by the Transfer API.
- Parameter mode: Pass only the minimal fields that cannot be inferred
onchain; the program reconstructs the attestation and verifies the ECDSA
signature against it.
For the static instruction definition, refer to the
onchain GatewayMinter IDL.
The remaining accounts described below are dynamic and therefore are not
captured statically in the IDL.
Account list
The Gateway Mint flow uses fixed program accounts together with three additional
ordered accounts for each transfer in the attestation. Refer to the
onchain IDL
for the canonical static account list.
For transfers to Solana, the destinationRecipient must be an initialized
USDC Token Account. If the intended recipient is a standard wallet address,
consider setting the destinationRecipient to its Associated Token Account
(ATA) not the recipient wallet address. See the Solana Technical
Guide and Solana Programs
and Interfaces for
high-level Solana guidance and gatewayMint account requirements. Use the
onchain IDLs linked from Solana Programs and
Interfaces as the
canonical static instruction and account definitions. | Parameter | Type | Description |
|---|
payer | Signer | The payer of the transaction. |
destination_caller | Signer | The destination caller of the transaction. |
gateway_minter | Account<GatewayMinter> | The GatewayMinter account. |
system_program | Program<System> | The System program. |
token_program | Program<Token> | The Token program. |
| Parameter | Type | Description |
|---|
custody_token_account | Account<TokenAccount> | The custody token account of the token used in the transfer |
destination_recipient | Account<TokenAccount> | The destination recipient token account of the transfer |
transfer_spec_hash_account | Account<UsedTransferSpecHash> | The transfer spec hash account |
destination_caller is the transaction sender
and usually matches payer. If the attestation sets a non-zero
destinationCaller, it must match the signer that submits the mint transaction.
Full attestation mode (gateway_mint)
Pass the full reduced attestation bytes and signature returned by the Transfer
API. Refer to the
onchain IDL
for the canonical static argument definitions for gateway_mint and
gateway_mint_with_params.
Parameter mode (gateway_mint_with_params)
Saves transaction space by assuming certain fields or reading them from the
account list. Refer to the
onchain IDL
for the canonical static argument definitions for gateway_mint_with_params and
MintAttestationParams.
deposit
Deposits tokens into the Gateway Wallet system.
- Deposit mode: Deposits tokens on behalf of the signer. The tokens are
transferred from the signer’s token account to the Gateway Wallet custody and
tracked in the signer’s balance.
- Deposit For mode: Deposits tokens on behalf of another depositor. The
tokens are transferred from the signer’s token account to the Gateway Wallet
custody and tracked in the specified depositor’s balance.
Refer to the
onchain GatewayWallet IDL
for the canonical static account and argument definitions for deposit and
depositFor.
initiateWithdrawal
Starts the withdrawal process. After a program-defined withdrawal_delay (in
slots), withdraw may be called to complete the withdrawal. Repeated calls add
to the amount and reset the delay timer.
Refer to the
onchain GatewayWallet IDL
for the canonical static account and argument definitions for
initiateWithdrawal.
withdraw
Completes a withdrawal that was initiated at least withdrawal_delay earlier.
The full pending amount is withdrawn to the depositor’s token account.
Refer to the
onchain GatewayWallet IDL
for the canonical static account definitions for withdraw.
addDelegate
Allows a delegate to transfer the caller’s balance for the specified token.
Refer to the
onchain GatewayWallet IDL
for the canonical static account and argument definitions for addDelegate.
removeDelegate
Revokes a previously granted delegate for the caller’s balance of the specified
token.
Revocation is respected by the Gateway API, which refuses BurnIntents signed by
a revoked delegate. However, revocation does not prevent a BurnIntent signed by
the delegate from being executed onchain. This design prevents malicious users
from blocking a burn transaction by pre-emptively revoking a signer.
GatewayWallet IDL
for the canonical static account and argument definitions for removeDelegate. 
