@stacks-passkey/relay 0.1.0

package/dist/load-env.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Load packages/relay/.env if present. Never commit that file.
+ */
+export function loadRelayEnv() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const envPath = resolve(here, '../.env');
+    if (!existsSync(envPath))
+        return;
+    const content = parseEnvFile(readFileSync(envPath, 'utf8'));
+    for (const [key, value] of Object.entries(content)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+function parseEnvFile(text) {
+    const out = {};
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        let value = trimmed.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}

package/dist/on-chain-balance.d.ts

@@ -0,0 +1,4 @@
+import type { RelayConfig } from './types.js';
+export declare function fetchStxBalanceMicro(address: string, networkName: RelayConfig['network']): Promise<bigint>;
+/** @internal test helper */
+export declare function clearStxBalanceCache(): void;

package/dist/on-chain-balance.js

@@ -0,0 +1,60 @@
+import { STACKS_MAINNET, STACKS_TESTNET } from '@stacks/network';
+function getNetwork(name) {
+    return name === 'mainnet' ? STACKS_MAINNET : STACKS_TESTNET;
+}
+const CACHE_TTL_MS = 15_000;
+const balanceCache = new Map();
+function cacheKey(address, networkName) {
+    return `${networkName}:${address}`;
+}
+function readCachedBalance(address, networkName) {
+    const entry = balanceCache.get(cacheKey(address, networkName));
+    if (!entry)
+        return null;
+    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS)
+        return null;
+    return entry.balance;
+}
+function readStaleBalance(address, networkName) {
+    return balanceCache.get(cacheKey(address, networkName))?.balance ?? null;
+}
+function writeCachedBalance(address, networkName, balance) {
+    balanceCache.set(cacheKey(address, networkName), { balance, fetchedAt: Date.now() });
+}
+async function fetchBalanceFromApi(address, networkName) {
+    const network = getNetwork(networkName);
+    return fetch(`${network.client.baseUrl}/extended/v1/address/${address}/stx`);
+}
+export async function fetchStxBalanceMicro(address, networkName) {
+    const cached = readCachedBalance(address, networkName);
+    if (cached !== null)
+        return cached;
+    let lastStatus = 0;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (attempt > 0) {
+            await new Promise((r) => setTimeout(r, 400 * attempt));
+        }
+        const res = await fetchBalanceFromApi(address, networkName);
+        lastStatus = res.status;
+        if (res.status === 429)
+            continue;
+        if (!res.ok) {
+            const stale = readStaleBalance(address, networkName);
+            if (stale !== null)
+                return stale;
+            throw new Error(`Unable to fetch STX balance for ${address}: ${res.status}`);
+        }
+        const data = (await res.json());
+        const balance = BigInt(data.balance ?? '0');
+        writeCachedBalance(address, networkName, balance);
+        return balance;
+    }
+    const stale = readStaleBalance(address, networkName);
+    if (stale !== null)
+        return stale;
+    throw new Error(`Unable to fetch STX balance for ${address}: ${lastStatus}`);
+}
+/** @internal test helper */
+export function clearStxBalanceCache() {
+    balanceCache.clear();
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,9 @@
+import type { RelayPolicy } from './types.js';
+export declare class RateLimiter {
+    private buckets;
+    private readonly windowMs;
+    private readonly maxRequests;
+    constructor(policy: RelayPolicy);
+    check(key: string): boolean;
+}
+export declare function isContractAllowed(contractId: string, policy: RelayPolicy): boolean;

package/dist/rate-limit.js

@@ -0,0 +1,29 @@
+export class RateLimiter {
+    buckets = new Map();
+    windowMs;
+    maxRequests;
+    constructor(policy) {
+        this.windowMs = policy.rateLimit.windowMs;
+        this.maxRequests = policy.rateLimit.maxRequests;
+    }
+    check(key) {
+        const now = Date.now();
+        const bucket = this.buckets.get(key);
+        if (!bucket || now >= bucket.resetAt) {
+            this.buckets.set(key, { count: 1, resetAt: now + this.windowMs });
+            return true;
+        }
+        if (bucket.count >= this.maxRequests)
+            return false;
+        bucket.count += 1;
+        return true;
+    }
+}
+export function isContractAllowed(contractId, policy) {
+    if (!policy.allowedContracts || policy.allowedContracts.length === 0)
+        return true;
+    const smartAccountName = process.env.PASSKEY_SMART_ACCOUNT_NAME ?? 'smart-account';
+    if (contractId.endsWith(`.${smartAccountName}`))
+        return true;
+    return policy.allowedContracts.some((allowed) => contractId.startsWith(allowed));
+}

package/dist/rate-limit.test.d.ts

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

package/dist/rate-limit.test.js

@@ -0,0 +1,21 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { isContractAllowed } from './rate-limit.js';
+describe('isContractAllowed', () => {
+    const policy = {
+        allowedContracts: ['ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ'],
+        maxFeeMicroStx: 50000n,
+        rateLimit: { windowMs: 60_000, maxRequests: 100 },
+    };
+    afterEach(() => {
+        delete process.env.PASSKEY_SMART_ACCOUNT_NAME;
+    });
+    it('allows platform deployer contracts', () => {
+        expect(isContractAllowed('ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ.passkey-adapter', policy)).toBe(true);
+    });
+    it('allows self-deployed smart-account contracts on any origin address', () => {
+        expect(isContractAllowed('ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.smart-account', policy)).toBe(true);
+    });
+    it('rejects unrelated contracts', () => {
+        expect(isContractAllowed('ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.other-contract', policy)).toBe(false);
+    });
+});

package/dist/registrar-queue.d.ts

@@ -0,0 +1,14 @@
+/** Serialize all txs from the deployer/sponsor key to avoid BadNonce races. */
+export declare function runWithDeployerLock<T>(task: () => Promise<T>): Promise<T>;
+export declare function isBadNonceResult(result: {
+    error?: string;
+    reason?: string;
+}): boolean;
+export declare function isBadNonceError(error: unknown): boolean;
+export declare function broadcastWithNonceRetry(buildTx: () => Promise<{
+    transaction: unknown;
+}>, broadcast: (tx: unknown) => Promise<{
+    txid?: string;
+    error?: string;
+    reason?: string;
+}>, maxAttempts?: number): Promise<string>;

package/dist/registrar-queue.js

@@ -0,0 +1,30 @@
+let deployerChain = Promise.resolve();
+/** Serialize all txs from the deployer/sponsor key to avoid BadNonce races. */
+export function runWithDeployerLock(task) {
+    const next = deployerChain.then(task, task);
+    deployerChain = next.then(() => undefined, () => undefined);
+    return next;
+}
+export function isBadNonceResult(result) {
+    const detail = `${result.error ?? ''} ${result.reason ?? ''}`;
+    return /BadNonce/i.test(detail);
+}
+export function isBadNonceError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /BadNonce/i.test(message);
+}
+export async function broadcastWithNonceRetry(buildTx, broadcast, maxAttempts = 4) {
+    let lastError = 'BadNonce';
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const { transaction: tx } = await buildTx();
+        const result = await broadcast(tx);
+        if (!result.error && result.txid) {
+            return result.txid.startsWith('0x') ? result.txid.slice(2) : result.txid;
+        }
+        lastError = result.reason ?? result.error ?? lastError;
+        if (!isBadNonceResult(result) || attempt === maxAttempts - 1) {
+            throw new Error(lastError);
+        }
+    }
+    throw new Error(lastError);
+}

