go-bitfs

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

BitFS 仲裁与 2-of-3 结算规范 v1

历史兼容文档，不作为新施工依据。 本文的 HashGetTicket、session_id、服务端记录、proposal_id、仲裁最终金额和签名域属于旧 V1 设计。新设计以 001-报价凭证规范至 006-费用池无条件关闭规范为准；尤其 V1 新关闭路径不在池内定义仲裁金额。

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

BitFS 协议规范 v1

历史兼容文档，不作为新施工依据。 本文描述的 FileQuote、HashGetTicket、session_id、content_index、expected_size、票据价格和签名域，均属于旧 V1 会话模型。新设计按业务顺序以 001-报价凭证规范至 006-费用池无条件关闭规范为准；新实现不得混用两套字段或把本文件的会话 ID 当作真值。

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

从 bsv8-gateway 迁移

go-bitfs 现在是 BitFS v3 文件交换、仲裁与 MultisigPool v4 费用池协议的唯一来源。目录名为 spec/v1 的 CDDL 文件仅因历史路径保留，不能用于当前协议；当前真值是 spec/v3 和 001–007 的 v3 文档。

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

001 · BitFS 报价凭证规范

编码、签名与哈希

所有结构使用 RFC 8949 core deterministic CBOR。TermsCBOR 必须是 FileQuoteTerms 的原始确定性 CBOR 字节：

TermsSignature = Sign_seller(TermsCBOR)
Verify(SellerPubkey, TermsCBOR, TermsSignature)
FileQuoteTermsHash = SHA256(TermsCBOR)

不使用签名域。实现必须只把 TermsSignature 按上述报价条款验证。

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

001 · 报价凭证需求

要解决什么

卖方需要向一个确定买方承诺：某个 seed 对应文件可以怎样出售、种子多少钱、完整文件块多少钱、哪些仲裁者可以接受，以及报价何时失效。

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

002 · v3 费用池开池规范

Buyer 使用 MultisigPool v4 的 ArbitratedPoolRoles{Buyer, Seller, Arbiter} 创建池锁，公钥顺序固定为 [Buyer, Seller, Arbiter]。

Opening/refund state 必须恰好包含三个资金输出：Buyer、Seller、Arbiter。Seller 和 Arbiter 初始金额为 0，Arbiter 输出仍必须存在。Opening sequence 由 v4 返回，当前为 2；go-bitfs 不重写 sequence、locktime、手续费或脚本。

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

002 · 费用池开池需求

要解决什么

买方需要先准备一笔可供后续累计支付的 2-of-3 费用池，但不能因为卖方拒绝后续签名而把资金永久锁死。开池与 BitFS 文件购买无关：它不应知道报价、seed、文件块或价格。

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

003 · v3 内容获取请求规范

003 的业务字段保持原有报价、内容和交付期限语义，编码 major 提升为 3。最终授权固定绑定 pool SpendTxID、base/target sequence、Seller 绝对累计金额、整数费率及 Buyer/Seller/Arbiter 公钥。

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

003 · 内容获取请求需求

要解决什么

买方已经选中报价并拥有可用费用池后，需要向卖方提出“请交付这个确定内容”的请求。请求必须让卖方能够验证：买方选择了自己的哪份报价、使用哪个池的当前支付能力、选了哪个仲裁者、要种子还是某个文件块，以及最晚何时交付。

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

004 · v3 内容交付凭证规范

004 编码 major 为 3，引用 003 的 PaymentAuthorizationHash 并携带内容字节。Seller 对确定性 CBOR 交付条款签名；Buyer 验证内容哈希、报价、期限和 Seller 身份后，才构造 005 无签名状态并产生 detached Buyer signature。

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

004 · 内容交付凭证需求

要解决什么

卖方收到 003 后，需要交付种子本体或文件块本体。交付不能把报价、费用池、仲裁者和请求参数逐项回传；它只要明确回答“这是对哪一张买方请求的交付，以及交付的确切字节是什么”。

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

005 · v3 累计支付规范

005 是对 003 最终付款授权的正常履行消息。交易模板、费用、序号、输出和签名由 MultisigPool v4.0.0 唯一决定；go-bitfs 只传递授权哈希、无签名状态交易和独立 Buyer 签名。

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

005 · 累计支付需求

要解决什么

买方验证 004 的内容后，才签出本次累计付款状态并交给卖方。费用池不为每个块独立扣一笔临时金额，而采用覆盖式的累计支付状态：同一池始终花费同一个基础输出，最新状态完整承接此前已付金额。

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

006 · 费用池关闭需求

要解决什么

买方没有承诺必须购买多少内容，甚至可以一项也不买。因此买方不必请求卖方关闭，也不因卖方不作为而起诉；买方只需等待费用池到期并提交自己在 002 已取得的退款交易。关闭不是对报价、文件或交付重新争论。

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

006 · v3 协商立即关闭规范

立即关闭由 MultisigPool v4 构造最终 sequence/locktime 的三输出无签名状态，Arbiter 输出存在且金额为 0。Buyer 返回无签名交易和 detached Buyer signature；Seller 验证后产生 detached Seller signature，并通过 MergeArbitratedPoolBuyerSellerSignatures 返回完整最终交易。节点确认前不推进本地 accepted state。

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

007 · v3 卖方仲裁提交规范

007 定义 Seller 依据买方最终付款授权请求 Arbiter detached signature 的约束。当前协议 major 为 3，费用池绑定 bitfs.pool.v4，ArbiterAmount = 0。

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

007 · 卖方仲裁提交需求

要解决什么

卖方持有买方已签出的 003 最终付款授权，但买方没有签出本次 005，或正常路径无法完成时，需要仲裁者补足 Seller+Arbiter 的 2-of-3 签名。仲裁者不是买方或卖方的数据库副本，不能只收到一个哈希或 SpendTxID 后再向任何一方查询材料。

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

01 · 协议基础与 CBOR

返回 SDK API 框架入口。

当前代码已落地本页的核心边界：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 协议规范；若本文与编号规范冲突，以编号规范为准。