跳到主要内容

arbitration

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

统一 wire 模型下的 Kind 10/11 买方托管取回。Kind 10 携带买方签名的 content_retrieval_request_cbor = [arbitration_claim_id, retrieval_nonce]。Kind 11 是显式判别的两分支 union，由仲裁方通过统一 SignWireDocument(1, 11, ...) helper 签名：分支 0 以结构化原因回答“当前不可交付”且不携带附件；分支 1 通过 SHA-256 content_payloads_id 绑定 exact content_payloads_cbor 并原样附带 payload。不再存在任何内嵌的 Kind 8/9 字节。

Package arbitration 是 007/008 的纯领域包：Kind 8/9 托管证据、Kind 10/11 取回报文的 DTO、确定性编解码、证据链验证与取回结果验证。它不持有任何角色 身份或签名能力；角色编排位于 arbiter/buyer/seller 包，签名一律经受约束 protocol.Signer 进入。

Kind 9 是硬切换后的四元回执应答：仲裁方获得一笔由调用方显式决定的正数 仲裁费，回执通过一次普通消息签名把 Claim ID、该费用与仲裁交易签名绑定为 单一真值；arbitration_claim_id = SHA-256(exact claim cbor)。

索引​

常量​

const (

    // RetrievalNonceBytes is the fixed width of the replay key. 默认入口由
    // SDK 用 crypto/rand 经 protocol.GenerateRetrievalNonce 生成；显式 nonce
    // 的底层入口只服务测试与恢复路径。
    RetrievalNonceBytes = sha256.Size

    // MinContentRetrievalSignatureBytes is the lower bound of the DER buyer
    // retrieval signature child.
    MinContentRetrievalSignatureBytes = 1

    // MaxContentRetrievalRequestBytes is derived from the four-element wire
    // shape [1, 10, request_cbor(3+69), signature(3+256)]:
    // 1 + 1 + 1 + 72 + 259 = 334 bytes.
    MaxContentRetrievalRequestBytes = 1 + 1 + 1 + maxSignatureBstrOverhead + maxContentRetrievalRequestDocBytes + maxSignatureBstrOverhead + MaxArbitrationSignatureBytes

    // MaxContentRetrievalUnavailableBytes is the fixed upper size of the
    // unavailable branch [1, 11, result(3+70), signature(3+256)] = 335.
    MaxContentRetrievalUnavailableBytes = 1 + 1 + 1 + maxSignatureBstrOverhead + maxContentRetrievalResultDocBytes + maxSignatureBstrOverhead + MaxArbitrationSignatureBytes

    // MaxContentRetrievalAvailableBytes is derived from the five-element
    // available branch shape [1, 11, result(3+70), signature(3+256),
    // payloads(uint32 head + bundle)]. It is not an independent quota.
    MaxContentRetrievalAvailableBytes = 1 + 1 + 1 + maxSignatureBstrOverhead + maxContentRetrievalResultDocBytes + maxSignatureBstrOverhead + MaxArbitrationSignatureBytes + 5 + content.MaxContentPayloadsCBORBytes

    // MaxContentRetrievalResponseBytes is the single pre-allocation guard used
    // before the branch discriminator is known; the unavailable branch is
    // strictly smaller than the available one.
    MaxContentRetrievalResponseBytes = MaxContentRetrievalAvailableBytes
)

Kind 8/9 的统一 wire Kind 值；版本只使用 protocol.WireVersion。

const (

    // These are protocol limits, applied before CBOR decoding. They bound both
    // the outer messages and the large bstr children that a decoder would
    // otherwise allocate before semantic validation. Applications may impose
    // smaller transport limits, but must not silently raise these limits.
    MaxArbitrationSignatureBytes      = 256
    MaxArbitrationRefundTemplateBytes = 16 * 1024
    MaxArbitrationAuthorizationBytes  = 16 * 1024
    MaxArbitrationClaimBytes          = 64 * 1024

    // MaxArbitrationReceiptBytes is derived from the Receipt child limits:
    // [claim_id(34), amount(9), transaction_signature(3+256)] plus the array
    // head = 1 + 34 + 9 + 259 = 303. It is intentionally NOT an independent
    // quota; raising it silently or shrinking it below the child limits breaks
    // interoperability.
    MaxArbitrationReceiptBytes = 1 + maxClaimIDBstrBytes + maxDeterministicUint64Bytes + maxSignatureBstrOverhead + MaxArbitrationSignatureBytes

    // MaxArbitrationResponseBytes is derived from the four-element response
    // shape [1, 9, receipt_cbor, receipt_signature]: array head, version,
    // kind, the receipt wrapped in a uint16-headed bstr, and the receipt
    // signature = 1 + 1 + 1 + (3 + 303) + (3 + 256) = 568.
    MaxArbitrationResponseBytes = 1 + 1 + 1 + maxSignatureBstrOverhead + MaxArbitrationReceiptBytes + maxSignatureBstrOverhead + MaxArbitrationSignatureBytes
)

