API 参考 - Spark

SparkWallet

SparkWallet 类是与 Spark 网络交互的主要接口。它提供了创建和管理钱包、处理存款、执行转账以及与闪电网络交互的方法。

安装

yarn add @buildonspark/spark-sdk

或 npm

npm i @buildonspark/spark-sdk

方法

`initialize({ mnemonicOrSeed, signer, options }: SparkWalletProps)`

创建并初始化一个新的 SparkWallet 实例。

interface SparkWalletProps {
  mnemonicOrSeed?: Uint8Array | string;
  accountNumber?: number;
  signer?: SparkSigner;
  options?: ConfigOptions;
}

static async initialize(props: SparkWalletProps): Promise<{
  wallet: SparkWallet;
  mnemonic?: string;
}>

参数:

props: 包含:
- mnemonicOrSeed: (可选) BIP-39 助记词短语或原始种子
- accountNumber: (可选) 账户编号
- signer: (可选) 自定义签名者实现
- options: (可选) 钱包配置选项

返回值:

包含:
- wallet: 初始化的 SparkWallet 实例
- mnemonic: 如果生成了助记词，则为助记词(对于原始种子为未定义)

`getIdentityPublicKey()`

获取钱包的身份公钥。

async getIdentityPublicKey(): Promise<string>

返回值:

Promise<string>: 十六进制字符串形式的身份公钥

`getSparkAddress()`

获取钱包的 Spark 地址。

async getSparkAddress(): Promise<SparkAddressFormat>

返回值:

Promise<SparkAddressFormat>: Spark 地址

`getTransfers(limit?: number, offset?: number)`

获取钱包的所有转账。

async getTransfers(
  limit: number = 20,
  offset: number = 0
): Promise<{
  transfers: WalletTransfer[];
  offset: number;
}>

参数:

limit: (可选，默认: 20) 返回的最大转账数量
offset: (可选，默认: 0) 分页的偏移量

返回值:

Promise<{ transfers: WalletTransfer[]; offset: number; }>: 包含转账列表和偏移量的响应

`getBalance()`

获取钱包的当前余额。您可以使用 forceRefetch 选项来同步您的钱包，并在返回余额之前认领任何待处理的传入闪电支付、Spark 转账或比特币存款。

async getBalance(): Promise<{
  balance: bigint;
  tokenBalances: Map<string, { balance: bigint, bech32mTokenIdentifier: string }>;
}>

返回值:

包含:
- balance: 钱包当前的余额(以聪为单位)
- tokenBalances: 代币公钥到代币余额的映射，包含 Bech32m 代币标识符

`getSingleUseDepositAddress()`

生成一个新的一次性存款地址，用于接收比特币资金。请注意，此函数返回一个比特币地址，而不是 Spark 地址。一旦使用，此地址不应再次使用。对于第 1 层比特币存款，Spark 生成支付到 Taproot (P2TR) 地址。这些地址以 “bc1p” 开头，可用于从任何钱包接收比特币。

async getSingleUseDepositAddress(): Promise<string>

返回值:

Promise<string>: 用于存入资金的比特币地址

`getUnusedDepositAddresses()`

获取钱包的所有未使用存款地址。

async getUnusedDepositAddresses(): Promise<string[]>

返回值:

Promise<string[]>: 未使用存款地址的数组

`transfer(params)`

将比特币转账给另一个 Spark 钱包。

async transfer({
  receiverSparkAddress,
  amountSats,
}: {
  receiverSparkAddress: string;
  amountSats: number;
}): Promise<WalletTransfer>

参数:

params: 包含:
- receiverSparkAddress: 接收者的 Spark 地址
- amountSats: 要转账的金额(以聪为单位)

返回值:

Promise<WalletTransfer>: 完成的转账详情

`payLightningInvoice(params: PayLightningInvoiceParams)`

支付闪电网络发票。

interface PayLightningInvoiceParams {
  invoice: string;
  maxFeeSats: number;
  amountSatsToSend?: number;
}

