SDK 指南 on go-bitfs

Mon, 01 Jan 0001 00:00:00 +0000

01 · 协议基础与 CBOR

当前代码已落地本页的核心边界：bitfs、pool、buyer.Workflow、seller.Workflow、arbitration.Workflow 和 wire 均可直接使用；本文中的伪代码用于说明职责，不替代 Go 包的实际签名。

Mon, 01 Jan 0001 00:00:00 +0000

02 · 外部钩子与数据类型

返回 SDK API 框架入口。

调用方把钱包、持久化、内容源和节点能力注入 SDK。SDK 不要求某个数据库或 RPC 服务。

签名、时间与内容钩子

// Signer 使用调用方托管的私钥签出精确 bytes。
// SDK 永不接收或保存私钥。
type Signer interface {
 PublicKey(ctx context.Context) ([]byte, error)
 Sign(ctx context.Context, payload []byte) ([]byte, error)
}

// SignatureVerifier 验证某个公钥对精确 payload 的签名。
// 001、003、004 使用它；005 使用 MultisigPoolPort 的交易签名校验。
type SignatureVerifier interface {
 Verify(pubkey, payload, signature []byte) error
}

// Clock 使到期校验可测试，且禁止工作流直接调用 time.Now。
type Clock interface {
 NowUnix() UnixSeconds
}

// ContentSource 只由卖方实现。它按内容哈希返回 seed 或块的原始字节。
// 返回的内容仍会由 SDK 再计算哈希和长度。
type ContentSource interface {
 LoadContent(ctx context.Context, hash Hash32) ([]byte, error)
}

// SeedSource 只由买方实现。请求 block 时提供已验证的 seed，SDK 会校验
// seed_hash 以及 block hash 的成员关系。
type SeedSource interface {
 LoadSeed(ctx context.Context, seedHash Hash32) ([]byte, error)
}

// ContentSink 是买方可选的落盘钩子。SDK 在验证 004 后才调用它。
type ContentSink interface {
 SaveVerifiedContent(ctx context.Context, hash Hash32, payload []byte) error
}

存储钩子

存储接口按凭证类别拆分。应用可用同一数据库实现它们，也可完全使用文件或内存。

Mon, 01 Jan 0001 00:00:00 +0000

03 · 角色工作流 API

返回 SDK API 框架入口。

当前实现入口分别是 buyer.NewWorkflow(buyer.WorkflowConfig{...})、seller.NewWorkflow(seller.WorkflowConfig{...}) 和 arbitration.NewWorkflow(arbitration.WorkflowConfig{...})。下文保留为角色级调用顺序说明；细节以包中的实际类型和方法为准。

Mon, 01 Jan 0001 00:00:00 +0000

04 · 实施路线

返回 SDK API 框架入口。

wire、bitfs 的 001/003/004、pool 的 002/005/006、arbitration 的 007 已实现 deterministic CBOR、严格解码和证据校验。
MultisigPool 是费用池交易、SIGHASH_ALL|FORKID、2-of-3 脚本、累计付款、最终关闭和退款到期校验的唯一实现；pool.VerifiedNonFinalPoolNode 负责本地验收和后端响应绑定，具体 BSV RPC 由 NonFinalPoolBackend 注入。
pool.MemoryStore 和 bitfs.FileQuoteStore 已实现线程安全/可重启的参考存储；生产多进程环境应替换为事务数据库，并保留其原子升级、不可变和幂等语义。
buyer.Workflow、seller.Workflow、arbitration.Workflow 已接入端到端集成测试，覆盖报价、开池、内容交付、付款推进和重复付款重试。
当前发布面只包含 BitFS v3 的 buyer.Workflow、seller.Workflow、arbitration.Workflow 与 pool 角色适配器；旧 settlement/runtime 双栈已删除，不存在 legacy build tag 验收路径。

Mon, 01 Jan 0001 00:00:00 +0000

BitFS SDK API 框架设计

本文是 BitFS SDK 的公开 API 蓝图入口，不是 wire 规范，也不是可直接编译的 Go 代码。实际实现必须服从 001–007 协议规范；若本文与编号规范冲突，以编号规范为准。