@openzeppelin/relayer-plugin-channels 0.2.0

package/dist/test/tx.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const tx_1 = require("../tx");
+(0, vitest_1.describe)("tx validation", () => {
+    const passphrase = stellar_sdk_1.Networks.TESTNET;
+    (0, vitest_1.test)("throws on far future timebounds", () => {
+        const acc = new stellar_sdk_1.Account("GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF", "1");
+        const tx = new stellar_sdk_1.TransactionBuilder(acc, {
+            fee: "100",
+            networkPassphrase: passphrase,
+        })
+            .setTimeout(300)
+            .build();
+        (0, vitest_1.expect)(() => (0, tx_1.validateExistingTransactionForSubmitOnly)(tx)).toThrow("too far into the future");
+    });
+    (0, vitest_1.test)("passes on short timeout", () => {
+        const acc = new stellar_sdk_1.Account("GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF", "1");
+        const tx = new stellar_sdk_1.TransactionBuilder(acc, {
+            fee: "100",
+            networkPassphrase: passphrase,
+        })
+            .setTimeout(30)
+            .build();
+        const out = (0, tx_1.validateExistingTransactionForSubmitOnly)(tx);
+        (0, vitest_1.expect)(out).toBe(tx);
+    });
+});

package/dist/test/validation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validation.test.d.ts.map

package/dist/test/validation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.test.d.ts","sourceRoot":"","sources":["../../src/test/validation.test.ts"],"names":[],"mappings":""}

package/dist/test/validation.test.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const validation_1 = require("../validation");
+(0, vitest_1.describe)("validation", () => {
+    (0, vitest_1.test)("accepts xdr-only request", () => {
+        const out = (0, validation_1.validateAndParseRequest)({ xdr: "BASE64XDR" });
+        (0, vitest_1.expect)(out).toEqual({ type: "xdr", xdr: "BASE64XDR" });
+    });
+    (0, vitest_1.test)("rejects xdr with extra keys", () => {
+        (0, vitest_1.expect)(() => (0, validation_1.validateAndParseRequest)({ xdr: "X", extra: 1 })).toThrow("`xdr` request must not include other parameters");
+    });
+    (0, vitest_1.test)("accepts func+auth with valid base64", () => {
+        const contract = new stellar_sdk_1.Contract("CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC");
+        const op = contract.call("no_auth_bump", stellar_sdk_1.xdr.ScVal.scvU32(1));
+        const body = op.body();
+        const inv = body.invokeHostFunctionOp();
+        const func = inv.hostFunction().toXDR("base64");
+        const auth = (inv.auth() ?? []).map((a) => a.toXDR("base64"));
+        const out = (0, validation_1.validateAndParseRequest)({ func, auth });
+        (0, vitest_1.expect)(out.type).toBe("func-auth");
+    });
+    (0, vitest_1.test)("rejects missing both", () => {
+        (0, vitest_1.expect)(() => (0, validation_1.validateAndParseRequest)({})).toThrow("Must pass either `xdr` or `func` and `auth`");
+    });
+    (0, vitest_1.test)("rejects missing func or missing auth", () => {
+        (0, vitest_1.expect)(() => (0, validation_1.validateAndParseRequest)({ func: "AAAA" })).toThrow("`func` and `auth` are both required");
+        (0, vitest_1.expect)(() => (0, validation_1.validateAndParseRequest)({ auth: [] })).toThrow("`func` and `auth` are both required");
+    });
+});

package/dist/tx.d.ts

@@ -0,0 +1,8 @@
+/**
+ * tx.ts
+ *
+ * Transaction validation helpers for the XDR submit-only path.
+ */
+import { Transaction } from "@stellar/stellar-sdk";
+export declare function validateExistingTransactionForSubmitOnly(tx: Transaction): Transaction;
+//# sourceMappingURL=tx.d.ts.map

package/dist/tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../src/tx.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AAIxD,wBAAgB,wCAAwC,CACtD,EAAE,EAAE,WAAW,GACd,WAAW,CA6Cb"}