async payLightningInvoice(params: PayLightningInvoiceParams): Promise<LightningSendRequest>

参数:

params: 包含:
- invoice: 要支付的 BOLT11 编码的闪电网络发票。
- maxFeeSats: 支付发票的最大费用(以聪为单位)。
- amountSatsToSend: (可选) 要发送的金额(以聪为单位)。此参数仅用于零金额发票。对于有固定金额的普通发票，此参数将被忽略。

返回值:

Promise<LightningSendRequest>: 闪电网络支付请求详情

示例:

// 支付普通发票
const payment_response = await wallet.payLightningInvoice({
  invoice: "lnbc100n...", // 有金额的普通闪电网络发票
  maxFeeSats: 5,
});
console.log("支付响应:", payment_response);

// 支付零金额发票
const zeroAmountPayment = await wallet.payLightningInvoice({
  invoice: "lnbc...", // 零金额闪电网络发票
  maxFeeSats: 5,
  amountSatsToSend: 1000, // 为零金额发票指定金额
});
console.log("零金额支付响应:", zeroAmountPayment);

`transferTokens(params)`

将代币转账给另一个用户。

async transferTokens({
  tokenIdentifier,
  tokenAmount,
  receiverSparkAddress,
  selectedOutputs,
}: {
  tokenIdentifier: string;
  tokenAmount: bigint;
  receiverSparkAddress: string;
  selectedOutputs?: OutputWithPreviousTransactionData[];
}): Promise<string>

参数:

params: 包含:
- tokenIdentifier: 要转账的代币的 Bech32m 代币标识符（例如：btkn1…）
- tokenAmount: 要转账的代币数量
- receiverSparkAddress: 接收者的 Spark 地址
- selectedOutputs: (可选) 用于转账的特定输出

返回值:

Promise<string>: 代币转账的交易 ID

`getTokenInfo()`

获取钱包拥有的代币信息。

async getTokenInfo(): Promise<TokenInfo[]>

返回值:

Promise<TokenInfo[]>: 代币信息对象的数组

`queryTokenTransactions()`

检索代币交易记录，可选根据 ownerPublicKeys、issuerPublicKeys、tokenTransactionHashes、tokenIdentifiers 或 outputIds 进行过滤。

async queryTokenTransactions({
  ownerPublicKeys,
  issuerPublicKeys,
  tokenTransactionHashes,
  tokenIdentifiers,
  outputIds,
}: {
  ownerPublicKeys?: string[];
  issuerPublicKeys?: string[];
  tokenTransactionHashes?: string[];
  tokenIdentifiers?: string[];
  outputIds?: string[];
}): Promise<TokenTransactionWithStatus[]>

参数:

ownerPublicKeys: (可选) 用于过滤的持有者公钥数组
issuerPublicKeys: (可选) 用于过滤的发行者公钥数组
tokenTransactionHashes: (可选) 用于过滤的代币交易哈希数组
tokenIdentifiers: (可选) 用于过滤的 Bech32m 代币标识符数组
outputIds: (可选) 用于过滤的输出 ID 数组

返回值:

Promise<TokenTransactionWithStatus[]>: 带状态的代币交易数组

`getTokenL1Address()`

获取用于代币操作的第 1 层比特币地址。

async getTokenL1Address(): Promise<string>

返回值:

Promise<string>: 第 1 层比特币地址

`createLightningInvoice(params)`

创建用于接收支付的闪电网络发票。

interface CreateLightningInvoiceParams {
  amountSats: number;
  memo?: string;
  expirySeconds?: number;
}

async createLightningInvoice(params: CreateLightningInvoiceParams): Promise<LightningReceiveRequest>

参数:

params: 包含:
- amountSats: 金额(以聪为单位)
- memo: (可选) 发票的描述
- expirySeconds: (可选) 过期时间(以秒为单位)，默认为 30 天

返回值:

Promise<LightningReceiveRequest>: 闪电网络接收请求详情

示例:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "test invoice",
});
console.log("Invoice:", invoice);

