# piece

PieceCID utilities for Filecoin Onchain Cloud.

## Example

```ts
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

Core primitives (FR32, merkle, streaming hasher, size math) are derived
from [`@web3-storage/data-segment`](https://github.com/web3-storage/data-segment).
See the package README for full attribution.

## Namespaces

| Namespace | Description |
| ------ | ------ |
| [download](/reference/filoz/synapse-core/piece/namespaces/download/toc/) | - |
| [downloadAndValidate](/reference/filoz/synapse-core/piece/namespaces/downloadandvalidate/toc/) | - |
| [fr32](/reference/filoz/synapse-core/piece/namespaces/fr32/toc/) | - |
| [merkle](/reference/filoz/synapse-core/piece/namespaces/merkle/toc/) | - |
| [resolvePieceUrl](/reference/filoz/synapse-core/piece/namespaces/resolvepieceurl/toc/) | - |

## Classes

| Class | Description |
| ------ | ------ |
| [PieceCID](/reference/filoz/synapse-core/piece/classes/piececid/) | - |

## Interfaces

| Interface | Description |
| ------ | ------ |
| [PieceCIDTransform](/reference/filoz/synapse-core/piece/interfaces/piececidtransform/) | A pass-through [TransformStream](https://developer.mozilla.org/docs/Web/API/TransformStream) that computes the PieceCID of the data flowing through it. The [PieceCIDTransform.result](/reference/filoz/synapse-core/piece/interfaces/piececidtransform/#result) promise resolves once the input stream closes. |
| [PieceHasher](/reference/filoz/synapse-core/piece/interfaces/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](/reference/filoz/synapse-core/piece/type-aliases/calculateinput/) | Input types accepted by [calculate](/reference/filoz/synapse-core/piece/functions/calculate/). |
| [PieceCIDInput](/reference/filoz/synapse-core/piece/type-aliases/piececidinput/) | Inputs accepted by [from](/reference/filoz/synapse-core/piece/functions/from/) and [tryFrom](/reference/filoz/synapse-core/piece/functions/tryfrom/). |

## Variables

| Variable | Description |
| ------ | ------ |
| [BYTES\_PER\_QUAD](/reference/filoz/synapse-core/piece/variables/bytes_per_quad/) | Source bytes per FR32 quad (127). |
| [CODEC\_CODE](/reference/filoz/synapse-core/piece/variables/codec_code/) | PieceCID codec (raw). |
| [defaultResolvers](/reference/filoz/synapse-core/piece/variables/defaultresolvers/) | The default resolvers to use when resolving the piece URL |
| [MAX\_HEIGHT](/reference/filoz/synapse-core/piece/variables/max_height/) | Maximum tree height (255). |
| [MAX\_SIZE](/reference/filoz/synapse-core/piece/variables/max_size/) | Maximum payload size that a single PieceCID can represent (limited by the 1-byte tree height field). |
| [MIN\_SIZE](/reference/filoz/synapse-core/piece/variables/min_size/) | Minimum payload size for which PieceCID is defined (smaller inputs are zero-padded up to this floor). |
| [MULTIHASH\_CODE](/reference/filoz/synapse-core/piece/variables/multihash_code/) | PieceCID multihash code (fr32-sha2-256-trunc254-padded-binary-tree). |
| [MULTIHASH\_NAME](/reference/filoz/synapse-core/piece/variables/multihash_name/) | PieceCID multihash name. |

## Functions

| Function | Description |
| ------ | ------ |
| [calculate](/reference/filoz/synapse-core/piece/functions/calculate/) | Compute the PieceCID of `input`. Always returns a Promise. For the synchronous bytes case, use [hasher](/reference/filoz/synapse-core/piece/functions/hasher/) directly. |
| [chainResolver](/reference/filoz/synapse-core/piece/functions/chainresolver/) | Resolve the piece URL from the chain |
| [download](/reference/filoz/synapse-core/piece/functions/download/) | Download a piece from a URL. |
| [downloadAndValidate](/reference/filoz/synapse-core/piece/functions/downloadandvalidate/) | Download data from a URL, validate its PieceCID, and return as Uint8Array |
| [equals](/reference/filoz/synapse-core/piece/functions/equals/) | Compare two PieceCID inputs for equality. Invalid inputs return `false`. |
| [filbeamResolver](/reference/filoz/synapse-core/piece/functions/filbeamresolver/) | Resolve the piece URL from the FilBeam CDN |
| [findPieceOnProviders](/reference/filoz/synapse-core/piece/functions/findpieceonproviders/) | Find the piece on the providers |
| [from](/reference/filoz/synapse-core/piece/functions/from/) | Construct a [PieceCID](/reference/filoz/synapse-core/piece/classes/piececid/) from any supported input. |
| [hasher](/reference/filoz/synapse-core/piece/functions/hasher/) | Create a new [PieceHasher](/reference/filoz/synapse-core/piece/interfaces/piecehasher/). |
| [heightFor](/reference/filoz/synapse-core/piece/functions/heightfor/) | Tree height that a raw payload of `rawSize` will produce. |
| [is](/reference/filoz/synapse-core/piece/functions/is/) | Type guard for [PieceCID](/reference/filoz/synapse-core/piece/classes/piececid/) instances. Plain CIDs need [tryFrom](/reference/filoz/synapse-core/piece/functions/tryfrom/) to gain accessors. Cross-realm/bundle safe via PIECE\_CID\_TAG. |
| [paddedSizeAtHeight](/reference/filoz/synapse-core/piece/functions/paddedsizeatheight/) | Padded piece size in bytes for a given tree height. |
| [paddedSizeFor](/reference/filoz/synapse-core/piece/functions/paddedsizefor/) | Padded piece size in bytes that a raw payload of `rawSize` will produce. |
| [providersResolver](/reference/filoz/synapse-core/piece/functions/providersresolver/) | Resolve the piece URL from the providers |
| [resolvePieceUrl](/reference/filoz/synapse-core/piece/functions/resolvepieceurl/) | Resolve the piece URL from the available resolvers |
| [transformStream](/reference/filoz/synapse-core/piece/functions/transformstream/) | - |
| [tryFrom](/reference/filoz/synapse-core/piece/functions/tryfrom/) | Construct a [PieceCID](/reference/filoz/synapse-core/piece/classes/piececid/) from any supported input, or `null` if the input is null/undefined or fails validation. |

## References

### createPieceUrl

Re-exports [createPieceUrl](/reference/filoz/synapse-core/utils/functions/createpieceurl/)

***

### createPieceUrlPDP

Re-exports [createPieceUrlPDP](/reference/filoz/synapse-core/utils/functions/createpieceurlpdp/)