Skip to content
foc Filecoin Onchain Cloud Documentation

Synapse SDK

What is Synapse SDK?

Section titled “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: Actors that safeguard data stored in the Filecoin Onchain Cloud, powered by the Curio Storage software

Core Modules

Section titled “Core Modules”
graph LR
    subgraph "Public API"
        Synapse
    end

    subgraph "Payment Operations"
        PS[PaymentsService]
    end

    subgraph "Storage Operations"
        SM[StorageManager]
    end

    subgraph "Lower-Level"
        WSS[WarmStorageService]
        SC[StorageContext]
    end
    Synapse --> SM
    Synapse --> PS
    SM --> SC
    SM --> WSS
  • Synapse: Is the main entry point with high-level API
  • PaymentsService: Manages deposits, approvals, and payment rails
  • StorageManager, StorageContext: Storage operation modules
  • WarmStorageService: Storage coordination and pricing module

Payment Operations

Section titled “Payment Operations”

Fund your account and manage payments for Filecoin storage services.

PaymentsService

Section titled “PaymentsService”

The PaymentsService provides direct access to the Filecoin Pay contract, enabling you to:

  • Manage token deposits and withdrawals
  • Approve operators for automated payments
  • Query and settle payment rails
  • Monitor account health and balance

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

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

API Reference: PaymentsService API Reference

Storage Operations

Section titled “Storage Operations”

Store data on Filecoin Onchain Cloud. The SDK provides storage with multi-copy durability by default. Synapse SDK offers two ways to work with storage operations:

  • Auto-Managed: The main entry point for storage operations through the StorageManager class (synapse.storage).
  • Explicit Control: Use StorageContext class for explicit control.

StorageManager

Section titled “StorageManager”

High-level storage operations with multi-copy durability. Stores data on multiple providers automatically, handling provider selection, SP-to-SP replication, and on-chain commit.

View Storage Operations Guide → - Multi-copy uploads in less than 10 minutes

API Reference: StorageManager API Reference

StorageContext

Section titled “StorageContext”

Provider-specific split operations (store → pull → commit). Used for batch uploads, custom error handling, and manual orchestration of multi-copy flows.

View Split Operations Guide → - Manual control over store, pull, and commit

API Reference: StorageContext API Reference

WarmStorageService

Section titled “WarmStorageService”

Low-level module for storage coordination and pricing:

  • Storage pricing and cost calculations
  • Data set management and queries
  • Metadata operations (data sets and pieces)
  • Get information about storage providers

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

API Reference: WarmStorageService API Reference

Technical Constraints

Section titled “Technical Constraints”

Metadata Limits

Section titled “Metadata Limits”

Metadata is subject to the following contract-enforced limits:

Data Set Metadata

Section titled “Data Set Metadata”
  • Maximum of 10 key-value pairs per data set
  • Keys: Maximum 32 characters
  • Values: Maximum 128 characters

Piece Metadata

Section titled “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

Section titled “Size Constraints”

Upload size limits:

  • Minimum: 127 bytes (required for PieceCID calculation)
  • Maximum: ~1 GiB (1,065,353,216 bytes)

PieceCID

Section titled “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.

Additional Resources

Section titled “Additional Resources”