跳到主要内容

bitfs

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

bitfs 包实现 BitFS 001、003 和 004 的协议层，负责规范 CBOR、已签名报价/内容凭证、哈希和载荷验证。它不保存文件、不负责开池或提交网络交易；这些能力由买方和卖方工作流注入。

索引​

常量​

const (
    // BlockSize is the fixed block size limit in bytes.
    BlockSize uint64 = 256 * 1024
)

MaxQuoteFileSize 是在一个 BitFS 载荷中交付种子时，报价可以描述的最大文件大小。

const MaxQuoteFileSize uint64 = MaxQuoteSeedBlocks * BlockSize

MaxQuoteSeedBlocks 是种子仍能放入 BitFS 载荷限制内时允许的最大区块数。种子为每个区块包含一个 32 字节哈希。

const MaxQuoteSeedBlocks uint64 = BlockSize / sha256.Size

变量​

哨兵错误为实现重试、拒绝和面向用户的错误处理提供稳定分类。

var (
    ErrInvalidEvidence      = errors.New("invalid evidence")
    ErrQuoteExpired         = errors.New("quote expired")
    ErrDeliveryDeadline     = errors.New("delivery deadline expired")
    ErrPoolBusy             = errors.New("pool busy")
    ErrStalePaymentSequence = errors.New("stale payment sequence")
    ErrInsufficientBalance  = errors.New("insufficient balance")
    ErrNonFinalRejected     = errors.New("non-final pool rejected update")
    ErrContentNotInSeed     = errors.New("content is not listed by seed")
)

函数 BlockHashInSeed​

func BlockHashInSeed(seed, quoteSeedHash, blockHash []byte) (bool, error)

BlockHashInSeed 报告区块哈希是否属于 seed 承诺的有序哈希列表。返回成员关系前会先依据报价检查 seed 本身。

函数 BuildSeedBytes​

func BuildSeedBytes(blockHashes [][]byte) ([]byte, error)

BuildSeedBytes 按顺序拼接 32 字节区块哈希来构造 seed。

函数 ContentPriceSat​

func ContentPriceSat(terms *FileQuoteTerms, contentType ContentType, contentSize uint64) (uint64, error)

ContentPriceSat 根据已验证报价和交付内容大小计算买方签名的金额。完整区块使用报价中的价格；尾区块按比例计费并向上取整，同时计入规定的卖方 10% 计算余量。计算使用大整数，避免畸形的 uint64 价格溢出为较小金额。

函数 DecodeSupportedArbiterPubkeys​

func DecodeSupportedArbiterPubkeys(data []byte) ([][]byte, error)

DecodeSupportedArbiterPubkeys 验证并解码规范的 supported-arbiter 子结构。

函数 EncodeContentDeliveryTerms​

func EncodeContentDeliveryTerms(terms *ContentDeliveryTerms) ([]byte, error)

EncodeContentDeliveryTerms 返回确定性的 004 条款字节，将交付内容绑定到先前授权的请求和卖方身份。

函数 EncodeContentRequestTerms​

func EncodeContentRequestTerms(terms *ContentRequestTerms) ([]byte, error)

EncodeContentRequestTerms 返回买方为 003 请求签名的精确确定性 CBOR 数组。它拒绝 nil 条款和无效字段长度。

函数 EncodeFileQuoteTerms​

func EncodeFileQuoteTerms(terms *FileQuoteTerms) ([]byte, error)

EncodeFileQuoteTerms 返回卖方签名的精确规范 CBOR 字节。条款是独立的子文档，因此拥有自己的版本号。

函数 EncodeSignedContentDelivery​

func EncodeSignedContentDelivery(delivery *SignedContentDelivery) ([]byte, error)

EncodeSignedContentDelivery 编码完整的卖方签名 004 凭证，并完整保留传入的条款字节和卖方分离签名。

函数 EncodeSignedContentRequest​

func EncodeSignedContentRequest(request *SignedContentRequest) ([]byte, error)

EncodeSignedContentRequest 编码完整的 003 凭证，包括原始条款字节、买方密钥和签名，但不会重新签名。

函数 EncodeSignedFileQuote​

func EncodeSignedFileQuote(quote *SignedFileQuote) ([]byte, error)

EncodeSignedFileQuote 返回报价凭证的规范 CBOR 表示。RecommendedFilename 被有意排除在 TermsSignature 之外。

函数 EncodeSupportedArbiterPubkeys​

func EncodeSupportedArbiterPubkeys(pubkeys [][]byte) ([]byte, error)

EncodeSupportedArbiterPubkeys 返回 supported-arbiter 子结构唯一允许的表示。

函数 FileQuoteTermsHash​

func FileQuoteTermsHash(termsCBOR []byte) ([sha256.Size]byte, error)