package/dist/registrar-queue.test.d.ts

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

package/dist/registrar-queue.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { runWithDeployerLock, isBadNonceResult } from './registrar-queue.js';
+describe('registrar-queue', () => {
+    it('detects BadNonce in broadcast results', () => {
+        expect(isBadNonceResult({ reason: 'BadNonce' })).toBe(true);
+        expect(isBadNonceResult({ error: 'transaction rejected' })).toBe(false);
+    });
+    it('runs deployer tasks serially', async () => {
+        const order = [];
+        await Promise.all([
+            runWithDeployerLock(async () => {
+                order.push(1);
+                await new Promise((r) => setTimeout(r, 20));
+                order.push(2);
+            }),
+            runWithDeployerLock(async () => {
+                order.push(3);
+            }),
+        ]);
+        expect(order).toEqual([1, 2, 3]);
+    });
+});

package/dist/registrar.d.ts

@@ -0,0 +1,4 @@
+import type { RelayConfig } from './types.js';
+/** Platform deployer key — required sender for passkey-factory and passkey-adapter registrar functions. */
+export declare function platformRegistrarPrivateKey(config: RelayConfig): string;
+export declare function platformRegistrarAddress(config: RelayConfig): string;

package/dist/registrar.js

@@ -0,0 +1,9 @@
+import { getAddressFromPrivateKey } from '@stacks/transactions';
+/** Platform deployer key — required sender for passkey-factory and passkey-adapter registrar functions. */
+export function platformRegistrarPrivateKey(config) {
+    return config.registrarPrivateKey ?? config.sponsorPrivateKey;
+}
+export function platformRegistrarAddress(config) {
+    const network = config.network === 'mainnet' ? 'mainnet' : 'testnet';
+    return getAddressFromPrivateKey(platformRegistrarPrivateKey(config), network);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load sponsor private key from a restricted file (preferred) or env var.
+ * Never log or return this value outside the relay process.
+ */
+export declare function loadSponsorPrivateKey(): string;
+export declare function assertRelayAuthConfigured(network: string): void;

package/dist/secrets.js

@@ -0,0 +1,59 @@
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+const PRIVATE_KEY_HEX = /^[0-9a-fA-F]{64}(01)?$/;
+function assertSafeKeyFile(path) {
+    const absolute = resolve(path);
+    const stat = statSync(absolute, { throwIfNoEntry: true });
+    if (!stat.isFile()) {
+        throw new Error(`SPONSOR_PRIVATE_KEY_FILE must point to a regular file: ${absolute}`);
+    }
+    // Require owner-only permissions on Unix (skip on Windows).
+    if (process.platform !== 'win32') {
+        const mode = stat.mode & 0o777;
+        if (mode & 0o077) {
+            throw new Error(`Insecure permissions on ${absolute} (${mode.toString(8)}). ` +
+                'Run: chmod 600 <keyfile>');
+        }
+    }
+}
+function normalizePrivateKey(raw, source) {
+    const key = raw.trim();
+    if (!PRIVATE_KEY_HEX.test(key)) {
+        throw new Error(`Invalid sponsor private key format from ${source}`);
+    }
+    return key.toLowerCase();
+}
+/**
+ * Load sponsor private key from a restricted file (preferred) or env var.
+ * Never log or return this value outside the relay process.
+ */
+export function loadSponsorPrivateKey() {
+    const keyFile = process.env.SPONSOR_PRIVATE_KEY_FILE;
+    if (keyFile) {
+        assertSafeKeyFile(keyFile);
+        return normalizePrivateKey(readFileSync(resolve(keyFile), 'utf8'), 'SPONSOR_PRIVATE_KEY_FILE');
+    }
+    const inline = process.env.SPONSOR_PRIVATE_KEY;
+    if (inline) {
+        if (process.env.NODE_ENV === 'production') {
+            throw new Error('SPONSOR_PRIVATE_KEY inline env var is disabled in production. ' +
+                'Use SPONSOR_PRIVATE_KEY_FILE pointing to a chmod 600 key file.');
+        }
+        console.warn('[relay] Warning: SPONSOR_PRIVATE_KEY is set inline. Prefer SPONSOR_PRIVATE_KEY_FILE to avoid shell history leaks.');
+        return normalizePrivateKey(inline, 'SPONSOR_PRIVATE_KEY');
+    }
+    throw new Error('Sponsor key not configured. Set SPONSOR_PRIVATE_KEY_FILE (recommended) or SPONSOR_PRIVATE_KEY (local dev only).');
+}
+export function assertRelayAuthConfigured(network) {
+    const hasApiKey = Boolean(process.env.RELAY_API_KEY?.trim());
+    const insecureLocal = process.env.RELAY_ALLOW_INSECURE_LOCAL === 'true';
+    if (network === 'mainnet' && !hasApiKey) {
+        throw new Error('RELAY_API_KEY is required when STACKS_NETWORK=mainnet');
+    }
+    if (!hasApiKey && !insecureLocal) {
+        throw new Error('RELAY_API_KEY is required. For local development only, set RELAY_ALLOW_INSECURE_LOCAL=true');
+    }
+    if (!hasApiKey && insecureLocal) {
+        console.warn('[relay] Warning: running without RELAY_API_KEY — local development only');
+    }
+}

package/dist/secrets.test.d.ts

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

package/dist/secrets.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { mkdtempSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+const VALID_KEY = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+describe('loadSponsorPrivateKey', () => {
+    it('loads from a restricted key file', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'relay-key-'));
+        const file = join(dir, 'sponsor.key');
+        writeFileSync(file, VALID_KEY);
+        chmodSync(file, 0o600);
+        process.env.SPONSOR_PRIVATE_KEY_FILE = file;
+        delete process.env.SPONSOR_PRIVATE_KEY;
+        const { loadSponsorPrivateKey } = await import('./secrets.js');
+        expect(loadSponsorPrivateKey()).toBe(VALID_KEY);
+        delete process.env.SPONSOR_PRIVATE_KEY_FILE;
+    });
+    it('rejects world-readable key files on unix', async () => {
+        if (process.platform === 'win32')
+            return;
+        const dir = mkdtempSync(join(tmpdir(), 'relay-key-'));
+        const file = join(dir, 'sponsor.key');
+        writeFileSync(file, VALID_KEY);
+        chmodSync(file, 0o644);
+        process.env.SPONSOR_PRIVATE_KEY_FILE = file;
+        delete process.env.SPONSOR_PRIVATE_KEY;
+        const { loadSponsorPrivateKey } = await import('./secrets.js');
+        expect(() => loadSponsorPrivateKey()).toThrow(/chmod 600/);
+        delete process.env.SPONSOR_PRIVATE_KEY_FILE;
+    });
+});
+describe('assertRelayAuthConfigured', () => {
+    it('requires api key on mainnet', async () => {
+        delete process.env.RELAY_API_KEY;
+        delete process.env.RELAY_ALLOW_INSECURE_LOCAL;
+        const { assertRelayAuthConfigured } = await import('./secrets.js');
+        expect(() => assertRelayAuthConfigured('mainnet')).toThrow(/RELAY_API_KEY/);
+    });
+});

