@openzeppelin/relayer-plugin-channels 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,44 @@
 
 A plugin for OpenZeppelin Relayer that enables parallel transaction submission on Stellar using channel accounts with fee bumping. Channel accounts provide unique sequence numbers for parallel transaction submission, preventing sequence number conflicts.
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Installation & Setup](#installation--setup)
+  - [Install from npm](#1-install-from-npm-recommended)
+  - [Use a local build](#2-use-a-local-build-for-development--debugging)
+  - [Create the plugin wrapper](#create-the-plugin-wrapper)
+  - [Configure the Relayer](#configure-the-relayer)
+  - [Configure Environment Variables](#configure-environment-variables)
+  - [Initialize Channel Accounts](#initialize-channel-accounts)
+- [Development](#development)
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Management API](#management-api)
+  - [List Channel Accounts](#list-channel-accounts)
+  - [Set Channel Accounts](#set-channel-accounts)
+- [Plugin Client](#plugin-client)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start-1)
+  - [Client Modes](#client-modes)
+  - [Usage Examples](#usage-examples)
+  - [Error Handling](#error-handling)
+  - [Metadata and Debugging](#metadata-and-debugging)
+  - [TypeScript Types](#typescript-types)
+  - [Configuration Options](#configuration-options)
+- [API Usage](#api-usage)
+  - [Submit with Transaction XDR](#submit-with-transaction-xdr)
+  - [Submit with Function and Auth](#submit-with-function-and-auth)
+  - [Parameters](#parameters)
+  - [Response](#response)
+- [How It Works](#how-it-works)
+- [Validation Rules](#validation-rules)
+- [KV Schema](#kv-schema)
+- [Error Codes](#error-codes)
+- [Smoke Test Contract](#smoke-test-contract)
+- [License](#license)
+
 ## Quick Start
 
 **Want to get started quickly?** Check out the [Channels Plugin Example](https://github.com/OpenZeppelin/openzeppelin-relayer/tree/main/examples/channels-plugin-example) which includes a pre-configured relayer setup, Docker Compose configuration, and step-by-step instructions. This is the fastest way to get the Channels plugin up and running.
@@ -311,6 +349,207 @@ curl -X POST http://localhost:8080/api/v1/plugins/channels/call \
 - All relayer IDs must exist in your OpenZeppelin Relayer configuration
 - The `adminSecret` must match the `PLUGIN_ADMIN_SECRET` environment variable
 
+## Plugin Client
+
+The Channels plugin provides a TypeScript client for easy integration into your applications. The client automatically handles request/response formatting, error handling, and supports both relayer mode and direct HTTP mode.
+
+### Installation
+
+```bash
+npm install @openzeppelin/relayer-plugin-channels
+# or
+pnpm add @openzeppelin/relayer-plugin-channels
+```
+
+### Quick Start
+
+```typescript
+import { ChannelsClient } from "@openzeppelin/relayer-plugin-channels";
+
+// Connecting to OpenZeppelin's managed Channels service
+const client = new ChannelsClient({
+  baseUrl: "https://channels.openzeppelin.com",
+  apiKey: "your-api-key",
+});
+
+// Connecting to your own Relayer with Channels plugin
+const relayerClient = new ChannelsClient({
+  baseUrl: "http://localhost:8080",
+  pluginId: "channels",
+  apiKey: "your-relayer-api-key",
+  adminSecret: "your-admin-secret", // Optional: Required for management operations
+});
+```
+
+### Configuration
+
+**Managed Service**
+
+When connecting to OpenZeppelin's managed Channels service (which runs behind Cloudflare and a load balancer), provide just the `baseUrl` and `apiKey`:
+
+```typescript
+// Mainnet
+const client = new ChannelsClient({
+  baseUrl: "https://channels.openzeppelin.com",
+  apiKey: "your-api-key",
+});
+
+// Testnet
+const testnetClient = new ChannelsClient({
+  baseUrl: "https://channels.openzeppelin.com/testnet",
+  apiKey: "your-api-key",
+});
+```
+
+**Generate API Keys:**
+
+- Testnet: https://channels.openzeppelin.com/testnet/gen
+- Mainnet: https://channels.openzeppelin.com/gen
+
+**Self-Hosted Relayer**
+
+When connecting directly to your own OpenZeppelin Relayer instance, include the `pluginId`:
+
+```typescript
+const client = new ChannelsClient({
+  baseUrl: "http://localhost:8080",
+  pluginId: "channels",
+  apiKey: "your-relayer-api-key",
+  adminSecret: "your-admin-secret", // Optional: Required for management operations
+});
+```
+
+The client automatically routes requests appropriately based on whether `pluginId` is provided
+
+### Usage Examples
+
+#### Submit Signed XDR Transaction
+
+```typescript
+// Submit a complete, signed transaction
+const result = await client.submitTransaction({
+  xdr: "AAAAAgAAAAC...", // Complete transaction envelope XDR
+});
+
+console.log(result.hash); // Transaction hash
+console.log(result.status); // Transaction status
+console.log(result.transactionId); // Relayer transaction ID
+```
+
+#### Submit Soroban Function with Auth
+
+```typescript
+// Submit func+auth (uses channel accounts and simulation)
+const result = await client.submitSorobanTransaction({
+  func: "AAAABAAAAAEAAAAGc3ltYm9s...", // Host function XDR (base64)
+  auth: ["AAAACAAAAAEAAAA..."], // Auth entry XDRs (base64)
+});
+
+console.log(result.hash);
+```
+
+#### List Channel Accounts (Management)
+
+```typescript
+// Initialize client with admin secret
+const adminClient = new ChannelsClient({
+  baseUrl: "http://localhost:8080",
+  apiKey: "your-api-key",
+  pluginId: "channels",
+  adminSecret: "your-admin-secret", // Required for management operations
+});
+
+// List configured channel accounts
+const accounts = await adminClient.listChannelAccounts();
+console.log(accounts.relayerIds); // ['channel-001', 'channel-002', ...]
+```
+
+#### Set Channel Accounts (Management)
+
+```typescript
+// Configure channel accounts (requires adminSecret)
+const result = await adminClient.setChannelAccounts([
+  "channel-001",
+  "channel-002",
+  "channel-003",
+]);
+
+console.log(result.ok); // true
+console.log(result.appliedRelayerIds); // ['channel-001', 'channel-002', 'channel-003']
+```
+
+### Error Handling
+
+The client provides three types of errors:
+
+```typescript
+import {
+  PluginTransportError,
+  PluginExecutionError,
+  PluginUnexpectedError,
+} from "@openzeppelin/relayer-plugin-channels";
+
+try {
+  const result = await client.submitTransaction({ xdr: "..." });
+} catch (error) {
+  if (error instanceof PluginTransportError) {
+    // Network/HTTP failures (connection refused, timeout, 500/502/503)
+    console.error("Transport error:", error.message);
+    console.error("Status code:", error.statusCode);
+  } else if (error instanceof PluginExecutionError) {
+    // Plugin rejected the request (validation, business logic, on-chain failure)
+    console.error("Execution error:", error.message);
+    console.error("Details:", error.errorDetails);
+  } else if (error instanceof PluginUnexpectedError) {
+    // Client-side parsing/validation errors
+    console.error("Unexpected error:", error.message);
+  }
+}
+```
+
+### Metadata and Debugging
+
+Responses include optional metadata (logs and traces) when the plugin is configured with `emit_logs` and `emit_traces`:
+
+```typescript
+const result = await client.submitTransaction({ xdr: "..." });
+
+// Access metadata if available
+if (result.metadata) {
+  console.log("Logs:", result.metadata.logs);
+  console.log("Traces:", result.metadata.traces);
+}
+```
+
+### TypeScript Types
+
+All request and response types are fully typed:
+
+```typescript
+import type {
+  ChannelsXdrRequest,
+  ChannelsFuncAuthRequest,
+  ChannelsTransactionResponse,
+  ListChannelAccountsResponse,
+  SetChannelAccountsResponse,
+} from "@openzeppelin/relayer-plugin-channels";
+```
+
+### Configuration Options
+
+```typescript
+interface ChannelsClientConfig {
+  // Required
+  baseUrl: string; // Service or Relayer URL
+  apiKey: string; // API key for authentication
+
+  // Optional
+  pluginId?: string; // Include when connecting to a Relayer directly
+  adminSecret?: string; // Required for management operations
+  timeout?: number; // Request timeout in ms (default: 30000)
+}
+```
+
 ## API Usage
 
 ### Submit with Transaction XDR
@@ -442,63 +681,3 @@ Plugin error example:
 ## License
 
 MIT
-
----
-
-## Smoke Test Contract
-
-This repo includes a minimal Soroban contract and smoke test script that exercise the Channels plugin with different authorization methods.
-
-### Contract
-
-- **Path**: `contracts/smoke-contract`
-- **Functions**:
-  - `no_auth_bump(n: u32) -> u32` — No auth required; returns n+1
-  - `write_with_address_auth(addr: Address, value: u32)` — Requires address auth; writes value to storage
-  - `read_value(addr: Address) -> u32` — Reads stored value for address
-
-Build/optimize/deploy with the Stellar CLI:
-
-```bash
-# Using helper script
-bash contracts/smoke-contract/contract.sh build
-bash contracts/smoke-contract/contract.sh optimize
-bash contracts/smoke-contract/contract.sh deploy --network testnet --account test-account
-```
-
-### Smoke Test Script
-
-- **Path**: `scripts/smoke.ts`
-- **Requirements**:
-  - Node.js 18+
-  - Stellar CLI (`stellar`) configured with a key
-  - Channels plugin running at base URL
-
-Environment variables:
-
-```bash
-export BASE_URL="http://localhost:8080"      # relayer origin
-export API_KEY="<relayer-api-key>"           # required
-export NETWORK="testnet"                     # or "mainnet"
-export RPC_URL="https://soroban-testnet.stellar.org"
-export ACCOUNT_NAME="test-account"           # key in `stellar keys`
-export CONTRACT_ID="CDXX..."                 # deployed smoke-contract
-```
-
-Run (args override env):
-
-```bash
-pnpm ts-node scripts/smoke.ts \
-  --api-key YOUR_API_KEY \
-  --account-name test-account \
-  --contract-id CDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
-# Show all options in the script header
-```
-
-What it does:
-
-- Health-checks the relayer
-- XDR submit-only: signs a small self-payment and submits via fee bump
-- func+auth (no auth): calls `no_auth_bump(42)` using a channel account
-- func+auth (address auth): calls `write_with_address_auth(addr, 777)` with signed auth entries

package/dist/client/channels-client.d.ts

@@ -0,0 +1,142 @@
+import type { ChannelsClientConfig, ChannelsXdrRequest, ChannelsFuncAuthRequest, ChannelsTransactionResponse, ListChannelAccountsResponse, SetChannelAccountsResponse } from "./types";
+/**
+ * Client for interacting with the Channels plugin
+ *
+ * @example
+ * // Connecting to OpenZeppelin's managed Channels service
+ * const client = new ChannelsClient({
+ *   baseUrl: 'https://channels.openzeppelin.com',
+ *   apiKey: 'your-api-key',
+ *   adminSecret: 'your-admin-secret', // Optional, for management operations
+ * });
+ *
+ * @example
+ * // Connecting to your own Relayer with Channels plugin
+ * const client = new ChannelsClient({
+ *   baseUrl: 'http://localhost:8080',
+ *   pluginId: 'channels',
+ *   apiKey: 'your-relayer-api-key',
+ *   adminSecret: 'your-admin-secret', // Optional, for management operations
+ * });
+ */
+export declare class ChannelsClient {
+    private readonly adminSecret?;
+    private readonly axiosClient?;
+    private readonly pluginsApi?;
+    private readonly pluginId?;
+    constructor(config: ChannelsClientConfig);
+    /**
+     * Submit a signed XDR transaction to the channel accounts service
+     *
+     * @param request Transaction request with signed XDR
+     * @returns Transaction result with ID, hash, and status
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const result = await client.submitTransaction({
+     *   xdr: 'AAAAAgAAAAC...',
+     * });
+     */
+    submitTransaction(request: ChannelsXdrRequest): Promise<ChannelsTransactionResponse>;
+    /**
+     * Submit a Soroban transaction using function and authorization entries
+     * This path uses channel accounts and includes automatic simulation
+     *
+     * @param request Transaction request with func and auth
+     * @returns Transaction result with ID, hash, and status
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const result = await client.submitSorobanTransaction({
+     *   func: 'AAAABgAAAA...',
+     *   auth: ['AAAABwAAAA...', 'AAAABwAAAA...'],
+     * });
+     */
+    submitSorobanTransaction(request: ChannelsFuncAuthRequest): Promise<ChannelsTransactionResponse>;
+    /**
+     * List currently configured channel accounts (requires adminSecret)
+     *
+     * @returns List of channel account relayer IDs
+     * @throws {Error} If adminSecret not provided in config
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const accounts = await client.listChannelAccounts();
+     * console.log(accounts.relayerIds);
+     */
+    listChannelAccounts(): Promise<ListChannelAccountsResponse>;
+    /**
+     * Configure channel accounts for the service (requires adminSecret)
+     *
+     * @param relayerIds Array of relayer IDs to use as channel accounts
+     * @returns Confirmation with applied relayer IDs
+     * @throws {Error} If adminSecret not provided in config
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const result = await client.setChannelAccounts([
+     *   'relayer-id-1',
+     *   'relayer-id-2',
+     * ]);
+     */
+    setChannelAccounts(relayerIds: string[]): Promise<SetChannelAccountsResponse>;
+    /**
+     * Ensures adminSecret is configured
+     *
+     * @returns The admin secret value
+     * @throws {Error} If adminSecret not provided in config
+     */
+    private requireAdminSecret;
+    /**
+     * Parses axios errors and extracts response body if available
+     *
+     * @param error The caught error from axios
+     * @returns Plugin response if available in error
+     * @throws {PluginTransportError} For network/transport errors
+     * @throws {PluginUnexpectedError} For unknown error types
+     */
+    private parseAxiosError;
+    /**
+     * Validates that response has the expected plugin response structure
+     *
+     * @param responseBody The raw response body to validate
+     * @returns Validated plugin response
+     * @throws {PluginUnexpectedError} For invalid/malformed responses
+     */
+    private validateResponse;
+    /**
+     * Merges metadata into the response data if present
+     *
+     * @param data The response data
+     * @param metadata Optional metadata (logs and traces)
+     * @returns Data with metadata merged if present
+     */
+    private mergeMetadata;
+    /**
+     * Internal method to make a plugin call with automatic payload wrapping and response parsing
+     *
+     * @param params Request parameters
+     * @returns Parsed response data with optional metadata
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     */
+    private call;
+    /**
+     * Internal method to send the actual HTTP request
+     * Routes to either axios (direct HTTP) or PluginsApi (relayer) based on configuration
+     *
+     * @param payload The complete payload (already wrapped in {params})
+     * @returns Raw response from the service/relayer
+     */
+    private sendCall;
+}
+//# sourceMappingURL=channels-client.d.ts.map

package/dist/client/channels-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels-client.d.ts","sourceRoot":"","sources":["../../src/client/channels-client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE3B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,MAAM,EAAE,oBAAoB;IA6BxC;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CACrB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,2BAA2B,CAAC;IAIvC;;;;;;;;;;;;;;;OAeG;IACG,wBAAwB,CAC5B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC;IAIvC;;;;;;;;;;;;OAYG;IACG,mBAAmB,IAAI,OAAO,CAAC,2BAA2B,CAAC;IASjE;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CACtB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,0BAA0B,CAAC;IAUtC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;OAOG;IAEH,OAAO,CAAC,eAAe;IAoBvB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;;;OAQG;YACW,IAAI;IA0BlB;;;;;;OAMG;YACW,QAAQ;CAYvB"}