storage

package

Go to main page

Versions in this module

v0

v0.2.2

May 8, 2026

Changes in this version

type Context

+ func (c *Context) DeletePieceByID(ctx context.Context, pieceID sdktypes.BigInt) (*sdktypes.WriteResult, error)

v0.2.1

May 6, 2026

v0.2.0

May 4, 2026

Changes in this version

+ type CDNRetriever interface

+ DownloadPiece func(context.Context, cid.Cid) (io.ReadCloser, error)

type Context

+ func (c *Context) CreateDataSet(ctx context.Context, opts *CreateDataSetOptions) (*CreateDataSetResult, error)

+ func (c *Context) WaitForDataSetCreated(ctx context.Context, submission CreateDataSetSubmission) (*CreateDataSetResult, error)

type ContextOption

+ func WithCDNRetriever(r CDNRetriever) ContextOption

+ func WithLogger(logger *slog.Logger) ContextOption

+ type CreateDataSetOptions struct

+ OnSubmitted func(CreateDataSetSubmission)

+ type CreateDataSetResult struct

+ ClientDataSetID types.BigInt

+ DataSetID types.BigInt

+ TransactionID string

+ type CreateDataSetSubmission struct

+ ClientDataSetID *types.BigInt

+ StatusURL string

+ TransactionID string

type Options

+ Logger *slog.Logger

+ type PDPProviderClient interface

+ AddPieces func(context.Context, types.BigInt, []pdp.AddPieceInput, []byte) (*pdp.AddPiecesResult, error)

+ CreateDataSet func(context.Context, common.Address, []byte) (*pdp.CreateDataSetResult, error)

+ CreateDataSetAndAddPieces func(context.Context, common.Address, []pdp.AddPieceInput, []byte) (*pdp.CreateDataSetResult, error)

+ DownloadPiece func(context.Context, cid.Cid) (io.ReadCloser, int64, error)

+ SchedulePieceDeletion func(ctx context.Context, dataSetID, pieceID types.BigInt, extraData []byte) (common.Hash, error)

+ UploadPieceStreaming func(context.Context, io.Reader, pdp.UploadPieceStreamingOptions) (*pdp.UploadStreamingResult, error)

+ WaitForCreateDataSetAndAddPieces func(context.Context, string, time.Duration) (*pdp.AddPiecesStatus, error)

+ WaitForDataSetCreated func(context.Context, string, time.Duration) (*pdp.CreateDataSetStatus, error)

+ WaitForPieceParked func(context.Context, cid.Cid, time.Duration) error

+ WaitForPiecesAdded func(context.Context, string, time.Duration) (*pdp.AddPiecesStatus, error)

+ WaitForPullComplete func(context.Context, pdp.PullRequest, time.Duration, func(*pdp.PullResult)) (*pdp.PullResult, error)

v0.1.0

Apr 26, 2026

Changes in this version

+ var ErrClosed = lifecycle.ErrClosed

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

+ var ErrInvalidDownloadOptions = errors.New("storage: invalid download options")

+ var ErrMaxBytesExceeded = errors.New("storage: download exceeded MaxBytes")

+ var ErrPrivateNetwork = errors.New("storage: private / local network address disallowed")

+ var ErrUninitialized = errors.New("storage: service not initialized; use storage.New")

+ var ErrUnsupportedScheme = errors.New("storage: unsupported URL scheme")

+ type Allowances struct

+ IsApproved bool

+ LockupAllowance *big.Int

+ LockupUsed *big.Int

+ MaxLockupPeriod *big.Int

+ RateAllowance *big.Int

+ RateUsed *big.Int

+ Service common.Address

+ type CIDMismatchError struct

+ ComputedV1 cid.Cid

+ ComputedV2 cid.Cid

+ Expected cid.Cid

+ func (e *CIDMismatchError) Error() string

+ type CommitError struct

+ Cause error

+ Endpoint string

+ ProviderID types.ProviderID

+ func (e *CommitError) Error() string

+ func (e *CommitError) Unwrap() error

+ type CommitRequest struct

+ ExtraData []byte

+ OnSubmitted func(txHash string)

+ Pieces []PieceInput