package/dist/sponsor-derivation.d.ts

@@ -0,0 +1,3 @@
+/** Deterministic sponsor private key per wallet owner (compressed hex). */
+export declare function deriveSponsorPrivateKey(masterSecret: string, ownerAddress: string): string;
+export declare function deriveSponsorAddress(masterSecret: string, ownerAddress: string, network: 'mainnet' | 'testnet'): string;

package/dist/sponsor-derivation.js

@@ -0,0 +1,25 @@
+import { createHmac } from 'node:crypto';
+import { getAddressFromPrivateKey } from '@stacks/transactions';
+const DERIVATION_LABEL = 'stacks-passkey-sponsor-v1';
+/** Deterministic sponsor private key per wallet owner (compressed hex). */
+export function deriveSponsorPrivateKey(masterSecret, ownerAddress) {
+    for (let counter = 0; counter < 256; counter++) {
+        const digest = createHmac('sha256', masterSecret)
+            .update(DERIVATION_LABEL)
+            .update(ownerAddress)
+            .update(Buffer.from([counter]))
+            .digest('hex');
+        const candidate = `${digest}01`;
+        try {
+            getAddressFromPrivateKey(candidate, 'testnet');
+            return candidate;
+        }
+        catch {
+            // try next counter
+        }
+    }
+    throw new Error('Unable to derive sponsor private key');
+}
+export function deriveSponsorAddress(masterSecret, ownerAddress, network) {
+    return getAddressFromPrivateKey(deriveSponsorPrivateKey(masterSecret, ownerAddress), network);
+}

