Stellar Integration

Overview

OpenZeppelin Relayer provides comprehensive support for Stellar networks, enabling secure transaction relaying, Soroban smart contract operations, and advanced transaction management. This integration supports both standard Stellar operations and the latest Soroban smart contract functionality.

Features

• Full Soroban smart contract support (invocation, deployment, WASM uploads)
• Standard Stellar payment operations
• Support for all Stellar operations via XDR transaction submission
• Fee bump transaction support
• Secure transaction signing with multiple signer backends
• Transaction status monitoring and sequence number management
• Custom RPC endpoints and network policies
• Metrics and observability

Supported Networks

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

• Configure standard Stellar clusters: mainnet, testnet
• Set up custom Stellar-compatible networks with specific RPC endpoints
• Define network passphrases for proper transaction signing

Example Stellar network configurations:

{
  "networks": [
    {
      "type": "stellar",
      "network": "mainnet",
      "rpc_urls": ["https://mainnet.sorobanrpc.com"],
      "explorer_urls": ["https://stellar.expert/explorer/public"],
      "average_blocktime_ms": 5000,
      "is_testnet": false,
      "passphrase": "Public Global Stellar Network ; September 2015"
    },
    {
      "type": "stellar",
      "network": "testnet",
      "rpc_urls": ["https://soroban-testnet.stellar.org"],
      "explorer_urls": ["https://stellar.expert/explorer/testnet"],
      "average_blocktime_ms": 5000,
      "is_testnet": true,
      "passphrase": "Test SDF Network ; September 2015"
    }
  ]
}

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

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 Stellar relayer:

{
  "id": "stellar-example",
  "name": "Stellar Example",
  "network": "testnet",
  "paused": false,
  "notification_id": "notification-example",
  "signer_id": "local-signer",
  "network_type": "stellar"
}

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

Configuration

Relayer Policies

Stellar relayers support standard relayer configuration options along with Stellar-specific policies:

Example configuration with policies:

{
  "id": "stellar-example",
  "name": "Stellar Example",
  "network": "testnet",
  "paused": false,
  "network_type": "stellar",
  "signer_id": "local-signer",
  "policies": {
    "min_balance": 10000000,
    "max_fee": 1000000,
    "timeout_seconds": 30,
    "concurrent_transactions": false
  }
}

For general relayer configuration options, check User Documentation - Relayers.

API Reference

Transaction Operations

The Stellar API supports a variety of transaction operations:

Supported Operation Types

Transaction Structure

Required fields:

• network: The Stellar network ("testnet", "mainnet", etc.)
• Either operations (array of operations) OR transaction_xdr (base64-encoded XDR) - but not both

Optional fields:

• source_account: The Stellar account that will be the source of the transaction (defaults to relayer’s address)
• memo: Transaction memo (see Memo Types below)
• valid_until: Transaction expiration time (ISO 8601 format)
• transaction_xdr: Pre-built transaction XDR (base64 encoded, signed or unsigned) - mutually exclusive with operations
• fee_bump: Boolean flag to request fee-bump wrapper (only valid with signed transaction_xdr)
• max_fee: Maximum fee for fee bump transactions in stroops (defaults to 1,000,000 = 0.1 XLM)

Transaction Input Methods

The relayer supports three ways to submit transactions:

1. Operations-based: Build a transaction by specifying the operations array (recommended for most use cases)
2. Transaction XDR (unsigned): Submit a pre-built unsigned transaction using transaction_xdr field (advanced use case)
3. Transaction XDR (signed): Submit a signed transaction using transaction_xdr with fee_bump: true (required for signed XDR) to wrap it in a fee bump transaction

Example 1: Operations-based Transaction

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "payment",
      "destination": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ",
      "asset": {"type": "native"},
      "amount": 1000000
    }
  ],
  "memo": {"type": "text", "value": "Payment for services"}
}'

Example 2: Unsigned Transaction XDR

