synapse

package module

v0.4.2 Latest Latest Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 30 Imported by: 1

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/strahe/synapse-go

Links

Open Source Insights

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.26.3+.

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. Client.ResolvedAddresses returns the address snapshot used by those services. Read-only callers can use ResolveAddresses directly without a private key.

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())
}

Output:

Index ¶

Variables
type Client
- func New(ctx context.Context, opts ...ClientOption) (*Client, error)
type ClientOption
type ContractCaller
type ResolvedAddresses
- func ResolveAddresses(ctx context.Context, caller ContractCaller, fwss common.Address) (ResolvedAddresses, error)

Examples ¶

Package

Constants ¶

This section is empty.

Variables ¶

View Source

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.

View Source

var ErrInvalidArgument = errors.New("synapse: invalid argument")

ErrInvalidArgument is returned when a public root-package function receives a nil, zero, or otherwise invalid caller-supplied argument.

Functions ¶

This section is empty.

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). If no RPC source is provided, the client uses the selected chain's default RPC endpoint, defaulting to Calibration when no chain is selected.

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) ResolvedAddresses ¶ added in v0.4.0

func (c *Client) ResolvedAddresses() ResolvedAddresses

ResolvedAddresses returns the contract-address snapshot used to initialise the Client and its services.

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 whenever a managed storage context is resolved.

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 local, private, multicast, unspecified, or otherwise reserved address ranges, 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 selects the Filecoin network. When omitted, New detects the chain from the RPC endpoint, except when both chain and RPC source are omitted; that path defaults to Calibration.

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 ¶ added in v0.2.0

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 and CDN downloads)
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, storage.Service URL downloads use the built-in safe HTTP client, filbeam.Service uses http.DefaultClient, and provider PDP clients use the pdp package default client. The filbeam and PDP defaults do not install SSRF guards.

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.

type ContractCaller ¶ added in v0.4.0

type ContractCaller interface {
	CallContract(ctx context.Context, call ethereum.CallMsg, blockNumber *big.Int) ([]byte, error)
}

ContractCaller is the RPC surface required to resolve contract addresses.

type ResolvedAddresses ¶ added in v0.4.0

type ResolvedAddresses struct {
	FWSS               common.Address
	PDPVerifier        common.Address
	SPRegistry         common.Address
	USDFC              common.Address
	Payments           common.Address
	ViewContract       common.Address
	FilBeamBeneficiary common.Address
	SessionKeyRegistry common.Address
}

ResolvedAddresses is the contract topology read from FWSS. FWSS is the bootstrap address supplied to ResolveAddresses. PDPVerifier and FilBeamBeneficiary may be zero when those optional services are not configured.

func ResolveAddresses ¶ added in v0.4.0

func ResolveAddresses(ctx context.Context, caller ContractCaller, fwss common.Address) (ResolvedAddresses, error)

