@stacks-passkey/relay 0.1.0

package/dist/account-service.d.ts

@@ -0,0 +1,39 @@
+import type { RelayConfig } from './types.js';
+import type { AccountStore } from './accounts.js';
+import type { GasTankStore } from './gas-tank.js';
+export interface EnsureAccountResult {
+    contractAddress: string;
+    contractName: string;
+    contractId: string;
+    alreadyRegistered: boolean;
+    originAddress: string;
+    registerTxid?: string;
+    factoryTxid?: string;
+}
+export declare const DEFAULT_SELF_DEPLOY_ACCOUNT_NAME: string;
+export interface EnsureAccountOptions {
+    originAddress?: string;
+    contractName?: string;
+}
+export declare class AccountService {
+    private readonly config;
+    private readonly store;
+    private readonly gasTank?;
+    constructor(config: RelayConfig, store: AccountStore, gasTank?: GasTankStore | undefined);
+    ensureAccount(projectId: string, publicKeyHex: string, options?: EnsureAccountOptions): Promise<EnsureAccountResult>;
+    getAccountContractTemplate(): {
+        contractName: string;
+        source: string;
+        clarityVersion: number;
+    };
+    /** Inject fully-qualified passkey-adapter references for user-origin deploys. */
+    buildAccountContractSource(): string;
+    private ensureAccountInner;
+    private lookupFactoryAccount;
+    private isContractDeployed;
+    private isKeyRegistered;
+    private readAccountContractSource;
+    private submitFactoryRegister;
+    private assertGas;
+    private broadcast;
+}

package/dist/account-service.js

