Package Exports
- @filoz/synapse-sdk
- @filoz/synapse-sdk/browser
- @filoz/synapse-sdk/commp
- @filoz/synapse-sdk/pandora
- @filoz/synapse-sdk/payments
- @filoz/synapse-sdk/pdp
Readme
Synapse SDK
A JavaScript/TypeScript SDK for interacting with Filecoin Synapse - a smart-contract based marketplace for storage and other services in the Filecoin ecosystem.
Overview
The Synapse SDK is designed with flexibility in mind:
- 🚀 Recommended Usage: Use the high-level
Synapseclass for a streamlined experience with sensible defaults - 🔧 Composable Components: Import and use individual components for fine-grained control over specific functionality
Whether you're building a quick prototype or a complex application with specific requirements, the SDK adapts to your needs.
Installation
npm install @filoz/synapse-sdk ethersNote: ethers v6 is a peer dependency and must be installed separately.
Table of Contents
- Overview
- Installation
- Recommended Usage
- Using Individual Components
- Network Configuration
- Browser Integration
- Additional Information
- Contributing
- License
Recommended Usage
The Synapse class provides a complete, easy-to-use interface for interacting with Filecoin storage services.
Quick Start
import { Synapse, RPC_URLS, TOKENS } from '@filoz/synapse-sdk'
// Initialize with private key
const synapse = await Synapse.create({
privateKey: '0x...',
rpcURL: RPC_URLS.mainnet.websocket
})
// Check balance of USDFC in the payments contract
const paymentsBalance = await synapse.payments.balance(TOKENS.USDFC)
console.log('USDFC balance in payments contract:',
ethers.formatUnits(paymentsBalance, synapse.payments.decimals(TOKENS.USDFC)))
// Deposit funds for storage operations
const amount = ethers.parseUnits('10', synapse.payments.decimals(TOKENS.USDFC))
await synapse.payments.deposit(amount, TOKENS.USDFC)
// Or manually approve service for creating payment rails
await synapse.payments.approveService(
serviceAddress,
// 10 USDFC per epoch rate allowance
ethers.parseUnits('10', synapse.payments.decimals(TOKENS.USDFC)),
// 1000 USDFC lockup allowance
ethers.parseUnits('1000', synapse.payments.decimals(TOKENS.USDFC))
)
// Create storage service and upload data
const storage = await synapse.createStorage()
// Upload data
const uploadResult = await storage.upload(
new TextEncoder().encode('Hello Filecoin!')
)
console.log(`Upload complete! CommP: ${uploadResult.commp}`)
console.log(`Size: ${uploadResult.size} bytes`)
// Download data
const data = await storage.download(uploadResult.commp)
console.log(new TextDecoder().decode(data))Note: The above code won't work currently due to a bug in dealing with small data. See this issue for more details and progress on addressing it.
With MetaMask
import { Synapse } from '@filoz/synapse-sdk'
import { ethers } from 'ethers'
// Connect to MetaMask
const provider = new ethers.BrowserProvider(window.ethereum)
const synapse = await Synapse.create({ provider })
// Same API as above
const balance = await synapse.payments.walletBalance()Advanced Payment Control
For users who need fine-grained control over token approvals:
import { Synapse, TOKENS, CONTRACT_ADDRESSES } from '@filoz/synapse-sdk'
const synapse = await Synapse.create({ provider })
// Check current allowance
const paymentsContract = CONTRACT_ADDRESSES.PAYMENTS[network]
const currentAllowance = await synapse.payments.allowance(TOKENS.USDFC, paymentsContract)
// Approve only if needed
if (currentAllowance < requiredAmount) {
await synapse.payments.approve(TOKENS.USDFC, paymentsContract, requiredAmount)
}
// Now deposit (won't trigger approval since we already approved)
await synapse.payments.deposit(requiredAmount, TOKENS.USDFC)
// Service operator approvals (required before creating proof sets)
const serviceAddress = '0x394feCa6bCB84502d93c0c5C03c620ba8897e8f4' // Pandora
// Approve service to create payment rails on your behalf
await synapse.payments.approveService(
serviceAddress,
// 10 USDFC per epoch rate allowance
ethers.parseUnits('10', synapse.payments.decimals(TOKENS.USDFC)),
// 1000 USDFC lockup allowance
ethers.parseUnits('1000', synapse.payments.decimals(TOKENS.USDFC))
)
// Check service approval status
const serviceStatus = await synapse.payments.serviceApproval(serviceAddress)
console.log('Service approved:', serviceStatus.isApproved)
console.log('Rate allowance:', serviceStatus.rateAllowance)
console.log('Rate used:', serviceStatus.rateUsed)
// Revoke service if needed
await synapse.payments.revokeService(serviceAddress)API Reference
Constructor Options
interface SynapseOptions {
// Wallet Configuration (exactly one required)
privateKey?: string // Private key for signing
provider?: ethers.Provider // Browser provider (MetaMask, etc.)
signer?: ethers.Signer // External signer
// Network Configuration
rpcURL?: string // RPC endpoint URL
authorization?: string // Authorization header (e.g., 'Bearer TOKEN')
// Advanced Configuration
disableNonceManager?: boolean // Disable automatic nonce management
withCDN?: boolean // Enable CDN for retrievals
pandoraAddress?: string // Override Pandora service contract address
}Synapse Methods
payments- Access payment-related functionality (see below)createStorage(options?)- Create a storage service instance (see Storage Service Creation)
Synapse.payments Methods
Balance Operations:
walletBalance(token?)- Get wallet balance (FIL or USDFC)balance(token?)- Get available balance in payments contract (accounting for lockups)accountInfo(token?)- Get detailed account info including funds, lockup details, and available balancegetCurrentEpoch()- Get the current Filecoin epoch numberdecimals(token?)- Get token decimals
Token Operations:
deposit(amount, token?)- Deposit funds to payments contract (handles approval automatically)withdraw(amount, token?)- Withdraw funds from payments contractapprove(token, spender, amount)- Approve token spending (for manual control)allowance(token, spender)- Check current token allowance
Service Approvals:
approveService(service, rateAllowance, lockupAllowance, token?)- Approve a service contract as operatorrevokeService(service, token?)- Revoke service operator approvalserviceApproval(service, token?)- Check service approval status and allowances
Storage Service Creation
The SDK automatically handles all the complexity of storage setup for you - selecting providers, managing proof sets, and coordinating with the blockchain. You just call createStorage() and the SDK takes care of everything.
Behind the scenes, the process may be:
- Fast (<1 second): When reusing existing infrastructure
- Slower (2-5 minutes): When setting up new blockchain infrastructure
Basic Usage
// Simple creation with default provider selection
const storage = await synapse.createStorage()Advanced Usage with Callbacks
Monitor the creation process with detailed callbacks:
const storage = await synapse.createStorage({
providerId: 1, // Optional: use specific provider ID
withCDN: true, // Optional: enable CDN for faster downloads
callbacks: {
// Called when a provider is selected
onProviderSelected: (provider) => {
console.log(`Selected provider: ${provider.owner}`)
console.log(` PDP URL: ${provider.pdpUrl}`)
},
// Called when proof set is found or created
onProofSetResolved: (info) => {
if (info.isExisting) {
console.log(`Using existing proof set: ${info.proofSetId}`)
} else {
console.log(`Created new proof set: ${info.proofSetId}`)
}
},
// Only called when creating a new proof set
onProofSetCreationStarted: (txHash, statusUrl) => {
console.log(`Creation transaction: ${txHash}`)
if (statusUrl) {
console.log(`Monitor status at: ${statusUrl}`)
}
},
// Progress updates during proof set creation
onProofSetCreationProgress: (status) => {
const elapsed = Math.round(status.elapsedMs / 1000)
console.log(`[${elapsed}s] Mining: ${status.transactionMined}, Live: ${status.proofSetLive}`)
}
}
})Creation Options
interface StorageServiceOptions {
providerId?: number // Specific provider ID to use
withCDN?: boolean // Enable CDN services
callbacks?: StorageCreationCallbacks // Progress callbacks
}Upload Methods
Once created, use the storage service to upload and download data:
// Upload with progress callbacks
const result = await storage.upload(data, {
onUploadComplete: (commp) => {
console.log(`Upload complete! CommP: ${commp}`)
},
onRootAdded: () => {
console.log('Data added to proof set')
}
})
// Download data
const downloaded = await storage.download(result.commp)Size Constraints
The storage service enforces the following size limits for uploads:
- Minimum: 65 bytes
- Maximum: 200 MiB (209,715,200 bytes)
Attempting to upload data outside these limits will result in an error.
Note: The minimum size is currently much larger than 65 bytes due to bugs that are being addressed. See this issue for more details and progress on addressing it.
Using Individual Components
All components can be imported and used independently for advanced use cases. The SDK is organized to match the external service structure:
Payments Service
Direct interface to the Payments contract for token operations and operator approvals.
import { PaymentsService } from '@filoz/synapse-sdk/payments'
import { ethers } from 'ethers'
const provider = new ethers.JsonRpcProvider(rpcUrl)
const signer = await provider.getSigner()
const paymentsService = new PaymentsService(provider, signer, 'calibration', false)
// Deposit USDFC to payments contract
await paymentsService.deposit(amount) // amount in base uints
// Check account info
const info = await paymentsService.accountInfo() // Uses USDFC by default
console.log('Available funds:', info.availableFunds)
// Approve service as operator
await paymentsService.approveService(
serviceAddress, // e.g., Pandora contract address
rateAllowance, // per-epoch rate allowance in base units
lockupAllowance // total lockup allowance in base units
)Pandora Service
Interact with the Pandora contract for proof set management, storage provider operations, and storage cost calculations.
import { PandoraService } from '@filoz/synapse-sdk/pandora'
const pandoraService = new PandoraService(provider, pandoraAddress)
// Storage cost calculations
const costs = await pandoraService.calculateStorageCost(sizeInBytes)
console.log(`Storage cost: ${costs.perMonth} per month`)
// Check allowances for storage (returns allowance details and costs)
const check = await pandoraService.checkAllowanceForStorage(
sizeInBytes,
withCDN,
paymentsService // Pass PaymentsService instance
)
// check.sufficient - boolean indicating if allowances are sufficient
// check.costs - storage costs per epoch/day/month
// Prepare storage upload
const prep = await pandoraService.prepareStorageUpload({
dataSize: sizeInBytes,
withCDN: false
}, paymentsService)
// Get client proof sets with enhanced details
const proofSets = await pandoraService.getClientProofSetsWithDetails(clientAddress)
for (const ps of proofSets) {
console.log(`Rail ID: ${ps.railId}, PDP Verifier ID: ${ps.pdpVerifierProofSetId}`)
console.log(`Is Live: ${ps.isLive}, Is Managed: ${ps.isManaged}`)
console.log(`Next Root ID: ${ps.nextRootId}`)
}
// Get only proof sets managed by this Pandora instance
const managedSets = await pandoraService.getManagedProofSets(clientAddress)
// Verify proof set creation
const verification = await pandoraService.verifyProofSetCreation(txHash)
if (verification.proofSetLive) {
console.log(`Proof set ${verification.proofSetId} is live!`)
}
// Storage provider operations
const isApproved = await pandoraService.isProviderApproved(providerAddress)
const providers = await pandoraService.getAllApprovedProviders()PDP Components
The PDP (Proof of Data Possession) system has three main components:
PDP Verifier
Low-level interface to the PDPVerifier contract for protocol operations.
import { PDPVerifier } from '@filoz/synapse-sdk/pdp'
const pdpVerifier = new PDPVerifier(provider)
// Check if proof set is live
const isLive = await pdpVerifier.proofSetLive(proofSetId)
// Get proof set details
const nextRootId = await pdpVerifier.getNextRootId(proofSetId)
const listener = await pdpVerifier.getProofSetListener(proofSetId)
const leafCount = await pdpVerifier.getProofSetLeafCount(proofSetId)
// Extract proof set ID from transaction receipt
const proofSetId = await pdpVerifier.extractProofSetIdFromReceipt(receipt)PDP Server
Consolidated interface for all PDP server (Curio) HTTP operations including proof sets, uploads, and downloads.
import { PDPServer, PDPAuthHelper } from '@filoz/synapse-sdk/pdp'
// Create server instance with auth helper
const authHelper = new PDPAuthHelper(pandoraAddress, signer, chainId)
const pdpServer = new PDPServer(authHelper, 'https://pdp.provider.com', 'https://pdp.provider.com')
// Create a proof set
const { txHash, statusUrl } = await pdpServer.createProofSet(
clientDataSetId, // number
payee, // string (storage provider address)
withCDN, // boolean
recordKeeper // string (Pandora contract address)
)
// Check creation status
const status = await pdpServer.getProofSetCreationStatus(txHash)
console.log(`Status: ${status.txStatus}, Proof Set ID: ${status.proofSetId}`)
// Add roots to proof set
await pdpServer.addRoots(
proofSetId, // number (PDPVerifier proof set ID)
clientDataSetId, // number
nextRootId, // number (must match chain state)
rootDataArray // Array of { cid: string | CommP, rawSize: number }
)
// Upload a piece
const { commP, size } = await pdpServer.uploadPiece(data, 'my-file.dat')
// Find existing piece
const piece = await pdpServer.findPiece(commP, size)
console.log(`Piece found: ${piece.uuid}`)
// Download a piece
const data = await pdpServer.downloadPiece(commP)
// Get proof set details
const proofSet = await pdpServer.getProofSet(proofSetId)PDP Auth Helper
Sign EIP-712 typed data for PDP operations. Compatible with MetaMask and other browser wallets.
import { PDPAuthHelper } from '@filoz/synapse-sdk/pdp'
// Create auth helper directly
const authHelper = new PDPAuthHelper(pandoraAddress, signer, chainId)
// Sign operations
const createProofSetSig = await authHelper.signCreateProofSet(
clientDataSetId, // number
payeeAddress, // string
withCDN // boolean
)
const addRootsSig = await authHelper.signAddRoots(
clientDataSetId, // number
firstRootId, // number
rootDataArray // Array of { cid: string | CommP, rawSize: number }
)
// All signatures return { signature, v, r, s, signedData }CommP Utilities
Calculate and validate Filecoin Piece Commitments without instantiating the full SDK.
import { calculate, asCommP, createCommPStream } from '@filoz/synapse-sdk/commp'
// Calculate CommP from data
const data = new Uint8Array([1, 2, 3, 4])
const commp = calculate(data)
console.log(commp.toString()) // baga6ea4seaq...
// Validate and convert CommP strings and CIDs
const commp = asCommP('baga6ea4seaqao7s73y24kcutaosvacpdjgfe5pw76ooefnyqw4ynr3d2y6x2mpq')
if (commp !== null) {
console.log('Valid CommP:', commp.toString())
}
// Stream-based CommP calculation; compatible with Web Streams API
const { stream, getCommP } = createCommPStream()
// Pipe data through stream, then call getCommP() for resultNetwork Configuration
RPC Endpoints
import { RPC_URLS } from '@filoz/synapse-sdk'
// Mainnet
RPC_URLS.mainnet.websocket // wss://wss.node.glif.io/apigw/lotus/rpc/v1
RPC_URLS.mainnet.http // https://api.node.glif.io/rpc/v1
// Calibration Testnet
RPC_URLS.calibration.websocket // wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1
RPC_URLS.calibration.http // https://api.calibration.node.glif.io/rpc/v1GLIF Authorization
For higher rate limits with GLIF endpoints:
import { Synapse } from '@filoz/synapse-sdk'
// Using GLIF authorization with private key
const synapse = await Synapse.create({
privateKey: '0x...',
rpcURL: 'https://api.node.glif.io/rpc/v1',
authorization: 'Bearer YOUR_GLIF_TOKEN'
})Network Details
Filecoin Mainnet
- Chain ID: 314
- USDFC Contract:
0x80B98d3aa09ffff255c3ba4A241111Ff1262F045
Filecoin Calibration Testnet
- Chain ID: 314159
- USDFC Contract:
0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0
Browser Integration
The SDK works seamlessly in browsers.
MetaMask Setup
Official documentation for configuring MetaMask with Filecoin (both Mainnet and the Calibration Test network) can be found at: https://docs.filecoin.io/basics/assets/metamask-setup
If you want to add the Filecoin network programmatically, you can use the following code snippet, for Mainnet (change accordingly for Calibration Testnet):
// Add Filecoin network to MetaMask
await window.ethereum.request({
method: 'wallet_addEthereumChain',
params: [{
chainId: '0x13A', // 314 for mainnet
chainName: 'Filecoin',
nativeCurrency: { name: 'FIL', symbol: 'FIL', decimals: 18 },
rpcUrls: ['https://api.node.glif.io/rpc/v1'],
blockExplorerUrls: ['https://filfox.info/en']
}]
})Additional Information
Type Definitions
The SDK is fully typed with TypeScript. Key types include:
CommP- Filecoin Piece Commitment CIDTokenAmount-number | bigintfor token amountsStorageOptions- Options for storage service creationAuthSignature- Signature data for authenticated operations
Error Handling
All SDK methods use descriptive error messages with proper error chaining:
try {
await synapse.payments.deposit(amount)
} catch (error) {
console.error(error.message) // Clear error description
console.error(error.cause) // Underlying error if any
}Contributing
Contributions are welcome! If using an AI tool, you are welcome to load AGENTS.md into your context to teach it about the structure and conventions of this SDK.
Testing
Run the test suite:
npm test # Run all tests and linting
npm run test:node # Node.js tests only
npm run test:browser # Browser tests onlyLicense
Apache-2.0