StorageContext

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

Constructors

Constructor

new StorageContext(options): StorageContext

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

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:130

Accessors

dataSetId

Get Signature

get dataSetId(): bigint | undefined

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

Returns

bigint | undefined

dataSetMetadata

Get Signature

get dataSetMetadata(): Record<string, string>

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

Returns

Record<string, string>

provider

Get Signature

get provider(): PDPProvider

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

Returns

PDPProvider

withCDN

Get Signature

get withCDN(): boolean

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

Returns

boolean

Methods

commit()

commit(options): Promise<CommitResult>

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

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.

Aborting options.signal after onSubmitted only stops waiting for confirmation; the transaction can still land. If it was creating the data set, this context does not learn the new data set ID, and a later commit() on it creates another data set.

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:1322

Delete a piece with the given CID or piece ID from this data set.

Parameters

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

Returns

Promise<`0x${string}`>

Transaction hash of the delete operation

deletePieces()

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

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

Delete pieces with the given CIDs or piece IDs from this data set in one transaction.

Parameters

Parameter	Type	Description
`options`	{ `pieces`: (`string` \| `bigint` \| `PieceCID`)[]; }	Options for the delete operation
`options.pieces`	(`string` \| `bigint` \| `PieceCID`)[]	PieceCID identifiers or piece numbers to delete by piece ID

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:1196

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:1247

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:1074

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

Returns

string

getProviderInfo()

getProviderInfo(): Promise<PDPProvider>

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

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:1233

Get pieces scheduled for removal from this data set.

Returns

Promise<readonly bigint[]>

Array of piece IDs scheduled for removal

pieceStatus()

pieceStatus(options): Promise<PieceStatus | null>

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

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` \| `PieceCID`; }	Options for the piece status
`options.pieceCid`	`string` \| `PieceCID`	The PieceCID (piece CID) to check

Returns

Promise<PieceStatus | null>

Status information including data set timing and retrieval URL

presignForCommit()

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

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

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:891

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, timeout, 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:813

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(options?): Promise<TerminateServiceResult>

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

Terminate the storage service for this context’s data set.

Relays through this provider by default (immediate); pass skipProvider: true to submit the transaction directly and wind down over the lockup period. See StorageManager.terminateService for full semantics.

Parameters

Parameter	Type	Description
`options?`	`Pick`<`TerminateServiceOptions`, `"onSubmitted"` \| `"skipProvider"`>	Optional `skipProvider` and `onSubmitted` TerminateServiceOptions

Returns

Promise<TerminateServiceResult>

The termination outcome TerminateServiceResult

upload()

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

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

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:355

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:260

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[]>

resolveByDataSetId()

static resolveByDataSetId(dataSetId, warmStorageService, spRegistry, clientAddress): Promise<ProviderSelectionResult>

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

Resolve using a specific data set ID. Also used by StorageManager.terminateService to locate the data set’s provider.

Parameters

Parameter	Type
`dataSetId`	`bigint`
`warmStorageService`	`WarmStorageService`
`spRegistry`	`SPRegistryService`
`clientAddress`	`string`

Returns

Promise<ProviderSelectionResult>