+ type CommitResult struct

+ DataSetID types.DataSetID

+ IsNewDataSet bool

+ PieceIDs []types.PieceID

+ TransactionID string

+ type ConfirmedPiece struct

+ PieceCID cid.Cid

+ PieceID types.PieceID

+ type Context struct

+ func NewContext(provider Provider, client PDPClient, evmSigner signer.EVMSigner, ...) (*Context, error)

+ func (c *Context) Commit(ctx context.Context, req CommitRequest) (*CommitResult, error)

+ func (c *Context) DataSetID() *types.DataSetID

+ func (c *Context) DeletePiece(ctx context.Context, pieceCID cid.Cid) (*sdktypes.WriteResult, error)

+ func (c *Context) Download(ctx context.Context, pieceCID cid.Cid) (io.ReadCloser, error)

+ func (c *Context) GetProviderInfo() Provider

+ func (c *Context) GetScheduledRemovals(ctx context.Context) ([]uint64, error)

+ func (c *Context) PieceStatus(ctx context.Context, pieceCID cid.Cid) (*PieceStatus, error)

+ func (c *Context) PieceURL(pieceCID cid.Cid) string

+ func (c *Context) PresignForCommit(ctx context.Context, pieces []PieceInput) ([]byte, error)

+ func (c *Context) ProviderID() types.ProviderID

+ func (c *Context) Pull(ctx context.Context, req PullRequest) (*PullResult, error)

+ func (c *Context) ServiceURL() string

+ func (c *Context) Store(ctx context.Context, r io.Reader, opts *StoreOptions) (*StoreResult, error)

+ func (c *Context) Terminate(ctx context.Context, opts ...warmstorage.WriteOption) (*types.WriteResult, error)

+ func (c *Context) Upload(ctx context.Context, r io.Reader, opts *UploadOptions) (*UploadResult, error)

+ func (c *Context) WithCDN() bool

+ type ContextCostRef struct

+ CurrentDataSetSizeBytes *big.Int

+ DataSetID *types.DataSetID

+ Provider Provider

+ WithCDN bool

+ type ContextFactory func(ResolvedUploadContext, *UploadOptions) (UploadContext, error)

+ type ContextOption func(*Context)

+ func WithCDN(enabled bool) ContextOption

+ func WithChainID(chainID types.ChainID) ContextOption

+ func WithClientDataSetID(id types.ClientDataSetID) ContextOption

+ func WithDataSetID(id types.DataSetID) ContextOption

+ func WithDataSetMetadata(metadata map[string]string) ContextOption

+ func WithFWSSTerminator(t FWSSTerminator) ContextOption

+ func WithPDPConfigReader(r PDPConfigReader) ContextOption

+ func WithPDPVerifierReader(r PDPVerifierReader) ContextOption

+ func WithPayer(payer common.Address) ContextOption

+ func WithRecordKeeper(addr common.Address) ContextOption

+ type CopyResult struct

+ DataSetID types.DataSetID

+ IsNewDataSet bool

+ PieceID types.PieceID

+ ProviderID types.ProviderID

+ RetrievalURL string

+ Role CopyRole

+ type CopyRole string

+ const CopyRolePrimary

+ const CopyRoleSecondary

+ type CopyStage string

+ const CopyStageCommit

+ const CopyStagePresign

+ const CopyStagePull

+ const CopyStageStore

+ type CreateContextOptions struct

+ DataSetIDs []types.DataSetID

+ DataSetMetadata map[string]string

+ ExcludeProviderIDs []types.ProviderID

+ ProviderIDs []types.ProviderID

+ WithCDN *bool

+ type CreateContextsOptions struct

+ Copies int

+ DataSetIDs []types.DataSetID

+ DataSetMetadata map[string]string

+ ExcludeProviderIDs []types.ProviderID

+ ProviderIDs []types.ProviderID

+ WithCDN *bool

+ type DataSetCatalog interface

+ GetAllDataSetMetadata func(context.Context, types.DataSetID) (map[string]string, error)

+ GetApprovedProviderIDs func(context.Context, types.ListOptions) ([]types.ProviderID, error)

