bitfs

由 doc2go 直接从当前 Go 源码与 doc comments 生成。

package bitfs

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

Package bitfs provides the current deterministic protocol helpers.

Index

Constants

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

MaxQuoteFileSize is the largest file a quote can describe while the seed is delivered in one BitFS payload.

const MaxQuoteSeedBlocks uint64 = BlockSize / sha256.Size

MaxQuoteSeedBlocks is the greatest block count whose seed fits the BitFS payload limit. A seed contains one 32-byte hash for each block.

Variables

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")
)

Sentinel errors are stable categories for callers implementing retry, rejection and user-facing error handling.

Functions

func BlockHashInSeed

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

BlockHashInSeed reports whether a block hash is one of the ordered hashes committed by seed. The seed itself is checked against the quote before the membership result is returned.

func BuildSeedBytes

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

BuildSeedBytes 按 BitFS v1 的唯一格式构造 seed：仅顺序拼接 32 字节 block hash。

func ContentPriceSat

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

ContentPriceSat derives the buyer-signed amount from the verified quote and the delivered content size. Full blocks use the quoted price. A tail block is charged proportionally, rounded up, with the specified 10% seller calculation allowance. The computation uses big integers so malformed uint64 prices cannot overflow into a lower amount.

func DecodeSupportedArbiterPubkeys

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

DecodeSupportedArbiterPubkeys validates and decodes a canonical supported-arbiter child structure.

func EncodeContentDeliveryTerms

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

func EncodeContentRequestTerms

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

func EncodeFileQuoteTerms

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

EncodeFileQuoteTerms returns the exact canonical CBOR bytes signed by a seller. The terms are an independent child document and therefore carry a version of their own.

func EncodeSignedContentDelivery

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

func EncodeSignedContentRequest

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

func EncodeSignedFileQuote

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

EncodeSignedFileQuote returns the canonical CBOR representation of a quote credential. RecommendedFilename is intentionally not in TermsSignature.

func EncodeSupportedArbiterPubkeys

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

EncodeSupportedArbiterPubkeys returns the sole allowed representation of the supported-arbiter child structure.

func FileQuoteTermsHash

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

FileQuoteTermsHash returns the content-derived reference for canonical quote terms. It is a cache and evidence index, never a database-generated ID.

func ParseSeedBytes

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

ParseSeedBytes 按 BitFS v1 的唯一格式解析 seed，并返回独立副本的 block hash 列表。

func SanitizeRecommendedFilename

func SanitizeRecommendedFilename(name string) string

SanitizeRecommendedFilename converts unsigned display metadata into a safe single filename. It must be applied before displaying or using the value as a local path; the original field remains outside the quote's economic truth.

func SeedHash

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

SeedHash 计算 BitFS v1 seed 的 sha256 摘要。

func ValidateContentDeliveryTerms

func ValidateContentDeliveryTerms(terms *ContentDeliveryTerms) error

func ValidateContentRequestTerms

func ValidateContentRequestTerms(terms *ContentRequestTerms) error

func ValidateFileQuoteTerms

func ValidateFileQuoteTerms(terms *FileQuoteTerms) error

ValidateFileQuoteTerms validates quote terms without considering time or a seller signature.

func ValidateFileQuoteTermsAt

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

ValidateFileQuoteTermsAt additionally verifies that terms have not expired.

func VerifyContentPayload

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

VerifyContentPayload verifies a delivered payload against the quoted content reference. For a block it also enforces the exact full/tail length derivable from the block's position in the seed.

func VerifyContentReference

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

VerifyContentReference verifies the relationship between a quote and a requested content hash. Seed requests are self-contained; block requests additionally require the raw seed previously obtained by the buyer or held by the seller.

func VerifySignedContentDeliveryAt

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

VerifySignedContentDeliveryAt verifies the exact request reference, seller signature and raw content hash. The caller may additionally validate a block against a previously received seed index.

func VerifySignedContentDeliveryWithSeedAt

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

VerifySignedContentDeliveryWithSeedAt additionally validates block membership and the exact full/tail block size derived from the seed.

Types

type ContentDeliveryTerms

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

ContentDeliveryTerms is the unsigned, signed-bytes portion of 004.

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

type ContentRef

type ContentRef struct {
	Type ContentType
	Hash []byte
}

ContentRef is the only content choice exposed by the new request API.

type ContentRequestTerms

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
}

