Storage Context

Advanced Guide

This guide is for developers who need fine-grained control over storage operations. You’ll learn about explicit provider selection, batch uploads, lifecycle management, and download strategies.

Audience: Experienced developers building production applications Prerequisites: Complete the Storage Operations Guide first When to use this: Batch operations, custom callbacks, specific provider requirements, advanced error handling

Storage Context Overview

A Storage Context represents a connection to a specific storage provider and data set. Unlike the auto-managed approach in the Storage Operations Guide, contexts give you explicit control over provider selection, data set management, batch operations, lifecycle, and download strategies.

Note

You don’t always need to create contexts directly. synapse.storage.upload() creates and manages contexts internally — it uses the same StorageContext abstraction under the hood. Create contexts explicitly when you need the control described in this guide.

Storage Contexts

Create contexts via synapse.storage.createContext() or createContexts() for multi-copy scenarios.

Creating Contexts

import { Synapse } from "@filoz/synapse-sdk"
import { privateKeyToAccount } from "viem/accounts"

const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })

// Single context — all options are optional
await synapse.storage.createContext({
  providerId: 1n,           // specific provider (optional)
  dataSetId: 42n,           // specific data set (optional)
  metadata: { source: "my-app" },        // data set metadata for matching/creation
  withCDN: true,            // enable fast-retrieval (paid, optional)
  excludeProviderIds: [3n], // skip specific providers (optional)
})

For multi-copy replication, use createContexts():

// Multiple contexts for multi-copy
const contexts = await synapse.storage.createContexts({
  copies: 3,                   // number of contexts (default: 2)
  providerIds: [1n, 2n, 3n],   // specific providers (mutually exclusive with dataSetIds)
  dataSetIds: [10n, 20n, 30n], // specific data sets (mutually exclusive with providerIds)
})
const [primary, secondary] = contexts

View creation options for createContext()

View creation options for createContexts()

Data Set Selection and Matching

Metadata Matching for Cost Efficiency

The SDK reuses existing data sets when metadata matches exactly, avoiding duplicate payment rails. To maximize reuse:

• Use consistent metadata keys and values across uploads
• Avoid changing metadata unnecessarily
• Group related content with the same metadata

Example: If you create a data set with {Application: "MyApp", Version: "1.0"}, all subsequent uploads with the same metadata will reuse that data set and its payment rail.

The SDK intelligently manages data sets to minimize on-chain transactions. The selection behavior depends on the parameters you provide:

Selection Scenarios:

1. Explicit data set ID: If you specify dataSetId, that exact data set is used (must exist and be accessible)
2. Specific provider: If you specify providerId, the SDK searches for matching data sets only within that provider’s existing data sets
3. Automatic selection: Without specific parameters, the SDK searches across all your data sets with any approved provider

Exact Metadata Matching: In scenarios 2 and 3, the SDK will reuse an existing data set only if it has exactly the same metadata keys and values as requested. This ensures data sets remain organized according to your specific requirements.

Selection Priority: When multiple data sets match your criteria:

• Data sets with existing pieces are preferred over empty ones
• Within each group (with pieces vs. empty), the oldest data set (lowest ID) is selected

Provider Selection (when no matching data sets exist):

• If you specify a provider (via providerId), that provider is used
• Otherwise, the SDK selects from endorsed providers for the primary copy and any approved provider for secondaries
• Before finalizing selection, the SDK verifies the provider is reachable via a ping test
• If a provider fails the ping test, the SDK tries the next candidate
• A new data set will be created automatically during the first commit

Storage Context Methods

Tip

For manual control over the individual store, pull, and commit phases (instead of the combined upload() shown below), see Split Operations.

Uploading Data

Upload data to a provider and commit on-chain:

const context = await synapse.storage.createContext()

const result = await context.upload(data, {
  onStored: (providerId, pieceCid) => {
    console.log(`Data stored on provider ${providerId}`)
  },
  onPiecesAdded: (txHash, providerId, pieces) => {
    console.log(`On-chain commit submitted: ${txHash}`)
  },
  onPiecesConfirmed: (dataSetId, providerId, pieces) => {
    console.log(`Confirmed on-chain: dataSet=${dataSetId}, provider=${providerId}`)
  },
  onProgress: (bytes) => {
    console.log(`Uploaded ${bytes} bytes`)
  },
})

