passkey-kit 0.12.1 → 0.14.0

package/{types → dist}/base.d.ts

@@ -4,3 +4,4 @@ export declare class PasskeyBase {
     rpc: Server | undefined;
     constructor(rpcUrl?: string);
 }
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAOjD,qBAAa,WAAW;IACb,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;gBAElB,MAAM,CAAC,EAAE,MAAM;CAM9B"}

package/{src/base.ts → dist/base.js}

@@ -1,18 +1,16 @@
-import { Server } from "@stellar/stellar-sdk/rpc"
-
+import { Server } from "@stellar/stellar-sdk/rpc";
 // TODO consider adding support for a signAuthEntry method that conforms to the ed25519 signature scheme of this passkey interface
 // once we do that we can clean the code a little with the `xdr.HashIdPreimage.envelopeTypeSorobanAuthorization` stuff
 // ... note I've re-read the above and I've currently got no clue what this is asking for. Maybe check git-blame for when it was added to try and find some context
 // actually this is just talking about adding support for signing transactions with an ed25519 key as well as a passkey. Simple enough
-
 export class PasskeyBase {
-    public rpcUrl: string | undefined
-    public rpc: Server | undefined
-    
-    constructor(rpcUrl?: string) {
+    rpcUrl;
+    rpc;
+    constructor(rpcUrl) {
         if (rpcUrl) {
-            this.rpcUrl = rpcUrl
-            this.rpc = new Server(rpcUrl)
+            this.rpcUrl = rpcUrl;
+            this.rpc = new Server(rpcUrl);
         }
     }
-}
+}
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAEjD,kIAAkI;AAClI,sHAAsH;AACtH,mKAAmK;AACnK,sIAAsI;AAEtI,MAAM,OAAO,WAAW;IACb,MAAM,CAAoB;IAC1B,GAAG,CAAoB;IAE9B,YAAY,MAAe;QACvB,IAAI,MAAM,EAAE,CAAC;YACT,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;YACpB,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,CAAC;IACL,CAAC;CACJ"}

package/dist/base64url.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `base64url` interop shim.
+ *
+ * The `base64url` package ships ESM-style type declarations
+ * (`export default base64url`) over a CommonJS runtime. Under NodeNext module
+ * resolution the default import is typed as the module namespace object rather
+ * than the callable `Base64Url`, so both calling it (`base64url(...)`) and
+ * member access (`base64url.toBuffer(...)`) fail to type-check. At runtime
+ * `esModuleInterop` already yields the callable, so this is a type-only
+ * correction, centralized here rather than repeated at every call site.
+ *
+ * Every module in the kit imports base64url from here, never directly from the
+ * package, so the interop fix lives in exactly one place.
+ */
+import { type Base64Url } from "base64url";
+declare const base64url: Base64Url;
+export default base64url;
+//# sourceMappingURL=base64url.d.ts.map

package/dist/base64url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64url.d.ts","sourceRoot":"","sources":["../src/base64url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAyB,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE7D,QAAA,MAAM,SAAS,EAAkC,SAAS,CAAC;AAE3D,eAAe,SAAS,CAAC"}

package/dist/base64url.js

@@ -0,0 +1,18 @@
+/**
+ * `base64url` interop shim.
+ *
+ * The `base64url` package ships ESM-style type declarations
+ * (`export default base64url`) over a CommonJS runtime. Under NodeNext module
+ * resolution the default import is typed as the module namespace object rather
+ * than the callable `Base64Url`, so both calling it (`base64url(...)`) and
+ * member access (`base64url.toBuffer(...)`) fail to type-check. At runtime
+ * `esModuleInterop` already yields the callable, so this is a type-only
+ * correction, centralized here rather than repeated at every call site.
+ *
+ * Every module in the kit imports base64url from here, never directly from the
+ * package, so the interop fix lives in exactly one place.
+ */
+import base64urlDefault from "base64url";
+const base64url = base64urlDefault;
+export default base64url;
+//# sourceMappingURL=base64url.js.map

