Spark签名器接口

概述

Spark SDK 提供了 SparkSigner 接口，以支持灵活的签名操作实现。此抽象允许您自定义加密操作的执行方式，并支持不同的签名策略，包括多重签名配置、硬件钱包和其他专门的密钥管理系统。

SDK 包含一个默认实现（DefaultSparkSigner），用于处理标准的单签名操作。这可以作为实现支持多重签名、硬件钱包或其他高级签名方案的自定义签名器的参考。

getIdentityPublicKey(): Promise<Uint8Array>;
getDepositSigningKey(): Promise<Uint8Array>;
generateStaticDepositKey(idx: number): Promise<Uint8Array>;
getStaticDepositSigningKey(idx: number): Promise<Uint8Array>;
getStaticDepositSecretKey(idx: number): Promise<Uint8Array>;

generateMnemonic(): Promise<string>;
mnemonicToSeed(mnemonic: string): Promise<Uint8Array>;

createSparkWalletFromSeed(
  seed: Uint8Array | string,
  accountNumber?: number,
): Promise<string>;

restoreSigningKeysFromLeafs(leafs: TreeNode[]): Promise<void>;
getTrackedPublicKeys(): Promise<Uint8Array[]>;
// 生成一个新的私钥，并返回公钥
generatePublicKey(hash?: Uint8Array): Promise<Uint8Array>;
// 当不再需要公钥时调用
removePublicKey(publicKey: Uint8Array): Promise<void>;
getSchnorrPublicKey(publicKey: Uint8Array): Promise<Uint8Array>;