`getLightningReceiveRequest(id: string)`

获取闪电网络接收请求(发票)的状态。

async getLightningReceiveRequest(id: string): Promise<LightningReceiveRequest | null>

参数:

id: 要检查的发票的 ID。

返回值:

Promise<LightningReceiveRequest | null>: 闪电网络接收请求详情，如果未找到则返回 null。

`getLightningSendRequest(id: string)`

获取闪电网络发送请求的状态。

async getLightningSendRequest(id: string): Promise<LightningSendRequest | null>

参数:

id: 要检查的闪电网络发送请求的 ID。

返回值:

Promise<LightningSendRequest | null>: 闪电网络发送请求详情，如果未找到则返回 null。

`getLightningSendFeeEstimate(params)`

估算发送闪电网络支付的费用。

interface LightningSendFeeEstimateInput {
  encodedInvoice: string;
}

async getLightningSendFeeEstimate(params: LightningSendFeeEstimateInput): Promise<number>

参数:

params: 包含:
- encodedInvoice: BOLT11 编码的闪电网络发票。

返回值:

Promise<number>: 估算的费用(以聪为单位)。

`withdraw(params)`

发起提款，将资金从 Spark 网络转移到链上比特币地址。

interface WithdrawParams {
  onchainAddress: string;
  exitSpeed: ExitSpeed;
  amountSats?: number;
  feeQuote: WithdrawalFeeQuote; // 由 getWithdrawalFeeQuote 返回
  deductFeeFromWithdrawalAmount?: boolean; // 默认: true
}

async withdraw(params: WithdrawParams): Promise<CoopExitRequest | null | undefined>

参数:

params: 包含以下属性的对象:
- onchainAddress: (必需) 资金应发送到的比特币地址。
- exitSpeed: (必需) 退出的期望速度(FAST, MEDIUM, SLOW)。
- amountSats: (可选) 要提取的金额(以聪为单位)。如果未指定，尝试提取所有可用资金。
- feeQuote: (必需) 由 getWithdrawalFeeQuote 返回的费用报价对象。必须在过期之前使用。
- deductFeeFromWithdrawalAmount: (可选，默认 true) 为 true 时，费用从提款金额中扣除；为 false 时，费用从剩余钱包余额中扣除。

返回值:

Promise<CoopExitRequest | null | undefined>: 提款请求详情，如果请求无法完成则返回 null/undefined。

示例:

// 1) 获取费用报价
const feeQuote = await wallet.getWithdrawalFeeQuote({
  amountSats: 17000,
  withdrawalAddress:
    "bcrt1pf8hed85p94emupfpfhq2g0p5c40cgzqs4agvvfmeuy32nxeh549syu2lwf",
});

// 2) 在报价过期之前使用它发起提款
const withdraw_result = await wallet.withdraw({
  onchainAddress:
    "bcrt1pf8hed85p94emupfpfhq2g0p5c40cgzqs4agvvfmeuy32nxeh549syu2lwf",
  amountSats: 17000,
  exitSpeed: ExitSpeed.MEDIUM, // 或 ExitSpeed.FAST, ExitSpeed.SLOW
  feeQuote,
  deductFeeFromWithdrawalAmount: true,
});
console.log("Withdraw Result:", withdraw_result);

`getWithdrawalFeeQuote(params)`

获取合作退出(链上提款)的费用报价。返回对象包含不同速度的选项与过期时间，必须在过期前传递给 withdraw。

async getWithdrawalFeeQuote({
  amountSats,
  withdrawalAddress,
}: {
  amountSats: number;
  withdrawalAddress: string;
}): Promise<WithdrawalFeeQuote | null>

参数:

params: 包含:
- amountSats: 要提取的金额(以聪为单位)。
- withdrawalAddress: 资金应发送到的比特币地址。

返回值:

Promise<WithdrawalFeeQuote | null>: 提款的费用报价，如果不可用则返回 null。

`getCoopExitRequest(id: string)`

通过 ID 获取合作退出请求。

