Skip to main content

buyer

import "github.com/bsv8/go-bitfs/buyer"

Index​

type ArbitratedContentCommand​

ArbitratedContentCommand 携带 008 取回验证所需的本地证据。

type ArbitratedContentCommand struct {
    // Quote 是已验证报价。
    Quote *content.VerifiedQuote
    // Pool 是当前池 checkpoint。
    Pool *PoolCheckpoint
    // Request 是取回所引用授权的 checkpoint（exact 已签 003）。
    Request *AuthorizationCheckpoint
    // RetrievalRequestRaw 是本地保存的 exact Kind 10 bytes（重放原请求，
    // 绝不生成新 nonce）。
    RetrievalRequestRaw []byte
    // RetrievalResponseRaw 是对端返回的 exact Kind 11 bytes。
    RetrievalResponseRaw []byte
    // Seed 在取回批次包含任何块时提供已验证 seed 原文；纯 seed 批次可空。
    Seed []byte
}

type ArbitratedContentResult​

ArbitratedContentResult 是 VerifyArbitratedContent 的统一 Result： Available=false 表示 valid unavailable（已验签协议结果，不是 error），应用 按 UnavailableReason 决定新 nonce、等待或终止；Available=true 时 Payloads 为已验证内容字节，落盘由应用负责。两种分支都不产生 Kind 7 或任何付款状态。

type ArbitratedContentResult struct {
    // ContentRetrievalRequestID 是本应答对应的 exact Kind 10 请求文档哈希。
    ContentRetrievalRequestID protocol.ContentRetrievalRequestID
    // ArbitrationClaimID 是托管记录的仲裁 Claim 身份。
    ArbitrationClaimID protocol.ArbitrationClaimID
    // Available 报告分支结果。
    Available bool
    // UnavailableReason 仅 Available=false 时有意义。
    UnavailableReason arbitration.ContentRetrievalUnavailableReason
    // Payloads 仅 Available=true 时非空：按授权顺序的已验证内容字节。
    Payloads [][]byte
}

type ArbitrationRetrievalCommand​

ArbitrationRetrievalCommand 携带构造 Kind 10 所需的本地证据：opening（经池 checkpoint）+ exact 已签 003。

type ArbitrationRetrievalCommand struct {
    // Pool 是当前池 checkpoint。
    Pool *PoolCheckpoint
    // Authorization 是 exact 已签 003 的 checkpoint。
    Authorization *AuthorizationCheckpoint
}

type AuthorizationCheckpoint​

AuthorizationCheckpoint 记录一次已签 Kind 5 授权的应用侧上下文： PaymentAuthorizationID 是查找键；Request 是 exact 已签 003（发送前必须 先持久化）。

type AuthorizationCheckpoint struct {
    // contains filtered or unexported fields
}

func RestoreAuthorizationCheckpoint​

func RestoreAuthorizationCheckpoint(rawKind1 []byte, rawKind5 []byte, openingProofCBOR []byte) (*AuthorizationCheckpoint, error)

RestoreAuthorizationCheckpoint 从完整本地证据（exact Kind 1 + exact Kind 5 + canonical opening proof）恢复授权 checkpoint：执行时间无关的 003 全链验证 （报价证据与卖方签名、池绑定、买方统一签名、FileQuoteTermsID 与角色绑定）， 并重算 typed ID。报价过期判断由调用方用显式事实完成；后续消费点会再次用 当时的事实做时间门禁。

func (*AuthorizationCheckpoint) AuthorizationID​

func (c *AuthorizationCheckpoint) AuthorizationID() protocol.PaymentAuthorizationID

AuthorizationID 返回本次授权的 typed ID。

func (*AuthorizationCheckpoint) Request​

func (c *AuthorizationCheckpoint) Request() *content.SignedContentRequest

Request 返回深拷贝的 exact 已签 003 凭证。

type ClosePreparationResult​