FileQuoteTermsHash 返回规范报价条款的内容派生引用。它用于缓存和证据索引，绝不是数据库生成的 ID。

函数 ParseSeedBytes​

func ParseSeedBytes(seed []byte) ([][]byte, error)

ParseSeedBytes 解析 seed，并返回各区块哈希的独立副本。

函数 SanitizeRecommendedFilename​

func SanitizeRecommendedFilename(name string) string

SanitizeRecommendedFilename 将未签名的展示元数据转换为安全的单一文件名。在展示该值或将其用作本地路径前必须调用它；原字段不属于报价的经济事实。

函数 SeedHash​

func SeedHash(seed []byte) [sha256.Size]byte

SeedHash 计算 seed 字节的 SHA-256 摘要。

函数 ValidateContentDeliveryTerms​

func ValidateContentDeliveryTerms(terms *ContentDeliveryTerms) error

ValidateContentDeliveryTerms 在接受交付前检查 004 版本、授权哈希、卖方密钥、内容哈希和声明的载荷长度。

函数 ValidateContentRequestTerms​

func ValidateContentRequestTerms(terms *ContentRequestTerms) error

ValidateContentRequestTerms 在签名之前检查 003 版本、报价哈希、费用池引用、内容选择器、仲裁人密钥、大小和交付截止时间。

函数 ValidateFileQuoteTerms​

func ValidateFileQuoteTerms(terms *FileQuoteTerms) error

ValidateFileQuoteTerms 验证报价条款的结构，不检查时间或卖方签名。

函数 ValidateFileQuoteTermsAt​

func ValidateFileQuoteTermsAt(terms *FileQuoteTerms, now time.Time) error

ValidateFileQuoteTermsAt 还会验证条款尚未过期。

函数 VerifyContentPayload​

func VerifyContentPayload(quoteTerms *FileQuoteTerms, contentType ContentType, contentHash, payload, seed []byte, requireBlockMembership bool) error

VerifyContentPayload 将交付载荷与报价中的内容引用进行核对。对于区块，它还会根据区块在 seed 中的位置强制执行可推导出的精确完整/尾部长度。

函数 VerifyContentReference​

func VerifyContentReference(quoteTerms *FileQuoteTerms, contentType ContentType, contentHash, seed []byte, requireBlockMembership bool) error

VerifyContentReference 验证报价与请求内容哈希之间的关系。seed 请求自包含；区块请求还需要买方此前取得或卖方持有的原始 seed。

函数 VerifySignedContentDeliveryAt​

func VerifySignedContentDeliveryAt(request *SignedContentRequest, delivery *SignedContentDelivery, quote *SignedFileQuote, now time.Time, quoteVerifier QuoteTermsSignatureVerifier, buyerVerifier ContentTermsSignatureVerifier, sellerVerifier ContentTermsSignatureVerifier) ([]byte, error)

VerifySignedContentDeliveryAt 验证精确的请求引用、卖方签名和原始内容哈希。调用方还可以依据此前收到的 seed 索引验证区块。

函数 VerifySignedContentDeliveryWithSeedAt​

func VerifySignedContentDeliveryWithSeedAt(request *SignedContentRequest, delivery *SignedContentDelivery, quote *SignedFileQuote, seed []byte, now time.Time, quoteVerifier QuoteTermsSignatureVerifier, buyerVerifier ContentTermsSignatureVerifier, sellerVerifier ContentTermsSignatureVerifier) ([]byte, error)

VerifySignedContentDeliveryWithSeedAt 还会验证区块成员关系，以及根据 seed 推导出的精确完整/尾部区块大小。

类型 ContentDeliveryTerms​

ContentDeliveryTerms 是 004 中未签名、但作为签名字节的部分。

type ContentDeliveryTerms struct {
    PaymentAuthorizationHash []byte
    ContentBytes             []byte
}

函数 DecodeContentDeliveryTerms​

func DecodeContentDeliveryTerms(data []byte) (*ContentDeliveryTerms, error)

DecodeContentDeliveryTerms 解码规范的 004 条款，并验证固定数组结构和字节字段长度。

类型 ContentRef​

ContentRef 是新请求 API 暴露的唯一内容选择类型。

type ContentRef struct {
    Type ContentType
    Hash []byte
}

类型 ContentRequestTerms​

ContentRequestTerms 是规范 003 最终支付授权中未签名、但作为签名字节的部分。保留历史类型名，以免调用方误建第二套授权模型。

type ContentRequestTerms struct {
    QuoteTermsHash        []byte
    SpendTxID             []byte
    BasePaymentSequence   uint64
    PaymentSequenceAfter  uint64
    SellerAmountAfterSat  uint64
    MinerFeeRateSatPerKB  uint64
    BuyerPubkey           []byte
    SellerPubkey          []byte
    SelectedArbiterPubkey []byte
    ContentType           ContentType
    ContentHash           []byte
    DeliveryDeadlineUnix  int64
}

