@acta-markets/ts-sdk 0.0.1-beta

package/dist/ws/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ws/client.test.js

@@ -0,0 +1,228 @@
+import { ActaWsClient } from "./client";
+const WS_CONNECTING = 0;
+const WS_OPEN = 1;
+const WS_CLOSED = 3;
+const WELCOME_MESSAGE = {
+    type: "Welcome",
+    data: {
+        protocol_version: "1.0.0",
+        server_version: "test",
+        min_supported_version: "1.0.0",
+        enabled_features: [],
+    },
+};
+class MockWebSocket {
+    url;
+    readyState = WS_CONNECTING;
+    onopen = null;
+    onclose = null;
+    onerror = null;
+    onmessage = null;
+    sent = [];
+    constructor(url) {
+        this.url = url;
+    }
+    send(data) {
+        this.sent.push(data);
+    }
+    close(code, reason) {
+        this.readyState = WS_CLOSED;
+        this.onclose?.({ code, reason });
+    }
+    triggerOpen() {
+        this.readyState = WS_OPEN;
+        this.onopen?.({});
+    }
+    triggerClose(code = 1000, reason = "") {
+        this.readyState = WS_CLOSED;
+        this.onclose?.({ code, reason });
+    }
+    triggerError(value) {
+        this.onerror?.(value);
+    }
+    triggerMessage(message) {
+        this.onmessage?.({ data: JSON.stringify(message) });
+    }
+}
+function parseClientMessage(payload) {
+    return JSON.parse(payload);
+}
+function makeAuthProvider(pubkey = "pubkey", signature = "signature") {
+    return {
+        getPublicKey: jest.fn().mockResolvedValue(pubkey),
+        signChallenge: jest.fn().mockResolvedValue(signature),
+    };
+}
+function makeHarness(overrides = {}) {
+    let currentSocket = null;
+    const client = new ActaWsClient({
+        url: "ws://localhost:1234",
+        role: "taker",
+        autoReconnect: false,
+        ...overrides,
+        makeSocket: (url) => {
+            currentSocket = new MockWebSocket(url);
+            return currentSocket;
+        },
+    });
+    return {
+        client,
+        socket: () => {
+            if (!currentSocket) {
+                throw new Error("Socket is not initialized");
+            }
+            return currentSocket;
+        },
+    };
+}
+async function flushMicrotasks() {
+    await Promise.resolve();
+    await Promise.resolve();
+}
+describe("ActaWsClient", () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+        jest.useRealTimers();
+    });
+    it("uses 1.0.0 protocolVersion by default in Hello", () => {
+        const { client, socket } = makeHarness();
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        expect(ws.sent).toHaveLength(1);
+        const hello = parseClientMessage(ws.sent[0]);
+        expect(hello.type).toBe("Hello");
+        if (hello.type === "Hello") {
+            expect(hello.data.protocol_version).toBe("1.0.0");
+        }
+    });
+    it("connectAndAuthenticate sends StartAuth after Welcome", async () => {
+        const { client, socket } = makeHarness();
+        const auth = makeAuthProvider("WalletPubkey", "WalletSignature");
+        client.connectAndAuthenticate(auth);
+        const ws = socket();
+        ws.triggerOpen();
+        ws.triggerMessage(WELCOME_MESSAGE);
+        await flushMicrotasks();
+        const sentTypes = ws.sent.map((payload) => parseClientMessage(payload).type);
+        expect(sentTypes).toEqual(["Hello", "StartAuth"]);
+        ws.triggerMessage({
+            type: "AuthRequest",
+            data: { challenge: "challenge-text" },
+        });
+        await flushMicrotasks();
+        const authChallenge = parseClientMessage(ws.sent[2]);
+        expect(authChallenge.type).toBe("AuthChallenge");
+        if (authChallenge.type === "AuthChallenge") {
+            expect(authChallenge.data.pubkey).toBe("WalletPubkey");
+            expect(authChallenge.data.signature).toBe("WalletSignature");
+            expect(authChallenge.data.challenge).toBe("challenge-text");
+        }
+    });
+    it("drop_oldest policy keeps the latest queued messages", () => {
+        const { client, socket } = makeHarness({
+            maxPendingMessages: 2,
+            pendingMessagesOverflowPolicy: "drop_oldest",
+        });
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        client.getMarkets();
+        client.getTokens();
+        client.getExpiries();
+        ws.triggerMessage(WELCOME_MESSAGE);
+        const flushedTypes = ws.sent
+            .slice(1)
+            .map((x) => parseClientMessage(x).type);
+        expect(flushedTypes).toEqual(["GetTokens", "GetExpiries"]);
+    });
+    it("drop_newest policy ignores newest message when queue is full", () => {
+        const { client, socket } = makeHarness({
+            maxPendingMessages: 2,
+            pendingMessagesOverflowPolicy: "drop_newest",
+        });
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        client.getMarkets();
+        client.getTokens();
+        client.getExpiries();
+        ws.triggerMessage(WELCOME_MESSAGE);
+        const flushedTypes = ws.sent
+            .slice(1)
+            .map((x) => parseClientMessage(x).type);
+        expect(flushedTypes).toEqual(["GetMarkets", "GetTokens"]);
+    });
+    it("throw policy emits error and does not grow queue", () => {
+        const { client, socket } = makeHarness({
+            maxPendingMessages: 1,
+            pendingMessagesOverflowPolicy: "throw",
+        });
+        const errors = [];
+        client.on("error", (err) => errors.push(err));
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        client.getMarkets();
+        client.getTokens();
+        expect(errors).toHaveLength(1);
+        expect(errors[0].message).toContain("Pending queue overflow");
+        ws.triggerMessage(WELCOME_MESSAGE);
+        const flushedTypes = ws.sent
+            .slice(1)
+            .map((x) => parseClientMessage(x).type);
+        expect(flushedTypes).toEqual(["GetMarkets"]);
+    });
+    it("applies jitter to reconnect delay", () => {
+        jest.useFakeTimers();
+        const randomSpy = jest.spyOn(Math, "random").mockReturnValue(1);
+        const timeoutSpy = jest.spyOn(global, "setTimeout");
+        const { client, socket } = makeHarness({
+            autoReconnect: true,
+            reconnectDelay: 1000,
+            maxReconnectDelay: 30_000,
+            reconnectJitterRatio: 0.5,
+        });
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        ws.triggerClose(1006, "abnormal_close");
+        expect(timeoutSpy).toHaveBeenCalled();
+        const scheduledDelay = timeoutSpy.mock.calls[0][1];
+        expect(scheduledDelay).toBe(1500);
+        randomSpy.mockRestore();
+        timeoutSpy.mockRestore();
+    });
+    it("stops auto reconnect on VersionMismatch", () => {
+        jest.useFakeTimers();
+        const timeoutSpy = jest.spyOn(global, "setTimeout");
+        const { client, socket } = makeHarness({
+            autoReconnect: true,
+        });
+        client.connectAnonymous();
+        const ws = socket();
+        ws.triggerOpen();
+        ws.triggerMessage({
+            type: "VersionMismatch",
+            data: {
+                requested_version: "1.0.0",
+                server_version: "1.1.0",
+                min_supported_version: "1.1.0",
+                message: "incompatible protocol version",
+            },
+        });
+        expect(timeoutSpy).not.toHaveBeenCalled();
+        timeoutSpy.mockRestore();
+    });
+    it("emits orderAccepted event payload", () => {
+        const { client } = makeHarness();
+        const hex = "11".repeat(32);
+        let got = null;
+        client.on("orderAccepted", (h) => (got = h));
+        client.handleMessage({
+            type: "OrderAccepted",
+            data: { order_id: hex },
+        });
+        expect(got).toBe(hex);
+    });
+});

