Solana Integration

Overview

OpenZeppelin Relayer provides robust support for Solana networks, enabling secure transaction relaying, automated token swaps, gasless transactions, and advanced fee management. This page covers everything you need to get started and make the most of Solana-specific features.

Features

• Automated token swaps via Jupiter DEX (mainnet-beta only)
• Gasless transactions (user or relayer pays fees)
• Secure transaction signing with multiple signer backends
• Transaction status monitoring and nonce management
• Custom RPC endpoints and network policies
• Metrics and observability

Supported Networks

Solana networks are defined via JSON configuration files, providing flexibility to:

• Configure standard Solana clusters: mainnet-beta, devnet, testnet
• Set up custom Solana-compatible networks with specific RPC endpoints
• Create network variants using inheritance from base configurations

Example Solana network configurations:

{
  "networks": [
    {
      "type": "solana",
      "network": "solana-mainnet",
      "rpc_urls": ["https://api.mainnet-beta.solana.com"],
      "explorer_urls": ["https://explorer.solana.com"],
      "is_testnet": false,
      "tags": ["mainnet", "solana"]
    },
    {
      "type": "solana",
      "network": "solana-devnet",
      "rpc_urls": ["https://api.devnet.solana.com"],
      "explorer_urls": ["https://explorer.solana.com?cluster=devnet"],
      "is_testnet": true,
      "tags": ["devnet", "solana"]
    },
    {
      "type": "solana",
      "network": "solana-custom",
      "rpc_urls": ["https://your-custom-solana-rpc.example.com"],
      "tags": ["custom", "solana"]
    }
  ]
}

For detailed network configuration options, see the Network Configuration guide.

Supported Signers

• vault_transit (hosted)
• turnkey (hosted)
• google_cloud_kms (hosted)
• local (local)
• vault (local)
• cdp (hosted)

Quickstart

For a step-by-step setup, see Quick Start Guide. Key prerequisites:

• Rust 2021, version 1.86 or later
• Redis
• Docker (optional)

Example configuration for a Solana relayer:

{
  "id": "solana-example",
  "name": "Solana Example",
  "network": "devnet",
  "paused": false,
  "notification_id": "notification-example",
  "signer_id": "local-signer",
  "network_type": "solana",
  "custom_rpc_urls": [
    { "url": "https://primary-solana-rpc.example.com", "weight": 100 },
    { "url": "https://backup-solana-rpc.example.com", "weight": 100 }
  ],
  "policies": {
    "fee_payment_strategy": "user",
    "min_balance": 0,
    "allowed_tokens": [
      { "mint": "So111...", "max_allowed_fee": 100000000 }
    ],
    "swap_config": {
      "strategy": "jupiter-swap",
      "cron_schedule": "0 0 * * * *",
      "min_balance_threshold": 1000000,
      "jupiter_swap_options": {
        "dynamic_compute_unit_limit": true,
        "priority_level": "high",
        "priority_fee_max_lamports": 1000000000
      }
    }
  }
}

For more configuration examples, visit the OpenZeppelin Relayer examples repository, window=_blank.

Configuration

Relayer Policies

In addition to standard relayer configuration and policies, Solana relayers support additional options:

• fee_payment_strategy: "user" or "relayer" (who pays transaction fees). "user" is default value.
  • "user": Users pay transaction fees in tokens (relayer receives fee payment from user)
  • "relayer": Relayer pays for all transaction fees using SOL from the relayer’s account
• allowed_tokens: List of SPL tokens supported for swaps and fee payments. Restrict relayer operations to specific tokens. Optional.
  • When not set or empty, all tokens are allowed for transactions and fee payments
  • When configured, only tokens in this list can be used for transfers and fee payments
• allowed_programs, allowed_accounts, disallowed_accounts: Restrict relayer operations to specific programs/accounts
• swap_config: Automated token swap settings (see below)

You can check all options in User Documentation - Relayers.

Automated token swap configuration options:

• strategy: The swap engine to use. Supported values: "jupiter-swap" (Jupiter Swap API), "jupiter-ultra" (Jupiter Ultra API).
• cron_schedule: Cron expression defining how often scheduled swaps should run (e.g., "0 0 * * * *" for every hour).
• min_balance_threshold: Minimum token balance (in lamports) that triggers a swap. If the relayer’s balance drops below this, a swap is attempted.
• jupiter_swap_options: Advanced options for Jupiter swaps, such as:
  • dynamic_compute_unit_limit: If true, dynamically adjusts compute units for swap transactions.
  • priority_level: Priority for the swap transaction. Supported values: "medium", "high", "veryHigh".
  • priority_fee_max_lamports: Maximum priority fee (in lamports) to pay for a swap transaction.
• Per-token swap limits:
  • min_amount: Minimum amount of a token to swap in a single operation.
  • max_amount: Maximum amount of a token to swap in a single operation.
  • retain_min_amount: Minimum amount of a token to retain in the relayer account after a swap (prevents swapping the entire balance).

Automated Token Swaps

The relayer can perform automated token swaps on Solana when user fee_payment_strategy is used for relayer using:

• jupiter-swap – via the Jupiter Swap API
• jupiter-ultra – via the Jupiter Ultra API

Swaps can be set to work as:

• Scheduled Swaps: Background jobs run swaps based on your cron schedule.
• On-Demand Swaps: If a transaction fails due to insufficient funds, the relayer attempts a swap before returning an error.

API Reference

The Solana API conforms to the Paymaster spec, window=_blank.

Common endpoints:

• POST /api/v1/relayers/<relayer_id>/rpc Methods:

• feeEstimate,
• prepareTransaction,
• transferTransaction,
• signTransaction,
• signAndSendTransaction,
• getSupportedTokens
• getSupportedFeatures

Example: Estimate fee for a transaction

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "feeEstimate",
  "params": {
    "transaction": "<base64-encoded-tx>",
    "fee_token": "<mint-address>"
  },
  "id": 1
}'

See API Reference and SDK examples, window=_blank for full details and examples.

Security

• Do not expose the relayer directly to the public internet.
• Deploy behind a secure backend (reverse proxy, firewall).
• Use hosted signers in production systems.

Troubleshooting

• Check environment variables and configuration files for errors
• Review container logs for issues

Roadmap

• See Project Roadmap for upcoming features

Support

For help, join our Telegram or open an issue on GitHub.

License

This project is licensed under the GNU Affero General Public License v3.0.