函数 DecodeContentRequestTerms​

func DecodeContentRequestTerms(data []byte) (*ContentRequestTerms, error)

DecodeContentRequestTerms 只接受规范的 003 条款 CBOR，检查固定数组结构和字段编码，并返回由调用方独立拥有的值。

函数 VerifySignedContentRequestAt​

func VerifySignedContentRequestAt(request *SignedContentRequest, quote *SignedFileQuote, now time.Time, quoteVerifier QuoteTermsSignatureVerifier, buyerVerifier ContentTermsSignatureVerifier) (*ContentRequestTerms, error)

VerifySignedContentRequestAt 验证报价绑定、买方签名、仲裁人选择和请求截止时间。费用池所有权及当前序列号被有意委托给费用池工作流层。

函数 VerifySignedContentRequestStandalone​

func VerifySignedContentRequestStandalone(request *SignedContentRequest, buyerVerifier ContentTermsSignatureVerifier) (*ContentRequestTerms, error)

VerifySignedContentRequestStandalone 验证仲裁使用的自包含买方授权。它有意不加载或验证报价、交付、载荷或支付历史。

函数 VerifySignedContentRequestWithSeedAt​

func VerifySignedContentRequestWithSeedAt(request *SignedContentRequest, quote *SignedFileQuote, seed []byte, now time.Time, quoteVerifier QuoteTermsSignatureVerifier, buyerVerifier ContentTermsSignatureVerifier) (*ContentRequestTerms, error)

VerifySignedContentRequestWithSeedAt 是 VerifySignedContentRequestAt 在工作流层的形式；它还证明区块哈希存在于报价的 seed 中。

类型 ContentTermsSignatureVerifier​

ContentTermsSignatureVerifier 验证针对精确字节的签名。

type ContentTermsSignatureVerifier func(pubkey, termsCBOR, signature []byte) error

类型 ContentTermsSigner​

ContentTermsSigner 为内容请求或交付条款文档的精确规范 CBOR 字节签名。

type ContentTermsSigner func(termsCBOR []byte) ([]byte, error)

类型 ContentType​

ContentType 标识请求可以寻址的两类内容。

type ContentType uint64
const (
    // ContentSeed selects the seed payload in a content reference.
    ContentSeed ContentType = 0
    // ContentBlock identifies a block payload.
    ContentBlock ContentType = 1
)

类型 FileQuoteStore​

FileQuoteStore 是买方和卖方报价存储端口的持久化原子快照实现。它保存已签名报价字节，并按规范 FileQuoteTerms 哈希建立索引。

它使用进程协作锁，并在每次操作前重新加载当前快照，因此协作的 Unix 进程不会相互覆盖报价。若需要索引查询以及更强的崩溃恢复和锁保证，事务数据库仍更合适。

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

函数 NewFileQuoteStore​

func NewFileQuoteStore(path string) (*FileQuoteStore, error)

NewFileQuoteStore 在 path 处打开或创建报价快照，按需创建父目录，并使用进程协作锁协调写入；calculator 用于规范条款哈希索引。

函数 (*FileQuoteStore) LoadQuote​

func (store *FileQuoteStore) LoadQuote(_ context.Context, termsHash Hash32) (*SignedFileQuote, error)

LoadQuote 在进程锁保护下重新加载快照，查找 termsHash，并返回防御性副本，避免调用方修改持久化字节。

函数 (*FileQuoteStore) SaveQuote​

func (store *FileQuoteStore) SaveQuote(_ context.Context, quote *SignedFileQuote) error

SaveQuote 验证完整的已签名报价，复制其中可变字节，并以 FileQuoteTermsHash 为键原子保存。

类型 FileQuoteTerms​

FileQuoteTerms 是卖方向单个买方签署的价格和有效期承诺。

type FileQuoteTerms struct {
    SeedHash                    []byte
    BuyerPubkey                 []byte
    SeedPriceSat                uint64
    FullBlockPriceSat           uint64
    FileSize                    uint64
    QuoteExpiresAtUnix          int64
    SupportedArbiterPubkeysCBOR []byte
}

函数 DecodeFileQuoteTerms​

func DecodeFileQuoteTerms(data []byte) (*FileQuoteTerms, error)

DecodeFileQuoteTerms 验证并解码规范的 FileQuoteTerms 字节。

函数 VerifySignedFileQuote​

func VerifySignedFileQuote(quote *SignedFileQuote, verifier QuoteTermsSignatureVerifier) (*FileQuoteTerms, error)

VerifySignedFileQuote 验证结构有效性、报价有效期和卖方签名，并返回由调用方独立拥有的解析条款。

