Synapse Core

Synapse Core (@filoz/synapse-core) is the low-level foundation that both the Synapse SDK and Synapse React build on. Use Synapse Core when you need:

• Direct control over individual contract calls without the Synapse class abstraction
• Custom integrations that combine only the modules you need

Setup

Install dependencies:

npm

npm install @filoz/synapse-core viem

Copy to clipboard

pnpm

pnpm add @filoz/synapse-core viem

Copy to clipboard

yarn

yarn add @filoz/synapse-core viem

Copy to clipboard

bun

bun add @filoz/synapse-core viem

Copy to clipboard

Synapse Core requires viem 2.x as a peer dependency.

Trying an unreleased version?

Install a preview build from a pull request, commit, or master. See Preview Packages.

Client setup:

All Synapse Core functions accept a viem Client as their first argument. Create one using viem’s standard client factories:

import { createPublicClient, createWalletClient } from "viem"
import { privateKeyToAccount } from "viem/accounts"
import { calibration } from "@filoz/synapse-core/chains"
import { getTransport } from "@filoz/synapse-core/client"

// Read-only client for queries
const publicClient = createPublicClient({
  chain: calibration, // or mainnet
  transport: getTransport(calibration),
})

// Wallet client for transactions
const account = privateKeyToAccount("0x...")
const walletClient = createWalletClient({
  account,
  chain: calibration, // or mainnet
  transport: getTransport(calibration),
})

Copy to clipboard

The @filoz/synapse-core/chains subpath exports chain definitions with all contract addresses pre-configured for Filecoin Mainnet (mainnet) and Filecoin testnet (calibration) networks. Import the FOC chain type as FilecoinChain when you need it in TypeScript.

The @filoz/synapse-core/client subpath exports getTransport (ranked Filecoin RPC fallbacks), asClient, and toReadClient. Prefer getTransport(chain) over a bare http() endpoint when talking to mainnet or Calibration.

Pagination

Collection actions in Synapse Core return one bounded page at a time. They share the same options and result shapes:

type PaginationOptions = {
  cursor?: bigint
  limit?: bigint
}

type Page<T> = {
  items: T[]
  nextCursor?: bigint
}

Copy to clipboard

Some actions also return a total alongside the page. A cursor is an opaque continuation value: pass the returned nextCursor back as cursor without calculating or incrementing it yourself. An omitted limit uses the action’s bounded default, while an explicit limit must be greater than 0n.

To read one page, call the action directly:

import { getClientDataSets } from "@filoz/synapse-core/warm-storage"

const page = await getClientDataSets(publicClient, {
  address,
  limit: 25n,
})

console.log(page.items)

if (page.nextCursor !== undefined) {
  const nextPage = await getClientDataSets(publicClient, {
    address,
    cursor: page.nextCursor,
    limit: 25n,
  })
  console.log(nextPage.items)
}

Copy to clipboard

Use paginate() when you want to traverse every page. It follows nextCursor, yields individual items, and rejects a repeated or non-advancing cursor. A normal break exits the for await loop, closes the generator, and prevents any further page requests.

import { paginate } from "@filoz/synapse-core"
import { getClientDataSetIds } from "@filoz/synapse-core/warm-storage"

for await (const dataSetId of paginate(({ cursor }) =>
  getClientDataSetIds(publicClient, { address, cursor })
)) {
  console.log(dataSetId)
}

const allDataSetIds = await Array.fromAsync(
  paginate(({ cursor }) =>
    getClientDataSetIds(publicClient, { address, cursor })
  )
)

Copy to clipboard

The exported *Call helpers remain literal ABI adapters for multicalls. They use contract-facing fields such as offset or startPieceId and require an explicit limit; cursor translation and default limits are handled by the corresponding action.

Payments

Query account balances, deposit funds, manage operator approvals, and settle payment rails on the Filecoin Pay contract.

import * as pay from "@filoz/synapse-core/pay"
import { parseUnits } from "viem"

// Query Filecoin Pay account info for the USDFC token
const info = await pay.accounts(publicClient, {
  // If not provided, the USDFC token address will be used.
  token: calibration.contracts.usdfc.address,
  address: account.address,
})
console.log(info.availableFunds) // bigint — funds available in Filecoin Pay

// Deposit USDFC in Filecoin Pay
const depositTxHash = await pay.depositAndApprove(walletClient, {
  // If not provided, the USDFC token address will be used.
  token: calibration.contracts.usdfc.address,
  amount: parseUnits("1", 18), // 1 USDFC
})

await publicClient.waitForTransactionReceipt({
  hash: depositTxHash
})

// Withdraw USDFC from Filecoin Pay
const withdrawTxHash = await pay.withdraw(walletClient, {
  // If not provided, the USDFC token address will be used.
  token: calibration.contracts.usdfc.address,
  amount: parseUnits("1", 18), // 1 USDFC
})

