StorageManager

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

Constructors

Constructor

new StorageManager(
   synapse,
   warmStorageService,
   pieceRetriever,
   withCDN,
   dev,
   withIpni?): StorageManager;

Defined in: packages/synapse-sdk/src/storage/manager.ts:106

Parameters

Parameter	Type
`synapse`	`Synapse`
`warmStorageService`	`WarmStorageService`
`pieceRetriever`	`PieceRetriever`
`withCDN`	`boolean`
`dev`	`boolean`
`withIpni?`	`boolean`

Returns

StorageManager

Methods

createContext()

createContext(options?): Promise<StorageContext>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:506

Create a new storage context with specified options

Parameters

Parameter	Type
`options?`	`StorageServiceOptions`

Returns

Promise<StorageContext>

createContextFromDataSetId()

createContextFromDataSetId(dataSetId, options?): Promise<StorageContext>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:420

Create a storage context from an existing dataset ID without scanning all client datasets. This is optimized for reconnecting to a known dataset.

This method bypasses the expensive dataset enumeration in createContext({ dataSetId }), making it significantly faster when the client has many datasets.

Parameters

Parameter	Type	Description
`dataSetId`	`number`	The dataset ID to create a context for
`options?`	`StorageServiceOptions`	Optional storage options (withCDN, callbacks, etc.)

Returns

Promise<StorageContext>

Storage context for the specified dataset

Example

// Reconnect to a known dataset
const context = await synapse.storage.createContextFromDataSetId(123)
await context.upload(data)

createContexts()

createContexts(options?): Promise<StorageContext[]>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:342

Creates storage contexts for multi-provider storage deals and other operations.

By storing data with multiple independent providers, you reduce dependency on any single provider and improve overall data availability. Use contexts together as a group.

Contexts are selected by priority:

Specified datasets (dataSetIds) - uses their existing providers
Specified providers (providerIds or providerAddresses) - finds or creates matching datasets
Automatically selected from remaining approved providers

For automatic selection, existing datasets matching the metadata are reused unless forceCreateDataSets is true. Providers are randomly chosen to distribute across the network.

Parameters

Parameter	Type	Description
`options?`	`CreateContextsOptions`	Configuration options

Returns

Promise<StorageContext[]>

Promise resolving to array of storage contexts

download()

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

Defined in: packages/synapse-sdk/src/storage/manager.ts:234

Download data from storage If context is provided, routes to context.download() Otherwise performs SP-agnostic download

Parameters

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

Returns

Promise<Uint8Array<ArrayBufferLike>>

findDataSets()

findDataSets(clientAddress?): Promise<EnhancedDataSetInfo[]>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:584

Query data sets for this client

Parameters

Parameter	Type	Description
`clientAddress?`	`string`	Optional client address, defaults to current signer

Returns

Promise<EnhancedDataSetInfo[]>

Array of enhanced data set information including management status

getDefaultContext()

getDefaultContext(): Promise<StorageContext>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:575

Get or create the default context

Returns

Promise<StorageContext>

getStorageInfo()

getStorageInfo(): Promise<StorageInfo>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:604

Get comprehensive information about the storage service including approved providers, pricing, contract addresses, and current allowances

Returns

Promise<StorageInfo>

Complete storage service information

preflightUpload()

preflightUpload(size, options?): Promise<PreflightInfo>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:295

Run preflight checks for an upload without creating a context

Parameters

Parameter	Type	Description
`size`	`number`	The size of data to upload in bytes
`options?`	{ `metadata?`: `Record`<`string`, `string`>; `withCDN?`: `boolean`; }	Optional settings including withCDN flag and/or metadata
`options.metadata?`	`Record`<`string`, `string`>	-
`options.withCDN?`	`boolean`	-

Returns

Promise<PreflightInfo>

Preflight information including costs and allowances

terminateDataSet()

terminateDataSet(dataSetId): Promise<TransactionResponse>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:595

Terminate a data set with given ID that belongs to the synapse signer. This will also result in the removal of all pieces in the data set.

Parameters

Parameter	Type	Description
`dataSetId`	`number`	The ID of the data set to terminate

Returns

Promise<TransactionResponse>

Transaction response

upload()

upload(data, options?): Promise<PromiseSettledResult<UploadResult>[]>;

Defined in: packages/synapse-sdk/src/storage/manager.ts:134

Upload data to storage Uses the storage contexts or context provided in the options Otherwise creates/reuses default context

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

Note: Multi-context uploads (uploading to multiple providers simultaneously) currently only support Uint8Array. For streaming uploads with multiple contexts, convert your stream to Uint8Array first or use stream forking (future feature).

Parameters

Parameter	Type
`data`	\| `Uint8Array`<`ArrayBufferLike`> \| `AsyncIterable`<`Uint8Array`<`ArrayBufferLike`>, `any`, `any`> \| `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>
`options?`	`StorageManagerUploadOptions`

Returns

Promise<PromiseSettledResult<UploadResult>[]>