Launchtube Plugin

A plugin for OpenZeppelin Relayer that simplifies submitting Stellar Soroban transactions by handling fees, sequence numbers, and retries.

Prerequisites

• Node.js >= 18
• pnpm >= 10
• OpenZeppelin Relayer

Installation & Setup

LaunchTube can be added to any OpenZeppelin Relayer in two ways:

1. Install from npm (recommended)

# From the root of your Relayer repository
cd plugins
pnpm add @openzeppelin/relayer-plugin-launchtube

2. Use a local build (for development / debugging)

# Clone and build the plugin
git clone https://github.com/openzeppelin/relayer-plugin-launchtube.git
cd relayer-plugin-launchtube
pnpm install
pnpm build

Now reference the local build from your Relayer’s plugins/package.json:

{
  "dependencies": {
    "@openzeppelin/relayer-plugin-launchtube": "file:../../relayer-plugin-launchtube",
  },
}

Install dependencies:

pnpm install

Create the plugin wrapper

Inside the Relayer create a directory for the plugin and expose its handler:

mkdir -p plugins/launchtube

plugins/launchtube/index.ts

export { handler } from '@openzeppelin/relayer-plugin-launchtube';

Configure Environment Variables

Set the required environment variables for the plugin:

# Required environment variables
export STELLAR_NETWORK="testnet"        # or "mainnet"
export SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
export FUND_RELAYER_ID="launchtube-fund"
export LAUNCHTUBE_ADMIN_SECRET="your-secret-here"  # Required for management API
export LOCK_TTL_SECONDS=30

Your Relayer should now contain:

relayer/
└─ plugins/
   ├─ package.json              # lists the dependency
   └─ launchtube/
      └─ index.ts

Initialize Sequence Accounts

Before using LaunchTube, you must configure sequence accounts using the management API:

curl -X POST http://localhost:8080/api/v1/plugins/launchtube/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "management": {
        "action": "setSequenceAccounts",
        "adminSecret": "your-secret-here",
        "relayerIds": ["launchtube-seq-001", "launchtube-seq-002"]
      }
    }
  }'

LaunchTube is now ready to serve Soroban transactions 🚀

Development

Building from Source

# Install dependencies
pnpm install

# Build the plugin
pnpm build

# Run tests
pnpm test

# Lint and format
pnpm lint
pnpm format

Overview

Launchtube accepts Soroban operations and handles all the complexity of getting them on-chain:

• Automatic fee bumping using a dedicated fund account
• Sequence number management with a pool of sequence accounts
• Transaction simulation and rebuilding
• Retry logic and error handling

Configuration

LaunchTube is configured through environment variables:

Required Environment Variables:

• STELLAR_NETWORK: Either "testnet" or "mainnet"
• SOROBAN_RPC_URL: Stellar Soroban RPC endpoint
• FUND_RELAYER_ID: Relayer ID for the account that pays fees

Optional Environment Variables:

• LAUNCHTUBE_ADMIN_SECRET: Secret for accessing the management API (required to manage sequence accounts)
• LOCK_TTL_SECONDS: TTL for sequence account locks (default: 30, range: 10-30)

Note: Sequence accounts are no longer configured via config file. They must be managed dynamically through the Management API (see below).

Management API

LaunchTube provides a management API to dynamically configure sequence accounts. This API requires authentication via the LAUNCHTUBE_ADMIN_SECRET environment variable.

List Sequence Accounts

Get the current list of configured sequence accounts:

curl -X POST http://localhost:8080/api/v1/plugins/launchtube/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "management": {
        "action": "listSequenceAccounts",
        "adminSecret": "your-secret-here"
      }
    }
  }'

Response:

{
  "relayerIds": ["launchtube-seq-001", "launchtube-seq-002"]
}

Set Sequence Accounts

Configure the sequence accounts that LaunchTube will use. This replaces the entire list:

curl -X POST http://localhost:8080/api/v1/plugins/launchtube/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "management": {
        "action": "setSequenceAccounts",
        "adminSecret": "your-secret-here",
        "relayerIds": ["launchtube-seq-001", "launchtube-seq-002", "launchtube-seq-003"]
      }
    }
  }'

Response:

{
  "ok": true,
  "appliedRelayerIds": ["launchtube-seq-001", "launchtube-seq-002", "launchtube-seq-003"]
}

Important Notes:

• You must configure at least one sequence account before LaunchTube can process transactions
• The management API will prevent removing accounts that are currently locked (in use). On failure it throws a plugin error with status 409, code LOCKED_CONFLICT, and details.locked listing blocked IDs.
• All relayer IDs must exist in your OpenZeppelin Relayer configuration
• The adminSecret must match the LAUNCHTUBE_ADMIN_SECRET environment variable

API Usage

Submit with Transaction XDR

Submit a complete, signed transaction:

curl -X POST http://localhost:8080/api/v1/plugins/launchtube/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "xdr": "AAAAAgAAAAA...",
      "sim": false
    }
  }'

Submit with Function and Auth

Submit just the Soroban function and auth entries:

curl -X POST http://localhost:8080/api/v1/plugins/launchtube/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "func": "AAAABAAAAAEAAAAGc3ltYm9s...",
      "auth": ["AAAACAAAAAEAAAA..."],
      "sim": true
    }
  }'

Parameters

• xdr (string): Complete transaction envelope XDR
• func (string): Soroban host function XDR
• auth (array): Array of Soroban authorization entry XDRs
• sim (boolean): Whether to simulate the transaction before submission

Note: Provide either xdr OR func+auth, not both.

Response

Responses follow the Relayer envelope { success, data, error }.

Success example:

{
  "success": true,
  "data": {
    "result": {
      "transactionId": "tx_123456",
      "hash": "1234567890abcdef..."
    }
  },
  "error": null
}

Plugin error example:

{
  "success": false,
  "data": {
    "code": "INVALID_PARAMS",
    "details": { "sim": false, "xdrProvided": false }
  },
  "error": "Cannot pass `sim = false` without `xdr`"
}

How It Works

1. Request Validation: Validates input parameters and extracts Soroban data
2. Sequence Account Pool: Acquires an available sequence account
3. Auth Checking: Validates authorization entries
4. Simulation (if enabled): Simulates transaction and rebuilds with proper resources
5. Fee Bumping: Fund account wraps transaction with fee bump
6. Submission: Sends to Stellar network

License

MIT License