synapse

package
v0.1.0-beta.1 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsDataSetServiceEnded

func IsDataSetServiceEnded(err error) bool

func IsDataSetWriteBlocked

func IsDataSetWriteBlocked(err error) bool

IsDataSetWriteBlocked reports whether err means the data set can no longer accept writes because its PDP payment ended. The SDK raises it while validating the data set, before the provider is contacted, so a commit that fails this way never reached the provider.

func IsNoProviderCandidates

func IsNoProviderCandidates(err error) bool

func IsProviderUnavailable

func IsProviderUnavailable(err error) bool

func IsTerminationBlocked

func IsTerminationBlocked(err error) bool

IsTerminationBlocked reports whether termination needs operator action rather than another attempt.

func NewClient

func NewClient(ctx context.Context, cfg ClientConfig) (*sdk.Client, error)

NewClient creates a synapse-go Client from config fields.

func NormalizeProviderOperationError

func NormalizeProviderOperationError(ctx context.Context, err error) error

NormalizeProviderOperationError classifies failures from a known provider endpoint. Callers must not use it for chain RPC or mixed resolution work.

Types

type AddPiecesStatusInput

type AddPiecesStatusInput struct {
	ServiceURL         string
	StatusURL          string
	DataSetID          string
	TransactionID      string
	ExpectedPieceCount int
}

type ChainEpochReader

type ChainEpochReader interface {
	CurrentEpoch(ctx context.Context) (int64, error)
}

ChainEpochReader observes the chain head. Replacement uses it to decide when a terminated service has genuinely ended.

func NewChainEpochReader

func NewChainEpochReader(source blockNumberSource) ChainEpochReader

NewChainEpochReader reads the epoch from the chain head.

The wall-clock estimate available elsewhere in the SDK derives an epoch from genesis time and can run ahead of the chain, which would let a replacement retire a source before its service has really ended. Retirement therefore only trusts an observed block number.

type CleanupContext

type CleanupContext interface {
	DeletePieceByID(context.Context, sdktypes.BigInt) (*sdktypes.WriteResult, error)
	PieceStatus(context.Context, cid.Cid) (*storage.PieceStatus, error)
}

CleanupContext abstracts the SDK operations needed to remove PDP pieces.

type ClientConfig

type ClientConfig struct {
	PrivateKey           string
	RPCURL               string
	WithCDN              bool
	AllowPrivateNetworks bool
	Logger               *slog.Logger
}

ClientConfig contains SynapS3 runtime settings forwarded into synapse-go.

type DataSetCreationStatusInput

type DataSetCreationStatusInput struct {
	StatusURL         string
	TransactionID     string
	ExpectedDataSetID string
}

type DataSetServiceEndedError

type DataSetServiceEndedError struct {
	Cause error
}

DataSetServiceEndedError reports typed evidence that an established data set no longer represents a writable service.

func (*DataSetServiceEndedError) Error

func (e *DataSetServiceEndedError) Error() string

func (*DataSetServiceEndedError) Unwrap

func (e *DataSetServiceEndedError) Unwrap() error

type DataSetTarget

DataSetTarget is an immutable existing data set used for piece operations.

type NoProviderCandidatesError

type NoProviderCandidatesError struct {
	Cause error
}

NoProviderCandidatesError reports that automatic selection cannot currently satisfy a newly authorized replica slot.

func (*NoProviderCandidatesError) Error

func (e *NoProviderCandidatesError) Error() string

func (*NoProviderCandidatesError) Unwrap

func (e *NoProviderCandidatesError) Unwrap() error

type PDPStatusChecker

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

func NewPDPStatusChecker

func NewPDPStatusChecker(opts PDPStatusCheckerOptions) *PDPStatusChecker

func (*PDPStatusChecker) CheckAddPiecesStatus

func (c *PDPStatusChecker) CheckAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) PDPStatusResult

func (*PDPStatusChecker) CheckDataSetCreationStatus

func (c *PDPStatusChecker) CheckDataSetCreationStatus(ctx context.Context, input DataSetCreationStatusInput) PDPStatusResult

func (*PDPStatusChecker) GetAddPiecesStatus

func (c *PDPStatusChecker) GetAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) (PDPStatusResult, error)

GetAddPiecesStatus performs one validated status request while preserving the underlying error for operational callers that must classify retries.

type PDPStatusCheckerOptions

type PDPStatusCheckerOptions struct {
	Timeout              time.Duration
	AllowPrivateNetworks bool
}

type PDPStatusResult

type PDPStatusResult struct {
	State                  PDPStatusState
	StatusURL              string
	TxStatus               string
	DataSetID              string
	DataSetCreated         bool
	PiecesAdded            bool
	PieceCount             int
	ConfirmedPieceIDs      []string
	ConfirmedTransactionID string
	Error                  string
}

type PDPStatusState

