Skip to main content

​
Overview

FilBeam provides a pay-per-byte CDN layer on top of Filecoin storage, offering:
  • Fast data retrieval through global CDN nodes
  • Cache-based delivery for frequently accessed content
  • Usage-based billing (only pay for data egress)
  • Trusted measurement layer for accurate billing

​
How It Works

FilBeam charges are usage-based:
  • CDN Egress: Data served from cache (fast)
  • Cache Miss Egress: Data retrieved from providers (triggers caching)

​
Enable CDN

1
Upload with CDN
2
import { Synapse } from '@filoz/synapse-sdk'

const synapse = await Synapse.create({ privateKey, rpcUrl })

// Enable CDN during upload
const result = await synapse.storage.upload(data, {
  withCDN: true,
})

console.log(`Uploaded with CDN enabled: ${result.pieceCid}`)
3
Download with CDN
4
// Download uses CDN automatically if enabled during upload
const data = await synapse.storage.download({ 
  pieceCid: result.pieceCid 
})

// Force CDN usage
const data = await synapse.storage.download({
  pieceCid: result.pieceCid,
  withCDN: true,
})
5
Create Context with CDN
6
const context = await synapse.storage.createContext({
  withCDN: true,
})

const result = await context.upload(data)

​
Monitor Usage

​
Check Data Set Quotas

const stats = await synapse.filbeam.getDataSetStats('12345')

console.log('Remaining quotas:')
console.log(`  CDN Egress: ${stats.cdnEgressQuota} bytes`)
console.log(`  Cache Miss: ${stats.cacheMissEgressQuota} bytes`)

​
Calculate Remaining Bandwidth

function formatBytes(bytes) {
  const gb = Number(bytes) / (1024 ** 3)
  return `${gb.toFixed(2)} GB`
}

const stats = await synapse.filbeam.getDataSetStats('12345')

console.log('Available bandwidth:')
console.log(`  Fast (cached): ${formatBytes(stats.cdnEgressQuota)}`)
console.log(`  Slow (uncached): ${formatBytes(stats.cacheMissEgressQuota)}`)

​
Pricing

​
Get CDN Pricing

const info = await synapse.storage.getStorageInfo()

console.log('Storage pricing:')
console.log(`  Base storage: ${info.pricing.noCDN.perTiBPerMonth}`)
console.log(`  Token: ${info.pricing.tokenSymbol}`)

// Note: CDN costs are usage-based (egress charges)
// Base storage price is the same with or without CDN

​
CDN Cost Structure

CDN pricing has two components:
  • Base Storage: Same as non-CDN (monthly rate per TiB)
  • Egress Charges: Pay per byte retrieved
    • CDN Egress: Data served from cache (cache hits)
    • Cache Miss Egress: Data pulled from providers (cache misses)

​
Preflight with CDN

Estimate costs including CDN: 
const preflight = await synapse.storage.preflightUpload({ 
  size: 1024 * 1024 * 100, // 100 MB
  withCDN: true,
})

console.log('Estimated base storage costs:')
console.log(`  Per epoch: ${preflight.estimatedCost.perEpoch}`)
console.log(`  Per day: ${preflight.estimatedCost.perDay}`)
console.log(`  Per month: ${preflight.estimatedCost.perMonth}`)

console.log('\nNote: Egress charges are usage-based')

​
Metadata Integration

CDN status is stored in metadata: 
// CDN is indicated by metadata key
const result = await synapse.storage.upload(data, {
  withCDN: true,
  metadata: {
    category: 'videos',
    // 'withCDN' key is added automatically
  },
})

​
FilBeam Service

Direct FilBeam service access: 
import { FilBeamService } from '@filoz/synapse-sdk'
import { calibration } from '@filoz/synapse-core/chains'

// Create service
const filbeam = new FilBeamService(calibration)

// Get stats
const stats = await filbeam.getDataSetStats('12345')

// Stats are BigInt for precision
console.log(typeof stats.cdnEgressQuota) // 'bigint'

​
CDN URLs

Retrieve data via FilBeam URLs: 
import * as Piece from '@filoz/synapse-core/piece'

// Create FilBeam URL
const url = Piece.createFilBeamUrl({
  cid: pieceCid.toString(),
  chain: 'calibration',
})

console.log(`FilBeam URL: ${url}`)
// https://calibration.filbeam.com/piece/{pieceCid}

​
Network-Specific Endpoints

import { mainnet, calibration } from '@filoz/synapse-core/chains'

// Mainnet FilBeam
const mainnetService = new FilBeamService(mainnet)
const mainnetStats = await mainnetService.getDataSetStats('12345')
// Uses: https://stats.filbeam.com

// Calibration testnet
const testnetService = new FilBeamService(calibration)
const testnetStats = await testnetService.getDataSetStats('12345')
// Uses: https://calibration.stats.filbeam.com

​
Error Handling

try {
  const stats = await synapse.filbeam.getDataSetStats('12345')
} catch (error) {
  if (error.message.includes('Data set not found')) {
    console.error('Data set does not exist')
  } else if (error.message.includes('HTTP 404')) {
    console.error('Data set not available on FilBeam')
  } else {
    console.error('FilBeam error:', error.message)
  }
}

​
Use Cases

Video Streaming

Serve videos with low latency to global audiences

Large Files

Fast downloads for frequently accessed files

Public Content

Distribute public datasets efficiently

Hot Storage

Cache frequently accessed data for performance

​
Best Practices

1
Choose CDN for Hot Data
2
Enable CDN for frequently accessed content:
3
// Public content that's accessed often
const result = await synapse.storage.upload(publicVideo, {
  withCDN: true,
  pieceMetadata: {
    category: 'public-content',
    access: 'frequent',
  },
})
4
Monitor Quotas
5
Regularly check remaining quotas:
6
setInterval(async () => {
  const stats = await synapse.filbeam.getDataSetStats('12345')
  
  if (stats.cdnEgressQuota < 1_000_000_000n) {
    console.warn('Low CDN quota remaining')
    // Add more credits or notify admin
  }
}, 3600000) // Check hourly
7
Cost Optimization
8
Use CDN selectively:
9
// Hot data: use CDN
await synapse.storage.upload(hotData, { withCDN: true })

// Cold data: skip CDN
await synapse.storage.upload(archiveData, { withCDN: false })

​
Limitations

  • CDN availability depends on data set configuration
  • First request may have cache-miss latency
  • Quotas must be monitored and replenished
  • Not available on devnet/local networks

​
Next Steps

Storage Operations

Learn about upload and download operations

Payment Management

Manage payments for CDN usage

Build docs developers (and LLMs) love

Get started for freeTalk to us