OpenZeppelin Relayer - Stellar Developer Docs

Launchtube, which served as an experimental service for fee sponsorship and contract invocations, has been instrumental in early-stage deployments and developer experimentation. However, while functional for testing and early use cases, Launchtube does not have the same maturity or scalability as OpenZeppelin’s Relayer, which is why the Stellar Development Foundation has discontinued the Launchtube service and points developers to OpenZeppelin’s managed Stellar Channels service as the replacement. OpenZeppelin Relayer is an open source (AGPL-3.0) framework for submitting Stellar transactions, including Soroban contract invocations. If you run your own instance, you control the signer and you fund the accounts that pay the fees. The signer can be a local keystore, Google Cloud KMS, or Turnkey. Parallel submission and automatic fee bumping come from the Channels plugin, which you can also run yourself. Stellar Channels is the managed service OpenZeppelin operates on top of the Relayer and the Channels plugin. There are no servers, relayers, or channel accounts for you to configure, because OpenZeppelin runs the pool of channel accounts and covers the fees, subject to a fair use policy.

The examples on this page use the managed Channels service, so they authenticate with a Channels API key rather than talking to a relayer you run yourself.

Stellar Channels status

To see the live status of Stellar Channels, visit the Stellar Channels status page.

Smart contract invocation

Let’s create a simple application that submits a transaction, invoking a smart contract function, using Channels. The application calls the Increment smart contract and returns the current counter value. The application is based on the Next.js framework and has server side code and client side code. The @openzeppelin/relayer-plugin-channels SDK makes HTTPS-requests to OpenZeppelin endpoints, which will trigger CORS errors when run client side, but by using the SDK server side, CORS will not be an issue.

Prerequisites

This guide assumes you have deployed the Increment smart contract example code found here. See the Getting Started tutorial section 3 and 4 for more information about building and deploying the Increment contract.

Server Side

In this simple application we only have one function server side, and that’s a function calling a smart contract function, by submitting a transaction through Channels.

1. Initialize the Channels client

First the two necessary SDKs are imported, and the Channels client is initialized. In this tutorial we use testnet, so the Channels endpoint for testnet is used as the base URL. The API key can be generated here.

"use server";
import * as StellarSDK from "@stellar/stellar-sdk";
import * as RPChannels from "@openzeppelin/relayer-plugin-channels";

// Initialize Channels Client
const client = new RPChannels.ChannelsClient({
  baseUrl: "https://channels.openzeppelin.com/testnet",
  apiKey: "c344ee79-6294-4dc3-8f7d-000000000000",
});

2. Initialize contract, RPC and account

Next we initialize the resources we need to build the transaction. Both the contractId and sourceId are arguments of the function and will be provided client side.

// Initialize Contract and RPC Server
const contract = new StellarSDK.Contract(contractId);
const rpc = new StellarSDK.rpc.Server("https://soroban-testnet.stellar.org");
// Get Source Account
const account = await rpc.getAccount(sourceId);

3. Build transaction

TransactionBuilder takes the user account and network information as parameters, and operations can be added. In this case we want to add the contract invocation by using contract.call(), with the contract function name and arguments as parameters.

const tx = new StellarSDK.TransactionBuilder(account, {
  fee: "100",
  networkPassphrase: StellarSDK.Networks.TESTNET,
})
  .addOperation(contract.call(func, ...args))
  .setTimeout(30)
  .build();

4. Simulate transaction and get XDRs

The final steps before we can submit the transaction to Channels is to simulate the transaction, bundle the transaction and simulation, and extract the transaction’s function and auth XDRs. We are extracting the function and auth from the assembled transaction, in XDR format, because that’s what we need to submit to Channels.

// Simulate to get auth entries
const simulation = await rpc.simulateTransaction(tx);
const assembled = StellarSDK.rpc.assembleTransaction(tx, simulation).build();
// Extract function and auth XDRs
const op = assembled.operations[0];
const contractFunc = op.func.toXDR("base64");
const contractAuth = (op.auth ?? []).map((a) => a.toXDR("base64"));