ContentRequestTerms is the unsigned, signed-bytes portion of the canonical 003 final payment authorization. The historical type name is retained so callers do not accidentally create a second authorization model.

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

VerifySignedContentRequestAt verifies the quote binding, buyer signature, arbiter selection and request deadline. Pool ownership and current sequence are deliberately delegated to the pool workflow layer.

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

VerifySignedContentRequestStandalone verifies the self-contained buyer authorization used by arbitration. It deliberately does not load or validate a quote, delivery, payload, or payment history.

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

VerifySignedContentRequestWithSeedAt is the workflow-level form of VerifySignedContentRequestAt. It additionally proves that a block hash is present in the quote's seed.

type ContentTermsSignatureVerifier

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

ContentTermsSignatureVerifier verifies a signature over exact bytes.

type ContentTermsSigner

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

ContentTermsSigner signs the exact canonical CBOR bytes of a content request or delivery terms document.

type ContentType

type ContentType uint64

ContentType identifies the two kinds of content addressable by a request.

const (
	ContentSeed  ContentType = 0
	ContentBlock ContentType = 1
)

type FileQuoteStore

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

FileQuoteStore is a durable, atomic-snapshot implementation of the quote store ports used by buyer and seller. It persists the signed quote bytes and indexes them by the canonical FileQuoteTerms hash.

It uses an advisory process lock and reloads the current snapshot for each operation, so cooperating Unix processes do not lose each other's quotes. A transactional database is still preferable for indexed queries and stronger crash-recovery/locking guarantees.

func NewFileQuoteStore
func NewFileQuoteStore(path string) (*FileQuoteStore, error)
func (*FileQuoteStore) LoadQuote
func (store *FileQuoteStore) LoadQuote(_ context.Context, termsHash Hash32) (*SignedFileQuote, error)
func (*FileQuoteStore) SaveQuote
func (store *FileQuoteStore) SaveQuote(_ context.Context, quote *SignedFileQuote) error

type FileQuoteTerms

type FileQuoteTerms struct {
	SeedHash                    []byte
	BuyerPubkey                 []byte
	SeedPriceSat                uint64
	FullBlockPriceSat           uint64
	FileSize                    uint64
	QuoteExpiresAtUnix          int64
	SupportedArbiterPubkeysCBOR []byte
}
func DecodeFileQuoteTerms
func DecodeFileQuoteTerms(data []byte) (*FileQuoteTerms, error)

DecodeFileQuoteTerms validates and decodes canonical FileQuoteTerms bytes.

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

VerifySignedFileQuote verifies structural validity, quote expiry, and the seller signature. It returns independently owned parsed terms.

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

VerifySignedFileQuoteAt is VerifySignedFileQuote with an injected clock.

type Hash32

type Hash32 [sha256.Size]byte

Hash32 is a fixed-size SHA-256 reference used by the new protocol.

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

type QuoteTermsSignatureVerifier

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

QuoteTermsSignatureVerifier verifies a seller signature over the exact canonical TermsCBOR bytes.

type QuoteTermsSigner

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

QuoteTermsSigner signs the exact canonical TermsCBOR bytes.

type SignedContentDelivery

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

SignedContentDelivery is the complete 004 credential.

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

type SignedContentRequest

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

SignedContentRequest is the complete 003 final payment authorization.

func CloneSignedContentRequest
func CloneSignedContentRequest(request *SignedContentRequest) *SignedContentRequest
func DecodeSignedContentRequest
func DecodeSignedContentRequest(data []byte) (*SignedContentRequest, error)
func NewSignedContentRequest
func NewSignedContentRequest(terms *ContentRequestTerms, signer ContentTermsSigner) (*SignedContentRequest, error)

type SignedFileQuote

type SignedFileQuote struct {
	TermsCBOR           []byte
	SellerPubkey        []byte
	TermsSignature      []byte
	RecommendedFilename string
}
func CloneSignedFileQuote
func CloneSignedFileQuote(quote *SignedFileQuote) *SignedFileQuote

CloneSignedFileQuote returns an independent copy for API and storage boundaries.

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

DecodeSignedFileQuote decodes one canonical quote credential. Signature and expiry verification is intentionally separate so callers can inject their wallet verifier and clock through VerifySignedFileQuoteAt.

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

NewSignedFileQuote creates a portable seller quote credential.

type UnixSeconds

type UnixSeconds int64

UnixSeconds is the protocol's UTC Unix-seconds representation.