warmstorage

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package warmstorage provides the WarmStorage (FWSS) service for managing storage contracts, data sets, and service pricing.

FWSS (Filecoin Warm Storage Service) is the canonical storage contract. The root synapse Client supplies the chain's known FWSS, StateView, and PDPVerifier addresses when constructing this service. Low-level callers that instantiate Service directly must provide those addresses explicitly.

Key operations: data set management (including Service.TerminateDataSet for FWSS-initiated teardown), service price queries, approval management, and provider allocation.

The root synapse Client wires WarmStorage together with the other write-capable services so transaction nonce allocation is coordinated for a shared signer. Standalone services create their own nonce coordinator when constructed with write dependencies.

Errors are returned as wrapped sentinels. Use errors.Is to check:

  • ErrNotFound: returned when a queried record (e.g. data set) does not exist. Getter methods document which lookups can produce this.
  • ErrInvalidArgument: returned when required arguments are nil, zero, or otherwise malformed.
  • ErrPDPVerifierNotConfigured: returned when a PDPVerifier-dependent read is used without configuring a PDPVerifier address.
  • ErrWriteNotConfigured: returned when a write method is used without write dependencies.

Stability

0.x phase: public API may change between minor releases.

Example

Example demonstrates listing a client's data sets via warmstorage.Service. In practice a Service is obtained from synapse.Client.WarmStorage. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ethereum/go-ethereum/common"
	"github.com/strahe/synapse-go/types"
	"github.com/strahe/synapse-go/warmstorage"
)

func main() {
	var svc *warmstorage.Service // obtained from synapse.Client.WarmStorage()

	ctx := context.Background()
	payer := common.HexToAddress("0x...")

	sets, err := svc.GetClientDataSets(ctx, payer, types.ListOptions{Limit: 10})
	if err != nil {
		log.Fatal(err)
	}
	for _, s := range sets {
		fmt.Println(s.DataSetID)
	}
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrClosed = lifecycle.ErrClosed

ErrClosed is returned when a method is called after the owning Client has been closed. It aliases the shared closed-client sentinel.

View Source 
var ErrInvalidArgument = errors.New("warmstorage: invalid argument")

ErrInvalidArgument is returned, wrapped, when a caller passes an argument that fails local precondition checks (nil IDs, zero addresses, etc.). Use errors.Is to detect it.

View Source 
var ErrNotFound = errors.New("warmstorage: not found")

ErrNotFound is returned, wrapped via fmt.Errorf with %w, when a queried record (e.g. a data set) does not exist on-chain. Callers should use errors.Is(err, warmstorage.ErrNotFound) rather than comparing for nil results.

View Source 
var ErrPDPVerifierNotConfigured = errors.New("warmstorage: PDPVerifier address not configured")

ErrPDPVerifierNotConfigured is returned when a method that relies on direct PDPVerifier reads is called on a Service that was constructed without a PDPVerifier address.

View Source 
var ErrUninitialized = errors.New("warmstorage: service not initialized; use warmstorage.New")

ErrUninitialized is returned when a method is invoked on a zero-value Service (one that was not constructed via New).

View Source 
var ErrWriteNotConfigured = errors.New("warmstorage: write backend / signer not configured")

ErrWriteNotConfigured is returned when a write method is called on a Service that was constructed without a Backend / Signer.

Functions

This section is empty.

Types

type Backend 

type Backend interface {
	bind.ContractBackend
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*ethtypes.Receipt, error)
	BlockNumber(ctx context.Context) (uint64, error)
}

Backend extends EthClient with the surface required for sending transactions (TopUpCDNPaymentRails). The full ethclient.Client satisfies this interface.

type DataSetInfo 

