synapse

README

synapse-go

Go SDK for Filecoin Onchain Cloud (FOC), ported from the @filoz/synapse-sdk.

Status: Beta - API may change.

Docs: getting started | API reference | examples

Install

go get github.com/strahe/synapse-go

Requires Go 1.25+.

Quick Start

client, err := synapse.New(ctx,
    synapse.WithPrivateKeyHex("0x..."),
    synapse.WithRPCURL("https://api.calibration.node.glif.io/rpc/v1"),
    synapse.WithSource("my-app"),
)
if err != nil { return err }
defer client.Close()

// file is an io.Reader over the payload to upload.
upload, err := client.Storage().Upload(ctx, file, &storage.UploadOptions{Copies: 2})
if err != nil { return err }

fmt.Println("piece:", upload.PieceCID)
fmt.Printf("copies: %d/%d\n", upload.SuccessCount(), upload.RequestedCopies)
fmt.Println("retrieve:", upload.Copies[0].RetrievalURL)

Use real values from your config or secret manager. Mainnet and Calibration are detected from the RPC chain ID.

Single uploads must be at least 127 bytes and fit the PDP cap, about 1 GiB.

Package Map

Package	Purpose
synapse	Root client that initializes chain config, contract addresses, and services
storage	Multi-provider upload/download orchestration, dataset discovery, and prepare flows
payments	USDFC balances, deposits, withdrawals, approvals, and Filecoin Pay rails
costs	Storage pricing, lockup, runway, and funding cost calculations
warmstorage	FWSS datasets, pricing, approved-provider discovery, and termination
spregistry	Storage provider registry discovery and provider/product management
sessionkey	Delegated session key authorization for FWSS EIP-712 operations
chain	Filecoin chain IDs, contract addresses, epochs, and token units
signer	Secp256k1 and BLS signing abstractions
piece	PieceCID v1/v2 calculation, parsing, and validation
filbeam	FilBeam egress quota, usage stats, and CDN retrieval for FWSS datasets
pdp	Low-level Curio-compatible PDP provider HTTP client

Testing

CI covers build, vet, lint, tests, and govulncheck.

Integration tests require INTEGRATION_PRIVATE_KEY in .env (needs tFIL for gas + 5 USDFC).

INTEGRATION_RPC_URL is optional.

Approximate local runtimes on Calibration:

make test                      # seconds; normal development loop
make test-integration-readonly # 30-60s; read-only Calibration checks
make test-integration-fast     # 5-10m; upload/download smoke with cleanup
make test-integration-cross    # 15-20m; full cross-package flow
make test-integration          # ~30m; final validation before merge

Development

make check   # build + vet + lint + test

License

Apache-2.0

Documentation

Overview

Package synapse provides the root Client for the Filecoin Onchain Cloud (FOC) Go SDK.

Create a client with New, passing a private key and an RPC endpoint (or an existing ethclient.Client). The client auto-detects the chain, resolves contract addresses, and eagerly initialises all sub-services before returning.

client, err := synapse.New(ctx,
    synapse.WithPrivateKeyHex("0x..."),
    synapse.WithRPCURL("https://api.calibration.node.glif.io/rpc/v1"),
    synapse.WithSource("my-app"),
)
if err != nil {
    // handle error
}
defer client.Close()

// data must contain uploadable content; PieceCIDv2 requires at least
// 127 raw bytes.
result, err := client.Storage().Upload(ctx, data, nil)

Sub-services are accessed via getters: Client.Storage, Client.Payments, Client.WarmStorage, Client.SPRegistry, Client.Costs, Client.FilBeam, and Client.SessionKey. Each getter returns the service instance created by New.

Lower-level packages (chain, signer, piece, storage, payments, etc.) can still be used independently without the root client.

Stability

This SDK is in its 0.x phase. Public APIs may change between minor releases; breaking changes are called out in release notes. Pin to a specific minor version in production. The implementation tracks the Filecoin Onchain Cloud protocol and the upstream TypeScript SDK.

Example

Example shows the minimal setup for creating a synapse.Client connected to an RPC endpoint with a signing key.

package main

import (
	"context"
	"fmt"
	"log"

	synapse "github.com/strahe/synapse-go"
)

