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.

Stellar support is currently under active development. The API interactions and specifics described below may evolve.

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

Configuration

Relayer Policies

Stellar relayers support standard relayer configuration options. Check all options in User Documentation - Relayers.

API Reference

Transaction Operations

The Stellar API supports a variety of transaction operations:

Method Name Required Parameters Description

Send Transaction

network, operations (or transaction_xdr)

Submit a transaction to the Stellar network. Supports payment and Soroban operations directly, or any Stellar operation via pre-built XDR transactions. Also supports fee bump transactions for managing transaction fees.

Get Transaction Details

transaction_id

Retrieve a specific transaction by its ID.

List Transactions

(none)

List transactions for the relayer with pagination support.

Supported Operation Types

Operation Type Description

payment

Transfer native XLM or other assets between accounts

invoke_contract

Call a deployed Soroban smart contract function

create_contract

Deploy a new Soroban smart contract from WASM hash

upload_wasm

Upload WASM contract code to the Stellar ledger

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) with fee bump: Submit a signed transaction using transaction_xdr with fee_bump: true to wrap it in a fee bump transaction

Example: Send 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"}
}'

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)

Memos are not supported for Soroban contract operations (invoke_contract, create_contract, upload_wasm). Attempting to include a memo with these operations will result in an error.

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:

Type Format Description

U64

{"u64": "1000000"}

Unsigned 64-bit integer

I64

{"i64": "-500"}

Signed 64-bit integer

U32

{"u32": 42}

Unsigned 32-bit integer

I32

{"i32": -42}

Signed 32-bit integer

Boolean

{"bool": true}

Boolean value

String

{"string": "hello world"}

UTF-8 string

Symbol

{"symbol": "transfer"}

Symbol (used for function names)

Address

{"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"}

Stellar account or contract address

Bytes

{"bytes": "deadbeef"}

Hex-encoded byte array

Vector

{"vec": [{"u32": 1}, {"u32": 2}, {"u32": 3}]}

Array of ScVal values

Map

{"map": [{"key": {"symbol": "name"}, "val": {"string": "MyToken"}}]}

Key-value pairs

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

Authorization Modes

Soroban operations support different authorization modes:

Type Description

none

No authorization required

source_account

Use the transaction source account (default)

addresses

Use specific addresses (future feature)

xdr

Advanced: provide base64-encoded XDR entries. This allows you to provide pre-signed SorobanAuthorizationEntry objects for complex authorization scenarios. See the official Stellar documentation on authorization for detailed information about SorobanAuthorizationEntries.

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

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.

← Solana Integration
Project Structure →