@breeztech/breez-sdk-spark 0.15.1 → 0.17.0

package/bundler/breez_sdk_spark_wasm.d.ts

@@ -128,6 +128,20 @@ export interface TokenStore {
     now: () => Promise<number>;
 }
 
+/**
+ * A passkey credential from `register` or `signIn`. `credentialId` is
+ * always set. The attestation fields (`userId`, `aaguid`,
+ * `backupEligible`) are populated on registration and null on sign-in
+ * (an assertion carries no attestation). AAGUID is unverified: a
+ * display hint only, never a trust signal.
+ */
+export interface PasskeyCredential {
+    credentialId: Uint8Array;
+    userId?: Uint8Array;
+    aaguid?: Uint8Array;
+    backupEligible?: boolean;
+}
+
 /**
  * A wallet derived from a passkey.
  */
@@ -206,78 +220,171 @@ export interface PostgresStorageConfig {
     runMigration?: boolean;
 }
 
+/**
+ * Configuration for `PasskeyClient`.
+ */
+export interface PasskeyConfig {
+    /**
+     * Wallet label for `register` / `signIn` when no label is given.
+     * Unset falls back to the internal default `\"Default\"`.
+     */
+    defaultLabel?: string;
+    /**
+     * Relying Party and user identity for the built-in provider on the
+     * zero-config path.
+     */
+    providerOptions?: PasskeyProviderOptions;
+}
+
 /**
  * Controls whether MySQL migrations create database-enforced foreign keys.
  */
 export type MysqlForeignKeyMode = "Enforced" | "Disabled";
 
 /**
- * Interface for passkey PRF (Pseudo-Random Function) operations.
- *
- * Implement this interface to provide passkey PRF functionality for seedless wallet restore.
- *
- * @example
- * ```typescript
- * class BrowserPasskeyPrfProvider implements PasskeyPrfProvider {
- *     async derivePrfSeed(salt: string): Promise<Uint8Array> {
- *         const credential = await navigator.credentials.get({
- *             publicKey: {
- *                 challenge: new Uint8Array(32),
- *                 rpId: window.location.hostname,
- *                 allowCredentials: [], // or specific credential IDs
- *                 extensions: {
- *                     prf: { eval: { first: new TextEncoder().encode(salt) } }
- *                 }
- *             }
- *         });
- *         const results = credential.getClientExtensionResults();
- *         return new Uint8Array(results.prf.results.first);
- *     }
+ * Interface for PRF (Pseudo-Random Function) operations backing seedless
+ * wallet restore.
  *
- *     async isPrfAvailable(): Promise<boolean> {
- *         return window.PublicKeyCredential?.isUserVerifyingPlatformAuthenticatorAvailable?.() ?? false;
- *     }
- * }
- * ```
+ * Implemented by the built-in `PasskeyProvider` (browser passkey via the
+ * WebAuthn PRF extension); also implementable directly for custom
+ * deterministic sources (YubiKey HMAC challenge, FIDO2 hmac-secret, on-disk
+ * key material, hardware HSMs).
  */
