@buildonspark/spark-sdk 0.4.1 → 0.4.2

package/dist/bare/index.d.cts

@@ -862,6 +862,12 @@ declare enum Order {
     ASCENDING = 1,
     UNRECOGNIZED = -1
 }
+declare enum PreimageRequestStatus {
+    PREIMAGE_REQUEST_STATUS_WAITING_FOR_PREIMAGE = 0,
+    PREIMAGE_REQUEST_STATUS_PREIMAGE_SHARED = 1,
+    PREIMAGE_REQUEST_STATUS_RETURNED = 2,
+    UNRECOGNIZED = -1
+}
 /** Static deposit address flow messages */
 declare enum UtxoSwapRequestType {
     Fixed = 0,
@@ -1149,7 +1155,6 @@ interface RenewNodeZeroTimelockSigningJob {
      */
     refundTxSigningJob: UserSignedTxSigningJob | undefined;
     directNodeTxSigningJob: UserSignedTxSigningJob | undefined;
-    directRefundTxSigningJob: UserSignedTxSigningJob | undefined;
     directFromCpfpRefundTxSigningJob: UserSignedTxSigningJob | undefined;
 }
 declare const RenewNodeZeroTimelockSigningJob: MessageFns$2<RenewNodeZeroTimelockSigningJob>;
@@ -1592,6 +1597,10 @@ declare const LeafRefundTxSigningJob: MessageFns$2<LeafRefundTxSigningJob>;
 interface UserSignedTxSigningJob {
     leafId: string;
     signingPublicKey: Uint8Array;
+    /**
+     * CPFP Refund Tx that is created when the User signs refunds. It spends the
+     * node transaction to the receiver.
+     */
     rawTx: Uint8Array;
     signingNonceCommitment: SigningCommitment | undefined;
     userSignature: Uint8Array;
@@ -1929,6 +1938,34 @@ interface QueryUserSignedRefundsResponse {
     transfer: Transfer | undefined;
 }
 declare const QueryUserSignedRefundsResponse: MessageFns$2<QueryUserSignedRefundsResponse>;
+interface PreimageRequestWithTransfer {
+    /** Preimage request data */
+    paymentHash: Uint8Array;
+    receiverIdentityPubkey: Uint8Array;
+    status: PreimageRequestStatus;
+    createdTime: Date | undefined;
+    /** Associated transfer (if exists) */
+    transfer?: Transfer | undefined;
+    /** Preimage data (if available) */
+    preimage?: Uint8Array | undefined;
+}
+declare const PreimageRequestWithTransfer: MessageFns$2<PreimageRequestWithTransfer>;
+interface QueryHtlcRequest {
+    paymentHashes: Uint8Array[];
+    identityPublicKey: Uint8Array;
+    status?: PreimageRequestStatus | undefined;
+    /** defaults to 100 if not set. */
+    limit: number;
+    /** defaults to 0 if not set. */
+    offset: number;
+}
+declare const QueryHtlcRequest: MessageFns$2<QueryHtlcRequest>;
+interface QueryHtlcResponse {
+    preimageRequests: PreimageRequestWithTransfer[];
+    /** defaults to -1 if there are no more results */
+    offset: number;
+}
+declare const QueryHtlcResponse: MessageFns$2<QueryHtlcResponse>;
 interface ProvidePreimageRequest {
     paymentHash: Uint8Array;
     preimage: Uint8Array;
@@ -2211,6 +2248,33 @@ interface TokenTransfer {
     finalTokenTransactionHash: Uint8Array;
 }
 declare const TokenTransfer: MessageFns$2<TokenTransfer>;
+interface InitiateSwapPrimaryTransferRequest {
+    /** Transfer with refunds and key tweaks signed */
+    transfer: StartTransferRequest | undefined;
+    /**
+     * Adaptor public keys to verify the signatures of refunds for the primary
+     * transfer in the swap
+     */
+    adaptorPublicKeys: AdaptorPublicKeyPackage | undefined;
+}
+declare const InitiateSwapPrimaryTransferRequest: MessageFns$2<InitiateSwapPrimaryTransferRequest>;
+interface InitiateSwapPrimaryTransferResponse {
+    transfer: Transfer | undefined;
+    signingResults: LeafRefundTxSigningResult[];
+}
+declare const InitiateSwapPrimaryTransferResponse: MessageFns$2<InitiateSwapPrimaryTransferResponse>;
+/**
+ * Adaptor public key is derived from the secret `t` using formula:
+ * ```
+ * T = t * G
+ * ```
+ */
+interface AdaptorPublicKeyPackage {
+    adaptorPublicKey: Uint8Array;
+    directAdaptorPublicKey: Uint8Array;
+    directFromCpfpAdaptorPublicKey: Uint8Array;
+}
+declare const AdaptorPublicKeyPackage: MessageFns$2<AdaptorPublicKeyPackage>;
 type SparkServiceDefinition = typeof SparkServiceDefinition;
 declare const SparkServiceDefinition: {
     readonly name: "SparkService";
@@ -2375,6 +2439,14 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly query_htlc: {
+            readonly name: "query_htlc";
+            readonly requestType: MessageFns$2<QueryHtlcRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<QueryHtlcResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         /**
          * This is the exact same as start_transfer, but expresses to the SO
          * this transfer is specifically for a leaf swap.
@@ -2654,6 +2726,14 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly initiate_preimage_swap_v3: {
+            readonly name: "initiate_preimage_swap_v3";
+            readonly requestType: MessageFns$2<InitiatePreimageSwapRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<InitiatePreimageSwapResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly start_leaf_swap_v2: {
             readonly name: "start_leaf_swap_v2";
             readonly requestType: MessageFns$2<StartTransferRequest>;
@@ -2702,6 +2782,19 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        /**
+         * Inititiates a primary transfer in a Swap V3 protocol. The sender submits the
+         * transfer package, but the SOs will not tweak the keys at this stage of the flow.
+         * It will be done later, when the SSP initiates a counter swap.
+         */
+        readonly initiate_swap_primary_transfer: {
+            readonly name: "initiate_swap_primary_transfer";
+            readonly requestType: MessageFns$2<InitiateSwapPrimaryTransferRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<InitiateSwapPrimaryTransferResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
     };
 };
 interface SparkServiceClient<CallOptionsExt = {}> {
@@ -2738,6 +2831,7 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     cooperative_exit(request: DeepPartial$2<CooperativeExitRequest>, options?: CallOptions & CallOptionsExt): Promise<CooperativeExitResponse>;
     initiate_preimage_swap(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
     provide_preimage(request: DeepPartial$2<ProvidePreimageRequest>, options?: CallOptions & CallOptionsExt): Promise<ProvidePreimageResponse>;
+    query_htlc(request: DeepPartial$2<QueryHtlcRequest>, options?: CallOptions & CallOptionsExt): Promise<QueryHtlcResponse>;
     /**
      * This is the exact same as start_transfer, but expresses to the SO
      * this transfer is specifically for a leaf swap.
@@ -2807,12 +2901,19 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     claim_transfer_sign_refunds_v2(request: DeepPartial$2<ClaimTransferSignRefundsRequest>, options?: CallOptions & CallOptionsExt): Promise<ClaimTransferSignRefundsResponse>;
     finalize_node_signatures_v2(request: DeepPartial$2<FinalizeNodeSignaturesRequest>, options?: CallOptions & CallOptionsExt): Promise<FinalizeNodeSignaturesResponse>;
     initiate_preimage_swap_v2(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
+    initiate_preimage_swap_v3(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
     start_leaf_swap_v2(request: DeepPartial$2<StartTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<StartTransferResponse>;
     counter_leaf_swap_v2(request: DeepPartial$2<CounterLeafSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<CounterLeafSwapResponse>;
     start_transfer_v2(request: DeepPartial$2<StartTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<StartTransferResponse>;
     refresh_timelock_v2(request: DeepPartial$2<RefreshTimelockRequest>, options?: CallOptions & CallOptionsExt): Promise<RefreshTimelockResponse>;
     get_utxos_for_address(request: DeepPartial$2<GetUtxosForAddressRequest>, options?: CallOptions & CallOptionsExt): Promise<GetUtxosForAddressResponse>;
     query_spark_invoices(request: DeepPartial$2<QuerySparkInvoicesRequest>, options?: CallOptions & CallOptionsExt): Promise<QuerySparkInvoicesResponse>;
+    /**
+     * Inititiates a primary transfer in a Swap V3 protocol. The sender submits the
+     * transfer package, but the SOs will not tweak the keys at this stage of the flow.
+     * It will be done later, when the SSP initiates a counter swap.
+     */
+    initiate_swap_primary_transfer(request: DeepPartial$2<InitiateSwapPrimaryTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiateSwapPrimaryTransferResponse>;
 }
 type Builtin$2 = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial$2<T> = T extends Builtin$2 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$2<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$2<U>> : T extends {
@@ -3556,8 +3657,8 @@ interface DecodedSparkAddressData {
     };
     signature?: string;
 }
-declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
-declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
+declare function encodeSparkAddress(payload: SparkAddressData): SparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): SparkAddressFormat;
 declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
 declare function getNetworkFromSparkAddress(address: string): NetworkType;
 declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
@@ -3607,20 +3708,23 @@ type FulfillSparkInvoiceResponse = {
     }[];
     tokenTransactionSuccess: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         txid: string;
     }[];
     satsTransactionErrors: {
-        invoice: string;
+        invoice: SparkAddressFormat;
         error: Error;
     }[];
     tokenTransactionErrors: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         error: Error;
     }[];
-    invalidInvoices: {
-        invoice: string;
-        error: Error;
-    }[];
+    invalidInvoices: InvalidInvoice[];
+};
+type InvalidInvoice = {
+    invoice: SparkAddressFormat;
+    error: Error;
 };
 /**
  * Token metadata containing essential information about a token.
@@ -4098,14 +4202,14 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {Object} params - Parameters for the sats payment
      * @param {number} params.amount - The amount of sats to receive
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the sats payment
      */
-    createSatsInvoice({ amount, memo, senderPublicKey, expiryTime, }: {
+    createSatsInvoice({ amount, memo, senderSparkAddress, expiryTime, }: {
         amount?: number;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -4115,15 +4219,15 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {bigint} [params.amount] - The amount of tokens to receive
      * @param {Bech32mTokenIdentifier} [params.tokenIdentifier] - The token identifier
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the tokens payment
      */
-    createTokensInvoice({ amount, tokenIdentifier, memo, senderPublicKey, expiryTime, }: {
+    createTokensInvoice({ amount, tokenIdentifier, memo, senderSparkAddress, expiryTime, }: {
         tokenIdentifier?: Bech32mTokenIdentifier;
         amount?: bigint;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -4422,6 +4526,31 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @returns {Promise<LightningSendRequest>} The Lightning payment request details
      */
     payLightningInvoice({ invoice, maxFeeSats, preferSpark, amountSatsToSend, }: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>;
+    /**
+     * Fulfills one or more Spark invoices.
+     *
+     * Processes each provided invoice and attempts to pay it according to the wallet’s
+     * funding/selection strategy.
+     *
+     * @param sparkInvoices - Invoices to fulfill.
+     * @param sparkInvoices[].invoice - The parsed Spark address/invoice to pay.
+     *   Must be a valid Spark address or invoice.
+     *   Must use spark1... prefixed invoices.
+     *   Deprecated sp1... prefixed invoices are not supported.
+     * @param sparkInvoices[].amount - Used to define an amount for invoices without an amount encoded.
+     *   For sats invoices, this is the amount in sats. For token invoices, this is the amount in tokens.
+     *   Amount encoded in the invoice takes precedence if both are provided.
+     *
+     * @returns Promise<string> A payment or transaction identifier (implementation‑specific).
+     *
+     * @throws {ValidationError} If validation fails (malformed invoice, zero/negative amount, unsupported network),
+     *
+     * @example
+     * await wallet.fulfillSparkInvoice([
+     *   { invoice: invoiceWithNilAmount, amount: 1000n },
+     *   { invoice: invoiceWithEncodedAmount }, // uses amount encoded in the invoice
+     * ]);
+     */
     fulfillSparkInvoice(sparkInvoices: {
         invoice: SparkAddressFormat;
         amount?: bigint;

package/dist/bare/index.d.ts

@@ -862,6 +862,12 @@ declare enum Order {
     ASCENDING = 1,
     UNRECOGNIZED = -1
 }
+declare enum PreimageRequestStatus {
+    PREIMAGE_REQUEST_STATUS_WAITING_FOR_PREIMAGE = 0,
+    PREIMAGE_REQUEST_STATUS_PREIMAGE_SHARED = 1,
+    PREIMAGE_REQUEST_STATUS_RETURNED = 2,
+    UNRECOGNIZED = -1
+}
 /** Static deposit address flow messages */
 declare enum UtxoSwapRequestType {
     Fixed = 0,
@@ -1149,7 +1155,6 @@ interface RenewNodeZeroTimelockSigningJob {
      */
     refundTxSigningJob: UserSignedTxSigningJob | undefined;
     directNodeTxSigningJob: UserSignedTxSigningJob | undefined;
-    directRefundTxSigningJob: UserSignedTxSigningJob | undefined;
     directFromCpfpRefundTxSigningJob: UserSignedTxSigningJob | undefined;
 }
 declare const RenewNodeZeroTimelockSigningJob: MessageFns$2<RenewNodeZeroTimelockSigningJob>;
@@ -1592,6 +1597,10 @@ declare const LeafRefundTxSigningJob: MessageFns$2<LeafRefundTxSigningJob>;
 interface UserSignedTxSigningJob {
     leafId: string;
     signingPublicKey: Uint8Array;
+    /**
+     * CPFP Refund Tx that is created when the User signs refunds. It spends the
+     * node transaction to the receiver.
+     */
     rawTx: Uint8Array;
     signingNonceCommitment: SigningCommitment | undefined;
     userSignature: Uint8Array;
@@ -1929,6 +1938,34 @@ interface QueryUserSignedRefundsResponse {
     transfer: Transfer | undefined;
 }
 declare const QueryUserSignedRefundsResponse: MessageFns$2<QueryUserSignedRefundsResponse>;
+interface PreimageRequestWithTransfer {
+    /** Preimage request data */
+    paymentHash: Uint8Array;
+    receiverIdentityPubkey: Uint8Array;
+    status: PreimageRequestStatus;
+    createdTime: Date | undefined;
+    /** Associated transfer (if exists) */
+    transfer?: Transfer | undefined;
+    /** Preimage data (if available) */
+    preimage?: Uint8Array | undefined;
+}
+declare const PreimageRequestWithTransfer: MessageFns$2<PreimageRequestWithTransfer>;
+interface QueryHtlcRequest {
+    paymentHashes: Uint8Array[];
+    identityPublicKey: Uint8Array;
+    status?: PreimageRequestStatus | undefined;
+    /** defaults to 100 if not set. */
+    limit: number;
+    /** defaults to 0 if not set. */
+    offset: number;
+}
+declare const QueryHtlcRequest: MessageFns$2<QueryHtlcRequest>;
+interface QueryHtlcResponse {
+    preimageRequests: PreimageRequestWithTransfer[];
+    /** defaults to -1 if there are no more results */
+    offset: number;
+}
+declare const QueryHtlcResponse: MessageFns$2<QueryHtlcResponse>;
 interface ProvidePreimageRequest {
     paymentHash: Uint8Array;
     preimage: Uint8Array;
@@ -2211,6 +2248,33 @@ interface TokenTransfer {
     finalTokenTransactionHash: Uint8Array;
 }
 declare const TokenTransfer: MessageFns$2<TokenTransfer>;
+interface InitiateSwapPrimaryTransferRequest {
+    /** Transfer with refunds and key tweaks signed */
+    transfer: StartTransferRequest | undefined;
+    /**
+     * Adaptor public keys to verify the signatures of refunds for the primary
+     * transfer in the swap
+     */
+    adaptorPublicKeys: AdaptorPublicKeyPackage | undefined;
+}
+declare const InitiateSwapPrimaryTransferRequest: MessageFns$2<InitiateSwapPrimaryTransferRequest>;
+interface InitiateSwapPrimaryTransferResponse {
+    transfer: Transfer | undefined;
+    signingResults: LeafRefundTxSigningResult[];
+}
+declare const InitiateSwapPrimaryTransferResponse: MessageFns$2<InitiateSwapPrimaryTransferResponse>;
+/**
+ * Adaptor public key is derived from the secret `t` using formula:
+ * ```
+ * T = t * G
+ * ```
+ */
+interface AdaptorPublicKeyPackage {
+    adaptorPublicKey: Uint8Array;
+    directAdaptorPublicKey: Uint8Array;
+    directFromCpfpAdaptorPublicKey: Uint8Array;
+}
+declare const AdaptorPublicKeyPackage: MessageFns$2<AdaptorPublicKeyPackage>;
 type SparkServiceDefinition = typeof SparkServiceDefinition;
 declare const SparkServiceDefinition: {
     readonly name: "SparkService";
@@ -2375,6 +2439,14 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly query_htlc: {
+            readonly name: "query_htlc";
+            readonly requestType: MessageFns$2<QueryHtlcRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<QueryHtlcResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         /**
          * This is the exact same as start_transfer, but expresses to the SO
          * this transfer is specifically for a leaf swap.
@@ -2654,6 +2726,14 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly initiate_preimage_swap_v3: {
+            readonly name: "initiate_preimage_swap_v3";
+            readonly requestType: MessageFns$2<InitiatePreimageSwapRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<InitiatePreimageSwapResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly start_leaf_swap_v2: {
             readonly name: "start_leaf_swap_v2";
             readonly requestType: MessageFns$2<StartTransferRequest>;
@@ -2702,6 +2782,19 @@ declare const SparkServiceDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        /**
+         * Inititiates a primary transfer in a Swap V3 protocol. The sender submits the
+         * transfer package, but the SOs will not tweak the keys at this stage of the flow.
+         * It will be done later, when the SSP initiates a counter swap.
+         */
+        readonly initiate_swap_primary_transfer: {
+            readonly name: "initiate_swap_primary_transfer";
+            readonly requestType: MessageFns$2<InitiateSwapPrimaryTransferRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$2<InitiateSwapPrimaryTransferResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
     };
 };
 interface SparkServiceClient<CallOptionsExt = {}> {
@@ -2738,6 +2831,7 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     cooperative_exit(request: DeepPartial$2<CooperativeExitRequest>, options?: CallOptions & CallOptionsExt): Promise<CooperativeExitResponse>;
     initiate_preimage_swap(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
     provide_preimage(request: DeepPartial$2<ProvidePreimageRequest>, options?: CallOptions & CallOptionsExt): Promise<ProvidePreimageResponse>;
+    query_htlc(request: DeepPartial$2<QueryHtlcRequest>, options?: CallOptions & CallOptionsExt): Promise<QueryHtlcResponse>;
     /**
      * This is the exact same as start_transfer, but expresses to the SO
      * this transfer is specifically for a leaf swap.
@@ -2807,12 +2901,19 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     claim_transfer_sign_refunds_v2(request: DeepPartial$2<ClaimTransferSignRefundsRequest>, options?: CallOptions & CallOptionsExt): Promise<ClaimTransferSignRefundsResponse>;
     finalize_node_signatures_v2(request: DeepPartial$2<FinalizeNodeSignaturesRequest>, options?: CallOptions & CallOptionsExt): Promise<FinalizeNodeSignaturesResponse>;
     initiate_preimage_swap_v2(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
+    initiate_preimage_swap_v3(request: DeepPartial$2<InitiatePreimageSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiatePreimageSwapResponse>;
     start_leaf_swap_v2(request: DeepPartial$2<StartTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<StartTransferResponse>;
     counter_leaf_swap_v2(request: DeepPartial$2<CounterLeafSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<CounterLeafSwapResponse>;
     start_transfer_v2(request: DeepPartial$2<StartTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<StartTransferResponse>;
     refresh_timelock_v2(request: DeepPartial$2<RefreshTimelockRequest>, options?: CallOptions & CallOptionsExt): Promise<RefreshTimelockResponse>;
     get_utxos_for_address(request: DeepPartial$2<GetUtxosForAddressRequest>, options?: CallOptions & CallOptionsExt): Promise<GetUtxosForAddressResponse>;
     query_spark_invoices(request: DeepPartial$2<QuerySparkInvoicesRequest>, options?: CallOptions & CallOptionsExt): Promise<QuerySparkInvoicesResponse>;
+    /**
+     * Inititiates a primary transfer in a Swap V3 protocol. The sender submits the
+     * transfer package, but the SOs will not tweak the keys at this stage of the flow.
+     * It will be done later, when the SSP initiates a counter swap.
+     */
+    initiate_swap_primary_transfer(request: DeepPartial$2<InitiateSwapPrimaryTransferRequest>, options?: CallOptions & CallOptionsExt): Promise<InitiateSwapPrimaryTransferResponse>;
 }
 type Builtin$2 = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial$2<T> = T extends Builtin$2 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$2<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$2<U>> : T extends {
@@ -3556,8 +3657,8 @@ interface DecodedSparkAddressData {
     };
     signature?: string;
 }
-declare function encodeSparkAddress(payload: SparkAddressData): LegacySparkAddressFormat;
-declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): LegacySparkAddressFormat;
+declare function encodeSparkAddress(payload: SparkAddressData): SparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): SparkAddressFormat;
 declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
 declare function getNetworkFromSparkAddress(address: string): NetworkType;
 declare function isLegacySparkAddress(address: string): address is LegacySparkAddressFormat;
@@ -3607,20 +3708,23 @@ type FulfillSparkInvoiceResponse = {
     }[];
     tokenTransactionSuccess: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         txid: string;
     }[];
     satsTransactionErrors: {
-        invoice: string;
+        invoice: SparkAddressFormat;
         error: Error;
     }[];
     tokenTransactionErrors: {
         tokenIdentifier: Bech32mTokenIdentifier;
+        invoices: SparkAddressFormat[];
         error: Error;
     }[];
-    invalidInvoices: {
-        invoice: string;
-        error: Error;
-    }[];
+    invalidInvoices: InvalidInvoice[];
+};
+type InvalidInvoice = {
+    invoice: SparkAddressFormat;
+    error: Error;
 };
 /**
  * Token metadata containing essential information about a token.
@@ -4098,14 +4202,14 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {Object} params - Parameters for the sats payment
      * @param {number} params.amount - The amount of sats to receive
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the sats payment
      */
-    createSatsInvoice({ amount, memo, senderPublicKey, expiryTime, }: {
+    createSatsInvoice({ amount, memo, senderSparkAddress, expiryTime, }: {
         amount?: number;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -4115,15 +4219,15 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @param {bigint} [params.amount] - The amount of tokens to receive
      * @param {Bech32mTokenIdentifier} [params.tokenIdentifier] - The token identifier
      * @param {string} [params.memo] - The memo for the payment
-     * @param {string} [params.senderPublicKey] - The public key of the expected sender
+     * @param {string} [params.senderSparkAddress] - The spark address of the expected sender
      * @param {Date} [params.expiryTime] - The expiry time of the payment
      * @returns {Promise<SparkAddressFormat>} The Spark address for the tokens payment
      */
-    createTokensInvoice({ amount, tokenIdentifier, memo, senderPublicKey, expiryTime, }: {
+    createTokensInvoice({ amount, tokenIdentifier, memo, senderSparkAddress, expiryTime, }: {
         tokenIdentifier?: Bech32mTokenIdentifier;
         amount?: bigint;
         memo?: string;
-        senderPublicKey?: string;
+        senderSparkAddress?: SparkAddressFormat;
         expiryTime?: Date;
     }): Promise<SparkAddressFormat>;
     /**
@@ -4422,6 +4526,31 @@ declare abstract class SparkWallet extends EventEmitter<SparkWalletEvents> {
      * @returns {Promise<LightningSendRequest>} The Lightning payment request details
      */
     payLightningInvoice({ invoice, maxFeeSats, preferSpark, amountSatsToSend, }: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>;
+    /**
+     * Fulfills one or more Spark invoices.
+     *
+     * Processes each provided invoice and attempts to pay it according to the wallet’s
+     * funding/selection strategy.
+     *
+     * @param sparkInvoices - Invoices to fulfill.
+     * @param sparkInvoices[].invoice - The parsed Spark address/invoice to pay.
+     *   Must be a valid Spark address or invoice.
+     *   Must use spark1... prefixed invoices.
+     *   Deprecated sp1... prefixed invoices are not supported.
+     * @param sparkInvoices[].amount - Used to define an amount for invoices without an amount encoded.
+     *   For sats invoices, this is the amount in sats. For token invoices, this is the amount in tokens.
+     *   Amount encoded in the invoice takes precedence if both are provided.
+     *
+     * @returns Promise<string> A payment or transaction identifier (implementation‑specific).
+     *
+     * @throws {ValidationError} If validation fails (malformed invoice, zero/negative amount, unsupported network),
+     *
+     * @example
+     * await wallet.fulfillSparkInvoice([
+     *   { invoice: invoiceWithNilAmount, amount: 1000n },
+     *   { invoice: invoiceWithEncodedAmount }, // uses amount encoded in the invoice
+     * ]);
+     */
     fulfillSparkInvoice(sparkInvoices: {
         invoice: SparkAddressFormat;
         amount?: bigint;