type DataSetInfo struct {
	DataSetID       types.BigInt
	PDPRailID       types.BigInt // payment rail for PDP proofs
	CacheMissRailID types.BigInt // payment rail for cache-miss egress
	CDNRailID       types.BigInt // payment rail for CDN egress
	Payer           common.Address
	Payee           common.Address
	ServiceProvider common.Address
	CommissionBps   *big.Int     // commission rate in basis points (out of 10 000)
	ClientDataSetID types.BigInt // caller-assigned ID used in EIP-712 payloads
	PDPEndEpoch     types.Epoch  // epoch at which PDP service expires; 0 = indefinite
	ProviderID      types.BigInt // storage provider ID
}

DataSetInfo is the FWSS StateView record for one data set.

type EnhancedDataSetInfo 

type EnhancedDataSetInfo struct {
	*DataSetInfo
	PDPVerifierDataSetID sdktypes.BigInt
	IsLive               bool
	IsManaged            bool
	ActivePieceCount     *big.Int
	WithCDN              bool
	Metadata             map[string]string
}

EnhancedDataSetInfo extends DataSetInfo with pdpverifier-derived liveness metadata. Returned by GetClientDataSetsWithDetails.

type EthClient 

type EthClient interface {
	bind.ContractCaller
}

EthClient is the minimal RPC surface the service needs. The interface is defined here so tests can substitute a mock without pulling in ethclient.

type Options 

type Options struct {
	Client       EthClient
	FWSS         common.Address
	ViewContract common.Address
	// PDPVerifier is the PDPVerifier contract address. Optional. Required
	// only for methods that call PDPVerifier directly (ValidateDataSet,
	// GetActivePieceCount, GetScheduledRemovals, and the isLive / listener
	// decorators on GetClientDataSetsWithDetails).
	PDPVerifier common.Address
	// ChainID is required only when writes are used (TopUpCDNPaymentRails).
	ChainID types.ChainID
	// Backend provides a full RPC surface for writes. When nil Service is
	// read-only; write methods return ErrWriteNotConfigured.
	Backend Backend
	// Signer signs write transactions. Optional.
	Signer signer.EVMSigner
	// NonceManager is optional. The root synapse Client injects a shared
	// coordinator across all write-capable services; standalone callers may
	// leave this nil to create one when Backend and Signer are both set.
	NonceManager *txutil.NonceManager
	// Logger is optional.
	Logger *slog.Logger
	// ReceiptWait overrides the default receipt polling timeout for
	// WithWait calls. Zero uses txutil.DefaultReceiptWaitConfig.
	ReceiptWait time.Duration
	// Lifecycle, when non-nil, ties this Service to the owning Client's
	// close state. After the Lifecycle is closed, every method returns
	// ErrClosed. Nil is allowed for standalone use.
	Lifecycle *lifecycle.Lifecycle
}

Options bundle the caller and contract addresses.

type PDPConfig 

type PDPConfig struct {
	MaxProvingPeriod         uint64
	ChallengeWindowSize      *big.Int
	ChallengesPerProof       *big.Int
	InitChallengeWindowStart *big.Int
}

PDPConfig contains the FWSS StateView parameters that govern proving period scheduling.

type Service 

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

Service provides read access to FilecoinWarmStorageService (FWSS) and its companion StateView contract, plus a small number of writes that are semantically owned by the WarmStorage contract (TopUpCDNPaymentRails).

Most writes still flow through the payments service or the curio HTTP client. FWSS is invoked here for queries that back SDK decisions (service pricing, dataset existence, provider approval, dataset management checks).

func New 

func New(opts Options) (*Service, error)

New creates a Service. Both FWSS and ViewContract addresses are required. The root synapse Client supplies the canonical chain addresses; low-level callers must provide the addresses they want this Service to use.

func (*Service) FWSSAddress 

func (s *Service) FWSSAddress() common.Address

FWSSAddress returns the configured FWSS contract address.

func (*Service) GetActivePieceCount 

func (s *Service) GetActivePieceCount(ctx context.Context, dataSetID sdktypes.BigInt) (*big.Int, error)

GetActivePieceCount returns the number of live (non-removed) pieces in the given data set.

func (*Service) GetAllDataSetMetadata 