5. Build the Channels request and submit it

Now we have completed all necessary steps to submit a transaction to Channels. First the request is built, and then the request is submitted to Channels.

// Build request for Channels
const request: RPChannels.ChannelsFuncAuthRequest = {
  func: contractFunc,
  auth: contractAuth,
};
// Submit to Channels
const response: RPChannels.ChannelsTransactionResponse =
  await client.submitSorobanTransaction(request);

A successful submission will return a response of the following format:

{
  transactionId: string; // Internal tracking ID
  hash: string; // Stellar transaction hash
  status: string; // Transaction status (e.g., "confirmed")
}

6. Get returned value from contract

The invoked Increment contract function will return the updated, incremented value so let’s get this value so we can show it in the client (frontend). To get the return value we simply poll for the transaction result until we get a response with rpc.pollTransaction(), which will return an object with more details than we need, so only the value is returned.

// Poll for transaction result
let txResponse = await rpc.pollTransaction(response.hash!);
// Return the result using the public SDK helper
return StellarSDK.scValToNative(txResponse.returnValue);

7. The complete code

The previous six steps contain all the functionality needed for invoking a smart contract function through Channels. This is the complete code for the function that we will call from the client side (frontend):

backend/index.tsx

"use server";
import * as StellarSDK from '@stellar/stellar-sdk';
import * as RPChannels from '@openzeppelin/relayer-plugin-channels';

// Initialize Channels Client
const client = new RPChannels.ChannelsClient({
  baseUrl: 'https://channels.openzeppelin.com/testnet',
  apiKey: 'c344ee79-6294-4dc3-8f7d-000000000000',
});

export const SendContractTransaction = async (sourceId: string, contractId: string, func: string, args: StellarSDK.xdr.ScVal[]) => {
  // Initialize Contract and RPC Server
  const contract = new StellarSDK.Contract(contractId);
  const rpc = new StellarSDK.rpc.Server('https://soroban-testnet.stellar.org');
  // Get Source Account
  const account = await rpc.getAccount(sourceId);
  // Build the transaction
  const tx = new StellarSDK.TransactionBuilder(account, {
    fee: '100',
    networkPassphrase: StellarSDK.Networks.TESTNET,
  })
  .addOperation(contract.call(func, ...args))
  .setTimeout(30)
  .build();
  // Simulate to get auth entries
  const simulation = await rpc.simulateTransaction(tx);
  const assembled = StellarSDK.rpc.assembleTransaction(tx, simulation).build();
  // Extract function and auth XDRs
  const op = assembled.operations[0];
  const contractFunc = op.func.toXDR('base64');
  const contractAuth = (op.auth ?? []).map((a) => a.toXDR('base64'));
  // Build request for Channels
  const request: RPChannels.ChannelsFuncAuthRequest = {
    func: contractFunc,
    auth: contractAuth,
  };
  // Submit to Channels
  const response: RPChannels.ChannelsTransactionResponse = await client.submitSorobanTransaction(request);
  // Poll for transaction result
  let txResponse = await rpc.pollTransaction(response.hash!);
  // Return the decoded result from the ScVal
  return StellarSDK.scValToNative(txResponse.returnValue);
}

Client Side

The client side code shows a button on the page in the browser, and when clicked, the server side function will be called with the relevant parameters. When the function returns a value, the value is shown on the page instead of the button. The functionality is very simple, but serves well as an end-to-end example of submitting a transaction with Channels.

1. Call server side function

The client code has a function callContract() that can be invoked from the button click. The function calls the server side function SendContractTransaction() with the sourceId, contractId, contract function name and auth.

const [result, setResult] = React.useState("");

const callContract = async () => {
  const response = await SendContractTransaction(
    "GAZQUIHE242WV4CK7LLM5ZV4SM6SLV4CEY4LLAKEYD2O000000000000",
    "CDAZOG4V2KAPVBBKCAMHUT367AUGYWYEHD652UOJVER5ERNYGSOROBAN",
    "increment",
    [],
  );

  setResult(response);
};

The response is stored as the result state.

