Skip to main content

bitfs

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

Package bitfs implements the protocol layer for BitFS 001, 003, and 004. It owns canonical CBOR, signed quote/content credentials, hashes, and payload validation. It does not store files, open pools, or submit network transactions; buyer and seller workflows inject those capabilities.

Index​

Constants​

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

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

const MaxQuoteFileSize uint64 = MaxQuoteSeedBlocks * BlockSize

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

const MaxQuoteSeedBlocks uint64 = BlockSize / sha256.Size

Variables​

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

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

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 constructs a seed by concatenating 32-byte block hashes in order.

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)

EncodeContentDeliveryTerms returns the deterministic 004 terms bytes that bind delivery content to a previously authorized request and seller identity.

func EncodeContentRequestTerms​

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

EncodeContentRequestTerms returns the exact deterministic CBOR array signed by the buyer for a 003 request. It rejects nil terms and invalid field lengths.

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)

EncodeSignedContentDelivery encodes the complete seller-signed 004 credential; it preserves the supplied terms bytes and detached seller signature exactly.

func EncodeSignedContentRequest​

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

EncodeSignedContentRequest encodes the complete 003 credential, including the original terms bytes, buyer key, and signature, without re-signing it.

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 parses a seed and returns independent copies of its block hashes.

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 computes the SHA-256 digest of seed bytes.

func ValidateContentDeliveryTerms​

func ValidateContentDeliveryTerms(terms *ContentDeliveryTerms) error

ValidateContentDeliveryTerms checks the 004 version, authorization hash, seller key, content hash, and declared payload length before delivery is accepted.

func ValidateContentRequestTerms​

func ValidateContentRequestTerms(terms *ContentRequestTerms) error

ValidateContentRequestTerms checks the 003 version, quote hash, pool reference, content selector, arbiter key, size, and delivery deadline before signing.

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.

type ContentDeliveryTerms​

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

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

func DecodeContentDeliveryTerms​

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

DecodeContentDeliveryTerms decodes canonical 004 terms and validates its fixed array shape and byte-field lengths.

type ContentRef​

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

type ContentRef struct {
    Type ContentType
    Hash []byte
}

type ContentRequestTerms​

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.

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
}

func DecodeContentRequestTerms​

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

DecodeContentRequestTerms accepts only canonical 003 terms CBOR, checks the fixed array shape and field encodings, and returns an independently owned value.

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​

ContentTermsSignatureVerifier verifies a signature over exact bytes.

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

type ContentTermsSigner​

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

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

type ContentType​

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

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

type FileQuoteStore​

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.

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

func NewFileQuoteStore​

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

NewFileQuoteStore opens or creates the quote snapshot at path. It creates the parent directory as needed and uses an advisory process lock for cooperating writers; calculator is retained for canonical terms-hash indexing.

func (*FileQuoteStore) LoadQuote​

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

LoadQuote reloads the snapshot under the process lock, looks up termsHash, and returns a defensive copy so callers cannot mutate persisted bytes.

func (*FileQuoteStore) SaveQuote​

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

SaveQuote validates a complete signed quote, copies its mutable bytes, and atomically stores it under FileQuoteTermsHash.

type FileQuoteTerms​

FileQuoteTerms is the seller's signed pricing and expiry commitment to one buyer.

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 performs structural, expiry, and seller-signature verification using now, allowing callers to test expiry without wall-clock time.

type Hash32​

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

type Hash32 [sha256.Size]byte

func ContentDeliveryTermsHash​

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

ContentDeliveryTermsHash validates canonical delivery terms and returns their SHA-256 digest.

func PaymentAuthorizationHash​

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

PaymentAuthorizationHash validates canonical request terms and returns their SHA-256 digest.

type QuoteTermsSignatureVerifier​

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

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

type QuoteTermsSigner​

QuoteTermsSigner signs the exact canonical TermsCBOR bytes.

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

type SignedContentDelivery​

SignedContentDelivery is the complete 004 credential.

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

func CloneSignedContentDelivery​

func CloneSignedContentDelivery(delivery *SignedContentDelivery) *SignedContentDelivery

CloneSignedContentDelivery returns a deep copy of a 004 credential, including independent terms, public-key, payload, and signature byte slices.

func DecodeSignedContentDelivery​

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

DecodeSignedContentDelivery decodes canonical 004 credential bytes and rejects malformed shape or fields before returning an independently owned value.

func NewSignedContentDelivery​

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

NewSignedContentDelivery binds payload bytes to the request authorization hash and signs the resulting deterministic delivery terms.

type SignedContentRequest​

SignedContentRequest is the complete 003 final payment authorization.

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

func CloneSignedContentRequest​

func CloneSignedContentRequest(request *SignedContentRequest) *SignedContentRequest

CloneSignedContentRequest returns a deep copy of a 003 credential, including independent terms, public-key, and signature byte slices.

func DecodeSignedContentRequest​

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

DecodeSignedContentRequest decodes a canonical 003 credential and rejects malformed array shape, versions, and byte fields before returning a copy.

func NewSignedContentRequest​

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

NewSignedContentRequest deterministically encodes request terms and signs those exact bytes with the buyer-supplied signer.

type SignedFileQuote​

SignedFileQuote carries canonical quote terms, the seller identity and signature, and a display-only recommended filename.

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 validates quote terms, encodes the canonical TermsCBOR, signs those exact bytes with signTerms, and returns a portable 001 credential.

type UnixSeconds​

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

type UnixSeconds int64

Generated by gomarkdoc