+ GetClientDataSets func(context.Context, common.Address, types.ListOptions) ([]*warmstorage.DataSetInfo, error)

+ GetDataSet func(context.Context, types.DataSetID) (*warmstorage.DataSetInfo, error)

+ type DataSetFinder interface

+ FindDataSets func(ctx context.Context, payer common.Address, onlyManaged bool) ([]*DataSetInfo, error)

+ type DataSetInfo = warmstorage.EnhancedDataSetInfo

+ type DataSetSizeReader interface

+ GetDataSetSizeBytes func(ctx context.Context, dataSetID sdktypes.DataSetID) (*big.Int, error)

+ type DownloadContext interface

+ Download func(context.Context, cid.Cid) (io.ReadCloser, error)

+ type DownloadError struct

+ Cause error

+ StatusCode int

+ URL string

+ func (e *DownloadError) Error() string

+ func (e *DownloadError) Unwrap() error

+ type DownloadOptions struct

+ Context DownloadContext

+ URL string

+ type FWSSDataSetReader interface

+ GetDataSet func(ctx context.Context, dataSetID sdktypes.DataSetID) (*warmstorage.DataSetInfo, error)

+ type FWSSTerminator interface

+ TerminateDataSet func(ctx context.Context, dataSetID sdktypes.DataSetID, ...) (*sdktypes.WriteResult, error)

+ type FailedAttempt struct

+ Err error

+ Explicit bool

+ ProviderID types.ProviderID

+ Role CopyRole

+ Stage CopyStage

+ type FindDataSetsOptions struct

+ OnlyManaged bool

+ Payer common.Address

+ type GetStorageInfoOptions struct

+ Client common.Address

+ type MultiContextCosts struct

+ DepositNeeded *big.Int

+ NeedsFWSSMaxApproval bool

+ RatePerEpoch *big.Int

+ RatePerMonth *big.Int

+ Ready bool

+ type MultiCostCalculator interface

+ CalculateMultiContextCosts func(ctx context.Context, payer common.Address, dataSizeBytes *big.Int, ...) (*MultiContextCosts, error)

+ type MultiCostOptions struct

+ BufferEpochs int64

+ EnableCDN bool

+ ExtraRunwayEpochs int64

+ type Options struct

+ AllowPrivateNetworks bool

+ CommitConcurrency int

+ CostCalculator MultiCostCalculator

+ DataSetFinder DataSetFinder

+ DataSetSizeReader DataSetSizeReader

+ DataSetTerminator FWSSTerminator

+ DefaultWithCDN bool

+ DownloadMaxBytes int64

+ FWSSDataSetReader FWSSDataSetReader

+ HTTPClient *http.Client

+ Lifecycle *lifecycle.Lifecycle

+ MaxSecondaryAttempts int

+ PaymentsFunder PaymentsFunder

+ Resolver UploadResolver

+ SignerAddress common.Address

+ Source string

+ StorageInfoReader StorageInfoReader

+ type PDPClient interface

+ AddPieces func(context.Context, uint64, []icurio.AddPieceInput, []byte) (*icurio.AddPiecesResult, error)

+ CreateDataSetAndAddPieces func(context.Context, common.Address, []icurio.AddPieceInput, []byte) (*icurio.CreateDataSetResult, error)

+ DownloadPiece func(context.Context, cid.Cid) (io.ReadCloser, int64, error)

+ SchedulePieceDeletion func(ctx context.Context, dataSetID, pieceID uint64, extraData []byte) (common.Hash, error)

+ UploadPieceStreaming func(context.Context, io.Reader, icurio.UploadPieceStreamingOptions) (*icurio.UploadStreamingResult, error)

+ WaitForCreateDataSetAndAddPieces func(context.Context, string, time.Duration) (*icurio.AddPiecesStatus, error)

+ WaitForPieceParked func(context.Context, cid.Cid, time.Duration) error

+ WaitForPiecesAdded func(context.Context, string, time.Duration) (*icurio.AddPiecesStatus, error)

+ WaitForPullComplete func(context.Context, icurio.PullRequest, time.Duration, func(*icurio.PullResult)) (*icurio.PullResult, error)

