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)
• PDPVerifier - Client for PDPVerifier contract - get data set and piece status, create data sets and add pieces
• PDPServer - HTTP client for Curio providers - create data sets and add pieces
• PDPAuthHelper - Signature generation utility - Generate EIP-712 signatures for authenticated operations (create data sets and add pieces)

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]
        PDPS[PDPServer]
        PDPA[PDPAuthHelper]
        PDPV[PDPVerifier]
    end
    Synapse --> SM
    Synapse --> PS
    SM --> SC
    SM --> WSS
    SC --> PDPS
    SC --> PDPA
    SC --> PDPV
    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

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

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

API Reference: Synapse API Reference

Synapse Interface:

interface SynapseAPI {
  // Create a new Synapse instance
  create(options: SynapseOptions): Promise<Synapse>;
  // Properties
  payments: PaymentsService;
  storage: StorageManager;
  // Storage Information (pricing, providers, service parameters, allowances)
  getStorageInfo(): Promise<StorageInfo>;
  getProviderInfo(providerAddress: string): Promise<ProviderInfo>;
  // Network Information
  getNetwork(): FilecoinNetworkType;
  getChainId(): number;
  // Contract Addresses
  getWarmStorageAddress(): string;
  getPaymentsAddress(): string;
  getPDPVerifierAddress(): string;
  // Ethers Helpers
  getProvider(): ethers.Provider;
  getSigner(): ethers.Signer;
}

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.

Payments Service Interface:

interface PaymentsServiceAPI {
  // Balances
  walletBalance(token: TokenIdentifier): Promise<bigint>;
  balance(): Promise<bigint>;
  accountInfo(token: TokenIdentifier): Promise<AccountInfo>;

  // Token Operations
  decimals(token: TokenIdentifier): number;
  allowance(spender: string, token: TokenIdentifier): Promise<bigint>;
  approve(spender: string, amount: TokenAmount): Transaction;
  // Deposits
  deposit(amount: TokenAmount): Transaction;
  depositWithPermit(amount: TokenAmount): Transaction;
  depositWithPermitAndApproveOperator(
    amount: TokenAmount,
    operator: string,
    rateAllowance: TokenAmount,
    lockupAllowance: TokenAmount,
    maxLockupPeriod: TokenAmount
  ): Transaction;

  // Operator management
  approveService(
    service: string,
    rateAllowance: TokenAmount,
    lockupAllowance: TokenAmount,
    maxLockupPeriod: TokenAmount,
    token: TokenIdentifier
  ): Transaction;
  revokeService(service: string, token: TokenIdentifier): Transaction;
  serviceApproval(service: string): Promise<ServiceApproval>;

  // Rails
  getRailsAsPayer(): Promise<RailInfo[]>;
  getRailsAsPayee(): Promise<RailInfo[]>;
  getRail(railId: bigint): Promise<Rail>;

  getSettlementAmounts(
    railId: bigint,
    targetEpoch?: bigint
  ): Promise<SettlementResult>;
  settle(railId: bigint, targetEpoch?: bigint): Transaction;
  settleTerminatedRail(railId: bigint): Transaction;
  settleAuto(railId: bigint, targetEpoch?: bigint): Transaction;
}

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.

Storage Manager Interface:

interface StorageManagerAPI {
  // Upload & Download
  upload(
    data: Uint8Array | ArrayBuffer,
    options?: StorageManagerUploadOptions
  ): Promise<UploadResult>;
  download(pieceCid: string | PieceCID): Promise<Uint8Array>;

  // Context Management
  createContext(options?: StorageServiceOptions): Promise<StorageContext>;
  getDefaultContext(): Promise<StorageContext>;

  // Data Set Management
  findDataSets(clientAddress?: string): Promise<EnhancedDataSetInfo[]>;
  terminateDataSet(dataSetId: number): Transaction;

  // Preflight & Info
  preflightUpload(
    size: number,
    options?: { withCDN?: boolean; metadata?: Record<string, string> }
  ): Promise<PreflightInfo>;
  getStorageInfo(): Promise<StorageInfo>;
}

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

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

WarmStorageService Interface:

interface WarmStorageServiceAPI {
  // Factory Method
  create(
    provider: ethers.Provider,
    warmStorageAddress: string
  ): Promise<WarmStorageService>

  // Data Set Queries
  getDataSet(dataSetId: number): Promise<DataSetInfo>
  getClientDataSets(clientAddress: string): Promise<DataSetInfo[]>
  getClientDataSetsWithDetails(
    client: string,
    onlyManaged?: boolean
  ): Promise<EnhancedDataSetInfo[]>

  // Metadata Operations
  getDataSetMetadata(dataSetId: number): Promise<Record<string, string>>
  getDataSetMetadataByKey(
    dataSetId: number,
    key: string
  ): Promise<string | null>
  getPieceMetadata(
    dataSetId: number,
    pieceId: number
  ): Promise<Record<string, string>>
  getPieceMetadataByKey(
    dataSetId: number,
    pieceId: number,
    key: string
  ): Promise<string | null>

  // Pricing & Cost Calculations
  getServicePrice(): Promise<ServicePriceInfo>
  calculateStorageCost(
    sizeInBytes: number
  ): Promise<CalculateStorageCostResult>
  checkAllowanceForStorage(
    sizeInBytes: number,
    withCDN: boolean,
    paymentsService: PaymentsService,
    lockupDays?: number
  ): Promise<CheckAllowanceForStorageResult>

  // Data Set Management
  terminateDataSet(signer: ethers.Signer, dataSetId: number): Transaction
  topUpCDNPaymentRails(
    signer: ethers.Signer,
    dataSetId: number,
    cdnAmountToAdd: bigint,
    cacheMissAmountToAdd: bigint
  ): Transaction

  getApprovedProviderIds(): Promise<number[]>
  isProviderIdApproved(providerId: number): Promise<boolean>

  getPDPConfig(): Promise<{
    maxProvingPeriod: number
    challengeWindowSize: number
    challengesPerProof: number
    initChallengeWindowStart: number
  }>

  getMaxProvingPeriod(): Promise<number>
  getChallengeWindow(): Promise<number>
}

PDPComponents

PDPVerifier

Purpose: Client for PDPVerifier contract - get dataset and piece status, create data sets and add pieces.

API Reference: PDPVerifier API Reference

PDPVerifier Example:

const pdpVerifier = new PDPVerifier(provider, pdpVerifierAddress);

// Check if data set is live
const isLive = await pdpVerifier.dataSetLive(dataSetId);

// Query data set information
const nextPieceId = await pdpVerifier.getNextPieceId(dataSetId);
const listener = await pdpVerifier.getDataSetListener(dataSetId);
const storageProvider = await pdpVerifier.getDataSetStorageProvider(dataSetId);
const leafCount = await pdpVerifier.getDataSetLeafCount(dataSetId);
const activePieces = await pdpVerifier.getActivePieces(dataSetId);

// Extract data set ID from transaction receipt
const extractedId = await pdpVerifier.extractDataSetIdFromReceipt(transactionReceipt);

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

Choose your learning path based on your immediate needs:

Ready to Build?

Jump straight to code with the Getting Started Guide →

• Storage Operations → - Upload and download your first file
• Storage Context → - Advanced storage operations and batch uploads
• Payment Operations → - Fund your account and manage payments
• Rails & Settlement → - Payment mechanics and settlement strategies

Want to Learn More?

• Architecture → - Understanding how all components work together
• PDP Overview → - Proof verification and data integrity
• Filecoin Pay → - Payment rails and lockup mechanisms
• Warm Storage Service → - Storage coordination and pricing model