MaxArbitrationRequestBytes 是 Kind 8 外层报文的完整 wire 字节上限： payload 上限 + Claim 上限 + 签名上限 + 固定外壳开销。它是公开常量， wire 层全局解析上限必须以它为下界之一，否则合法满载 Kind 8 会在进入 typed decoder 之前被误判为 malformed_wire。

const MaxArbitrationRequestBytes = contentMaxPayloadsLimit + MaxArbitrationClaimBytes + MaxArbitrationSignatureBytes + maxArbitrationRequestEnvelopeBytes

函数 ArbitrationClaimID​

func ArbitrationClaimID(claimCBOR []byte) (protocol.ArbitrationClaimID, error)

ArbitrationClaimID 返回 SHA-256(exact_claim_cbor)，作为 Kind 8 文档命名空间内的 typed Claim 身份。Claim 文档是唯一的 ID 来源；任何签名域包装都不参与身份计算。

函数 AuthenticateContentRetrievalRequest​

func AuthenticateContentRetrievalRequest(retrievalRequest *ContentRetrievalRequest, storedArbitrationRequest *ArbitrationRequest, arbiterPublicKey []byte) error

AuthenticateContentRetrievalRequest 只依赖已持久化的 Kind 8 完成 Buyer 鉴权， 不要求 Kind 9 已存在。它是时间无关纯函数：先从 Claim 的资金池锁定脚本恢复 角色公钥，确认 Claim 归属目标 Arbiter 公钥，再通过统一 helper 验证 Buyer 对 精确 content_retrieval_request_cbor 的签名。任何其他 Claim ID、nonce 或 Kind 域下的有效签名都不可能通过。

函数 DecodeContentRetrievalRequestDocument​

func DecodeContentRetrievalRequestDocument(data []byte) (protocol.ArbitrationClaimID, []byte, error)

DecodeContentRetrievalRequestDocument 严格解码子文档并返回其 Claim ID 与 nonce 的深拷贝。

函数 EncodeContentRetrievalRequestDocument​

func EncodeContentRetrievalRequestDocument(claimID protocol.ArbitrationClaimID, nonce []byte) ([]byte, error)

EncodeContentRetrievalRequestDocument 在强制两项字段约束后返回精确规范的子文档 [arbitration_claim_id, retrieval_nonce]。

函数 EncodeContentRetrievalResultDocument​

func EncodeContentRetrievalResultDocument(requestID protocol.ContentRetrievalRequestID, result ContentRetrievalResult, branchValue []byte) ([]byte, error)

EncodeContentRetrievalResultDocument 为任一分支构造精确规范的 content_retrieval_result_cbor。判别值决定第三个元素的含义；调用方无法混用分支。

函数 MarshalClaim​

func MarshalClaim(claim *ArbitrationClaim) ([]byte, error)

MarshalClaim 编码 canonical 五元确定性 CBOR 子文档。

函数 MarshalContentRetrievalRequest​

func MarshalContentRetrievalRequest(request *ContentRetrievalRequest) ([]byte, error)

MarshalContentRetrievalRequest 编码规范的四元 Kind 10。

函数 MarshalContentRetrievalResponse​

func MarshalContentRetrievalResponse(response *ContentRetrievalResponse) ([]byte, error)

MarshalContentRetrievalResponse 按 ContentRetrievalResultCBOR 声明的分支编码规范的 Kind 11。

函数 MarshalReceipt​

func MarshalReceipt(receipt *ArbitrationReceipt) ([]byte, error)

MarshalReceipt 把回执编码为规范的三元确定性 CBOR 子文档。

函数 MarshalRequest​

func MarshalRequest(request *ArbitrationRequest) ([]byte, error)

MarshalRequest 编码完整 Kind 8 wire 报文：[1, 8, claim_cbor, seller_claim_signature, content_payloads_cbor]。