package/dist/ws/discovery.d.ts

@@ -0,0 +1,13 @@
+import type { MarketDescriptorInfo, TokenInfo, WsU64 } from "./types";
+export type DeriveTokenListsResult = {
+    underlyings: TokenInfo[];
+    quotesByUnderlying: Record<string, TokenInfo[]>;
+};
+/** Derive token dropdown lists from `MarketDescriptorInfo[]`. */
+export declare function deriveTokenLists(markets: MarketDescriptorInfo[]): DeriveTokenListsResult;
+/** Derive expiry list (unix seconds) from `MarketDescriptorInfo[]`, optionally filtered. */
+export declare function deriveExpiries(markets: MarketDescriptorInfo[], filters?: {
+    underlyingMint?: string;
+    quoteMint?: string;
+    isPut?: boolean | null;
+}): WsU64[];

package/dist/ws/discovery.js

@@ -0,0 +1,44 @@
+/** Derive token dropdown lists from `MarketDescriptorInfo[]`. */
+export function deriveTokenLists(markets) {
+    const underlyings = new Map();
+    const quotesByUnderlying = new Map();
+    for (const m of markets) {
+        const uMint = String(m.market.underlying_mint);
+        const qMint = String(m.market.quote_mint);
+        underlyings.set(uMint, {
+            mint: m.market.underlying_mint,
+            decimals: m.underlying_decimals,
+            symbol: m.underlying_symbol,
+        });
+        const q = {
+            mint: m.market.quote_mint,
+            decimals: m.quote_decimals,
+            symbol: m.quote_symbol,
+        };
+        const inner = quotesByUnderlying.get(uMint) ?? new Map();
+        inner.set(qMint, q);
+        quotesByUnderlying.set(uMint, inner);
+    }
+    const underlyingsOut = Array.from(underlyings.values()).sort((a, b) => String(a.mint).localeCompare(String(b.mint)));
+    const quotesOut = {};
+    for (const [u, qs] of quotesByUnderlying.entries()) {
+        quotesOut[u] = Array.from(qs.values()).sort((a, b) => String(a.mint).localeCompare(String(b.mint)));
+    }
+    return { underlyings: underlyingsOut, quotesByUnderlying: quotesOut };
+}
+/** Derive expiry list (unix seconds) from `MarketDescriptorInfo[]`, optionally filtered. */
+export function deriveExpiries(markets, filters) {
+    const set = new Set();
+    for (const m of markets) {
+        if (filters?.underlyingMint &&
+            String(m.market.underlying_mint) !== String(filters.underlyingMint))
+            continue;
+        if (filters?.quoteMint &&
+            String(m.market.quote_mint) !== String(filters.quoteMint))
+            continue;
+        if (filters?.isPut != null && m.market.is_put !== filters.isPut)
+            continue;
+        set.add(m.market.expiry_ts);
+    }
+    return Array.from(set.values()).sort((a, b) => a - b);
+}