@@ -0,0 +1,223 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Cl, broadcastTransaction, fetchCallReadOnlyFunction, makeContractCall, cvToValue, } from '@stacks/transactions';
+import { STACKS_MAINNET, STACKS_TESTNET } from '@stacks/network';
+import { waitForTx } from './tx-wait.js';
+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';
+function getNetwork(name) {
+    return name === 'mainnet' ? STACKS_MAINNET : STACKS_TESTNET;
+}
+function defaultAccountContractPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '../../../contracts/contracts/passkey-account.clar');
+}
+export const DEFAULT_SELF_DEPLOY_ACCOUNT_NAME = process.env.PASSKEY_SMART_ACCOUNT_NAME ?? 'smart-account';
+export class AccountService {
+    config;
+    store;
+    gasTank;
+    constructor(config, store, gasTank) {
+        this.config = config;
+        this.store = store;
+        this.gasTank = gasTank;
+    }
+    async ensureAccount(projectId, publicKeyHex, options = {}) {
+        return runWithDeployerLock(() => this.ensureAccountInner(projectId, publicKeyHex, options));
+    }
+    getAccountContractTemplate() {
+        return {
+            contractName: DEFAULT_SELF_DEPLOY_ACCOUNT_NAME,
+            source: this.buildAccountContractSource(),
+            clarityVersion: 5,
+        };
+    }
+    /** Inject fully-qualified passkey-adapter references for user-origin deploys. */
+    buildAccountContractSource() {
+        const adapterAddress = process.env.PASSKEY_ADAPTER_ADDRESS ?? process.env.PASSKEY_DEPLOYER_ADDRESS ?? '';
+        const adapterName = process.env.PASSKEY_ADAPTER_NAME ?? 'passkey-adapter';
+        if (!adapterAddress) {
+            throw new Error('PASSKEY_ADAPTER_ADDRESS or PASSKEY_DEPLOYER_ADDRESS must be configured');
+        }
+        const adapterContract = `'${adapterAddress}.${adapterName}`;
+        return this.readAccountContractSource()
+            .replaceAll('(use-trait exec-trait .passkey-adapter.passkey-exec-trait)', `(use-trait exec-trait ${adapterContract}.passkey-exec-trait)`)
+            .replaceAll('(contract-call? .passkey-adapter forward-invoke', `(contract-call? ${adapterContract} forward-invoke`);
+    }
+    async ensureAccountInner(projectId, publicKeyHex, options) {
+        const normalized = publicKeyHex.toLowerCase().replace(/^0x/, '');
+        if (normalized.length !== 66) {
+            throw new Error('publicKeyHex must be 33-byte compressed key (66 hex chars)');
+        }
+        const originAddress = options.originAddress;
+        if (!originAddress) {
+            throw new Error('originAddress is required');
+        }
+        const contractName = options.contractName ?? DEFAULT_SELF_DEPLOY_ACCOUNT_NAME;
+        const contractAddress = originAddress;
+        const contractId = `${contractAddress}.${contractName}`;
+        const cached = this.store.find(projectId, normalized);
+        if (cached?.registerTxid && cached.contractName === contractName && cached.contractAddress === contractAddress) {
+            return {
+                contractAddress,
+                contractName,
+                contractId,
+                originAddress,
+                alreadyRegistered: true,
+                registerTxid: cached.registerTxid,
+                factoryTxid: cached.factoryTxid,
+            };
+        }
+        const deployerAddress = process.env.PASSKEY_DEPLOYER_ADDRESS ?? process.env.PASSKEY_ADAPTER_ADDRESS;
+        const factoryAddress = process.env.PASSKEY_FACTORY_ADDRESS ?? deployerAddress;
+        const factoryName = process.env.PASSKEY_FACTORY_NAME ?? 'passkey-factory';
+        if (!deployerAddress || !factoryAddress) {
+            throw new Error('PASSKEY_DEPLOYER_ADDRESS or PASSKEY_FACTORY_ADDRESS must be configured');
+        }
+        const maxAccounts = Number(process.env.ACCOUNTS_MAX_PER_PROJECT ?? '500');
+        if (this.gasTank && this.store.count(projectId) >= maxAccounts && !cached) {
+            throw new Error(`Project exceeded max passkey accounts (${maxAccounts})`);
+        }
+        const network = getNetwork(this.config.network);
+        const pubkeyBuffer = Buffer.from(normalized, 'hex');
+        const deployed = await this.isContractDeployed(contractAddress, contractName, network);
+        if (!deployed) {
+            throw new Error(`Smart account ${contractId} is not deployed on chain yet`);
+        }
+        const registered = await this.isKeyRegistered(contractAddress, contractName, pubkeyBuffer, network, contractAddress);
+        if (!registered) {
+            throw new Error(`Passkey is not registered on ${contractId}`);
+        }
+        const onChain = await this.lookupFactoryAccount(factoryAddress, factoryName, pubkeyBuffer, deployerAddress);
+        let factoryTxid = cached?.factoryTxid;
+        if (!onChain) {
+            factoryTxid = await this.submitFactoryRegister(factoryAddress, factoryName, pubkeyBuffer, contractAddress, contractName, projectId);
+            await waitForTx(network, factoryTxid);
+        }
+        this.store.save({
+            publicKeyHex: normalized,
+            contractAddress,
+            contractName,
+            contractId,
+            projectId,
+            registerTxid: cached?.registerTxid ?? 'client-registered',
+            factoryTxid,
+            createdAt: new Date().toISOString(),
+        });
+        return {
+            contractAddress,
+            contractName,
+            contractId,
+            originAddress,
+            alreadyRegistered: Boolean(onChain && registered),
+            factoryTxid,
+        };
+    }
+    async lookupFactoryAccount(factoryAddress, factoryName, pubkey, sender) {
+        const network = getNetwork(this.config.network);
+        try {
+            const result = await fetchCallReadOnlyFunction({
+                contractAddress: factoryAddress,
+                contractName: factoryName,
+                functionName: 'lookup-account',
+                functionArgs: [Cl.buffer(pubkey)],
+                network,
+                senderAddress: sender,
+            });
+            const parsed = cvToValue(result);
+            if (parsed && typeof parsed === 'object' && parsed.type === 'optional') {
+                return parsed.value != null;
+            }
+            if (typeof parsed === 'string')
+                return true;
+            if (parsed && typeof parsed === 'object' && 'value' in parsed && parsed.value)
+                return true;
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isContractDeployed(address, name, network) {
+        const res = await fetch(`${network.client.baseUrl}/v2/contracts/interface/${address}/${name}`);
+        return res.ok;
+    }
+    async isKeyRegistered(address, name, pubkey, network, sender) {
+        try {
+            const result = await fetchCallReadOnlyFunction({
+                contractAddress: address,
+                contractName: name,
+                functionName: 'is-key-authorized',
+                functionArgs: [Cl.buffer(pubkey)],
+                network,
+                senderAddress: sender,
+            });
+            const parsed = cvToValue(result);
+            return parsed === true || (typeof parsed === 'object' && parsed?.value === true);
+        }
+        catch {
+            return false;
+        }
+    }
+    readAccountContractSource() {
+        const path = process.env.PASSKEY_ACCOUNT_CONTRACT_PATH ?? defaultAccountContractPath();
+        return readFileSync(path, 'utf8');
+    }
+    async submitFactoryRegister(factoryAddress, factoryName, pubkey, accountAddress, accountName, projectId) {
+        const network = getNetwork(this.config.network);
+        const fee = this.config.policy.maxFeeMicroStx;
+        const creds = await this.assertGas(projectId, fee);
+        const senderKey = platformRegistrarPrivateKey(this.config);
+        const lockAddress = platformRegistrarAddress(this.config);
+        const broadcastTask = () => this.broadcast(projectId, fee, async () => makeContractCall({
+            contractAddress: factoryAddress,
+            contractName: factoryName,
+            functionName: 'register-account',
+            functionArgs: [Cl.buffer(pubkey), Cl.contractPrincipal(accountAddress, accountName)],
+            senderKey,
+            network,
+            fee,
+        }));
+        if (creds) {
+            return runWithSponsorLock(lockAddress, broadcastTask);
+        }
+        return broadcastTask();
+    }
+    async assertGas(walletId, fee) {
+        if (!this.gasTank)
+            return null;
+        const creds = this.gasTank.getSponsorCredentials(walletId);
+        if (!creds)
+            throw new Error('Wallet not found');
+        const onChain = await fetchStxBalanceMicro(creds.sponsorAddress, this.config.network);
+        const available = this.gasTank.availableBalance(onChain, creds.wallet);
+        if (available < fee) {
+            throw new Error(`Insufficient gas tank balance for account operation. Deposit STX to ${creds.sponsorAddress}`);
+        }
+        this.gasTank.reserveGas(walletId, fee);
+        return creds;
+    }
+    async broadcast(projectId, fee, buildTx) {
+        const network = getNetwork(this.config.network);
+        let reserved = fee;
+        try {
+            const txid = await broadcastWithNonceRetry(async () => ({ transaction: await buildTx() }), 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);
+            }
+        }
+    }
+}

package/dist/account-service.test.d.ts

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

package/dist/account-service.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AccountService, DEFAULT_SELF_DEPLOY_ACCOUNT_NAME } from './account-service.js';
+import { AccountStore } from './accounts.js';
+describe('AccountService', () => {
+    let dir;
+    let service;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'account-service-'));
+        process.env.PASSKEY_ADAPTER_ADDRESS = 'ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ';
+        process.env.PASSKEY_ADAPTER_NAME = 'passkey-adapter';
+        const clarPath = join(dir, 'passkey-account.clar');
+        writeFileSync(clarPath, `(use-trait exec-trait .passkey-adapter.passkey-exec-trait)
+(contract-call? .passkey-adapter forward-invoke target)
+`);
+        process.env.PASSKEY_ACCOUNT_CONTRACT_PATH = clarPath;
+        const config = {
+            sponsorPrivateKey: '753b7cc01a1855527860d90776314512f5f16cc592133f14327856e06653810e01',
+            masterSecret: 'test-master',
+            sessionSecret: 'test-session',
+            network: 'testnet',
+            port: 8787,
+            host: '127.0.0.1',
+            policy: { maxFeeMicroStx: 50000n, rateLimit: { windowMs: 60_000, maxRequests: 100 } },
+        };
+        service = new AccountService(config, new AccountStore(join(dir, 'accounts.json')));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+        delete process.env.PASSKEY_ACCOUNT_CONTRACT_PATH;
+    });
+    it('uses smart-account as default self-deploy contract name', () => {
+        expect(DEFAULT_SELF_DEPLOY_ACCOUNT_NAME).toBe('smart-account');
+    });
+    it('injects fully-qualified passkey-adapter into contract source for user-origin deploys', () => {
+        const source = service.buildAccountContractSource();
+        expect(source).toContain("(use-trait exec-trait 'ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ.passkey-adapter.passkey-exec-trait)");
+        expect(source).toContain("(contract-call? 'ST3XHHZ1CXVCNYXK3FQ1FDGJ9NK6YBJBJK3FVY5KQ.passkey-adapter forward-invoke");
+        expect(source).not.toContain('(use-trait exec-trait .passkey-adapter');
+        expect(source).not.toContain('(contract-call? .passkey-adapter');
+    });
+});