func (s *Service) GetAllDataSetMetadata(ctx context.Context, dataSetID types.BigInt) (map[string]string, error)

GetAllDataSetMetadata returns all metadata entries for the given dataset as a key/value map. The returned map is non-nil; an empty map signals "no metadata entries" (which the contract also returns when the dataset itself does not exist — the two cases are indistinguishable at this layer). Mismatched response lengths are treated as an RPC/ABI error.

func (*Service) GetAllPieceMetadata 

func (s *Service) GetAllPieceMetadata(ctx context.Context, dataSetID sdktypes.BigInt, pieceID sdktypes.BigInt) (map[string]string, error)

GetAllPieceMetadata returns a key/value map of all metadata for a specific (dataSetID, pieceID) pair.

func (*Service) GetApprovedProviderIDs 

func (s *Service) GetApprovedProviderIDs(ctx context.Context, opts types.ListOptions) ([]types.BigInt, error)

GetApprovedProviderIDs returns one page of approved-provider ids. opts.Limit must be > 0; use IterateAllApprovedProviderIDs for unbounded traversal.

func (*Service) GetApprovedProvidersLength 

func (s *Service) GetApprovedProvidersLength(ctx context.Context) (*big.Int, error)

GetApprovedProvidersLength returns the total number of approved providers.

func (*Service) GetClientDataSetIds 

func (s *Service) GetClientDataSetIds(ctx context.Context, payer common.Address, opts sdktypes.ListOptions) ([]sdktypes.BigInt, error)

GetClientDataSetIds returns the shallow list of data set IDs for payer with offset/limit pagination. Limit must be > 0; use IterateAllClientDataSetIds for unbounded traversal.

func (*Service) GetClientDataSets 

func (s *Service) GetClientDataSets(ctx context.Context, payer common.Address, opts types.ListOptions) ([]*DataSetInfo, error)

GetClientDataSets returns one page of data sets owned by payer. opts.Limit must be > 0; use IterateAllClientDataSets for unbounded traversal.

func (*Service) GetClientDataSetsLength 

func (s *Service) GetClientDataSetsLength(ctx context.Context, payer common.Address) (*big.Int, error)

GetClientDataSetsLength returns the total number of data sets for a payer.

func (*Service) GetClientDataSetsWithDetails 

func (s *Service) GetClientDataSetsWithDetails(ctx context.Context, payer common.Address, onlyManaged bool) ([]*EnhancedDataSetInfo, error)

GetClientDataSetsWithDetails returns the client's data sets enriched with pdpverifier liveness and active-piece counts. Requires the Service to have been configured with a PDPVerifier address. When onlyManaged is true, entries whose listener is not this WarmStorage contract are filtered out.

func (*Service) GetDataSet 

func (s *Service) GetDataSet(ctx context.Context, dataSetID types.BigInt) (*DataSetInfo, error)

GetDataSet returns the data set record for dataSetID. Returns an error wrapping ErrNotFound when no such data set exists (the contract convention is pdpRailId == 0 for "not found"). RPC or ABI errors are wrapped and propagated as-is.

func (*Service) GetOwner 

func (s *Service) GetOwner(ctx context.Context) (common.Address, error)

GetOwner returns the current owner of the FWSS contract.

func (*Service) GetPDPConfig 

func (s *Service) GetPDPConfig(ctx context.Context) (*PDPConfig, error)

GetPDPConfig returns PDP proving-period parameters from FWSSView.

func (*Service) GetPieceMetadata 

func (s *Service) GetPieceMetadata(ctx context.Context, dataSetID sdktypes.BigInt, pieceID sdktypes.BigInt, key string) (bool, string, error)

GetPieceMetadata returns the (exists, value) pair for (dataSetID, pieceID, key).

func (*Service) GetServicePrice 

func (s *Service) GetServicePrice(ctx context.Context) (*ServicePrice, error)

GetServicePrice returns the current pricing parameters.