package/dist/tx.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * tx.ts
+ *
+ * Transaction validation helpers for the XDR submit-only path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateExistingTransactionForSubmitOnly = validateExistingTransactionForSubmitOnly;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
+const constants_1 = require("./constants");
+function validateExistingTransactionForSubmitOnly(tx) {
+    const now = Math.floor(Date.now() / 1000);
+    // Reject fee-bump envelopes
+    const envelope = tx.toEnvelope();
+    const kind = envelope.switch();
+    if (kind !== stellar_sdk_1.xdr.EnvelopeType.envelopeTypeTx()) {
+        throw (0, relayer_sdk_1.pluginError)("Input must be a regular transaction envelope (fee-bump not allowed)", {
+            code: "INVALID_ENVELOPE_TYPE",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    // Soroban sanity checks
+    const sorobanData = envelope.v1().tx().ext().sorobanData();
+    if (sorobanData) {
+        const resourceFee = sorobanData.resourceFee().toBigInt();
+        if (BigInt(tx.fee) > resourceFee + 201n) {
+            throw (0, relayer_sdk_1.pluginError)("Transaction fee must be equal to the resource fee", {
+                code: "FEE_MISMATCH",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: { fee: tx.fee, resourceFee: resourceFee.toString() },
+            });
+        }
+    }
+    // Time bounds sanity
+    if (tx.timeBounds?.maxTime &&
+        Number(tx.timeBounds.maxTime) - now >
+            constants_1.SIMULATION.MAX_FUTURE_TIME_BOUND_SECONDS) {
+        throw (0, relayer_sdk_1.pluginError)(`Transaction \`timeBounds.maxTime\` too far into the future. Must be no greater than ${constants_1.SIMULATION.MAX_FUTURE_TIME_BOUND_SECONDS} seconds`, {
+            code: "TIMEBOUNDS_TOO_FAR",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    return tx;
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * types.ts
+ *
+ * Type definitions for the channel accounts plugin.
+ */
+/**
+ * Plugin request parameters:
+ * - Submit-only: signed regular transaction XDR
+ * - Channel build: func + auth (always simulated)
+ */
+import type { xdr } from "@stellar/stellar-sdk";
+export type ChannelAccountsRequest = {
+    type: "xdr";
+    xdr: string;
+} | {
+    type: "func-auth";
+    func: xdr.HostFunction;
+    auth: xdr.SorobanAuthorizationEntry[];
+};
+/**
+ * Plugin response format aligned with launchtube
+ */
+export interface ChannelAccountsResponse {
+    transactionId: string | null;
+    status: string | null;
+    hash: string | null;
+}
+/**
+ * Management request structure
+ */
+export interface ManagementRequest {
+    management: {
+        adminSecret: string;
+        action: "listChannelAccounts" | "setChannelAccounts";
+        relayerIds?: string[];
+    };
+}
+/**
+ * Management response for listing channel accounts
+ */
+export interface ListChannelAccountsResponse {
+    relayerIds: string[];
+}
+/**
+ * Management response for setting channel accounts
+ */
+export interface SetChannelAccountsResponse {
+    ok: boolean;
+    appliedRelayerIds: string[];
+}
+/**
+ * Channel account info
+ */
+export interface ChannelAccountInfo {
+    relayerId: string;
+    address: string;
+    sequenceNumber: string;
+}
+/**
+ * Fund account info
+ */
+export interface FundAccountInfo {
+    relayerId: string;
+    address: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,CAAC;CACvC,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;QACrD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * types.ts
+ *
+ * Type definitions for the channel accounts plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * validation.ts
+ *
+ * Request validation and parsing for the Channel Accounts plugin.
+ * Supports either a signed XDR or func+auth.
+ */
+import { ChannelAccountsRequest } from "./types";
+export declare function validateAndParseRequest(params: any): ChannelAccountsRequest;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEjD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,GAAG,GAAG,sBAAsB,CAyF3E"}

package/dist/validation.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * validation.ts
+ *
+ * Request validation and parsing for the Channel Accounts plugin.
+ * Supports either a signed XDR or func+auth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndParseRequest = validateAndParseRequest;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
+const constants_1 = require("./constants");
+function validateAndParseRequest(params) {
+    if (!params || typeof params !== "object") {
+        throw (0, relayer_sdk_1.pluginError)("Invalid request: params must be an object", {
+            code: "INVALID_PARAMS",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    // Disallow any management-shaped keys leaking into here; management is handled earlier
+    const keys = Object.keys(params);
+    // Mode: XDR
+    if ("xdr" in params) {
+        if (typeof params.xdr !== "string" || params.xdr.trim() === "") {
+            throw (0, relayer_sdk_1.pluginError)("`xdr` must be a non-empty base64 string", {
+                code: "INVALID_PARAMS",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+            });
+        }
+        // Strict: cannot include func/auth when using xdr
+        const unknown = keys.filter((k) => !["xdr"].includes(k));
+        if (unknown.length > 0) {
+            throw (0, relayer_sdk_1.pluginError)("`xdr` request must not include other parameters", {
+                code: "INVALID_PARAMS",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: { unknown },
+            });
+        }
+        return { type: "xdr", xdr: params.xdr.trim() };
+    }
+    // Mode: func+auth
+    if ("func" in params || "auth" in params) {
+        if (!params.func || !params.auth) {
+            throw (0, relayer_sdk_1.pluginError)("`func` and `auth` are both required when omitting `xdr`", {
+                code: "INVALID_PARAMS",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+            });
+        }
+        // Parse values from base64
+        let func;
+        let auth = [];
+        try {
+            func = stellar_sdk_1.xdr.HostFunction.fromXDR(params.func, "base64");
+            if (!Array.isArray(params.auth)) {
+                throw new Error("auth must be an array of base64 strings");
+            }
+            auth = params.auth.map((a) => stellar_sdk_1.xdr.SorobanAuthorizationEntry.fromXDR(a, "base64"));
+        }
+        catch (e) {
+            throw (0, relayer_sdk_1.pluginError)("Invalid `func` or `auth` encoding", {
+                code: "INVALID_PARAMS",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: { message: e instanceof Error ? e.message : String(e) },
+            });
+        }
+        // Reject SourceAccount credentials: incompatible with relayer-managed channel source
+        for (const entry of auth) {
+            const credType = entry.credentials().switch();
+            if (credType ===
+                stellar_sdk_1.xdr.SorobanCredentialsType.sorobanCredentialsSourceAccount()) {
+                throw (0, relayer_sdk_1.pluginError)("Detached address credentials required: source-account credentials are incompatible with relayer-managed channel accounts", {
+                    code: "INVALID_PARAMS",
+                    status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                    details: { reason: "source-account credentials not allowed" },
+                });
+            }
+        }
+        return { type: "func-auth", func, auth };
+    }
+    throw (0, relayer_sdk_1.pluginError)("Must pass either `xdr` or `func` and `auth`", {
+        code: "INVALID_PARAMS",
+        status: constants_1.HTTP_STATUS.BAD_REQUEST,
+    });
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@openzeppelin/relayer-plugin-channels",
+  "version": "0.2.0",
+  "description": "OpenZeppelin Relayer Plugin for Stellar Channel Accounts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenZeppelin/relayer-plugin-channels.git"
+  },
+  "author": "OpenZeppelin <contact@openzeppelin.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@openzeppelin/relayer-sdk": "^1.6.0",
+    "@stellar/stellar-sdk": "^11.2.0",
+    "@actions/exec": "^1.1.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.7",
+    "@types/node": "^22.13.14",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "eslint": "^9.22.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.27.0",
+    "vitest": "^4.0.4"
+  },
+  "engines": {
+    "node": ">=22.18.0",
+    "npm": "use pnpm",
+    "pnpm": ">=9",
+    "yarn": "use pnpm"
+  },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "lint:fix": "pnpm prettier:fix && pnpm lint:check && pnpm prettier:check",
+    "prettier:check": "prettier -u --check '**/*.{js,ts,tsx,md}'",
+    "prettier:fix": "prettier -u --write '**/*.{js,ts,tsx,md}'",
+    "style": "pnpm lint:fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "install-deps": "pnpm install --frozen-lockfile --ignore-scripts --prefer-offline",
+    "install-pnpm": "npm install -g pnpm",
+    "ci:version": "pnpm changeset version",
+    "release": "node ./scripts/release.js"
+  }
+}