函数 MarshalResponse​

func MarshalResponse(response *ArbitrationResponse) ([]byte, error)

MarshalResponse 编码完整 Kind 9 wire 报文：[1, 9, receipt_cbor, arbiter_receipt_signature]。

函数 ValidateClaim​

func ValidateClaim(claim *ArbitrationClaim) error

ValidateClaim 验证已解码仲裁 Claim：正数池输出、canonical 2-of-3 锁定脚本、有界的退款模板与授权子文档，以及买方对 exact Kind 5 文档的签名。它是纯证据检查；此处没有任何费用、deadline 或时钟输入。

函数 ValidateContentRetrievalRequest​

func ValidateContentRetrievalRequest(request *ContentRetrievalRequest) error

ValidateContentRetrievalRequest 强制 Kind 10 的固定外形：子文档内的规范 32 字节 Claim ID 加非零 nonce，以及对精确该文档的有界 DER 签名。

函数 ValidateContentRetrievalResponse​

func ValidateContentRetrievalResponse(response *ContentRetrievalResponse) error

ValidateContentRetrievalResponse 强制分支一致的结构：ContentRetrievalResultCBOR 内的判别值决定是否允许附件存在。

函数 ValidateReceipt​

func ValidateReceipt(receipt *ArbitrationReceipt) error

ValidateReceipt 校验解码后的仲裁回执：固定 32 字节 Claim ID、正仲裁费和有界的交易签名。

函数 ValidateRequest​

func ValidateRequest(request *ArbitrationRequest) error

ValidateRequest 强制 exact 五元 Kind 8 形状：有界 Claim 子文档、卖方签名与 canonical payload 附件。

函数 ValidateResponse​

func ValidateResponse(response *ArbitrationResponse) error

ValidateResponse 强制四元 Kind 9 形状：有界回执子文档加仲裁方统一回执签名。

函数 VerifySellerClaimSignature​

func VerifySellerClaimSignature(request *ArbitrationRequest, keys pool.MultisigPoolPublicKeys) error

VerifySellerClaimSignature 验证卖方对精确 Claim 文档的统一签名；供角色包 在完整证据链之外复用（例如 seller 仲裁路径的本地证据检查）。

类型 ArbitrationClaim​

ArbitrationClaim 是无版本、无 Kind 的 Kind 8 内层认证文档。它的精确字节既是业务真值也是 Claim ID 的来源：arbitration_claim_id = SHA-256(arbitration_claim_cbor)。

type ArbitrationClaim struct {
    // PoolOutputSatoshis 是被托管资金池输出的聪数（uint64）；仲裁 candidate
    // 的输入金额必须与它一致。
    PoolOutputSatoshis uint64
    // PoolOutputLockingScript 是角色顺序固定 [Buyer, Seller, Arbiter] 的
    // 2-of-3 压缩公钥锁定脚本（恰好 105 字节）；三方公钥由它恢复。
    PoolOutputLockingScript []byte
    // RefundTemplateRaw 是规范未签名退款模板交易的原始字节；到期后买方凭它
    // 广播退款，仲裁方用它派生 refund_template_txid 与保留矿工费。
    RefundTemplateRaw []byte
    // PaymentAuthorizationCBOR 是买方签名的 exact Kind 5 付款授权子文档；
    // 目标序号与绝对卖方金额由此提供，绝不解码重编码。
    PaymentAuthorizationCBOR []byte
    // BuyerPaymentAuthorizationSignature 是买方对 WireSignatureInput(1, 5,
    // payment_authorization_cbor) 的统一消息签名。
    BuyerPaymentAuthorizationSignature []byte
}

函数 UnmarshalClaim​

func UnmarshalClaim(data []byte) (*ArbitrationClaim, error)

UnmarshalClaim 严格解码 Claim 字节：先查大小上限，严格解码，验证，再做确定性重编码逐字节相等比较。

函数 ValidateRequestEvidence​

func ValidateRequestEvidence(request *ArbitrationRequest, arbiterAmountSatoshis uint64) (*ArbitrationClaim, *content.PaymentAuthorization, [][]byte, *pool.UnsignedPayment, protocol.ArbitrationClaimID, protocol.PaymentAuthorizationID, pool.MultisigPoolPublicKeys, error)