2. Markup code

The page markup code checks if result contains a value. If not, the button for invoking the callContract function is shown, and if result does contain a value, it’s shown on the page instead. That’s all there is to the client side markup code.

<div
  className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-black"
>
  <main
    className="flex min-h-screen w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start"
  >
    {result ? (
    <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
      Result from Channels: {result}
    </h2>
    ) : (
    <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
      <button
        className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
        onClick="{callContract}"
      >
        Call Contract via Channels
      </button>
    </h2>
    )}
  </main>
</div>

The complete code This is the complete code for the client side (frontend):

page.tsx

"use client"
import React from "react";
import { SendContractTransaction } from "./backend";

export default function Home() {
  const [result, setResult] = React.useState('');

  const callContract = async () => {
    const args: [] = [];
    const response = await SendContractTransaction(
      'GAZQUIHE242WV4CK7LLM5ZV4SM6SLV4CEY4LLAKEYD2O000000000000',
      'CDAZOG4V2KAPVBBKCAMHUT367AUGYWYEHD652UOJVER5ERNYGSOROBAN',
      "increment",
      [],
    );

    setResult(response);
  }

  return (
    <div className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-black">
      <main className="flex min-h-screen w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
        {result ? (
          <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
            Result from Channels: {result}
          </h2>
        ) : (
          <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
            <button
              className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
              onClick={callContract}
            >
              Call Contract via Channels
            </button>
          </h2>
        )}
      </main>
    </div>
  );
}

Account transfer

Let’s create another simple application, this application submits a transfer transaction, sending XLM tokens from one account to another, using Channels. The application is based on the Next.js framework and has server side code and client side code. The @openzeppelin/relayer-plugin-channels SDK makes HTTPS-requests to OpenZeppelin endpoints, which will trigger CORS errors when run client side, but by using the SDK server side, CORS will not be an issue.

Server Side

In this simple application we only have one function server side, and that’s a function making a transfer of XLM tokens from one account to another, by submitting a transaction through Channels.

Initialize the Channels client

"use server";
import * as StellarSDK from "@stellar/stellar-sdk";
import * as RPChannels from "@openzeppelin/relayer-plugin-channels";

// Initialize Channels Client
const client = new RPChannels.ChannelsClient({
  baseUrl: "https://channels.openzeppelin.com/testnet",
  apiKey: "c344ee79-6294-4dc3-8f7d-000000000000",
});

2. Initialize RPC and source account

Next we initialize the resources we need to build the transaction. In this example code the source secret key is hardcoded, but this must be handled in a more secure manner in production applications.

// Initialize RPC Server
const rpc = new StellarSDK.rpc.Server("https://soroban-testnet.stellar.org");

// Define source account details - this should be securely managed and not hardcoded in production
const sourceSecret = "SADMGRVM3MDTZ54FN3SBEKSTRCVEY4WE5JAVCERJJBFR000000000000";
// Load the source account from the secret key
const sourceKeypair = StellarSDK.Keypair.fromSecret(sourceSecret);
const sourcePublicKey = sourceKeypair.publicKey();

// Load account details from the network
const sourceAccount = await rpc.getAccount(sourcePublicKey);

3. Build and sign transaction

TransactionBuilder takes the source account and network information as parameters, and operations can be added. In this case we want to add the payment() operation to transfer an amount of XLM tokens (native asset) from the source account to the destination. The transaction is signed with the source keypair.

// Build the transaction
const transaction = new StellarSDK.TransactionBuilder(sourceAccount, {
  fee: StellarSDK.BASE_FEE,
  networkPassphrase: StellarSDK.Networks.TESTNET,
})
  .addOperation(
    StellarSDK.Operation.payment({
      destination: destinationPublicKey,
      asset: StellarSDK.Asset.native(),
      amount: amount.toString(),
    }),
  )
  .setTimeout(30)
  .build();

transaction.sign(sourceKeypair);

4. Submit the transaction

Now we have completed all necessary steps to submit the transaction to Channels. The Channels client function submitTransaction() takes the transaction in XDR-format as an argument.

