StorageContext

Defined in: packages/synapse-sdk/src/storage/context.ts:97

Constructors

Constructor

new StorageContext(options): StorageContext

Defined in: packages/synapse-sdk/src/storage/context.ts:183

Creates a new StorageContext

Parameters

Parameter	Type	Description
`options`	`StorageContextOptions`	The options for the StorageContext StorageContextOptions

Returns

StorageContext

Properties

serviceProvider

readonly serviceProvider: `0x${string}`

Defined in: packages/synapse-sdk/src/storage/context.ts:110

Accessors

dataSetId

Get Signature

get dataSetId(): bigint | undefined

Defined in: packages/synapse-sdk/src/storage/context.ts:127

Returns

bigint | undefined

dataSetMetadata

Get Signature

get dataSetMetadata(): Record<string, string>

Defined in: packages/synapse-sdk/src/storage/context.ts:122

Returns

Record<string, string>

provider

Get Signature

get provider(): PDPProvider

Defined in: packages/synapse-sdk/src/storage/context.ts:117

Returns

PDPProvider

withCDN

Get Signature

get withCDN(): boolean

Defined in: packages/synapse-sdk/src/storage/context.ts:113

Returns

boolean

Methods

commit()

commit(options): Promise<CommitResult>

Defined in: packages/synapse-sdk/src/storage/context.ts:897

Commit pieces on-chain by calling AddPieces (or CreateDataSetAndAddPieces).

Pieces must be stored on the provider (via store() or pull()) before committing. Creates a new data set if this context doesn’t have one yet.

Parameters

Parameter	Type	Description
`options`	`CommitOptions`	Pieces to commit with optional pieceMetadata, extraData, and onSubmitted callback

Returns

Promise<CommitResult>

Transaction hash, confirmed pieceIds, dataSetId, and whether a new data set was created

deletePiece()