validateRequestEvidence performs the complete pre-signature evidence chain: strict Kind 8 decoding, Claim and authorization validation, role recovery, Buyer and Seller signature checks, per-payload hash verification, and independent candidate reconstruction with the explicit arbitration fee. The zero-fee rejection lives in the success builder, so no caller ever passes a placeholder amount. 它是纯证据函数：无时钟、无高度、无签名副作用。

类型 ArbitrationReceipt​

ArbitrationReceipt 是无版本、无 kind 的 Kind 9 内层文档。它绑定精确的 Claim ID、由 output[2] 支付的绝对仲裁费，以及对独立重建 candidate 的 ForkID|All 交易签名。成功回执的费用必须为正。

type ArbitrationReceipt struct {
    // ArbitrationClaimID 路由本回执对应的托管记录（SHA-256(exact claim cbor)）；
    // 必须与验证时重算的 Claim ID 一致。
    ArbitrationClaimID protocol.ArbitrationClaimID
    // ArbiterAmountSatoshis 是分配给 output[2] 的冻结绝对仲裁费（单位
    // satoshi）；成功回执恒为正数。
    ArbiterAmountSatoshis uint64
    // ArbiterPaymentTransactionSignature 是仲裁方对独立重建付费 candidate 的
    // ForkID|All 原生交易签名；不能替代回执普通消息签名。
    ArbiterPaymentTransactionSignature []byte
}

函数 UnmarshalReceipt​

func UnmarshalReceipt(data []byte) (*ArbitrationReceipt, error)

UnmarshalReceipt 严格解码回执字节：先做长度上限检查，再严格解码、校验，最后要求与确定性重编码逐字节相等。

类型 ArbitrationRequest​

ArbitrationRequest 是精确的五元 Kind 8 报文。ArbitrationClaimCBOR 是精确确定的 ArbitrationClaim 子文档；它在 wire 上不会被解码再重编码。

type ArbitrationRequest struct {
    // ArbitrationClaimCBOR 是 exact 确定性 Claim 子文档字节；wire 不解码重编码，
    // arbitration_claim_id = SHA-256(该字段)。
    ArbitrationClaimCBOR []byte
    // SellerArbitrationClaimSignature 是卖方对 WireSignatureInput(1, 8,
    // arbitration_claim_cbor) 的统一消息签名；payload 不直接入签。
    SellerArbitrationClaimSignature []byte
    // ContentPayloadsCBOR 是确定性 CBOR payload 批次（attachment）：顺序与
    // 授权哈希一一对应，经买方已签 content_hashes_cbor 间接绑定。
    ContentPayloadsCBOR []byte
}

函数 CloneRequest​

func CloneRequest(request *ArbitrationRequest) *ArbitrationRequest

CloneRequest 返回深拷贝的 Kind 8 请求（跨包防御性复制边界）。

函数 UnmarshalRequest​

func UnmarshalRequest(data []byte) (*ArbitrationRequest, error)

UnmarshalRequest 严格解码 Kind 8 字节：先查大小上限，严格解码，外层 version/kind 检查，验证，再确定性重编码逐字节相等。

类型 ArbitrationResponse​

ArbitrationResponse 是精确的四元 Kind 9 报文。ArbitrationReceiptCBOR 是精确确定的 ArbitrationReceipt 子文档；它在 wire 上不会被解码再重编码。

type ArbitrationResponse struct {
    // ArbitrationReceiptCBOR 是 exact 确定性回执子文档字节；wire 不解码重编码。
    ArbitrationReceiptCBOR []byte
    // ArbiterArbitrationReceiptSignature 是仲裁方对 WireSignatureInput(1, 9,
    // arbitration_receipt_cbor) 的统一消息签名，把 Claim ID、费用和交易签名绑定在一起。
    ArbiterArbitrationReceiptSignature []byte
}

函数 CloneResponse​

func CloneResponse(response *ArbitrationResponse) *ArbitrationResponse

CloneResponse 返回深拷贝的 Kind 9 应答（跨包防御性复制边界）。

函数 UnmarshalResponse​

func UnmarshalResponse(data []byte) (*ArbitrationResponse, error)

UnmarshalResponse 严格解码 Kind 9 字节：先查大小上限，严格解码，外层 version/kind 检查，验证，再确定性重编码逐字节相等。

类型 BuiltClaim​