package/dist/ws/flows.d.ts

@@ -0,0 +1,44 @@
+/**
+ * WS flow helpers that enforce SDK-wide `orderId` rules:
+ * - canonical `orderId` is 32 bytes (sha256 preimage)
+ * - WS wire uses hex string for `order_id` and base58 for signatures
+ */
+import type { Address } from "@solana/addresses";
+import type { AcceptQuoteMessage, QuoteMessage, RfqBroadcastMessage } from "./types";
+import type { SignerLike } from "../chain/orders";
+export declare function buildSignedQuoteMessage(args: {
+    rfqId: string;
+    strike: number;
+    price: number;
+    validUntil: number;
+    nonce: number;
+    orderId: Uint8Array;
+    makerSigner: SignerLike;
+}): Promise<QuoteMessage>;
+/**
+ * Strict maker helper: build a fully-valid quote from a server RFQ broadcast.
+ *
+ * Rules enforced:
+ * - `strike` MUST be one of `rfq.order_options`.
+ * - `nonce` is maker-provided (server never assigns it). Use your own RNG
+ *   or the SDK's `NonceGenerator` helper.
+ * - `order_id` is computed as sha256(preimage182) using canonical fields.
+ * - signature is Ed25519 over 32-byte `order_id`.
+ */
+export declare function buildSignedQuoteFromRfq(args: {
+    rfq: RfqBroadcastMessage;
+    strike: number;
+    price: number;
+    validUntil: number;
+    /** Maker-provided u64 nonce (recommended: random). */
+    nonce: number;
+    /** Maker owner pubkey (base58). Included in order_id preimage. */
+    makerOwner: Address<string>;
+    /** Maker signing key (ed25519) that signs 32-byte order_id. */
+    makerSigner: SignerLike;
+}): Promise<QuoteMessage>;
+export declare function buildAcceptQuoteMessage(args: {
+    rfqId: string;
+    maker: Address<string>;
+    orderId: Uint8Array;
+}): AcceptQuoteMessage;

package/dist/ws/flows.js

