@aspect-wallet/sdk 0.1.0

package/dist/auth/session.js

@@ -0,0 +1,61 @@
+/**
+ * JWT session management.
+ * Corresponds to SPEC-013 Section 7.4.
+ */
+import { FcxError } from '../core/errors.js';
+/**
+ * Manages authentication sessions (JWT lifecycle).
+ * Sessions are short-lived (1-24h), RS256 signed, and revocable.
+ */
+export class SessionManager {
+    api;
+    currentSession = null;
+    constructor(api) {
+        this.api = api;
+    }
+    /** Get the current session */
+    getSession() {
+        if (this.currentSession && this.currentSession.expiresAt < Date.now() / 1000) {
+            this.currentSession = null;
+        }
+        return this.currentSession;
+    }
+    /** Check if the user is authenticated with a valid session */
+    isAuthenticated() {
+        return this.getSession() !== null;
+    }
+    /** Set the session (called internally by auth flows) */
+    setSession(session) {
+        this.currentSession = session;
+        this.api.setSessionJwt(session.jwt);
+    }
+    /** Refresh the current session */
+    async refreshSession() {
+        if (!this.currentSession) {
+            throw new FcxError('AUTH_SESSION_EXPIRED', 'No active session to refresh');
+        }
+        const session = await this.api.post('/auth/session/refresh', {
+            jwt: this.currentSession.jwt,
+        });
+        this.setSession(session);
+        return session;
+    }
+    /** Get session info from the server */
+    async getServerSession() {
+        return this.api.get('/auth/session');
+    }
+    /** Logout and revoke the current session */
+    async logout() {
+        if (this.currentSession) {
+            await this.api.post('/auth/logout', {});
+        }
+        this.currentSession = null;
+        this.api.setSessionJwt(null);
+    }
+    /** Clear the local session without server-side revocation */
+    clearLocal() {
+        this.currentSession = null;
+        this.api.setSessionJwt(null);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI7C;;;GAGG;AACH,MAAM,OAAO,cAAc;IAGI;IAFrB,cAAc,GAAuB,IAAI,CAAC;IAElD,YAA6B,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAE/C,8BAA8B;IAC9B,UAAU;QACR,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;YAC7E,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,8DAA8D;IAC9D,eAAe;QACb,OAAO,IAAI,CAAC,UAAU,EAAE,KAAK,IAAI,CAAC;IACpC,CAAC;IAED,wDAAwD;IACxD,UAAU,CAAC,OAAoB;QAC7B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,QAAQ,CAAC,sBAAsB,EAAE,8BAA8B,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAc,uBAAuB,EAAE;YACxE,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG;SAC7B,CAAC,CAAC;QAEH,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,uCAAuC;IACvC,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAc,eAAe,CAAC,CAAC;IACpD,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,MAAM;QACV,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,6DAA6D;IAC7D,UAAU;QACR,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/chain/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Chain configuration registry.
+ * Corresponds to SPEC-013 Section 13.
+ */
+import { ApiClient } from '../transport/api.js';
+import type { ChainId, ChainInfo, ChainConfig } from '../types.js';
+/**
+ * Manages chain configurations and supports runtime chain switching.
+ */
+export declare class ChainRegistry {
+    private readonly api;
+    private cache;
+    constructor(api: ApiClient);
+    /** List all chains supported by the platform */
+    list(): Promise<ChainInfo[]>;
+    /** Get full configuration for a specific chain */
+    getConfig(chainId: ChainId): Promise<ChainConfig>;
+    /** Get the numeric chain ID for a chain identifier */
+    getNumericChainId(chainId: ChainId): number;
+    /** Get default config (local, no API call) */
+    getDefaultConfig(chainId: ChainId): Partial<ChainConfig> | undefined;
+    /** Clear the config cache */
+    clearCache(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/chain/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/chain/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEnE;;GAEG;AACH,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,KAAK,CAAmC;gBAEnB,GAAG,EAAE,SAAS;IAE3C,gDAAgD;IAC1C,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIlC,kDAAkD;IAC5C,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IASvD,sDAAsD;IACtD,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAQ3C,8CAA8C;IAC9C,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS;IAIpE,6BAA6B;IAC7B,UAAU,IAAI,IAAI;CAGnB"}

package/dist/chain/registry.js

@@ -0,0 +1,46 @@
+/**
+ * Chain configuration registry.
+ * Corresponds to SPEC-013 Section 13.
+ */
+import { FcxError } from '../core/errors.js';
+import { CHAIN_IDS, DEFAULT_CHAIN_CONFIGS } from '../core/config.js';
+/**
+ * Manages chain configurations and supports runtime chain switching.
+ */
+export class ChainRegistry {
+    api;
+    cache = new Map();
+    constructor(api) {
+        this.api = api;
+    }
+    /** List all chains supported by the platform */
+    async list() {
+        return this.api.get('/chains');
+    }
+    /** Get full configuration for a specific chain */
+    async getConfig(chainId) {
+        const cached = this.cache.get(chainId);
+        if (cached)
+            return cached;
+        const config = await this.api.get(`/chains/${chainId}/config`);
+        this.cache.set(chainId, config);
+        return config;
+    }
+    /** Get the numeric chain ID for a chain identifier */
+    getNumericChainId(chainId) {
+        const id = CHAIN_IDS[chainId];
+        if (id === undefined) {
+            throw new FcxError('CHAIN_UNSUPPORTED', `Unsupported chain: ${chainId}`);
+        }
+        return id;
+    }
+    /** Get default config (local, no API call) */
+    getDefaultConfig(chainId) {
+        return DEFAULT_CHAIN_CONFIGS[chainId];
+    }
+    /** Clear the config cache */
+    clearCache() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/chain/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/chain/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAIrE;;GAEG;AACH,MAAM,OAAO,aAAa;IAGK;IAFrB,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEhD,YAA6B,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAE/C,gDAAgD;IAChD,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAc,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,SAAS,CAAC,OAAgB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAc,WAAW,OAAO,SAAS,CAAC,CAAC;QAC5E,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sDAAsD;IACtD,iBAAiB,CAAC,OAAgB;QAChC,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,QAAQ,CAAC,mBAAmB,EAAE,sBAAsB,OAAO,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,8CAA8C;IAC9C,gBAAgB,CAAC,OAAgB;QAC/B,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,6BAA6B;IAC7B,UAAU;QACR,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/core/client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * FcxWalletClient -- main entry point for the SDK.
+ * Corresponds to SPEC-013 Section 2.3.
+ */
+import { ApiClient } from '../transport/api.js';
+import { BundlerClient } from '../transport/bundler.js';
+import { IframeBridge } from '../transport/iframe.js';
+import { WalletFactory } from '../wallet/factory.js';
+import { ChainRegistry } from '../chain/registry.js';
+import { PaymasterClient } from '../sponsor/paymaster.js';
+import { AuditClient } from '../audit/history.js';
+import type { Address, ChainId, FcxWalletClientConfig, SecurityEvent, SecurityEventType } from '../types.js';
+type SecurityEventHandler = (event: SecurityEvent) => void;
+/**
+ * Main SDK client. All wallet operations flow through this class.
+ *
+ * @example
+ * ```ts
+ * const client = new FcxWalletClient({
+ *   apiKey: 'fcx_live_abc123...',
+ *   chain: 'arbitrum-one',
+ *   bundlerUrl: 'https://bundler.yourapp.com/rpc',
+ * });
+ * ```
+ */
+export declare class FcxWalletClient {
+    /** Current chain identifier */
+    chain: ChainId;
+    /** Numeric chain ID */
+    readonly chainId: number;
+    /** EntryPoint contract address */
+    readonly entryPoint: Address;
+    /** Wallet lifecycle operations */
+    readonly wallet: WalletFactory;
+    /** Chain configuration registry */
+    readonly chains: ChainRegistry;
+    /** Gas sponsorship / paymaster */
+    readonly sponsor: PaymasterClient;
+    /** Bundler JSON-RPC client */
+    readonly bundler: BundlerClient;
+    /** Audit and logging */
+    readonly audit: AuditClient;
+    /** Platform API client (internal) */
+    readonly api: ApiClient;
+    /** Iframe bridge for cross-origin signing (internal) */
+    readonly iframe: IframeBridge | null;
+    private eventHandlers;
+    constructor(config: FcxWalletClientConfig);
+    /**
+     * Switch the active chain at runtime.
+     * Clears cached chain configurations.
+     */
+    switchChain(chain: ChainId): void;
+    /**
+     * Create a new client instance configured for a different chain.
+     * Useful for cross-chain operations while keeping the original client intact.
+     */
+    forChain(chain: ChainId): FcxWalletClient;
+    /**
+     * Subscribe to security events.
+     *
+     * @example
+     * ```ts
+     * client.on('security:suspicious', (event) => {
+     *   console.log(event.type, event.recommendation);
+     * });
+     * ```
+     */
+    on(event: 'security:suspicious', handler: SecurityEventHandler): void;
+    /** Unsubscribe from security events */
+    off(event: 'security:suspicious', handler: SecurityEventHandler): void;
+    /** Emit a security event (internal use) */
+    emitSecurityEvent(type: SecurityEventType, details: Record<string, unknown>, recommendation: SecurityEvent['recommendation']): void;
+    /** Clean up resources (iframe, event listeners) */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,KAAK,oBAAoB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;IAEf,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAExB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAErC,OAAO,CAAC,aAAa,CAAgD;gBAEzD,MAAM,EAAE,qBAAqB;IA2BzC;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAUjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe;IAQzC;;;;;;;;;OASG;IACH,EAAE,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI;IASrE,uCAAuC;IACvC,GAAG,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAItE,2CAA2C;IAC3C,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAUnI,mDAAmD;IACnD,OAAO,IAAI,IAAI;CAIhB"}

package/dist/core/client.js

@@ -0,0 +1,129 @@
+/**
+ * FcxWalletClient -- main entry point for the SDK.
+ * Corresponds to SPEC-013 Section 2.3.
+ */
+import { FcxError } from './errors.js';
+import { ENTRYPOINT_V06, CHAIN_IDS } from './config.js';
+import { ApiClient } from '../transport/api.js';
+import { BundlerClient } from '../transport/bundler.js';
+import { IframeBridge } from '../transport/iframe.js';
+import { WalletFactory } from '../wallet/factory.js';
+import { ChainRegistry } from '../chain/registry.js';
+import { PaymasterClient } from '../sponsor/paymaster.js';
+import { AuditClient } from '../audit/history.js';
+/**
+ * Main SDK client. All wallet operations flow through this class.
+ *
+ * @example
+ * ```ts
+ * const client = new FcxWalletClient({
+ *   apiKey: 'fcx_live_abc123...',
+ *   chain: 'arbitrum-one',
+ *   bundlerUrl: 'https://bundler.yourapp.com/rpc',
+ * });
+ * ```
+ */
+export class FcxWalletClient {
+    /** Current chain identifier */
+    chain;
+    /** Numeric chain ID */
+    chainId;
+    /** EntryPoint contract address */
+    entryPoint;
+    /** Wallet lifecycle operations */
+    wallet;
+    /** Chain configuration registry */
+    chains;
+    /** Gas sponsorship / paymaster */
+    sponsor;
+    /** Bundler JSON-RPC client */
+    bundler;
+    /** Audit and logging */
+    audit;
+    /** Platform API client (internal) */
+    api;
+    /** Iframe bridge for cross-origin signing (internal) */
+    iframe;
+    eventHandlers = new Map();
+    constructor(config) {
+        this.chain = config.chain;
+        this.chainId = CHAIN_IDS[config.chain] ?? (() => {
+            throw new FcxError('CHAIN_UNSUPPORTED', `Unsupported chain: ${config.chain}`);
+        })();
+        this.entryPoint = config.entryPoint ?? ENTRYPOINT_V06;
+        // Initialise transport clients
+        const apiBaseUrl = config.paymasterUrl ?? config.authUrl ?? 'https://api.fcxwallet.com/v1';
+        this.api = new ApiClient(apiBaseUrl, config.apiKey);
+        this.bundler = new BundlerClient(config.bundlerUrl ?? `https://bundler.fcxwallet.com/${config.chain}`, this.entryPoint);
+        this.iframe = config.signerIframeUrl
+            ? new IframeBridge(config.signerIframeUrl, typeof window !== 'undefined' ? window.location.origin : '')
+            : null;
+        // Initialise modules
+        this.wallet = new WalletFactory(this.api, this.chain);
+        this.chains = new ChainRegistry(this.api);
+        this.sponsor = new PaymasterClient(this.api);
+        this.audit = new AuditClient(this.api);
+    }
+    /**
+     * Switch the active chain at runtime.
+     * Clears cached chain configurations.
+     */
+    switchChain(chain) {
+        const newChainId = CHAIN_IDS[chain];
+        if (newChainId === undefined) {
+            throw new FcxError('CHAIN_UNSUPPORTED', `Unsupported chain: ${chain}`);
+        }
+        this.chain = chain;
+        this.chainId = newChainId;
+        this.chains.clearCache();
+    }
+    /**
+     * Create a new client instance configured for a different chain.
+     * Useful for cross-chain operations while keeping the original client intact.
+     */
+    forChain(chain) {
+        return new FcxWalletClient({
+            apiKey: this.api.apiKey,
+            chain,
+            entryPoint: this.entryPoint,
+        });
+    }
+    /**
+     * Subscribe to security events.
+     *
+     * @example
+     * ```ts
+     * client.on('security:suspicious', (event) => {
+     *   console.log(event.type, event.recommendation);
+     * });
+     * ```
+     */
+    on(event, handler) {
+        let handlers = this.eventHandlers.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.eventHandlers.set(event, handlers);
+        }
+        handlers.add(handler);
+    }
+    /** Unsubscribe from security events */
+    off(event, handler) {
+        this.eventHandlers.get(event)?.delete(handler);
+    }
+    /** Emit a security event (internal use) */
+    emitSecurityEvent(type, details, recommendation) {
+        const handlers = this.eventHandlers.get('security:suspicious');
+        if (handlers) {
+            const event = { type, details, recommendation };
+            for (const handler of handlers) {
+                handler(event);
+            }
+        }
+    }
+    /** Clean up resources (iframe, event listeners) */
+    destroy() {
+        this.iframe?.destroy();
+        this.eventHandlers.clear();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/core/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/core/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Chain configuration and constants.
+ * Corresponds to SPEC-013 Sections 2.3 and 13.
+ */
+import type { Address, ChainId, ChainConfig } from '../types.js';
+/** Canonical EntryPoint v0.6 address -- NEVER deploy custom (CLAUDE.md) */
+export declare const ENTRYPOINT_V06: Address;
+/** RIP-7212 P256 precompile address */
+export declare const RIP7212_PRECOMPILE: Address;
+/** ERC-1967 implementation slot */
+export declare const ERC1967_IMPLEMENTATION_SLOT: "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/** P256 curve order N */
+export declare const P256_N = 115792089210356248762697446949407573529996955224135760342422259061068512044369n;
+/** Gas estimation safety margin: 130% */
+export declare const GAS_SAFETY_MARGIN = 1.3;
+/** Fee estimation safety margin: 120% */
+export declare const FEE_SAFETY_MARGIN = 1.2;
+/** Numeric chain IDs */
+export declare const CHAIN_IDS: Record<ChainId, number>;
+/** Default chain configurations */
+export declare const DEFAULT_CHAIN_CONFIGS: Partial<Record<ChainId, Partial<ChainConfig>>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,2EAA2E;AAC3E,eAAO,MAAM,cAAc,EAAE,OAAsD,CAAC;AAEpF,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,EAAE,OAAsD,CAAC;AAExF,mCAAmC;AACnC,eAAO,MAAM,2BAA2B,EACtC,oEAA6E,CAAC;AAEhF,yBAAyB;AACzB,eAAO,MAAM,MAAM,kFAAsE,CAAC;AAE1F,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,wBAAwB;AACxB,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAS7C,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CA6DhF,CAAC"}

package/dist/core/config.js

@@ -0,0 +1,91 @@
+/**
+ * Chain configuration and constants.
+ * Corresponds to SPEC-013 Sections 2.3 and 13.
+ */
+/** Canonical EntryPoint v0.6 address -- NEVER deploy custom (CLAUDE.md) */
+export const ENTRYPOINT_V06 = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';
+/** RIP-7212 P256 precompile address */
+export const RIP7212_PRECOMPILE = '0x0000000000000000000000000000000000000100';
+/** ERC-1967 implementation slot */
+export const ERC1967_IMPLEMENTATION_SLOT = '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc';
+/** P256 curve order N */
+export const P256_N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+/** Gas estimation safety margin: 130% */
+export const GAS_SAFETY_MARGIN = 1.3;
+/** Fee estimation safety margin: 120% */
+export const FEE_SAFETY_MARGIN = 1.2;
+/** Numeric chain IDs */
+export const CHAIN_IDS = {
+    'arbitrum-one': 42161,
+    'arbitrum-sepolia': 421614,
+    'base': 8453,
+    'base-sepolia': 84532,
+    'polygon': 137,
+    'polygon-amoy': 80002,
+    'ethereum': 1,
+    'sepolia': 11155111,
+};
+/** Default chain configurations */
+export const DEFAULT_CHAIN_CONFIGS = {
+    'arbitrum-one': {
+        chainId: 42161,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 100000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: true, erc6900: true, sponsorship: true },
+    },
+    'arbitrum-sepolia': {
+        chainId: 421614,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 100000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: true, erc6900: true, sponsorship: true },
+    },
+    'base': {
+        chainId: 8453,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 100000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: true, erc6900: true, sponsorship: true },
+    },
+    'base-sepolia': {
+        chainId: 84532,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 100000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: true, erc6900: true, sponsorship: true },
+    },
+    'polygon': {
+        chainId: 137,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 30000000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: false, erc6900: true, sponsorship: true },
+    },
+    'sepolia': {
+        chainId: 11155111,
+        entryPoint: ENTRYPOINT_V06,
+        gas: {
+            safetyMargin: GAS_SAFETY_MARGIN,
+            minPriorityFee: 100000000n,
+            estimationMethod: 'bundler',
+        },
+        features: { rip7212: true, erc6900: true, sponsorship: true },
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Error taxonomy for the FcxWallet SDK.
+ * Corresponds to SPEC-013 Section 15.
+ */
+import type { Hex } from '../types.js';
+/** All error codes defined in SPEC-013 Section 15.2 */
+export type FcxErrorCode = 'API_KEY_INVALID' | 'API_KEY_CHAIN_MISMATCH' | 'API_KEY_QUOTA_EXCEEDED' | 'API_KEY_PERMISSION_DENIED' | 'AUTH_OTP_INVALID' | 'AUTH_OTP_EXPIRED' | 'AUTH_OTP_RATE_LIMITED' | 'AUTH_SESSION_EXPIRED' | 'AUTH_SESSION_REVOKED' | 'AUTH_OAUTH_FAILED' | 'WALLET_NOT_DEPLOYED' | 'WALLET_FROZEN' | 'USEROP_SIGNATURE_INVALID' | 'USEROP_SIMULATION_FAILED' | 'USEROP_PAYMASTER_REJECTED' | 'USEROP_OPCODE_BANNED' | 'USEROP_EXPIRED' | 'USEROP_PAYMASTER_THROTTLED' | 'USEROP_STAKE_TOO_LOW' | 'USEROP_GAS_TOO_LOW' | 'USEROP_NONCE_INVALID' | 'SPONSOR_BUDGET_EXHAUSTED' | 'SPONSOR_POLICY_REJECTED' | 'SPONSOR_SIGNER_ERROR' | 'SESSION_KEY_EXPIRED' | 'SESSION_KEY_SPEND_EXCEEDED' | 'SESSION_KEY_NOT_ALLOWED' | 'SESSION_KEY_PAYMASTER_WRONG' | 'MFA_THRESHOLD_NOT_MET' | 'MFA_TIMELOCK_PENDING' | 'RECOVERY_NOT_AUTHORIZED' | 'RECOVERY_TIMELOCK_PENDING' | 'RECOVERY_ALREADY_PENDING' | 'CHAIN_UNSUPPORTED' | 'NETWORK_ERROR' | 'IFRAME_TIMEOUT';
+/**
+ * Structured error class for all SDK operations.
+ * Every error has a typed code, optional details, and retryability flag.
+ */
+export declare class FcxError extends Error {
+    readonly code: FcxErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly userOpHash?: Hex;
+    readonly httpStatus?: number;
+    readonly rpcCode?: number;
+    readonly retryable: boolean;
+    constructor(code: FcxErrorCode, message: string, options?: {
+        details?: Record<string, unknown>;
+        userOpHash?: Hex;
+        cause?: Error;
+    });
+    /** Create FcxError from a bundler JSON-RPC error response */
+    static fromRpcError(rpcCode: number, message: string, data?: Record<string, unknown>): FcxError;
+    /** Create FcxError from an HTTP error response */
+    static fromHttpError(status: number, body: {
+        code?: string;
+        message?: string;
+    }): FcxError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEvC,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAEpB,iBAAiB,GACjB,wBAAwB,GACxB,wBAAwB,GACxB,2BAA2B,GAE3B,kBAAkB,GAClB,kBAAkB,GAClB,uBAAuB,GACvB,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GAEnB,qBAAqB,GACrB,eAAe,GAEf,0BAA0B,GAC1B,0BAA0B,GAC1B,2BAA2B,GAC3B,sBAAsB,GACtB,gBAAgB,GAChB,4BAA4B,GAC5B,sBAAsB,GACtB,oBAAoB,GACpB,sBAAsB,GAEtB,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,GAEtB,qBAAqB,GACrB,4BAA4B,GAC5B,yBAAyB,GACzB,6BAA6B,GAE7B,uBAAuB,GACvB,sBAAsB,GAEtB,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,GAE1B,mBAAmB,GAEnB,eAAe,GACf,gBAAgB,CAAC;AA6DrB;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAG1B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,UAAU,CAAC,EAAE,GAAG,CAAC;QACjB,KAAK,CAAC,EAAE,KAAK,CAAC;KACf;IAYH,6DAA6D;IAC7D,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ;IAO/F,kDAAkD;IAClD,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,QAAQ;CAM1F"}

package/dist/core/errors.js

@@ -0,0 +1,95 @@
+/**
+ * Error taxonomy for the FcxWallet SDK.
+ * Corresponds to SPEC-013 Section 15.
+ */
+/** HTTP status codes mapped to error codes */
+const ERROR_HTTP_STATUS = {
+    API_KEY_INVALID: 401,
+    API_KEY_CHAIN_MISMATCH: 403,
+    API_KEY_QUOTA_EXCEEDED: 429,
+    API_KEY_PERMISSION_DENIED: 403,
+    AUTH_OTP_INVALID: 401,
+    AUTH_OTP_EXPIRED: 401,
+    AUTH_OTP_RATE_LIMITED: 429,
+    AUTH_SESSION_EXPIRED: 401,
+    AUTH_SESSION_REVOKED: 401,
+    AUTH_OAUTH_FAILED: 401,
+    WALLET_NOT_DEPLOYED: 400,
+    WALLET_FROZEN: 403,
+    USEROP_SIGNATURE_INVALID: undefined,
+    USEROP_SIMULATION_FAILED: undefined,
+    USEROP_PAYMASTER_REJECTED: undefined,
+    USEROP_OPCODE_BANNED: undefined,
+    USEROP_EXPIRED: undefined,
+    USEROP_PAYMASTER_THROTTLED: undefined,
+    USEROP_STAKE_TOO_LOW: undefined,
+    USEROP_GAS_TOO_LOW: 400,
+    USEROP_NONCE_INVALID: 400,
+    SPONSOR_BUDGET_EXHAUSTED: 402,
+    SPONSOR_POLICY_REJECTED: 403,
+    SPONSOR_SIGNER_ERROR: 500,
+    SESSION_KEY_EXPIRED: 403,
+    SESSION_KEY_SPEND_EXCEEDED: 403,
+    SESSION_KEY_NOT_ALLOWED: 403,
+    SESSION_KEY_PAYMASTER_WRONG: 403,
+    MFA_THRESHOLD_NOT_MET: 403,
+    MFA_TIMELOCK_PENDING: 403,
+    RECOVERY_NOT_AUTHORIZED: 403,
+    RECOVERY_TIMELOCK_PENDING: 403,
+    RECOVERY_ALREADY_PENDING: 409,
+    CHAIN_UNSUPPORTED: 400,
+    NETWORK_ERROR: 503,
+    IFRAME_TIMEOUT: 408,
+};
+/** JSON-RPC error codes for bundler errors */
+const ERROR_RPC_CODES = {
+    USEROP_SIGNATURE_INVALID: -32507,
+    USEROP_SIMULATION_FAILED: -32500,
+    USEROP_PAYMASTER_REJECTED: -32501,
+    USEROP_OPCODE_BANNED: -32502,
+    USEROP_EXPIRED: -32503,
+    USEROP_PAYMASTER_THROTTLED: -32504,
+    USEROP_STAKE_TOO_LOW: -32505,
+};
+/** Whether an error code is retryable */
+const RETRYABLE_CODES = new Set([
+    'NETWORK_ERROR',
+    'IFRAME_TIMEOUT',
+    'USEROP_GAS_TOO_LOW',
+    'SPONSOR_SIGNER_ERROR',
+]);
+/**
+ * Structured error class for all SDK operations.
+ * Every error has a typed code, optional details, and retryability flag.
+ */
+export class FcxError extends Error {
+    code;
+    details;
+    userOpHash;
+    httpStatus;
+    rpcCode;
+    retryable;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'FcxError';
+        this.code = code;
+        this.details = options?.details;
+        this.userOpHash = options?.userOpHash;
+        this.httpStatus = ERROR_HTTP_STATUS[code];
+        this.rpcCode = ERROR_RPC_CODES[code];
+        this.retryable = RETRYABLE_CODES.has(code);
+    }
+    /** Create FcxError from a bundler JSON-RPC error response */
+    static fromRpcError(rpcCode, message, data) {
+        const code = Object.entries(ERROR_RPC_CODES).find(([, v]) => v === rpcCode)?.[0];
+        return new FcxError(code ?? 'USEROP_SIMULATION_FAILED', message, { details: data });
+    }
+    /** Create FcxError from an HTTP error response */
+    static fromHttpError(status, body) {
+        const code = body.code ?? 'NETWORK_ERROR';
+        return new FcxError(code, body.message ?? `HTTP ${status}`, {
+            details: { httpStatus: status },
+        });
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}