+ type PDPConfigReader interface

+ GetPDPConfig func(ctx context.Context) (*warmstorage.PDPConfig, error)

+ type PDPProviderSource interface

+ GetPDPProvider func(context.Context, types.ProviderID) (*spregistry.PDPProvider, error)

+ SelectActivePDPProviders func(context.Context, spregistry.ProviderFilter) ([]spregistry.PDPProvider, error)

+ type PDPVerifierReader interface

+ BlockNumber func(ctx context.Context) (uint64, error)

+ FindPieceIdsByCid func(ctx context.Context, dataSetID sdktypes.DataSetID, pieceCID cid.Cid, ...) ([]uint64, error)

+ GetNextChallengeEpoch func(ctx context.Context, dataSetID sdktypes.DataSetID) (*big.Int, error)

+ GetScheduledRemovals func(ctx context.Context, dataSetID sdktypes.DataSetID) ([]uint64, error)

+ type PaymentsFunder interface

+ FundSync func(ctx context.Context, amount *big.Int, opts ...payments.WriteOption) (*sdktypes.WriteResult, error)

+ type PieceInput struct

+ PieceCID cid.Cid

+ PieceMetadata map[string]string

+ type PieceStatus struct

+ DataSetLastProven time.Time

+ DataSetNextProofDue time.Time

+ Exists bool

+ HoursUntilChallengeWindow float64

+ InChallengeWindow bool

+ IsProofOverdue bool

+ PieceID uint64

+ RetrievalURL string

+ type PrepareOptions struct

+ BufferEpochs int64

+ Contexts []UploadContext

+ Costs *MultiContextCosts

+ DataSize uint64

+ EnableCDN *bool

+ ExtraRunwayEpochs int64

+ type PrepareResult struct

+ Costs *MultiContextCosts

+ Transaction *PrepareTransaction

+ type PrepareTransaction struct

+ DepositAmount *big.Int

+ Execute func(ctx context.Context, opts ...payments.WriteOption) (*types.WriteResult, error)

+ IncludesApproval bool

+ type PricePerTiB struct

+ PerDay *big.Int

+ PerEpoch *big.Int

+ PerMonth *big.Int

+ type PricingInfo struct

+ NoCDN PricePerTiB

+ TokenAddress common.Address

+ TokenSymbol string

+ WithCDN PricePerTiB

+ type Provider struct

+ ID types.ProviderID

+ Payee common.Address

+ ServiceProvider common.Address

+ ServiceURL string

+ type PullPieceResult struct

+ PieceCID cid.Cid

+ Status PullStatus

+ type PullRequest struct

+ ExtraData []byte

+ From func(cid.Cid) string

+ OnProgress func(pieceCID cid.Cid, status PullStatus)

+ Pieces []cid.Cid

+ type PullResult struct

+ Pieces []PullPieceResult

+ Status PullStatus

+ type PullStatus string

+ const PullStatusComplete

+ const PullStatusFailed

+ const PullStatusInProgress

+ const PullStatusPending

+ const PullStatusRetrying

+ type ResolvedUploadContext struct

+ ClientDataSetID types.ClientDataSetID

+ DataSetID *types.DataSetID

+ DataSetMetadata map[string]string

+ Provider Provider

+ type Service struct

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

+ func (s *Service) CalculateMultiContextCosts(ctx context.Context, dataSizeBytes uint64, refs []ContextCostRef, ...) (*MultiContextCosts, error)

+ func (s *Service) CreateContext(ctx context.Context, opts *CreateContextOptions) (*Context, error)

+ func (s *Service) CreateContexts(ctx context.Context, opts *CreateContextsOptions) ([]*Context, error)

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

+ func (s *Service) FindDataSets(ctx context.Context, opts *FindDataSetsOptions) ([]*DataSetInfo, error)

+ func (s *Service) GetDefaultContext(ctx context.Context) (*Context, error)

+ func (s *Service) GetStorageInfo(ctx context.Context, opts *GetStorageInfoOptions) (*StorageInfo, error)

+ func (s *Service) Prepare(ctx context.Context, opts *PrepareOptions) (*PrepareResult, error)

