> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana programs and interfaces for Gateway

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](#program-derived-account-pdas)
and [instructions](#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

| Program         | Address                                                                                                                                   |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `GatewayWallet` | [`GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ`](https://solscan.io/account/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ?cluster=mainnet) |
| `GatewayMinter` | [`GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ`](https://solscan.io/account/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ?cluster=mainnet) |

## Devnet program addresses

| Program         | Address                                                                                                                                  |
| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `GatewayWallet` | [`GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu`](https://solscan.io/account/GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu?cluster=devnet) |
| `GatewayMinter` | [`GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr`](https://solscan.io/account/GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr?cluster=devnet) |

## 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:

* [`GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
* [`GatewayMinter` IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)

### `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](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/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](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)
for the canonical static account list.

<Info>
  For transfers to Solana, the `destinationRecipient` must be an initialized
  USDC Token Account. If the intended recipient is a standard wallet address,
  use its Associated Token Account (ATA), not the recipient wallet address
  itself.
</Info>

| 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.                         |

Three additional ordered accounts are required in the remaining accounts list
for each transfer in the attestation:

| 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                              |

In the common direct-mint flow, `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](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/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](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/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](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/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](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/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](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/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](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/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.

<Note>
  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.
</Note>

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account and argument definitions for `removeDelegate`.