package/dist/base64url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64url.js","sourceRoot":"","sources":["../src/base64url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,gBAAoC,MAAM,WAAW,CAAC;AAE7D,MAAM,SAAS,GAAG,gBAAwC,CAAC;AAE3D,eAAe,SAAS,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Constants used throughout the Passkey Kit SDK.
+ *
+ * Cryptographic sizes mirror the smart-wallet contract; the deployer seed is
+ * load-bearing for deterministic contract-id derivation (see below).
+ *
+ * @packageDocumentation
+ */
+/** Size of an uncompressed secp256r1 (P-256) public key, in bytes. */
+export declare const SECP256R1_PUBLIC_KEY_SIZE = 65;
+/** First byte of an uncompressed secp256r1 public key (0x04). */
+export declare const UNCOMPRESSED_PUBKEY_PREFIX = 4;
+/** Size of an Ed25519 public key, in bytes. */
+export declare const ED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an Ed25519 signature, in bytes. */
+export declare const ED25519_SIGNATURE_SIZE = 64;
+/**
+ * Order (n) of the secp256r1 (P-256) curve, used to enforce low-S signatures.
+ * @see https://github.com/stellar/stellar-protocol/discussions/1435
+ */
+export declare const SECP256R1_CURVE_ORDER: bigint;
+/** Field prime (p) of the secp256r1 (P-256) curve. */
+export declare const SECP256R1_FIELD_PRIME: bigint;
+/** Curve coefficient `b` of secp256r1 (P-256): y² = x³ − 3x + b (mod p). */
+export declare const SECP256R1_B: bigint;
+/** Default timeout for WebAuthn ceremonies, in milliseconds. */
+export declare const WEBAUTHN_TIMEOUT_MS = 60000;
+/** Length, in bytes, of a randomly generated WebAuthn challenge. */
+export declare const WEBAUTHN_CHALLENGE_SIZE = 32;
+/**
+ * Seed for the default (deterministic) deployer keypair.
+ *
+ * The deployer keypair is derived as
+ * `Keypair.fromRawEd25519Seed(sha256(utf8(DEFAULT_DEPLOYER_SEED)))`. Deriving it
+ * from a fixed, well-known string makes smart-wallet contract IDs reproducible
+ * across clients from a passkey credential ID alone (`salt = sha256(keyId)`,
+ * `deployer = this keypair`), which is exactly what the indexer reverse-lookup
+ * (keyId → contract) depends on.
+ *
+ * This value MUST remain `"kalepail"`: every wallet ever deployed by passkey-kit
+ * used this deployer, and the derivation is load-bearing for discovery. The
+ * deployer only pays fees and salts the deploy — it never controls the wallet —
+ * but it IS a shared, publicly-derivable keypair. Provide your own
+ * `deploySource` secret for a dedicated fee payer (note: a different deployer
+ * changes the derived contract addresses and breaks keyId → contract discovery).
+ */
+export declare const DEFAULT_DEPLOYER_SEED = "kalepail";
+/**
+ * Default transaction timeout, in seconds.
+ *
+ * The OpenZeppelin Relayer requires a time-bound of <= 30s on submitted
+ * transactions, so the kit defaults to that.
+ */
+export declare const DEFAULT_TIMEOUT_SECONDS = 30;
+/** Default IndexedDB database name for passkey credential storage. */
+export declare const DB_NAME = "passkey-kit";
+/** Current IndexedDB schema version. */
+export declare const DB_VERSION = 1;
+/** IndexedDB object-store name for passkey credentials. */
+export declare const IDB_STORE_CREDENTIALS = "credentials";
+/** IndexedDB index name for contract-id lookups. */
+export declare const IDB_INDEX_CONTRACT_ID = "contractId";
+/** localStorage key under which passkey credentials are persisted. */
+export declare const LOCALSTORAGE_CREDENTIALS_KEY = "passkey-kit:credentials";
+/**
+ * Default relayer request timeout, in milliseconds (6 minutes).
+ *
+ * Long enough to absorb testnet channel-account funding retries after a network
+ * reset. Mainnet requests return quickly; this only bounds the maximum wait.
+ */
+export declare const DEFAULT_RELAYER_TIMEOUT_MS = 360000;
+/** OpenZeppelin managed Channels relayer endpoint (mainnet). */
+export declare const CHANNELS_MAINNET_URL = "https://channels.openzeppelin.com";
+/** OpenZeppelin managed Channels relayer endpoint (testnet). */
+export declare const CHANNELS_TESTNET_URL = "https://channels.openzeppelin.com/testnet";
+/** Default indexer request timeout, in milliseconds. */
+export declare const DEFAULT_INDEXER_TIMEOUT_MS = 10000;
+/**
+ * Mercury's hosted, keyless passkey-indexer base URLs, per network. Public REST
+ * (no API key / JWT); covers both the legacy `("sw_v1", …)` and v1
+ * `#[contractevent]` signer generations with full history.
+ *
+ * @see https://docs.mercurydata.app/smart-wallet-indexers/introduction-1
+ */
+export declare const MERCURY_PASSKEY_INDEXER_URLS: {
+    readonly testnet: "https://testnet.mercurydata.app/rest/passkey-indexer";
+    readonly mainnet: "https://mainnet.mercurydata.app/rest/passkey-indexer";
+};
+/** Stellar Friendbot URL for testnet funding. */
+export declare const FRIENDBOT_URL = "https://friendbot.stellar.org";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,IAAO,CAAC;AAE/C,+CAA+C;AAC/C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,WAAW,QAEvB,CAAC;AAMF,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAM1C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAMhD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAM1C,sEAAsE;AACtE,eAAO,MAAM,OAAO,gBAAgB,CAAC;AAErC,wCAAwC;AACxC,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,sEAAsE;AACtE,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAMtE;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,sCAAsC,CAAC;AAExE,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,8CAA8C,CAAC;AAMhF,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;CAG/B,CAAC;AAMX,iDAAiD;AACjD,eAAO,MAAM,aAAa,kCAAkC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,115 @@
+/**
+ * Constants used throughout the Passkey Kit SDK.
+ *
+ * Cryptographic sizes mirror the smart-wallet contract; the deployer seed is
+ * load-bearing for deterministic contract-id derivation (see below).
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Cryptographic constants (mirror the smart-wallet contract)
+// ============================================================================
+/** Size of an uncompressed secp256r1 (P-256) public key, in bytes. */
+export const SECP256R1_PUBLIC_KEY_SIZE = 65;
+/** First byte of an uncompressed secp256r1 public key (0x04). */
+export const UNCOMPRESSED_PUBKEY_PREFIX = 0x04;
+/** Size of an Ed25519 public key, in bytes. */
+export const ED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an Ed25519 signature, in bytes. */
+export const ED25519_SIGNATURE_SIZE = 64;
+/**
+ * Order (n) of the secp256r1 (P-256) curve, used to enforce low-S signatures.
+ * @see https://github.com/stellar/stellar-protocol/discussions/1435
+ */
+export const SECP256R1_CURVE_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
+/** Field prime (p) of the secp256r1 (P-256) curve. */
+export const SECP256R1_FIELD_PRIME = BigInt("0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff");
+/** Curve coefficient `b` of secp256r1 (P-256): y² = x³ − 3x + b (mod p). */
+export const SECP256R1_B = BigInt("0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b");
+// ============================================================================
+// WebAuthn configuration
+// ============================================================================
+/** Default timeout for WebAuthn ceremonies, in milliseconds. */
+export const WEBAUTHN_TIMEOUT_MS = 60_000;
+/** Length, in bytes, of a randomly generated WebAuthn challenge. */
+export const WEBAUTHN_CHALLENGE_SIZE = 32;
+// ============================================================================
+// Deployer
+// ============================================================================
+/**
+ * Seed for the default (deterministic) deployer keypair.
+ *
+ * The deployer keypair is derived as
+ * `Keypair.fromRawEd25519Seed(sha256(utf8(DEFAULT_DEPLOYER_SEED)))`. Deriving it
+ * from a fixed, well-known string makes smart-wallet contract IDs reproducible
+ * across clients from a passkey credential ID alone (`salt = sha256(keyId)`,
+ * `deployer = this keypair`), which is exactly what the indexer reverse-lookup
+ * (keyId → contract) depends on.
+ *
+ * This value MUST remain `"kalepail"`: every wallet ever deployed by passkey-kit
+ * used this deployer, and the derivation is load-bearing for discovery. The
+ * deployer only pays fees and salts the deploy — it never controls the wallet —
+ * but it IS a shared, publicly-derivable keypair. Provide your own
+ * `deploySource` secret for a dedicated fee payer (note: a different deployer
+ * changes the derived contract addresses and breaks keyId → contract discovery).
+ */
+export const DEFAULT_DEPLOYER_SEED = "kalepail";
+// ============================================================================
+// Transaction timeouts
+// ============================================================================
+/**
+ * Default transaction timeout, in seconds.
+ *
+ * The OpenZeppelin Relayer requires a time-bound of <= 30s on submitted
+ * transactions, so the kit defaults to that.
+ */
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+// ============================================================================
+// Storage configuration
+// ============================================================================
+/** Default IndexedDB database name for passkey credential storage. */
+export const DB_NAME = "passkey-kit";
+/** Current IndexedDB schema version. */
+export const DB_VERSION = 1;
+/** IndexedDB object-store name for passkey credentials. */
+export const IDB_STORE_CREDENTIALS = "credentials";
+/** IndexedDB index name for contract-id lookups. */
+export const IDB_INDEX_CONTRACT_ID = "contractId";
+/** localStorage key under which passkey credentials are persisted. */
+export const LOCALSTORAGE_CREDENTIALS_KEY = "passkey-kit:credentials";
+// ============================================================================
+// Relayer
+// ============================================================================
+/**
+ * Default relayer request timeout, in milliseconds (6 minutes).
+ *
+ * Long enough to absorb testnet channel-account funding retries after a network
+ * reset. Mainnet requests return quickly; this only bounds the maximum wait.
+ */
+export const DEFAULT_RELAYER_TIMEOUT_MS = 360_000;
+/** OpenZeppelin managed Channels relayer endpoint (mainnet). */
+export const CHANNELS_MAINNET_URL = "https://channels.openzeppelin.com";
+/** OpenZeppelin managed Channels relayer endpoint (testnet). */
+export const CHANNELS_TESTNET_URL = "https://channels.openzeppelin.com/testnet";
+// ============================================================================
+// Indexer
+// ============================================================================
+/** Default indexer request timeout, in milliseconds. */
+export const DEFAULT_INDEXER_TIMEOUT_MS = 10_000;
+/**
+ * Mercury's hosted, keyless passkey-indexer base URLs, per network. Public REST
+ * (no API key / JWT); covers both the legacy `("sw_v1", …)` and v1
+ * `#[contractevent]` signer generations with full history.
+ *
+ * @see https://docs.mercurydata.app/smart-wallet-indexers/introduction-1
+ */
+export const MERCURY_PASSKEY_INDEXER_URLS = {
+    testnet: "https://testnet.mercurydata.app/rest/passkey-indexer",
+    mainnet: "https://mainnet.mercurydata.app/rest/passkey-indexer",
+};
+// ============================================================================
+// Networks
+// ============================================================================
+/** Stellar Friendbot URL for testnet funding. */
+export const FRIENDBOT_URL = "https://friendbot.stellar.org";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,6DAA6D;AAC7D,+EAA+E;AAE/E,sEAAsE;AACtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C,iEAAiE;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C,+CAA+C;AAC/C,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CACzC,oEAAoE,CACrE,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CACzC,oEAAoE,CACrE,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAC/B,oEAAoE,CACrE,CAAC;AAEF,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,oEAAoE;AACpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;AAEhD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,sEAAsE;AACtE,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;AAErC,wCAAwC;AACxC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAE5B,2DAA2D;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD,oDAAoD;AACpD,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAElD,sEAAsE;AACtE,MAAM,CAAC,MAAM,4BAA4B,GAAG,yBAAyB,CAAC;AAEtE,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAElD,gEAAgE;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,mCAAmC,CAAC;AAExE,gEAAgE;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,2CAA2C,CAAC;AAEhF,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,wDAAwD;AACxD,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,OAAO,EAAE,sDAAsD;IAC/D,OAAO,EAAE,sDAAsD;CACvD,CAAC;AAEX,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,iDAAiD;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC"}