package/dist/sponsor-derivation.test.d.ts

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

package/dist/sponsor-derivation.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { deriveSponsorAddress, deriveSponsorPrivateKey } from './sponsor-derivation.js';
+describe('sponsor derivation', () => {
+    const master = 'master-secret-v1';
+    const owner = 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM';
+    it('is deterministic per owner address', () => {
+        const a = deriveSponsorAddress(master, owner, 'testnet');
+        const b = deriveSponsorAddress(master, owner, 'testnet');
+        expect(a).toBe(b);
+    });
+    it('differs across owners', () => {
+        const a = deriveSponsorAddress(master, owner, 'testnet');
+        const b = deriveSponsorAddress(master, 'ST2OTHER', 'testnet');
+        expect(a).not.toBe(b);
+    });
+    it('returns compressed private keys', () => {
+        const key = deriveSponsorPrivateKey(master, owner);
+        expect(key.endsWith('01')).toBe(true);
+        expect(key.length).toBeGreaterThan(64);
+    });
+});

package/dist/sponsor-lock.d.ts

@@ -0,0 +1,2 @@
+/** Serialize txs per sponsor address to avoid BadNonce races across tenants. */
+export declare function runWithSponsorLock<T>(sponsorAddress: string, task: () => Promise<T>): Promise<T>;

