Documentation
¶
Overview ¶
Package piece provides PieceCID utilities for Filecoin content addressing.
This is a leaf package. It provides Filecoin-specific piece commitment (commp) calculation, CID format conversion, merkle root extraction, and padded size helpers.
CID formats ¶
PieceCIDv1 (codec=0xf101, multihash=sha2-256-trunc254-padded) is the traditional Filecoin piece commitment. It does not encode the original raw size.
PieceCIDv2 (codec=0x55, multihash=fr32-sha256-trunc254-padbintree, per FRC-0069) encodes the original raw byte count inside its multihash digest. Storage operations and PDPVerifier piece lookups use this format.
PieceInfo ¶
Calculate and CalculateFromBytes return a PieceInfo value that holds both CID formats together with the exact raw byte count (RawSize). Storage consumers can rely on PieceInfo directly without maintaining separate v1 / rawSize fields.
CIDv2 requires a minimum raw payload of 127 bytes (the unpadded capacity of the smallest valid Filecoin piece, 128 padded bytes). For inputs smaller than 127 bytes CIDv2 is left as cid.Undef while CIDv1 and RawSize are still populated.
Other utilities ¶
- Validate checks that a CID is a valid v1 piece commitment.
- ExtractRoot extracts the 32-byte merkle root from a v1 CID.
- ParseV2 decodes a PieceCIDv2 back into a PieceInfo.
- PieceInfoFromV1 reconstructs a PieceInfo from a stored v1 CID and raw size.
- PaddedSize computes the smallest power-of-two padded piece size for a given raw byte count.
Index ¶
Constants ¶
const ( // FilCommitmentUnsealed is the CID codec for Filecoin unsealed piece commitments (v1). FilCommitmentUnsealed = 0xf101 // SHA2_256_Trunc254Padded is the multihash code for Filecoin v1 piece hashing. SHA2_256_Trunc254Padded = 0x1012 )
Variables ¶
var ( // ErrInvalidCodec is returned when a CID does not use the fil-commitment-unsealed codec. ErrInvalidCodec = errors.New("CID codec is not fil-commitment-unsealed (0xf101)") // ErrInvalidHashFunction is returned when a CID does not use sha2-256-trunc254-padded. ErrInvalidHashFunction = errors.New("multihash function is not sha2-256-trunc254-padded (0x1012)") // ErrInvalidDigestLength is returned when a PieceCID multihash digest is not 32 bytes. ErrInvalidDigestLength = errors.New("multihash digest length is not 32 bytes") // ErrEmptyInput is returned when Calculate receives an empty reader. ErrEmptyInput = errors.New("input data is empty") // ErrNotV2 is returned when ParseV2 receives a CID that is not PieceCIDv2. ErrNotV2 = errors.New("CID is not PieceCIDv2 (fr32-sha256-trunc254-padbintree)") // ErrZeroRawSize is returned when PieceInfoFromV1 is called with rawSize == 0. ErrZeroRawSize = errors.New("rawSize must be non-zero to construct PieceInfo from v1 CID") )
var ( // ErrNegativeRawSize is returned when PaddedSize is called with a // negative rawSize. ErrNegativeRawSize = errors.New("rawSize must be non-negative") // ErrRawSizeTooLarge is returned when PaddedSize is called with a rawSize // that would overflow int64 arithmetic during padded-size computation. ErrRawSizeTooLarge = errors.New("rawSize too large for padded size computation") )
Functions ¶
func ExtractRoot ¶
ExtractRoot extracts the 32-byte merkle root from a v1 PieceCID. Smart contracts use this root for piece verification.
func PaddedSize ¶
PaddedSize returns the smallest power-of-two padded piece size (in bytes) that can hold rawSize bytes after FR32 padding (127 useful bytes per 128-byte leaf). Returns ErrNegativeRawSize for negative inputs and ErrRawSizeTooLarge for inputs near math.MaxInt64 where the computation would otherwise silently overflow.
Types ¶
type PieceInfo ¶
PieceInfo holds lossless piece information at the upload/download boundary.
CIDv1 is the standard Filecoin piece commitment (codec=0xf101, multihash=sha2-256-trunc254-padded). It does not encode the original raw size.
CIDv2 is the PieceCIDv2 (codec=0x55, multihash=fr32-sha256-trunc254-padbintree), which encodes the original raw (unpadded) byte count inside its multihash digest. Use CIDv2 for storage operations and PDPVerifier piece lookups.
RawSize is the original unpadded byte count. It is encoded losslessly inside CIDv2 and is always equal to the number of bytes passed to Calculate.
Use PaddedSize(int64(info.RawSize)) to obtain the corresponding padded piece size.
func Calculate ¶
Calculate reads all data from r, computes the piece commitment, and returns a fully-populated PieceInfo. Returns ErrEmptyInput if r is empty.
CIDv1 is always populated. CIDv2 is populated when RawSize >= 127 (the minimum Filecoin piece payload size). For smaller inputs CIDv2 is cid.Undef because the fr32 encoding standard does not define pieces below 127 bytes.
func CalculateFromBytes ¶
CalculateFromBytes is a convenience wrapper around Calculate for byte slices.
func ParseV2 ¶
ParseV2 decodes a PieceCIDv2 and returns the fully-populated PieceInfo. Returns ErrNotV2 if c is a v1 piece CID or any other non-v2 CID.
func PieceInfoFromV1 ¶
PieceInfoFromV1 constructs a PieceInfo from a v1 piece CID and the known raw size. This is useful when reading from storage systems that persist v1 + size separately and need to reconstruct the full v2-aware PieceInfo.
Returns ErrZeroRawSize if rawSize is 0. For raw sizes below 127 bytes, CIDv2 is returned as cid.Undef to mirror Calculate semantics.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer is a streaming PieceCID calculator. Data written to a Writer is hashed incrementally; call Sum once after the final Write to obtain the fully-populated PieceInfo.
A Writer is not safe for concurrent use. Do not reuse a Writer after Sum has been called.
Typical use is wrapping an upload body with io.TeeReader so the data is hashed in the same pass that sends it to the network:
w := piece.NewWriter() body := io.TeeReader(src, w) // ... stream body to HTTP PUT ... info, err := w.Sum()
func NewWriter ¶
func NewWriter() *Writer
NewWriter returns a new, ready-to-use streaming PieceCID calculator.
func (*Writer) Sum ¶
Sum finalizes the piece commitment and returns the corresponding PieceInfo. It may only be called once; subsequent calls return an error. Returns ErrEmptyInput if no bytes were written.
CIDv1 is always populated. CIDv2 is populated when the written byte count is at least 127 (the minimum Filecoin piece payload size); for smaller inputs CIDv2 is cid.Undef, mirroring Calculate semantics.
Source Files