@@ -0,0 +1,96 @@
+/**
+ * WS flow helpers that enforce SDK-wide `orderId` rules:
+ * - canonical `orderId` is 32 bytes (sha256 preimage)
+ * - WS wire uses hex string for `order_id` and base58 for signatures
+ */
+import { computeOrderId, signOrderIdBase58 } from "../chain/orders";
+import { assertOrderId32, orderIdToHex } from "../types/orderId";
+import { assertWsU64Safe } from "./wirePolicy";
+export async function buildSignedQuoteMessage(args) {
+    // WS numeric safety: these fields are u64 in Rust and must be safe integers in JS.
+    assertWsU64Safe(args.strike, "strike");
+    assertWsU64Safe(args.price, "price");
+    assertWsU64Safe(args.validUntil, "validUntil");
+    assertWsU64Safe(args.nonce, "nonce");
+    assertOrderId32(args.orderId);
+    const { signatureBase58 } = await signOrderIdBase58(args.makerSigner, args.orderId);
+    return {
+        rfq_id: args.rfqId,
+        strike: args.strike,
+        price: args.price,
+        valid_until: args.validUntil,
+        nonce: args.nonce,
+        order_id: orderIdToHex(args.orderId),
+        signature: signatureBase58,
+    };
+}
+function positionTypeToU8(positionType) {
+    switch (positionType) {
+        case "covered_call":
+            return 0;
+        case "cash_secured_put":
+            return 1;
+        default:
+            throw new Error(`Unknown position_type: ${positionType}`);
+    }
+}
+/**
+ * Strict maker helper: build a fully-valid quote from a server RFQ broadcast.
+ *
+ * Rules enforced:
+ * - `strike` MUST be one of `rfq.order_options`.
+ * - `nonce` is maker-provided (server never assigns it). Use your own RNG
+ *   or the SDK's `NonceGenerator` helper.
+ * - `order_id` is computed as sha256(preimage182) using canonical fields.
+ * - signature is Ed25519 over 32-byte `order_id`.
+ */
+export async function buildSignedQuoteFromRfq(args) {
+    // WS numeric safety: order_id preimage packs these as u64; JS must not lose precision.
+    assertWsU64Safe(args.rfq.market.chain_id, "rfq.market.chain_id");
+    assertWsU64Safe(args.rfq.quantity, "rfq.quantity");
+    assertWsU64Safe(args.strike, "strike");
+    assertWsU64Safe(args.price, "price");
+    assertWsU64Safe(args.validUntil, "validUntil");
+    assertWsU64Safe(args.nonce, "nonce");
+    const opts = args.rfq.order_options;
+    if (!opts || opts.length === 0) {
+        throw new Error("rfq.order_options is required to build a strict quote");
+    }
+    const option = opts.find((o) => o.strike === args.strike);
+    if (!option) {
+        throw new Error("strike must match one of rfq.order_options");
+    }
+    const orderId = computeOrderId({
+        chainId: args.rfq.market.chain_id,
+        programId: args.rfq.market.program_id,
+        isTakerBuy: false,
+        positionType: positionTypeToU8(args.rfq.position_type),
+        market: args.rfq.market.market_pda,
+        strike: args.strike,
+        quantity: args.rfq.quantity,
+        price: args.price,
+        validUntil: args.validUntil,
+        maker: args.makerOwner,
+        taker: args.rfq.taker,
+        nonce: args.nonce,
+    });
+    assertOrderId32(orderId);
+    const { signatureBase58 } = await signOrderIdBase58(args.makerSigner, orderId);
+    return {
+        rfq_id: args.rfq.rfq_id,
+        strike: args.strike,
+        price: args.price,
+        valid_until: args.validUntil,
+        nonce: args.nonce,
+        order_id: orderIdToHex(orderId),
+        signature: signatureBase58,
+    };
+}
+export function buildAcceptQuoteMessage(args) {
+    assertOrderId32(args.orderId);
+    return {
+        rfq_id: args.rfqId,
+        maker: args.maker,
+        order_id: orderIdToHex(args.orderId),
+    };
+}

package/dist/ws/flows.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ws/flows.test.js

