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

  • mainnet-beta

  • devnet

  • testnet

Supported Signers

  • vault_transit (hosted)

  • turnkey (hosted)

  • google_cloud_kms (hosted)

  • local (local)

  • vault (local)

  • vault_cloud (local)

In production systems, hosted signers are recommended for the best security model.

Quickstart

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

  • Rust 2021 edition

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

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)

  • allowed_tokens: List of SPL tokens supported for swaps 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.

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

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.

← Project Roadmap