🚀 Getting Started with FilCDN

FilCDN is a blazing fast content delivery network (CDN) for Filecoin Proof of Data Possession (PDP) 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. Manually using a demo web app
2. Programmatically using the Synapse SDK

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 the Demo Web App

Open https://fs-upload-dapp.netlify.app and connect your wallet.

Note: You need a browser that can connect to your wallet (e.g. a Chromium-based browser with Metamask extension installed).

Initial Payment Setup

You need to set up payments before you can upload files to Filecoin PDP.

1. In the Manage Storage tab, click on “Deposit & Increase Allowances” to start the process of authorizing Filecoin Services to charge your wallet for storage deals.
2. This will open your wallet with a Spending cap request to approve. Change the Spending Cap value from “Unlimited” to an amount smaller than your USDFC balance and confirm the transaction.
3. After the blockchain confirms the first transaction, the app will deposit USDFC to pay for storing 10 GB for 30 days. Approve the Deposit transaction request in your wallet.
4. Finally, the app requires you to sign some metadata (more details about this request will follow soon). Approve the request in your wallet.

Upload a File

Once you have completed the initial setup, you can switch to the Upload File tab and drop some files into your browser to upload them to Filecoin!

1. If this is your first file upload, you will need to approve a CreateProofSet signature request. Filecoin PDP ProofSets are similar to Buckets you may know from Web2 storage offerings. In your wallet, check the transaction details - the WithCDN parameter must be set to true.
2. After a file is uploaded to the storage provider, it must be linked to your ProofSet. To establish the link, you need to approve an AddRoots signature request in your wallet.
3. After the blockchain confirms the transaction, your file is stored on Filecoin and ready for retrieval. Take a note of the CommP value shown in File Upload Details - that’s the CID you will use for downloads.

Retrieve a File

To retrieve your file using FilCDN, you need two pieces of information:

• Your wallet address (a hex-encoded string prefixed with 0x).
• The CID of the file (the CommP value starting with baga).

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}

Example URL:

https://0xde946319e3dba67b58bd771de01af8accafcda9d.calibration.filcdn.io/baga6ea4seaqlils6ulckqxstjmjtneo7hfa3qbvlkwsfnyroxcbrw3veq45luji

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.

See Synapse end-to-end example for a full solution.

Initial Payment Setup

You need to setup payments before you can upload files to Filecoin PDP.

We recommend to use the web app for this step, see FilCDN Docs - Initial Payment Setup.

Initialise Synapse and StorageService

import { Synapse } from '@filoz/synapse-sdk'
import { ethers } from 'ethers'

// Configuration from environment
const PRIVATE_KEY = process.env.PRIVATE_KEY
const RPC_URL = process.env.RPC_URL ||
   'https://api.calibration.node.glif.io/rpc/v1'

// Initialise the SDK
const synapse = await Synapse.create({
  withCDN: true,
  privateKey: PRIVATE_KEY,
  rpcURL: RPC_URL
})

// Create storage service
const storageService = await synapse.createStorage({
  callbacks: {
    onProviderSelected: (provider) => {
      console.log(`✓ Selected storage provider: ${provider.owner}`)
      console.log(`  PDP URL: ${provider.pdpUrl}`)
    },
    onProofSetResolved: (info) => {
      if (info.isExisting) {
        console.log(`✓ Using existing proof set: ${info.proofSetId}`)
      } else {
        console.log(`✓ Created new proof set: ${info.proofSetId}`)
      }
    },
    onProofSetCreationStarted: (transaction, statusUrl) => {
      console.log(`  Creating proof set, tx: ${transaction.hash}`)
    },
    onProofSetCreationProgress: (progress) => {
      if (progress.transactionMined && !progress.proofSetLive) {
        console.log('  Transaction mined, waiting for proof set to be live...')
      }
    },
  },
})

Upload a File

// Read the file into an in-memory buffer
const fileData = await readFile(filePath)

// Run preflight checks
const preflight = await storageService.preflightUpload(fileData.length)

if (!preflight.allowanceCheck.sufficient) {
  // The Filecoin Services deal is not sufficient
  // You need to increase the allowance, e.g. via the web app
  throw new Error('Allowance not sufficient.')
}

const uploadResult = await storageService.upload(fileData)
const cid = uploadResult.commp
// You will need `cid` to retrieve the file later

Retrieve a File

We recommend using synapse.download(cid) API to retrieve content from FilCDN. This API verifies that the retrieved content matches the requested CID.

const downloadedData = await synapse.download(cid)

Alternatively, if you want to perform content verification yourself (or skip it), you can retrieve the content using Fetch API.

const clientAddress = await synapse.getSigner().getAddress()
const url = `https://${clientAddress}.calibration.filcdn.io/${cid}`
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`