deletePiece(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/storage/context.ts:1129

Delete a piece with given CID from this data set.

Parameters

Parameter	Type	Description
`options`	{ `piece`: `string` \| `bigint` \| `PieceLink`; }	Options for the delete operation
`options.piece`	`string` \| `bigint` \| `PieceLink`	The PieceCID identifier or a piece number to delete by pieceID

Returns

Promise<`0x${string}`>

Transaction hash of the delete operation

download()

download(options): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/synapse-sdk/src/storage/context.ts:1038

Download data from this specific service provider

Parameters

Parameter	Type
`options`	`DownloadOptions`

Returns

Promise<Uint8Array<ArrayBufferLike>>

getPieces()

getPieces(options?): AsyncGenerator<PieceRecord>

Defined in: packages/synapse-sdk/src/storage/context.ts:1074

Get all active pieces for this data set as an async generator.

Parameters

Parameter	Type	Description
`options`	{ `batchSize?`: `bigint`; }	Optional configuration object
`options.batchSize?`	`bigint`	The batch size for each pagination call (default: 100)

Returns

AsyncGenerator<PieceRecord>

Yields

Object with pieceCid and pieceId

getPieceUrl()

getPieceUrl(pieceCid): string

Defined in: packages/synapse-sdk/src/storage/context.ts:970

Get the retrieval URL for a piece on this provider.

Used by pull() to construct source URLs when pulling from this context to another provider.

Parameters

Parameter	Type
`pieceCid`	`PieceLink`

Returns

string

getProviderInfo()

getProviderInfo(): Promise<PDPProvider>

Defined in: packages/synapse-sdk/src/storage/context.ts:1051

Get information about the service provider used by this service.

Returns

Promise<PDPProvider>

Provider information including pricing (currently same for all providers)

getScheduledRemovals()

getScheduledRemovals(): Promise<readonly bigint[]>

Defined in: packages/synapse-sdk/src/storage/context.ts:1060

Get pieces scheduled for removal from this data set.

Returns

Promise<readonly bigint[]>

Array of piece IDs scheduled for removal

hasPiece()

hasPiece(options): Promise<boolean>

Defined in: packages/synapse-sdk/src/storage/context.ts:1154

Check if a piece exists on this service provider.

Parameters

Parameter	Type	Description
`options`	{ `pieceCid`: `string` \| `PieceLink`; }	Options for the has piece operation
`options.pieceCid`	`string` \| `PieceLink`	The PieceCID (piece CID) to check

Returns

Promise<boolean>

True if the piece exists on this provider, false otherwise

pieceStatus()

pieceStatus(options): Promise<PieceStatus>

Defined in: packages/synapse-sdk/src/storage/context.ts:1185

Check if a piece exists on this service provider and get its proof status. Also returns timing information about when the piece was last proven and when the next proof is due.

Note: Proofs are submitted for entire data sets, not individual pieces. The timing information returned reflects when the data set (containing this piece) was last proven and when the next proof is due.

Parameters

Parameter	Type	Description
`options`	{ `pieceCid`: `string` \| `PieceLink`; }	Options for the piece status
`options.pieceCid`	`string` \| `PieceLink`	The PieceCID (piece CID) to check

Returns

Promise<PieceStatus>

Status information including existence, data set timing, and retrieval URL

preflightUpload()

preflightUpload(options): Promise<PreflightInfo>

Defined in: packages/synapse-sdk/src/storage/context.ts:717

Run preflight checks for an upload

Parameters

Parameter	Type	Description
`options`	{ `size`: `number`; }	Options for the preflight upload
`options.size`	`number`	The size of data to upload in bytes

Returns

Promise<PreflightInfo>

Preflight information including costs and allowances

presignForCommit()

presignForCommit(pieces): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/storage/context.ts:785

Pre-sign EIP-712 extraData for the given pieces.

The returned Hex can be passed to both pull() and commit() to avoid redundant wallet signature prompts during multi-copy uploads.

Parameters

Parameter	Type	Description
`pieces`	`object`[]	Pieces to sign for, with optional per-piece metadata

Returns

Promise<`0x${string}`>

Signed extraData hex to pass to pull() or commit()

pull()

pull(options): Promise<PullResult>

Defined in: packages/synapse-sdk/src/storage/context.ts:818

Request this provider to pull pieces from another provider.

Used for multi-copy uploads: data stored once on primary, then pulled to secondaries via SP-to-SP transfer.

Parameters

Parameter	Type	Description
`options`	`PullOptions`	Pull options: pieces to pull, source (URL or StorageContext), optional extraData, signal, and onProgress

Returns

Promise<PullResult>

Status per piece (‘complete’ or ‘failed’) and overall result

store()

store(data, options?): Promise<StoreResult>

Defined in: packages/synapse-sdk/src/storage/context.ts:741

Store data on the service provider without committing on-chain.

First step of the split upload flow: store -> pull -> commit. After storing, the piece is “parked” on the provider and ready for pulling to other providers via pull(), on-chain commitment via commit(), or retrieval via getPieceUrl() (not yet committed; eligible for GC).

Parameters

Parameter	Type	Description
`data`	`UploadPieceStreamingData`	Raw bytes or readable stream to upload
`options?`	`StoreOptions`	Optional pieceCid (skip CommP), signal, and onProgress callback

Returns

Promise<StoreResult>

PieceCid and size of the stored piece

terminate()

terminate(): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/storage/context.ts:1305

Terminates the data set by sending on-chain message. This will also result in the removal of all pieces in the data set.

Returns

Promise<`0x${string}`>

Transaction response

upload()

upload(data, options?): Promise<UploadResult>

Defined in: packages/synapse-sdk/src/storage/context.ts:992

Upload data to the service provider and commit on-chain.

Combines store() and commit() into a single call. Accepts Uint8Array or ReadableStream; prefer streaming for large files to minimize memory.

When uploading to multiple contexts, pieceCid should be pre-calculated and passed in options to avoid redundant computation. For streaming uploads, pieceCid must be provided as it cannot be calculated without consuming the stream.

Parameters

Parameter	Type	Description
`data`	`UploadPieceStreamingData`	Raw bytes or readable stream to upload
`options?`	`UploadOptions`	Upload options including callbacks, pieceMetadata, pieceCid, and signal

Returns

Promise<UploadResult>

Upload result with pieceCid, size, and a single-element copies array

create()

static create(options): Promise<StorageContext>

Defined in: packages/synapse-sdk/src/storage/context.ts:296

Static factory method to create a StorageContext Handles provider selection and data set selection/creation

Parameters

Parameter	Type
`options`	`StorageContextCreateOptions`

Returns

Promise<StorageContext>

createContexts()

static createContexts(options): Promise<StorageContext[]>

Defined in: packages/synapse-sdk/src/storage/context.ts:204

Creates storage contexts with specified options.

Three mutually exclusive modes:

dataSetIds provided: creates contexts for exactly those data sets
providerIds provided: creates contexts for exactly those providers
Neither provided: uses smart selection with count (default 2)

Parameters

Parameter	Type
`options`	`ContextCreateContextsOptions`

Returns

Promise<StorageContext[]>

performPreflightCheck()

static performPreflightCheck(options): Promise<PreflightInfo>

Defined in: packages/synapse-sdk/src/storage/context.ts:685

Static method to perform preflight checks for an upload

Parameters

Parameter	Type	Description
`options`	{ `size`: `number`; `warmStorageService`: `WarmStorageService`; `withCDN`: `boolean`; }	Options for the preflight check
`options.size`	`number`	The size of data to upload in bytes
`options.warmStorageService`	`WarmStorageService`	WarmStorageService instance
`options.withCDN`	`boolean`	Whether CDN is enabled

Returns

Promise<PreflightInfo>

Preflight check results without provider/dataSet specifics