Filecoin Beam Docs

🚀 Getting Started with Filecoin Beam

Filecoin Beam is an incentivized retrieval layer for Filecoin Warm Storage Service deals. It speeds up data retrieval, reduces egress bills, and protects Filecoin Storage Providers from the internet.

You can create PDP deals on the Filecoin Calibration testnet in two ways:

1. Programmatically using the Synapse SDK

2. Manually using a demo web app (coming soon)

Remember to set up your wallet first!

💵 Set Up Your Wallet

Before you can interact with Filecoin Services to create PDP deals, you need to create a wallet, obtain a small amount of testnet Filecoin to pay for gas fees and enough USDFC tokens to pay for the storage & CDN deals.

1. Configure your wallet (e.g. Metamask) for Filecoin Calibration testnet (Calibration docs, Metamask setup instructions).

2. Get tFIL. You can use one of the following faucets:
   • Calibration Faucet - Chainsafe
   • Calibration Faucet - Zondax
   • Calibration Faucet - Forest Explorer

3. Get testnet USDFC tokens using one of the following ways:
   • Mint new USDFC tokens
   • Get USDFC tokens from the Chainsafe Faucet

Use Synapse SDK for JavaScript

The Synapse SDK offers an easy-to-use SDK to manage Filecoin Service deals, uploading content to Filecoin, and downloading it back.

You can learn more about Synapse SDK at https://synapse.filecoin.services. I

Initial Payment Setup

You need to set up payments before you can upload files to Filecoin PDP. Learn more in Synapse docs: Payment Setup.

Upload a File Using Synapse SDK

Please refer to Synapse docs: Quick Start.

⚠️ Important ⚠️

Synapse SDK does not enable FilBeam retrievals by default. You must set withCDN: true in Synapse or StorageContext initialization options.

const synapse = await Synapse.create({
  privateKey: PRIVATE_KEY,
  withCDN: true,
})
const uploadResult = await synapse.storage.upload(/* ... */)
const pieceCid = uploadResult.pieceCid
// we will need `pieceCid` later to retrieve the file

Retrieve a File Using Synapse SDK

We recommend using synapse.storage.download(pieceCid) API to retrieve content from Filecoin Beam. This API verifies that the retrieved content matches the requested CID.

const downloadedData = await synapse.storage.download(pieceCid)

Retrieve a File Directly

Alternatively, if you want to perform content verification yourself (or skip it), you can retrieve the content using Fetch API. To construct the FilBeam URL for retrieval, you need two pieces of information:

• Your wallet address (a hex-encoded string prefixed with 0x).

• The CID of the file (the PieceCID value starting with bafk).

Fill those values in the URL template below to get your unique URL for downloading the file.

https://{your-wallet-address}.calibration.filcdn.io/{CID}

Using Synapse SDK:

const clientAddress = await synapse.getSigner().getAddress()
const url = `https://${clientAddress}.calibration.filcdn.io/${pieceCid}`
const res = await fetch(url)
if (!res.ok) {
  throw new Error(`Cannot retrieve ${cid}: ${res.status}`)
}
const downloadedData = await res.arrayBuffer()
// TODO: verify that `downloadedData` hashes to the digest in `cid`

Example URL:

https://0xaf992fbc0c22bc941a232c63dc1b0c0cd572d145.calibration.filbeam.io/bafkzcibexduqqdwjwoj7yvgdolkxut7jopbjovjb4fdkktbyqetxalb2mxh43ddwee