@buildonspark/spark-sdk 0.3.6 → 0.3.8

package/dist/bare/index.d.cts

@@ -3,10 +3,11 @@ import * as btc from '@scure/btc-signer';
 import { Transaction } from '@scure/btc-signer';
 import { HDKey } from '@scure/bip32';
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
-import { CallOptions, ClientMiddlewareCall, Metadata } from 'nice-grpc-common';
+import { CallOptions, ClientMiddleware, ClientMiddlewareCall, Metadata } from 'nice-grpc-common';
+import * as _scure_base from '@scure/base';
 import { Channel } from 'nice-grpc';
 import { Channel as Channel$1, createChannel } from 'nice-grpc-web';
-import * as _scure_base from '@scure/base';
+import { RetryOptions as RetryOptions$1 } from 'nice-grpc-client-middleware-retry';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { EventEmitter } from 'eventemitter3';
 import * as nice_grpc_web_lib_client_Transport_js from 'nice-grpc-web/lib/client/Transport.js';
@@ -962,7 +963,7 @@ interface GenerateDepositAddressRequest {
 }
 declare const GenerateDepositAddressRequest: MessageFns$2<GenerateDepositAddressRequest>;
 /** Address is the address of the user's public key + SE's public key. */
-interface Address {
+interface Address$1 {
     /** The p2tr address of the user's public key + SE's public key. */
     address: string;
     /** The verifying key of the address, which is user's public key + SE's public key. */
@@ -972,10 +973,10 @@ interface Address {
     /** Is it a static deposit address */
     isStatic: boolean;
 }
-declare const Address: MessageFns$2<Address>;
+declare const Address$1: MessageFns$2<Address$1>;
 /** GenerateDepositAddressResponse is the response to the request to generate a deposit address. */
 interface GenerateDepositAddressResponse {
-    depositAddress: Address | undefined;
+    depositAddress: Address$1 | undefined;
 }
 declare const GenerateDepositAddressResponse: MessageFns$2<GenerateDepositAddressResponse>;
 /** GenerateStaticDepositAddressRequest is the request to generate a static deposit address. */
@@ -990,7 +991,7 @@ interface GenerateStaticDepositAddressRequest {
 declare const GenerateStaticDepositAddressRequest: MessageFns$2<GenerateStaticDepositAddressRequest>;
 /** GenerateStaticDepositAddressResponse is the response to the request to generate a static deposit address. */
 interface GenerateStaticDepositAddressResponse {
-    depositAddress: Address | undefined;
+    depositAddress: Address$1 | undefined;
 }
 declare const GenerateStaticDepositAddressResponse: MessageFns$2<GenerateStaticDepositAddressResponse>;
 /**
@@ -1062,7 +1063,6 @@ interface SigningResult {
 declare const SigningResult: MessageFns$2<SigningResult>;
 interface RenewLeafRequest {
     leafId: string;
-    ownerIdentityPublicKey: Uint8Array;
     signingJobs?: //
     /**
      * Resets the node transaction timelock and refund transaction timelock
@@ -1128,11 +1128,11 @@ interface RenewRefundTimelockSigningJob {
 declare const RenewRefundTimelockSigningJob: MessageFns$2<RenewRefundTimelockSigningJob>;
 interface RenewLeafResponse {
     renewResult?: {
-        $case: "extendResult";
-        extendResult: RenewNodeTimelockResult;
+        $case: "renewNodeTimelockResult";
+        renewNodeTimelockResult: RenewNodeTimelockResult;
     } | {
-        $case: "refreshResult";
-        refreshResult: RenewRefundTimelockResult;
+        $case: "renewRefundTimelockResult";
+        renewRefundTimelockResult: RenewRefundTimelockResult;
     } | undefined;
 }
 declare const RenewLeafResponse: MessageFns$2<RenewLeafResponse>;
@@ -1747,15 +1747,28 @@ interface RequestedSigningCommitments {
 }
 declare const RequestedSigningCommitments: MessageFns$2<RequestedSigningCommitments>;
 interface GetSigningCommitmentsRequest {
+    /** The node IDs for which to get signing commitments. */
     nodeIds: string[];
+    /** The number of signing commitments to get per node ID. */
     count: number;
 }
 declare const GetSigningCommitmentsRequest: MessageFns$2<GetSigningCommitmentsRequest>;
 interface GetSigningCommitmentsResponse {
+    /**
+     * A list of signing commitments for each requested node ID. The signing commitments will be
+     * ordered in the same order as the requested node IDs, repeated for the number of commitments
+     * requested. For example, if node_ids = [A, B] and count = 2, the response will contain:
+     *
+     * [commitment_A1, commitment_B1, commitment_A2, commitment_B2]
+     */
     signingCommitments: RequestedSigningCommitments[];
 }
 declare const GetSigningCommitmentsResponse: MessageFns$2<GetSigningCommitmentsResponse>;
 interface SigningCommitments {
+    /**
+     * A map of signing operator ID (i.e. 000...01) to the signing commitment provided by that
+     * operator.
+     */
     signingCommitments: {
         [key: string]: SigningCommitment;
     };
@@ -1786,6 +1799,7 @@ interface InitiatePreimageSwapRequest {
     transfer: StartUserSignedTransferRequest | undefined;
     receiverIdentityPublicKey: Uint8Array;
     feeSats: number;
+    transferRequest: StartTransferRequest | undefined;
 }
 declare const InitiatePreimageSwapRequest: MessageFns$2<InitiatePreimageSwapRequest>;
 interface InitiatePreimageSwapResponse {
@@ -2290,6 +2304,10 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        /**
+         * Gets a specified number of signing commmitments for a set of nodes, which can be used as
+         * part of a transfer package.
+         */
         readonly get_signing_commitments: {
             readonly name: "get_signing_commitments";
             readonly requestType: MessageFns$2<GetSigningCommitmentsRequest>;
@@ -2677,6 +2695,10 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     claim_transfer_tweak_keys(request: DeepPartial$2<ClaimTransferTweakKeysRequest>, options?: CallOptions & CallOptionsExt): Promise<Empty>;
     claim_transfer_sign_refunds(request: DeepPartial$2<ClaimTransferSignRefundsRequest>, options?: CallOptions & CallOptionsExt): Promise<ClaimTransferSignRefundsResponse>;
     store_preimage_share(request: DeepPartial$2<StorePreimageShareRequest>, options?: CallOptions & CallOptionsExt): Promise<Empty>;
+    /**
+     * Gets a specified number of signing commmitments for a set of nodes, which can be used as
+     * part of a transfer package.
+     */
     get_signing_commitments(request: DeepPartial$2<GetSigningCommitmentsRequest>, options?: CallOptions & CallOptionsExt): Promise<GetSigningCommitmentsResponse>;
     cooperative_exit(request: DeepPartial$2<CooperativeExitRequest>, options?: CallOptions & CallOptionsExt): Promise<CooperativeExitResponse>;
     initiate_preimage_swap(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
@@ -2822,7 +2844,7 @@ interface ClaimStaticDepositOutput {
 
 interface CompleteCoopExitInput {
     userOutboundTransferExternalId: string;
-    coopExitRequestId: string;
+    coopExitRequestId?: string | undefined;
 }
 
 interface CompleteLeavesSwapInput {
@@ -2910,11 +2932,12 @@ interface LightningSendFeeEstimateOutput {
 interface RequestCoopExitInput {
     leafExternalIds: string[];
     withdrawalAddress: string;
-    idempotencyKey: string;
+    idempotencyKey?: string | undefined;
     exitSpeed: ExitSpeed;
     withdrawAll: boolean;
     feeLeafExternalIds?: string[] | undefined;
     feeQuoteId?: string | undefined;
+    userOutboundTransferExternalId?: string | undefined;
 }
 
 interface UserLeafInput {
@@ -2974,12 +2997,13 @@ interface RequestLightningReceiveInput {
 
 interface RequestLightningSendInput {
     encodedInvoice: string;
-    idempotencyKey: string;
+    idempotencyKey?: string | undefined;
     /**
- * The amount you will pay for this invoice in sats. It should ONLY be set when the invoice amount is
- * zero.
-**/
+     * The amount you will pay for this invoice in sats. It should ONLY be set when the invoice amount is
+     * zero.
+     **/
     amountSats?: number | undefined;
+    userOutboundTransferExternalId?: string | undefined;
 }
 
 interface StaticDepositQuoteInput {
@@ -3036,10 +3060,10 @@ declare class SspClient {
     getLightningSendFeeEstimate(encodedInvoice: string, amountSats?: number): Promise<LightningSendFeeEstimateOutput | null>;
     getCoopExitFeeEstimate({ leafExternalIds, withdrawalAddress, }: CoopExitFeeEstimatesInput): Promise<CoopExitFeeEstimatesOutput | null>;
     getCurrentUser(): Promise<void>;
-    completeCoopExit({ userOutboundTransferExternalId, coopExitRequestId, }: CompleteCoopExitInput): Promise<CoopExitRequest | null>;
-    requestCoopExit({ leafExternalIds, withdrawalAddress, idempotencyKey, exitSpeed, feeLeafExternalIds, feeQuoteId, withdrawAll, }: RequestCoopExitInput): Promise<CoopExitRequest | null>;
+    completeCoopExit({ userOutboundTransferExternalId, }: CompleteCoopExitInput): Promise<CoopExitRequest | null>;
+    requestCoopExit({ leafExternalIds, withdrawalAddress, exitSpeed, feeLeafExternalIds, feeQuoteId, withdrawAll, userOutboundTransferExternalId, }: RequestCoopExitInput): Promise<CoopExitRequest | null>;
     requestLightningReceive({ amountSats, network, paymentHash, expirySecs, memo, includeSparkAddress, receiverIdentityPubkey, descriptionHash, }: RequestLightningReceiveInput): Promise<LightningReceiveRequest | null>;
-    requestLightningSend({ encodedInvoice, idempotencyKey, amountSats, }: RequestLightningSendInput): Promise<LightningSendRequest | null>;
+    requestLightningSend({ encodedInvoice, amountSats, userOutboundTransferExternalId, }: RequestLightningSendInput): Promise<LightningSendRequest | null>;
     requestLeaveSwap({ adaptorPubkey, directAdaptorPubkey, directFromCpfpAdaptorPubkey, totalAmountSats, targetAmountSats, feeSats, userLeaves, idempotencyKey, targetAmountSatsList, }: RequestLeavesSwapInput): Promise<LeavesSwapRequest | null>;
     completeLeaveSwap({ adaptorSecretKey, directAdaptorSecretKey, directFromCpfpAdaptorSecretKey, userOutboundTransferExternalId, leavesSwapRequestId, }: CompleteLeavesSwapInput): Promise<LeavesSwapRequest | null>;
     getLightningReceiveRequest(id: string): Promise<LightningReceiveRequest | null>;
@@ -3467,6 +3491,174 @@ declare function getNetworkFromAddress(address: string): BitcoinNetwork.MAINNET
  */
 declare function getNetworkFromString(network?: string): Network;
 
+type Bech32mTokenIdentifier = `btkn1${string}` | `btknrt1${string}` | `btknt1${string}` | `btkns1${string}` | `btknl1${string}`;
+interface Bech32mTokenIdentifierData {
+    tokenIdentifier: Uint8Array;
+    network: NetworkType;
+}
+declare function encodeBech32mTokenIdentifier(payload: Bech32mTokenIdentifierData): Bech32mTokenIdentifier;
+declare function decodeBech32mTokenIdentifier(bech32mTokenIdentifier: Bech32mTokenIdentifier, network?: NetworkType): Bech32mTokenIdentifierData;
+declare function getNetworkFromBech32mTokenIdentifier(bech32mTokenIdentifier: Bech32mTokenIdentifier): NetworkType;
+
+declare const AddressNetwork: Record<NetworkType, string>;
+declare const LegacyAddressNetwork: Record<NetworkType, string>;
+type Bech32String = `${string}1${string}`;
+type SparkAddressFormat = `${(typeof AddressNetwork)[keyof typeof AddressNetwork]}1${string}`;
+type LegacySparkAddressFormat = `${(typeof LegacyAddressNetwork)[keyof typeof LegacyAddressNetwork]}1${string}`;
+interface SparkAddressData {
+    identityPublicKey: string;
+    network: NetworkType;
+    sparkInvoiceFields?: SparkInvoiceFields;
+}
+interface DecodedSparkAddressData {
+    identityPublicKey: string;
+    network: NetworkType;
+    sparkInvoiceFields?: {
+        version: number;
+        id: string;
+        paymentType?: {
+            type: "tokens";
+            tokenIdentifier?: string;
+            amount?: bigint;
+        } | {
+            type: "sats";
+            amount?: number;
+        };
+        memo?: string;
+        senderPublicKey?: string;
+        expiryTime?: Date;
+    };
+    signature?: string;
+}
+declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
+declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
+declare function getNetworkFromSparkAddress(address: string): NetworkType;
+declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
+declare function isValidSparkAddress(address: string): boolean;
+declare function isValidPublicKey(publicKey: string): void;
+declare function validateSparkInvoiceFields(sparkInvoiceFields: SparkInvoiceFields): void;
+declare function validateSparkInvoiceSignature(invoice: SparkAddressFormat): void;
+declare function toProtoTimestamp(date: Date): {
+    seconds: number;
+    nanos: number;
+};
+declare function assertBech32(s: string): asserts s is Bech32String;
+declare function bech32mDecode(address: string): _scure_base.Bech32Decoded<string>;
+declare function isSafeForNumber(bi: bigint): boolean;
+
+type CreateLightningInvoiceParams = {
+    amountSats: number;
+    memo?: string;
+    expirySeconds?: number;
+    includeSparkAddress?: boolean;
+    receiverIdentityPubkey?: string;
+    descriptionHash?: string;
+};
+type PayLightningInvoiceParams = {
+    invoice: string;
+    maxFeeSats: number;
+    preferSpark?: boolean;
+    amountSatsToSend?: number;
+};
+type TransferParams = {
+    amountSats: number;
+    receiverSparkAddress: string;
+};
+type FulfillSparkInvoiceResponse = {
+    satsTransactionSuccess: {
+        invoice: SparkAddressFormat;
+        transferResponse: WalletTransfer;
+    }[];
+    tokenTransactionSuccess: {
+        tokenIdentifier: Bech32mTokenIdentifier;
+        txid: string;
+    }[];
+    satsTransactionErrors: {
+        invoice: string;
+        error: Error;
+    }[];
+    tokenTransactionErrors: {
+        tokenIdentifier: Bech32mTokenIdentifier;
+        error: Error;
+    }[];
+    invalidInvoices: {
+        invoice: string;
+        error: Error;
+    }[];
+};
+/**
+ * Token metadata containing essential information about a token.
+ * This is the wallet's internal representation with JavaScript-friendly types.
+ *
+ * rawTokenIdentifier: This is the raw binary token identifier - This is used to encode the bech32m encoded token identifier.
+ *
+ * tokenPublicKey: This is the hex-encoded public key of the token issuer - Same as issuerPublicKey.
+ *
+ * @example
+ * ```typescript
+ * const tokenMetadata: UserTokenMetadata = {
+ *   rawTokenIdentifier: new Uint8Array([1, 2, 3]),
+ *   tokenPublicKey: "0348fbb...",
+ *   tokenName: "SparkToken",
+ *   tokenTicker: "SPK",
+ *   decimals: 8,
+ *   maxSupply: 1000000n
+ * };
+ * ```
+ */
+type UserTokenMetadata = {
+    /** Raw binary token identifier - This is used to encode the human readable token identifier */
+    rawTokenIdentifier: Uint8Array;
+    /** Public key of the token issuer - Same as issuerPublicKey */
+    tokenPublicKey: string;
+    /** Human-readable name of the token (e.g., SparkToken)*/
+    tokenName: string;
+    /** Short ticker symbol for the token (e.g., "SPK") */
+    tokenTicker: string;
+    /** Number of decimal places for token amounts */
+    decimals: number;
+    /** Maximum supply of tokens that can ever be minted */
+    maxSupply: bigint;
+};
+type TokenBalanceMap = Map<Bech32mTokenIdentifier, {
+    balance: bigint;
+    tokenMetadata: UserTokenMetadata;
+}>;
+type TokenOutputsMap = Map<Bech32mTokenIdentifier, OutputWithPreviousTransactionData$1[]>;
+type TokenMetadataMap = Map<Bech32mTokenIdentifier, TokenMetadata>;
+type InitWalletResponse<T extends SparkWallet = SparkWallet> = {
+    wallet: T;
+    mnemonic: string | undefined;
+};
+interface SparkWalletProps {
+    mnemonicOrSeed?: Uint8Array | string;
+    accountNumber?: number;
+    signer?: SparkSigner;
+    options?: ConfigOptions;
+}
+declare const SparkWalletEvent: {
+    readonly All: "*";
+    readonly TransferClaimed: "transfer:claimed";
+    readonly DepositConfirmed: "deposit:confirmed";
+    readonly StreamConnected: "stream:connected";
+    readonly StreamDisconnected: "stream:disconnected";
+    readonly StreamReconnecting: "stream:reconnecting";
+};
+interface SparkWalletEvents {
+    [SparkWalletEvent.All]: (eventName: string, ...args: unknown[]) => void;
+    /** Emitted when an incoming transfer is successfully claimed. Includes the transfer ID and new total balance. */
+    [SparkWalletEvent.TransferClaimed]: (transferId: string, updatedBalance: bigint) => void;
+    /** Emitted when a deposit is marked as available. Includes the deposit ID and new total balance. */
+    [SparkWalletEvent.DepositConfirmed]: (depositId: string, updatedBalance: bigint) => void;
+    /** Emitted when the stream is connected */
+    [SparkWalletEvent.StreamConnected]: () => void;
+    /** Emitted when the stream disconnects and fails to reconnect after max attempts */
+    [SparkWalletEvent.StreamDisconnected]: (reason: string) => void;
+    /** Emitted when attempting to reconnect the stream */
+    [SparkWalletEvent.StreamReconnecting]: (attempt: number, maxAttempts: number, delayMs: number, error: string) => void;
+}
+
 type SigningOperator = {
     readonly id: number;
     readonly identifier: string;
@@ -3490,13 +3682,14 @@ type ConfigOptions = MayHaveSspClientOptions & {
     readonly expectedWithdrawRelativeBlockLocktime?: number;
     readonly signerWithPreExistingKeys?: boolean;
     readonly console?: ConsoleOptions;
+    readonly events?: Partial<SparkWalletEvents>;
 };
 
 declare class WalletConfigService implements HasSspClientOptions {
     private readonly config;
     readonly signer: SparkSigner;
     readonly sspClientOptions: SspClientOptions;
-    constructor(options?: ConfigOptions, signer?: SparkSigner);
+    constructor(options: ConfigOptions | undefined, signer: SparkSigner);
     private getDefaultConfig;
     getCoordinatorAddress(): string;
     getSigningOperators(): Readonly<Record<string, SigningOperator>>;
@@ -3514,6 +3707,7 @@ declare class WalletConfigService implements HasSspClientOptions {
     getSspBaseUrl(): string;
     getSspIdentityPublicKey(): string;
     getConsoleOptions(): ConsoleOptions;
+    getEvents(): Partial<SparkWalletEvents>;
 }
 
 /** Challenge represents the core challenge data */
@@ -3618,87 +3812,55 @@ interface RetryOptions {
 }
 type SparkCallOptions = CallOptions & RetryOptions;
 
-declare class ConnectionManager {
-    private config;
-    protected clients: Map<string, {
-        client: SparkServiceClient & {
-            close?: () => void;
-        };
-        authToken: string;
+type ChannelKey = string;
+type BrowserOrNodeJSChannel = Channel | Channel$1;
+type SparkClientType = "spark" | "stream" | "tokens";
+type Address = string;
+declare abstract class ConnectionManager {
+    private static channelCache;
+    private static channelInflight;
+    private static authTokenCache;
+    private static authInflight;
+    protected makeChannelKey(address: Address, stream?: boolean): ChannelKey;
+    protected static acquireChannel<T extends BrowserOrNodeJSChannel>(key: ChannelKey, create: () => Promise<T>): Promise<T>;
+    protected static releaseChannel(key: ChannelKey): void;
+    private static makeAuthTokenKey;
+    private static getCachedAuthToken;
+    private static setCachedAuthToken;
+    private static invalidateCachedAuthToken;
+    private static getOrCreateAuthToken;
+    protected abstract createChannelWithTLS(address: Address, isStreamClientType?: boolean): Promise<Channel | Channel$1>;
+    protected abstract createGrpcClient<T>(definition: SparkAuthnServiceDefinition | SparkServiceDefinition | SparkTokenServiceDefinition, channel: Channel | Channel$1, withRetries: boolean, middleware?: ClientMiddleware<RetryOptions$1, {}>, channelKey?: ChannelKey): Promise<T & {
+        close?: () => void;
     }>;
-    private tokenClients;
-    private streamClients;
-    private authPromises;
+    private config;
+    private clientsByType;
+    private identityPublicKeyHex?;
     constructor(config: WalletConfigService);
     createClients(): Promise<void>;
     closeConnections(): Promise<void>;
-    protected createChannelWithTLS(address: string, certPath?: string): Promise<Channel | Channel$1>;
-    createSparkStreamClient(address: string, certPath?: string): Promise<SparkServiceClient & {
+    private getDefinitionForClientType;
+    protected static isStreamClientType(type: SparkClientType): type is "stream";
+    private getAddressToClientMap;
+    private getOrCreateClientInternal;
+    createSparkStreamClient(address: string): Promise<SparkServiceClient & {
         close?: () => void;
     }>;
-    createSparkClient(address: string, certPath?: string): Promise<SparkServiceClient & {
+    createSparkClient(address: string): Promise<SparkServiceClient & {
         close?: () => void;
     }>;
-    createSparkTokenClient(address: string, certPath?: string): Promise<SparkTokenServiceClient & {
+    createSparkTokenClient(address: string): Promise<SparkTokenServiceClient & {
         close?: () => void;
     }>;
-    getStreamChannel(address: string): Promise<Channel | Channel$1 | undefined>;
-    private authenticate;
+    getChannelForClient(clientType: SparkClientType, address: Address): Promise<BrowserOrNodeJSChannel | undefined>;
+    private getIdentityPublicKeyHex;
+    protected authenticate(address: string): Promise<string>;
     private createSparkAuthnGrpcConnection;
-    protected createAuthnMiddleware(): (call: ClientMiddlewareCall<any, any>, options: SparkCallOptions) => AsyncGenerator<any, any, undefined>;
-    protected createMiddleware(address: string, authToken: string): ((call: ClientMiddlewareCall<any, any>, options: SparkCallOptions) => AsyncGenerator<any, any, undefined>) | undefined;
-    protected handleMiddlewareError(error: unknown, address: string, call: ClientMiddlewareCall<any, any>, metadata: Metadata, options: SparkCallOptions): AsyncGenerator<any, any, undefined>;
-    protected createGrpcClient<T>(defintion: SparkAuthnServiceDefinition | SparkServiceDefinition | SparkTokenServiceDefinition, channel: Channel | Channel$1, withRetries: boolean, middleware?: any): Promise<T & {
-        close?: () => void;
-    }>;
-}
-
-declare const AddressNetwork: Record<NetworkType, string>;
-declare const LegacyAddressNetwork: Record<NetworkType, string>;
-type Bech32String = `${string}1${string}`;
-type SparkAddressFormat = `${(typeof AddressNetwork)[keyof typeof AddressNetwork]}1${string}`;
-type LegacySparkAddressFormat = `${(typeof LegacyAddressNetwork)[keyof typeof LegacyAddressNetwork]}1${string}`;
-interface SparkAddressData {
-    identityPublicKey: string;
-    network: NetworkType;
-    sparkInvoiceFields?: SparkInvoiceFields;
-}
-interface DecodedSparkAddressData {
-    identityPublicKey: string;
-    network: NetworkType;
-    sparkInvoiceFields?: {
-        version: number;
-        id: string;
-        paymentType?: {
-            type: "tokens";
-            tokenIdentifier?: string;
-            amount?: bigint;
-        } | {
-            type: "sats";
-            amount?: number;
-        };
-        memo?: string;
-        senderPublicKey?: string;
-        expiryTime?: Date;
-    };
-    signature?: string;
+    protected createAuthnMiddleware(): <Req, Res>(call: ClientMiddlewareCall<Req, Res>, options: SparkCallOptions) => AsyncGenerator<Res, Res | void, undefined>;
+    protected createMiddleware(address: Address): <Req, Res>(call: ClientMiddlewareCall<Req, Res>, options: SparkCallOptions) => AsyncGenerator<Res, Res | void, undefined>;
+    protected handleMiddlewareError<Req, Res>(error: unknown, address: string, call: ClientMiddlewareCall<Req, Res>, metadata: Metadata, options: SparkCallOptions): AsyncGenerator<Awaited<Res>, void | Awaited<Res>, undefined>;
+    subscribeToEvents(address: string, signal: AbortSignal): Promise<AsyncIterable<SubscribeToEventsResponse>>;
 }
-declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
-declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
-declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
-declare function getNetworkFromSparkAddress(address: string): NetworkType;
-declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
-declare function isValidSparkAddress(address: string): boolean;
-declare function isValidPublicKey(publicKey: string): void;
-declare function validateSparkInvoiceFields(sparkInvoiceFields: SparkInvoiceFields): void;
-declare function validateSparkInvoiceSignature(invoice: SparkAddressFormat): void;
-declare function toProtoTimestamp(date: Date): {
-    seconds: number;
-    nanos: number;
-};
-declare function assertBech32(s: string): asserts s is Bech32String;
-declare function bech32mDecode(address: string): _scure_base.Bech32Decoded<string>;
-declare function isSafeForNumber(bi: bigint): boolean;
 
 declare class SigningService {
     private readonly config;
@@ -3709,6 +3871,11 @@ declare class SigningService {
         directLeafSigningJobs: UserSignedTxSigningJob[];
         directFromCpfpLeafSigningJobs: UserSignedTxSigningJob[];
     }>;
+    signRefundsForLightning(leaves: LeafKeyTweak[], receiverIdentityPubkey: Uint8Array, cpfpSigningCommitments: RequestedSigningCommitments[], directSigningCommitments: RequestedSigningCommitments[], directFromCpfpSigningCommitments: RequestedSigningCommitments[], hash: Uint8Array): Promise<{
+        cpfpLeafSigningJobs: UserSignedTxSigningJob[];
+        directLeafSigningJobs: UserSignedTxSigningJob[];
+        directFromCpfpLeafSigningJobs: UserSignedTxSigningJob[];
+    }>;
 }
 
 type LeafKeyTweak = {
@@ -3735,8 +3902,10 @@ declare class BaseTransferService {
     protected readonly signingService: SigningService;
     constructor(config: WalletConfigService, connectionManager: ConnectionManager, signingService: SigningService);
     deliverTransferPackage(transfer: Transfer, leaves: LeafKeyTweak[], cpfpRefundSignatureMap: Map<string, Uint8Array>, directRefundSignatureMap: Map<string, Uint8Array>, directFromCpfpRefundSignatureMap: Map<string, Uint8Array>): Promise<Transfer>;
+    prepareTransferForLightning(leaves: LeafKeyTweak[], receiverIdentityPubkey: Uint8Array, paymentHash: Uint8Array, expiryTime: Date, transferID: string): Promise<StartTransferRequest>;
     sendTransferWithKeyTweaks(leaves: LeafKeyTweak[], receiverIdentityPubkey: Uint8Array, sparkInvoice?: SparkAddressFormat): Promise<Transfer>;
     private prepareTransferPackage;
+    private prepareTransferPackageForLightning;
     signRefunds(leafDataMap: Map<string, LeafRefundSigningData>, operatorSigningResults: LeafRefundTxSigningResult[]): Promise<NodeSignatures[]>;
     private prepareSendTransferKeyTweaks;
     private prepareSingleSendTransferKeyTweak;
@@ -3786,127 +3955,6 @@ declare class TransferService extends BaseTransferService {
     testonly_expireTimeLockRefundtx(node: TreeNode): Promise<FinalizeNodeSignaturesResponse>;
 }
 
-type Bech32mTokenIdentifier = `btkn1${string}` | `btknrt1${string}` | `btknt1${string}` | `btkns1${string}` | `btknl1${string}`;
-interface Bech32mTokenIdentifierData {
-    tokenIdentifier: Uint8Array;
-    network: NetworkType;
-}
-declare function encodeBech32mTokenIdentifier(payload: Bech32mTokenIdentifierData): Bech32mTokenIdentifier;
-declare function decodeBech32mTokenIdentifier(bech32mTokenIdentifier: Bech32mTokenIdentifier, network?: NetworkType): Bech32mTokenIdentifierData;
-declare function getNetworkFromBech32mTokenIdentifier(bech32mTokenIdentifier: Bech32mTokenIdentifier): NetworkType;
-
-type CreateLightningInvoiceParams = {
-    amountSats: number;
-    memo?: string;
-    expirySeconds?: number;
-    includeSparkAddress?: boolean;
-    receiverIdentityPubkey?: string;
-    descriptionHash?: string;
-};
-type PayLightningInvoiceParams = {
-    invoice: string;
-    maxFeeSats: number;
-    preferSpark?: boolean;
-    amountSatsToSend?: number;
-};
-type TransferParams = {
-    amountSats: number;
-    receiverSparkAddress: string;
-};
-type FulfillSparkInvoiceResponse = {
-    satsTransactionSuccess: {
-        invoice: SparkAddressFormat;
-        transferResponse: WalletTransfer;
-    }[];
-    tokenTransactionSuccess: {
-        tokenIdentifier: Bech32mTokenIdentifier;
-        txid: string;
-    }[];
-    satsTransactionErrors: {
-        invoice: string;
-        error: Error;
-    }[];
-    tokenTransactionErrors: {
-        tokenIdentifier: Bech32mTokenIdentifier;
-        error: Error;
-    }[];
-    invalidInvoices: {
-        invoice: string;
-        error: Error;
-    }[];
-};
-/**
- * Token metadata containing essential information about a token.
- * This is the wallet's internal representation with JavaScript-friendly types.
- *
- * rawTokenIdentifier: This is the raw binary token identifier - This is used to encode the bech32m encoded token identifier.
- *
- * tokenPublicKey: This is the hex-encoded public key of the token issuer - Same as issuerPublicKey.
- *
- * @example
- * ```typescript
- * const tokenMetadata: UserTokenMetadata = {
- *   rawTokenIdentifier: new Uint8Array([1, 2, 3]),
- *   tokenPublicKey: "0348fbb...",
- *   tokenName: "SparkToken",
- *   tokenTicker: "SPK",
- *   decimals: 8,
- *   maxSupply: 1000000n
- * };
- * ```
- */
-type UserTokenMetadata = {
-    /** Raw binary token identifier - This is used to encode the human readable token identifier */
-    rawTokenIdentifier: Uint8Array;
-    /** Public key of the token issuer - Same as issuerPublicKey */
-    tokenPublicKey: string;
-    /** Human-readable name of the token (e.g., SparkToken)*/
-    tokenName: string;
-    /** Short ticker symbol for the token (e.g., "SPK") */
-    tokenTicker: string;
-    /** Number of decimal places for token amounts */
-    decimals: number;
-    /** Maximum supply of tokens that can ever be minted */
-    maxSupply: bigint;
-};
-type TokenBalanceMap = Map<Bech32mTokenIdentifier, {
-    balance: bigint;
-    tokenMetadata: UserTokenMetadata;
-}>;
-type TokenOutputsMap = Map<Bech32mTokenIdentifier, OutputWithPreviousTransactionData$1[]>;
-type TokenMetadataMap = Map<Bech32mTokenIdentifier, TokenMetadata>;
-type InitWalletResponse<T extends SparkWallet = SparkWallet> = {
-    wallet: T;
-    mnemonic: string | undefined;
-};
-interface SparkWalletProps {
-    mnemonicOrSeed?: Uint8Array | string;
-    accountNumber?: number;
-    signer?: SparkSigner;
-    options?: ConfigOptions;
-}
-declare const SparkWalletEvent: {
-    readonly All: "*";
-    readonly TransferClaimed: "transfer:claimed";
-    readonly DepositConfirmed: "deposit:confirmed";
-    readonly StreamConnected: "stream:connected";
-    readonly StreamDisconnected: "stream:disconnected";
-    readonly StreamReconnecting: "stream:reconnecting";
-};
-interface SparkWalletEvents {
-    [SparkWalletEvent.All]: (eventName: string, ...args: unknown[]) => void;
-    /** Emitted when an incoming transfer is successfully claimed. Includes the transfer ID and new total balance. */
-    [SparkWalletEvent.TransferClaimed]: (transferId: string, updatedBalance: bigint) => void;
-    /** Emitted when a deposit is marked as available. Includes the deposit ID and new total balance. */
-    [SparkWalletEvent.DepositConfirmed]: (depositId: string, updatedBalance: bigint) => void;
-    /** Emitted when the stream is connected */
-    [SparkWalletEvent.StreamConnected]: () => void;
-    /** Emitted when the stream disconnects and fails to reconnect after max attempts */
-    [SparkWalletEvent.StreamDisconnected]: (reason: string) => void;
-    /** Emitted when attempting to reconnect the stream */
-    [SparkWalletEvent.StreamReconnecting]: (attempt: number, maxAttempts: number, delayMs: number, error: string) => void;
-}
-
 /**
  * The SparkWallet class is the primary interface for interacting with the Spark network.
  * It provides methods for creating and managing wallets, handling deposits, executing transfers,
@@ -3935,11 +3983,12 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
     protected tokenOutputs: TokenOutputsMap;
     private claimTransfersInterval;
     private tracer;
-    constructor(options?: ConfigOptions, signer?: SparkSigner);
+    protected abstract buildConnectionManager(config: WalletConfigService): ConnectionManager;
+    constructor(options?: ConfigOptions, signerArg?: SparkSigner);
     static initialize<T extends SparkWallet>(this: new (options?: ConfigOptions, signer?: SparkSigner) => T, { mnemonicOrSeed, accountNumber, signer, options }: SparkWalletProps): Promise<InitWalletResponse<T>>;
     private createClientsAndSyncWallet;
     private getSspClient;
-    protected buildConnectionManager(config: WalletConfigService): ConnectionManager;
+    protected buildSigner(): DefaultSparkSigner;
     private handleStreamEvent;
     protected setupBackgroundStream(): Promise<void>;
     getLeaves(isBalanceCheck?: boolean): Promise<TreeNode[]>;
@@ -4530,11 +4579,11 @@ type Transport = NonNullable<Parameters<typeof createChannel>[1]>;
 declare class ConnectionManagerBrowser extends ConnectionManager {
     protected transport: Transport;
     constructor(config: WalletConfigService, transport?: nice_grpc_web_lib_client_Transport_js.Transport);
-    protected createChannelWithTLS(address: string, certPath?: string): Promise<Channel$1>;
-    protected createAuthnMiddleware(): (call: ClientMiddlewareCall<any, any>, options: SparkCallOptions) => AsyncGenerator<any, any, undefined>;
-    protected createMiddleware(address: string, initialAuthToken: string): (call: ClientMiddlewareCall<any, any>, options: SparkCallOptions) => AsyncGenerator<any, any, undefined>;
-    protected createGrpcClient<T>(defintion: SparkAuthnServiceDefinition | SparkServiceDefinition | SparkTokenServiceDefinition, channel: Channel$1, withRetries: boolean, middleware?: any): Promise<T & {
-        close: undefined;
+    protected createChannelWithTLS(address: string): Promise<Channel$1>;
+    protected createAuthnMiddleware(): <Req, Res>(call: ClientMiddlewareCall<Req, Res>, options: SparkCallOptions) => AsyncGenerator<Res, Res | void, undefined>;
+    protected createMiddleware(address: string): <Req, Res>(call: ClientMiddlewareCall<Req, Res>, options: SparkCallOptions) => AsyncGenerator<Res, Res | void, undefined>;
+    protected createGrpcClient<T>(definition: SparkAuthnServiceDefinition | SparkServiceDefinition | SparkTokenServiceDefinition, channel: Channel$1, withRetries: boolean, middleware?: ClientMiddleware<RetryOptions, {}>, channelKey?: string): Promise<T & {
+        close: (() => void) | undefined;
     }>;
 }
 
@@ -4606,6 +4655,8 @@ declare function filterTokenBalanceForTokenIdentifier(tokenBalances: TokenBalanc
 declare function getTransferPackageSigningPayload(transferID: string, transferPackage: TransferPackage): Uint8Array;
 
 declare const DIRECT_TIMELOCK_OFFSET = 50;
+declare const HTLC_TIMELOCK_OFFSET = 70;
+declare const DIRECT_HTLC_TIMELOCK_OFFSET = 85;
 declare const INITIAL_SEQUENCE: number;
 declare const INITIAL_DIRECT_SEQUENCE: number;
 declare const TEST_UNILATERAL_SEQUENCE: number;
@@ -4640,6 +4691,10 @@ interface CreateRefundTxInput {
     includeAnchor: boolean;
 }
 declare function createRefundTx({ sequence, input, amountSats, receivingPubkey, network, shouldCalculateFee, includeAnchor, }: CreateRefundTxInput): Transaction;
+declare function getNextHTLCTransactionSequence(currSequence: number, isNodeTx?: boolean): {
+    nextSequence: number;
+    nextDirectSequence: number;
+};
 interface CreateRefundTxsInput {
     sequence: number;
     directSequence?: number;
@@ -4732,4 +4787,4 @@ declare class SparkSdkLogger {
     static setAllEnabled(enabled: boolean): void;
 }
 
-export { type AggregateFrostParams, AuthenticationError, type Bech32mTokenIdentifier, type Bech32mTokenIdentifierData, type BroadcastConfig, type BroadcastResult, ConfigurationError, DEFAULT_FEE_SATS, DIRECT_TIMELOCK_OFFSET, type DecodedSparkAddressData, DefaultSparkSigner, type FeeBumpTxChain, type FeeBumpTxPackage, type FeeRate, type IKeyPackage, INITIAL_DIRECT_SEQUENCE, INITIAL_SEQUENCE, InternalValidationError, LOGGER_NAMES, type LeafInfo, type LegacySparkAddressFormat, type LoggerName, Network, NetworkError, NetworkToProto, type NetworkType, NotImplementedError, RPCError, type SignFrostParams, type SparkAddressData, type SparkAddressFormat, SparkSDKError, SparkSdkLogger, type SparkSigner, SparkWalletBare as SparkWallet, TEST_UNILATERAL_DIRECT_SEQUENCE, TEST_UNILATERAL_SEQUENCE, TaprootOutputKeysGenerator, TaprootSparkSigner, type TxChain, UnsafeStatelessSparkSigner, type Utxo, ValidationError, type VerifiableSecretShare, addPrivateKeys, addPublicKeys, applyAdaptorToSignature, applyAdditiveTweakToPublicKey, assertBech32, bech32mDecode, bigIntToPrivateKey, checkIfSelectedOutputsAreAvailable, checkIfValidSequence, collectResponses, computeTaprootKeyNoScript, computerLagrangeCoefficients, constructFeeBumpTx, constructUnilateralExitFeeBumpPackages, constructUnilateralExitTxs, createConnectorRefundTransactions, createLeafNodeTx, createNodeTx, createNodeTxs, createRefundTx, createRefundTxs, createRootTx, createSigningCommitment, createSigningNonce, createSplitTx, decodeBech32mTokenIdentifier, decodeBytesToSigningCommitment, decodeBytesToSigningNonce, decodeSparkAddress, doesLeafNeedRefresh, encodeBech32mTokenIdentifier, encodeSigningCommitmentToBytes, encodeSigningNonceToBytes, encodeSparkAddress, encodeSparkAddressWithSignature, evaluatePolynomial, fieldDiv, filterTokenBalanceForTokenIdentifier, generateAdaptorFromSignature, generatePolynomialForSecretSharing, generateSignatureFromExistingAdaptor, getCurrentTimelock, getEphemeralAnchorOutput, getLatestDepositTxId, getNetwork, getNetworkFromAddress, getNetworkFromBech32mTokenIdentifier, getNetworkFromSparkAddress, getNetworkFromString, getNextTransactionSequence, getP2TRAddressFromPkScript, getP2TRAddressFromPublicKey, getP2TRScriptFromPublicKey, getP2WPKHAddressFromPublicKey, getRandomBigInt, getRandomSigningNonce, getSigHashFromTx, getSigningCommitmentFromNonce, getSparkAddressFromTaproot, getTransactionSequence, getTransferPackageSigningPayload, getTxEstimatedVbytesSizeByNumberOfInputsOutputs, getTxFromRawTxBytes, getTxFromRawTxHex, getTxId, getTxIdNoReverse, isEphemeralAnchorOutput, isLegacySparkAddress, isSafeForNumber, isTxBroadcast, isValidPublicKey, isValidSparkAddress, lastKeyWithTarget, maybeApplyFee, modInverse, proofOfPossessionMessageHashForDepositAddress, protoToNetwork, recoverSecret, splitSecret, splitSecretWithProofs, subtractPrivateKeys, subtractPublicKeys, sumAvailableTokens, sumOfPrivateKeys, toProtoTimestamp, validateOutboundAdaptorSignature, validateShare, validateSparkInvoiceFields, validateSparkInvoiceSignature };
+export { type AggregateFrostParams, AuthenticationError, type Bech32mTokenIdentifier, type Bech32mTokenIdentifierData, type BroadcastConfig, type BroadcastResult, ConfigurationError, DEFAULT_FEE_SATS, DIRECT_HTLC_TIMELOCK_OFFSET, DIRECT_TIMELOCK_OFFSET, type DecodedSparkAddressData, DefaultSparkSigner, type FeeBumpTxChain, type FeeBumpTxPackage, type FeeRate, HTLC_TIMELOCK_OFFSET, type IKeyPackage, INITIAL_DIRECT_SEQUENCE, INITIAL_SEQUENCE, InternalValidationError, LOGGER_NAMES, type LeafInfo, type LegacySparkAddressFormat, type LoggerName, Network, NetworkError, NetworkToProto, type NetworkType, NotImplementedError, RPCError, type SignFrostParams, type SparkAddressData, type SparkAddressFormat, SparkSDKError, SparkSdkLogger, type SparkSigner, SparkWalletBare as SparkWallet, TEST_UNILATERAL_DIRECT_SEQUENCE, TEST_UNILATERAL_SEQUENCE, TaprootOutputKeysGenerator, TaprootSparkSigner, type TxChain, UnsafeStatelessSparkSigner, type Utxo, ValidationError, type VerifiableSecretShare, addPrivateKeys, addPublicKeys, applyAdaptorToSignature, applyAdditiveTweakToPublicKey, assertBech32, bech32mDecode, bigIntToPrivateKey, checkIfSelectedOutputsAreAvailable, checkIfValidSequence, collectResponses, computeTaprootKeyNoScript, computerLagrangeCoefficients, constructFeeBumpTx, constructUnilateralExitFeeBumpPackages, constructUnilateralExitTxs, createConnectorRefundTransactions, createLeafNodeTx, createNodeTx, createNodeTxs, createRefundTx, createRefundTxs, createRootTx, createSigningCommitment, createSigningNonce, createSplitTx, decodeBech32mTokenIdentifier, decodeBytesToSigningCommitment, decodeBytesToSigningNonce, decodeSparkAddress, doesLeafNeedRefresh, encodeBech32mTokenIdentifier, encodeSigningCommitmentToBytes, encodeSigningNonceToBytes, encodeSparkAddress, encodeSparkAddressWithSignature, evaluatePolynomial, fieldDiv, filterTokenBalanceForTokenIdentifier, generateAdaptorFromSignature, generatePolynomialForSecretSharing, generateSignatureFromExistingAdaptor, getCurrentTimelock, getEphemeralAnchorOutput, getLatestDepositTxId, getNetwork, getNetworkFromAddress, getNetworkFromBech32mTokenIdentifier, getNetworkFromSparkAddress, getNetworkFromString, getNextHTLCTransactionSequence, getNextTransactionSequence, getP2TRAddressFromPkScript, getP2TRAddressFromPublicKey, getP2TRScriptFromPublicKey, getP2WPKHAddressFromPublicKey, getRandomBigInt, getRandomSigningNonce, getSigHashFromTx, getSigningCommitmentFromNonce, getSparkAddressFromTaproot, getTransactionSequence, getTransferPackageSigningPayload, getTxEstimatedVbytesSizeByNumberOfInputsOutputs, getTxFromRawTxBytes, getTxFromRawTxHex, getTxId, getTxIdNoReverse, isEphemeralAnchorOutput, isLegacySparkAddress, isSafeForNumber, isTxBroadcast, isValidPublicKey, isValidSparkAddress, lastKeyWithTarget, maybeApplyFee, modInverse, proofOfPossessionMessageHashForDepositAddress, protoToNetwork, recoverSecret, splitSecret, splitSecretWithProofs, subtractPrivateKeys, subtractPublicKeys, sumAvailableTokens, sumOfPrivateKeys, toProtoTimestamp, validateOutboundAdaptorSignature, validateShare, validateSparkInvoiceFields, validateSparkInvoiceSignature };