@breeztech/breez-sdk-spark 0.18.0-dev4 → 0.19.0

package/bundler/breez_sdk_spark_wasm.d.ts

@@ -39,16 +39,24 @@ type ReserveResult =
 | { type: 'insufficientFunds' }
 | { type: 'waitForPending'; needed: number; available: number; pending: number };
 
+type LeafSelection =
+| { type: 'exact'; leaves: TreeNode[] }
+| { type: 'swapNeeded'; leaves: TreeNode[] }
+| { type: 'insufficientFunds' };
+
 export interface TreeStore {
     addLeaves: (leaves: TreeNode[]) => Promise<void>;
     getLeaves: () => Promise<Leaves>;
     getAvailableBalance: () => Promise<bigint>;
+    getVerifiedLeafKeys: () => Promise<[string, string, string][]>;
     setLeaves: (leaves: TreeNode[], missingLeaves: TreeNode[], refreshStartedAtMs: number) => Promise<void>;
     cancelReservation: (id: string, leavesToKeep: TreeNode[]) => Promise<void>;
     finalizeReservation: (id: string, newLeaves: TreeNode[] | null) => Promise<void>;
     tryReserveLeaves: (targetAmounts: TargetAmounts | null, exactOnly: boolean, purpose: string) => Promise<ReserveResult>;
     now: () => Promise<number>;
     updateReservation: (reservationId: string, reservedLeaves: TreeNode[], changeLeaves: TreeNode[]) => Promise<LeavesReservation>;
+    tryReserveLeavesByIds: (leafIds: string[], purpose: string) => Promise<LeavesReservation>;
+    trySelectLeaves: (targetAmounts: TargetAmounts | null) => Promise<LeafSelection>;
 }
 
 
@@ -123,6 +131,17 @@ export interface TokenStore {
     preferredOutputs: WasmTokenOutputWithPrevOut[] | null,
     selectionStrategy: string | null
     ) => Promise<WasmTokenOutputsReservation>;
+    selectTokenOutputs: (
+    tokenIdentifier: string,
+    target: WasmReservationTarget,
+    preferredOutputs: WasmTokenOutputWithPrevOut[] | null,
+    selectionStrategy: string | null
+    ) => Promise<WasmTokenOutputs>;
+    reserveTokenOutputsByOutpoints: (
+    tokenIdentifier: string,
+    outpoints: { prevTxHash: string; prevTxVout: number }[],
+    purpose: string
+    ) => Promise<WasmTokenOutputsReservation>;
     cancelReservation: (id: string) => Promise<void>;
     finalizeReservation: (id: string) => Promise<void>;
     now: () => Promise<number>;
@@ -536,6 +555,15 @@ export interface Bolt12OfferDetails {
     signingPubkey?: string;
 }
 
+export interface BuildUnsignedLnurlPayPackageRequest {
+    prepareResponse: PrepareLnurlPayResponse;
+}
+
+export interface BuildUnsignedTransferPackageRequest {
+    prepareResponse: PrepareSendPaymentResponse;
+    options?: BuildTransferPackageOptions;
+}
+
 export interface BurnIssuerTokenRequest {
     amount: bigint;
 }
@@ -886,6 +914,13 @@ export interface ExternalSigningCommitments {
     binding: number[];
 }
 
