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

Files are encoded without a parent-directory wrapper (IPIP-499 conformance). The basename is exposed via CreateCarResult so callers can route it into piece metadata.

Multi-file uploads without a webkitRelativePath have no meaningful basename, so name is returned as null and no name piece metadata is attached (see withDerivedNameMetadata).

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.

Fetches on-chain pieces via PDPVerifier and provider-side pieces from the service URL, reconciles statuses, and optionally enriches with metadata.

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

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`)
}
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