@@ -0,0 +1,83 @@
+import { buildSignedQuoteFromRfq, buildSignedQuoteMessage, } from "./flows";
+import { orderIdToHex } from "../types/orderId";
+import { getAddressDecoder } from "@solana/addresses";
+import { getBase58Decoder } from "@solana/codecs-strings";
+describe("ws flows", () => {
+    it("buildSignedQuoteMessage encodes order_id as hex and signature as base58", async () => {
+        const base58 = getBase58Decoder();
+        const decoder = getAddressDecoder();
+        const makerPk = decoder.decode(new Uint8Array(32).fill(7));
+        const orderId = new Uint8Array(32).fill(1);
+        const mockSig = new Uint8Array(64).fill(9);
+        const makerSigner = {
+            publicKey: makerPk,
+            signMessage: async (msg) => {
+                expect(msg).toEqual(orderId);
+                return mockSig;
+            },
+        };
+        const quote = await buildSignedQuoteMessage({
+            rfqId: "rfq-1",
+            strike: 1100,
+            price: 123,
+            validUntil: 456,
+            nonce: 42,
+            orderId,
+            makerSigner,
+        });
+        expect(quote.strike).toBe(1100);
+        expect(quote.order_id).toBe(orderIdToHex(orderId));
+        expect(quote.signature).toBe(base58.decode(mockSig));
+    });
+    it("buildSignedQuoteFromRfq uses maker-provided nonce and computes order_id", async () => {
+        const base58 = getBase58Decoder();
+        const decoder = getAddressDecoder();
+        const makerSigningPk = decoder.decode(new Uint8Array(32).fill(7));
+        const mockSig = new Uint8Array(64).fill(9);
+        const makerSigner = {
+            publicKey: makerSigningPk,
+            signMessage: async (msg) => {
+                // ensure we are signing a 32-byte order id
+                expect(msg).toHaveLength(32);
+                return mockSig;
+            },
+        };
+        const rfq = {
+            rfq_id: "rfq-1",
+            market: {
+                chain_id: 0,
+                program_id: decoder.decode(new Uint8Array(32).fill(4)),
+                market_pda: decoder.decode(new Uint8Array(32).fill(1)),
+                underlying_mint: decoder.decode(new Uint8Array(32).fill(11)),
+                quote_mint: decoder.decode(new Uint8Array(32).fill(12)),
+                expiry_ts: 1_700_000_000,
+                is_put: false,
+                collateral_mint: decoder.decode(new Uint8Array(32).fill(13)),
+                settlement_mint: decoder.decode(new Uint8Array(32).fill(14)),
+            },
+            position_type: "covered_call",
+            strike: 1000,
+            quantity: 2,
+            expires_at: 999,
+            taker: decoder.decode(new Uint8Array(32).fill(2)),
+            order_options: [
+                { strike: 1050 },
+                { strike: 1100 },
+            ],
+        };
+        const quote = await buildSignedQuoteFromRfq({
+            rfq,
+            strike: 1100,
+            price: 123,
+            validUntil: 456,
+            nonce: 43,
+            makerOwner: decoder.decode(new Uint8Array(32).fill(3)),
+            makerSigner,
+        });
+        expect(quote.rfq_id).toBe("rfq-1");
+        expect(quote.strike).toBe(1100);
+        expect(quote.nonce).toBe(43);
+        expect(quote.order_id).toHaveLength(64); // hex32
+        expect(quote.signature).toBe(base58.decode(mockSig));
+    });
+});

package/dist/ws/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./auth";
+export * from "./client";
+export * from "./flows";
+export * from "./sponsoredTx";
+export * from "./apy";
+export * from "./discovery";

package/dist/ws/index.js

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./auth";
+export * from "./client";
+export * from "./flows";
+export * from "./sponsoredTx";
+export * from "./apy";
+export * from "./discovery";

package/dist/ws/sponsoredTx.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sponsored tx helpers for WS flow.
+ *
+ * The server sends `tx_base64` as base64-encoded Solana wire transaction bytes:
+ *   <shortvec num_sigs> | <sigs[64]*num_sigs> | <message bytes>
+ *
+ * The taker signs the **message bytes** and fills its signature slot (index 1 by convention:
+ * 0 = relayer fee payer, 1 = taker).
+ */
+import type { KeyPairSigner } from "@solana/kit";
+export type MessageSigner = {
+    /** Return raw 64-byte ed25519 signature over `message`. */
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+};
+export type WalletStandardMessageSigner = {
+    /** Wallet-standard `signMessages` (used by @solana/kit signers and some wallets). */
+    signMessages(messages: Array<{
+        content: Uint8Array;
+    }>): Promise<any>;
+    /** Optional address used by wallet-standard result maps. */
+    address?: string;
+};
+/**
+ * Sign a sponsored tx template in-place and return new base64.
+ *
+ * Convention:
+ * - signature slot 0: relayer (must remain default/zero at this step)
+ * - signature slot 1: taker (filled by this helper)
+ */
+export declare function signSponsoredTxBase64(args: {
+    txBase64: string;
+    /**
+     * Any signer capable of producing an ed25519 signature over the transaction message bytes:
+     * - @solana/kit KeyPairSigner
+     * - wallet-adapter style: { signMessage(bytes): Uint8Array }
+     */
+    taker: KeyPairSigner | MessageSigner | WalletStandardMessageSigner;
+    takerSignatureIndex?: number;
+}): Promise<string>;

