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.

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. Supports multi-copy uploads via the StorageManager.

Get all pieces for a dataset from a StorageContext

Uses StorageContext.getPieces() async generator to retrieve all pieces. Optionally fetches metadata for each piece from WarmStorage.

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: ${formatUnits(status.filBalance, 18)}`)
console.log(`USDFC Balance: ${formatUnits(status.walletUsdfcBalance, 18)}`)
console.log(`Deposited: ${formatUnits(status.filecoinPayBalance, 18)}`)
Copy

Create a Synapse instance from CLI-friendly configuration.

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.

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