console.log(`Stored: ${result.pieceCid}, ${result.size} bytes`)

Terminating a Data Set

Irreversible Operation

Data set termination cannot be undone. Once initiated:

• The termination transaction is irreversible
• After the termination period, the provider may delete all data
• Payment rails associated with the data set will be terminated
• You cannot cancel the termination

Only terminate data sets when you’re certain you no longer need the data.

To delete an entire data set and discontinue payments for the service, call context.terminate(). This method submits an on-chain transaction to initiate the termination process. Following a defined termination period, payments will cease, and the service provider will be able to delete the data set.

You can also terminate a data set using synapse.storage.terminateDataSet({ dataSetId }), when the data set ID is known and creating a context is not necessary.

import { Synapse } from "@filoz/synapse-sdk"
import { privateKeyToAccount } from "viem/accounts"

const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
const ctx = await synapse.storage.createContext({
  metadata: { source: "my-app" },
})
// Via context
const hash = await ctx.terminate()
await synapse.client.waitForTransactionReceipt({ hash })
console.log("Dataset terminated successfully")

// Or directly by data set ID
const hash2 = await synapse.storage.terminateDataSet({ dataSetId: 42n })
await synapse.client.waitForTransactionReceipt({ hash: hash2 })

Deleting a Piece

To delete an individual piece from the data set, call context.deletePiece(). This method submits an on-chain transaction to initiate the deletion process.

Important: Piece deletion is irreversible and cannot be canceled once initiated.

import { Synapse } from "@filoz/synapse-sdk"
import { privateKeyToAccount } from "viem/accounts"

const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
const ctx = await synapse.storage.createContext({
  metadata: { source: "my-app" },
})
// List all pieces in the data set
const pieces = []
for await (const piece of ctx.getPieces()) {
  pieces.push(piece)
}

if (pieces.length > 0) {
  await ctx.deletePiece({ piece: pieces[0].pieceId })
  console.log(
    `Piece ${pieces[0].pieceCid} (ID: ${pieces[0].pieceId}) deleted successfully`
  )
}

// Delete by PieceCID
await ctx.deletePiece({ piece: "bafkzcib..." })

Downloading Options

The SDK provides flexible download options with clear semantics:

SP-Agnostic Download (from anywhere)

Download pieces from any available provider using the StorageManager:

// Download from any provider that has the piece
const data = await synapse.storage.download({ pieceCid })

// Download with CDN optimization (if available)
const dataWithCDN = await synapse.storage.download({ pieceCid, withCDN: true })

Context-Specific Download (from this provider)

When using a StorageContext, downloads are automatically restricted to that specific provider:

import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
import { privateKeyToAccount } from "viem/accounts"

const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
const ctx = await synapse.storage.createContext({
  metadata: { source: "my-app" },
})
const pieceCid = null as unknown as PieceCID;
// Downloads from the provider associated with this context
const data = await ctx.download({ pieceCid })

CDN Option Inheritance

The withCDN option follows a clear inheritance hierarchy:

1. Synapse level: Default setting for all operations
2. StorageContext level: Can override Synapse’s default
3. Method level: Can override instance settings

await synapse.storage.download({ pieceCid })                // Uses Synapse's withCDN: true
await ctx.download({ pieceCid })                            // Uses context's withCDN: false
await synapse.storage.download({ pieceCid, withCDN: false }) // Method override: CDN disabled

Note: When withCDN: true is set, it adds { withCDN: '' } to the data set’s metadata, ensuring CDN-enabled and non-CDN data sets remain separate.

Next Steps

• Split Operations — Learn how to manually control the store, pull, and commit phases for advanced upload workflows.

• Storage Operations — The high-level multi-copy upload API for most use cases. Start here if you haven’t used synapse.storage.upload() yet.

• Calculate Storage Costs — Plan your budget and fund your storage account. Use the quick calculator to estimate monthly costs.

• Payment Management — Manage deposits, approvals, and payment rails. Required before your first upload.