ResolveAddresses reads the current contract topology from FWSS. It uses the SDK's Multicall3 deployment for supported Filecoin networks and does not fall back to compiled child-contract addresses.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
chain Package chain defines chain identifiers, contract addresses, and epoch utilities for supported Filecoin networks (Mainnet and Calibration).	Package chain defines chain identifiers, contract addresses, and epoch utilities for supported Filecoin networks (Mainnet and Calibration).
costs Package costs provides cost calculation for storage operations.	Package costs provides cost calculation for storage operations.
examples
download-piece command Download-piece downloads a retrieval URL and verifies it against a PieceCID.	Download-piece downloads a retrieval URL and verifies it against a PieceCID.
internal/exampleutil
list-datasets command List-datasets shows the storage state for the current wallet.	List-datasets shows the storage state for the current wallet.
list-providers command List-providers shows active PDP storage providers and their capabilities.	List-providers shows active PDP storage providers and their capabilities.
piece-info command Piece-info calculates Filecoin PieceCID information for a local file.	Piece-info calculates Filecoin PieceCID information for a local file.
quickstart command Quickstart runs the shortest complete FOC flow on Calibration: prepare funds when needed, upload data, download the first copy, and verify the bytes match.	Quickstart runs the shortest complete FOC flow on Calibration: prepare funds when needed, upload data, download the first copy, and verify the bytes match.
upload-file command Upload-file uploads a local file to FOC storage.	Upload-file uploads a local file to FOC storage.
filbeam Package filbeam provides a client for FilBeam stats and retrieval APIs.	Package filbeam provides a client for FilBeam stats and retrieval APIs.
internal
abi Package abi provides helpers for working with contract ABIs beyond what generated bindings offer: address auto-discovery via the FWSS root of trust, generic event extraction from receipts, and PieceCID <-> contract struct conversions.	Package abi provides helpers for working with contract ABIs beyond what generated bindings offer: address auto-discovery via the FWSS root of trust, generic event extraction from receipts, and PieceCID <-> contract struct conversions.
adapters Package adapters contains the private glue that composes the per-service packages (warmstorage, spregistry, payments, costs, internal/contracts/ pdpverifier) into the narrow interfaces consumed by the storage package.	Package adapters contains the private glue that composes the per-service packages (warmstorage, spregistry, payments, costs, internal/contracts/ pdpverifier) into the narrow interfaces consumed by the storage package.
contracts Package contracts contains go:generate directives for regenerating smart contract bindings from ABI JSON files using abigen.	Package contracts contains go:generate directives for regenerating smart contract bindings from ABI JSON files using abigen.
contracts/cmd/syncabi command Command syncabi fetches pinned contract ABIs from the upstream FilOzone/filecoin-services repository and regenerates Go bindings under internal/contracts/.	Command syncabi fetches pinned contract ABIs from the upstream FilOzone/filecoin-services repository and regenerates Go bindings under internal/contracts/.
contracts/erc20 Package erc20 contains the generated Go bindings for the standard ERC20 token interface, used for USDFC token operations.	Package erc20 contains the generated Go bindings for the standard ERC20 token interface, used for USDFC token operations.
contracts/filpay Package filpay contains the generated Go bindings for the Filecoin Pay smart contract.	Package filpay contains the generated Go bindings for the Filecoin Pay smart contract.
contracts/fwss Package fwss contains the generated Go bindings for the FWSS (Filecoin Warm Storage Service) smart contract.	Package fwss contains the generated Go bindings for the FWSS (Filecoin Warm Storage Service) smart contract.
contracts/fwssview Package fwssview contains the generated Go bindings for the FWSS StateView contract (read-only surface of FilecoinWarmStorageService).	Package fwssview contains the generated Go bindings for the FWSS StateView contract (read-only surface of FilecoinWarmStorageService).
contracts/pdpverifier Package pdpverifier contains generated Go bindings and internal error helpers for the PDPVerifier smart contract.	Package pdpverifier contains generated Go bindings and internal error helpers for the PDPVerifier smart contract.
contracts/sessionkeyregistry Package sessionkeyregistry contains the generated Go bindings for the SessionKeyRegistry smart contract.	Package sessionkeyregistry contains the generated Go bindings for the SessionKeyRegistry smart contract.
contracts/spregistry Package spregistry contains the generated Go bindings for the ServiceProviderRegistry smart contract.	Package spregistry contains the generated Go bindings for the ServiceProviderRegistry smart contract.
contracts/syncabi Package syncabi fetches pinned contract ABIs from the upstream FilOzone/filecoin-services repository and regenerates the Go bindings under internal/contracts/.	Package syncabi fetches pinned contract ABIs from the upstream FilOzone/filecoin-services repository and regenerates the Go bindings under internal/contracts/.
idconv Package idconv converts between SDK uint256 identifiers and generated contract binding *big.Int values.	Package idconv converts between SDK uint256 identifiers and generated contract binding *big.Int values.
integrationtest Package integrationtest provides small helpers shared by the SDK's integration tests (files built under `//go:build integration`).	Package integrationtest provides small helpers shared by the SDK's integration tests (files built under `//go:build integration`).
lifecycle Package lifecycle tracks whether a [synapse.Client] has been closed so that services derived from it can refuse new work with a clear error rather than making RPC calls on a closed ethclient.	Package lifecycle tracks whether a [synapse.Client] has been closed so that services derived from it can refuse new work with a clear error rather than making RPC calls on a closed ethclient.
retry Package retry provides exponential backoff retry logic for transient failures in RPC calls, HTTP requests, and transaction submissions.	Package retry provides exponential backoff retry logic for transient failures in RPC calls, HTTP requests, and transaction submissions.
testutil Package testutil provides internal test helpers, mock implementations, and fixture data for testing synapse-go packages.	Package testutil provides internal test helpers, mock implementations, and fixture data for testing synapse-go packages.
txutil Package txutil provides transaction lifecycle utilities for Ethereum/FEVM transactions.	Package txutil provides transaction lifecycle utilities for Ethereum/FEVM transactions.
typeddata Package typeddata implements EIP-712 typed data signing for storage provider authentication.	Package typeddata implements EIP-712 typed data signing for storage provider authentication.
upstream Package upstream records pinned upstream references.	Package upstream records pinned upstream references.
payments Package payments provides the payment management service for Filecoin Onchain Cloud.	Package payments provides the payment management service for Filecoin Onchain Cloud.
pdp Package pdp provides a Curio-compatible PDP provider HTTP client.	Package pdp provides a Curio-compatible PDP provider HTTP client.
piece Package piece provides PieceCID utilities for Filecoin content addressing.	Package piece provides PieceCID utilities for Filecoin content addressing.
sessionkey Package sessionkey provides SessionKeyRegistry authorization management on Filecoin EVM.	Package sessionkey provides SessionKeyRegistry authorization management on Filecoin EVM.
signer Package signer provides signing abstractions for Filecoin and Ethereum transactions.	Package signer provides signing abstractions for Filecoin and Ethereum transactions.
spregistry Package spregistry provides the Storage Provider Registry service.	Package spregistry provides the Storage Provider Registry service.
storage Package storage provides the multi-copy upload orchestration service.	Package storage provides the multi-copy upload orchestration service.
types Package types holds shared SDK domain types used across service packages.	Package types holds shared SDK domain types used across service packages.
warmstorage Package warmstorage provides the WarmStorage (FWSS) service for managing storage contracts, data sets, and pricing.	Package warmstorage provides the WarmStorage (FWSS) service for managing storage contracts, data sets, and pricing.