+ func (s *Service) TerminateDataSet(ctx context.Context, dataSetID types.DataSetID, opts *TerminateDataSetOptions) (*types.WriteResult, error)

+ func (s *Service) Upload(ctx context.Context, r io.Reader, opts *UploadOptions) (*UploadResult, error)

+ type ServiceParameters struct

+ EpochDuration int64

+ EpochsPerDay int64

+ EpochsPerMonth int64

+ MaxUploadSize int64

+ MinUploadSize int64

+ type ServiceResolver struct

+ func NewServiceResolver(opts ServiceResolverOptions) (*ServiceResolver, error)

+ func (r *ServiceResolver) ResolveUploadContexts(ctx context.Context, opts *UploadOptions) ([]UploadContext, bool, error)

+ func (r *ServiceResolver) SelectReplacement(ctx context.Context, usedProviders map[types.ProviderID]struct{}, ...) (UploadContext, error)

+ type ServiceResolverOptions struct

+ NewContext ContextFactory

+ Payer common.Address

+ SPRegistry PDPProviderSource

+ WarmStorage DataSetCatalog

+ type StorageInfo struct

+ Allowances *Allowances

+ Pricing PricingInfo

+ Providers []spregistry.PDPProvider

+ ServiceParameters ServiceParameters

+ type StorageInfoReader interface

+ GetStorageInfo func(ctx context.Context, client common.Address) (*StorageInfo, error)

+ type StoreError struct

+ Cause error

+ Endpoint string

+ ProviderID types.ProviderID

+ func (e *StoreError) Error() string

+ func (e *StoreError) Unwrap() error

+ type StoreOptions struct

+ OnProgress func(bytesUploaded int64)

+ PieceCID cid.Cid

+ type StoreResult struct

+ PieceCID cid.Cid

+ Size int64

+ type SubmittedPiece struct

+ PieceCID cid.Cid

+ type TerminateDataSetOptions struct

+ WriteOptions []warmstorage.WriteOption

+ type UploadContext interface

+ Commit func(context.Context, CommitRequest) (*CommitResult, error)

+ PieceURL func(cid.Cid) string

+ PresignForCommit func(context.Context, []PieceInput) ([]byte, error)

+ ProviderID func() types.ProviderID

+ Pull func(context.Context, PullRequest) (*PullResult, error)

+ ServiceURL func() string

+ Store func(context.Context, io.Reader, *StoreOptions) (*StoreResult, error)

+ type UploadOptions struct

+ Copies int

+ DataSetIDs []types.DataSetID

+ DataSetMetadata map[string]string

+ ExcludeProviderIDs []types.ProviderID

+ OnCopyComplete func(providerID types.ProviderID, pieceCID cid.Cid)

+ OnCopyFailed func(providerID types.ProviderID, pieceCID cid.Cid, err error)

+ OnPiecesAdded func(txHash string, providerID types.ProviderID, pieces []SubmittedPiece)

+ OnPiecesConfirmed func(dataSetID types.DataSetID, providerID types.ProviderID, ...)

+ OnProgress func(bytesUploaded int64)

+ OnPullProgress func(providerID types.ProviderID, pieceCID cid.Cid, status PullStatus)

+ OnStored func(providerID types.ProviderID, pieceCID cid.Cid)

+ PieceCID cid.Cid

+ PieceMetadata map[string]string

+ ProviderIDs []types.ProviderID

+ WithCDN *bool

+ type UploadResolver interface

+ ResolveUploadContexts func(context.Context, *UploadOptions) ([]UploadContext, bool, error)

+ SelectReplacement func(context.Context, map[types.ProviderID]struct{}, *UploadOptions) (UploadContext, error)

+ type UploadResult struct

+ Complete bool

+ Copies []CopyResult

+ FailedAttempts []FailedAttempt

+ PieceCID cid.Cid

+ RequestedCopies int

+ Size int64

+ func (r *UploadResult) PartialSuccess() bool

+ func (r *UploadResult) PrimaryDataSetID() (types.DataSetID, bool)

+ func (r *UploadResult) SuccessCount() int

+ func (r *UploadResult) SuccessfulProviderIDs() []types.ProviderID

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