ClosePreparationResult 是 PrepareClose 的统一 Result：Unsigned 是未签名最终 关闭 candidate，BuyerSignature 是买方 detached 交易签名（均须先持久化再 发送给卖方）。两者都不是 complete transaction。

type ClosePreparationResult struct {
    // Unsigned 是 sequence=4294967295 的未签名关闭 candidate。
    Unsigned *pool.UnsignedPayment
    // BuyerSignature 是买方对该 candidate 的 DER+flag 交易签名。
    BuyerSignature []byte
}

type CompleteOpeningResult​

CompleteOpeningResult 是 CompletePoolOpening 的统一 Result：Opening 是 verified 开池证明；InitialPool 是初始池 checkpoint（应用需持久化）。

type CompleteOpeningResult struct {
    // Opening 是含卖方预签与资金交易原文的完整已验证开池证明。
    Opening *pool.VerifiedOpening
    // InitialPool 是初始池 checkpoint（sequence=2、卖方/仲裁金额为零）。
    InitialPool *PoolCheckpoint
}

type OpeningCheckpoint​

OpeningCheckpoint 是买方本地开池状态（Prepared 阶段产物）：字段私有， getter 防御性复制。应用必须在发送 Kind 2 之前先持久化本 checkpoint 的 evidence；CompletePoolOpening 需要 Request 与 FundingTransactionRaw 原样回传。

type OpeningCheckpoint struct {
    // contains filtered or unexported fields
}

func RestoreOpeningCheckpoint​

func RestoreOpeningCheckpoint(rawKind2 []byte, fundingTransactionRaw []byte) (*OpeningCheckpoint, error)

RestoreOpeningCheckpoint 从应用持久化的 exact evidence（exact Kind 2 bytes + 资金交易原文）恢复开池 checkpoint：严格解析、退款模板 canonical 重建与买方 对模板的交易签名全量验证，并重新派生 RefundTemplateTxID——不信任持久化的 派生字段。

func (*OpeningCheckpoint) FundingTransactionRaw​

func (c *OpeningCheckpoint) FundingTransactionRaw() []byte

FundingTransactionRaw 返回资金交易原始字节副本。

func (*OpeningCheckpoint) RefundTemplateTxID​

func (c *OpeningCheckpoint) RefundTemplateTxID() pool.RefundTemplateTxID

RefundTemplateTxID 返回费用池统一关联 ID。

func (*OpeningCheckpoint) Request​

func (c *OpeningCheckpoint) Request() *pool.RefundPresignRequest

Request 返回深拷贝的已签 Kind 2 预签请求。

type PaymentPreparationResult​

PaymentPreparationResult 是 VerifyDeliveryAndPreparePayment 的统一 Result： Payloads 落盘由应用负责；Outbound 是待发送 exact Kind 7（发送前必须先 持久化 payloads 与本 Result 的全部字段）；NextCandidate 是重建出的目标 未签名状态交易，仅供审计，不进入 wire。

type PaymentPreparationResult struct {
    // Payloads 是按授权顺序排列的已验证 payload 字节。
    Payloads [][]byte
    // Outbound 是待发送 exact Kind 7 最小付款凭证 Artifact。
    Outbound wire.Artifact
    // NextCandidate 是确定性重建的目标未签名状态交易（本地审计用）。
    NextCandidate *pool.UnsignedPayment
}

type PoolCheckpoint​

PoolCheckpoint 是买方本地资金池状态（Verified 阶段产物）：完整开池证明 + 初始/最新付款状态。应用负责持久化其 evidence 并自行判断业务最新状态。

type PoolCheckpoint struct {
    // contains filtered or unexported fields
}

func RestorePoolCheckpoint​

func RestorePoolCheckpoint(openingProofCBOR []byte, paymentRawTx []byte) (*PoolCheckpoint, error)