函数 VerifySignedFileQuoteAt​

func VerifySignedFileQuoteAt(quote *SignedFileQuote, now time.Time, verifier QuoteTermsSignatureVerifier) (*FileQuoteTerms, error)

VerifySignedFileQuoteAt 使用 now 验证结构、有效期和卖方签名，使调用方无需依赖系统时钟即可测试过期行为。

类型 Hash32​

Hash32 是新协议使用的固定大小 SHA-256 引用。

type Hash32 [sha256.Size]byte

函数 ContentDeliveryTermsHash​

func ContentDeliveryTermsHash(termsCBOR []byte) (Hash32, error)

ContentDeliveryTermsHash 验证规范交付条款并返回其 SHA-256 摘要。

函数 PaymentAuthorizationHash​

func PaymentAuthorizationHash(termsCBOR []byte) (Hash32, error)

PaymentAuthorizationHash 验证规范请求条款并返回其 SHA-256 摘要。

类型 QuoteTermsSignatureVerifier​

QuoteTermsSignatureVerifier 验证卖方针对精确规范 TermsCBOR 字节的签名。

type QuoteTermsSignatureVerifier func(sellerPubkey, termsCBOR, signature []byte) error

类型 QuoteTermsSigner​

QuoteTermsSigner 为精确规范 TermsCBOR 字节签名。

type QuoteTermsSigner func(termsCBOR []byte) ([]byte, error)

类型 SignedContentDelivery​

SignedContentDelivery 是完整的 004 凭证。

type SignedContentDelivery struct {
    TermsCBOR       []byte
    SellerSignature []byte
}

函数 CloneSignedContentDelivery​

func CloneSignedContentDelivery(delivery *SignedContentDelivery) *SignedContentDelivery

CloneSignedContentDelivery 返回 004 凭证的深拷贝，包括独立的条款、公钥、载荷和签名字节切片。

函数 DecodeSignedContentDelivery​

func DecodeSignedContentDelivery(data []byte) (*SignedContentDelivery, error)

DecodeSignedContentDelivery 解码规范的 004 凭证字节，在返回独立拥有的值前拒绝畸形结构或字段。

函数 NewSignedContentDelivery​

func NewSignedContentDelivery(request *SignedContentRequest, payload []byte, signer ContentTermsSigner) (*SignedContentDelivery, error)

NewSignedContentDelivery 将载荷字节绑定到请求授权哈希，并为生成的确定性交付条款签名。

类型 SignedContentRequest​

SignedContentRequest 是完整的 003 最终支付授权。

type SignedContentRequest struct {
    TermsCBOR      []byte
    BuyerSignature []byte
}

函数 CloneSignedContentRequest​

func CloneSignedContentRequest(request *SignedContentRequest) *SignedContentRequest

CloneSignedContentRequest 返回 003 凭证的深拷贝，包括独立的条款、公钥和签名字节切片。

函数 DecodeSignedContentRequest​

func DecodeSignedContentRequest(data []byte) (*SignedContentRequest, error)

DecodeSignedContentRequest 解码规范的 003 凭证，在返回副本前拒绝畸形数组结构、版本和字节字段。

函数 NewSignedContentRequest​

func NewSignedContentRequest(terms *ContentRequestTerms, signer ContentTermsSigner) (*SignedContentRequest, error)

NewSignedContentRequest 确定性编码请求条款，并使用买方提供的签名器为这些精确字节签名。

类型 SignedFileQuote​

SignedFileQuote 携带规范报价条款、卖方身份及签名，以及仅用于展示的推荐文件名。

type SignedFileQuote struct {
    TermsCBOR           []byte
    SellerPubkey        []byte
    TermsSignature      []byte
    RecommendedFilename string
}

函数 CloneSignedFileQuote​

func CloneSignedFileQuote(quote *SignedFileQuote) *SignedFileQuote

CloneSignedFileQuote 返回用于 API 和存储边界的独立副本。

函数 DecodeSignedFileQuote​

func DecodeSignedFileQuote(data []byte) (*SignedFileQuote, error)

DecodeSignedFileQuote 解码一个规范报价凭证。签名和有效期验证被有意分开，调用方可通过 VerifySignedFileQuoteAt 注入自己的钱包验证器和时钟。

函数 NewSignedFileQuote​

func NewSignedFileQuote(terms *FileQuoteTerms, sellerPubkey []byte, recommendedFilename string, signer QuoteTermsSigner) (*SignedFileQuote, error)

NewSignedFileQuote 验证报价条款，编码规范 TermsCBOR，使用 signTerms 为这些精确字节签名，并返回可传输的 001 凭证。

类型 UnixSeconds​

UnixSeconds 是协议使用的 UTC Unix 秒表示。

type UnixSeconds int64

由 gomarkdoc 生成