API 参考

yarn add @buildonspark/spark-sdk

npm i @buildonspark/spark-sdk

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

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

async getIdentityPublicKey(): Promise<string>

async getSparkAddress(): Promise<SparkAddressFormat>

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

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

async getSingleUseDepositAddress(): Promise<string>

async getUnusedDepositAddresses(): Promise<string[]>

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

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

async payLightningInvoice(params: PayLightningInvoiceParams): 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);

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

async getTokenInfo(): Promise<TokenInfo[]>

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

async getTokenL1Address(): Promise<string>

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

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

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

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

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

interface LightningSendFeeEstimateInput {
  encodedInvoice: string;
}

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

interface WithdrawParams {
  onchainAddress: string;
  exitSpeed: ExitSpeed;
  amountSats?: number;
}

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

const withdraw_result = await wallet.withdraw({
  onchainAddress:
    "bcrt1pf8hed85p94emupfpfhq2g0p5c40cgzqs4agvvfmeuy32nxeh549syu2lwf",
  amountSats: 17000,
  exitSpeed: ExitSpeed.MEDIUM, // 或 ExitSpeed.FAST, ExitSpeed.SLOW
});
console.log("Withdraw Result:", withdraw_result);

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

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

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

static isValidSparkAddress(address: string): boolean

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}`);
});

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

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

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

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

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

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

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

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

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

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

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

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

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;
}