RestorePoolCheckpoint 从 exact evidence（canonical opening proof 编码 + 当前 完整付款状态 raw tx）恢复池 checkpoint：opening 全量重验（签名/关系），付款 状态经完整双签名验证路径解析——伪造或错池证据都会被拒绝，不信任任何派生字段。

func (*PoolCheckpoint) Opening​

func (c *PoolCheckpoint) Opening() *pool.OpeningProof

Opening 返回深拷贝的完整开池证据。

func (*PoolCheckpoint) Payment​

func (c *PoolCheckpoint) Payment() *pool.PaymentState

Payment 返回深拷贝的当前已验证付款状态。

func (*PoolCheckpoint) RefundTemplateTxID​

func (c *PoolCheckpoint) RefundTemplateTxID() pool.RefundTemplateTxID

RefundTemplateTxID 返回费用池统一关联 ID。

func (*PoolCheckpoint) VerifiedOpening​

func (c *PoolCheckpoint) VerifiedOpening() (*pool.VerifiedOpening, error)

VerifiedOpening 返回经完整重验的不可变 verified opening。

func (*PoolCheckpoint) VerifiedPayment​

func (c *PoolCheckpoint) VerifiedPayment() (*pool.VerifiedPaymentState, error)

VerifiedPayment 返回经完整重验的不可变 verified payment value；验证失败 返回错误而不是降级包装。

type PrepareCloseCommand​

PrepareCloseCommand 携带立即关闭所需输入：调用方自选基准状态与目标金额。

type PrepareCloseCommand struct {
    // Pool 是当前池 checkpoint。
    Pool *PoolCheckpoint
    // Base 是调用方选定的基准付款状态；SDK 不声称它是业务最新。
    Base *pool.PaymentState
    // TargetSellerAmountSatoshis 是最终关闭中卖方的累计金额（绝对聪数）。
    TargetSellerAmountSatoshis protocol.Satoshis
}

type PrepareOpeningCommand​

PrepareOpeningCommand 携带构造 Kind 2 所需的全部显式输入：verified quote、 资金交易、退款锁定、费率与对手方公钥。

type PrepareOpeningCommand struct {
    // Quote 是买方已验证接受的报价（AcceptQuote 的返回值）。
    Quote *content.VerifiedQuote
    // FundingTransactionRaw 是买方资金交易原始字节；输出 0 必须是池输出。
    FundingTransactionRaw []byte
    // ExpiryLockTime 是退款交易的到期锁定时间（低于阈值按区块高解释，否则
    // 按 UTC Unix 时间戳）。
    ExpiryLockTime protocol.RefundLockTime
    // MinerFeeRateSatoshisPerKilobyte 是池内交易矿工费率（每千字节聪数）。
    MinerFeeRateSatoshisPerKilobyte protocol.SatoshisPerKilobyte
    // SellerPublicKey 是卖方压缩公钥。
    SellerPublicKey protocol.PublicKey
    // ArbiterPublicKey 是仲裁方压缩公钥。
    ArbiterPublicKey protocol.PublicKey
}

type PreparePoolOpeningResult​

PreparePoolOpeningResult 是 PreparePoolOpening 的统一 Result：Outbound 是待发送 的 exact Kind 2 Artifact——发送前必须先持久化 Checkpoint。

type PreparePoolOpeningResult struct {
    // Outbound 是待发送 exact Kind 2 wire Artifact。
    Outbound wire.Artifact
    // Checkpoint 是必须先于 Outbound 发送而持久化的买方开池 checkpoint。
    Checkpoint *OpeningCheckpoint
}

type RequestContentCommand​

RequestContentCommand 携带构造一次 003 授权的全部输入。

type RequestContentCommand struct {
    // Quote 是已验证报价。
    Quote *content.VerifiedQuote
    // Pool 是当前池 checkpoint（opening + previous payment state）。
    Pool *PoolCheckpoint
    // ContentHashes 是有序不重复的内容哈希批次（1..64）；等于 SeedHash 即购 seed。
    ContentHashes [][]byte
    // DeliveryDeadline 是交付截止时间（UTC Unix 秒）；必须晚于 Facts.Now 且
    // 不超过报价有效期。
    DeliveryDeadline content.UnixSeconds
    // Seed 在批次包含任何块时必须提供已验证 seed 原文；纯 seed 批次可空。
    Seed []byte
}