func (*Service) IsOwner 

func (s *Service) IsOwner(ctx context.Context, addr common.Address) (bool, error)

IsOwner reports whether addr equals the current owner.

func (*Service) IsProviderApproved 

func (s *Service) IsProviderApproved(ctx context.Context, providerID types.BigInt) (bool, error)

IsProviderApproved returns true if providerID is on the approved list.

func (*Service) IterateAllApprovedProviderIDs 

func (s *Service) IterateAllApprovedProviderIDs(ctx context.Context) iter.Seq2[types.BigInt, error]

IterateAllApprovedProviderIDs yields every approved-provider id across all pages. Semantics match IterateAllClientDataSets.

func (*Service) IterateAllClientDataSetIds 

func (s *Service) IterateAllClientDataSetIds(ctx context.Context, payer common.Address) iter.Seq2[types.BigInt, error]

IterateAllClientDataSetIds yields every data set ID owned by payer across all pages. Semantics match IterateAllClientDataSets but returns a shallow list of IDs (lighter-weight than the full DataSetInfo).

func (*Service) IterateAllClientDataSets 

func (s *Service) IterateAllClientDataSets(ctx context.Context, payer common.Address) iter.Seq2[*DataSetInfo, error]

IterateAllClientDataSets yields every data set owned by payer across all pages. It terminates cleanly when ctx is cancelled; the error yielded by the last (err != nil) pair is ctx.Err(). Break out of the range loop to stop early — the iterator performs no further RPC work after the body returns false.

func (*Service) PDPVerifierAddress 

func (s *Service) PDPVerifierAddress() common.Address

PDPVerifierAddress returns the configured PDPVerifier address. Zero when the Service was constructed without a PDPVerifier.

func (*Service) TerminateDataSet 

func (s *Service) TerminateDataSet(ctx context.Context, dataSetID sdktypes.BigInt, opts ...WriteOption) (*sdktypes.WriteResult, error)

TerminateDataSet terminates the FWSS-managed payment rails for the given data set. It maps to FWSS.terminateService(uint256).

See FilecoinWarmStorageService.sol and the TS warmStorage.terminateService for semantics.

func (*Service) TopUpCDNPaymentRails 

func (s *Service) TopUpCDNPaymentRails(
	ctx context.Context,
	dataSetID sdktypes.BigInt,
	cdnAmountToAdd, cacheMissAmountToAdd *big.Int,
	opts ...WriteOption,
) (*sdktypes.WriteResult, error)

TopUpCDNPaymentRails tops up the CDN egress and cache-miss rails associated with dataSetID. Requires Signer + Backend.

func (*Service) ValidateDataSet 

func (s *Service) ValidateDataSet(ctx context.Context, dataSetID sdktypes.BigInt) error

ValidateDataSet verifies that the given data set is alive on the PDPVerifier contract and that its listener is this WarmStorage contract. Returns nil on success.

func (*Service) ViewAddress 

func (s *Service) ViewAddress() common.Address

ViewAddress returns the configured StateView contract address.

type ServicePrice 

type ServicePrice struct {
	PricePerTiBPerMonthNoCDN   *big.Int
	PricePerTiBCdnEgress       *big.Int
	PricePerTiBCacheMissEgress *big.Int
	TokenAddress               common.Address // EVM address of the payment token
	EpochsPerMonth             *big.Int       // Filecoin epochs per billing month
	MinimumPricePerMonth       *big.Int
}

ServicePrice is the FWSS pricing view. All amounts are in base units of the payment token.

type WriteOption 

type WriteOption func(*writeConfig)

WriteOption tunes the behaviour of a single state-changing call.

func WithConfirmations 

func WithConfirmations(n uint64) WriteOption

WithConfirmations requires N block confirmations in addition to WithWait.

func WithWait 

func WithWait(timeout time.Duration) WriteOption

WithWait makes the call block until the transaction is mined, or the given timeout elapses. Zero / negative returns immediately after broadcast.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.