async getCoopExitRequest(id: string): Promise<CoopExitRequest | null>

参数:

id: 合作退出请求的 ID。

返回值:

Promise<CoopExitRequest | null>: 合作退出请求详情，如果未找到则返回 null。

`claimDeposit(txId: string)`

认领对一次性存款地址进行的比特币存款。

async claimDeposit(txId: string): Promise<DepositClaimResult>

参数:

txId: 要认领的存款交易的 ID。

返回值:

Promise<DepositClaimResult>: 存款认领的结果。

`isValidSparkAddress(address: string)`

检查一个地址是否是有效的 Spark 地址。

static isValidSparkAddress(address: string): boolean

参数:

address: 要验证的地址。

返回值:

boolean: 如果地址是有效的 Spark 地址则为 true，否则为 false。

事件

SparkWallet 类发出多种事件，允许您监听和响应各种钱包状态变化。

余额更新

wallet.on(
  "balance:update",
  (balance: number, tokenBalances: Map<string, { balance: bigint }>) => {
    console.log(`Balance updated: ${balance}`);
  }
);

存款认领

wallet.on("deposit:claimed", (txId: string, balance: number) => {
  console.log(`Deposit ${txId} claimed. New balance: ${balance}`);
});

闪电网络支付已支付

wallet.on(
  "lightning:paid",
  (invoiceId: string, status: LightningSendStatus) => {
    console.log(`Lightning payment ${invoiceId} status: ${status}`);
  }
);

闪电网络支付已收到

wallet.on(
  "lightning:received",
  (invoiceId: string, status: LightningReceiveStatus, amountSats: number) => {
    console.log(
      `Lightning payment received for invoice ${invoiceId}. Amount: ${amountSats}`
    );
  }
);

合作退出状态变更

wallet.on("coopExit:statusChange", (exitId: string, status: CoopExitStatus) => {
  console.log(`Cooperative exit ${exitId} status changed to ${status}`);
});

转账已认领

wallet.on("transfer:claimed", (transferId: string, balance: number) => {
  console.log(`Transfer ${transferId} claimed. New balance: ${balance}`);
});

常量和枚举

Network

enum Network {
  MAINNET = "MAINNET",
  TESTNET = "TESTNET",
  REGTEST = "REGTEST",
  SIGNET = "SIGNET",
  LOCAL = "LOCAL",
}

ExitSpeed

enum ExitSpeed {
  SLOW = "SLOW",
  MEDIUM = "MEDIUM",
  FAST = "FAST",
}

LightningSendStatus

enum LightningSendStatus {
  CREATED = "CREATED",
  PENDING = "PENDING",
  SUCCESSFUL = "SUCCESSFUL",
  FAILED = "FAILED",
}

LightningReceiveStatus

enum LightningReceiveStatus {
  OPEN = "OPEN",
  PENDING = "PENDING",
  SETTLED = "SETTLED",
  CANCELED = "CANCELED",
  EXPIRED = "EXPIRED",
}

CoopExitStatus

enum CoopExitStatus {
  PENDING = "PENDING",
  BROADCASTED = "BROADCASTED",
  CONFIRMED = "CONFIRMED",
  FAILED = "FAILED",
  CANCELED = "CANCELED",
}

TransferStatus

enum TransferStatus {
  PENDING = "PENDING",
  RECEIVED = "RECEIVED",
  COMPLETE = "COMPLETE",
  FAILED = "FAILED",
}

接口和类型

ConfigOptions

interface ConfigOptions {
  network?: Network;
  apiUrl?: string;
  apiKey?: string;
  mempoolApiUrl?: string;
  logLevel?: "debug" | "info" | "warn" | "error";
}

WalletTransfer

interface WalletTransfer {
  id: string;
  sender: string;
  receiver: string;
  status: TransferStatus;
  totalValue: number;
  expiryTime: Date | undefined;
  createdTime: Date | undefined;
  updatedTime: Date | undefined;
  type: TransferType;
}

LightningReceiveRequest