type RequestContentResult​

RequestContentResult 是 RequestContent 的统一 Result：Outbound 是待发送的 exact Kind 5 Artifact；AuthorizationID 是路由键；Checkpoint 必须在发送前 与 Outbound 一同持久化。

type RequestContentResult struct {
    // Outbound 是待发送 exact Kind 5 wire Artifact。
    Outbound wire.Artifact
    // AuthorizationID 是本批授权的内容寻址键：SHA-256(exact payment_authorization_cbor)。
    AuthorizationID protocol.PaymentAuthorizationID
    // Checkpoint 保存 exact 已签 003，供 VerifyDeliveryAndPreparePayment 与
    // 仲裁取回路径复用。
    Checkpoint *AuthorizationCheckpoint
}

type VerifyCloseCommand​

VerifyCloseCommand 携带验收卖方完整关闭交易所需的证据。

type VerifyCloseCommand struct {
    // Pool 是当前池 checkpoint（用于 opening 归属绑定）。
    Pool *PoolCheckpoint
    // Close 是卖方合并后的完整关闭交易。
    Close *pool.SignedPayment
}

type VerifyDeliveryCommand​

VerifyDeliveryCommand 携带验收一次 004 交付所需的全部证据。

type VerifyDeliveryCommand struct {
    // Quote 是已验证报价。
    Quote *content.VerifiedQuote
    // Pool 是当前池 checkpoint。
    Pool *PoolCheckpoint
    // Request 是本批次的授权 checkpoint（RequestContent 返回并持久化者）。
    Request *AuthorizationCheckpoint
    // DeliveryRaw 是对端发来的 exact Kind 6 bytes。
    DeliveryRaw []byte
    // Seed 在批次包含任何块时提供已验证 seed 原文；纯 seed 批次可空。
    Seed []byte
}

type Workflow​

Workflow 是 Buyer 角色 API（001–006 与 008 取回）。它只持有固定的受约束 Signer 及其派生公钥；没有存储、网络、节点、时钟或广播副作用。所有时间与 高度判断使用调用方显式传入的一份 Facts；签名一律由 SDK 构造 digest 后交给 Signer 并固定自验。

type Workflow struct {
    // contains filtered or unexported fields
}

func NewWorkflow​

func NewWorkflow(signer protocol.Signer) (*Workflow, error)

NewWorkflow 固定并验证 Signer 公钥后返回 Buyer 角色 API。直接私钥必须经 protocol.NewPrivateKeySigner 进入，不存在第二构造器。

func (*Workflow) AcceptQuote​

func (workflow *Workflow) AcceptQuote(facts protocol.Facts, rawKind1 []byte) (*content.VerifiedQuote, error)

AcceptQuote 严格解析 exact Kind 1 bytes，验签、过期判断（唯一时间事实为 facts.Now）与买方归属绑定全部通过后，返回不可变 VerifiedQuote。本操作是 纯验证：不签名、无长计算，因此不接收 context。应用决定保存位置。

func (*Workflow) BuildMaturedRefund​

func (workflow *Workflow) BuildMaturedRefund(facts protocol.Facts, poolCheckpoint *PoolCheckpoint) (*pool.VerifiedSignedTransaction, error)

BuildMaturedRefund 在显式事实判定退款到期后合并双方退款签名，返回可广播的 verified refund transaction；是否广播由应用决定。

func (*Workflow) CompletePoolOpening​

func (workflow *Workflow) CompletePoolOpening(checkpoint *OpeningCheckpoint, rawKind3 []byte) (*CompleteOpeningResult, error)

