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": "mainnet-beta",
      "rpc_urls": ["https://api.mainnet-beta.solana.com"],
      "explorer_urls": ["https://explorer.solana.com"],
      "average_blocktime_ms": 400,
      "is_testnet": false
    },
    {
      "from": "mainnet-beta",
      "type": "solana",
      "network": "testnet",
      "rpc_urls": ["https://api.testnet.solana.com"],
      "explorer_urls": ["https://explorer.solana.com?cluster=testnet"],
      "is_testnet": true
    }
  ]
}

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.88 or later
• Redis
• Docker (optional)

Example configuration for a Solana relayer with user fee payment (default):

{
  "id": "solana-user-pays",
  "name": "Solana User Pays Fees",
  "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": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "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
      }
    }
  }
}

Example configuration for a Solana relayer with relayer fee payment:

{
  "id": "solana-relayer-pays",
  "name": "Solana Relayer Pays Fees",
  "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": "relayer",
    "min_balance": 100000000
  }
}

For more configuration examples, visit the OpenZeppelin Relayer examples repository.

Configuration

Fee Payment Strategies

Solana relayers support two distinct fee payment strategies that determine who pays for transaction fees and how transactions are processed.

User Pays Fees (Default)

fee_payment_strategy: user (default when not specified)

In this mode:

• Users pay transaction fees in SPL tokens
• The relayer receives fee payment from the user as part of the transaction
• Users submit fully-formed, pre-signed transactions via the API
• The relayer validates and relays the transaction to the network

Relayer Pays Fees

fee_payment_strategy: relayer

In this mode:

• The relayer pays all transaction fees in SOL
• Users can submit either:
  • Encoded transactions (base64-encoded, pre-signed)
  • Array of instructions (relayer builds and signs the full transaction)

Use Cases:

• Simplified user experience (no fee token management)
• Backend-controlled transaction execution
• Automated workflows and scheduled operations
• Applications where the relayer subsidizes transaction costs

Additional Relayer Policies

• allowed_tokens: List of SPL tokens supported for swaps and fee payments. 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 set 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 relayer provides two API interfaces:

1. RPC Endpoint (JSON-RPC 2.0) - Conforms to the Paymaster spec

   • Best for: User fee payment mode
   • URL: POST /api/v1/relayers/<relayer_id>/rpc
   • Works in: Both fee payment modes

2. REST Endpoint - Direct transaction submission

   • Best for: Relayer fee payment mode
   • URL: POST /api/v1/relayers/<relayer_id>/transactions
   • Works in: Relayer fee payment mode only

RPC Endpoint (JSON-RPC 2.0)

Base URL: POST /api/v1/relayers/<relayer_id>/rpc

This endpoint can be used in both fee payment modes, but provides the best experience for user fee payment mode.

RPC Methods

• feeEstimate - Estimate transaction fees
• getSupportedTokens - Get list of supported tokens
• getSupportedFeatures - Get list of available features
• prepareTransaction - Prepare transaction with fee payments
• transferTransaction - Execute token transfers with fee payments
• signTransaction - Sign user-provided transactions
• signAndSendTransaction - Sign and relay user transactions

For complete RPC examples, see the SDK Solana examples.

REST Endpoint (Transaction Submission)

Base URL: POST /api/v1/relayers/<relayer_id>/transactions

Only available when fee_payment_strategy: "relayer"

This endpoint provides two ways to submit transactions:

Option 1: Encoded Transaction (Pre-signed)

Submit a base64-encoded, pre-signed transaction that the relayer will relay to the network.

Option 2: Array of Instructions (Relayer Builds Transaction)

Submit an array of Solana instructions. The relayer will:

1. Build a complete transaction from the provided instructions
2. Add necessary compute budget and priority fee instructions
3. Sign the transaction with the relayer's signer
4. Submit the transaction to the Solana network

For complete REST API examples with both options, see the SDK Solana examples.

API Summary

For User Fee Payment Mode (fee_payment_strategy: "user"):

• Use RPC endpoint: POST /api/v1/relayers/<relayer_id>/rpc
• Full Paymaster specification support
• Methods: feeEstimate, prepareTransaction, signAndSendTransaction, etc.

For Relayer Fee Payment Mode (fee_payment_strategy: "relayer"):

• Use REST endpoint: POST /api/v1/relayers/<relayer_id>/transactions
• Accepts encoded transactions or instruction arrays
• Alternative: RPC endpoint also works but REST is recommended

Additional Resources:

• API Reference Documentation - Complete API specification
• SDK Solana Examples - Working code examples for both RPC and REST endpoints

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.