interface LightningReceiveRequest {
  id: string;
  invoice: string;
  amountSats: number;
  status: LightningReceiveStatus;
  description?: string;
  expiresAt: Date;
  paymentHash: string;
  preimage?: string;
  receivedAt?: Date;
}

LightningSendRequest

interface LightningSendRequest {
  id: string;
  invoice: string;
  amountSats: number;
  status: LightningSendStatus;
  maxFeeSats: number;
  paymentHash: string;
  paidAt?: Date;
  preimage?: string;
  error?: string;
}

CoopExitRequest

interface CoopExitRequest {
  id: string;
  destinationAddress: string;
  amountSats: number;
  fee: number;
  status: CoopExitStatus;
  txId?: string;
  createdAt: Date;
  updatedAt?: Date;
  exitSpeed: ExitSpeed;
}

DepositClaimResult

interface DepositClaimResult {
  success: boolean;
  claimedAmountSats: number;
}

TokenInfo

interface TokenInfo {
  tokenId: string;
  tokenPublicKey: string;
  name: string;
  ticker: string;
  decimalPlaces: number;
  balance: bigint;
  description?: string;
  iconUrl?: string;
  issuerId?: string;
  issuerName?: string;
  totalSupply?: bigint;
  maxSupply?: bigint;
}

概述

从这里开始

开发者指南

文档

UX 指南

​SparkWallet

​安装

​方法

​initialize({ mnemonicOrSeed, signer, options }: SparkWalletProps)

​getIdentityPublicKey()

​getSparkAddress()

​getTransfers(limit?: number, offset?: number)

​getBalance()

​getSingleUseDepositAddress()

​getUnusedDepositAddresses()

​transfer(params)

​payLightningInvoice(params: PayLightningInvoiceParams)

​transferTokens(params)

​getTokenInfo()

​queryTokenTransactions()

​getTokenL1Address()

​createLightningInvoice(params)

​getLightningReceiveRequest(id: string)

​getLightningSendRequest(id: string)

​getLightningSendFeeEstimate(params)

​withdraw(params)

​getWithdrawalFeeQuote(params)

​getCoopExitRequest(id: string)

​claimDeposit(txId: string)

​isValidSparkAddress(address: string)

​事件

​余额更新

​存款认领

​闪电网络支付已支付

​闪电网络支付已收到

​合作退出状态变更

​转账已认领

​常量和枚举

​Network

​ExitSpeed

​LightningSendStatus

​LightningReceiveStatus

​CoopExitStatus

​TransferStatus

​接口和类型

​ConfigOptions

​WalletTransfer

​LightningReceiveRequest

​LightningSendRequest

​CoopExitRequest

​DepositClaimResult

​TokenInfo

SparkWallet

安装

方法

`initialize({ mnemonicOrSeed, signer, options }: SparkWalletProps)`

`getIdentityPublicKey()`

`getSparkAddress()`

`getTransfers(limit?: number, offset?: number)`

`getBalance()`

`getSingleUseDepositAddress()`

`getUnusedDepositAddresses()`

`transfer(params)`

`payLightningInvoice(params: PayLightningInvoiceParams)`

`transferTokens(params)`

`getTokenInfo()`

`queryTokenTransactions()`

`getTokenL1Address()`

`createLightningInvoice(params)`

`getLightningReceiveRequest(id: string)`

`getLightningSendRequest(id: string)`

`getLightningSendFeeEstimate(params)`

`withdraw(params)`

`getWithdrawalFeeQuote(params)`

`getCoopExitRequest(id: string)`

`claimDeposit(txId: string)`

`isValidSparkAddress(address: string)`

事件

余额更新

存款认领

闪电网络支付已支付

闪电网络支付已收到

合作退出状态变更

转账已认领

常量和枚举

Network

ExitSpeed

LightningSendStatus

LightningReceiveStatus

CoopExitStatus

TransferStatus

接口和类型

ConfigOptions

WalletTransfer

LightningReceiveRequest

LightningSendRequest

CoopExitRequest

DepositClaimResult

TokenInfo