Skip to main content

​
Overview

The SPRegistryService provides access to the ServiceProviderRegistry contract for discovering providers, querying their offerings, and managing provider registrations. Access via synapse.providers.

​
Provider Queries

​
getProvider()

Get information about a specific provider by ID.
​
options
object
required
​
provider
PDPProvider | null
Provider information or null if not found:
  • id - Provider ID
  • serviceProvider - Provider address
  • name - Provider name
  • description - Provider description
  • pdp - PDP service offering details
  • capabilities - Provider capabilities
const provider = await synapse.providers.getProvider({ 
  providerId: 1n 
})

if (provider) {
  console.log('Name:', provider.name)
  console.log('PDP URL:', provider.pdp.serviceURL)
  console.log('Min size:', provider.pdp.minPieceSizeInBytes)
  console.log('Max size:', provider.pdp.maxPieceSizeInBytes)
}

​
getProviderByAddress()

Get provider information by their service address.
​
options
object
required
​
provider
PDPProvider | null
Provider information or null if not found
const provider = await synapse.providers.getProviderByAddress({
  address: '0x...'
})

​
getProviders()

Get multiple providers by their IDs.
​
options
object
required
​
providers
PDPProvider[]
Array of provider information (skips providers not found)
const providers = await synapse.providers.getProviders({
  providerIds: [1n, 2n, 3n]
})

providers.forEach(p => {
  console.log(`Provider ${p.id}: ${p.name}`)
})

​
getAllActiveProviders()

Get all currently active providers.
​
providers
PDPProvider[]
Array of all active providers
const allProviders = await synapse.providers.getAllActiveProviders()

console.log('Total providers:', allProviders.length)

allProviders.forEach(p => {
  console.log(`${p.name} (ID: ${p.id})`) 
  console.log(`  URL: ${p.pdp.serviceURL}`)
  console.log(`  Capacity: ${p.pdp.minPieceSizeInBytes} - ${p.pdp.maxPieceSizeInBytes} bytes`)
})

​
Provider Registration

Provider Registration is for Storage ProvidersThese methods are only needed if you’re operating a storage provider service. Regular users uploading data don’t need to register.

​
registerProvider()

Register as a new service provider.
​
options
ProviderRegistrationInfo
required
Provider registration information
​
txHash
Hash
Transaction hash of the registration
import { SIZE_CONSTANTS } from '@filoz/synapse-sdk/utils'

const txHash = await synapse.providers.registerProvider({
  payee: '0x...', // Payment recipient address
  name: 'My Storage Provider',
  description: 'High-performance Filecoin storage with 99.9% uptime',
  pdpOffering: {
    serviceURL: 'https://pdp.myprovider.com',
    minPieceSizeInBytes: SIZE_CONSTANTS.KiB,
    maxPieceSizeInBytes: SIZE_CONSTANTS.GiB * 32n,
  },
  capabilities: {
    region: 'us-east-1',
    tier: 'premium',
    maxBandwidth: '10Gbps'
  }
})

console.log('Registration tx:', txHash)

​
updateProviderInfo()

Update provider name and description.
​
options
object
required
​
txHash
Hash
Transaction hash
const txHash = await synapse.providers.updateProviderInfo({
  name: 'My Updated Provider Name',
  description: 'Updated service description with new features'
})

​
removeProvider()

Remove provider registration.
​
txHash
Hash
Transaction hash
const txHash = await synapse.providers.removeProvider()
console.log('Provider removed:', txHash)

​
Product Management

​
addProduct()

Add a new product offering to your provider.
​
options
object
required
​
txHash
Hash
Transaction hash
const txHash = await synapse.providers.addProduct({
  productType: 'PDP',
  productData: {
    serviceURL: 'https://pdp2.myprovider.com',
    minPieceSizeInBytes: SIZE_CONSTANTS.KiB,
    maxPieceSizeInBytes: SIZE_CONSTANTS.GiB * 64n,
  }
})

​
updateProduct()

Update an existing product offering.
​
options
object
required
​
txHash
Hash
Transaction hash
const txHash = await synapse.providers.updateProduct({
  productIndex: 0,
  productType: 'PDP',
  productData: {
    serviceURL: 'https://pdp-updated.myprovider.com',
    minPieceSizeInBytes: SIZE_CONSTANTS.KiB * 4n,
    maxPieceSizeInBytes: SIZE_CONSTANTS.GiB * 128n,
  }
})

​
removeProduct()

Remove a product offering.
​
options
object
required
​
txHash
Hash
Transaction hash
const txHash = await synapse.providers.removeProduct({
  productIndex: 0
})

​
Complete Example: User Finding Providers

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

const synapse = Synapse.create({ account, chain })

// Get all available providers
const providers = await synapse.providers.getAllActiveProviders()

console.log(`Found ${providers.length} active providers`)

// Filter by capabilities
const regionalProviders = providers.filter(p => {
  const region = p.capabilities?.region
  return region === 'us-east-1' || region === 'us-west-2'
})

console.log(`${regionalProviders.length} providers in US regions`)

// Check provider details
for (const provider of regionalProviders) {
  console.log(`\n${provider.name} (ID: ${provider.id})`)
  console.log(`  Description: ${provider.description}`)
  console.log(`  Service URL: ${provider.pdp.serviceURL}`)
  console.log(`  Min/Max size: ${provider.pdp.minPieceSizeInBytes} - ${provider.pdp.maxPieceSizeInBytes} bytes`)
  
  if (provider.capabilities) {
    console.log('  Capabilities:')
    Object.entries(provider.capabilities).forEach(([key, value]) => {
      console.log(`    ${key}: ${value}`)
    })
  }
}

// Get specific provider info
const provider = await synapse.providers.getProvider({ 
  providerId: 1n 
})

if (provider) {
  // Use this provider for storage
  const context = await synapse.storage.createContext({
    providerId: provider.id
  })
  
  const result = await context.upload(data)
  console.log('Uploaded to:', provider.name)
}

​
Complete Example: Provider Registration

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

const account = privateKeyToAccount(process.env.PROVIDER_PRIVATE_KEY)
const synapse = Synapse.create({ account, chain })

// Register as a storage provider
const registrationTx = await synapse.providers.registerProvider({
  payee: account.address, // Where payments go
  name: 'Acme Storage Provider',
  description: 'Enterprise-grade Filecoin storage with SLA guarantees',
  pdpOffering: {
    serviceURL: 'https://pdp.acmestorage.com',
    minPieceSizeInBytes: SIZE_CONSTANTS.KiB * 4n,      // 4 KiB min
    maxPieceSizeInBytes: SIZE_CONSTANTS.GiB * 32n,     // 32 GiB max
  },
  capabilities: {
    region: 'us-east-1',
    tier: 'enterprise',
    uptime: '99.99%',
    bandwidth: '10Gbps',
    storage: '5PB'
  }
})

console.log('Registered! Tx:', registrationTx)

// Find your provider ID from the transaction logs
// (Implementation would parse the ProviderRegistered event)

// Later, update your info
const updateTx = await synapse.providers.updateProviderInfo({
  name: 'Acme Storage Provider (Enhanced)',
  description: 'Enterprise-grade storage with new CDN integration'
})

console.log('Info updated:', updateTx)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us