@buildonspark/spark-sdk 0.2.7 → 0.2.8

package/dist/bare/index.d.ts

@@ -9,6 +9,7 @@ import { Channel } from 'nice-grpc';
 import { Channel as Channel$1 } from 'nice-grpc-web';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { EventEmitter } from 'eventemitter3';
+import * as _scure_base from '@scure/base';
 import { TransactionOutput, TransactionInput } from '@scure/btc-signer/psbt';
 
 declare class SparkSDKError extends Error {
@@ -968,18 +969,6 @@ interface UTXO {
     txid: Uint8Array;
 }
 declare const UTXO: MessageFns$2<UTXO>;
-/**
- * NodeOutput represents a node on the tree.
- * This is similar to a UTXO, which is used to create a subtree on Spark. But instead of using
- * a utxo, a existing node on the tree is used as the utxo.
- */
-interface NodeOutput {
-    /** The id of the node. */
-    nodeId: string;
-    /** The vout of the raw transaction for the node, which will be used to create the tree. */
-    vout: number;
-}
-declare const NodeOutput: MessageFns$2<NodeOutput>;
 /**
  * SigningJob is the job for signing a transaction.
  * The signing job is used to sign a bitcoin transaction using Spark FROST.
@@ -1153,7 +1142,9 @@ interface TokenMintInput$1 {
 declare const TokenMintInput$1: MessageFns$2<TokenMintInput$1>;
 interface TokenCreateInput$1 {
     issuerPublicKey: Uint8Array;
+    /** No minimum length because a single utf-8 character can be 3 bytes. */
     tokenName: string;
+    /** No minimum length because a single utf-8 character can be 3 bytes. */
     tokenTicker: string;
     decimals: number;
     /** Decoded uint128 */
@@ -1732,79 +1723,6 @@ interface ExtendLeafResponse {
     directFromCpfpRefundTxSigningResult: ExtendLeafSigningResult | undefined;
 }
 declare const ExtendLeafResponse: MessageFns$2<ExtendLeafResponse>;
-interface AddressRequestNode {
-    userPublicKey: Uint8Array;
-    children: AddressRequestNode[];
-}
-declare const AddressRequestNode: MessageFns$2<AddressRequestNode>;
-interface PrepareTreeAddressRequest {
-    source?: {
-        $case: "parentNodeOutput";
-        parentNodeOutput: NodeOutput;
-    } | {
-        $case: "onChainUtxo";
-        onChainUtxo: UTXO;
-    } | undefined;
-    /**
-     * The tx on this node is to spend the source's utxo.
-     * The user's public key should already be registered with the SE for the root node.
-     */
-    node: AddressRequestNode | undefined;
-    userIdentityPublicKey: Uint8Array;
-}
-declare const PrepareTreeAddressRequest: MessageFns$2<PrepareTreeAddressRequest>;
-interface AddressNode {
-    address: Address | undefined;
-    children: AddressNode[];
-}
-declare const AddressNode: MessageFns$2<AddressNode>;
-interface PrepareTreeAddressResponse {
-    node: AddressNode | undefined;
-}
-declare const PrepareTreeAddressResponse: MessageFns$2<PrepareTreeAddressResponse>;
-interface CreationNode {
-    /** This is the cpfp tx that spends the parent node's output. */
-    nodeTxSigningJob: SigningJob | undefined;
-    /** The refund tx can only exist if there's no children. */
-    refundTxSigningJob: SigningJob | undefined;
-    /** The children will spend the output of the node's tx. Vout is the index of the child. */
-    children: CreationNode[];
-    /** This is the direct tx that spends the parent node's output. */
-    directNodeTxSigningJob: SigningJob | undefined;
-    /** The direct refund tx can only exist if there's no children. */
-    directRefundTxSigningJob: SigningJob | undefined;
-    /** The direct from cpfp refund tx can only exist if there's no children. */
-    directFromCpfpRefundTxSigningJob: SigningJob | undefined;
-}
-declare const CreationNode: MessageFns$2<CreationNode>;
-interface CreateTreeRequest {
-    source?: {
-        $case: "parentNodeOutput";
-        parentNodeOutput: NodeOutput;
-    } | {
-        $case: "onChainUtxo";
-        onChainUtxo: UTXO;
-    } | undefined;
-    /** The node should contain the tx that spends the source's utxo. */
-    node: CreationNode | undefined;
-    /** The owner of the tree. */
-    userIdentityPublicKey: Uint8Array;
-}
-declare const CreateTreeRequest: MessageFns$2<CreateTreeRequest>;
-interface CreationResponseNode {
-    nodeId: string;
-    nodeTxSigningResult: SigningResult | undefined;
-    refundTxSigningResult: SigningResult | undefined;
-    children: CreationResponseNode[];
-    directNodeTxSigningResult: SigningResult | undefined;
-    directRefundTxSigningResult: SigningResult | undefined;
-    directFromCpfpRefundTxSigningResult: SigningResult | undefined;
-}
-declare const CreationResponseNode: MessageFns$2<CreationResponseNode>;
-interface CreateTreeResponse {
-    node: CreationResponseNode | undefined;
-}
-declare const CreateTreeResponse: MessageFns$2<CreateTreeResponse>;
 interface SigningOperatorInfo {
     index: number;
     identifier: string;
@@ -2121,8 +2039,6 @@ interface SparkServiceClient<CallOptionsExt = {}> {
     counter_leaf_swap(request: DeepPartial$2<CounterLeafSwapRequest>, options?: CallOptions & CallOptionsExt): Promise<CounterLeafSwapResponse>;
     refresh_timelock(request: DeepPartial$2<RefreshTimelockRequest>, options?: CallOptions & CallOptionsExt): Promise<RefreshTimelockResponse>;
     extend_leaf(request: DeepPartial$2<ExtendLeafRequest>, options?: CallOptions & CallOptionsExt): Promise<ExtendLeafResponse>;
-    prepare_tree_address(request: DeepPartial$2<PrepareTreeAddressRequest>, options?: CallOptions & CallOptionsExt): Promise<PrepareTreeAddressResponse>;
-    create_tree(request: DeepPartial$2<CreateTreeRequest>, options?: CallOptions & CallOptionsExt): Promise<CreateTreeResponse>;
     get_signing_operator_list(request: DeepPartial$2<Empty>, options?: CallOptions & CallOptionsExt): Promise<GetSigningOperatorListResponse>;
     query_nodes(request: DeepPartial$2<QueryNodesRequest>, options?: CallOptions & CallOptionsExt): Promise<QueryNodesResponse>;
     query_nodes_distribution(request: DeepPartial$2<QueryNodesDistributionRequest>, options?: CallOptions & CallOptionsExt): Promise<QueryNodesDistributionResponse>;
@@ -2161,7 +2077,6 @@ interface SparkServiceClient<CallOptionsExt = {}> {
      * The following endpoints enforce inclusion of Direct Transactions used
      * for unilateral exits
      */
-    create_tree_v2(request: DeepPartial$2<CreateTreeRequest>, options?: CallOptions & CallOptionsExt): Promise<CreateTreeResponse>;
     cooperative_exit_v2(request: DeepPartial$2<CooperativeExitRequest>, options?: CallOptions & CallOptionsExt): Promise<CooperativeExitResponse>;
     extend_leaf_v2(request: DeepPartial$2<ExtendLeafRequest>, options?: CallOptions & CallOptionsExt): Promise<ExtendLeafResponse>;
     claim_transfer_sign_refunds_v2(request: DeepPartial$2<ClaimTransferSignRefundsRequest>, options?: CallOptions & CallOptionsExt): Promise<ClaimTransferSignRefundsResponse>;
@@ -2534,6 +2449,7 @@ type ConfigOptions = MayHaveSspClientOptions & {
     readonly sspClientOptions?: SspClientOptions;
     readonly expectedWithdrawBondSats?: number;
     readonly expectedWithdrawRelativeBlockLocktime?: number;
+    readonly signerWithPreExistingKeys?: boolean;
     readonly console?: ConsoleOptions;
 };
 
@@ -2625,6 +2541,12 @@ interface MessageFns$1<T> {
     fromPartial(object: DeepPartial$1<T>): T;
 }
 
+declare enum CommitStatus {
+    COMMIT_UNSPECIFIED = 0,
+    COMMIT_PROCESSING = 1,
+    COMMIT_FINALIZED = 2,
+    UNRECOGNIZED = -1
+}
 declare enum TokenTransactionStatus {
     TOKEN_TRANSACTION_STARTED = 0,
     TOKEN_TRANSACTION_SIGNED = 1,
@@ -2655,7 +2577,9 @@ interface TokenMintInput {
 declare const TokenMintInput: MessageFns<TokenMintInput>;
 interface TokenCreateInput {
     issuerPublicKey: Uint8Array;
+    /** No minimum length because a single utf-8 character can be 3 bytes. */
     tokenName: string;
+    /** No minimum length because a single utf-8 character can be 3 bytes. */
     tokenTicker: string;
     decimals: number;
     /** Decoded uint128 */
@@ -2720,8 +2644,14 @@ interface TokenTransaction {
      * timestamps win over later ones.
      */
     clientCreatedTimestamp: Date | undefined;
+    /** The spark invoices this transaction fulfills. */
+    invoiceAttachments: InvoiceAttachment[];
 }
 declare const TokenTransaction: MessageFns<TokenTransaction>;
+interface InvoiceAttachment {
+    sparkInvoice: string;
+}
+declare const InvoiceAttachment: MessageFns<InvoiceAttachment>;
 interface SignatureWithIndex {
     /**
      * This is a Schnorr or ECDSA DER signature which can be between 64 and 73
@@ -2772,7 +2702,14 @@ interface CommitTransactionRequest {
     ownerIdentityPublicKey: Uint8Array;
 }
 declare const CommitTransactionRequest: MessageFns<CommitTransactionRequest>;
+interface CommitProgress {
+    committedOperatorPublicKeys: Uint8Array[];
+    uncommittedOperatorPublicKeys: Uint8Array[];
+}
+declare const CommitProgress: MessageFns<CommitProgress>;
 interface CommitTransactionResponse {
+    commitStatus: CommitStatus;
+    commitProgress: CommitProgress | undefined;
 }
 declare const CommitTransactionResponse: MessageFns<CommitTransactionResponse>;
 interface QueryTokenMetadataRequest {
@@ -3002,7 +2939,7 @@ declare class TransferService extends BaseTransferService {
      */
     sendTransfer(leaves: LeafKeyTweak[], receiverIdentityPubkey: Uint8Array): Promise<Transfer>;
     claimTransfer(transfer: Transfer, leaves: LeafKeyTweak[]): Promise<FinalizeNodeSignaturesResponse>;
-    queryPendingTransfers(): Promise<QueryTransfersResponse>;
+    queryPendingTransfers(transferIds?: string[]): Promise<QueryTransfersResponse>;
     queryAllTransfers(limit: number, offset: number): Promise<QueryTransfersResponse>;
     verifyPendingTransfer(transfer: Transfer): Promise<Map<string, Uint8Array>>;
     queryTransfer(transferId: string): Promise<Transfer | undefined>;
@@ -3079,10 +3016,18 @@ interface DecodedSparkAddressData {
     signature?: string;
 }
 declare function encodeSparkAddress(payload: SparkAddressData): SparkAddressFormat;
+declare function encodeSparkAddressWithSignature(payload: SparkAddressData, signature?: Uint8Array): SparkAddressFormat;
 declare function decodeSparkAddress(address: string, network: NetworkType): DecodedSparkAddressData;
 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 getNetworkFromSparkAddress(address: SparkAddressFormat): "MAINNET" | "REGTEST" | "SIGNET" | "TESTNET" | "LOCAL";
+declare function toProtoTimestamp(date: Date): {
+    seconds: number;
+    nanos: number;
+};
+declare function bech32mDecode(address: SparkAddressFormat): _scure_base.Bech32Decoded<string>;
 
 type Bech32mTokenIdentifier = `btkn1${string}` | `btknrt1${string}` | `btknt1${string}` | `btkns1${string}` | `btknl1${string}`;
 interface Bech32mTokenIdentifierData {
@@ -3172,7 +3117,6 @@ declare class SparkWallet extends EventEmitter {
     protected transferService: TransferService;
     protected tracerId: string;
     private depositService;
-    private treeCreationService;
     private lightningService;
     private coopExitService;
     private signingService;
@@ -3273,11 +3217,16 @@ declare class SparkWallet extends EventEmitter {
      * @private
      */
     protected initWallet(mnemonicOrSeed?: Uint8Array | string, accountNumber?: number): Promise<InitWalletResponse | undefined>;
+    /**
+     * Initializes the wallet without a seed. Meant for use with a signer with pre-existing keys.
+     * @private
+     */
+    protected initWalletWithoutSeed(): Promise<`${string}1${string}`>;
     /**
      * Initializes a wallet from a seed.
      *
      * @param {Uint8Array | string} seed - The seed to initialize the wallet from
-     * @returns {Promise<string>} The identity public key
+     * @returns {Promise<string>} The Spark address
      * @private
      */
     private initWalletFromSeed;
@@ -3344,6 +3293,18 @@ declare class SparkWallet extends EventEmitter {
      */
     private generateDepositAddress;
     queryStaticDepositAddresses(): Promise<string[]>;
+    /**
+     * Returns confirmed UTXOs for a given Spark deposit address.
+     *
+     * @param depositAddress - The deposit address to query.
+     * @param limit - Maximum number of UTXOs to return (default 100).
+     * @param offset - Pagination offset (default 0).
+     * @returns {Promise<{ txid: string, vout: number }[]>} List of confirmed UTXOs.
+     */
+    getUtxosForDepositAddress(depositAddress: string, limit?: number, offset?: number): Promise<{
+        txid: string;
+        vout: number;
+    }[]>;
     /**
      * Get a quote on how much credit you can claim for a deposit from the SSP.
      *
@@ -3468,6 +3429,8 @@ declare class SparkWallet extends EventEmitter {
      * @private
      */
     private checkRefreshTimelockNodes;
+    private claimTransferCore;
+    private processClaimedTransferResults;
     /**
      * Claims a specific transfer.
      *
@@ -3512,6 +3475,10 @@ declare class SparkWallet extends EventEmitter {
      * @returns {Promise<LightningSendRequest>} The Lightning payment request details
      */
     payLightningInvoice({ invoice, maxFeeSats, preferSpark, amountSatsToSend, }: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>;
+    fulfillSparkInvoice(sparkInvoices: {
+        invoice: SparkAddressFormat;
+        amount?: bigint;
+    }[]): Promise<string>;
     /**
      * Gets fee estimate for sending Lightning payments.
      *
@@ -3519,29 +3486,6 @@ declare class SparkWallet extends EventEmitter {
      * @returns {Promise<number>} Fee estimate for sending Lightning payments
      */
     getLightningSendFeeEstimate({ encodedInvoice, amountSats, }: LightningSendFeeEstimateInput): Promise<number>;
-    /**
-     * Generates a deposit address for a tree.
-     *
-     * @param {number} vout - The vout index
-     * @param {Uint8Array} parentSigningPubKey - The parent signing public key
-     * @param {Transaction} [parentTx] - Optional parent transaction
-     * @param {TreeNode} [parentNode] - Optional parent node
-     * @returns {Promise<Object>} Deposit address information
-     * @private
-     */
-    private generateDepositAddressForTree;
-    /**
-     * Creates a tree structure.
-     *
-     * @param {number} vout - The vout index
-     * @param {DepositAddressTree} root - The root of the tree
-     * @param {boolean} createLeaves - Whether to create leaves
-     * @param {Transaction} [parentTx] - Optional parent transaction
-     * @param {TreeNode} [parentNode] - Optional parent node
-     * @returns {Promise<Object>} The created tree
-     * @private
-     */
-    private createTree;
     /**
      * Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address.
      *
@@ -3760,6 +3704,12 @@ declare class SparkWalletBrowser extends SparkWallet {
     protected initializeTracerEnv({ spanProcessors, traceUrls, }: Parameters<SparkWallet["initializeTracerEnv"]>[0]): void;
 }
 
+/**
+ * @deprecated Use `SparkWallet.getUtxosForDepositAddress()` instead.
+ * Retrieves the most recent transaction that pays to the given deposit address
+ * by querying the electrs HTTP API. Retained only for backwards compatibility
+ * and will be removed in a future release.
+ */
 declare function getLatestDepositTxId(address: string): Promise<string | null>;
 declare function isTxBroadcast(txid: string, baseUrl: string, network?: any): Promise<boolean>;
 
@@ -3926,4 +3876,4 @@ declare function constructFeeBumpTx(txHex: string, utxos: Utxo[], feeRate: FeeRa
 
 declare function getSparkAddressFromTaproot(taprootAddress: string): SparkAddressFormat;
 
-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, LRC_WALLET_NETWORK, type LeafInfo, Network, NetworkError, NetworkToProto, type NetworkType, NotImplementedError, RPCError, type SignFrostParams, type SparkAddressData, type SparkAddressFormat, SparkSDKError, type SparkSigner, SparkWalletBrowser as SparkWallet, TEST_UNILATERAL_DIRECT_SEQUENCE, TEST_UNILATERAL_SEQUENCE, TaprootOutputKeysGenerator, TaprootSparkSigner, type TxChain, UnsafeStatelessSparkSigner, type Utxo, ValidationError, type VerifiableSecretShare, addPrivateKeys, addPublicKeys, applyAdaptorToSignature, applyAdditiveTweakToPublicKey, 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, evaluatePolynomial, fieldDiv, filterTokenBalanceForTokenIdentifier, generateAdaptorFromSignature, generatePolynomialForSecretSharing, generateSignatureFromExistingAdaptor, getCurrentTimelock, getEphemeralAnchorOutput, getLatestDepositTxId, getNetwork, getNetworkFromAddress, getNetworkFromBech32mTokenIdentifier, getNetworkFromString, getNextTransactionSequence, getP2TRAddressFromPkScript, getP2TRAddressFromPublicKey, getP2TRScriptFromPublicKey, getP2WPKHAddressFromPublicKey, getRandomBigInt, getRandomSigningNonce, getSigHashFromTx, getSigningCommitmentFromNonce, getSparkAddressFromTaproot, getTransactionSequence, getTransferPackageSigningPayload, getTxEstimatedVbytesSizeByNumberOfInputsOutputs, getTxFromRawTxBytes, getTxFromRawTxHex, getTxId, getTxIdNoReverse, isEphemeralAnchorOutput, isTxBroadcast, isValidPublicKey, isValidSparkAddress, lastKeyWithTarget, maybeApplyFee, modInverse, proofOfPossessionMessageHashForDepositAddress, protoToNetwork, recoverSecret, splitSecret, splitSecretWithProofs, subtractPrivateKeys, subtractPublicKeys, sumAvailableTokens, sumOfPrivateKeys, validateOutboundAdaptorSignature, validateShare, validateSparkInvoiceFields };
+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, LRC_WALLET_NETWORK, type LeafInfo, Network, NetworkError, NetworkToProto, type NetworkType, NotImplementedError, RPCError, type SignFrostParams, type SparkAddressData, type SparkAddressFormat, SparkSDKError, type SparkSigner, SparkWalletBrowser as SparkWallet, TEST_UNILATERAL_DIRECT_SEQUENCE, TEST_UNILATERAL_SEQUENCE, TaprootOutputKeysGenerator, TaprootSparkSigner, type TxChain, UnsafeStatelessSparkSigner, type Utxo, ValidationError, type VerifiableSecretShare, addPrivateKeys, addPublicKeys, applyAdaptorToSignature, applyAdditiveTweakToPublicKey, 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, isTxBroadcast, isValidPublicKey, isValidSparkAddress, lastKeyWithTarget, maybeApplyFee, modInverse, proofOfPossessionMessageHashForDepositAddress, protoToNetwork, recoverSecret, splitSecret, splitSecretWithProofs, subtractPrivateKeys, subtractPublicKeys, sumAvailableTokens, sumOfPrivateKeys, toProtoTimestamp, validateOutboundAdaptorSignature, validateShare, validateSparkInvoiceFields, validateSparkInvoiceSignature };