StorageContext

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

Constructors

Constructor

new StorageContext(synapse, warmStorageService, provider, dataSetId, options, dataSetMetadata): StorageContext

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

Parameters

Parameter	Type
`synapse`	`Synapse`
`warmStorageService`	`WarmStorageService`
`provider`	`PDPProvider`
`dataSetId`	`bigint` \| `undefined`
`options`	`BaseContextOptions`
`dataSetMetadata`	`Record`<`string`, `string`>

Returns

StorageContext

Properties

serviceProvider

readonly serviceProvider: `0x${string}`

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

Accessors

dataSetId

Get Signature

get dataSetId(): bigint | undefined

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

Returns

bigint | undefined

dataSetMetadata

Get Signature

get dataSetMetadata(): Record<string, string>

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

Returns

Record<string, string>

provider

Get Signature

get provider(): PDPProvider

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

Returns

PDPProvider

withCDN

Get Signature

get withCDN(): boolean

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

Returns

boolean

Methods

commit()

commit(options): Promise<CommitResult>

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

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

This is the final step of the split upload flow. Pieces must be stored on the provider (via store() or pull()) before committing.

Parameters

Parameter	Type	Description
`options`	`CommitOptions`	Commit options including pieces to commit

Returns

Promise<CommitResult>

Transaction hash, piece IDs, and data set ID

deletePiece()

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

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

Delete a piece with given CID from this data set

Parameters

Parameter	Type	Description
`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(pieceCid, options?): Promise<Uint8Array<ArrayBufferLike>>

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

Download data from this specific service provider

Parameters

Parameter	Type	Description
`pieceCid`	`string` \| `PieceLink`	The PieceCID identifier
`options?`	`DownloadOptions`	Download options

Returns

Promise<Uint8Array<ArrayBufferLike>>

The downloaded data

getDataSetPieces()

getDataSetPieces(): Promise<PieceLink[]>

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

Get the list of piece CIDs for this service service’s data set.

Returns

Promise<PieceLink[]>

Array of piece CIDs as PieceCID objects

getPieces()

getPieces(options?): AsyncGenerator<PieceRecord>

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

Get all active pieces for this data set as an async generator. This provides lazy evaluation and better memory efficiency for large data sets.

Parameters

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

Returns

AsyncGenerator<PieceRecord>

Yields

Object with pieceCid and pieceId - the piece ID is needed for certain operations like deletion

getPieceUrl()

getPieceUrl(pieceCid): string

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

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	Description
`pieceCid`	`PieceLink`	The PieceCID to get URL for

Returns

string

The full retrieval URL

getProviderInfo()

getProviderInfo(): Promise<PDPProvider>

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

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

Get pieces scheduled for removal from this data set

Returns

Promise<readonly bigint[]>

Array of piece IDs scheduled for removal

hasPiece()

hasPiece(pieceCid): Promise<boolean>

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

Check if a piece exists on this service provider.

Parameters

Parameter	Type	Description
`pieceCid`	`string` \| `PieceLink`	The PieceCID (piece CID) to check

Returns

Promise<boolean>

True if the piece exists on this provider, false otherwise

pieceStatus()

pieceStatus(pieceCid): Promise<PieceStatus>

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

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
`pieceCid`	`string` \| `PieceLink`	The PieceCID (piece CID) to check

Returns

Promise<PieceStatus>

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

preflightUpload()

preflightUpload(size): Promise<PreflightInfo>

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

Run preflight checks for an upload

Parameters

Parameter	Type	Description
`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:919

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 with optional pieceMetadata (must match what commit() will receive)

Returns

Promise<`0x${string}`>

Signed extraData blob

providerDownload()

providerDownload(pieceCid, options?): Promise<Uint8Array<ArrayBufferLike>>

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

Download data from the service provider

Parameters

Parameter	Type
`pieceCid`	`string` \| `PieceLink`
`options?`	`DownloadOptions`

Returns

Promise<Uint8Array<ArrayBufferLike>>

pull()

pull(options): Promise<PullResult>

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

Request this provider to pull pieces from another provider.

This is used for multi-copy uploads where data is stored once on a primary provider and then pulled to secondary providers via SP-to-SP transfer.

Parameters

Parameter	Type	Description
`options`	`PullOptions`	Pull options including pieces and source

Returns

Promise<PullResult>

Result with status for each piece

store()

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

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

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

This is the first step of the split upload flow: store → pull → commit. After storing, the piece is “parked” on the provider and ready for:

Retrieval via getPieceUrl() (although it is not yet committed on-chain and is therefore eligible for garbage collection)
Pulling to other providers via pull()
On-chain commitment via commit()

Parameters

Parameter	Type	Description
`data`	`Uint8Array`<`ArrayBufferLike`> \| `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>	Data to store (Uint8Array or ReadableStream)
`options?`	`StoreOptions`	Optional store configuration

Returns

Promise<StoreResult>

The PieceCID and size of the stored data

terminate()

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

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

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

Upload data to the service provider

Accepts Uint8Array or ReadableStream. For large files, prefer streaming to minimize memory usage.

Note: 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 in options as it cannot be calculated without consuming the stream.

Parameters

Parameter	Type
`data`	`Uint8Array`<`ArrayBufferLike`> \| `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>
`options?`	`UploadOptions`

Returns

Promise<UploadResult>

create()

static create(synapse, warmStorageService, options?): Promise<StorageContext>

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

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

Parameters

Parameter	Type
`synapse`	`Synapse`
`warmStorageService`	`WarmStorageService`
`options`	`CreateContextOptions`

Returns

Promise<StorageContext>

createContexts()

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

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

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
`synapse`	`Synapse`
`warmStorageService`	`WarmStorageService`
`options`	`CreateContextsOptions`

Returns

Promise<StorageContext[]>

performPreflightCheck()

static performPreflightCheck(warmStorageService, paymentsService, size, withCDN): Promise<PreflightInfo>

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

Static method to perform preflight checks for an upload

Parameters

Parameter	Type	Description
`warmStorageService`	`WarmStorageService`	WarmStorageService instance
`paymentsService`	`PaymentsService`	PaymentsService instance
`size`	`number`	The size of data to upload in bytes
`withCDN`	`boolean`	Whether CDN is enabled

Returns

Promise<PreflightInfo>

Preflight check results without provider/dataSet specifics