package/dist/ws/sponsoredTx.js

@@ -0,0 +1,92 @@
+/**
+ * Sponsored tx helpers for WS flow.
+ *
+ * The server sends `tx_base64` as base64-encoded Solana wire transaction bytes:
+ *   <shortvec num_sigs> | <sigs[64]*num_sigs> | <message bytes>
+ *
+ * The taker signs the **message bytes** and fills its signature slot (index 1 by convention:
+ * 0 = relayer fee payer, 1 = taker).
+ */
+async function signMessageWithSigner(signer, message) {
+    // Path A: plain signMessage (wallet-adapter style, Privy/Phantom via adapters).
+    if (typeof signer.signMessage === "function") {
+        const sig = await signer.signMessage(message);
+        return sig;
+    }
+    // Path B: wallet-standard signMessages (used by @solana/kit KeyPairSigner).
+    if (typeof signer.signMessages === "function") {
+        const res = await signer.signMessages([{ content: message }]);
+        const addr = signer.address;
+        const sig = addr && res?.[0] ? res?.[0]?.[addr] : Object.values(res?.[0] ?? {})?.[0];
+        if (sig instanceof Uint8Array)
+            return sig;
+    }
+    throw new Error("Signer does not support signMessage/signMessages");
+}
+function decodeShortU16Len(bytes, offset = 0) {
+    // Solana shortvec: little-endian base128 varint (u16 in practice).
+    let value = 0;
+    let shift = 0;
+    let i = offset;
+    while (i < bytes.length) {
+        const b = bytes[i];
+        value |= (b & 0x7f) << shift;
+        i += 1;
+        if ((b & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift > 21)
+            throw new Error("shortvec too long");
+    }
+    return { value, size: i - offset };
+}
+function bytesToBase64(bytes) {
+    // Browser
+    if (typeof globalThis.btoa === "function") {
+        let s = "";
+        for (let i = 0; i < bytes.length; i++)
+            s += String.fromCharCode(bytes[i]);
+        return globalThis.btoa(s);
+    }
+    // Node
+    return Buffer.from(bytes).toString("base64");
+}
+function base64ToBytes(b64) {
+    // Browser
+    if (typeof globalThis.atob === "function") {
+        const bin = globalThis.atob(b64.trim());
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    // Node
+    return new Uint8Array(Buffer.from(b64.trim(), "base64"));
+}
+/**
+ * Sign a sponsored tx template in-place and return new base64.
+ *
+ * Convention:
+ * - signature slot 0: relayer (must remain default/zero at this step)
+ * - signature slot 1: taker (filled by this helper)
+ */
+export async function signSponsoredTxBase64(args) {
+    const idx = args.takerSignatureIndex ?? 1;
+    const bytes = base64ToBytes(args.txBase64);
+    const { value: sigCount, size: sigCountSize } = decodeShortU16Len(bytes, 0);
+    if (sigCount <= idx) {
+        throw new Error(`tx has sigCount=${sigCount}, cannot fill index=${idx}`);
+    }
+    const sigsStart = sigCountSize;
+    const msgStart = sigsStart + sigCount * 64;
+    if (msgStart > bytes.length)
+        throw new Error("invalid tx bytes (truncated)");
+    const msgBytes = bytes.slice(msgStart);
+    const sig = await signMessageWithSigner(args.taker, msgBytes);
+    if (!(sig instanceof Uint8Array) || sig.length !== 64) {
+        throw new Error("signer returned invalid signature");
+    }
+    const out = Uint8Array.from(bytes);
+    out.set(sig, sigsStart + idx * 64);
+    return bytesToBase64(out);
+}