# 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](/core-concepts/pdp-overview/))
- **Filecoin Pay** : Payment layer contract powered by ([Filecoin Pay](/core-concepts/filecoin-pay-overview/))
- **Filecoin Warm Storage Service** : Business logic contract powered by ([WarmStorage](/core-concepts/fwss-overview/))
- **Service Providers** : Service providers are the actors that safeguard the data stored in the Filecoin Onchain Cloud powered by the [Curio Storage software](https://github.com/filecoin-project/curio)

:::tip[New to Synapse SDK?]
**Start building in 5 minutes!** Follow the [**Getting Started Guide →**](/getting-started/) to install the SDK, configure your environment, and upload your first file to Filecoin Onchain Cloud.
:::

:::tip[Other Languages?]
Looking for Python or Go? Check out [Community Projects](/resources/community-projects/) for community-maintained SDKs.
:::

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:

```ts twoslash
// @lib: esnext,dom
import {
  Synapse,
  SynapseOptions,
  StorageInfo,
  PDPProvider,
} from "@filoz/synapse-sdk"
import type { PaymentsService } from "@filoz/synapse-sdk/payments"
import type { StorageManager } from "@filoz/synapse-sdk/storage"
// ---cut---
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<PDPProvider>
  getChainId(): number
  // Contract Addresses
  getWarmStorageAddress(): string
  getPaymentsAddress(): 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 →](/developer-guides/payments/payment-operations/) - _Learn the basics in less than 10 minutes_

[View Rails & Settlement Guide →](/developer-guides/payments/rails-settlement/) - _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 →](/developer-guides/storage/storage-operations/) - _Learn the basics in less than 10 minutes_

[View Storage Context Guide →](/developer-guides/storage/storage-context/) - _Learn the advanced storage concepts_

[View Storage Costs Guide →](/developer-guides/storage/storage-costs/) - _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.

:::note
These limits are defined in the SDK constants (`SIZE_CONSTANTS.MIN_UPLOAD_SIZE` and `SIZE_CONSTANTS.MAX_UPLOAD_SIZE`). While the underlying Curio PDP service supports files up to 254 MiB, the SDK currently limits uploads to 200 MiB. Future versions will support larger files through chunking and aggregate PieceCIDs.

See [this issue](https://github.com/FilOzone/synapse-sdk/issues/110) for details.
:::

### 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](https://docs.ipfs.tech/concepts/content-addressing/). 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](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md) 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.

```ts
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](/getting-started/) - Installation and setup guide
- [Payment Operations Guide](/developer-guides/payments/payment-operations/) - Complete payment operations reference
- [Storage Operations Guide](/developer-guides/storage/storage-operations/) - Complete storage operations reference
- [API Reference](/reference/filoz/synapse-sdk/toc/) - Full API documentation
- [GitHub Repository](https://github.com/FilOzone/synapse-sdk) - Source code and examples