BuiltClaim 是从完整 OpeningProof 和买方签名付款授权装配 exact Kind 8 Claim 证据的共享、时间无关结果。Seller 仲裁（007）与买方内容取回（008）共用这一个 builder，因此两个角色总是从相同的 opening 加授权得到逐字节一致的 ArbitrationClaimCBOR 和 ArbitrationClaimID。

type BuiltClaim struct {
    // Claim 是 ArbitrationClaimCBOR 背后的已解码、深拷贝 Claim 证据。
    Claim *ArbitrationClaim
    // ArbitrationClaimCBOR 是精确规范的五元 Claim 子文档字节。
    ArbitrationClaimCBOR []byte
    // ArbitrationClaimID = SHA-256(exact_claim_cbor)，Seller 与 Buyer 独立重建必得同一值。
    ArbitrationClaimID protocol.ArbitrationClaimID
    // Authorization 是 Claim 携带的已解码 Kind 5 付款授权（含目标序号与绝对卖方金额）。
    Authorization *content.PaymentAuthorization
}

函数 BuildClaimFromAuthorization​

func BuildClaimFromAuthorization(opening *pool.OpeningProof, signedAuthorization *content.SignedContentRequest) (*BuiltClaim, error)

BuildClaimFromAuthorization 从提供的 OpeningProof 派生资金池输出事实，验证签名付款授权确属该 opening，装配并规范编码 Claim，最后计算其 Claim ID。它克隆全部输入，不施加任何时钟或区块高度门禁，也不产生签名；deadline/退款门禁仍由调用方 workflow 负责。

类型 ContentRetrievalRequest​

ContentRetrievalRequest 是精确的四元 Kind 10 报文。它不携带买方公钥、OpeningProof、付款授权、Claim 字节或付款授权 ID：仲裁方从 ContentRetrievalRequestCBOR 内 Claim ID 所指存储 Claim 恢复全部角色公钥。

type ContentRetrievalRequest struct {
    // ContentRetrievalRequestCBOR 是 exact 规范子文档
    // [arbitration_claim_id, retrieval_nonce]；它是买方唯一签署的对象，
    // 其 SHA-256 即 content_retrieval_request_id。
    ContentRetrievalRequestCBOR []byte
    // BuyerContentRetrievalRequestSignature 是买方对 WireSignatureInput(1, 10,
    // content_retrieval_request_cbor) 的统一消息签名。
    BuyerContentRetrievalRequestSignature []byte
}

函数 CloneContentRetrievalRequest​

func CloneContentRetrievalRequest(request *ContentRetrievalRequest) *ContentRetrievalRequest

CloneContentRetrievalRequest 返回深拷贝的 Kind 10（跨包防御性复制边界）。

函数 NewContentRetrievalRequest​

func NewContentRetrievalRequest(ctx context.Context, claimID protocol.ArbitrationClaimID, nonce protocol.RetrievalNonce, signer protocol.Signer) (*ContentRetrievalRequest, error)

NewContentRetrievalRequest builds and signs a complete Kind 10 through the unified SignWireDocument(1, 10, ...) helper with the supplied constrained Signer and self-verifies the result. 这是显式 nonce 的底层入口：nonce 必须是 SDK 生成的 typed 随机数（测试/恢复路径）；普通角色 API 不接受任意 []byte。

函数 UnmarshalContentRetrievalRequest​

func UnmarshalContentRetrievalRequest(data []byte) (*ContentRetrievalRequest, error)

UnmarshalContentRetrievalRequest 严格解码 Kind 10 字节：尺寸上限、严格形状、版本/kind 检查、语义验证，最后是确定性往返相等校验。

类型 ContentRetrievalResponse​

ContentRetrievalResponse 是精确的 Kind 11 报文。ContentRetrievalResultCBOR 内的判别值选择唯一合法的外层形状：

unavailable: [1, 11, result_cbor, signature]
available:   [1, 11, result_cbor, signature, content_payloads_cbor]
type ContentRetrievalResponse struct {
    // ContentRetrievalResultCBOR 是 exact 规范结果子文档
    // [content_retrieval_request_id, result, branch_value]；判别值决定外层形状。
    ContentRetrievalResultCBOR []byte
    // ArbiterContentRetrievalResultSignature 是仲裁方对 WireSignatureInput(1, 11,
    // content_retrieval_result_cbor) 的统一消息签名（两分支同域）。
    ArbiterContentRetrievalResultSignature []byte
    // ContentPayloadsCBOR 仅 available 分支存在：exact content_payloads_cbor
    // attachment，经签名的 content_payloads_id 绑定；unavailable 分支禁止携带。
    ContentPayloadsCBOR []byte
}

