Synapse SDK

What is Synapse SDK?

Synapse SDK is a TypeScript SDK for interacting with the Filecoin Onchain Cloud - a smart-contract based marketplace for storage and other services in the Filecoin ecosystem. It provides a high-level API for interacting with the system. Additionally, it offers a low-level API for direct interaction with the underlying smart contracts and storage providers.

The SDK integrates with four key components of the Filecoin Onchain Cloud:

PDPVerifier : Proof verification contract powered by (PDP)
Filecoin Pay : Payment layer contract powered by (Filecoin Pay)
Filecoin Warm Storage Service : Business logic contract powered by (WarmStorage)
Service Providers : Service providers are the actors that safeguard the data stored in the Filecoin Onchain Cloud powered by the Curio Storage software

The SDK provides two primary components:

synapse.payments - Token operations, service authorizations, and payment rail settlements
synapse.storage - Data upload, download, and storage context management

The main Synapse class exposes this simple interface for all operations:

interface 
interface SynapseAPI
SynapseAPI {
  // Create a new Synapse instance
  
SynapseAPI.create(options: SynapseOptions): Promise<Synapse>
create(
options: SynapseOptions
options: 
(alias) interface SynapseOptions
import SynapseOptions
SynapseOptions): 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
class Synapse
Synapse>
  // Properties
  
SynapseAPI.payments: PaymentsService
payments: 
class PaymentsService
PaymentsService
  
SynapseAPI.storage: StorageManager
storage: 
class StorageManager
StorageManager
  // Storage Information (pricing, providers, service parameters, allowances)
  
SynapseAPI.getStorageInfo(): Promise<StorageInfo>
getStorageInfo(): 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
(alias) interface StorageInfo
import StorageInfo
StorageInfo>
  
SynapseAPI.getProviderInfo(providerAddress: string): Promise<PDPProvider>
getProviderInfo(
providerAddress: string
providerAddress: string): 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
(alias) interface PDPProvider
import PDPProvider
PDPProvider>
  
SynapseAPI.getChainId(): number
getChainId(): number
  // Contract Addresses
  
SynapseAPI.getWarmStorageAddress(): string
getWarmStorageAddress(): string
  
SynapseAPI.getPaymentsAddress(): string
getPaymentsAddress(): string
  
SynapseAPI.getPDPVerifierAddress(): string
getPDPVerifierAddress(): string
}

Payment Operations

Fund your account and manage payments for Filecoin storage services.

When You Need This

Required before uploading files (must fund account and approve operators)
To monitor account balance and health
If you’re a service provider managing settlements

View Payment Operations Guide → - Learn the basics in less than 10 minutes

View Rails & Settlement Guide → - Learn the advanced payment concepts

Storage Operations

The SDK provides comprehensive storage capabilities through two main approaches:

Auto-managed storage: Quick and simple - the SDK handles provider selection and data set creation.
Explicit control: Full control over providers, data sets, and batch operations.

To understand these storage approaches, you’ll need to be familiar with several key concepts:

Core Concepts

Storage Contexts: Manage storage lifecycle and provider connections.
Data Sets: Organize related data pieces with shared payment rails.
PieceCIDs: Unique content-addressed identifiers for stored data.
Service Providers: Infrastructure for decentralized storage with cryptographic proofs.

View Storage Operations Guide → - Learn the basics in less than 10 minutes

View Storage Context Guide → - Learn the advanced storage concepts

View Storage Costs Guide → - Learn how to calculate your storage costs

Technical Constraints and Concepts

The following sections cover important technical constraints and concepts that apply to all storage operations.

Metadata Limits

Metadata is subject to the following contract-enforced limits:

Data Set Metadata

Maximum of 10 key-value pairs per data set
Keys: Maximum 32 characters
Values: Maximum 128 characters

Piece Metadata

Maximum of 5 key-value pairs per piece
Keys: Maximum 32 characters
Values: Maximum 128 characters

These limits are enforced by the blockchain contracts. The SDK will validate metadata before submission and throw descriptive errors if limits are exceeded.

Size Constraints

The storage service enforces the following size limits for uploads:

Minimum: 127 bytes (required for PieceCID calculation)
Maximum: 200 MiB (209,715,200 bytes)

Attempting to upload data outside these limits will result in an error.

PieceCID

Understanding PieceCID is essential for working with Filecoin storage, as it serves as the unique identifier for your uploaded data.

PieceCID is Filecoin’s native content address identifier, a variant of CID. When you upload data, the SDK calculates a PieceCID—an identifier that:

Uniquely identifies your bytes, regardless of size, in a short string form
Enables retrieval from any provider storing those bytes
Contains embedded size information

Format Recognition:

PieceCID: Starts with bafkzcib, 64-65 characters - this is what Synapse SDK uses
LegacyPieceCID: Starts with baga6ea4seaq, 64 characters - for compatibility with other Filecoin services

PieceCID is also known as “CommP” or “Piece Commitment” in Filecoin documentation. The SDK exclusively uses PieceCID (v2 format) for all operations—you receive a PieceCID when uploading and use it for downloads.

LegacyPieceCID (v1 format) conversion utilities are provided for interoperability with other Filecoin services that may still use the older format.

Technical Reference: See FRC-0069 for the complete specification of PieceCID (“v2 Piece CID”) and its relationship to LegacyPieceCID (“v1 Piece CID”). Most Filecoin tooling currently uses v1, but the ecosystem is transitioning to v2.

Error Handling

The SDK provides consistent error handling across all operations to help you debug issues quickly.

try {
  await synapse.payments.deposit(amount);
} catch (error) {
  console.error(error.message); // Clear error description
  console.error(error.cause); // Underlying error if any
}

Additional Resources

Getting Started - Installation and setup guide
Payment Operations Guide - Complete payment operations reference
Storage Operations Guide - Complete storage operations reference
API Reference - Full API documentation
GitHub Repository - Source code and examples