StorageManager
Defined in: packages/synapse-sdk/src/storage/manager.ts:147
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new StorageManager(
options):StorageManager
Defined in: packages/synapse-sdk/src/storage/manager.ts:158
Creates a new StorageManager
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | StorageManagerOptions | The options for the StorageManager StorageManagerOptions |
Returns
Section titled “Returns”StorageManager
Accessors
Section titled “Accessors”source
Section titled “source”Get Signature
Section titled “Get Signature”get source():
string|null
Defined in: packages/synapse-sdk/src/storage/manager.ts:170
The application source identifier used for dataset namespace isolation.
Set via Synapse.create({ source }). Used by combineMetadata to tag
datasets so that different applications sharing a wallet don’t collide.
Returns
Section titled “Returns”string | null
withCDN
Section titled “withCDN”Get Signature
Section titled “Get Signature”get withCDN():
boolean
Defined in: packages/synapse-sdk/src/storage/manager.ts:178
Whether CDN rails are enabled for new datasets by default.
Set via Synapse.create({ withCDN }).
Returns
Section titled “Returns”boolean
Methods
Section titled “Methods”calculateMultiContextCosts()
Section titled “calculateMultiContextCosts()”calculateMultiContextCosts(
contexts,options):Promise<OutputType>
Defined in: packages/synapse-sdk/src/storage/manager.ts:707
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 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:939
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:881
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:560
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:1010
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:1000
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:1066
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:636
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:658
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
terminateService()
Section titled “terminateService()”terminateService(
options):Promise<TerminateServiceResult>
Defined in: packages/synapse-sdk/src/storage/manager.ts:1037
Terminate the storage service for a data set belonging to the synapse signer.
By default the request is relayed through the data set’s service provider: the client signs an EIP-712 authorization and the provider submits the transaction (paying the gas), in exchange for a small fee drawn from the payer’s account. Provider-relayed termination takes effect immediately; it requires the payer’s account to cover settlement in full and fails otherwise, rather than falling back to a lockup wind-down.
With skipProvider: true the transaction is submitted directly from the
signer’s wallet. No provider cooperation is needed, but the service and
its payments run to the end of the lockup period (typically ~30 days;
the actual end is endEpoch in the result).
Either way, termination ends the service and its payments; the data set’s remaining on-chain state is cleaned up later by the provider, not by this call.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options | TerminateServiceOptions | TerminateServiceOptions |
Returns
Section titled “Returns”Promise<TerminateServiceResult>
The termination outcome TerminateServiceResult
upload()
Section titled “upload()”upload(
data,options?):Promise<UploadResult>
Defined in: packages/synapse-sdk/src/storage/manager.ts:206
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)