func main() {
	ctx := context.Background()

	client, err := synapse.New(ctx,
		synapse.WithRPCURL("https://api.calibration.node.glif.io/rpc/v1"),
		synapse.WithPrivateKeyHex("0x..."),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	fmt.Println(client.Address())
}

Index

• Variables
• type Client
  • func New(ctx context.Context, opts ...ClientOption) (*Client, error)
  • func (c *Client) Address() common.Address
  • func (c *Client) Chain() chain.Chain
  • func (c *Client) Close() error
  • func (c *Client) Costs() *costs.Service
  • func (c *Client) FilBeam() *filbeam.Service
  • func (c *Client) GetProviderInfoByAddress(ctx context.Context, addr common.Address) (*spregistry.ProviderInfo, error)
  • func (c *Client) GetProviderInfoByID(ctx context.Context, id types.BigInt) (*spregistry.ProviderInfo, error)
  • func (c *Client) Payments() *payments.Service
  • func (c *Client) SPRegistry() *spregistry.Service
  • func (c *Client) SessionKey() *sessionkey.Service
  • func (c *Client) Storage() *storage.Service
  • func (c *Client) WarmStorage() *warmstorage.Service
• type ClientOption
  • func WithAllowPrivateNetworks(allow bool) ClientOption
  • func WithCDN(enabled bool) ClientOption
  • func WithChain(c chain.Chain) ClientOption
  • func WithEthClient(c *ethclient.Client) ClientOption
  • func WithFilBeamRetrievalDomain(domain string) ClientOption
  • func WithHTTPClient(c *http.Client) ClientOption
  • func WithLogger(l *slog.Logger) ClientOption
  • func WithPrivateKey(key *ecdsa.PrivateKey) ClientOption
  • func WithPrivateKeyHex(hex string) ClientOption
  • func WithRPCURL(url string) ClientOption
  • func WithSource(s string) ClientOption

Examples

• Package

Variables

var ErrClosed = lifecycle.ErrClosed

ErrClosed is returned by service methods invoked after the owning Client has been closed via Client.Close. It is an alias of the shared closed-client sentinel and matches the per-package ErrClosed sentinels (for example, payments.ErrClosed) re-exported by every sub-service.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the root entry point for the Filecoin Onchain Cloud SDK. It composes all sub-services, all of which are initialised eagerly by New. Create with New; release resources with Client.Close.

All methods are safe for concurrent use.

func New

func New(ctx context.Context, opts ...ClientOption) (*Client, error)

New creates a Client, connecting to the given RPC endpoint and resolving the chain and contract addresses.

Required options: a private key (WithPrivateKey or WithPrivateKeyHex) and an RPC source (WithRPCURL or WithEthClient).

func (*Client) Address

func (c *Client) Address() common.Address

Address returns the EVM address derived from the private key.

func (*Client) Chain

func (c *Client) Chain() chain.Chain

Chain returns the resolved chain.Chain.

func (*Client) Close

func (c *Client) Close() error

Close releases resources held by the Client. If the ethclient was created internally (via WithRPCURL), it is closed. User-provided clients (via WithEthClient) are left open. Safe to call concurrently or multiple times.

After Close returns, the Client and all services obtained from it must not be used.

func (*Client) Costs

func (c *Client) Costs() *costs.Service

Costs returns the costs.Service.

func (*Client) FilBeam

func (c *Client) FilBeam() *filbeam.Service

FilBeam returns the filbeam.Service.

func (*Client) GetProviderInfoByAddress

func (c *Client) GetProviderInfoByAddress(ctx context.Context, addr common.Address) (*spregistry.ProviderInfo, error)

GetProviderInfoByAddress looks up a storage provider on Client.SPRegistry by its service-provider common.Address.

func (*Client) GetProviderInfoByID

func (c *Client) GetProviderInfoByID(ctx context.Context, id types.BigInt) (*spregistry.ProviderInfo, error)

GetProviderInfoByID looks up a storage provider on Client.SPRegistry by its numeric types.BigInt id.

func (*Client) Payments

func (c *Client) Payments() *payments.Service

Payments returns the payments.Service.

func (*Client) SPRegistry

func (c *Client) SPRegistry() *spregistry.Service

SPRegistry returns the spregistry.Service.

func (*Client) SessionKey

func (c *Client) SessionKey() *sessionkey.Service

SessionKey returns the sessionkey.Service.

func (*Client) Storage

func (c *Client) Storage() *storage.Service

Storage returns the storage.Service.

The service is wired with a storage.ServiceResolver that uses Client.WarmStorage and Client.SPRegistry. A per-provider PDP client is created inside the storage.ContextFactory closure on each upload.

func (*Client) WarmStorage

func (c *Client) WarmStorage() *warmstorage.Service

WarmStorage returns the warmstorage.Service.

type ClientOption

type ClientOption func(*clientConfig)

ClientOption configures a Client via New.

func WithAllowPrivateNetworks

func WithAllowPrivateNetworks(allow bool) ClientOption

WithAllowPrivateNetworks disables the built-in SSRF guard for URL-based storage.Service.Download calls. When false (the default), the storage service refuses to dial loopback, RFC1918, link-local, ULA, multicast, and unspecified addresses, returning storage.ErrPrivateNetwork.

Set to true only when you knowingly need to fetch content from a private network (e.g. in-cluster storage nodes). This is an explicit SSRF opt-in for trusted private infrastructure; do not enable it for untrusted user-supplied URLs.

This option has no effect when WithHTTPClient is also provided: the custom client's transport is responsible for any SSRF safeguards.

func WithCDN

func WithCDN(enabled bool) ClientOption

WithCDN sets the Client-wide default for CDN-first context downloads and the withCDN dataset-metadata flag used during provider selection.

This is a default only: each storage.UploadOptions and storage.CreateContextsOptions carries its own *bool WithCDN that overrides the Client default when non-nil. Leaving the per-op field nil inherits this Client default.

Example — override per upload:

b := false
_, err := client.Storage().Upload(ctx, r, &storage.UploadOptions{WithCDN: &b})

func WithChain

func WithChain(c chain.Chain) ClientOption

WithChain overrides automatic chain detection. When omitted, New calls eth_chainId on the RPC endpoint.

func WithEthClient

func WithEthClient(c *ethclient.Client) ClientOption

WithEthClient provides a pre-created ethclient.Client. When set, WithRPCURL is ignored and the client is NOT closed by Client.Close.

func WithFilBeamRetrievalDomain

func WithFilBeamRetrievalDomain(domain string) ClientOption

WithFilBeamRetrievalDomain overrides the chain default FilBeam retrieval domain. Leave unset for the built-in Mainnet / Calibration defaults.

func WithHTTPClient

func WithHTTPClient(c *http.Client) ClientOption

WithHTTPClient sets the HTTP client used by every service that makes HTTP calls:

• filbeam.Service (stats API)
• storage.Service (URL-based downloads via Service.HTTPClient)
• provider HTTP clients constructed by the storage resolver for upload, pull, and provider RPC calls

Services communicating over Ethereum JSON-RPC (payments, sessionkey, warmstorage, spregistry, costs) reuse the chain client instead and are not affected by this option. If nil, each HTTP service uses its own default.

func WithLogger

func WithLogger(l *slog.Logger) ClientOption

WithLogger sets the structured logger passed to sub-services. Nil disables logging (the default).

func WithPrivateKey

func WithPrivateKey(key *ecdsa.PrivateKey) ClientOption

WithPrivateKey sets the ECDSA private key used for transaction signing. If both WithPrivateKey and WithPrivateKeyHex are provided, WithPrivateKey takes precedence.

func WithPrivateKeyHex

func WithPrivateKeyHex(hex string) ClientOption

WithPrivateKeyHex sets the private key from a hex-encoded string. Both "0x"-prefixed and raw hex are accepted. Ignored when WithPrivateKey is also provided.

func WithRPCURL

func WithRPCURL(url string) ClientOption

WithRPCURL sets the JSON-RPC endpoint URL. An ethclient is dialed during New and closed by Client.Close.

func WithSource

func WithSource(s string) ClientOption

WithSource sets the application-level source identifier used for dataset namespace isolation. Datasets with different source values are treated as distinct namespaces; reuse only occurs within the same source.