type PDPStatusState string
const (
	PDPStatusPending     PDPStatusState = "pending"
	PDPStatusConfirmed   PDPStatusState = "confirmed"
	PDPStatusRejected    PDPStatusState = "rejected"
	PDPStatusMismatch    PDPStatusState = "mismatch"
	PDPStatusUnavailable PDPStatusState = "unavailable"
	PDPStatusUnknown     PDPStatusState = "unknown"
)

type PaymentAccountInfo

type PaymentAccountInfo struct {
	Funds               *big.Int
	AvailableFunds      *big.Int
	LockupCurrent       *big.Int
	LockupRate          *big.Int
	LockupLastSettledAt *big.Int
	FundedUntilEpoch    *big.Int
	FundedUntilTime     *time.Time
	RunwaySeconds       *int64
	LockupRatePerDay    *big.Int
	LockupRatePerMonth  *big.Int
	NoActiveSpend       bool
}

PaymentAccountInfo holds USDFC payment contract account state.

type ProviderTarget

ProviderTarget is an unbound provider used to create or resume creation of a data set. Creating a data set does not mutate the target into a bound one.

type ProviderUnavailableError

type ProviderUnavailableError struct {
	Cause error
}

ProviderUnavailableError reports a recoverable provider or transport dependency failure.

func (*ProviderUnavailableError) Error

func (e *ProviderUnavailableError) Error() string

func (*ProviderUnavailableError) Unwrap

func (e *ProviderUnavailableError) Unwrap() error

type ReadinessCheck

type ReadinessCheck struct {
	ID            string          `json:"id"`
	Status        ReadinessStatus `json:"status"`
	Message       string          `json:"message"`
	Action        string          `json:"action,omitempty"`
	RequiredUSDFC string          `json:"required_usdfc,omitempty"`
}

type ReadinessChecker

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

func NewReadinessChecker

func NewReadinessChecker(cfg ReadinessConfig, runtime ReadinessClient, opts ...ReadinessCheckerOption) *ReadinessChecker

func (*ReadinessChecker) CheckDraft

func (*ReadinessChecker) CheckRuntime

func (c *ReadinessChecker) CheckRuntime(ctx context.Context) ReadinessResult

type ReadinessCheckerOption

type ReadinessCheckerOption func(*ReadinessChecker)

func WithReadinessClientFactory

func WithReadinessClientFactory(factory ReadinessClientFactory) ReadinessCheckerOption

func WithReadinessLogger

func WithReadinessLogger(logger *slog.Logger) ReadinessCheckerOption

func WithReadinessTimeout

func WithReadinessTimeout(timeout time.Duration) ReadinessCheckerOption

type ReadinessClient

type ReadinessClient interface {
	Address() common.Address
	Chain() chain.Chain
	ResolvedAddresses() sdk.ResolvedAddresses
	Payments() readinessPayments
	Storage() readinessStorage
	Close() error
}

func AdaptReadinessClient

func AdaptReadinessClient(client *sdk.Client) ReadinessClient

type ReadinessClientFactory

type ReadinessClientFactory func(context.Context, ReadinessConfig) (ReadinessClient, error)

type ReadinessConfig

type ReadinessConfig struct {
	Network              string
	RPCURL               string
	PrivateKey           string
	WithCDN              bool
	AllowPrivateNetworks bool
	DefaultCopies        int
}

func ReadinessConfigFromFilecoinConfig

func ReadinessConfigFromFilecoinConfig(cfg config.FilecoinConfig) ReadinessConfig

type ReadinessMode

type ReadinessMode string
const (
	ReadinessModeRuntime ReadinessMode = "runtime"
	ReadinessModeDraft   ReadinessMode = "draft"
)

type ReadinessResult

type ReadinessResult struct {
	Status        ReadinessStatus   `json:"status"`
	Mode          ReadinessMode     `json:"mode"`
	CheckedAt     time.Time         `json:"checked_at"`
	Checks        []ReadinessCheck  `json:"checks"`
	PartialErrors map[string]string `json:"partial_errors,omitempty"`
}

func (*ReadinessResult) Finish

func (r *ReadinessResult) Finish()

Finish updates the aggregate readiness status from the contained checks.

type ReadinessStatus

type ReadinessStatus string
const (
	ReadinessStatusReady   ReadinessStatus = "ready"
	ReadinessStatusWarning ReadinessStatus = "warning"
	ReadinessStatusBlocked ReadinessStatus = "blocked"
	ReadinessStatusUnknown ReadinessStatus = "unknown"
)

type ServiceTerminator

type ServiceTerminator interface {
	TerminateService(ctx context.Context, dataSetID sdktypes.BigInt) (*TerminationResult, error)
}

ServiceTerminator is the destructive service-lifecycle boundary. It is used only after replacement cleanup authorization and the retirement safety gate have both passed.

type StorageClient