package/dist/sponsor-lock.js

@@ -0,0 +1,8 @@
+const sponsorChains = new Map();
+/** Serialize txs per sponsor address to avoid BadNonce races across tenants. */
+export function runWithSponsorLock(sponsorAddress, task) {
+    const prev = sponsorChains.get(sponsorAddress) ?? Promise.resolve();
+    const next = prev.then(task, task);
+    sponsorChains.set(sponsorAddress, next.then(() => undefined, () => undefined));
+    return next;
+}

package/dist/sponsor.d.ts

@@ -0,0 +1,24 @@
+import type { RelayConfig, SponsorResult } from './types.js';
+import type { GasTankStore } from './gas-tank.js';
+export interface SponsorContext {
+    walletId?: string;
+    apiKeyId?: string;
+    sponsorPrivateKey?: string;
+    sponsorAddress?: string;
+    billingMode: 'gasless' | 'account-pay';
+    estimatedFeeMicroStx?: bigint;
+}
+export declare class SponsorService {
+    private readonly config;
+    private readonly network;
+    private readonly gasTank?;
+    constructor(config: RelayConfig, gasTank?: GasTankStore);
+    getRegistrarAddress(): string;
+    /** Platform registrar / legacy sponsor address */
+    getSponsorAddress(): string;
+    sponsorAndBroadcast(txHex: string, context?: SponsorContext): Promise<SponsorResult & {
+        feeChargedMicroStx?: string;
+        gasBalanceMicroStx?: string;
+    }>;
+    private sponsorAndBroadcastInner;
+}

package/dist/sponsor.js

