piece

PieceCID utilities for Filecoin Onchain Cloud.

Example

import * as Piece from '@filoz/synapse-core/piece'

// Compute
const piece = await Piece.calculate(bytes)
piece.root    // 32-byte merkle root (for contract calls)
piece.size    // raw bytes
piece.height  // tree height

// Parse / validate
const piece = Piece.from('bafkz...')     // throws on invalid
const piece = Piece.tryFrom(maybeInput)  // null on invalid
Piece.is(value)                          // type guard

// Streaming
const { transform, result } = Piece.transformStream()
await source.pipeThrough(transform).pipeTo(sink)
const piece = await result

// Lower-level primitives
Piece.fr32.expand(rawBytes)
Piece.merkle.computeNode(left, right)

Reference: FRC-0069 https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md

PieceCID hashing uses the Rust/WASM hasher from @hugomrdias/commp-wasm. Lower-level primitives (FR32, merkle, size math) are derived from @web3-storage/data-segment. See the package README for full attribution.

Namespaces

Namespace	Description
download	-
downloadAndValidate	-
fr32	-
merkle	-
resolvePieceUrl	-

Classes

Class	Description
PieceCID	-

Interfaces

Interface	Description
PieceCIDTransform	A pass-through TransformStream that computes the PieceCID of the data flowing through it. The PieceCIDTransform.result promise resolves once the input stream closes.
PieceHasher	Imperative incremental hasher. Use for sync code paths or when integrating with libraries that expose chunk-level callbacks.

Type Aliases

Type Alias	Description
CalculateInput	Input types accepted by calculate.
PieceCIDInput	Inputs accepted by from and tryFrom.

Variables

Variable	Description
BYTES_PER_QUAD	Source bytes per FR32 quad (127).
CODEC_CODE	PieceCID codec (raw).
defaultResolvers	The default resolvers to use when resolving the piece URL
MAX_HEIGHT	Maximum tree height (255).
MAX_SIZE	Maximum payload size that a single PieceCID can represent (limited by the 1-byte tree height field).
MIN_SIZE	Minimum payload size for which PieceCID is defined (smaller inputs are zero-padded up to this floor).
MULTIHASH_CODE	PieceCID multihash code (fr32-sha2-256-trunc254-padded-binary-tree).
MULTIHASH_NAME	PieceCID multihash name.

Functions

Function	Description
calculate	Compute the PieceCID of `input`. Always returns a Promise. For the synchronous bytes case, use hasher directly.
chainResolver	Resolve the piece URL from the chain
download	Download a piece from a URL.
downloadAndValidate	Download data from a URL, validate its PieceCID, and return as Uint8Array
equals	Compare two PieceCID inputs for equality. Invalid inputs return `false`.
filbeamResolver	Resolve the piece URL from the FilBeam CDN
findPieceOnProviders	Find the piece on the providers
from	Construct a PieceCID from any supported input.
hasher	Create a new PieceHasher.
heightFor	Tree height that a raw payload of `rawSize` will produce.
is	Type guard for PieceCID instances. Plain CIDs need tryFrom to gain accessors. Cross-realm/bundle safe via PIECE_CID_TAG.
paddedSizeAtHeight	Padded piece size in bytes for a given tree height.
paddedSizeFor	Padded piece size in bytes that a raw payload of `rawSize` will produce.
providersResolver	Resolve the piece URL from the providers
resolvePieceUrl	Resolve the piece URL from the available resolvers
transformStream	-
tryFrom	Construct a PieceCID from any supported input, or `null` if the input is null/undefined or fails validation.

References

createPieceUrl

Re-exports createPieceUrl

createPieceUrlFilBeam

Re-exports createPieceUrlFilBeam

createPieceUrlPDP

Re-exports createPieceUrlPDP