package/dist/contract-errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Contract error decoding.
+ *
+ * Maps on-chain smart-wallet failure codes (surfaced in simulation/submission
+ * diagnostics as `Error(Contract, #N)`) to typed {@link ContractError}s with the
+ * enum variant name and a human-readable message.
+ *
+ * The `SmartWallet` family is the source of truth in the generated bindings'
+ * `Errors` map; `contract-errors.test.ts` asserts this registry stays in sync
+ * with it, so a bindings regen surfaces any drift.
+ *
+ * The v1 contract deliberately renumbered its error space to 100-129 so it is
+ * disjoint from the legacy (pre-1.0) 1-9 range: a decoded code < 100 means the
+ * client is talking to a legacy wallet. Both ranges are kept here so errors
+ * from legacy deployed wallets still decode (family `SmartWalletLegacy`).
+ *
+ * @packageDocumentation
+ */
+import { ContractError, PasskeyKitError } from "./errors.js";
+import type { TransactionFailure } from "./types.js";
+/**
+ * Contract families that expose custom error codes.
+ */
+export type ContractErrorFamily = "SmartWallet" | "SmartWalletLegacy";
+/**
+ * A single contract error entry: code, enum variant name, family, and a
+ * human-readable message.
+ */
+export interface ContractErrorInfo {
+    code: number;
+    name: string;
+    family: ContractErrorFamily;
+    message: string;
+}
+/**
+ * Registry of every known contract error code, keyed by numeric code.
+ */
+export declare const CONTRACT_ERROR_REGISTRY: Readonly<Record<number, ContractErrorInfo>>;
+/**
+ * Build a {@link ContractError} for a known contract code, or `null` if the code
+ * is not in the registry.
+ */
+export declare function contractErrorFromCode(code: number, context?: Record<string, unknown>): ContractError | null;
+/**
+ * Decode a simulation/submission diagnostic into a typed {@link ContractError}.
+ *
+ * Scans the (stringified) diagnostic for an `Error(Contract, #N)` marker and
+ * looks the code up in {@link CONTRACT_ERROR_REGISTRY}. Returns `null` when no
+ * contract code is present or the code is unknown, letting callers fall back to
+ * a generic {@link SimulationError}/{@link SubmissionError}.
+ */
+export declare function decodeContractError(diagnostic: unknown): ContractError | null;
+/**
+ * Build a {@link TransactionFailure} from an already-typed error.
+ */
+export declare function failedTransaction(error: PasskeyKitError, hash?: string): TransactionFailure;
+/**
+ * Build a {@link TransactionFailure} from a simulation diagnostic, decoding a
+ * contract error when present and otherwise wrapping it in a
+ * {@link SimulationError}.
+ */
+export declare function simulationFailure(diagnostic: unknown, hash?: string): TransactionFailure;
+/**
+ * Build a {@link TransactionFailure} from a submission diagnostic, decoding a
+ * contract error when present and otherwise wrapping it in a
+ * {@link SubmissionError}.
+ */
+export declare function submissionFailure(diagnostic: unknown, hash?: string): TransactionFailure;
+//# sourceMappingURL=contract-errors.d.ts.map

