StorageManager
Defined in: packages/synapse-sdk/src/storage/manager.ts:143
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new StorageManager(
options):StorageManager
Defined in: packages/synapse-sdk/src/storage/manager.ts:154
Creates a new StorageManager
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | StorageManagerOptions | The options for the StorageManager StorageManagerOptions |
Returns
Section titled “Returns”StorageManager
Methods
Section titled “Methods”calculateMultiContextCosts()
Section titled “calculateMultiContextCosts()”calculateMultiContextCosts(
contexts,options):Promise<OutputType>
Defined in: packages/synapse-sdk/src/storage/manager.ts:686
Calculate upload costs aggregated across multiple storage contexts.
Each context creates its own PDP payment rail with its own lockup. This method correctly sums per-context lockup while computing account-level debt, runway, and buffer only once (they are shared across all contexts from the same payer).
Dataset sizes are fetched from chain for existing datasets to get accurate floor-aware rate deltas.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
contexts | StorageContext[] | Storage contexts to aggregate costs for |
options | Pick<PrepareOptions, "dataSize" | "extraRunwayEpochs" | "bufferEpochs"> | Upload options (dataSize, extraRunwayEpochs, bufferEpochs) |
Returns
Section titled “Returns”Aggregated upload costs with summed rates and single deposit/approval
createContext()
Section titled “createContext()”createContext(
options?):Promise<StorageContext>
Defined in: packages/synapse-sdk/src/storage/manager.ts:884
Create a single storage context with specified options
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
options? | StorageServiceOptions |
Returns
Section titled “Returns”createContexts()
Section titled “createContexts()”createContexts(
options?):Promise<StorageContext[]>
Defined in: packages/synapse-sdk/src/storage/manager.ts:826
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) - finds or creates matching datasets - Automatically selected from remaining approved providers
For automatic selection, existing datasets matching the metadata are reused.
Providers are randomly chosen to distribute across the network.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options? | CreateContextsOptions | Configuration options CreateContextsOptions |
Returns
Section titled “Returns”Promise resolving to array of storage contexts
download()
Section titled “download()”download(
options):Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/synapse-sdk/src/storage/manager.ts:539
Download data from storage If context is provided, routes to context.download() Otherwise performs SP-agnostic download
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
options | StorageManagerDownloadOptions |
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
findDataSets()
Section titled “findDataSets()”findDataSets(
options?):Promise<EnhancedDataSetInfo[]>
Defined in: packages/synapse-sdk/src/storage/manager.ts:955
Query data sets for this client
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | { address?: `0x${string}`; } | The options for the find data sets |
options.address? | `0x${string}` | The client address, defaults to current signer |
Returns
Section titled “Returns”Promise<EnhancedDataSetInfo[]>
Array of enhanced data set information including management status
getDefaultContext()
Section titled “getDefaultContext()”getDefaultContext():
Promise<StorageContext>
Defined in: packages/synapse-sdk/src/storage/manager.ts:945
Get or create the default context
Returns
Section titled “Returns”getStorageInfo()
Section titled “getStorageInfo()”getStorageInfo():
Promise<StorageInfo>
Defined in: packages/synapse-sdk/src/storage/manager.ts:976
Get comprehensive information about the storage service including approved providers, pricing, contract addresses, and current allowances
Returns
Section titled “Returns”Complete storage service information
getUploadCosts()
Section titled “getUploadCosts()”getUploadCosts(
options):Promise<OutputType>
Defined in: packages/synapse-sdk/src/storage/manager.ts:615
Get upload costs including rate, deposit needed, and approval state.
Wraps the synapse-core getUploadCosts() function, automatically injecting
the client address. No StorageContext needed — works with primitive values.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | Omit<GetUploadCostsOptions, "clientAddress"> | Upload cost options (clientAddress auto-injected) |
Returns
Section titled “Returns”Upload costs including rate, deposit needed, and readiness
prepare()
Section titled “prepare()”prepare(
options):Promise<PrepareResult>
Defined in: packages/synapse-sdk/src/storage/manager.ts:637
Prepare the account for upload by computing costs and returning a transaction to execute.
Can accept pre-computed costs (from a prior getUploadCosts() call) to skip redundant RPC,
or computes them internally. When no context is provided, creates default contexts
(mirroring the upload() flow).
Aggregates per-context lockup correctly for any number of contexts:
- Fetches each existing dataset’s size from chain
- Sums lockup across all contexts
- Computes debt, runway, and buffer once at the account level
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | PrepareOptions | PrepareOptions |
Returns
Section titled “Returns”PrepareResult with costs and an optional transaction
terminateDataSet()
Section titled “terminateDataSet()”terminateDataSet(
options):Promise<`0x${string}`>
Defined in: packages/synapse-sdk/src/storage/manager.ts:967
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
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | { dataSetId: bigint; } | The options for the terminate data set |
options.dataSetId | bigint | The ID of the data set to terminate |
Returns
Section titled “Returns”Promise<`0x${string}`>
Transaction hash
upload()
Section titled “upload()”upload(
data,options?):Promise<UploadResult>
Defined in: packages/synapse-sdk/src/storage/manager.ts:185
Upload data to Filecoin Onchain Cloud using a store->pull->commit flow across multiple providers.
By default, uploads to 2 providers (primary + secondary) for redundancy. Data is uploaded once to the primary, then secondaries pull from the primary via SP-to-SP transfer.
This method only throws if zero copies succeed. Partial success (some but
not all copies) is indicated by result.complete === false. Check complete
to determine overall success. Don’t use failedAttempts.length as a failure
signal as failedAttempts exists as a diagnostic for intermediate failures.
For large files, prefer streaming to minimize memory usage.
For uploading multiple files, use the split operations API directly: createContexts() -> store() -> presignForCommit() -> pull() -> commit()
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data | UploadPieceStreamingData | Raw bytes (Uint8Array) or ReadableStream to upload |
options? | StorageManagerUploadOptions | Upload options including contexts, callbacks, and abort signal |
Returns
Section titled “Returns”Upload result with pieceCid, copies, and completion status
Throws
Section titled “Throws”StoreError if primary store fails (before any data is committed)
Throws
Section titled “Throws”CommitError if all commit attempts fail (data stored but not on-chain)