Interface FilecoinPinAPI

Check readiness for uploading a CAR file.

This performs the same validation chain previously used by the CLI/action:

1. Ensure basic wallet requirements (FIL for gas, USDFC balance)
2. Confirm or configure WarmStorage allowances
3. Validate that the current deposit can cover the upload

The function only mutates state when autoConfigureAllowances is enabled (default), in which case it will call setMaxAllowances as needed.

Session Key Authentication: When using session key authentication, autoConfigureAllowances is automatically disabled since payment operations require the owner wallet to sign. Allowances must be configured separately by the owner wallet before uploads can proceed.

Clean up WebSocket providers and other resources

Call this when CLI commands are finishing to ensure proper cleanup and allow the process to terminate

Create a CAR file from a File using UnixFS encoding

Create a CAR file from multiple Files using UnixFS encoding

Create a CAR file from a file or directory using UnixFS encoding

Execute the upload to Synapse, returning the same structured data used by the CLI and GitHub Action.

Get all pieces for a dataset from a StorageContext

This function uses the StorageContext.getPieces() async generator to retrieve all pieces in a dataset. Optionally fetches metadata for each piece from WarmStorage.

Example usage:

const result = await getDataSetPieces(storageContext, {
  includeMetadata: true,
  batchSize: 100
})

console.log(`Found ${result.pieces.length} pieces`)
for (const piece of result.pieces) {
  console.log(`  ${piece.pieceCid}`)
  if (piece.rootIpfsCid) {
    console.log(`    IPFS: ${piece.rootIpfsCid}`)
  }
}
Copy

Get current payment status including all balances and approvals

Example usage:

const status = await getPaymentStatus(synapse)
console.log(`Address: ${status.address}`)
console.log(`FIL Balance: ${ethers.formatEther(status.filBalance)}`)
console.log(`USDFC Balance: ${ethers.formatUnits(status.walletUsdfcBalance, 18)}`)
console.log(`Deposited: ${ethers.formatUnits(status.filecoinPayBalance, 18)}`)
Copy

List all datasets for an address with optional provider enrichment

Example usage:

const synapse = await Synapse.create({ privateKey, rpcURL })
const datasets = await listDataSets(synapse)

for (const ds of datasets) {
  console.log(`Dataset ${ds.dataSetId}: ${ds.currentPieceCount} pieces`)
  if (ds.provider) {
    console.log(`  Provider: ${ds.provider.name}`)
  }
}
Copy

Set WarmStorage allowances to maximum

This function sets the allowances for WarmStorage to maximum values, effectively treating it as a fully trusted service.

Set up complete Synapse service with SDK and storage context

This function demonstrates the complete setup flow for Synapse:

1. Validates required configuration (private key)
2. Creates Synapse instance with network configuration
3. Creates a storage context with comprehensive callbacks
4. Returns a service object for application use

Our wrapping of Synapse initialization and storage context creation is primarily to handle our custom configuration needs and add detailed logging and progress tracking.

Validate payment capacity for a specific piece size

This function checks if the deposit is sufficient for the piece upload. It does not account for allowances since WarmStorage is assumed to be given full trust with max allowances.

Note: This function will attempt to automatically set max allowances unless using session key authentication, in which case allowances must be configured separately by the owner wallet.

Example usage:

const fileSize = 10 * 1024 * 1024 * 1024 // 10 GiB
const capacity = await validatePaymentCapacity(synapse, fileSize)

if (!capacity.canUpload) {
  console.error('Cannot upload file with current payment setup')
  capacity.suggestions.forEach(s => console.log(`  - ${s}`))
}
Copy