signSchnorr(message: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>;
signSchnorrWithIdentityKey(message: Uint8Array): Promise<Uint8Array>;

subtractPrivateKeysGivenPublicKeys(
  first: Uint8Array,
  second: Uint8Array,
): Promise<Uint8Array>;
splitSecretWithProofs(
  params: SplitSecretWithProofsParams,
): Promise<VerifiableSecretShare[]>;

signFrost(params: SignFrostParams): Promise<Uint8Array>;
aggregateFrost(params: AggregateFrostParams): Promise<Uint8Array>;

signMessageWithPublicKey(
  message: Uint8Array,
  publicKey: Uint8Array,
  compact?: boolean,
): Promise<Uint8Array>;
// 如果 compact 为 true，签名应为 ecdsa 紧凑格式，否则应为 DER 格式
signMessageWithIdentityKey(
  message: Uint8Array,
  compact?: boolean,
): Promise<Uint8Array>;
validateMessageWithIdentityKey(
  message: Uint8Array,
  signature: Uint8Array,
): Promise<boolean>;

encryptLeafPrivateKeyEcies(
  receiverPublicKey: Uint8Array,
  publicKey: Uint8Array,
): Promise<Uint8Array>;
decryptEcies(ciphertext: Uint8Array): Promise<Uint8Array>;

getRandomSigningCommitment(): Promise<SigningCommitment>;

hashRandomPrivateKey(): Promise<Uint8Array>;
generateAdaptorFromSignature(signature: Uint8Array): Promise<{
  adaptorSignature: Uint8Array;
  adaptorPublicKey: Uint8Array;
}>;

getDepositSigningKey(): Promise<Uint8Array>;
getMasterPublicKey(): Promise<Uint8Array>;

核心概念

密钥类型

身份密钥（Identity Key）: 用于身份验证的主要钱包标识符
签名密钥（Signing Keys）: 为特定交易输出派生的密钥
存款密钥（Deposit Keys）: 用于接收 L1 比特币存款的密钥
静态存款密钥（Static Deposit Keys）: 用于存款操作的可重复使用密钥

安全模型

所有私钥都使用 BIP32 分层确定性密钥派生从主种子派生。签名器维护公钥与其对应私钥之间的内部映射，确保安全的访问控制。

接口方法

钱包初始化

`generateMnemonic()`

生成用于钱包创建的新 BIP39 助记词短语。

async generateMnemonic(): Promise<string>

返回值:

Promise<string>: 12 个单词的 BIP39 助记词短语

示例:

const mnemonic = await signer.generateMnemonic();
console.log(mnemonic); // "abandon ability able about above absent..."

`mnemonicToSeed(mnemonic: string)`

将 BIP39 助记词短语转换为加密种子。

async mnemonicToSeed(mnemonic: string): Promise<Uint8Array>

参数:

mnemonic: 有效的 BIP39 助记词短语

返回值:

Promise<Uint8Array>: 从助记词派生的 64 字节种子

`createSparkWalletFromSeed(seed, accountNumber?)`

使用主种子初始化签名器并派生所有必要的密钥。

async createSparkWalletFromSeed(
  seed: Uint8Array | string,
  accountNumber?: number,
): Promise<string>

参数:

seed: 主种子（字节数组或十六进制字符串）
accountNumber: （可选，默认值：0）用于密钥派生的账户索引

返回值:

Promise<string>: 十六进制编码的身份公钥

示例:

const seed = await signer.mnemonicToSeed(mnemonic);
const identityPubKey = await signer.createSparkWalletFromSeed(seed, 0);

密钥管理

`getIdentityPublicKey()`

检索钱包的身份公钥。

async getIdentityPublicKey(): Promise<Uint8Array>

返回值:

Promise<Uint8Array>: 身份公钥

`getMasterPublicKey()`

检索主公钥。

async getMasterPublicKey(): Promise<Uint8Array>

返回值:

Promise<Uint8Array>: 主公钥

`generatePublicKey(hash?)`

生成新的签名密钥对并返回公钥。

async generatePublicKey(hash?: Uint8Array): Promise<Uint8Array>

参数:

hash: （可选）用于密钥派生的确定性哈希

返回值:

Promise<Uint8Array>: 生成的公钥

`removePublicKey(publicKey)`

从签名器的跟踪密钥中移除公钥。

async removePublicKey(publicKey: Uint8Array): Promise<void>

参数:

publicKey: 要移除的公钥

`getTrackedPublicKeys()`

返回当前跟踪的所有公钥。

async getTrackedPublicKeys(): Promise<Uint8Array[]>

返回值:

Promise<Uint8Array[]>: 跟踪的公钥数组

存款地址管理

`getDepositSigningKey()`

检索存款签名公钥。

async getDepositSigningKey(): Promise<Uint8Array>

返回值:

Promise<Uint8Array>: 存款签名公钥

`generateStaticDepositKey(idx)`

通过索引生成或检索静态存款密钥。

async generateStaticDepositKey(idx: number): Promise<Uint8Array>

参数:

idx: 静态存款密钥的索引

返回值:

Promise<Uint8Array>: 静态存款公钥

`getStaticDepositSigningKey(idx)`

通过索引检索静态存款签名密钥。

async getStaticDepositSigningKey(idx: number): Promise<Uint8Array>

参数:

idx: 静态存款密钥的索引

返回值:

Promise<Uint8Array>: 静态存款签名公钥

`getStaticDepositSecretKey(idx)`

通过索引检索静态存款私钥。

async getStaticDepositSecretKey(idx: number): Promise<Uint8Array>

参数:

idx: 静态存款密钥的索引

返回值:

Promise<Uint8Array>: 静态存款私钥

数字签名

`signMessageWithIdentityKey(message, compact?)`

使用钱包的身份密钥签名消息。

async signMessageWithIdentityKey(
  message: Uint8Array,
  compact?: boolean,
): Promise<Uint8Array>

参数:

message: 要签名的消息
compact: （可选，默认值：false）使用紧凑签名格式

返回值:

Promise<Uint8Array>: ECDSA 签名（DER 或紧凑格式）

`signMessageWithPublicKey(message, publicKey, compact?)`

使用特定公钥签名消息。

async signMessageWithPublicKey(
  message: Uint8Array,
  publicKey: Uint8Array,
  compact?: boolean,
): Promise<Uint8Array>

参数:

message: 要签名的消息
publicKey: 用于签名的公钥
compact: （可选，默认值：false）使用紧凑签名格式

返回值:

Promise<Uint8Array>: ECDSA 签名（DER 或紧凑格式）

`validateMessageWithIdentityKey(message, signature)`

验证针对身份密钥的签名。

async validateMessageWithIdentityKey(
  message: Uint8Array,
  signature: Uint8Array,
): Promise<boolean>

参数:

message: 原始消息
signature: 要验证的签名

返回值:

Promise<boolean>: 如果签名有效则返回 true

Schnorr 签名

`getSchnorrPublicKey(publicKey)`

将 secp256k1 公钥转换为 Schnorr 格式。

async getSchnorrPublicKey(publicKey: Uint8Array): Promise<Uint8Array>

参数:

publicKey: secp256k1 公钥

返回值:

Promise<Uint8Array>: Schnorr 公钥

`signSchnorr(message, publicKey)`

为消息创建 Schnorr 签名。

async signSchnorr(message: Uint8Array, publicKey: Uint8Array): Promise<Uint8Array>

参数:

message: 要签名的消息
publicKey: 用于签名的公钥

返回值:

Promise<Uint8Array>: Schnorr 签名

`signSchnorrWithIdentityKey(message)`

使用身份密钥创建 Schnorr 签名。

async signSchnorrWithIdentityKey(message: Uint8Array): Promise<Uint8Array>

参数:

message: 要签名的消息

返回值:

Promise<Uint8Array>: Schnorr 签名

高级加密操作

`restoreSigningKeysFromLeafs(leafs)`

从一组树叶节点恢复签名密钥。

async restoreSigningKeysFromLeafs(leafs: TreeNode[]): Promise<void>

参数:

leafs: 树叶节点数组

`subtractPrivateKeysGivenPublicKeys(first, second)`

执行私钥减法并返回结果公钥。

async subtractPrivateKeysGivenPublicKeys(
  first: Uint8Array,
  second: Uint8Array,
): Promise<Uint8Array>

参数:

first: 第一个公钥
second: 第二个公钥

返回值:

Promise<Uint8Array>: 减法后的结果公钥

`splitSecretWithProofs(params)`

实现带有可验证证明的 Shamir 秘密共享。

interface SplitSecretWithProofsParams {
  secret: Uint8Array;
  curveOrder: bigint;
  threshold: number;
  numShares: number;
  isSecretPubkey?: boolean;
}

async splitSecretWithProofs(
  params: SplitSecretWithProofsParams,
): Promise<VerifiableSecretShare[]>

参数:

params: 秘密共享参数

返回值:

Promise<VerifiableSecretShare[]>: 可验证秘密份额数组

FROST 协议（门限签名）

`getRandomSigningCommitment()`

为 FROST 协议生成随机签名承诺。

async getRandomSigningCommitment(): Promise<SigningCommitment>

返回值:

Promise<SigningCommitment>: 随机签名承诺

`signFrost(params)`

执行 FROST 签名操作。

interface SignFrostParams {
  message: Uint8Array;
  privateAsPubKey: Uint8Array;
  publicKey: Uint8Array;
  verifyingKey: Uint8Array;
  selfCommitment: ISigningCommitment;
  statechainCommitments?: { [key: string]: ISigningCommitment };
  adaptorPubKey?: Uint8Array;
}

async signFrost(params: SignFrostParams): Promise<Uint8Array>

参数:

params: FROST 签名参数

返回值:

Promise<Uint8Array>: FROST 签名份额

`aggregateFrost(params)`

将 FROST 签名份额聚合为最终签名。

interface AggregateFrostParams extends Omit<SignFrostParams, "privateAsPubKey"> {
  selfSignature: Uint8Array;
  statechainSignatures?: { [key: string]: Uint8Array };
  statechainPublicKeys?: { [key: string]: Uint8Array };
}

async aggregateFrost(params: AggregateFrostParams): Promise<Uint8Array>

参数:

params: FROST 聚合参数

返回值:

Promise<Uint8Array>: 最终聚合签名

加密

`encryptLeafPrivateKeyEcies(receiverPublicKey, publicKey)`

使用 ECIES 加密叶私钥。

async encryptLeafPrivateKeyEcies(
  receiverPublicKey: Uint8Array,
  publicKey: Uint8Array,
): Promise<Uint8Array>

参数:

receiverPublicKey: 接收方的公钥
publicKey: 要加密其私钥的公钥

返回值:

Promise<Uint8Array>: 加密的私钥

`decryptEcies(ciphertext)`

使用身份密钥解密 ECIES 加密的数据。

async decryptEcies(ciphertext: Uint8Array): Promise<Uint8Array>

参数:

ciphertext: 加密的数据

返回值:

Promise<Uint8Array>: 解密的公钥

实用函数

`hashRandomPrivateKey()`

生成随机私钥的哈希。

async hashRandomPrivateKey(): Promise<Uint8Array>

返回值:

Promise<Uint8Array>: 随机私钥的 SHA256 哈希

`generateAdaptorFromSignature(signature)`

从常规签名生成适配器签名。

async generateAdaptorFromSignature(signature: Uint8Array): Promise<{
  adaptorSignature: Uint8Array;
  adaptorPublicKey: Uint8Array;
}>

参数:

signature: 原始签名

返回值:

包含以下内容的 Promise：
- adaptorSignature: 适配器签名
- adaptorPublicKey: 适配器公钥

Overview

Start Here

Developer Guide

Documentation

UX Guidelines

​概述

​核心概念

​密钥类型

​安全模型

​接口方法

​钱包初始化

​generateMnemonic()

​mnemonicToSeed(mnemonic: string)

​createSparkWalletFromSeed(seed, accountNumber?)

​密钥管理

​getIdentityPublicKey()

​getMasterPublicKey()

​generatePublicKey(hash?)

​removePublicKey(publicKey)

​getTrackedPublicKeys()

​存款地址管理

​getDepositSigningKey()

​generateStaticDepositKey(idx)

​getStaticDepositSigningKey(idx)

​getStaticDepositSecretKey(idx)

​数字签名

​signMessageWithIdentityKey(message, compact?)

​signMessageWithPublicKey(message, publicKey, compact?)

​validateMessageWithIdentityKey(message, signature)

​Schnorr 签名

​getSchnorrPublicKey(publicKey)

​signSchnorr(message, publicKey)

​signSchnorrWithIdentityKey(message)

​高级加密操作

​restoreSigningKeysFromLeafs(leafs)

​subtractPrivateKeysGivenPublicKeys(first, second)

​splitSecretWithProofs(params)

​FROST 协议（门限签名）

​getRandomSigningCommitment()

​signFrost(params)

​aggregateFrost(params)

​加密

​encryptLeafPrivateKeyEcies(receiverPublicKey, publicKey)

​decryptEcies(ciphertext)

​实用函数

​hashRandomPrivateKey()

​generateAdaptorFromSignature(signature)

概述

核心概念

密钥类型

安全模型

接口方法

钱包初始化

`generateMnemonic()`

`mnemonicToSeed(mnemonic: string)`

`createSparkWalletFromSeed(seed, accountNumber?)`

密钥管理

`getIdentityPublicKey()`

`getMasterPublicKey()`

`generatePublicKey(hash?)`

`removePublicKey(publicKey)`

`getTrackedPublicKeys()`

存款地址管理

`getDepositSigningKey()`

`generateStaticDepositKey(idx)`

`getStaticDepositSigningKey(idx)`

`getStaticDepositSecretKey(idx)`

数字签名

`signMessageWithIdentityKey(message, compact?)`

`signMessageWithPublicKey(message, publicKey, compact?)`

`validateMessageWithIdentityKey(message, signature)`

Schnorr 签名

`getSchnorrPublicKey(publicKey)`

`signSchnorr(message, publicKey)`

`signSchnorrWithIdentityKey(message)`

高级加密操作

`restoreSigningKeysFromLeafs(leafs)`

`subtractPrivateKeysGivenPublicKeys(first, second)`

`splitSecretWithProofs(params)`

FROST 协议（门限签名）

`getRandomSigningCommitment()`

`signFrost(params)`

`aggregateFrost(params)`

加密

`encryptLeafPrivateKeyEcies(receiverPublicKey, publicKey)`

`decryptEcies(ciphertext)`

实用函数

`hashRandomPrivateKey()`

`generateAdaptorFromSignature(signature)`