Submit a pre-built unsigned transaction. The relayer will sign it with its configured signer:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAACige4lTdwSB/sto4SniEdJ2kOa2X65s5bqkd40J4DjSwAAAGQAAHAkAAAADgAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAKKB7iVN3BIH+y2jhKeIR0naQ5rZfrmzluqR3jQngONLAAAAAAAAAAAAD0JAAAAAAAAAAAA="
}'

The transaction_xdr field should contain a base64-encoded unsigned transaction envelope. This is useful when:

• You need precise control over transaction structure
• You want to use advanced Stellar features not exposed via the operations API

Example 3: Signed Transaction XDR

Submit a pre-signed transaction with fee bump wrapper. Note: fee_bump: true is required when submitting signed XDR:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAABjc+mbXCnvmVk4lxqVl7s0LAz5slXqmkHBg8PpH7p3DgAAAGQABpK0AAAACQAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAGN0qQBW8x3mfbwGGYndt2uq4O4sZPUrDx5HlwuQke9zAAAAAAAAAAAAAA9CAAAAAQAAAAA=",
  "fee_bump": true,
  "max_fee": 10000000
}'

The fee bump feature is useful when:

• You have a pre-signed transaction from another system or wallet
• You want the relayer to pay transaction fees on behalf of the original signer
• You need to increase the fee for a transaction to ensure timely execution

See API Reference for full details and examples.

Asset Types

Assets in Stellar operations must be specified with a type field:

Native XLM:

{"type": "native"}

Credit Asset (4 characters or less):

{
  "type": "credit_alphanum4",
  "code": "USDC",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Credit Asset (5-12 characters):

{
  "type": "credit_alphanum12",
  "code": "LONGASSET",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Memo Types

Transactions can include optional memos:

• No Memo: "type": "none"
• Text Memo: "type": "text", "value": "Payment for services" (max 28 UTF-8 bytes)
• ID Memo: "type": "id", "value": "12345"
• Hash Memo: "type": "hash", "value": "deadbeef..." (32 bytes hex)
• Return Memo: "type": "return", "value": "deadbeef..." (32 bytes hex)

Soroban Contract Operations

Invoke Contract

Call a deployed Soroban smart contract:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "invoke_contract",
      "contract_address": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUWDA",
      "function_name": "transfer",
      "args": [
        {"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"},
        {"address": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ"},
        {"i128": {"hi": "0", "lo": "1000000"}}
      ],
      "auth": {"type": "source_account"}
    }
  ]
}'

Create Contract

Deploy a new Soroban smart contract:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "create_contract",
      "source": {
        "from": "address",
        "address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"
      },
      "wasm_hash": "d3b2f6f8a1c5e9b4a7d8c2e1f5a9b3c6e8d4f7a2b5c8e1d4f7a0b3c6e9d2f5a8",
      "salt": "0000000000000000000000000000000000000000000000000000000000000001"
    }
  ]
}'

Upload WASM

Upload contract code to the Stellar ledger:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "upload_wasm",
      "wasm": {
        "type": "base64",
        "base64": "AGFzbQEAAAABBgFgAX8BfwMCAQAFAwEAAQcPAgVoZWxsbwAACG1lbW9yeTIDCgQAAAAL"
      }
    }
  ]
}'

ScVal Argument Format

When invoking contract functions, arguments must be provided as ScVal values in JSON format:

Additional types like U128, I128, U256, and I256 are also supported using multi-part representations.

Authorization Modes

Soroban operations support different authorization modes:

Signer Support

Stellar networks support the following signer types:

• Local Signer: Uses encrypted keystore files (suitable for development)
• Google Cloud KMS: Uses Google Cloud Key Management Service with ED25519 keys (recommended for production)
• Turnkey: Uses Turnkey’s secure key management infrastructure with ED25519 keys (recommended for production)

For detailed signer configuration, see the Signers Configuration guide.

For complete examples:

• Google Cloud KMS: stellar-gcp-kms-signer example
• Turnkey: stellar-turnkey-signer example

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
• Ensure proper network passphrases are configured for transaction signing

Troubleshooting

• Check environment variables and configuration files for errors
• Verify network passphrase matches the target network
• Review container logs for Stellar-specific errors
• Ensure Soroban RPC endpoints are properly configured for contract operations

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.