函数 BuildContentRetrievalAvailable​

func BuildContentRetrievalAvailable(ctx context.Context, requestID protocol.ContentRetrievalRequestID, payloads [][]byte, signer protocol.Signer) (*ContentRetrievalResponse, error)

BuildContentRetrievalAvailable 构造并签署 Kind 11 的正向分支。payload bundle 在此规范编码，因此签名的 content_payloads_id 总是绑定实际附带的字节。

函数 BuildContentRetrievalAvailableRaw​

func BuildContentRetrievalAvailableRaw(ctx context.Context, requestID protocol.ContentRetrievalRequestID, payloadsCBOR []byte, signer protocol.Signer) (*ContentRetrievalResponse, error)

BuildContentRetrievalAvailableRaw 是 BuildContentRetrievalAvailable 的原始字节变体，供持久化 exact canonical payload bundle 的应用使用。bundle 必须已经是规范形式。

函数 BuildContentRetrievalUnavailable​

func BuildContentRetrievalUnavailable(ctx context.Context, requestID protocol.ContentRetrievalRequestID, reason ContentRetrievalUnavailableReason, signer protocol.Signer) (*ContentRetrievalResponse, error)

BuildContentRetrievalUnavailable 经受约束 Signer 构造并签署 Kind 11 否定分支。调用方只提供结构合法的请求 ID 与诚实原因；签署后的应答不携带 Claim、角色公钥、payload 或记录元数据。

函数 CloneContentRetrievalResponse​

func CloneContentRetrievalResponse(response *ContentRetrievalResponse) *ContentRetrievalResponse

CloneContentRetrievalResponse 返回深拷贝的 Kind 11（跨包防御性复制边界）。

函数 UnmarshalContentRetrievalResponse​

func UnmarshalContentRetrievalResponse(data []byte) (*ContentRetrievalResponse, error)

UnmarshalContentRetrievalResponse 严格解码 Kind 11 字节。它先检查尺寸上限，再检查外层版本/kind 对，然后在接受该分支唯一合法的外层长度之前读取 ContentRetrievalResultCBOR 的分支判别值。任何不匹配、尾随字段、未知原因或非规范编码都会被拒绝。

类型 ContentRetrievalResult​

ContentRetrievalResult 判别 Kind 11 的两个分支。

type ContentRetrievalResult uint64
const (
    // ContentRetrievalUnavailable: the arbiter currently cannot deliver the
    // custodied content to this buyer.
    ContentRetrievalUnavailable ContentRetrievalResult = 0
    // ContentRetrievalAvailable: the arbiter completed the internal state
    // transition required for retrieval and attached the payloads.
    ContentRetrievalAvailable ContentRetrievalResult = 1
)

类型 ContentRetrievalUnavailableReason​

ContentRetrievalUnavailableReason 枚举 Kind 11 unavailable 分支可以携带的三种诚实原因。

type ContentRetrievalUnavailableReason uint64
const (
    // RetrievalSellerArbitrationNotReceived: no Kind 8 custody record exists
    // for this Claim ID.
    RetrievalSellerArbitrationNotReceived ContentRetrievalUnavailableReason = 0
    // RetrievalSellerArbitrationNotReady: the Kind 8 record exists and is
    // persisted, but the Kind 9 receipt has not been completed.
    RetrievalSellerArbitrationNotReady ContentRetrievalUnavailableReason = 1
    // RetrievalCustodyGone: a complete custody record existed but the content
    // was deleted under the public retention policy.
    RetrievalCustodyGone ContentRetrievalUnavailableReason = 2
)

类型 DecodedContentRetrievalResult​

DecodedContentRetrievalResult 是严格解码后的 content_retrieval_result_cbor 的 typed 视图。

type DecodedContentRetrievalResult struct {
    // ContentRetrievalRequestID 必须等于 SHA-256(exact Kind 10 请求文档)，绑定本应答对应的请求。
    ContentRetrievalRequestID protocol.ContentRetrievalRequestID
    // Result 是分支判别值：0 unavailable / 1 available；未知值在严格解码时拒绝。
    Result ContentRetrievalResult
    // UnavailableReason 仅 Result == unavailable 时有意义：
    // 0 seller_arbitration_not_received / 1 not_ready / 2 custody_gone。
    UnavailableReason ContentRetrievalUnavailableReason
    // ContentPayloadsID 仅 Result == available 时有意义：
    // SHA-256(exact content_payloads_cbor)，逐字节绑定附件批次。
    ContentPayloadsID protocol.ContentPayloadsID
}