@@ -0,0 +1,129 @@
+import { extractContractCallId } from './contract-id.js';
+import { isContractAllowed } from './rate-limit.js';
+import { broadcastTransaction, deserializeTransaction, getAddressFromPrivateKey, sponsorTransaction, AuthType, isSmartContractPayload, } from '@stacks/transactions';
+import { STACKS_MAINNET, STACKS_TESTNET } from '@stacks/network';
+import { isBadNonceResult } from './registrar-queue.js';
+import { runWithSponsorLock } from './sponsor-lock.js';
+import { fetchStxBalanceMicro } from './on-chain-balance.js';
+function normalizeTxId(txid) {
+    return txid.startsWith('0x') ? txid.slice(2) : txid;
+}
+function getNetwork(name) {
+    switch (name) {
+        case 'mainnet':
+            return STACKS_MAINNET;
+        case 'testnet':
+            return STACKS_TESTNET;
+        default:
+            return { ...STACKS_TESTNET, client: { ...STACKS_TESTNET.client, baseUrl: 'http://localhost:3999' } };
+    }
+}
+export class SponsorService {
+    config;
+    network;
+    gasTank;
+    constructor(config, gasTank) {
+        this.config = config;
+        this.network = getNetwork(config.network);
+        this.gasTank = gasTank;
+    }
+    getRegistrarAddress() {
+        const network = this.config.network === 'mainnet' ? 'mainnet' : 'testnet';
+        const key = this.config.registrarPrivateKey ?? this.config.sponsorPrivateKey;
+        return getAddressFromPrivateKey(key, network);
+    }
+    /** Platform registrar / legacy sponsor address */
+    getSponsorAddress() {
+        return this.getRegistrarAddress();
+    }
+    async sponsorAndBroadcast(txHex, context = { billingMode: 'gasless' }) {
+        const sponsorPrivateKey = context.sponsorPrivateKey ?? this.config.sponsorPrivateKey;
+        const sponsorAddress = context.sponsorAddress ??
+            getAddressFromPrivateKey(sponsorPrivateKey, this.config.network === 'mainnet' ? 'mainnet' : 'testnet');
+        return runWithSponsorLock(sponsorAddress, () => this.sponsorAndBroadcastInner(txHex, { ...context, sponsorPrivateKey, sponsorAddress }));
+    }
+    async sponsorAndBroadcastInner(txHex, context) {
+        const hex = txHex.startsWith('0x') ? txHex.slice(2) : txHex;
+        const deployFeeMultiplier = 4n;
+        const transactionPreview = deserializeTransaction(Buffer.from(hex, 'hex'));
+        const configuredFee = isSmartContractPayload(transactionPreview.payload)
+            ? this.config.policy.maxFeeMicroStx * deployFeeMultiplier
+            : this.config.policy.maxFeeMicroStx;
+        const actualFee = context.billingMode === 'account-pay'
+            ? configuredFee
+            : context.estimatedFeeMicroStx && context.estimatedFeeMicroStx > configuredFee
+                ? context.estimatedFeeMicroStx
+                : configuredFee;
+        let reserved = false;
+        if (this.gasTank && context.walletId && context.billingMode === 'gasless') {
+            const wallet = this.gasTank.getWalletById(context.walletId);
+            if (!wallet) {
+                return { txid: '', status: 'rejected', reason: 'Wallet not found' };
+            }
+            const onChain = await fetchStxBalanceMicro(context.sponsorAddress, this.config.network);
+            const available = this.gasTank.availableBalance(onChain, wallet);
+            if (available < actualFee) {
+                return {
+                    txid: '',
+                    status: 'rejected',
+                    reason: `Insufficient gas tank balance at ${context.sponsorAddress}`,
+                };
+            }
+            this.gasTank.reserveGas(context.walletId, actualFee);
+            reserved = true;
+        }
+        let lastError = 'Transaction broadcast failed: BadNonce';
+        try {
+            for (let attempt = 0; attempt < 3; attempt++) {
+                const transaction = deserializeTransaction(Buffer.from(hex, 'hex'));
+                if (transaction.auth.authType !== AuthType.Sponsored) {
+                    return { txid: '', status: 'rejected', reason: 'Transaction is not marked as sponsored' };
+                }
+                const contractId = extractContractCallId(transaction.payload);
+                if (contractId && !isContractAllowed(contractId, this.config.policy)) {
+                    return { txid: '', status: 'rejected', reason: `Contract not allowlisted: ${contractId}` };
+                }
+                const sponsoredTx = await sponsorTransaction({
+                    transaction,
+                    sponsorPrivateKey: context.sponsorPrivateKey,
+                    fee: actualFee,
+                    network: this.network,
+                });
+                const response = (await broadcastTransaction({
+                    transaction: sponsoredTx,
+                    network: this.network,
+                }));
+                if (!response.error && response.txid) {
+                    const txid = normalizeTxId(response.txid);
+                    let gasBalanceMicroStx;
+                    if (this.gasTank && context.walletId) {
+                        const wallet = this.gasTank.recordSponsor(context.walletId, BigInt(actualFee), txid, context.billingMode, context.apiKeyId, reserved ? actualFee : undefined);
+                        reserved = false;
+                        const onChain = await fetchStxBalanceMicro(context.sponsorAddress, this.config.network);
+                        gasBalanceMicroStx = this.gasTank.availableBalance(onChain, wallet).toString();
+                    }
+                    return {
+                        txid,
+                        status: 'accepted',
+                        feeChargedMicroStx: actualFee.toString(),
+                        gasBalanceMicroStx,
+                    };
+                }
+                lastError = response.reason ?? response.error ?? lastError;
+                if (!isBadNonceResult(response) || attempt === 2) {
+                    throw new Error(`Transaction broadcast failed: ${lastError}`);
+                }
+            }
+        }
+        catch (error) {
+            if (reserved && this.gasTank && context.walletId) {
+                this.gasTank.releaseReservation(context.walletId, actualFee);
+            }
+            throw error;
+        }
+        if (reserved && this.gasTank && context.walletId) {
+            this.gasTank.releaseReservation(context.walletId, actualFee);
+        }
+        throw new Error(`Transaction broadcast failed: ${lastError}`);
+    }
+}