-export interface PasskeyPrfProvider {
+export interface PrfProvider {
     /**
-     * Derive a 32-byte seed from passkey PRF with the given salt.
+     * Derive 32-byte PRF outputs for one or more salts, in input order.
+     * Implementations with bulk capability (WebAuthn dual-salt via
+     * `prf.eval.first` + `prf.eval.second`) pack two salts per ceremony
+     * where supported; others loop the single-salt path. `options` carries
+     * per-call ceremony shapers that built-in providers forward to the OS
+     * call and custom providers may ignore.
      *
-     * The platform authenticates the user via passkey and evaluates the PRF extension.
-     * The salt is used as input to the PRF to derive a deterministic output.
-     *
-     * @param salt - The salt string to use for PRF evaluation
-     * @returns A Promise resolving to the 32-byte PRF output
-     * @throws If authentication fails or PRF is not supported
+     * @param salts - Salt strings in caller order
+     * @param options - Optional per-call overrides
+     * @returns Promise of the 32-byte outputs in input order plus the
+     *   credential ID observed in the same assertion (`null` when the
+     *   provider surfaces none, e.g. sources without an OS picker)
      */
-    derivePrfSeed(salt: string): Promise<Uint8Array>;
+    deriveSeeds(salts: string[], options?: DeriveSeedOptions): Promise<DeriveSeedsResult>;
 
     /**
-     * Check if a PRF-capable passkey is available on this device.
+     * Optional explicit registration. Platform passkey providers (browser
+     * WebAuthn, iOS / Android) implement this to drive the OS create
+     * ceremony and return credential metadata (`credentialId`, `userId`,
+     * optional `aaguid` / `backupEligible`) callers need for
+     * `excludeCredentials` bookkeeping and server-side correlation. Custom
+     * providers without a creation step can omit it.
      *
-     * This allows applications to gracefully degrade if passkey PRF is not supported.
+     * `excludeCredentials` lists already-registered IDs; a match raises
+     * `PasskeyAlreadyExistsError`.
      *
-     * @returns A Promise resolving to true if PRF-capable passkey is available
+     * @throws `PasskeyAlreadyExistsError` when an entry in
+     *   `excludeCredentials` matches a credential already on the device.
+     */
+    createPasskey?(excludeCredentials: Uint8Array[]): Promise<PasskeyCredential>;
+
+    /**
+     * Whether this provider can produce PRF outputs on the current
+     * device. Hosts gate UX on the result.
      */
-    isPrfAvailable(): Promise<boolean>;
+    isSupported(): Promise<boolean>;
 }
 
 /**
- * Nostr relay configuration for passkey label operations.
- *
- * Used by `Passkey.listLabels` and `Passkey.storeLabel`.
+ * Per-call options passed as the second argument of
+ * {@link PrfProvider.deriveSeeds}.
  */
-export interface NostrRelayConfig {
+export interface DeriveSeedOptions {
     /**
-     * Optional Breez API key for authenticated access to the Breez relay.
-     * When provided, the Breez relay is added and NIP-42 authentication is enabled.
+     * Credential IDs the assertion is restricted to, for reauthenticating
+     * a known user without an account picker. Empty or unset lets the
+     * provider's default apply.
      */
-    breezApiKey?: string;
+    allowCredentials?: Uint8Array[];
     /**
-     * Connection timeout in seconds. Defaults to 30 when `None`.
+     * Fast-fail when no local credential is available. On the web this maps
+     * to WebAuthn `mediation: 'immediate'`: `true` opts in where the browser
+     * advertises support, `false` uses the standard picker. Unset uses the
+     * provider default.
      */
-    timeoutSecs?: number;
+    preferImmediatelyAvailableCredentials?: boolean;
+}
+
+/**
+ * Returned by {@link PrfProvider.deriveSeeds}: the derived 32-byte outputs
+ * in input order plus the credential ID observed in the same assertion.
+ * `credentialId` is `null` when the provider does not surface one (custom
+ * deterministic sources without an OS picker).
+ */
+export interface DeriveSeedsResult {
+    seeds: Uint8Array[];
+    credentialId?: Uint8Array | null;
+}
+
+/**
+ * One-shot capability + configuration probe returned by
+ * `PasskeyClient.checkAvailability`. Collapses `isSupported` +
+ * `checkDomainAssociation` into one tagged value hosts branch on.
+ */
+export type PasskeyAvailability = { type: "available" } | { type: "prfUnsupported" } | { type: "notAssociated"; source: string; reason: string } | { type: "skipped"; reason: string };
+
+/**
+ * Relying Party and user identity for the built-in provider on the
+ * zero-config path (ignored when you inject your own provider).
+ */
+export interface PasskeyProviderOptions {
+    /**
+     * Relying Party ID. Unset uses the Breez shared RP.
+     */
+    rpId?: string;
+    /**
+     * Relying Party name. Unset uses the SDK default (`\"Breez\"`).
+     */
+    rpName?: string;
+    /**
+     * `user.name`: the account identifier the picker shows beneath the
+     * display name (e.g. `john@doe.com`). Unset uses `rpName`.
+     */
+    userName?: string;
+    /**
+     * `user.displayName`: the human-friendly name shown most
+     * prominently (e.g. `John Doe`). Unset uses `userName`.
+     */
+    userDisplayName?: string;
+}
+
+/**
+ * Request shape for `PasskeyClient.register`.
+ */
+export interface RegisterRequest {
+    label?: string;
+    excludeCredentials?: Uint8Array[];
+}
+
+/**
+ * Request shape for `PasskeyClient.signIn`.
+ */
+export interface SignInRequest {
+    label?: string;
+    allowCredentials?: Uint8Array[];
+    preferImmediatelyAvailableCredentials?: boolean;
+}
+
+/**
+ * Response shape for `PasskeyClient.register`.
+ */
+export interface RegisterResponse {
+    wallet: Wallet;
+    credential?: PasskeyCredential;
+}
+
+/**
+ * Response shape for `PasskeyClient.signIn`.
+ */
+export interface SignInResponse {
+    wallet: Wallet;
+    labels: string[];
+    credential?: PasskeyCredential;
 }
 
 /**
@@ -330,6 +437,10 @@ export interface AesSuccessActionDataDecrypted {
     plaintext: string;
 }
 
+export interface AuthorizeTransferRequest {
+    transfereePubkey: string;
+}
+
 export interface Bip21Details {
     amountSat?: number;
     assetId?: string;
@@ -465,6 +576,11 @@ export interface ClaimHtlcPaymentResponse {
     payment: Payment;
 }
 
+export interface ClaimTransferRequest {
+    authorization: TransferAuthorization;
+    description?: string;
+}
+
 export interface Config {
     apiKey?: string;
     network: Network;
@@ -489,6 +605,7 @@ export interface Config {
     maxConcurrentClaims: number;
     sparkConfig?: SparkConfig;
     backgroundTasksEnabled: boolean;
+    crossChainConfig?: CrossChainConfig;
 }
 
 export interface ConnectRequest {
@@ -505,10 +622,23 @@ export interface Contact {
     updatedAt: number;
 }
 
+export interface Conversion {
+    provider: ConversionProvider;
+    status: ConversionStatus;
+    from: ConversionSide;
+    to: ConversionSide;
+    amountAdjustment?: AmountAdjustmentReason;
+}
+
+export interface ConversionAsset {
+    ticker: string;
+    identifier?: string;
+    decimals: number;
+}
+
 export interface ConversionDetails {
     status: ConversionStatus;
-    from?: ConversionStep;
-    to?: ConversionStep;
+    conversions?: Conversion[];
 }
 
 export interface ConversionEstimate {
@@ -519,28 +649,17 @@ export interface ConversionEstimate {
     amountAdjustment?: AmountAdjustmentReason;
 }
 
-export interface ConversionInfo {
-    poolId: string;
-    conversionId: string;
-    status: ConversionStatus;
-    fee?: string;
-    purpose?: ConversionPurpose;
-    amountAdjustment?: AmountAdjustmentReason;
-}
-
 export interface ConversionOptions {
     conversionType: ConversionType;
     maxSlippageBps?: number;
     completionTimeoutSecs?: number;
 }
 
-export interface ConversionStep {
-    paymentId: string;
-    amount: bigint;
-    fee: bigint;
-    method: PaymentMethod;
-    tokenMetadata?: TokenMetadata;
-    amountAdjustment?: AmountAdjustmentReason;
+export interface ConversionSide {
+    chain: ConversionChain;
+    asset: ConversionAsset;
+    amount: string;
+    fee: string;
 }
 
 export interface CreateIssuerTokenRequest {
@@ -556,6 +675,30 @@ export interface Credentials {
     password: string;
 }
 
+export interface CrossChainAddressDetails {
+    address: string;
+    addressFamily: CrossChainAddressFamily;
+    contractAddress?: string;
+    chainId?: number;
+    amount?: bigint;
+}
+
+export interface CrossChainConfig {
+    defaultSlippageBps?: number;
+    defaultTargetOverpayBps?: number;
+}
+
+export interface CrossChainRoutePair {
+    provider: CrossChainProvider;
+    chain: string;
+    chainId?: string;
+    asset: string;
+    contractAddress?: string;
+    decimals: number;
+    exactOutEligible: boolean;
+    supportedSources: SourceAsset[];
+}
+
 export interface CurrencyInfo {
     name: string;
     fractionSize: number;
@@ -584,20 +727,20 @@ export interface EventListener {
     onEvent: (e: SdkEvent) => void;
 }
 
-export interface ExternalAggregateFrostRequest {
-    message: number[];
-    statechainSignatures: IdentifierSignaturePair[];
-    statechainPublicKeys: IdentifierPublicKeyPair[];
-    verifyingKey: number[];
-    statechainCommitments: IdentifierCommitmentPair[];
-    selfCommitment: ExternalSigningCommitments;
-    publicKey: number[];
-    selfSignature: ExternalFrostSignatureShare;
-    adaptorPublicKey?: number[];
+export interface ExternalBreezSigner {
+    derivePublicKey(path: string): Promise<PublicKeyBytes>;
+    signEcdsa(message: MessageBytes, path: string): Promise<EcdsaSignatureBytes>;
+    signEcdsaRecoverable(message: MessageBytes, path: string): Promise<RecoverableEcdsaSignatureBytes>;
+    encryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
+    decryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
+    signHashSchnorr(hash: Uint8Array, path: string): Promise<SchnorrSignatureBytes>;
+    hmacSha256(message: Uint8Array, path: string): Promise<HashedMessageBytes>;
 }
 
-export interface ExternalEncryptedSecret {
-    ciphertext: number[];
+export interface ExternalClaimLeafInput {
+    nodeId: ExternalTreeNodeId;
+    senderSignature: number[];
+    leafKeyCiphertext: number[];
 }
 
 export interface ExternalFrostCommitments {
@@ -606,6 +749,19 @@ export interface ExternalFrostCommitments {
     noncesCiphertext: number[];
 }
 
+export interface ExternalFrostJob {
+    derivation: ExternalFrostDerivation;
+    sighash: number[];
+    verifyingKey: number[];
+    operatorCommitments: IdentifierCommitmentPair[];
+    adaptorPublicKey?: number[];
+}
+
+export interface ExternalFrostShareResult {
+    commitment: ExternalFrostCommitments;
+    signatureShare: ExternalFrostSignatureShare;
+}
+
 export interface ExternalFrostSignature {
     bytes: number[];
 }
@@ -624,47 +780,105 @@ export interface ExternalInputParser {
     parserUrl: string;
 }
 
-export interface ExternalScalar {
-    bytes: number[];
+export interface ExternalNewLeafKey {
+    nodeId: ExternalTreeNodeId;
+    newSigningPublicKey: number[];
 }
 
-export interface ExternalSecretShare {
-    threshold: number;
-    index: ExternalScalar;
-    share: ExternalScalar;
+export interface ExternalOperatorPackage {
+    operatorIdentifier: ExternalIdentifier;
+    encryptedPackage: number[];
 }
 
-export interface ExternalSignFrostRequest {
-    message: number[];
+export interface ExternalOperatorRecipient {
+    id: number;
+    identifier: ExternalIdentifier;
     publicKey: number[];
-    secret: ExternalSecretSource;
+}
+
+export interface ExternalPrepareClaimRequest {
+    transferId: string;
+    senderIdentityPublicKey: number[];
+    leaves: ExternalClaimLeafInput[];
+    operatorRecipients: ExternalOperatorRecipient[];
+    threshold: number;
+}
+
+export interface ExternalPrepareLightningReceiveRequest {
+    operatorRecipients: ExternalOperatorRecipient[];
+    threshold: number;
+}
+
+export interface ExternalPrepareStaticDepositClaimRequest {
+    index: number;
+    userStatement: number[];
+}
+
+export interface ExternalPrepareStaticDepositRequest {
+    index: number;
+    sspPublicKey: number[];
+    frostJobs: ExternalFrostJob[];
+}
+
+export interface ExternalPrepareTokenTransactionRequest {
+    kind: ExternalTokenTransactionKind;
+    digest: number[];
+}
+
+export interface ExternalPrepareTransferRequest {
+    transferId: string;
+    receiverPublicKey: number[];
+    leaves: ExternalTransferLeafInput[];
+    operatorRecipients: ExternalOperatorRecipient[];
+    threshold: number;
+}
+
+export interface ExternalPreparedClaim {
+    operatorPackages: ExternalOperatorPackage[];
+}
+
+export interface ExternalPreparedLightningReceive {
+    paymentHash: number[];
+    operatorPreimagePackages: ExternalOperatorPackage[];
+}
+
+export interface ExternalPreparedStaticDeposit {
+    exportedSecret: number[];
+    frostShares: ExternalFrostShareResult[];
+}
+
+export interface ExternalPreparedStaticDepositClaim {
+    depositSecretKey: SecretBytes;
+    userSignature: EcdsaSignatureBytes;
+}
+
+export interface ExternalPreparedTokenTransaction {
+    signature: SchnorrSignatureBytes;
+}
+
+export interface ExternalPreparedTransfer {
+    operatorPackages: ExternalOperatorPackage[];
+    newLeafKeys: ExternalNewLeafKey[];
+    transferUserSignature: EcdsaSignatureBytes;
+}
+
+export interface ExternalSignSparkInvoiceRequest {
+    kind: ExternalSparkInvoiceKind;
+    invoiceHash: number[];
+}
+
+export interface ExternalSignStaticDepositRefundRequest {
+    index: number;
+    sighash: number[];
     verifyingKey: number[];
-    selfNonceCommitment: ExternalFrostCommitments;
+    nonceCommitment: ExternalFrostCommitments;
     statechainCommitments: IdentifierCommitmentPair[];
-    adaptorPublicKey?: number[];
+    statechainSignatures: IdentifierSignaturePair[];
+    statechainPublicKeys: IdentifierPublicKeyPair[];
 }
 
-export interface ExternalSigner {
-    identityPublicKey(): PublicKeyBytes;
-    derivePublicKey(path: string): Promise<PublicKeyBytes>;
-    signEcdsa(message: MessageBytes, path: string): Promise<EcdsaSignatureBytes>;
-    signEcdsaRecoverable(message: MessageBytes, path: string): Promise<RecoverableEcdsaSignatureBytes>;
-    encryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
-    decryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
-    signHashSchnorr(hash: Uint8Array, path: string): Promise<SchnorrSignatureBytes>;
-    generateRandomSigningCommitment(): Promise<ExternalFrostCommitments>;
-    getPublicKeyForNode(id: ExternalTreeNodeId): Promise<PublicKeyBytes>;
-    generateRandomSecret(): Promise<ExternalEncryptedSecret>;
-    staticDepositSecretEncrypted(index: number): Promise<ExternalSecretSource>;
-    staticDepositSecret(index: number): Promise<SecretBytes>;
-    staticDepositSigningKey(index: number): Promise<PublicKeyBytes>;
-    subtractSecrets(signingKey: ExternalSecretSource, newSigningKey: ExternalSecretSource): Promise<ExternalSecretSource>;
-    splitSecretWithProofs(secret: ExternalSecretToSplit, threshold: number, numShares: number): Promise<ExternalVerifiableSecretShare[]>;
-    encryptPrivateKeyForReceiver(privateKey: ExternalEncryptedSecret, receiverPublicKey: PublicKeyBytes): Promise<Uint8Array>;
-    publicKeyFromSecret(privateKey: ExternalSecretSource): Promise<PublicKeyBytes>;
-    signFrost(request: ExternalSignFrostRequest): Promise<ExternalFrostSignatureShare>;
-    aggregateFrost(request: ExternalAggregateFrostRequest): Promise<ExternalFrostSignature>;
-    hmacSha256(message: Uint8Array, path: string): Promise<HashedMessageBytes>;
+export interface ExternalSignedSparkInvoice {
+    signature: SchnorrSignatureBytes;
 }
 
 export interface ExternalSigningCommitments {
@@ -672,13 +886,42 @@ export interface ExternalSigningCommitments {
     binding: number[];
 }
 
-export interface ExternalTreeNodeId {
-    id: string;
+export interface ExternalSparkSigner {
+    getIdentityPublicKey(): Promise<PublicKeyBytes>;
+    getPublicKeyForLeaf(leafId: ExternalTreeNodeId): Promise<PublicKeyBytes>;
+    getStaticDepositPublicKey(index: number): Promise<PublicKeyBytes>;
+    signAuthenticationChallenge(challenge: Uint8Array): Promise<EcdsaSignatureBytes>;
+    signMessage(message: Uint8Array): Promise<EcdsaSignatureBytes>;
+    signFrost(jobs: ExternalFrostJob[]): Promise<ExternalFrostShareResult[]>;
+    prepareTransfer(request: ExternalPrepareTransferRequest): Promise<ExternalPreparedTransfer>;
+    prepareClaim(request: ExternalPrepareClaimRequest): Promise<ExternalPreparedClaim>;
+    prepareLightningReceive(request: ExternalPrepareLightningReceiveRequest): Promise<ExternalPreparedLightningReceive>;
+    prepareStaticDeposit(request: ExternalPrepareStaticDepositRequest): Promise<ExternalPreparedStaticDeposit>;
+    startStaticDepositRefund(request: ExternalStartStaticDepositRefundRequest): Promise<ExternalStartedStaticDepositRefund>;
+    signStaticDepositRefund(request: ExternalSignStaticDepositRefundRequest): Promise<ExternalFrostSignature>;
+    signSparkInvoice(request: ExternalSignSparkInvoiceRequest): Promise<ExternalSignedSparkInvoice>;
+    prepareTokenTransaction(request: ExternalPrepareTokenTransactionRequest): Promise<ExternalPreparedTokenTransaction>;
+    prepareStaticDepositClaim(request: ExternalPrepareStaticDepositClaimRequest): Promise<ExternalPreparedStaticDepositClaim>;
+}
+
+export interface ExternalStartStaticDepositRefundRequest {
+    index: number;
+    userStatement: number[];
 }
 
-export interface ExternalVerifiableSecretShare {
-    secretShare: ExternalSecretShare;
-    proofs: number[][];
+export interface ExternalStartedStaticDepositRefund {
+    signingPublicKey: number[];
+    nonceCommitment: ExternalFrostCommitments;
+    userSignature: EcdsaSignatureBytes;
+}
+
+export interface ExternalTransferLeafInput {
+    nodeId: ExternalTreeNodeId;
+    newLeafId: ExternalTreeNodeId;
+}
+
+export interface ExternalTreeNodeId {
+    id: string;
 }
 
 export interface FetchConversionLimitsRequest {
@@ -760,12 +1003,6 @@ export interface IncomingChange {
     oldState?: Record;
 }
 
-export interface KeySetConfig {
-    keySetType: KeySetType;
-    useAddressIndex: boolean;
-    accountNumber?: number;
-}
-
 export interface LeafOptimizationConfig {
     autoEnabled: boolean;
     multiplicity: number;
@@ -927,10 +1164,12 @@ export interface MintIssuerTokenRequest {
     amount: bigint;
 }
 
-export interface OptimizationProgress {
-    isRunning: boolean;
-    currentRound: number;
-    totalRounds: number;
+export interface OptimizeLeavesRequest {
+    mode: OptimizationMode;
+}
+
+export interface OptimizeLeavesResponse {
+    outcome: OptimizationOutcome;
 }
 
 export interface OutgoingChange {
@@ -950,6 +1189,11 @@ export interface Payment {
     conversionDetails?: ConversionDetails;
 }
 
+export interface PaymentIdUpdate {
+    provisionalPaymentId: string;
+    finalPaymentId: string;
+}
+
 export interface PaymentMetadata {
     parentPaymentId?: string;
     lnurlPayInfo?: LnurlPayInfo;
@@ -961,6 +1205,7 @@ export interface PaymentMetadata {
 
 export interface PaymentObserver {
     beforeSend: (payments: ProvisionalPayment[]) => Promise<void>;
+    afterSend: (updates: PaymentIdUpdate[]) => Promise<void>;
 }
 
 export interface PaymentRequestSource {
@@ -990,7 +1235,7 @@ export interface PrepareLnurlPayResponse {
 }
 
 export interface PrepareSendPaymentRequest {
-    paymentRequest: string;
+    paymentRequest: PaymentRequest;
     amount?: bigint;
     tokenIdentifier?: string;
     conversionOptions?: ConversionOptions;
@@ -1134,7 +1379,7 @@ export interface Session {
     expiration: number;
 }
 
-export interface SessionManager {
+export interface SessionStore {
     getSession: (serviceIdentityKey: string) => Promise<Session>;
     setSession: (serviceIdentityKey: string, session: Session) => Promise<void>;
 }
@@ -1211,6 +1456,7 @@ export interface SparkSigningOperator {
     identifier: string;
     address: string;
     identityPublicKey: string;
+    caCertPem?: string;
 }
 
 export interface SparkSspConfig {
@@ -1241,7 +1487,15 @@ export interface Storage {
     setCachedItem: (key: string, value: string) => Promise<void>;
     deleteCachedItem: (key: string) => Promise<void>;
     listPayments: (request: StorageListPaymentsRequest) => Promise<Payment[]>;
-    insertPayment: (payment: Payment) => Promise<void>;
+    /**
+     * Insert or update a payment, applying a terminal-status guard.
+     *
+     * Returns `true` when the caller should emit a payment event (the row was
+     * newly inserted, or its status transitioned). Returns `false` for
+     * redundant same-status updates and for rejected updates that would
+     * replace an already-terminal status.
+     */
+    applyPaymentUpdate: (payment: Payment) => Promise<boolean>;
     insertPaymentMetadata: (paymentId: string, metadata: PaymentMetadata) => Promise<void>;
     getPaymentById: (id: string) => Promise<Payment>;
     getPaymentByInvoice: (invoice: string) => Promise<Payment>;
@@ -1255,6 +1509,9 @@ export interface Storage {
     getContact: (id: string) => Promise<Contact>;
     insertContact: (contact: Contact) => Promise<void>;
     deleteContact: (id: string) => Promise<void>;
+    setCrossChainSwap: (swap: StoredCrossChainSwap) => Promise<void>;
+    getCrossChainSwap: (provider: string, id: string) => Promise<StoredCrossChainSwap | null>;
+    listActiveCrossChainSwaps: (provider: string) => Promise<StoredCrossChainSwap[]>;
     syncAddOutgoingChange: (record: UnversionedRecordChange) => Promise<number>;
     syncCompleteOutgoingSync: (record: Record) => Promise<void>;
     syncGetPendingOutgoingChanges: (limit: number) => Promise<OutgoingChange[]>;
@@ -1278,6 +1535,15 @@ export interface StorageListPaymentsRequest {
     sortAscending?: boolean;
 }
 
+export interface StoredCrossChainSwap {
+    provider: string;
+    id: string;
+    isTerminal: boolean;
+    updatedAt: number;
+    data: string;
+    secrets: string;
+}
+
 export interface Symbol {
     grapheme?: string;
     template?: string;
@@ -1310,6 +1576,31 @@ export interface TokenOptimizationConfig {
     minOutputsThreshold: number;
 }
 
+export interface TransferAuthorization {
+    username: string;
+    pubkey: string;
+    signature: string;
+}
+
+export interface TurnkeyConfig {
+    baseUrl?: string;
+    organizationId: string;
+    apiPublicKey: string;
+    apiPrivateKey: string;
+    walletId: string;
+    network: Network;
+    accountNumber?: number;
+    retry?: TurnkeyRetryConfig;
+}
+
+export interface TurnkeyRetryConfig {
+    initialDelayMs: number;
+    multiplier: number;
+    maxDelayMs: number;
+    maxRetries: number;
+    requestTimeoutMs: number;
+}
+
 export interface TxStatus {
     confirmed: boolean;
     blockHeight?: number;
@@ -1378,31 +1669,51 @@ export type AmountAdjustmentReason = "flooredToMinLimit" | "increasedToAvoidDust
 
 export type AssetFilter = { type: "bitcoin" } | { type: "token"; tokenIdentifier?: string };
 
+export type AutoOptimizationEvent = { type: "started"; totalRounds: number } | { type: "roundCompleted"; currentRound: number; totalRounds: number } | { type: "completed" } | { type: "cancelled" } | { type: "failed"; error: string } | { type: "skipped" };
+
 export type BitcoinNetwork = "bitcoin" | "testnet3" | "testnet4" | "signet" | "regtest";
 
 export type BuyBitcoinRequest = { type: "moonpay"; lockedAmountSat?: number; redirectUrl?: string } | { type: "cashApp"; amountSats: number };
 
 export type ChainApiType = "esplora" | "mempoolSpace";
 
+export type ConversionChain = { type: "spark" } | { type: "lightning" } | { type: "external"; name: string; chainId?: string };
+
+export type ConversionFilter = "ammRefundNeeded" | "orchestraPending" | "boltzPending";
+
+export type ConversionInfo = { type: "amm"; poolId: string; conversionId: string; status: ConversionStatus; fee?: string; purpose?: ConversionPurpose; amountAdjustment?: AmountAdjustmentReason } | { type: "orchestra"; chain: string; chainId?: string; asset?: string; assetContract?: string; recipientAddress: string; assetAmountIn?: string; estimatedOut: string; deliveredAmount?: string; status: ConversionStatus; feeAmount?: string; serviceFeeAmount?: string; serviceFeeAsset?: string; assetDecimals: number; orderId: string; quoteId: string; readToken?: string } | { type: "boltz"; chain: string; chainId?: string; asset?: string; assetContract?: string; recipientAddress: string; assetAmountIn?: string; estimatedOut: string; deliveredAmount?: string; status: ConversionStatus; feeAmount?: string; serviceFeeAmount?: string; serviceFeeAsset?: string; assetDecimals: number; swapId: string; invoice: string; invoiceAmountSats: number; bridgeRef?: string; maxSlippageBps: number; quoteDegraded?: boolean };
+
+export type ConversionProvider = "amm" | "orchestra" | "boltz";
+
 export type ConversionPurpose = { type: "ongoingPayment"; paymentRequest: string } | { type: "selfTransfer" } | { type: "autoConversion" };
 
 export type ConversionStatus = "pending" | "completed" | "failed" | "refundNeeded" | "refunded";
 
 export type ConversionType = { type: "fromBitcoin" } | { type: "toBitcoin"; fromTokenIdentifier: string };
 
+export type CrossChainAddressFamily = "evm" | "solana" | "tron";
+
+export type CrossChainFeeMode = "feesExcluded" | "feesIncluded";
+
+export type CrossChainProvider = "orchestra" | "boltz";
+
+export type CrossChainProviderContext = { type: "orchestra"; quoteId: string; depositAddress: string; depositAmount?: string } | { type: "boltz"; swapId: string; invoice: string; invoiceAmountSats?: number; maxSlippageBps: number };
+
+export type CrossChainRouteFilter = { type: "send"; addressDetails: CrossChainAddressDetails } | { type: "receive"; contractAddress?: string };
+
 export type DepositClaimError = { type: "maxDepositClaimFeeExceeded"; tx: string; vout: number; maxFee?: Fee; requiredFeeSats: number; requiredFeeRateSatPerVbyte: number } | { type: "missingUtxo"; tx: string; vout: number } | { type: "generic"; message: string };
 
-export type ExternalSecretSource = { type: "derived"; nodeId: ExternalTreeNodeId } | { type: "encrypted"; key: ExternalEncryptedSecret };
+export type ExternalFrostDerivation = { type: "signingLeaf"; leafId: ExternalTreeNodeId } | { type: "staticDeposit"; index: number } | { type: "htlcPreimage" } | { type: "identity" };
 
-export type ExternalSecretToSplit = { type: "secretSource"; source: ExternalSecretSource } | { type: "preimage"; data: number[] };
+export type ExternalSparkInvoiceKind = "sats" | "tokens";
+
+export type ExternalTokenTransactionKind = "freeze" | "partial" | "final";
 
 export type Fee = { type: "fixed"; amount: number } | { type: "rate"; satPerVbyte: number };
 
 export type FeePolicy = "feesExcluded" | "feesIncluded";
 
-export type InputType = ({ type: "bitcoinAddress" } & BitcoinAddressDetails) | ({ type: "bolt11Invoice" } & Bolt11InvoiceDetails) | ({ type: "bolt12Invoice" } & Bolt12InvoiceDetails) | ({ type: "bolt12Offer" } & Bolt12OfferDetails) | ({ type: "lightningAddress" } & LightningAddressDetails) | ({ type: "lnurlPay" } & LnurlPayRequestDetails) | ({ type: "silentPaymentAddress" } & SilentPaymentAddressDetails) | ({ type: "lnurlAuth" } & LnurlAuthRequestDetails) | ({ type: "url" } & string) | ({ type: "bip21" } & Bip21Details) | ({ type: "bolt12InvoiceRequest" } & Bolt12InvoiceRequestDetails) | ({ type: "lnurlWithdraw" } & LnurlWithdrawRequestDetails) | ({ type: "sparkAddress" } & SparkAddressDetails) | ({ type: "sparkInvoice" } & SparkInvoiceDetails);
-
-export type KeySetType = "default" | "taproot" | "nativeSegwit" | "wrappedSegwit" | "legacy";
+export type InputType = ({ type: "bitcoinAddress" } & BitcoinAddressDetails) | ({ type: "bolt11Invoice" } & Bolt11InvoiceDetails) | ({ type: "bolt12Invoice" } & Bolt12InvoiceDetails) | ({ type: "bolt12Offer" } & Bolt12OfferDetails) | ({ type: "lightningAddress" } & LightningAddressDetails) | ({ type: "lnurlPay" } & LnurlPayRequestDetails) | ({ type: "silentPaymentAddress" } & SilentPaymentAddressDetails) | ({ type: "lnurlAuth" } & LnurlAuthRequestDetails) | ({ type: "url" } & string) | ({ type: "bip21" } & Bip21Details) | ({ type: "bolt12InvoiceRequest" } & Bolt12InvoiceRequestDetails) | ({ type: "lnurlWithdraw" } & LnurlWithdrawRequestDetails) | ({ type: "sparkAddress" } & SparkAddressDetails) | ({ type: "sparkInvoice" } & SparkInvoiceDetails) | ({ type: "crossChainAddress" } & CrossChainAddressDetails);
 
 export type LnurlCallbackStatus = { type: "ok" } | { type: "errorStatus"; errorDetails: LnurlErrorDetails };
 
@@ -1412,14 +1723,18 @@ export type Network = "mainnet" | "regtest";
 
 export type OnchainConfirmationSpeed = "fast" | "medium" | "slow";
 
-export type OptimizationEvent = { type: "started"; totalRounds: number } | { type: "roundCompleted"; currentRound: number; totalRounds: number } | { type: "completed" } | { type: "cancelled" } | { type: "failed"; error: string } | { type: "skipped" };
+export type OptimizationMode = "full" | "singleRound";
 
-export type PaymentDetails = { type: "spark"; invoiceDetails?: SparkInvoicePaymentDetails; htlcDetails?: SparkHtlcDetails; conversionInfo?: ConversionInfo } | { type: "token"; metadata: TokenMetadata; txHash: string; txType: TokenTransactionType; invoiceDetails?: SparkInvoicePaymentDetails; conversionInfo?: ConversionInfo } | { type: "lightning"; description?: string; invoice: string; destinationPubkey: string; htlcDetails: SparkHtlcDetails; lnurlPayInfo?: LnurlPayInfo; lnurlWithdrawInfo?: LnurlWithdrawInfo; lnurlReceiveMetadata?: LnurlReceiveMetadata } | { type: "withdraw"; txId: string } | { type: "deposit"; txId: string };
+export type OptimizationOutcome = { type: "completed"; roundsExecuted: number } | { type: "inProgress" };
+
+export type PaymentDetails = { type: "spark"; invoiceDetails?: SparkInvoicePaymentDetails; htlcDetails?: SparkHtlcDetails; conversionInfo?: ConversionInfo } | { type: "token"; metadata: TokenMetadata; txHash: string; txType: TokenTransactionType; invoiceDetails?: SparkInvoicePaymentDetails; conversionInfo?: ConversionInfo } | { type: "lightning"; description?: string; invoice: string; destinationPubkey: string; htlcDetails: SparkHtlcDetails; lnurlPayInfo?: LnurlPayInfo; lnurlWithdrawInfo?: LnurlWithdrawInfo; lnurlReceiveMetadata?: LnurlReceiveMetadata; conversionInfo?: ConversionInfo } | { type: "withdraw"; txId: string } | { type: "deposit"; txId: string; vout: number };
 
 export type PaymentDetailsFilter = { type: "spark"; htlcStatus?: SparkHtlcStatus[]; conversionRefundNeeded?: boolean } | { type: "token"; conversionRefundNeeded?: boolean; txHash?: string; txType?: TokenTransactionType } | { type: "lightning"; htlcStatus?: SparkHtlcStatus[] };
 
 export type PaymentMethod = "lightning" | "spark" | "token" | "deposit" | "withdraw" | "unknown";
 
+export type PaymentRequest = { type: "input"; input: string } | { type: "crossChain"; address: string; route: CrossChainRoutePair; maxSlippageBps?: number; targetOverpayBps?: number };
+
 export type PaymentStatus = "completed" | "pending" | "failed";
 
 export type PaymentType = "send" | "receive";
@@ -1428,23 +1743,25 @@ export type ProvisionalPaymentDetails = { type: "bitcoin"; withdrawalAddress: st
 
 export type ReceivePaymentMethod = { type: "sparkAddress" } | { type: "sparkInvoice"; amount?: string; tokenIdentifier?: string; expiryTime?: number; description?: string; senderPublicKey?: string } | { type: "bitcoinAddress"; newAddress?: boolean } | { type: "bolt11Invoice"; description: string; amountSats?: number; expirySecs?: number; paymentHash?: string };
 
-export type SdkEvent = { type: "synced" } | { type: "unclaimedDeposits"; unclaimedDeposits: DepositInfo[] } | { type: "claimedDeposits"; claimedDeposits: DepositInfo[] } | { type: "paymentSucceeded"; payment: Payment } | { type: "paymentPending"; payment: Payment } | { type: "paymentFailed"; payment: Payment } | { type: "optimization"; optimizationEvent: OptimizationEvent } | { type: "lightningAddressChanged"; lightningAddress?: LightningAddressInfo } | { type: "newDeposits"; newDeposits: DepositInfo[] };
+export type SdkEvent = { type: "synced" } | { type: "unclaimedDeposits"; unclaimedDeposits: DepositInfo[] } | { type: "claimedDeposits"; claimedDeposits: DepositInfo[] } | { type: "paymentSucceeded"; payment: Payment } | { type: "paymentPending"; payment: Payment } | { type: "paymentFailed"; payment: Payment } | { type: "autoOptimization"; optimizationEvent: AutoOptimizationEvent } | { type: "lightningAddressChanged"; lightningAddress?: LightningAddressInfo } | { type: "newDeposits"; newDeposits: DepositInfo[] };
 
 export type Seed = { type: "mnemonic"; mnemonic: string; passphrase?: string } | ({ type: "entropy" } & number[]);
 
-export type SendPaymentMethod = { type: "bitcoinAddress"; address: BitcoinAddressDetails; feeQuote: SendOnchainFeeQuote } | { type: "bolt11Invoice"; invoiceDetails: Bolt11InvoiceDetails; sparkTransferFeeSats?: number; lightningFeeSats: number } | { type: "sparkAddress"; address: string; fee: string; tokenIdentifier?: string } | { type: "sparkInvoice"; sparkInvoiceDetails: SparkInvoiceDetails; fee: string; tokenIdentifier?: string };
+export type SendPaymentMethod = { type: "bitcoinAddress"; address: BitcoinAddressDetails; feeQuote: SendOnchainFeeQuote } | { type: "bolt11Invoice"; invoiceDetails: Bolt11InvoiceDetails; sparkTransferFeeSats?: number; lightningFeeSats: number } | { type: "sparkAddress"; address: string; fee: string; tokenIdentifier?: string } | { type: "sparkInvoice"; sparkInvoiceDetails: SparkInvoiceDetails; fee: string; tokenIdentifier?: string } | { type: "crossChainAddress"; route: CrossChainRoutePair; recipientAddress: string; amountIn: string; assetAmountIn: string; estimatedOut: string; feeAmount: string; serviceFeeAmount: string; serviceFeeAsset?: string; sourceTransferFeeSats: number; feeMode: CrossChainFeeMode; expiresAt: string; providerContext: CrossChainProviderContext };
 
 export type SendPaymentOptions = { type: "bitcoinAddress"; confirmationSpeed: OnchainConfirmationSpeed } | { type: "bolt11Invoice"; preferSpark: boolean; completionTimeoutSecs?: number } | { type: "sparkAddress"; htlcOptions?: SparkHtlcOptions };
 
 export type ServiceStatus = "operational" | "degraded" | "partial" | "unknown" | "major";
 
-export type SessionManagerError = { type: "notFound" } | ({ type: "generic" } & string);
+export type SessionStoreError = { type: "notFound" } | ({ type: "generic" } & string);
+
+export type SourceAsset = { type: "bitcoin" } | { type: "token"; tokenIdentifier: string };
 
 export type SparkHtlcStatus = "waitingForPreimage" | "preimageShared" | "returned";
 
 export type StableBalanceActiveLabel = { type: "set"; label: string } | { type: "unset" };
 
-export type StoragePaymentDetailsFilter = { type: "spark"; htlcStatus?: SparkHtlcStatus[]; conversionRefundNeeded?: boolean } | { type: "token"; conversionRefundNeeded?: boolean; txHash?: string; txType?: TokenTransactionType } | { type: "lightning"; htlcStatus?: SparkHtlcStatus[] };
+export type StoragePaymentDetailsFilter = { type: "spark"; htlcStatus?: SparkHtlcStatus[]; conversionFilter?: ConversionFilter } | { type: "token"; conversionFilter?: ConversionFilter; txHash?: string; txType?: TokenTransactionType } | { type: "lightning"; htlcStatus?: SparkHtlcStatus[]; conversionFilter?: ConversionFilter };
 
 export type SuccessAction = { type: "aes"; data: AesSuccessActionData } | { type: "message"; data: MessageSuccessActionData } | { type: "url"; data: UrlSuccessActionData };
 
@@ -1482,18 +1799,19 @@ export class BreezSdk {
     [Symbol.dispose](): void;
     addContact(request: AddContactRequest): Promise<Contact>;
     addEventListener(listener: EventListener): Promise<string>;
+    authorizeLightningAddressTransfer(request: AuthorizeTransferRequest): Promise<TransferAuthorization>;
     buyBitcoin(request: BuyBitcoinRequest): Promise<BuyBitcoinResponse>;
-    cancelLeafOptimization(): Promise<void>;
     checkLightningAddressAvailable(request: CheckLightningAddressRequest): Promise<boolean>;
     checkMessage(request: CheckMessageRequest): Promise<CheckMessageResponse>;
     claimDeposit(request: ClaimDepositRequest): Promise<ClaimDepositResponse>;
     claimHtlcPayment(request: ClaimHtlcPaymentRequest): Promise<ClaimHtlcPaymentResponse>;
+    claimLightningAddressTransfer(request: ClaimTransferRequest): Promise<LightningAddressInfo>;
     deleteContact(id: string): Promise<void>;
     deleteLightningAddress(): Promise<void>;
     disconnect(): Promise<void>;
     fetchConversionLimits(request: FetchConversionLimitsRequest): Promise<FetchConversionLimitsResponse>;
+    getCrossChainRoutes(filter: CrossChainRouteFilter): Promise<CrossChainRoutePair[]>;
     getInfo(request: GetInfoRequest): Promise<GetInfoResponse>;
-    getLeafOptimizationProgress(): OptimizationProgress;
     getLightningAddress(): Promise<LightningAddressInfo | undefined>;
     getPayment(request: GetPaymentRequest): Promise<GetPaymentResponse>;
     getTokenIssuer(): TokenIssuer;
@@ -1508,6 +1826,7 @@ export class BreezSdk {
     lnurlAuth(request_data: LnurlAuthRequestDetails): Promise<LnurlCallbackStatus>;
     lnurlPay(request: LnurlPayRequest): Promise<LnurlPayResponse>;
     lnurlWithdraw(request: LnurlWithdrawRequest): Promise<LnurlWithdrawResponse>;
+    optimizeLeaves(request: OptimizeLeavesRequest): Promise<OptimizeLeavesResponse>;
     parse(input: string): Promise<InputType>;
     prepareLnurlPay(request: PrepareLnurlPayRequest): Promise<PrepareLnurlPayResponse>;
     prepareSendPayment(request: PrepareSendPaymentRequest): Promise<PrepareSendPaymentResponse>;
@@ -1520,7 +1839,6 @@ export class BreezSdk {
     removeEventListener(id: string): Promise<boolean>;
     sendPayment(request: SendPaymentRequest): Promise<SendPaymentResponse>;
     signMessage(request: SignMessageRequest): Promise<SignMessageResponse>;
-    startLeafOptimization(): Promise<void>;
     syncWallet(request: SyncWalletRequest): Promise<SyncWalletResponse>;
     unregisterWebhook(request: UnregisterWebhookRequest): Promise<void>;
     updateContact(request: UpdateContactRequest): Promise<Contact>;
@@ -1528,33 +1846,71 @@ export class BreezSdk {
 }
 
 /**
- * A default signer implementation that wraps the core SDK's ExternalSigner.
- * This is returned by `defaultExternalSigner` and can be passed to `connectWithSigner`.
+ * A Rust-backed [`ExternalBreezSigner`] surfaced to JS as a signer object that
+ * can be passed to `connectWithSigner` or `SdkBuilder.newWithSigner`. Produced
+ * by `defaultExternalSigners` (seed) and `createTurnkeySigner` (Turnkey).
+ *
+ * [`ExternalBreezSigner`]: breez_sdk_spark::signer::ExternalBreezSigner
  */
-export class DefaultSigner {
+export class ExternalBreezSignerHandle {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    aggregateFrost(request: ExternalAggregateFrostRequest): Promise<ExternalFrostSignature>;
     decryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
     derivePublicKey(path: string): Promise<PublicKeyBytes>;
     encryptEcies(message: Uint8Array, path: string): Promise<Uint8Array>;
-    encryptPrivateKeyForReceiver(private_key: ExternalEncryptedSecret, receiver_public_key: PublicKeyBytes): Promise<Uint8Array>;
-    generateRandomSecret(): Promise<ExternalEncryptedSecret>;
-    generateRandomSigningCommitment(): Promise<ExternalFrostCommitments>;
-    getPublicKeyForNode(id: ExternalTreeNodeId): Promise<PublicKeyBytes>;
     hmacSha256(message: Uint8Array, path: string): Promise<HashedMessageBytes>;
-    identityPublicKey(): PublicKeyBytes;
-    publicKeyFromSecret(private_key: ExternalSecretSource): Promise<PublicKeyBytes>;
     signEcdsa(message: MessageBytes, path: string): Promise<EcdsaSignatureBytes>;
     signEcdsaRecoverable(message: MessageBytes, path: string): Promise<RecoverableEcdsaSignatureBytes>;
-    signFrost(request: ExternalSignFrostRequest): Promise<ExternalFrostSignatureShare>;
     signHashSchnorr(hash: Uint8Array, path: string): Promise<SchnorrSignatureBytes>;
-    splitSecretWithProofs(secret: ExternalSecretToSplit, threshold: number, num_shares: number): Promise<ExternalVerifiableSecretShare[]>;
-    staticDepositSecret(index: number): Promise<SecretBytes>;
-    staticDepositSecretEncrypted(index: number): Promise<ExternalSecretSource>;
-    staticDepositSigningKey(index: number): Promise<PublicKeyBytes>;
-    subtractSecrets(signing_key: ExternalSecretSource, new_signing_key: ExternalSecretSource): Promise<ExternalSecretSource>;
+}
+
+/**
+ * The two external signers for the SDK's signer-based connect. Returned by
+ * `defaultExternalSigners` (seed) and `createTurnkeySigner` (Turnkey); pass
+ * both halves to `connectWithSigner` or `SdkBuilder.newWithSigner`.
+ */
+export class ExternalSigners {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * External signer for non-Spark SDK signing (LNURL-auth, sync, message
+     * signing, ECIES).
+     */
+    readonly breezSigner: ExternalBreezSignerHandle;
+    /**
+     * External high-level Spark signer for the Spark wallet flows.
+     */
+    readonly sparkSigner: ExternalSparkSignerHandle;
+}
+
+/**
+ * A Rust-backed [`ExternalSparkSigner`] surfaced to JS as a signer object that
+ * can be passed to `connectWithSigner` or `SdkBuilder.newWithSigner`. Produced
+ * by `defaultExternalSigners` (seed) and `createTurnkeySigner` (Turnkey).
+ *
+ * [`ExternalSparkSigner`]: breez_sdk_spark::signer::ExternalSparkSigner
+ */
+export class ExternalSparkSignerHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    getIdentityPublicKey(): Promise<PublicKeyBytes>;
+    getPublicKeyForLeaf(leaf_id: ExternalTreeNodeId): Promise<PublicKeyBytes>;
+    getStaticDepositPublicKey(index: number): Promise<PublicKeyBytes>;
+    prepareClaim(request: ExternalPrepareClaimRequest): Promise<ExternalPreparedClaim>;
+    prepareLightningReceive(request: ExternalPrepareLightningReceiveRequest): Promise<ExternalPreparedLightningReceive>;
+    prepareStaticDeposit(request: ExternalPrepareStaticDepositRequest): Promise<ExternalPreparedStaticDeposit>;
+    prepareStaticDepositClaim(request: ExternalPrepareStaticDepositClaimRequest): Promise<ExternalPreparedStaticDepositClaim>;
+    prepareTokenTransaction(request: ExternalPrepareTokenTransactionRequest): Promise<ExternalPreparedTokenTransaction>;
+    prepareTransfer(request: ExternalPrepareTransferRequest): Promise<ExternalPreparedTransfer>;
+    signAuthenticationChallenge(challenge: Uint8Array): Promise<EcdsaSignatureBytes>;
+    signFrost(jobs: ExternalFrostJob[]): Promise<ExternalFrostShareResult[]>;
+    signMessage(message: Uint8Array): Promise<EcdsaSignatureBytes>;
+    signSparkInvoice(request: ExternalSignSparkInvoiceRequest): Promise<ExternalSignedSparkInvoice>;
+    signStaticDepositRefund(request: ExternalSignStaticDepositRefundRequest): Promise<ExternalFrostSignature>;
+    startStaticDepositRefund(request: ExternalStartStaticDepositRefundRequest): Promise<ExternalStartedStaticDepositRefund>;
 }
 
 export class IntoUnderlyingByteSource {
@@ -1586,73 +1942,59 @@ export class IntoUnderlyingSource {
 }
 
 /**
- * A shareable `MySQL` connection pool. See
- * [`PostgresConnectionPool`](super::postgres_pool::PostgresConnectionPool)
- * for sharing semantics and lifecycle.
- */
-export class MysqlConnectionPool {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-}
-
-/**
- * Passkey-based wallet operations using WebAuthn PRF extension.
- *
- * Wraps a `PasskeyPrfProvider` and optional relay configuration to provide
- * wallet derivation and label management via Nostr relays.
+ * High-level orchestrator that collapses register / sign-in flows
+ * into single calls. See the matching Rust types for full semantics;
+ * the JS surface is a thin wasm-bindgen wrapper.
  */
-export class Passkey {
+export class PasskeyClient {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Derive a wallet for a given label.
-     *
-     * Uses the passkey PRF to derive a `Wallet` containing the seed and resolved label.
-     *
-     * @param label - Optional label string (defaults to "Default")
+     * One-shot capability probe (PRF support + domain association)
+     * hosts can gate UX on.
      */
-    getWallet(label?: string | null): Promise<Wallet>;
+    checkAvailability(): Promise<PasskeyAvailability>;
     /**
-     * Check if passkey PRF is available on this device.
+     * Label sub-object. List / publish labels for this passkey's identity.
      */
-    isAvailable(): Promise<boolean>;
+    labels(): PasskeyLabels;
     /**
-     * List all labels published to Nostr for this passkey's identity.
-     *
-     * Requires 1 PRF call (for Nostr identity derivation).
+     * Create a `PasskeyClient` backed by the supplied `PrfProvider` and
+     * the default Nostr-backed label store. `breezApiKey` enables
+     * authenticated (NIP-42) relay access for label storage; omit for
+     * public relays only.
      */
-    listLabels(): Promise<string[]>;
+    constructor(prf_provider: PrfProvider, breez_api_key?: string | null, config?: PasskeyConfig | null);
     /**
-     * Create a new `Passkey` instance.
-     *
-     * @param prfProvider - Platform implementation of passkey PRF operations
-     * @param relayConfig - Optional configuration for Nostr relay connections
+     * First-time setup. Drives the platform's create-passkey ceremony
+     * then derives the wallet seed in the same PRF assertion ceremony
+     * where the platform supports it.
      */
-    constructor(prf_provider: PasskeyPrfProvider, relay_config?: NostrRelayConfig | null);
+    register(request: RegisterRequest): Promise<RegisterResponse>;
     /**
-     * Publish a label to Nostr relays for this passkey's identity.
-     *
-     * Idempotent: if the label already exists, it is not published again.
-     * Requires 1 PRF call.
+     * Returning-user sign-in. With `label` set, uses the fast path
+     * (one ceremony, no Nostr round-trip). With `label` omitted,
+     * derives the default-label wallet and discovers the user's
+     * label set in the same ceremony.
      */
-    storeLabel(label: string): Promise<void>;
+    signIn(request: SignInRequest): Promise<SignInResponse>;
 }
 
 /**
- * A shareable Postgres connection pool.
- *
- * Construct via [`create_postgres_connection_pool`] and pass the same handle to multiple
- * `SdkBuilder`s via `withPostgresConnectionPool` to share connections across SDKs.
- * Per-tenant scoping is derived from each SDK's seed.
- *
- * The pool's lifecycle is controlled by the integrator: it stays alive as
- * long as any reference is held. `disconnect()` does **not** close the pool.
+ * Label sub-object surfaced from `PasskeyClient.labels()`.
  */
-export class PostgresConnectionPool {
+export class PasskeyLabels {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * List labels published for this passkey's identity.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Idempotently publish `label` for this passkey's identity.
+     */
+    store(label: string): Promise<void>;
 }
 
 export class SdkBuilder {
@@ -1661,37 +2003,21 @@ export class SdkBuilder {
     [Symbol.dispose](): void;
     build(): Promise<BreezSdk>;
     static new(config: Config, seed: Seed): SdkBuilder;
-    static newWithSigner(config: Config, signer: ExternalSigner): SdkBuilder;
+    static newWithSigner(config: Config, breez_signer: ExternalBreezSigner, spark_signer: ExternalSparkSigner): SdkBuilder;
+    withAccountNumber(account_number: number): SdkBuilder;
     withChainService(chain_service: BitcoinChainService): SdkBuilder;
     withDefaultStorage(storage_dir: string): Promise<SdkBuilder>;
     withFiatService(fiat_service: FiatService): SdkBuilder;
-    withKeySet(config: KeySetConfig): SdkBuilder;
     withLnurlClient(lnurl_client: RestClient): SdkBuilder;
     /**
-     * **Deprecated.** Call `createMysqlConnectionPool(config)` and
-     * `withMysqlConnectionPool(pool)` instead.
+     * **Deprecated.** Use `withStorageBackend(mysqlStorage(config))`.
      */
     withMysqlBackend(config: MysqlStorageConfig): SdkBuilder;
-    /**
-     * Sets a shared `MySQL` connection pool as the backend for all stores.
-     *
-     * If the same builder also receives a `WasmSdkContext` carrying a MySQL
-     * pool, `build()` returns an error — pick one source.
-     */
-    withMysqlConnectionPool(pool: MysqlConnectionPool): SdkBuilder;
     withPaymentObserver(payment_observer: PaymentObserver): SdkBuilder;
     /**
-     * **Deprecated.** Call `createPostgresConnectionPool(config)` and
-     * `withPostgresConnectionPool(pool)` instead.
+     * **Deprecated.** Use `withStorageBackend(postgresStorage(config))`.
      */
     withPostgresBackend(config: PostgresStorageConfig): SdkBuilder;
-    /**
-     * Sets a shared Postgres connection pool as the backend for all stores.
-     *
-     * If the same builder also receives a `WasmSdkContext` carrying a
-     * Postgres pool, `build()` returns an error — pick one source.
-     */
-    withPostgresConnectionPool(pool: PostgresConnectionPool): SdkBuilder;
     withRestChainService(url: string, api_type: ChainApiType, credentials?: Credentials | null): SdkBuilder;
     /**
      * Threads a shared [`WasmSdkContext`] into the builder.
@@ -1702,6 +2028,13 @@ export class SdkBuilder {
      */
     withSharedContext(context: WasmSdkContext): SdkBuilder;
     withStorage(storage: Storage): SdkBuilder;
+    /**
+     * Sets one of the SDK's built-in storage backends.
+     *
+     * Construct the [`WasmStorageConfig`] via `defaultStorage`,
+     * `postgresStorage` or `mysqlStorage`.
+     */
+    withStorageBackend(config: WasmStorageConfig): SdkBuilder;
 }
 
 export class TokenIssuer {
@@ -1730,23 +2063,38 @@ export class WasmSdkContext {
     [Symbol.dispose](): void;
 }
 
-export function connect(request: ConnectRequest): Promise<BreezSdk>;
-
-export function connectWithSigner(config: Config, signer: ExternalSigner, storage_dir: string): Promise<BreezSdk>;
-
 /**
- * Creates a shareable `MySQL` connection pool from the given config.
+ * Selects one of the SDK's built-in storage backends.
+ *
+ * Construct it via `defaultStorage`, `postgresStorage` or `mysqlStorage` and
+ * pass it to `SdkBuilder.withStorageBackend`.
  */
-export function createMysqlConnectionPool(config: MysqlStorageConfig): MysqlConnectionPool;
+export class WasmStorageConfig {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+export function connect(request: ConnectRequest): Promise<BreezSdk>;
+
+export function connectWithSigner(config: Config, breez_signer: ExternalBreezSigner, spark_signer: ExternalSparkSigner, storage_dir: string): Promise<BreezSdk>;
 
 /**
- * Creates a shareable Postgres connection pool from the given config.
+ * Builds the Turnkey-backed signers from `config`, then pass
+ * `signers.breezSigner` and `signers.sparkSigner` to `connectWithSigner`,
+ * exactly as with any other external signer.
  */
-export function createPostgresConnectionPool(config: PostgresStorageConfig): PostgresConnectionPool;
+export function createTurnkeySigner(config: TurnkeyConfig): Promise<ExternalSigners>;
 
 export function defaultConfig(network: Network): Config;
 
-export function defaultExternalSigner(mnemonic: string, passphrase: string | null | undefined, network: Network, key_set_config?: KeySetConfig | null): DefaultSigner;
+/**
+ * Creates the default external signers from a mnemonic phrase.
+ *
+ * Key derivation matches the seed-based connect path: an SDK built either
+ * way from the same mnemonic is the same wallet.
+ */
+export function defaultExternalSigners(mnemonic: string, passphrase: string | null | undefined, network: Network, account_number?: number | null): ExternalSigners;
 
 /**
  * Creates a default MySQL storage configuration with sensible defaults.
@@ -1772,14 +2120,20 @@ export function defaultPostgresStorageConfig(connection_string: string): Postgre
 export function defaultServerConfig(network: Network): Config;
 
 /**
- * Creates a default external signer from a mnemonic phrase.
- *
- * This creates a signer that can be used with `connectWithSigner` or `SdkBuilder.newWithSigner`.
+ * File-based storage rooted at `storageDir` — IndexedDB in the browser,
+ * SQLite under Node.js.
  */
+export function defaultStorage(storage_dir: string): WasmStorageConfig;
+
 export function getSparkStatus(): Promise<SparkStatus>;
 
 export function initLogging(logger: Logger, filter?: string | null): Promise<void>;
 
+/**
+ * `MySQL`-backed storage built from `config`.
+ */
+export function mysqlStorage(config: MysqlStorageConfig): WasmStorageConfig;
+
 /**
  * Constructs a shareable REST-based Bitcoin chain service.
  *
@@ -1796,6 +2150,19 @@ export function newRestChainService(url: string, network: Network, api_type: Cha
  */
 export function newSharedSdkContext(config: WasmSdkContextConfig): Promise<WasmSdkContext>;
 
+/**
+ * `PostgreSQL`-backed storage built from `config`.
+ */
+export function postgresStorage(config: PostgresStorageConfig): WasmStorageConfig;
+
+/**
+ * Runs automatically when the wasm module is instantiated. Installs the
+ * panic hook so Rust panics surface as readable `console.error` output
+ * (with the panic message + `file.rs:line`) instead of a bare
+ * `RuntimeError: unreachable`.
+ */
+export function start(): void;
+
 /**
  * Entry point invoked by JavaScript in a worker.
  */