// Submit to Channels
const response = await client.submitTransaction({
  xdr: transaction.toXDR(),
});

A successful submission will return a response of the following format:

{
  transactionId: string; // Internal tracking ID
  hash: string; // Stellar transaction hash
  status: string; // Transaction status (e.g., "confirmed")
}

5. Return the transaction hash

As a final step the transaction hash is returned.

return response.hash;

6. The complete code

The previous five steps contain all the functionality needed for transferring XLM tokens from the source account to another account through Channels. This is the complete code for the function that we will call from the client side (frontend):

backend/index.tsx

"use server";
import * as StellarSDK from '@stellar/stellar-sdk';
import * as RPChannels from '@openzeppelin/relayer-plugin-channels';

// Initialize Channels Client
const client = new RPChannels.ChannelsClient({
  baseUrl: 'https://channels.openzeppelin.com/testnet',
  apiKey: 'c344ee79-6294-4dc3-8f7d-000000000000',
});

export const SendTransaction = async (destinationPublicKey: string, amount: string) => {
  // Initialize RPC Server
  const rpc = new StellarSDK.rpc.Server('https://soroban-testnet.stellar.org');

  // Define source account details - this should be securely managed and not hardcoded in production
  const sourceSecret = 'SADMGRVM3MDTZ54FN3SBEKSTRCVEY4WE5JAVCERJJBFR000000000000';
  // Load the source account from the secret key
  const sourceKeypair = StellarSDK.Keypair.fromSecret(sourceSecret);
  const sourcePublicKey = sourceKeypair.publicKey();

  // Load account details from the network
  const sourceAccount = await rpc.getAccount(sourcePublicKey);

  try {
    // Build the transaction
    const transaction = new StellarSDK.TransactionBuilder(sourceAccount, {
      fee: StellarSDK.BASE_FEE, // Or use server.fetchBaseFee() for dynamic fees
      networkPassphrase: StellarSDK.Networks.TESTNET // Use Networks.PUBLIC for mainnet
    })
    .addOperation(
      StellarSDK.Operation.payment({
        destination: destinationPublicKey,
        asset: StellarSDK.Asset.native(), // XLM is the native asset
        amount: amount.toString() // Amount in XLM (e.g., "10" for 10 XLM)
      })
    )
    .setTimeout(30) // Transaction expires after 30 seconds
    .build();

    // Sign the transaction
    transaction.sign(sourceKeypair);

    const response = await client.submitTransaction({
      xdr: transaction.toXDR(), // base64 envelope XDR
    });

    return response.hash;
  } catch (error) {
    console.error('Failed to submit Stellar transaction via OpenZeppelin Channels:', error);
    throw error;
  }
}

Client Side

The client side code shows a form with input fields for a transfer-to-address, and amount to transfer, on the page in the browser. When the form is filled out and submitted, the server side function will be called with the form values as parameters. When the function returns with the transaction hash, the hash is shown on the page instead of the form. The functionality is very simple, but serves well as an end-to-end example of submitting a token transfer transaction with Channels.

Call server side function

The client code has a function sendXLM() that works as a form action function. The function calls the server side function SendTransaction() with the transfer destination public key and amount as parameters.

const [result, setResult] = React.useState('');

const sendXLM = async (formData: FormData) => {
  const to = formData.get('toAddress') as string;
  const amount = formData.get('amount') as string;

  const response = await SendTransaction(to, amount);
  setResult(response);
};

The response is stored as the result state.

Markup code

The page markup code checks if result contains a value. If not, the form for submitting a transfer is shown, and if result does contain a value, it’s shown on the page instead. That’s all there is to the client side markup code.

<div
  className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-black"