package/dist/accounts.d.ts

@@ -0,0 +1,20 @@
+export interface AccountRecord {
+    publicKeyHex: string;
+    contractAddress: string;
+    contractName: string;
+    contractId: string;
+    projectId: string;
+    registerTxid?: string;
+    factoryTxid?: string;
+    createdAt: string;
+}
+export declare function defaultAccountsPath(): string;
+export declare class AccountStore {
+    private readonly path;
+    constructor(path: string);
+    private load;
+    private persist;
+    find(projectId: string, publicKeyHex: string): AccountRecord | undefined;
+    save(record: AccountRecord): void;
+    count(projectId: string): number;
+}

package/dist/accounts.js

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function defaultAccountsPath() {
+    return join(process.cwd(), 'data', 'accounts.json');
+}
+export class AccountStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return { accounts: [] };
+        return JSON.parse(readFileSync(this.path, 'utf8'));
+    }
+    persist(data) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, `${JSON.stringify(data, null, 2)}\n`);
+    }
+    find(projectId, publicKeyHex) {
+        const normalized = publicKeyHex.toLowerCase().replace(/^0x/, '');
+        return this.load().accounts.find((a) => a.projectId === projectId && a.publicKeyHex.toLowerCase() === normalized);
+    }
+    save(record) {
+        const data = this.load();
+        const normalized = record.publicKeyHex.toLowerCase().replace(/^0x/, '');
+        const next = data.accounts.filter((a) => !(a.projectId === record.projectId && a.publicKeyHex.toLowerCase() === normalized));
+        next.push({ ...record, publicKeyHex: normalized });
+        this.persist({ accounts: next });
+    }
+    count(projectId) {
+        return this.load().accounts.filter((a) => a.projectId === projectId).length;
+    }
+}

package/dist/app.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { RelayConfig } from './types.js';
+import { GasTankStore } from './gas-tank.js';
+export declare function createRelayApp(config: RelayConfig, gasTank?: GasTankStore): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;