CompletePoolOpening 用保存的 OpeningCheckpoint 验收 exact Kind 3：重派生池 ID 并拒绝任何错配，验卖方预签，产出 verified opening + 初始池 checkpoint。 纯验证路径：不接收 context。

func (*Workflow) PrepareClose​

func (workflow *Workflow) PrepareClose(ctx context.Context, facts protocol.Facts, command PrepareCloseCommand) (*ClosePreparationResult, error)

PrepareClose 从调用方选定的基准状态与目标金额构造未签名关闭 candidate 和 买方 detached 签名。SDK 不声称 base 是业务最新，也不判断目标金额是否符合 订单或账本；不广播。

func (*Workflow) PrepareFundingDelivery​

func (workflow *Workflow) PrepareFundingDelivery(poolCheckpoint *PoolCheckpoint) (wire.Artifact, error)

PrepareFundingDelivery 把 verified opening 携带的资金交易打包成 Kind 4 Artifact；纯打包路径，不接收 context；不广播资金交易——广播边界属于应用。

func (*Workflow) PreparePoolOpening​

func (workflow *Workflow) PreparePoolOpening(ctx context.Context, command PrepareOpeningCommand) (*PreparePoolOpeningResult, error)

PreparePoolOpening 构造并签署 Kind 2 预签请求：返回待发送 Artifact 与必须 先持久化的 OpeningCheckpoint。本操作不含任何时间/高度判断（纯交易构造）， 因此不接收 Facts，也不接收无用参数。资金交易原文只存在于 checkpoint；SDK 不持久化。

func (*Workflow) PublicKey​

func (workflow *Workflow) PublicKey() []byte

PublicKey 返回本角色的固定压缩公钥副本。

func (*Workflow) RequestArbitratedContent​

func (workflow *Workflow) RequestArbitratedContent(ctx context.Context, command ArbitrationRetrievalCommand) (wire.Artifact, error)

RequestArbitratedContent 为一条托管记录构造 exact Kind 10 Artifact：默认入口 由 SDK 生成安全随机 nonce；网络超时重试必须原样重放已持久化的 Artifact， 绝不能重新调用本方法生成新 nonce。

func (*Workflow) RequestContent​

func (workflow *Workflow) RequestContent(ctx context.Context, facts protocol.Facts, command RequestContentCommand) (*RequestContentResult, error)

RequestContent 验证报价/池/批次上下文/聚合价格/余额后签署 003：返回待发送 Kind 5 Artifact、授权 typed ID 与必须先持久化的 AuthorizationCheckpoint。

func (*Workflow) VerifyArbitratedContent​

func (workflow *Workflow) VerifyArbitratedContent(ctx context.Context, command ArbitratedContentCommand) (*ArbitratedContentResult, error)

VerifyArbitratedContent 时间无关地验收 exact Kind 10/11：available 分支额外 复核 payload 归属与价格；unavailable 分支作为已验签协议结果返回。过期报价、 截止或退款锁定绝不拒绝已签托管证据；available 不生成 Kind 7。

func (*Workflow) VerifyCompletedClose​

func (workflow *Workflow) VerifyCompletedClose(command VerifyCloseCommand) (*pool.VerifiedSignedTransaction, error)

VerifyCompletedClose 验证卖方完整关闭交易在给定 opening 下密码学、结构与 交易关系全部正确，返回不可变 Complete 结果；不声称已广播或已确认。

func (*Workflow) VerifyDeliveryAndPreparePayment​

func (workflow *Workflow) VerifyDeliveryAndPreparePayment(ctx context.Context, facts protocol.Facts, command VerifyDeliveryCommand) (*PaymentPreparationResult, error)

VerifyDeliveryAndPreparePayment 验收 exact Kind 6 并产生整个批次的唯一 Kind 7 签名凭证。方法名显式暴露"会产生买方交易签名"；先保存 payloads 与 Result 再发送 Outbound。

Generated by gomarkdoc