>
  <main
    className="flex min-h-screen w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start"
  >
    {result ? (
    <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
      Transaction Hash: {result}
    </h2>
    ) : (
    <form action="{sendXLM}" className="max-w-sm mx-auto">
      <div className="mb-5">
        <label
          htmlFor="toAddress"
          className="block mb-2.5 text-sm font-medium text-heading"
          >To (Address)</label
        >
        <input
          type="text"
          id="toAddress"
          name="toAddress"
          className="bg-neutral-secondary-medium border border-default-medium text-heading text-sm rounded-base focus:ring-brand focus:border-brand block w-full px-3 py-2.5 shadow-xs placeholder:text-body"
          placeholder="G.........."
          required
        />
      </div>
      <div className="mb-5">
        <label
          htmlFor="amount"
          className="block mb-2.5 text-sm font-medium text-heading"
          >Amount (XLM)</label
        >
        <input
          type="number"
          id="amount"
          name="amount"
          className="bg-neutral-secondary-medium border border-default-medium text-heading text-sm rounded-base focus:ring-brand focus:border-brand block w-full px-3 py-2.5 shadow-xs placeholder:text-body"
          placeholder="10"
          required
        />
      </div>
      <button
        type="submit"
        className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
      >
        Submit
      </button>
    </form>
    )}
  </main>
</div>

3. The complete code

This is the complete code for the client side (frontend):

page.tsx

"use client"
import React from "react";
import { SendTransaction } from "./backend";

export default function Home() {
  const [result, setResult] = React.useState('');

  const sendXLM = async (formData: FormData) => {
    const to = formData.get('toAddress') as string;
    const amount = formData.get('amount') as string;

    const response = await SendTransaction(to, amount);
    setResult(response);
  };

  return (
    <div className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-black">
      <main className="flex min-h-screen w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
        {result ? (
          <h2 className="mb-10 text-2xl font-semibold text-black dark:text-white">
            Transaction Hash: {result}
          </h2>
        ) : (
          <form action={sendXLM} className="max-w-sm mx-auto">
            <div className="mb-5">
              <label htmlFor="toAddress" className="block mb-2.5 text-sm font-medium text-heading">To (Address)</label>
              <input type="text" id="toAddress" name="toAddress" className="bg-neutral-secondary-medium border border-default-medium text-heading text-sm rounded-base focus:ring-brand focus:border-brand block w-full px-3 py-2.5 shadow-xs placeholder:text-body" placeholder="G.........." required />
            </div>
            <div className="mb-5">
              <label htmlFor="amount" className="block mb-2.5 text-sm font-medium text-heading">Amount (XLM)</label>
              <input type="number" id="amount" name="amount" className="bg-neutral-secondary-medium border border-default-medium text-heading text-sm rounded-base focus:ring-brand focus:border-brand block w-full px-3 py-2.5 shadow-xs placeholder:text-body" placeholder="10" required />
            </div>
            <button type="submit" className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">Submit</button>
          </form>
        )}
      </main>
    </div>
  );
}

OpenZeppelin Relayer documentation

For more information see the OpenZeppelin Relayer documentation here.

​Stellar Channels status

​Smart contract invocation

​Prerequisites

​Server Side

​1. Initialize the Channels client

​2. Initialize contract, RPC and account

​3. Build transaction

​4. Simulate transaction and get XDRs

​5. Build the Channels request and submit it

​6. Get returned value from contract

​7. The complete code

​Client Side

​1. Call server side function

​2. Markup code

​Account transfer

​Server Side

​ Initialize the Channels client

​2. Initialize RPC and source account

​3. Build and sign transaction

​4. Submit the transaction

​5. Return the transaction hash

​6. The complete code

​Client Side

​ Call server side function

​ Markup code

​3. The complete code

​OpenZeppelin Relayer documentation

Stellar Channels status

Smart contract invocation

Prerequisites

Server Side

1. Initialize the Channels client

2. Initialize contract, RPC and account

3. Build transaction

4. Simulate transaction and get XDRs

5. Build the Channels request and submit it

6. Get returned value from contract

7. The complete code

Client Side

1. Call server side function

2. Markup code

Account transfer

Server Side

Initialize the Channels client

2. Initialize RPC and source account

3. Build and sign transaction

4. Submit the transaction

5. Return the transaction hash

6. The complete code

Client Side

Call server side function

Markup code

3. The complete code

OpenZeppelin Relayer documentation