await publicClient.waitForTransactionReceipt({
  hash: withdrawTxHash
})

Copy to clipboard

Storage

List approved storage providers.

import * as warmStorage from "@filoz/synapse-core/warm-storage"

// Read one bounded page of approved provider IDs
const page = await warmStorage.getApprovedProviderIds(publicClient)
console.log(page.items, page.nextCursor)

Copy to clipboard

---

Create a data set and upload a file.

import * as piece from "@filoz/synapse-core/piece"
import * as sp from "@filoz/synapse-core/sp"
import { getPDPProvider } from "@filoz/synapse-core/sp-registry"

// 1. Select a provider
const provider = await getPDPProvider(publicClient, { providerId: 1n })
if (!provider) {
  throw new Error('Provider not found.');
}

// 2. Calculate PieceCID and upload data
const pieceCid = await piece.calculate(data)
console.log(pieceCid.size) // size of the piece in bytes
// Upload the piece to the provider
await sp.uploadPiece({
  data,
  pieceCid,
  serviceURL: provider.pdp.serviceURL,
})
// Poll the provider to confirm the piece is stored
await sp.findPiece({
  pieceCid,
  serviceURL: provider.pdp.serviceURL,
  poll: true,
})

console.log(`Piece ${pieceCid.toString()} uploaded to provider ${provider.pdp.serviceURL}`)

// 3. Create a data set and add the piece on-chain
const result = await sp.createDataSetAndAddPieces(walletClient, {
  serviceURL: provider.pdp.serviceURL,
  payee: provider.payee,
  cdn: false,
  pieces: [{ pieceCid }],
})

// 4. Wait for the transaction on chain (follows the provider's fee replacements)
const confirmed = await sp.waitForCreateDataSetAddPieces({ client: publicClient, ...result })

const { dataSetId, pieceIds, txHash } = confirmed

console.log(`Data set ${dataSetId} created and piece ${pieceCid.toString()} added to data set`)

Copy to clipboard

For large files, use uploadPieceStreaming instead of uploadPiece:

// Stream upload — PieceCID is calculated during transfer
const stream = new ReadableStream<Uint8Array>({ /* ... */ })
const uploaded = await sp.uploadPieceStreaming({
  data: stream,
  serviceURL,
  onProgress(bytes) {
    console.log(`${bytes} bytes uploaded`)
  },
})
console.log(uploaded.pieceCid) // PieceCID — calculated from streamed data
console.log(uploaded.size)     // number — total bytes uploaded

Copy to clipboard

---

Download a piece from a storage provider.

import { downloadAndValidate } from "@filoz/synapse-core/piece"

// Download a piece
const data = await downloadAndValidate({
  url: `${provider.pdp.serviceURL}/piece`,
  expectedPieceCid: "bafkzcib...",
})
console.log(data) // Uint8Array — downloaded piece data

Copy to clipboard

Provider Selection

For custom upload pipelines, you can use the provider selection functions directly to find matching data sets and providers:

import { fetchProviderSelectionInput, selectProviders } from "@filoz/synapse-core/warm-storage"

// Fetch all chain data needed for selection
const input = await fetchProviderSelectionInput(publicClient, {
  address: account.address,
})

// Primary: pass endorsedIds to restrict pool to endorsed providers only
const [primary] = selectProviders({
  ...input,
  count: 1,
  metadata: { source: "my-app" },
})

// Secondary: pass empty set to allow any approved provider
const [secondary] = selectProviders({
  ...input,
  endorsedIds: [],
  count: 1,
  excludeProviderIds: [primary.provider.id],
  metadata: { source: "my-app" },
})

Copy to clipboard

fetchProviderSelectionInput() makes a single multicall to gather providers, endorsements, and existing data sets. selectProviders() is a pure function (no network calls) that applies a 2-tier preference within the eligible pool:

1. Existing data set with matching metadata
2. New data set (no matching data set found)

The endorsedIds parameter controls which providers are eligible. When non-empty, only endorsed providers can be selected (no fallback to non-endorsed). When empty, all approved providers are eligible. See Storage Provider Tiers for what approval and endorsement mean and how providers qualify.

SP-to-SP Pull

Transfer pieces between providers without using client bandwidth:

import * as SP from "@filoz/synapse-core/sp"

const response = await SP.waitForPullPieces(walletClient, {
  serviceURL: secondaryProvider.pdp.serviceURL,
  pieces: [{
    pieceCid,
    sourceUrl: `${primaryProvider.pdp.serviceURL}/pdp/piece/${pieceCid}`,
  }],
  payee: secondaryProvider.payee,
  payer: account.address,
  cdn: false,
  metadata: {},
})

Copy to clipboard

This path requires manual EIP-712 signing. The signAddPieces and signCreateDataSetAndAddPieces functions from @filoz/synapse-core/typed-data handle the signature creation.

Check out the Synapse Core Reference for all available modules and functions.