package/dist/tx-wait.d.ts

@@ -0,0 +1,4 @@
+import type { STACKS_MAINNET, STACKS_TESTNET } from '@stacks/network';
+type Network = typeof STACKS_MAINNET | typeof STACKS_TESTNET;
+export declare function waitForTx(network: Network, txid: string, maxAttempts?: number, intervalMs?: number): Promise<void>;
+export {};

package/dist/tx-wait.js

@@ -0,0 +1,18 @@
+export async function waitForTx(network, txid, maxAttempts = 60, intervalMs = 2000) {
+    const normalized = txid.startsWith('0x') ? txid.slice(2) : txid;
+    for (let i = 0; i < maxAttempts; i++) {
+        if (i > 0)
+            await new Promise((r) => setTimeout(r, intervalMs));
+        const res = await fetch(`${network.client.baseUrl}/extended/v1/tx/${normalized}`);
+        if (!res.ok)
+            continue;
+        const data = (await res.json());
+        if (data.tx_status === 'success')
+            return;
+        if (data.tx_status === 'abort_by_response' || data.tx_status === 'failed') {
+            const detail = data.tx_result?.repr ?? data.tx_status;
+            throw new Error(`Transaction failed on chain: ${detail}`);
+        }
+    }
+    throw new Error(`Transaction ${normalized} was not confirmed on chain`);
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export interface RateLimitConfig {
+    windowMs: number;
+    maxRequests: number;
+}
+export interface RelayPolicy {
+    allowedContracts?: string[];
+    maxFeeMicroStx: bigint;
+    rateLimit: RateLimitConfig;
+}
+export interface RelayConfig {
+    sponsorPrivateKey: string;
+    registrarPrivateKey?: string;
+    masterSecret: string;
+    sessionSecret: string;
+    network: 'mainnet' | 'testnet' | 'devnet';
+    port: number;
+    host: string;
+    apiKey?: string;
+    adminApiKey?: string;
+    gasTankPath?: string;
+    policy: RelayPolicy;
+}
+export interface SponsorRequest {
+    txHex: string;
+}
+export interface SponsorResult {
+    txid: string;
+    status: 'accepted' | 'rejected';
+    reason?: string;
+}

package/dist/types.js

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