warmstorage

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package warmstorage provides the WarmStorage (FWSS) service for managing storage contracts, data sets, and 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 direct FWSS teardown), bounded active-piece checks through Service.HasActivePieces, PriceList reads, approved-provider reads, and provider allocation. Service.GetServicePrice remains as a compatibility view; Service.GetPriceList is the canonical pricing entry point.

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 or typed errors. Use errors.Is for sentinels and errors.AsType for typed errors:

  • 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.
  • DataSetNotLiveError: returned by ValidateDataSet when PDPVerifier reports that the data set is not live.
  • DataSetNotManagedError: returned by ValidateDataSet when the data set is managed by another listener.

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 DataSetNotLiveError added in v0.3.0 

type DataSetNotLiveError struct {
	DataSetID types.BigInt
}

DataSetNotLiveError is returned when PDPVerifier reports that a data set is not live, which prevents adding pieces to it.

func (*DataSetNotLiveError) Error added in v0.3.0 

func (e *DataSetNotLiveError) Error() string

type DataSetNotManagedError added in v0.3.0 

type DataSetNotManagedError struct {
	DataSetID        types.BigInt
	Listener         common.Address
	ExpectedListener common.Address
}

DataSetNotManagedError is returned when a data set is live but managed by a listener other than this WarmStorage contract.

func (*DataSetNotManagedError) Error added in v0.3.0 

func (e *DataSetNotManagedError) Error() string

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 NonceManager added in v0.5.0 

type NonceManager interface {
	Acquire(ctx context.Context) (nonce uint64, release func(), err error)
}

NonceManager serializes transaction-nonce acquisition for one signing address. On success, Acquire must return the next pending nonce and a non-nil, idempotent release function. Callers may invoke release more than once, but must invoke it after broadcasting or abandoning the transaction.

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, HasActivePieces, 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. A
	// typed-nil value is treated as nil.
	NonceManager NonceManager
	// Logger is optional.
	Logger *slog.Logger
	// ReceiptWait overrides the default receipt polling timeout for
	// WithWait calls. Zero uses the default receipt polling configuration.
	ReceiptWait time.Duration
	// MaxMulticallCalls limits the number of actual contract calls in each
	// dynamic Multicall3 request. Zero uses the default of 64. Negative values
	// are invalid. Batches execute serially and may observe different blocks;
	// this count does not bound request or response bytes, gas, or execution
	// time.
	MaxMulticallCalls int
	// Lifecycle is checked before service operations that can touch configured
	// backends. Any error returned by CheckClosed is returned without touching
	// those backends. The root synapse Client injects a shared checker whose
	// closed error matches ErrClosed. Nil is allowed for standalone use. A
	// typed-nil value is treated as nil.
	Lifecycle interface{ CheckClosed() error }
}

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 PDPPaymentTerminatedEvent added in v0.4.0 

type PDPPaymentTerminatedEvent struct {
	DataSetID sdktypes.BigInt
	EndEpoch  sdktypes.Epoch
	PDPRailID sdktypes.BigInt
}

PDPPaymentTerminatedEvent is the FWSS termination event carrying the PDP rail end epoch.

func ExtractPDPPaymentTerminatedEvent added in v0.4.0 

func ExtractPDPPaymentTerminatedEvent(receipt *ethtypes.Receipt) (*PDPPaymentTerminatedEvent, error)

ExtractPDPPaymentTerminatedEvent extracts PDPPaymentTerminated from a transaction receipt.

type PriceList added in v0.4.0 

type PriceList struct {
	Token   common.Address
	Rates   PriceListRates
	Fees    PriceListFees
	Lockups PriceListLockups
}

PriceList is the canonical warm-storage pricing view. All amounts are in base units of the payment token.

type PriceListFees added in v0.4.0 

type PriceListFees struct {
	CreateDataSetFee         *big.Int
	AddPiecesBaseFee         *big.Int
	AddPiecesPerPieceFee     *big.Int
	SchedulePieceRemovalsFee *big.Int
	TerminateFee             *big.Int
}

PriceListFees contains one-time operation fees.

type PriceListLockups added in v0.4.0 

type PriceListLockups struct {
	LifecycleReserveTarget *big.Int
	ReplenishThreshold     *big.Int
	DefaultLockupPeriod    *big.Int
	CDNLockupAmount        *big.Int
	CacheMissLockupAmount  *big.Int
	CDNLockupPeriod        *big.Int
}

PriceListLockups contains required lockup amounts and periods.

type PriceListRates added in v0.4.0 

type PriceListRates struct {
	StoragePerTiBPerMonth *big.Int
	DatasetFeePerMonth    *big.Int
	CDNEgressPerTiB       *big.Int
	CacheMissEgressPerTiB *big.Int
}

PriceListRates contains recurring storage and egress rates.

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) GetAllClientDataSetIds added in v0.3.1 

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

GetAllClientDataSetIds returns every data set ID owned by payer across all pages. It materializes the full result set in memory; use IterateAllClientDataSetIds or GetClientDataSetIds with explicit pagination for large accounts.

func (*Service) GetAllClientDataSets added in v0.3.1 

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

GetAllClientDataSets returns every data set owned by payer across all pages. It materializes the full result set in memory; use IterateAllClientDataSets or GetClientDataSets with explicit pagination for large accounts.

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, 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. Detail reads use serial Multicall3 batches; separate batches may observe different blocks. When sub-calls fail, the method returns the earliest error in data-set and operation order.

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, pieceID sdktypes.BigInt, key string) (bool, string, error)

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

func (*Service) GetPriceList added in v0.4.0 

func (s *Service) GetPriceList(ctx context.Context) (*PriceList, error)

GetPriceList returns the canonical warm-storage price list.

func (*Service) GetServicePrice deprecated 

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

GetServicePrice returns the legacy current pricing parameters.

Deprecated: Use GetPriceList.

func (*Service) HasActivePieces added in v0.4.1 

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

HasActivePieces reports whether the data set contains at least one active piece. It reads at most one piece, so its cost does not grow with the total number of pieces. Missing and non-live data sets report false.

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).

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 deprecated 

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
	DatasetFeePerMonth         *big.Int
	// MinimumPricePerMonth is kept as a source-compatibility alias for
	// DatasetFeePerMonth.
	//
	// Deprecated: Use DatasetFeePerMonth.
	MinimumPricePerMonth *big.Int
}

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

Deprecated: Use PriceList returned by GetPriceList. ServicePrice omits one-time fees and lockup parameters required for current cost calculations.

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.