Skip to content
foc Filecoin Onchain Cloud Documentation

Components

This page describes the components of the Synapse SDK and how they work together. You’ll learn how each component can be used independently, how they are organized within the SDK architecture, and how they interact with the underlying smart contracts and storage providers.

The SDK is built from these core components:

  • Synapse - Main SDK entry point with simple, high-level API
  • PaymentsService - SDK client for managing deposits, approvals, and payment rails (interacts with Filecoin Pay contract)
  • StorageManager, StorageContext - Storage operation classes
  • WarmStorageService - SDK client for storage coordination and pricing (interacts with WarmStorage contract)

The following diagram illustrates how these components relate to each other and the external systems they interact with:

graph LR
    subgraph "Public API"
        Synapse
    end

    subgraph "Payment Services"
        PS[PaymentsService]
    end

    subgraph "Storage Services"
        SM[StorageManager]
    end

    subgraph "Lower-Level"
        WSS[WarmStorageService]
        SC[StorageContext]
    end
    Synapse --> SM
    Synapse --> PS
    SM --> SC
    SM --> WSS
    PS --> SC

The SDK architecture is guided by several key principles that ensure maintainability, flexibility, and ease of use:

Design Principles:

  • Separation of Concerns: Protocol, business logic, and application layers are distinct
  • Composability: Each component can be used independently or together
  • Abstraction: SDK hides blockchain complexity from applications
  • Verification: All storage backed by cryptographic proofs

SDK Components

Section titled “SDK Components”

The SDK is organized into three layers, each serving a specific purpose:

  • High-Level API: The Synapse class provides a simple interface for common operations.
  • Service Layer: PaymentsService and StorageManager handle domain-specific logic.
  • Lower-Level Clients: Direct access to contracts and providers for advanced use cases.

Synapse

Section titled “Synapse”

Purpose: Main SDK entry point with simple, high-level API

API Reference: Synapse API Reference

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

This is your primary interface for all payment-related operations in the SDK.

API Reference: PaymentsService API Reference

Check out the Payment Operations guide for more details.

StorageManager

Section titled “StorageManager”

Purpose: High-level, auto-managed storage operations - upload and download data to and from the Filecoin Onchain Cloud.

API Reference: StorageManager API Reference

Check out the Storage Operations guide for more details.

StorageContext

Section titled “StorageContext”

Purpose: Provider-specific storage operations - upload and download data to and from the Filecoin Onchain Cloud.

API Reference: StorageContext API Reference

Check out the Storage Context guide for more details.

WarmStorageService

Section titled “WarmStorageService”

Purpose: SDK client for storage coordination and pricing - storage pricing and cost calculations, data set management and queries, metadata operations (data sets and pieces), service provider approval management, contract address discovery, data set creation verification.

API Reference: WarmStorageService API Reference

Complete Data Flow

Section titled “Complete Data Flow”

This sequence diagram shows the complete lifecycle of a file upload operation, from initialization through verification. Each step represents an actual blockchain transaction or API call.

sequenceDiagram
    participant Client
    participant SDK
    participant WarmStorage
    participant Curio
    participant PDPVerifier
    participant Payments

    Note over Client,Payments: Step 1: Preparation
    Client->>SDK: Initialize Synapse SDK
    SDK->>WarmStorage: Discover contract addresses

    Note over Client,Payments: Step 2: Payment Setup
    Client->>SDK: Check allowances
    SDK->>WarmStorage: getServicePrice()
    SDK->>Payments: accountInfo(client)
    alt Needs setup
        Client->>Payments: depositWithPermitAndApproveOperator()
    end

    Note over Client,Payments: Step 3: Storage Context
    Client->>SDK: synapse.storage.upload(data)
    SDK->>SDK: Auto-select provider or use default
    alt No data set exists
        SDK->>SDK: Sign CreateDataSet (EIP-712)
        SDK->>Curio: POST /pdp/data-sets (+ signature)
        Curio->>PDPVerifier: createDataSet(warmStorage, signature)
        PDPVerifier->>WarmStorage: dataSetCreated()
        WarmStorage->>Payments: createRail()
        Payments-->>WarmStorage: railId
    end

    Note over Client,Payments: Step 4: Upload & Register
    SDK->>SDK: Calculate PieceCID
    SDK->>Curio: POST /pdp/piece (upload data)
    Curio-->>SDK: uploadUUID
    SDK->>SDK: Sign AddPieces (EIP-712)
    SDK->>Curio: POST /pdp/data-sets/{id}/pieces
    Curio->>PDPVerifier: addPieces(dataSetId, pieces, signature)
    PDPVerifier->>WarmStorage: piecesAdded()
    WarmStorage->>WarmStorage: Store metadata
    WarmStorage-->>PDPVerifier: Success

    Note over Client,Payments: Step 5: Verification Begins
    PDPVerifier->>PDPVerifier: Schedule first challenge
    PDPVerifier-->>Client: Upload complete!

Next Steps

Section titled “Next Steps”

Choose your learning path based on your immediate needs:

Ready to Build?

Section titled “Ready to Build?”

Jump straight to code with the Getting Started Guide →

Want to Learn More?

Section titled “Want to Learn More?”