@stacks-passkey/relay 0.1.0

package/dist/app.js

@@ -0,0 +1,412 @@
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { RateLimiter } from './rate-limit.js';
+import { SponsorService } from './sponsor.js';
+import { CatalogStore, defaultCatalogPath } from './catalog.js';
+import { CatalogService } from './catalog-service.js';
+import { AccountStore, defaultAccountsPath } from './accounts.js';
+import { AccountService } from './account-service.js';
+import { verifySessionToken } from './crypto.js';
+import { createWalletSession, issueAuthChallengeForNetwork, verifyAuthSignatureWithReason, } from './wallet-auth.js';
+import { fetchStxBalanceMicro } from './on-chain-balance.js';
+function resolveSessionAddress(c, config) {
+    const auth = c.req.header('Authorization');
+    const token = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+    if (!token || token.startsWith('spk_'))
+        return null;
+    return verifySessionToken(token, config.sessionSecret)?.address ?? null;
+}
+function isAdminKey(c, config) {
+    if (!config.adminApiKey)
+        return true;
+    return c.req.header('X-Admin-Key') === config.adminApiKey;
+}
+export function createRelayApp(config, gasTank) {
+    const app = new Hono();
+    const sponsor = new SponsorService(config, gasTank);
+    const limiter = new RateLimiter(config.policy);
+    const catalog = new CatalogStore(process.env.CATALOG_PATH ?? defaultCatalogPath());
+    const catalogService = new CatalogService(config, catalog, gasTank);
+    const accountStore = new AccountStore(process.env.ACCOUNTS_PATH ?? defaultAccountsPath());
+    const accountService = new AccountService(config, accountStore, gasTank);
+    app.use('*', cors({
+        origin: ['http://localhost:3000', 'http://127.0.0.1:3000', 'http://localhost:3001', 'http://127.0.0.1:3001'],
+        allowMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+        allowHeaders: ['Content-Type', 'Authorization', 'X-Admin-Key'],
+    }));
+    app.get('/health', (c) => {
+        const registrarAddress = sponsor.getRegistrarAddress();
+        return c.json({
+            ok: true,
+            registrarAddress,
+            sponsorAddress: registrarAddress,
+            sponsorFeeMicroStx: config.policy.maxFeeMicroStx.toString(),
+            network: config.network,
+            auth: 'wallet-signature',
+        });
+    });
+    app.get('/v1/accounts/template', (c) => c.json(accountService.getAccountContractTemplate()));
+    // --- Wallet signature auth ---
+    app.get('/v1/auth/challenge', (c) => {
+        const address = c.req.query('address');
+        if (!address)
+            return c.json({ error: 'Missing address query param' }, 400);
+        const challenge = issueAuthChallengeForNetwork(address, config.network);
+        return c.json({
+            address,
+            nonce: challenge.nonce,
+            expiresAt: challenge.expiresAt,
+            plainMessage: challenge.plainMessage,
+            domain: {
+                name: process.env.RELAY_AUTH_DOMAIN ?? 'localhost',
+                version: '1.0.0',
+                'chain-id': config.network === 'mainnet' ? 1 : 0x80000000,
+            },
+            message: {
+                action: 'authenticate',
+                address,
+                nonce: challenge.nonce,
+                expires: challenge.expiresAt,
+            },
+        });
+    });
+    app.post('/v1/auth/verify', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const body = await c.req.json();
+        if (!body.address || !body.signature || !body.publicKey || !body.nonce || !body.expiresAt) {
+            return c.json({ error: 'Missing auth fields' }, 400);
+        }
+        const verified = verifyAuthSignatureWithReason({
+            address: body.address,
+            signature: body.signature,
+            publicKey: body.publicKey,
+            nonce: body.nonce,
+            expiresAt: body.expiresAt,
+            network: config.network,
+            mode: body.mode,
+            plainMessage: body.plainMessage,
+        });
+        if (!verified.ok) {
+            const messages = {
+                missing_challenge: 'Sign-in expired or was replaced. Click Sign in again.',
+                nonce_mismatch: 'Sign-in challenge changed while signing. Click Sign in again.',
+                expires_mismatch: 'Sign-in challenge changed while signing. Click Sign in again.',
+                expired: 'Sign-in challenge expired. Click Sign in again.',
+                bad_signature: 'Signature did not match the connected wallet. Try Sign in again.',
+            };
+            return c.json({ error: messages[verified.reason] ?? 'Invalid or expired signature' }, 401);
+        }
+        gasTank.ensureWallet(body.address);
+        const session = createWalletSession(body.address, config.sessionSecret);
+        return c.json({
+            sessionToken: session.sessionToken,
+            expiresAt: session.expiresAt,
+            address: body.address,
+        });
+    });
+    // --- Wallet dashboard (session auth) ---
+    app.get('/v1/wallet/me', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallet = gasTank.ensureWallet(address);
+        const onChain = await fetchStxBalanceMicro(wallet.sponsorAddress, config.network);
+        const available = gasTank.availableBalance(onChain, wallet);
+        return c.json({
+            walletId: wallet.id,
+            ownerAddress: wallet.ownerAddress,
+            sponsorAddress: wallet.sponsorAddress,
+            gasBalanceMicroStx: onChain.toString(),
+            availableMicroStx: available.toString(),
+            reservedMicroStx: wallet.reservedMicroStx.toString(),
+            totalSpentMicroStx: wallet.totalSpentMicroStx.toString(),
+            txCount: wallet.txCount,
+            createdAt: wallet.createdAt,
+        });
+    });
+    app.get('/v1/wallet/keys', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallet = gasTank.getWalletByOwner(address);
+        if (!wallet)
+            return c.json({ keys: [] });
+        return c.json({
+            keys: gasTank.listApiKeys(wallet.id).map((k) => ({
+                id: k.id,
+                name: k.name,
+                keyPrefix: k.keyPrefix,
+                createdAt: k.createdAt,
+                retrievable: gasTank.canRevealApiKey(wallet.id, k.id),
+            })),
+        });
+    });
+    app.get('/v1/wallet/keys/:id/reveal', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallet = gasTank.getWalletByOwner(address);
+        if (!wallet)
+            return c.json({ error: 'Wallet not registered' }, 404);
+        try {
+            const apiKey = gasTank.revealApiKey(wallet.id, c.req.param('id'));
+            return c.json({ apiKey });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Reveal failed';
+            return c.json({ error: message }, 404);
+        }
+    });
+    app.post('/v1/wallet/keys', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const body = await c.req.json();
+        if (!body.name?.trim())
+            return c.json({ error: 'Missing name' }, 400);
+        const wallet = gasTank.ensureWallet(address);
+        const { apiKey, record } = gasTank.createApiKey(wallet.id, body.name.trim());
+        return c.json({
+            id: record.id,
+            name: record.name,
+            apiKey,
+            keyPrefix: record.keyPrefix,
+            createdAt: record.createdAt,
+            warning: 'Store this API key securely — it is shown only once.',
+        });
+    });
+    app.delete('/v1/wallet/keys/:id', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallet = gasTank.getWalletByOwner(address);
+        if (!wallet)
+            return c.json({ error: 'Wallet not registered' }, 404);
+        try {
+            const revoked = gasTank.revokeApiKey(wallet.id, c.req.param('id'));
+            return c.json({ id: revoked.id, revokedAt: revoked.revokedAt });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Revoke failed';
+            return c.json({ error: message }, 400);
+        }
+    });
+    app.get('/v1/wallet/logs', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const address = resolveSessionAddress(c, config);
+        if (!address)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallet = gasTank.getWalletByOwner(address);
+        if (!wallet)
+            return c.json({ logs: [] });
+        return c.json({
+            logs: gasTank.getLogs(wallet.id).map((l) => ({
+                ...l,
+                feeMicroStx: l.feeMicroStx.toString(),
+            })),
+        });
+    });
+    // --- SDK project info (API key auth) ---
+    app.get('/v1/project', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const auth = c.req.header('Authorization');
+        const apiKey = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+        if (!apiKey)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const resolved = gasTank.resolveApiKey(apiKey);
+        if (!resolved)
+            return c.json({ error: 'Invalid or revoked API key' }, 401);
+        try {
+            const onChain = await fetchStxBalanceMicro(resolved.wallet.sponsorAddress, config.network);
+            const available = gasTank.availableBalance(onChain, resolved.wallet);
+            return c.json({
+                walletId: resolved.wallet.id,
+                projectId: resolved.wallet.id,
+                projectName: resolved.apiKey.name,
+                gasTankAddress: resolved.wallet.sponsorAddress,
+                gasBalanceMicroStx: onChain.toString(),
+                availableMicroStx: available.toString(),
+                totalSpentMicroStx: resolved.wallet.totalSpentMicroStx.toString(),
+                txCount: resolved.wallet.txCount,
+                sponsorFeeMicroStx: config.policy.maxFeeMicroStx.toString(),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Balance lookup failed';
+            return c.json({ error: message }, 503);
+        }
+    });
+    // --- Legacy admin (X-Admin-Key) — list only ---
+    app.get('/v1/admin/projects', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        if (!isAdminKey(c, config))
+            return c.json({ error: 'Unauthorized' }, 401);
+        const wallets = await Promise.all(gasTank.listWallets().map(async (w) => {
+            const onChain = await fetchStxBalanceMicro(w.sponsorAddress, config.network);
+            return {
+                id: w.id,
+                name: w.ownerAddress,
+                ownerAddress: w.ownerAddress,
+                gasTankAddress: w.sponsorAddress,
+                gasBalanceMicroStx: onChain.toString(),
+                availableMicroStx: gasTank.availableBalance(onChain, w).toString(),
+                totalSpentMicroStx: w.totalSpentMicroStx.toString(),
+                txCount: w.txCount,
+                createdAt: w.createdAt,
+            };
+        }));
+        return c.json({ projects: wallets });
+    });
+    app.get('/v1/admin/projects/:id/logs', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        if (!isAdminKey(c, config))
+            return c.json({ error: 'Unauthorized' }, 401);
+        return c.json({
+            logs: gasTank.getLogs(c.req.param('id')).map((l) => ({
+                ...l,
+                projectId: l.walletId,
+                feeMicroStx: l.feeMicroStx.toString(),
+            })),
+        });
+    });
+    app.get('/v1/catalog', (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const auth = c.req.header('Authorization');
+        const apiKey = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+        if (!apiKey)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const resolved = gasTank.resolveApiKey(apiKey);
+        if (!resolved)
+            return c.json({ error: 'Invalid API key' }, 401);
+        return c.json({ contracts: catalog.listForProject(resolved.wallet.id) });
+    });
+    app.post('/v1/catalog/ensure', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const auth = c.req.header('Authorization');
+        const apiKey = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+        if (!apiKey)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const resolved = gasTank.resolveApiKey(apiKey);
+        if (!resolved)
+            return c.json({ error: 'Invalid API key' }, 401);
+        const body = await c.req.json();
+        if (!body.contractId)
+            return c.json({ error: 'Missing contractId' }, 400);
+        try {
+            const result = await catalogService.ensureContract(resolved.wallet.id, body.contractId);
+            return c.json(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Catalog ensure failed';
+            return c.json({ error: message }, 400);
+        }
+    });
+    app.post('/v1/accounts/ensure', async (c) => {
+        if (!gasTank)
+            return c.json({ error: 'Gas tank not enabled' }, 503);
+        const auth = c.req.header('Authorization');
+        const apiKey = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+        if (!apiKey)
+            return c.json({ error: 'Unauthorized' }, 401);
+        const resolved = gasTank.resolveApiKey(apiKey);
+        if (!resolved)
+            return c.json({ error: 'Invalid API key' }, 401);
+        const body = await c.req.json();
+        if (!body.publicKeyHex)
+            return c.json({ error: 'Missing publicKeyHex' }, 400);
+        if (!body.originAddress)
+            return c.json({ error: 'Missing originAddress' }, 400);
+        try {
+            const result = await accountService.ensureAccount(resolved.wallet.id, body.publicKeyHex, {
+                originAddress: body.originAddress,
+                contractName: body.contractName,
+            });
+            return c.json(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Account ensure failed';
+            return c.json({ error: message }, 400);
+        }
+    });
+    app.post('/sponsor', async (c) => {
+        const auth = c.req.header('Authorization');
+        const apiKey = auth?.startsWith('Bearer ') ? auth.slice(7) : null;
+        let walletId;
+        let apiKeyId;
+        let sponsorPrivateKey;
+        let sponsorAddress;
+        if (gasTank && apiKey) {
+            const resolved = gasTank.resolveApiKey(apiKey);
+            if (!resolved) {
+                return c.json({ status: 'rejected', reason: 'Invalid or revoked API key' }, 401);
+            }
+            walletId = resolved.wallet.id;
+            apiKeyId = resolved.apiKey.id;
+            sponsorPrivateKey = resolved.sponsorPrivateKey;
+            sponsorAddress = resolved.wallet.sponsorAddress;
+        }
+        else if (config.apiKey) {
+            if (auth !== `Bearer ${config.apiKey}`) {
+                return c.json({ status: 'rejected', reason: 'Unauthorized' }, 401);
+            }
+        }
+        const clientIp = c.req.header('x-forwarded-for') ?? 'local';
+        if (!limiter.check(clientIp)) {
+            return c.json({ status: 'rejected', reason: 'Rate limit exceeded' }, 429);
+        }
+        const body = await c.req.json();
+        if (!body.txHex) {
+            return c.json({ status: 'rejected', reason: 'Missing txHex' }, 400);
+        }
+        const billingMode = body.billingMode ?? 'gasless';
+        if (gasTank && walletId && billingMode === 'gasless' && sponsorAddress) {
+            const wallet = gasTank.getWalletById(walletId);
+            const minFee = config.policy.maxFeeMicroStx;
+            if (wallet) {
+                const onChain = await fetchStxBalanceMicro(sponsorAddress, config.network);
+                if (gasTank.availableBalance(onChain, wallet) < minFee) {
+                    return c.json({
+                        status: 'rejected',
+                        reason: `Insufficient gas tank balance. Deposit STX to ${sponsorAddress}`,
+                    }, 402);
+                }
+            }
+        }
+        try {
+            const result = await sponsor.sponsorAndBroadcast(body.txHex, {
+                walletId,
+                apiKeyId,
+                sponsorPrivateKey,
+                sponsorAddress,
+                billingMode,
+                estimatedFeeMicroStx: body.estimatedFeeMicroStx ? BigInt(body.estimatedFeeMicroStx) : undefined,
+            });
+            if (result.status === 'rejected') {
+                return c.json(result, 400);
+            }
+            return c.json(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown relay error';
+            return c.json({ status: 'rejected', reason: message }, 500);
+        }
+    });
+    return app;
+}

package/dist/catalog-service.d.ts

@@ -0,0 +1,20 @@
+import type { RelayConfig } from './types.js';
+import type { CatalogStore } from './catalog.js';
+import type { GasTankStore } from './gas-tank.js';
+export interface EnsureResult {
+    contractId: string;
+    registered: boolean;
+    alreadyRegistered: boolean;
+    registrationTxid?: string;
+    functions: string[];
+}
+export declare class CatalogService {
+    private readonly config;
+    private readonly catalog;
+    private readonly gasTank?;
+    constructor(config: RelayConfig, catalog: CatalogStore, gasTank?: GasTankStore | undefined);
+    ensureContract(projectId: string, contractId: string): Promise<EnsureResult>;
+    private fetchPublicFunctions;
+    private isRegisteredOnChain;
+    private submitRegistration;
+}

package/dist/catalog-service.js

@@ -0,0 +1,165 @@
+import { Cl, broadcastTransaction, fetchCallReadOnlyFunction, makeContractCall, cvToValue, } from '@stacks/transactions';
+import { STACKS_MAINNET, STACKS_TESTNET } from '@stacks/network';
+import { broadcastWithNonceRetry, runWithDeployerLock } from './registrar-queue.js';
+import { runWithSponsorLock } from './sponsor-lock.js';
+import { fetchStxBalanceMicro } from './on-chain-balance.js';
+import { platformRegistrarAddress, platformRegistrarPrivateKey } from './registrar.js';
+const REGISTRATION_FEE_MULTIPLIER = 3n;
+function getNetwork(name) {
+    return name === 'mainnet' ? STACKS_MAINNET : STACKS_TESTNET;
+}
+function parseContractId(contractId) {
+    const dot = contractId.indexOf('.');
+    if (dot === -1)
+        throw new Error('contractId must be address.name');
+    return { address: contractId.slice(0, dot), name: contractId.slice(dot + 1) };
+}
+export class CatalogService {
+    config;
+    catalog;
+    gasTank;
+    constructor(config, catalog, gasTank) {
+        this.config = config;
+        this.catalog = catalog;
+        this.gasTank = gasTank;
+    }
+    async ensureContract(projectId, contractId) {
+        const limits = {
+            maxContracts: Number(process.env.CATALOG_MAX_CONTRACTS_PER_PROJECT ?? '50'),
+            maxRegistrationsPerDay: Number(process.env.CATALOG_MAX_REGISTRATIONS_PER_DAY ?? '5'),
+        };
+        const cached = this.catalog.find(projectId, contractId);
+        if (cached?.registrationTxid) {
+            return {
+                contractId,
+                registered: true,
+                alreadyRegistered: true,
+                registrationTxid: cached.registrationTxid,
+                functions: cached.functions,
+            };
+        }
+        if (this.gasTank) {
+            if (this.catalog.countContracts(projectId) >= limits.maxContracts && !cached) {
+                throw new Error(`Project exceeded max registered contracts (${limits.maxContracts})`);
+            }
+            if (this.catalog.countRegistrationsToday(projectId) >= limits.maxRegistrationsPerDay) {
+                throw new Error(`Project exceeded daily registration limit (${limits.maxRegistrationsPerDay})`);
+            }
+        }
+        const functions = await this.fetchPublicFunctions(contractId);
+        if (!functions.includes('passkey-exec')) {
+            throw new Error('Contract must implement public passkey-exec (passkey-exec-trait)');
+        }
+        const adapterAddress = process.env.PASSKEY_ADAPTER_ADDRESS;
+        const adapterName = process.env.PASSKEY_ADAPTER_NAME ?? 'passkey-adapter';
+        if (!adapterAddress) {
+            throw new Error('PASSKEY_ADAPTER_ADDRESS is not configured on relay');
+        }
+        const network = getNetwork(this.config.network);
+        const alreadyOnChain = await this.isRegisteredOnChain(adapterAddress, adapterName, contractId);
+        let registrationTxid = cached?.registrationTxid;
+        if (!alreadyOnChain) {
+            registrationTxid = await runWithDeployerLock(() => this.submitRegistration(projectId, adapterAddress, adapterName, contractId));
+            this.catalog.incrementRegistrationsToday(projectId);
+        }
+        this.catalog.save({
+            contractId,
+            projectId,
+            functions,
+            registeredAt: new Date().toISOString(),
+            registrationTxid,
+        });
+        return {
+            contractId,
+            registered: true,
+            alreadyRegistered: alreadyOnChain,
+            registrationTxid,
+            functions,
+        };
+    }
+    async fetchPublicFunctions(contractId) {
+        const network = getNetwork(this.config.network);
+        const { address, name } = parseContractId(contractId);
+        const url = `${network.client.baseUrl}/v2/contracts/interface/${address}/${name}`;
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new Error(`Unable to fetch contract interface for ${contractId}: ${res.status}`);
+        }
+        const body = (await res.json());
+        return (body.functions ?? [])
+            .filter((f) => f.access === 'public')
+            .map((f) => f.name);
+    }
+    async isRegisteredOnChain(adapterAddress, adapterName, contractId) {
+        const network = getNetwork(this.config.network);
+        const { address, name } = parseContractId(contractId);
+        try {
+            const result = await fetchCallReadOnlyFunction({
+                contractAddress: adapterAddress,
+                contractName: adapterName,
+                functionName: 'is-registered',
+                functionArgs: [Cl.contractPrincipal(address, name)],
+                network,
+                senderAddress: adapterAddress,
+            });
+            const parsed = cvToValue(result);
+            return parsed === true || (typeof parsed === 'object' && parsed?.value === true);
+        }
+        catch {
+            return false;
+        }
+    }
+    async submitRegistration(projectId, adapterAddress, adapterName, contractId) {
+        const network = getNetwork(this.config.network);
+        const { address, name } = parseContractId(contractId);
+        const fee = this.config.policy.maxFeeMicroStx * REGISTRATION_FEE_MULTIPLIER;
+        let creds = null;
+        if (this.gasTank) {
+            const sponsor = this.gasTank.getSponsorCredentials(projectId);
+            if (!sponsor)
+                throw new Error('Wallet not found');
+            const onChain = await fetchStxBalanceMicro(sponsor.sponsorAddress, this.config.network);
+            const available = this.gasTank.availableBalance(onChain, sponsor.wallet);
+            if (available < fee) {
+                throw new Error(`Insufficient gas tank balance for contract registration. Deposit STX to ${sponsor.sponsorAddress}`);
+            }
+            this.gasTank.reserveGas(projectId, fee);
+            creds = sponsor;
+        }
+        const senderKey = platformRegistrarPrivateKey(this.config);
+        const lockAddress = platformRegistrarAddress(this.config);
+        const submit = async () => {
+            let reserved = fee;
+            try {
+                const txid = await broadcastWithNonceRetry(async () => ({
+                    transaction: await makeContractCall({
+                        contractAddress: adapterAddress,
+                        contractName: adapterName,
+                        functionName: 'register-contract',
+                        functionArgs: [Cl.contractPrincipal(address, name)],
+                        senderKey,
+                        network,
+                        fee,
+                    }),
+                }), async (tx) => broadcastTransaction({
+                    transaction: tx,
+                    network,
+                }));
+                if (this.gasTank) {
+                    this.gasTank.recordSponsor(projectId, fee, txid, 'gasless', undefined, reserved);
+                    reserved = 0n;
+                }
+                return txid;
+            }
+            finally {
+                if (reserved > 0n && this.gasTank) {
+                    this.gasTank.releaseReservation(projectId, reserved);
+                }
+            }
+        };
+        if (this.gasTank) {
+            return runWithSponsorLock(lockAddress, submit);
+        }
+        return submit();
+    }
+}

