StorageContext

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

Constructors

Constructor

new StorageContext(options): StorageContext

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

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

Accessors

dataSetId

Get Signature

get dataSetId(): bigint | undefined

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

Returns

bigint | undefined

dataSetMetadata

Get Signature

get dataSetMetadata(): Record<string, string>

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

Returns

Record<string, string>

provider

Get Signature

get provider(): PDPProvider

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

Returns

PDPProvider

withCDN

Get Signature

get withCDN(): boolean

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

Returns

boolean

Methods

deletePiece()

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

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

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

Download data from this specific service provider

Parameters

Parameter	Type	Description
`options`	`DownloadOptions`	Download options

Returns

Promise<Uint8Array<ArrayBufferLike>>

The downloaded data Uint8Array

getPieces()

getPieces(options?): AsyncGenerator<PieceRecord>

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

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`; }	Optional configuration object
`options.batchSize?`	`bigint`	The batch size for each pagination call (default: 100)

Returns

AsyncGenerator<PieceRecord>

Yields

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

getProviderInfo()

getProviderInfo(): Promise<PDPProvider>

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

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

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

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

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

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

terminate()

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

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

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

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`	`UploadPieceStreamingData`
`options?`	`UploadOptions`

Returns

Promise<UploadResult>

create()

static create(options): Promise<StorageContext>

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

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

Creates new storage contexts with specified options Each context corresponds to a different data set

Parameters

Parameter	Type
`options`	`ContextCreateContextsOptions`

Returns

Promise<StorageContext[]>

performPreflightCheck()

static performPreflightCheck(options): Promise<PreflightInfo>

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

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