FilBeam

FilBeam Service

Client for the FilBeam stats API.

Disclaimer

FilBeam is not currently a priority for active support and development, use with caution. If you have a use case for FilBeam, please open an issue at https://github.com/filbeam/roadmap/issues describing it, so we can prioritize the work accordingly.

Overview

FilBeam enables retrieval incentives for Filecoin PDP (Proof of Data Possession) service providers by acting as a trusted intermediary that measures traffic between clients and storage providers.

Architecture

FilBeam operates as a caching layer between clients and storage providers, enabling efficient retrieval of content-addressable data stored on Filecoin PDP.

Client  <-->  FilBeam (cache + metering)  <-->  Storage Provider

Copy to clipboard

Billing Model

Both cache hits and cache misses generate billable egress events. This transforms Filecoin from passive archival storage into an active “serve many” data delivery infrastructure, where service providers are compensated for serving retrievals.

Examples

Basic Usage

import { mainnet } from '@filoz/synapse-core/chains'
import { FilBeamService } from '@filoz/synapse-sdk/filbeam'

// Create service for mainnet
const service = new FilBeamService(mainnet)

// Get remaining data set statistics
const stats = await service.getDataSetStats('dataset-id')
console.log('Remaining CDN Egress:', stats.cdnEgressQuota)
console.log('Remaining Cache Miss:', stats.cacheMissEgressQuota)

Copy to clipboard

Integration with Synapse SDK

import { Synapse } from '@filoz/synapse-sdk'
import { privateKeyToAccount } from 'viem/accounts'

// Initialize Synapse
const synapse = Synapse.create({
  account: privateKeyToAccount('0x...'),
  source: 'my-app',
})

// Access FilBeam service through Synapse
const stats = await synapse.filbeam.getDataSetStats('my-dataset')

// Monitor remaining quotas over time
setInterval(async () => {
  const currentStats = await synapse.filbeam.getDataSetStats('my-dataset')
  console.log('Remaining quotas:', currentStats)

  // Alert if running low
  const TiB = BigInt(1024 ** 4)
  const remainingTiB = Number((currentStats.cdnEgressQuota + currentStats.cacheMissEgressQuota) / TiB)
  if (remainingTiB < 1) {
    console.warn('Low quota warning: Less than 1 TiB remaining')
  }
}, 60000) // Check every minute

Copy to clipboard

See

• FilBeam Documentation - Official FilBeam documentation
• Pay Per Byte Blog Post - Introduction to the pay-per-byte pricing model
• DataSetStats for the structure of returned statistics
• FilBeamService for the main service class

Classes

Class	Description
FilBeamService	Service for interacting with FilBeam infrastructure and APIs.

Interfaces

Interface	Description
DataSetStats	Data set statistics from FilBeam.
GetDataSetStatsOptions	Options for FilBeamService.getDataSetStats.