+export interface ExternalSigningSigner {
+    derivePublicKey(path: string): Promise<PublicKeyBytes>;
+    signEcdsa(message: MessageBytes, path: string): Promise<EcdsaSignatureBytes>;
+    signEcdsaRecoverable(message: MessageBytes, path: string): Promise<RecoverableEcdsaSignatureBytes>;
+    signHashSchnorr(hash: Uint8Array, path: string): Promise<SchnorrSignatureBytes>;
+}
+
 export interface ExternalSparkSigner {
     getIdentityPublicKey(): Promise<PublicKeyBytes>;
     getPublicKeyForLeaf(leafId: ExternalTreeNodeId): Promise<PublicKeyBytes>;
@@ -1071,6 +1106,12 @@ export interface LnurlInfo {
     bech32: string;
 }
 
+export interface LnurlPayContext {
+    payRequest: LnurlPayRequestDetails;
+    comment?: string;
+    successAction?: SuccessAction;
+}
+
 export interface LnurlPayInfo {
     lnAddress?: string;
     comment?: string;
@@ -1260,6 +1301,14 @@ export interface PublicKeyBytes {
     bytes: number[];
 }
 
+export interface PublishSignedLnurlPayPackageRequest {
+    signedPackage: SignedTransferPackage;
+}
+
+export interface PublishSignedTransferPackageRequest {
+    signedPackage: SignedTransferPackage;
+}
+
 export interface Rate {
     coin: string;
     value: number;
@@ -1401,6 +1450,11 @@ export interface SignMessageResponse {
     signature: string;
 }
 
+export interface SignedTransferPackage {
+    unsigned: UnsignedTransferPackage;
+    signature: TransferSignature;
+}
+
 export interface SilentPaymentAddressDetails {
     address: string;
     network: BitcoinNetwork;
@@ -1421,6 +1475,7 @@ export interface SparkConfig {
     sspConfig: SparkSspConfig;
     expectedWithdrawBondSats: number;
     expectedWithdrawRelativeBlockLocktime: number;
+    maxTokenTransactionInputs?: number;
 }
 
 export interface SparkHtlcDetails {
@@ -1590,7 +1645,9 @@ export interface TurnkeyConfig {
     walletId: string;
     network: Network;
     accountNumber?: number;
+    identityPublicKey?: string;
     retry?: TurnkeyRetryConfig;
+    maxRps?: number;
 }
 
 export interface TurnkeyRetryConfig {
@@ -1673,6 +1730,8 @@ export type AutoOptimizationEvent = { type: "started"; totalRounds: number } | {
 
 export type BitcoinNetwork = "bitcoin" | "testnet3" | "testnet4" | "signet" | "regtest";
 
+export type BuildTransferPackageOptions = { type: "bitcoinAddress"; confirmationSpeed: OnchainConfirmationSpeed } | { type: "bolt11Invoice"; preferSpark: boolean; completionTimeoutSecs?: number };
+
 export type BuyBitcoinRequest = { type: "moonpay"; lockedAmountSat?: number; redirectUrl?: string } | { type: "cashApp"; amountSats: number };
 
 export type ChainApiType = "esplora" | "mempoolSpace";
@@ -1741,6 +1800,10 @@ export type PaymentType = "send" | "receive";
 
 export type ProvisionalPaymentDetails = { type: "bitcoin"; withdrawalAddress: string } | { type: "lightning"; invoice: string } | { type: "spark"; payRequest: string } | { type: "token"; tokenId: string; payRequest: string };
 
+export type PublishSignedLnurlPayResponse = { type: "swapCompleted" } | { type: "paymentSent"; response: LnurlPayResponse };
+
+export type PublishSignedTransferPackageResponse = { type: "swapCompleted" } | { type: "paymentSent"; payment: Payment };
+
 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: "autoOptimization"; optimizationEvent: AutoOptimizationEvent } | { type: "lightningAddressChanged"; lightningAddress?: LightningAddressInfo } | { type: "newDeposits"; newDeposits: DepositInfo[] };
@@ -1769,6 +1832,12 @@ export type SuccessActionProcessed = { type: "aes"; result: AesSuccessActionData
 
 export type TokenTransactionType = "transfer" | "mint" | "burn";
 
+export type TransferSignature = { type: "transfer"; signed: ExternalPreparedTransfer } | { type: "token"; signed: ExternalPreparedTokenTransaction };
+
+export type TransferTarget = { type: "spark"; address: string; sparkInvoice?: string } | { type: "lightning"; bolt11: string; lnurlPay?: LnurlPayContext; feePolicy: FeePolicy; completionTimeoutSecs?: number } | { type: "coopExit"; address: string; feeQuote: SendOnchainFeeQuote; confirmationSpeed: OnchainConfirmationSpeed };
+
+export type UnsignedTransferPackage = { type: "swap"; prepareTransfer: ExternalPrepareTransferRequest; targetAmounts: number[]; amountSat: number; feeSat: number } | { type: "transfer"; prepareTransfer: ExternalPrepareTransferRequest; amountSat: number; feeSat: number; target: TransferTarget } | { type: "token"; prepareTokenTransaction: ExternalPrepareTokenTransactionRequest; tokenContext: number[]; tokenIdentifier: string; amount: string; fee: string; isSwap: boolean };
+
 export type UpdateDepositPayload = { type: "claimError"; error: DepositClaimError } | { type: "refund"; refundTxid: string; refundTx: string };
 
 export type WebhookEventType = { type: "lightningReceiveFinished" } | { type: "lightningSendFinished" } | { type: "coopExitFinished" } | { type: "staticDepositFinished" } | ({ type: "unknown" } & string);
@@ -1800,6 +1869,8 @@ export class BreezSdk {
     addContact(request: AddContactRequest): Promise<Contact>;
     addEventListener(listener: EventListener): Promise<string>;
     authorizeLightningAddressTransfer(request: AuthorizeTransferRequest): Promise<TransferAuthorization>;
+    buildUnsignedLnurlPayPackage(request: BuildUnsignedLnurlPayPackageRequest): Promise<UnsignedTransferPackage>;
+    buildUnsignedTransferPackage(request: BuildUnsignedTransferPackageRequest): Promise<UnsignedTransferPackage>;
     buyBitcoin(request: BuyBitcoinRequest): Promise<BuyBitcoinResponse>;
     checkLightningAddressAvailable(request: CheckLightningAddressRequest): Promise<boolean>;
     checkMessage(request: CheckMessageRequest): Promise<CheckMessageResponse>;
@@ -1830,6 +1901,8 @@ export class BreezSdk {
     parse(input: string): Promise<InputType>;
     prepareLnurlPay(request: PrepareLnurlPayRequest): Promise<PrepareLnurlPayResponse>;
     prepareSendPayment(request: PrepareSendPaymentRequest): Promise<PrepareSendPaymentResponse>;
+    publishSignedLnurlPayPackage(request: PublishSignedLnurlPayPackageRequest): Promise<PublishSignedLnurlPayResponse>;
+    publishSignedTransferPackage(request: PublishSignedTransferPackageRequest): Promise<PublishSignedTransferPackageResponse>;
     receivePayment(request: ReceivePaymentRequest): Promise<ReceivePaymentResponse>;
     recommendedFees(): Promise<RecommendedFees>;
     refundDeposit(request: RefundDepositRequest): Promise<RefundDepositResponse>;
@@ -1845,6 +1918,21 @@ export class BreezSdk {
     updateUserSettings(request: UpdateUserSettingsRequest): Promise<void>;
 }
 
+/**
+ * A JS handle to a backend's own session store (from `defaultSessionStore`),
+ * exposing the same `getSession` / `setSession` interface. Wrap it in a JS
+ * `SessionStore` decorator and pass that to `SdkBuilder.withSessionStore` to
+ * transform tokens while keeping the backend's persistence: for example
+ * at-rest encryption, which the SDK does not apply itself.
+ */
+export class DefaultSessionStore {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    getSession(service_identity_key: string): Promise<Session>;
+    setSession(service_identity_key: string, session: Session): Promise<void>;
+}
+
 /**
  * A Rust-backed [`ExternalBreezSigner`] surfaced to JS as a signer object that
  * can be passed to `connectWithSigner` or `SdkBuilder.newWithSigner`. Produced
@@ -1885,6 +1973,24 @@ export class ExternalSigners {
     readonly sparkSigner: ExternalSparkSignerHandle;
 }
 
+/**
+ * A Rust-backed [`ExternalSigningSigner`] surfaced to JS as a signer object
+ * that can be passed to `connectWithSigningOnlySigner` or
+ * `SdkBuilder.newWithSigningOnlySigner`. Produced by
+ * `createTurnkeySigningOnlySigner`.
+ *
+ * [`ExternalSigningSigner`]: breez_sdk_spark::signer::ExternalSigningSigner
+ */
+export class ExternalSigningSignerHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    derivePublicKey(path: string): Promise<PublicKeyBytes>;
+    signEcdsa(message: MessageBytes, path: string): Promise<EcdsaSignatureBytes>;
+    signEcdsaRecoverable(message: MessageBytes, path: string): Promise<RecoverableEcdsaSignatureBytes>;
+    signHashSchnorr(hash: Uint8Array, path: string): Promise<SchnorrSignatureBytes>;
+}
+
 /**
  * A Rust-backed [`ExternalSparkSigner`] surfaced to JS as a signer object that
  * can be passed to `connectWithSigner` or `SdkBuilder.newWithSigner`. Produced
@@ -2004,6 +2110,13 @@ export class SdkBuilder {
     build(): Promise<BreezSdk>;
     static new(config: Config, seed: Seed): SdkBuilder;
     static newWithSigner(config: Config, breez_signer: ExternalBreezSigner, spark_signer: ExternalSparkSigner): SdkBuilder;
+    /**
+     * Creates a new `SdkBuilder` with a signing-only external signer, for a
+     * signer that can't perform the SDK's local ECIES/HMAC operations. The SDK
+     * keeps session tokens in plaintext and disables the features that rely on
+     * ECIES/HMAC.
+     */
+    static newWithSigningOnlySigner(config: Config, breez_signer: ExternalSigningSigner, spark_signer: ExternalSparkSigner): SdkBuilder;
     withAccountNumber(account_number: number): SdkBuilder;
     withChainService(chain_service: BitcoinChainService): SdkBuilder;
     withDefaultStorage(storage_dir: string): Promise<SdkBuilder>;
@@ -2019,6 +2132,13 @@ export class SdkBuilder {
      */
     withPostgresBackend(config: PostgresStorageConfig): SdkBuilder;
     withRestChainService(url: string, api_type: ChainApiType, credentials?: Credentials | null): SdkBuilder;
+    /**
+     * Overrides the session store used to cache auth tokens, replacing the one
+     * the backend provides. Pass any `SessionStore`: for example one that wraps
+     * the backend's own store from `defaultSessionStore` to add at-rest
+     * encryption, which the SDK does not apply itself.
+     */
+    withSessionStore(session_store: SessionStore): SdkBuilder;
     /**
      * Threads a shared [`WasmSdkContext`] into the builder.
      *
@@ -2037,6 +2157,25 @@ export class SdkBuilder {
     withStorageBackend(config: WasmStorageConfig): SdkBuilder;
 }
 
+/**
+ * The signing-only external signers for the SDK's signer-based connect.
+ * Returned by `createTurnkeySigningOnlySigner`; pass both halves to
+ * `connectWithSigningOnlySigner` or `SdkBuilder.newWithSigningOnlySigner`.
+ */
+export class SigningOnlyExternalSigners {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Signing-only external signer for non-Spark SDK signing.
+     */
+    readonly breezSigner: ExternalSigningSignerHandle;
+    /**
+     * External high-level Spark signer for the Spark wallet flows.
+     */
+    readonly sparkSigner: ExternalSparkSignerHandle;
+}
+
 export class TokenIssuer {
     private constructor();
     free(): void;
@@ -2079,6 +2218,13 @@ export function connect(request: ConnectRequest): Promise<BreezSdk>;
 
 export function connectWithSigner(config: Config, breez_signer: ExternalBreezSigner, spark_signer: ExternalSparkSigner, storage_dir: string): Promise<BreezSdk>;
 
+/**
+ * Connects using a signing-only external signer, for a signer that can't
+ * perform the SDK's local ECIES/HMAC operations. The SDK keeps session tokens
+ * in plaintext and disables the features that rely on ECIES/HMAC.
+ */
+export function connectWithSigningOnlySigner(config: Config, breez_signer: ExternalSigningSigner, spark_signer: ExternalSparkSigner, storage_dir: string): Promise<BreezSdk>;
+
 /**
  * Builds the Turnkey-backed signers from `config`, then pass
  * `signers.breezSigner` and `signers.sparkSigner` to `connectWithSigner`,
@@ -2086,6 +2232,14 @@ export function connectWithSigner(config: Config, breez_signer: ExternalBreezSig
  */
 export function createTurnkeySigner(config: TurnkeyConfig): Promise<ExternalSigners>;
 
+/**
+ * Builds the signing-only Turnkey-backed signers from `config` (for a wallet
+ * under a deny-export policy), then pass `signers.breezSigner` and
+ * `signers.sparkSigner` to `connectWithSigningOnlySigner`. The Breez half
+ * performs signing only and never exports a key.
+ */
+export function createTurnkeySigningOnlySigner(config: TurnkeyConfig): Promise<SigningOnlyExternalSigners>;
+
 export function defaultConfig(network: Network): Config;
 
 /**
@@ -2119,6 +2273,14 @@ export function defaultPostgresStorageConfig(connection_string: string): Postgre
 
 export function defaultServerConfig(network: Network): Config;
 
+/**
+ * The session store the `config`'s backend provides for `identity` (the wallet
+ * identity public key, hex), as a handle to wrap in a `SessionStore` decorator
+ * and pass to `SdkBuilder.withSessionStore`, keeping the backend's persistence.
+ * A typical use is at-rest encryption, which the SDK does not apply itself.
+ */
+export function defaultSessionStore(config: WasmStorageConfig, network: Network, identity: string): Promise<DefaultSessionStore>;
+
 /**
  * File-based storage rooted at `storageDir` — IndexedDB in the browser,
  * SQLite under Node.js.

package/bundler/breez_sdk_spark_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./breez_sdk_spark_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    BitcoinChainServiceHandle, BreezSdk, ExternalBreezSignerHandle, ExternalSigners, ExternalSparkSignerHandle, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, PasskeyClient, PasskeyLabels, SdkBuilder, TokenIssuer, WasmSdkContext, WasmStorageConfig, connect, connectWithSigner, createTurnkeySigner, defaultConfig, defaultExternalSigners, defaultMysqlStorageConfig, defaultPostgresStorageConfig, defaultServerConfig, defaultStorage, getSparkStatus, initLogging, mysqlStorage, newRestChainService, newSharedSdkContext, postgresStorage, start, task_worker_entry_point
+    BitcoinChainServiceHandle, BreezSdk, DefaultSessionStore, ExternalBreezSignerHandle, ExternalSigners, ExternalSigningSignerHandle, ExternalSparkSignerHandle, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, PasskeyClient, PasskeyLabels, SdkBuilder, SigningOnlyExternalSigners, TokenIssuer, WasmSdkContext, WasmStorageConfig, connect, connectWithSigner, connectWithSigningOnlySigner, createTurnkeySigner, createTurnkeySigningOnlySigner, defaultConfig, defaultExternalSigners, defaultMysqlStorageConfig, defaultPostgresStorageConfig, defaultServerConfig, defaultSessionStore, defaultStorage, getSparkStatus, initLogging, mysqlStorage, newRestChainService, newSharedSdkContext, postgresStorage, start, task_worker_entry_point
 } from "./breez_sdk_spark_wasm_bg.js";