package/dist/catalog.d.ts

@@ -0,0 +1,21 @@
+export interface CatalogEntry {
+    contractId: string;
+    projectId: string;
+    functions: string[];
+    registeredAt: string;
+    registrationTxid?: string;
+}
+export declare class CatalogStore {
+    private readonly filePath;
+    private data;
+    constructor(filePath: string);
+    private load;
+    private persist;
+    find(projectId: string, contractId: string): CatalogEntry | null;
+    listForProject(projectId: string): CatalogEntry[];
+    save(entry: CatalogEntry): CatalogEntry;
+    countRegistrationsToday(projectId: string): number;
+    incrementRegistrationsToday(projectId: string): number;
+    countContracts(projectId: string): number;
+}
+export declare function defaultCatalogPath(): string;

package/dist/catalog.js

@@ -0,0 +1,60 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export class CatalogStore {
+    filePath;
+    data;
+    constructor(filePath) {
+        this.filePath = filePath;
+        mkdirSync(dirname(filePath), { recursive: true });
+        this.data = this.load();
+    }
+    load() {
+        if (!existsSync(this.filePath)) {
+            return { entries: [], registrationCounts: {} };
+        }
+        return JSON.parse(readFileSync(this.filePath, 'utf8'));
+    }
+    persist() {
+        writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
+    }
+    find(projectId, contractId) {
+        return (this.data.entries.find((e) => e.projectId === projectId && e.contractId === contractId) ?? null);
+    }
+    listForProject(projectId) {
+        return this.data.entries.filter((e) => e.projectId === projectId);
+    }
+    save(entry) {
+        const idx = this.data.entries.findIndex((e) => e.projectId === entry.projectId && e.contractId === entry.contractId);
+        if (idx >= 0)
+            this.data.entries[idx] = entry;
+        else
+            this.data.entries.push(entry);
+        this.persist();
+        return entry;
+    }
+    countRegistrationsToday(projectId) {
+        const day = new Date().toISOString().slice(0, 10);
+        const row = this.data.registrationCounts[projectId];
+        if (!row || row.day !== day)
+            return 0;
+        return row.count;
+    }
+    incrementRegistrationsToday(projectId) {
+        const day = new Date().toISOString().slice(0, 10);
+        const row = this.data.registrationCounts[projectId];
+        if (!row || row.day !== day) {
+            this.data.registrationCounts[projectId] = { day, count: 1 };
+        }
+        else {
+            row.count += 1;
+        }
+        this.persist();
+        return this.data.registrationCounts[projectId].count;
+    }
+    countContracts(projectId) {
+        return this.data.entries.filter((e) => e.projectId === projectId).length;
+    }
+}
+export function defaultCatalogPath() {
+    return join(process.cwd(), 'data', 'catalog.json');
+}

package/dist/catalog.test.d.ts

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