函数 DecodeContentRetrievalResultDocument​

func DecodeContentRetrievalResultDocument(data []byte) (*DecodedContentRetrievalResult, error)

DecodeContentRetrievalResultDocument 严格解码一份 content_retrieval_result_cbor。判别值最先读取；未知 result 和错误外形都会被拒绝，不做 presence guessing。

类型 VerifiedContentRetrievalResult​

VerifiedContentRetrievalResult 是把一份 Kind 11 对照其应答的确切 Kind 10 验证后的深拷贝结果。

type VerifiedContentRetrievalResult struct {
    // ContentRetrievalRequestID 是已验证绑定的请求 ID（等于买方请求文档哈希）。
    ContentRetrievalRequestID protocol.ContentRetrievalRequestID
    // Available 报告分支结果：true 为可交付；false 表示 unavailable 分支，
    // 此时 Payloads/PayloadsCBOR 均为空且不产生任何付款状态变化。valid
    // unavailable 是协议结果，不是 transport/parser error。
    Available bool
    // UnavailableReason 仅 Available == false 时有意义：仲裁方给出的诚实原因，
    // 应用据此决定生成新 nonce、等待或终止。
    UnavailableReason ContentRetrievalUnavailableReason
    // PayloadsCBOR 是 exact content_payloads_cbor 字节；仅 available 分支非空。
    PayloadsCBOR []byte
    // Payloads 是按授权顺序深拷贝的 payload 内容；仅 available 分支非空。
    Payloads [][]byte
}

函数 VerifyContentRetrievalResponse​

func VerifyContentRetrievalResponse(request *ContentRetrievalRequest, arbiterPublicKey []byte, response *ContentRetrievalResponse) (*VerifiedContentRetrievalResult, error)

VerifyContentRetrievalResponse verifies one Kind 11 against the exact Kind 10 request it answers: the signed request ID must equal SHA-256(exact_request_cbor), the arbiter signature must verify through the unified helper over the exact result document, and the available branch must additionally bind its payload attachment through content_payloads_id. It performs no clock read and no payment state change. valid unavailable 作为 已验签协议结果返回（Available=false），绝不作为普通 error。

类型 VerifiedCustodiedContent​

VerifiedCustodiedContent 是完整验证一对存储托管记录（Kind 8 + Kind 9）后的深拷贝结果。它是时间无关的：过期 deadline 或成熟退款不会使仍在应用留存窗口内的已签名托管证据失效。

type VerifiedCustodiedContent struct {
    // ArbitrationClaimID 是重算并与回执比对一致的托管 Claim 身份。
    ArbitrationClaimID protocol.ArbitrationClaimID
    // PayloadsCBOR 是从托管 Kind 8 证据字节派生的唯一 payload 真值。
    PayloadsCBOR []byte
    // Payloads 是按授权顺序深拷贝的 payload 内容。
    Payloads [][]byte
    // Receipt 是已验证的 Kind 9 回执（Claim ID、正费用与交易签名绑定）。
    Receipt *ArbitrationReceipt
    // Request 是存储的 exact Kind 8 证据（深拷贝，只读使用）。
    Request *ArbitrationRequest
    // Response 是存储的 exact Kind 9 证据（深拷贝，只读使用）。
    Response *ArbitrationResponse
}

函数 VerifyCustodiedContent​

func VerifyCustodiedContent(arbitrationRequest *ArbitrationRequest, arbitrationResponse *ArbitrationResponse) (*VerifiedCustodiedContent, error)

VerifyCustodiedContent 对一对存储记录执行完整的时间无关托管证据验证：两份报文的严格解码、Seller Claim 签名、买方授权签名、payload 数量/顺序/哈希、对照 Receipt 重算 Claim ID、仲裁方回执签名、按 Receipt 费用重建 candidate 以及仲裁方交易签名。应用用它决定一条存储记录支持哪个 Kind 11 分支。它从不读时钟，也从不施加 deadline 或退款成熟门禁：那些都在 Kind 9 签署之前执行过了。

由 gomarkdoc 生成