package/dist/contract-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-errors.d.ts","sourceRoot":"","sources":["../src/contract-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EAGb,eAAe,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAC5C,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAiClC,CAAC;AAkBF;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,aAAa,GAAG,IAAI,CAMtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAM7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,IAAI,CAAC,EAAE,MAAM,GACZ,kBAAkB,CAMpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,OAAO,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,kBAAkB,CAKpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,OAAO,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,kBAAkB,CAQpB"}

package/dist/contract-errors.js

@@ -0,0 +1,132 @@
+/**
+ * Contract error decoding.
+ *
+ * Maps on-chain smart-wallet failure codes (surfaced in simulation/submission
+ * diagnostics as `Error(Contract, #N)`) to typed {@link ContractError}s with the
+ * enum variant name and a human-readable message.
+ *
+ * The `SmartWallet` family is the source of truth in the generated bindings'
+ * `Errors` map; `contract-errors.test.ts` asserts this registry stays in sync
+ * with it, so a bindings regen surfaces any drift.
+ *
+ * The v1 contract deliberately renumbered its error space to 100-129 so it is
+ * disjoint from the legacy (pre-1.0) 1-9 range: a decoded code < 100 means the
+ * client is talking to a legacy wallet. Both ranges are kept here so errors
+ * from legacy deployed wallets still decode (family `SmartWalletLegacy`).
+ *
+ * @packageDocumentation
+ */
+import { ContractError, SimulationError, SubmissionError, } from "./errors.js";
+function entry(code, name, family, message) {
+    return [code, { code, name, family, message }];
+}
+/**
+ * Registry of every known contract error code, keyed by numeric code.
+ */
+export const CONTRACT_ERROR_REGISTRY = Object.freeze(Object.fromEntries([
+    // --- v1 SmartWallet (100-129) — source of truth in the bindings Errors map ---
+    // 100-109: signer storage / management
+    entry(100, "SignerNotFound", "SmartWallet", "The requested signer does not exist on this smart wallet."),
+    entry(101, "SignerAlreadyExists", "SmartWallet", "add_signer was called with a signer key that already exists."),
+    entry(102, "SignerExpired", "SmartWallet", "The signer's expiration timestamp is in the past."),
+    entry(103, "LastAdminSigner", "SmartWallet", "This change would remove or demote the wallet's last durable admin signer (persistent, non-expiring, independently admin-capable) and permanently lock the wallet's admin surface; add or promote a replacement admin signer first."),
+    entry(104, "LastSigner", "SmartWallet", "The operation would leave the wallet without any durable (Persistent, non-expiring) signer — thrown by remove_signer, update_signer demotions, and a __constructor with a non-durable first signer; keep or add a Persistent, non-expiring signer."),
+    // 110-119: auth (__check_auth)
+    entry(110, "MissingContext", "SmartWallet", "No signer in the signatures map is permitted to authorize one of the requested auth contexts."),
+    entry(111, "SignatureKeyValueMismatch", "SmartWallet", "A signature's variant does not match the stored signer it claims to be for."),
+    // 120-129: WebAuthn (secp256r1) verification
+    entry(120, "ClientDataJsonTooLarge", "SmartWallet", "clientDataJSON exceeds the 1024-byte parse buffer."),
+    entry(121, "ClientDataJsonParseError", "SmartWallet", "clientDataJSON is not parseable JSON (or is missing required fields)."),
+    entry(122, "ClientDataJsonChallengeIncorrect", "SmartWallet", "The clientDataJSON challenge does not match the signature payload; this binding MUST NOT be weakened."),
+    entry(123, "InvalidWebAuthnType", "SmartWallet", 'clientDataJSON `type` is not "webauthn.get".'),
+    entry(124, "InvalidAuthenticatorData", "SmartWallet", "authenticatorData is shorter than the WebAuthn minimum of 37 bytes."),
+    entry(125, "UserPresenceRequired", "SmartWallet", "The authenticator did not set the User Present (UP) flag."),
+    entry(126, "AuthenticatorDataTooLarge", "SmartWallet", "authenticatorData exceeds the 1024-byte cap."),
+    // --- Legacy (pre-1.0) 1-9 — kept so errors from legacy deployed wallets decode ---
+    entry(1, "NotFound", "SmartWalletLegacy", "[legacy] The specified signer was not found."),
+    entry(2, "AlreadyExists", "SmartWalletLegacy", "[legacy] The signer already exists on this wallet."),
+    entry(3, "MissingContext", "SmartWalletLegacy", "[legacy] The signature did not cover a required authorization context."),
+    entry(4, "SignerExpired", "SmartWalletLegacy", "[legacy] The signer has expired."),
+    entry(5, "FailedSignerLimits", "SmartWalletLegacy", "[legacy] The signer is not permitted to authorize this context by its limits."),
+    entry(6, "FailedPolicySignerLimits", "SmartWalletLegacy", "[legacy] A policy signer's limits rejected this context."),
+    entry(7, "SignatureKeyValueMismatch", "SmartWalletLegacy", "[legacy] A signature entry's key and value did not match."),
+    entry(8, "ClientDataJsonChallengeIncorrect", "SmartWalletLegacy", "[legacy] The WebAuthn clientDataJSON challenge did not match the signature payload."),
+    entry(9, "JsonParseError", "SmartWalletLegacy", "[legacy] The WebAuthn clientDataJSON could not be parsed."),
+]));
+/**
+ * Matches the host's rendering of a contract error, e.g. `Error(Contract, #4)`.
+ */
+const CONTRACT_ERROR_PATTERN = /Error\(Contract,\s*#(\d+)\)/;
+function diagnosticToString(diagnostic) {
+    if (diagnostic == null)
+        return "";
+    if (typeof diagnostic === "string")
+        return diagnostic;
+    if (diagnostic instanceof Error)
+        return diagnostic.message;
+    try {
+        return JSON.stringify(diagnostic);
+    }
+    catch {
+        return String(diagnostic);
+    }
+}
+/**
+ * Build a {@link ContractError} for a known contract code, or `null` if the code
+ * is not in the registry.
+ */
+export function contractErrorFromCode(code, context) {
+    const info = CONTRACT_ERROR_REGISTRY[code];
+    if (!info)
+        return null;
+    return new ContractError(info.code, info.name, info.family, info.message, {
+        context,
+    });
+}
+/**
+ * Decode a simulation/submission diagnostic into a typed {@link ContractError}.
+ *
+ * Scans the (stringified) diagnostic for an `Error(Contract, #N)` marker and
+ * looks the code up in {@link CONTRACT_ERROR_REGISTRY}. Returns `null` when no
+ * contract code is present or the code is unknown, letting callers fall back to
+ * a generic {@link SimulationError}/{@link SubmissionError}.
+ */
+export function decodeContractError(diagnostic) {
+    const text = diagnosticToString(diagnostic);
+    const match = text.match(CONTRACT_ERROR_PATTERN);
+    if (!match)
+        return null;
+    const code = Number.parseInt(match[1], 10);
+    return contractErrorFromCode(code, { diagnostic: text });
+}
+/**
+ * Build a {@link TransactionFailure} from an already-typed error.
+ */
+export function failedTransaction(error, hash) {
+    return {
+        success: false,
+        error,
+        ...(hash ? { hash } : {}),
+    };
+}
+/**
+ * Build a {@link TransactionFailure} from a simulation diagnostic, decoding a
+ * contract error when present and otherwise wrapping it in a
+ * {@link SimulationError}.
+ */
+export function simulationFailure(diagnostic, hash) {
+    const error = decodeContractError(diagnostic) ??
+        new SimulationError(diagnosticToString(diagnostic) || "Simulation failed");
+    return failedTransaction(error, hash);
+}
+/**
+ * Build a {@link TransactionFailure} from a submission diagnostic, decoding a
+ * contract error when present and otherwise wrapping it in a
+ * {@link SubmissionError}.
+ */
+export function submissionFailure(diagnostic, hash) {
+    const error = decodeContractError(diagnostic) ??
+        new SubmissionError(diagnosticToString(diagnostic) || "Submission failed", hash);
+    return failedTransaction(error, hash);
+}
+//# sourceMappingURL=contract-errors.js.map

package/dist/contract-errors.js.map

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