type StorageClient interface {
	Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error)
	PrepareUpload(ctx context.Context, dataSize uint64, targets []StorageTarget) (*storage.MultiContextCosts, error)
	SelectUploadTargets(ctx context.Context, opts storage.SelectUploadContextsOptions) ([]StorageTarget, error)
	OpenProviderTarget(ctx context.Context, providerID sdktypes.BigInt, opts storage.NewProviderContextOptions) (ProviderTarget, error)
	OpenDataSetTarget(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (DataSetTarget, error)
	FindMatchingDataSet(ctx context.Context, providerID sdktypes.BigInt, metadata map[string]string, withCDN bool) (*storage.DataSetRef, error)
	OpenCleanupContext(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (CleanupContext, error)
}

StorageClient abstracts the synapse-go storage service for download plus staged provider operations.

type StorageServiceAdapter

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

StorageServiceAdapter adapts synapse-go's concrete immutable storage contexts to SynapS3's testable staged storage interface.

func AdaptStorageService

func AdaptStorageService(service *storage.Service) *StorageServiceAdapter

func (*StorageServiceAdapter) Download

func (s *StorageServiceAdapter) Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error)

func (*StorageServiceAdapter) FindMatchingDataSet

func (s *StorageServiceAdapter) FindMatchingDataSet(
	ctx context.Context,
	providerID sdktypes.BigInt,
	metadata map[string]string,
	withCDN bool,
) (*storage.DataSetRef, error)

func (*StorageServiceAdapter) OpenCleanupContext

func (*StorageServiceAdapter) OpenDataSetTarget

func (*StorageServiceAdapter) OpenProviderTarget

func (*StorageServiceAdapter) PrepareUpload

func (s *StorageServiceAdapter) PrepareUpload(ctx context.Context, dataSize uint64, targets []StorageTarget) (*storage.MultiContextCosts, error)

func (*StorageServiceAdapter) SelectUploadTargets

func (*StorageServiceAdapter) TerminateService

func (s *StorageServiceAdapter) TerminateService(ctx context.Context, dataSetID sdktypes.BigInt) (*TerminationResult, error)

TerminateService ends the storage service for one data set. It is the destructive boundary of provider replacement and must only be called after the retirement safety gate passes.

Termination is relayed through the provider first. A provider-side failure falls back to the direct FWSS transaction path; a pending relay does not, because the provider has already accepted it. An already-terminated service reports its recorded end epoch rather than failing.

type StorageTarget

type StorageTarget interface {
	ProviderID() sdktypes.BigInt
	DataSetRef() (storage.DataSetRef, bool)
	GetProviderInfo() storage.Provider
	CDNEnabled() bool
	PieceURL(cid.Cid) string
	ServiceURL() string
}

StorageTarget abstracts the immutable identity shared by provider and data set targets returned by synapse-go.

type TerminationBlockedError

type TerminationBlockedError struct {
	Reason    string
	Shortfall *big.Int
	Err       error
}

TerminationBlockedError means the service cannot be terminated until an operator resolves something the gateway must not decide on its own, such as settling outstanding payment debt. It is never retried automatically.

func (*TerminationBlockedError) Error

func (e *TerminationBlockedError) Error() string

func (*TerminationBlockedError) Unwrap

func (e *TerminationBlockedError) Unwrap() error

type TerminationResult

type TerminationResult struct {
	TxHash   string
	EndEpoch int64
}

TerminationResult records what the chain agreed to. EndEpoch is the epoch at which the service actually stops, which is why retirement waits for the chain to reach it rather than trusting the call returning.

type WalletInfo

type WalletInfo struct {
	Address              string
	Network              string
	ChainID              int64
	Nonce                *uint64
	CurrentEpoch         *big.Int
	EpochDurationSeconds int64
	PaymentsAddress      string
	USDFCAddress         string
	USDFCDecimals        uint8
	FILGasBalance        *big.Int
	USDFCWalletBalance   *big.Int
	PaymentAccount       *PaymentAccountInfo
	Errors               map[string]string
}

WalletInfo holds a snapshot of the wallet's on-chain state. Fields are nil when the corresponding RPC call failed; see Errors for details.

type WalletOperator

type WalletOperator interface {
	FundUSDFC(ctx context.Context, amount *big.Int) (string, error)
	WithdrawUSDFC(ctx context.Context, amount *big.Int) (string, error)
	ApproveFWSS(ctx context.Context) (string, error)
}

WalletOperator broadcasts wallet payment transactions.

func NewWalletOperator

func NewWalletOperator(paySvc *payments.Service, usdfc common.Address) WalletOperator

type WalletQuerier

type WalletQuerier interface {
	GetWalletInfo(ctx context.Context) (*WalletInfo, error)
}

WalletQuerier provides on-chain wallet state for the admin dashboard.

func NewWalletQuerier

func NewWalletQuerier(paySvc *payments.Service, address common.Address, c chain.Chain, addrs sdk.ResolvedAddresses) WalletQuerier

NewWalletQuerier creates a WalletQuerier backed by synapse-go payments.Service.

Jump to

Keyboard shortcuts

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