storage

type Allowances struct {
	Service         common.Address
	IsApproved      bool
	RateAllowance   *big.Int
	LockupAllowance *big.Int
	RateUsed        *big.Int
	LockupUsed      *big.Int
	MaxLockupPeriod *big.Int
}

type CDNRetriever interface {
	DownloadPiece(context.Context, cid.Cid) (io.ReadCloser, error)
}

type CIDMismatchError struct {
	Expected   cid.Cid
	ComputedV1 cid.Cid
	ComputedV2 cid.Cid
}

type CommitError struct {
	ProviderID types.BigInt
	Endpoint   string
	Cause      error
	// PieceCID and Size identify the stored piece.
	PieceCID cid.Cid
	Size     int64
	// FailedAttempts lists every failed attempt, as UploadResult.FailedAttempts
	// would have.
	FailedAttempts []FailedAttempt
}

type CommitKind string

type CommitRejectedError struct {
	ProviderID types.BigInt
	Status     CommitStatus
}

type CommitRequest struct {
	Pieces []PieceInput
	// ExtraData is an EIP-712 signed add-pieces payload. Leave it nil to let the
	// DataSetContext sign the request. Payloads whose encoded add-pieces calldata
	// exceeds pdp.MaxAddPiecesMessageSize are rejected.
	ExtraData []byte
	// OnSubmitted is invoked with an independent runtime snapshot immediately
	// after the provider returns a valid handle, before confirmation. For restart
	// recovery, persist StatusURL together with the target DataSetRef; do not treat
	// the complete CommitSubmission as a persistence schema. It may be nil.
	// Direct calls do not recover callback panics.
	OnSubmitted func(CommitSubmission)
}

type CommitResult struct {
	TransactionID          string         `json:"transactionId"`          // transaction hash from the provider submission
	ConfirmedTransactionID string         `json:"confirmedTransactionId"` // actual on-chain hash, when reported by the provider
	DataSet                DataSetRef     `json:"dataSet"`
	PieceIDs               []types.BigInt `json:"pieceIds"`
	IsNewDataSet           bool           `json:"isNewDataSet"` // true when a new data set was created by this commit
}

type CommitState string

type CommitStatus struct {
	Kind                   CommitKind     `json:"kind"`
	State                  CommitState    `json:"state"`
	TransactionID          string         `json:"transactionId"`
	ConfirmedTransactionID string         `json:"confirmedTransactionId"`
	DataSet                *DataSetRef    `json:"dataSet"`
	PieceIDs               []types.BigInt `json:"pieceIds"`
}

type CommitSubmission struct {
	Kind            CommitKind      `json:"kind"`
	TransactionID   string          `json:"transactionId"`
	StatusURL       string          `json:"statusUrl"`
	ProviderID      types.BigInt    `json:"providerId"`
	Identity        ContextIdentity `json:"identity"`
	DataSet         *DataSetRef     `json:"dataSet"`
	ClientDataSetID *types.BigInt   `json:"clientDataSetId"`
	PieceCIDs       []cid.Cid       `json:"pieceCids"`
}

type ConfirmedPiece struct {
	PieceID  types.BigInt
	PieceCID cid.Cid
}

type ContextCostRef struct {
	DataSetID *types.BigInt
	Provider  Provider
	// CurrentDataSetLeafCount is required and non-negative for an existing
	// data set. Zero means known empty. It is ignored for a new data set.
	CurrentDataSetLeafCount *big.Int
	// CurrentLifecycleReserveBalance is required and non-negative for an
	// existing data set. It is ignored for a new data set.
	CurrentLifecycleReserveBalance *big.Int
	// PendingOneTimePayments is the non-negative operation-fee total already
	// waiting to be paid from an existing data set's reserve. Nil defaults to
	// zero. It is ignored for a new data set.
	PendingOneTimePayments *big.Int
	// PDPEndEpoch is required for an existing data set and must point to zero.
	// It is ignored for a new data set.
	PDPEndEpoch *types.Epoch
	WithCDN     bool
}

type ContextFactory func(Provider, ContextFactoryOptions) (*ProviderContext, error)

type ContextFactoryOptions struct {
	// LegacyPieceStorageIDLimit is the first compact data set ID; zero is unknown.
	LegacyPieceStorageIDLimit uint64
	DataSetMetadata           map[string]string
	WithCDN                   bool
}

type ContextIdentity struct {
	Payer        common.Address `json:"payer"`
	ChainID      types.ChainID  `json:"chainId"`
	RecordKeeper common.Address `json:"recordKeeper"`
}

type ContextOption func(*contextCore)

type ContextResolver interface {
	ResolveProviderContext(context.Context, types.BigInt, NewProviderContextOptions) (*ProviderContext, error)
	ResolveDataSetContext(context.Context, types.BigInt, NewDataSetContextOptions) (*DataSetContext, error)
}

type ContextSelector interface {
	SelectProviderContext(context.Context, SelectProviderContextOptions) (*ProviderContext, error)
	SelectUploadContexts(context.Context, SelectUploadContextsOptions) (*UploadContextSelection, error)
}

type ContextUploadOptions struct {
	// PieceMetadata is validated, signed, and emitted in the FWSS PieceAdded
	// event. FWSS does not persist it in contract state.
	PieceMetadata map[string]string
	// PieceCID, when defined, is a pre-computed PieceCIDv2 of the payload.
	// When set, the provider client skips inline commP calculation; the server
	// still verifies the uploaded bytes match this value.
	PieceCID cid.Cid
	// OnProgress is invoked after each non-empty Read from the upload reader,
	// with the cumulative bytes sent to the provider so far. It may be nil.
	OnProgress func(bytesUploaded int64)
	// OnStored is invoked once the provider has confirmed storage of the piece.
	// It may be nil.
	OnStored func(providerID types.BigInt, pieceCID cid.Cid)
	// OnPiecesAdded is invoked after the on-chain AddPieces transaction is
	// submitted, carrying the transaction hash and submitted pieces. It may be nil.
	OnPiecesAdded func(txHash string, providerID types.BigInt, pieces []SubmittedPiece)
	// OnPiecesConfirmed is invoked after AddPieces is confirmed, carrying the
	// assigned on-chain IDs. It may be nil.
	OnPiecesConfirmed func(dataSetID, providerID types.BigInt, pieces []ConfirmedPiece)
}

type CopyResult struct {
	ProviderID   types.BigInt
	DataSetID    types.BigInt
	PieceID      types.BigInt
	Role         CopyRole
	RetrievalURL string // HTTPS retrieval URL for this piece on the provider.
	IsNewDataSet bool
}

type CopyRole string

type CopyStage string

type CreateAndAddRequest struct {
	Pieces []PieceInput
	// ExtraData is an EIP-712 signed create-and-add payload. Leave it nil to
	// let the ProviderContext sign the request. Payloads whose encoded
	// add-pieces calldata exceeds pdp.MaxAddPiecesMessageSize are rejected.
	ExtraData []byte
	// ClientDataSetID is the caller-owned uint256 used when creating the data
	// set. Nil generates a random ID. When ExtraData is set, the value must
	// match the ID embedded in its create payload.
	ClientDataSetID *types.BigInt
	// OnSubmitted is invoked with an independent runtime snapshot immediately
	// after the provider returns a valid handle, before confirmation. For restart
	// recovery, persist StatusURL and the original ClientDataSetID; do not treat
	// the complete CommitSubmission as a persistence schema. It may be nil.
	// Direct calls do not recover callback panics.
	OnSubmitted func(CommitSubmission)
}

type CreateDataSetOptions struct {
	// ClientDataSetID is the caller-owned uint256 included in the create
	// authorization. Nil generates a random ID. Persist a caller-supplied value
	// before calling CreateDataSet when recovery from an ambiguous provider
	// response is required.
	ClientDataSetID *types.BigInt
	// OnSubmitted is invoked after the create transaction is submitted and
	// before waiting for confirmation. It may be nil.
	OnSubmitted func(CreateDataSetSubmission)
}

type CreateDataSetResult struct {
	TransactionID          string     `json:"transactionId"`
	ConfirmedTransactionID string     `json:"confirmedTransactionId"`
	DataSet                DataSetRef `json:"dataSet"`
}

type CreateDataSetSubmission struct {
	ProviderID      types.BigInt `json:"providerId"`
	TransactionID   string       `json:"transactionId"`
	StatusURL       string       `json:"statusUrl"`
	ClientDataSetID types.BigInt `json:"clientDataSetId"`
}

type DataSetCatalog interface {
	GetApprovedProviderIDs(context.Context, types.ListOptions) ([]types.BigInt, error)
	GetClientDataSets(context.Context, common.Address, types.ListOptions) ([]*warmstorage.DataSetInfo, error)
	GetDataSet(context.Context, types.BigInt) (*warmstorage.DataSetInfo, error)
	GetAllDataSetMetadata(context.Context, types.BigInt) (map[string]string, error)
}

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

type DataSetDetails = warmstorage.EnhancedDataSetInfo

type DataSetDetailsCatalog interface {
	GetClientDataSetsWithDetails(ctx context.Context, payer common.Address, onlyManaged bool) ([]*warmstorage.EnhancedDataSetInfo, error)
}

type DataSetDownloader interface {
	DownloadDataSet(context.Context, types.BigInt, cid.Cid) (io.ReadCloser, error)
}

type DataSetFinder interface {
	FindDataSets(ctx context.Context, payer common.Address, onlyManaged bool) ([]*DataSetDetails, error)
}

type DataSetLeafCountReader interface {
	GetDataSetLeafCount(ctx context.Context, dataSetID sdktypes.BigInt) (*big.Int, error)
}

type DataSetPDPPaymentTerminatedError struct {
	DataSetID   types.BigInt
	PDPEndEpoch types.Epoch
}

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

type DataSetValidator interface {
	ValidateDataSet(ctx context.Context, dataSetID sdktypes.BigInt) error
}

type DownloadContext interface {
	Download(context.Context, cid.Cid) (io.ReadCloser, error)
}

type DownloadError struct {
	URL        string
	StatusCode int   // zero when the failure occurred before receiving a response
	Cause      error // non-nil when the failure has an underlying error (e.g. a network or transport-level error)
}

type DownloadOptions struct {
	Context DownloadContext // delegates to DownloadContext.Download
	URL     string          // direct HTTP or HTTPS URL; validated against pieceCID on read completion
	// DataSetID downloads an owned data set's piece, using its CDN setting.
	// CDN retrieval can succeed even when the provider is inactive.
	DataSetID *types.BigInt
}

type EndorsedProviderSource interface {
	GetEndorsedProviderIDs(context.Context) ([]types.BigInt, error)
}

type EpochReader interface {
	BlockNumber(ctx context.Context) (uint64, error)
}

type FWSSDataSetReader interface {
	GetDataSet(ctx context.Context, dataSetID sdktypes.BigInt) (*warmstorage.DataSetInfo, error)
	FindDataSetByClientDataSetID(ctx context.Context, payer common.Address, clientDataSetID sdktypes.BigInt) (*warmstorage.DataSetInfo, error)
}

type FWSSTerminationOptions struct {
	// WriteOptions carry WarmStorage write settings. Submission overrides
	// WithWait and WithOnSubmitted so it only broadcasts without notification.
	WriteOptions []warmstorage.WriteOption
}

type FWSSTerminator interface {
	TerminateDataSet(ctx context.Context, dataSetID sdktypes.BigInt, opts FWSSTerminationOptions) (*sdktypes.WriteResult, error)
	// WaitForTermination succeeds only after the requested confirmation depth,
	// successful execution, and a termination event matching the configured
	// FWSS address and dataSetID. A returned receipt reached that depth, even
	// alongside an error. Timeout overrides WithWait; confirmations are preserved
	// and submission callbacks are ignored.
	WaitForTermination(ctx context.Context, dataSetID sdktypes.BigInt, hash common.Hash, timeout time.Duration, writeOpts []warmstorage.WriteOption) (*sdktypes.WriteResult, sdktypes.Epoch, error)
}

type FailedAttempt struct {
	ProviderID types.BigInt
	Role       CopyRole
	Stage      CopyStage // pipeline stage where the failure occurred
	Err        error
	Explicit   bool // true when the provider was caller-specified (no auto-retry)
	// Submission is set when the SDK validated and registered the commit
	// handle before this attempt ended. Nil means the handle is unknown, not
	// that the provider rejected the submission; it does not imply retrying is
	// safe. Use StatusURL, and ClientDataSetID for create-and-add, to resume
	// waiting; see Submission recovery in the package documentation.
	Submission *CommitSubmission
}

type FindDataSetsOptions struct {
	// Payer overrides the address configured via Options.PayerAddress.
	// Zero means use the configured default payer.
	Payer common.Address
	// OnlyManaged restricts the returned set to data sets whose
	// record-keeper is the configured FWSS contract.
	OnlyManaged bool
}

type GetStorageInfoOptions struct {
	// Client overrides the default payer. Zero means use the address
	// configured via Options.PayerAddress; if that too is zero the
	// allowances section of the returned StorageInfo will be nil.
	Client common.Address
}

type InsufficientUploadContextsError struct {
	// Requested is the copy count requested from the selector.
	Requested int
	// Available is the number of usable contexts returned with the error.
	Available int
}

type MultiCostCalculator interface {
	CalculateMultiContextCosts(ctx context.Context, payer common.Address, pieceSizes []uint64, refs []costs.MultiContextRef, opts *costs.UploadCostOptions) (*costs.MultiContextCosts, error)
}

type MultiCostOptions struct {
	// EnableCDN forces CDN pricing on every ref (in addition to any
	// per-ref `WithCDN` flag) and governs whether the CDN-fixed lockup
	// is added for new datasets.
	EnableCDN bool
	// ExtraRunwayEpochs is additional runway (epochs) on top of the
	// minimum lockup period. Defaults to 0. Negative values return ErrInvalidArgument.
	ExtraRunwayEpochs int64
	// BufferEpochs is the deposit cushion above current lockup usage to
	// cover transaction latency. Nil uses the cost service default; a pointer
	// to zero disables the buffer. Negative values return ErrInvalidArgument.
	BufferEpochs *int64
}

type NewDataSetContextOptions struct {
	ProviderID *types.BigInt
	WithCDN    *bool
}

type NewProviderContextOptions struct {
	DataSetMetadata map[string]string
	WithCDN         *bool
}

type Options struct {
	// Resolver selects provider contexts for Upload and supplies replacement
	// candidates when a secondary provider fails. A nil resolver is allowed
	// so the Service can still serve DownloadFromContext / download-by-URL
	// calls; Upload then returns a clean validation error.
	Resolver UploadResolver

	// ContextResolver opens explicitly identified storage targets. When nil and
	// Resolver also implements ContextResolver, New reuses Resolver.
	ContextResolver ContextResolver

	// ContextSelector chooses healthy providers and upload targets. When nil and
	// Resolver also implements ContextSelector, New reuses Resolver.
	ContextSelector ContextSelector

	// DataSetDownloader backs downloads identified by data set ID. The root
	// Client supplies ServiceResolver; nil disables this download mode.
	DataSetDownloader DataSetDownloader

	// HTTPClient is used for URL-based downloads and manager-level provider PDP
	// control requests. nil installs clients sharing a safe transport: downloads
	// use a 24-hour timeout for large transfers, while PDP control requests use
	// [pdp.DefaultHTTPTimeout]. The default transport disables environment-variable
	// proxies to avoid proxy-assisted SSRF bypass. When set, the SDK's built-in
	// SSRF protection is bypassed entirely: the provided client is used unchanged
	// and is responsible for equivalent safeguards, redirect policy, and timeouts.
	// AllowPrivateNetworks has no effect in this case.
	HTTPClient *http.Client

	// Source is the application identifier for dataset namespace isolation.
	// Datasets with different Source values are treated as separate
	// namespaces; reuse only occurs within the same Source.
	Source string

	// DefaultWithCDN is the Client-level CDN default applied when an
	// UploadOptions.WithCDN or context-selection WithCDN field is nil.
	// Ignored when the per-operation field is non-nil.
	DefaultWithCDN bool

	// MaxSecondaryAttempts caps the number of provider candidates tried for
	// each secondary copy slot before giving up. Values <= 0 select the
	// default of 5.
	MaxSecondaryAttempts int

	// PullConcurrency caps concurrent secondary presign/pull/replacement
	// workflows within one upload. Values <= 0 select the default of 4.
	// A value of 1 serializes secondary pulls but still overlaps them with commits.
	PullConcurrency int

	// CommitConcurrency caps concurrent direct commits, including confirmation
	// waits, within one upload. Values <= 0 select the default of 4.
	// With UploadBatcher, the coordinator controls submission concurrency instead.
	CommitConcurrency int

	// AllowPrivateNetworks disables the default SSRF protection applied to
	// URL-based Service.Download calls and manager-level provider PDP requests.
	// When false (the default), the built-in HTTP transport refuses to dial local,
	// private, multicast, unspecified, or otherwise reserved address ranges and
	// returns ErrPrivateNetwork. Set to true only for trusted private download or
	// provider infrastructure. Ignored when HTTPClient is set.
	AllowPrivateNetworks bool

	// DownloadMaxBytes caps the number of bytes a single URL-based
	// Service.Download will return. Zero (the default) adds no configured cap;
	// PieceCIDv2 always caps downloads at its raw payload size. Negative values
	// are invalid. Exceeding the effective limit returns
	// ErrMaxBytesExceeded either eagerly (via Content-Length) or at the terminal
	// Read of the returned reader.
	DownloadMaxBytes int64

	// Logger receives internal warnings. nil disables logging.
	Logger *slog.Logger

	// 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 }

	// DataSetFinder backs Service.FindDataSets. Optional; when nil the
	// method returns an ErrUninitialized-wrapped error.
	DataSetFinder DataSetFinder

	// StorageInfoReader backs Service.GetStorageInfo. Optional.
	StorageInfoReader StorageInfoReader

	// DataSetTerminator backs Service.TerminateService with SkipProvider enabled.
	// Optional; the root SDK client assembles the built-in WarmStorage adapter.
	DataSetTerminator FWSSTerminator

	// CostCalculator backs Service.CalculateMultiContextCosts and the
	// cost estimation inside Prepare. Optional; the root SDK client supplies
	// the built-in costs.Service.
	CostCalculator MultiCostCalculator

	// PaymentsFunder backs PrepareTransaction.Execute. Optional.
	PaymentsFunder PaymentsFunder

	// DataSetLeafCountReader backs Service.Prepare for existing-dataset
	// contexts. It is required together with FWSSDataSetReader for that
	// calculation path; missing configuration returns ErrUninitialized.
	// New-dataset and precomputed-cost paths do not need it. The root SDK client
	// supplies its built-in PDPVerifier adapter.
	DataSetLeafCountReader DataSetLeafCountReader

	// FWSSDataSetReader reads existing data-set state for Prepare, reads the
	// on-chain ClientDataSetID during explicit data-set resolution, and checks
	// existing data sets before uploads. A custom context resolver must
	// separately pass the same reader to its contexts to support
	// ProviderContext.FindDataSetByClientDataSetID. When nil, these service-level
	// reads are unavailable.
	FWSSDataSetReader FWSSDataSetReader

	// ProviderResolver resolves provider endpoints for manager-level
	// provider-relayed termination. Optional.
	ProviderResolver ProviderResolver

	// PaymentStateReader and EpochReader back the provider-relayed termination
	// debt pre-check. Optional.
	PaymentStateReader PaymentStateReader
	EpochReader        EpochReader
	PaymentToken       common.Address

	// Signer signs EIP-712 authorizations for manager-level provider-relayed
	// termination. It may differ from PayerAddress when the payer has authorized
	// a delegated signer. It is independent from the signer attached to contexts
	// returned by Resolver. A typed-nil value is treated as nil.
	Signer       signer.StorageSigner
	ChainID      types.ChainID
	RecordKeeper common.Address

	// PayerAddress is the payer/client identity used by manager-level helpers
	// and validated against every StorageContext. It may differ from Signer.
	// When zero, New derives it from a non-nil Signer. Set it explicitly when a
	// delegated Signer authorizes operations for a different payer.
	PayerAddress common.Address

	// UploadBatcher batches commits made by high-level Upload and
	// UploadToContexts calls. Accepted work uses the batcher's lifecycle rather
	// than the individual Upload context. The caller retains ownership and must
	// close the batcher separately.
	UploadBatcher *UploadBatcher
}

type PDPConfigReader interface {
	GetPDPConfig(ctx context.Context) (*warmstorage.PDPConfig, error)
}

type PDPProviderClient interface {
	UploadPieceStreaming(context.Context, io.Reader, pdp.UploadPieceStreamingOptions) (*pdp.UploadStreamingResult, error)
	DownloadPiece(context.Context, cid.Cid) (io.ReadCloser, int64, error)
	WaitForPieceParked(context.Context, cid.Cid, time.Duration) error
	PullPieces(context.Context, pdp.PullRequest) (*pdp.PullResult, error)
	WaitForPullComplete(context.Context, pdp.PullRequest, time.Duration, func(*pdp.PullResult)) (*pdp.PullResult, error)
	AddPieces(context.Context, types.BigInt, []pdp.AddPieceInput, []byte) (*pdp.AddPiecesResult, error)
	GetAddPiecesStatus(context.Context, string) (*pdp.AddPiecesStatus, error)
	WaitForPiecesAdded(context.Context, string, time.Duration) (*pdp.AddPiecesStatus, error)
	CreateDataSet(context.Context, common.Address, []byte) (*pdp.CreateDataSetResult, error)
	GetDataSetCreationStatus(context.Context, string) (*pdp.CreateDataSetStatus, error)
	WaitForDataSetCreated(context.Context, string, time.Duration) (*pdp.CreateDataSetStatus, error)
	CreateDataSetAndAddPieces(context.Context, common.Address, []pdp.AddPieceInput, []byte) (*pdp.CreateDataSetResult, error)
	GetCreateDataSetAndAddPiecesStatus(context.Context, string) (*pdp.CreateAndAddPiecesStatus, error)
	WaitForCreateDataSetAndAddPieces(context.Context, string, time.Duration) (*pdp.AddPiecesStatus, error)
	SchedulePieceDeletions(ctx context.Context, dataSetID types.BigInt, pieceIDs []types.BigInt, extraData []byte) (common.Hash, error)
	TerminateService(context.Context, pdp.TerminateServiceRequest) (*pdp.TerminateServiceResult, error)
	// Waiting errors return the last status read, if any.
	WaitForTerminateService(context.Context, types.BigInt, time.Duration, func(common.Hash), ...pdp.WaitForTerminateServiceOption) (*pdp.TerminateServiceStatus, error)
}

type PDPProviderSource interface {
	GetPDPProvider(context.Context, types.BigInt) (*spregistry.PDPProvider, error)
	SelectActivePDPProviders(context.Context, spregistry.ProviderFilter) ([]spregistry.PDPProvider, error)
}

type PDPVerifierReader interface {
	FindPieceIdsByCid(ctx context.Context, dataSetID sdktypes.BigInt, pieceCID cid.Cid, start, limit uint64) ([]sdktypes.BigInt, error)
	FindPieceIDsByCIDs(ctx context.Context, dataSetID sdktypes.BigInt, pieceCIDs []cid.Cid) ([][]sdktypes.BigInt, error)
	GetScheduledRemovals(ctx context.Context, dataSetID sdktypes.BigInt) ([]sdktypes.BigInt, error)
	GetNextChallengeEpoch(ctx context.Context, dataSetID sdktypes.BigInt) (*big.Int, error)
	BlockNumber(ctx context.Context) (uint64, error)
}

type PaymentStateReader interface {
	AccountInfo(ctx context.Context, token, owner common.Address) (*payments.AccountState, error)
}

type PaymentsFunder interface {
	FundSync(ctx context.Context, amount *big.Int, opts ...payments.WriteOption) (*sdktypes.WriteResult, error)
}

type PieceInput struct {
	PieceCID      cid.Cid
	PieceMetadata map[string]string // optional key-value metadata emitted in the FWSS PieceAdded event
}

type PieceStatus struct {
	// Exists reports whether the piece is currently present in the data set.
	Exists bool

	// PieceID is the piece's on-chain numeric id. Only meaningful when
	// Exists is true.
	PieceID types.BigInt

	// DataSetNextChallengeAt is the time of the scheduled challenge epoch,
	// which may be in the past. Zero time indicates unavailable timing.
	DataSetNextChallengeAt time.Time

	// DataSetEstimatedProofDeadline adds the configured window length to the
	// challenge epoch. It need not equal the contract's actual deadline.
	// Zero time indicates unavailable timing.
	DataSetEstimatedProofDeadline time.Time

	// RetrievalURL is the HTTPS URL at which the piece can be retrieved
	// from the provider. Empty when provider info is not available.
	RetrievalURL string

	// InEstimatedChallengeWindow reports whether the head epoch lies in the
	// estimated interval [challenge epoch, estimated deadline). False also
	// covers unavailable estimates and does not establish data-set health.
	InEstimatedChallengeWindow bool

	// HoursUntilNextChallenge is the nonnegative epoch difference in hours.
	// Zero also covers an unavailable challenge schedule.
	HoursUntilNextChallenge float64

	// EstimatedProofDeadlinePassed reports whether the head epoch has reached
	// the estimated deadline. False also covers unavailable estimates.
	EstimatedProofDeadlinePassed bool
}

type PrepareOptions struct {
	// PieceSizes contains the raw payload size of each piece, copied to every
	// context. Each size must be between chain.MinUploadSize and
	// chain.MaxUploadSize. Required when Costs is nil; must be empty otherwise.
	PieceSizes []uint64
	// Contexts is the exact set of upload targets used for cost calculation.
	// It is required when Costs is nil.
	Contexts []StorageContext
	// Costs short-circuits cost calculation. When set, no other
	// PrepareOptions fields are accepted.
	Costs *costs.MultiContextCosts
	// ExtraRunwayEpochs is additional runway (epochs) above the
	// minimum lockup period passed through to the cost calculator. It is
	// valid only when Costs is nil and must be non-negative.
	ExtraRunwayEpochs int64
	// BufferEpochs is the deposit cushion above current lockup usage
	// used to absorb transaction-latency epochs. Nil uses the cost service
	// default; a pointer to zero disables the buffer. It is valid only when
	// Costs is nil. Negative values return ErrInvalidArgument.
	BufferEpochs *int64
}

type PrepareResult struct {
	// Costs is the aggregated cost calculation that drove the decision.
	Costs *costs.MultiContextCosts
	// Transaction is non-nil only when funding is required (Ready=false).
	Transaction *PrepareTransaction
}

type PrepareTransaction struct {
	// DepositAmount is the USDFC amount that will be moved into the
	// payments account. It is a copy; modifying it does not change what
	// Execute sends.
	DepositAmount *big.Int
	// IncludesApproval reports whether the call will also set the FWSS
	// operator to max allowance.
	IncludesApproval bool
	// Execute performs the funding operation. Prepare fixes the deposit
	// amount, approval decision, and max lockup period when it returns; later
	// changes to DepositAmount, PrepareResult.Costs, or PrepareOptions.Costs
	// do not affect Execute. Caller-provided payments.WriteOption values
	// should be limited to write controls such as wait, confirmations, or
	// precheck behavior.
	Execute func(ctx context.Context, opts ...payments.WriteOption) (*types.WriteResult, error)
}

type PricePerTiB struct {
	PerMonth *big.Int
	PerDay   *big.Int
	PerEpoch *big.Int
}

type PricingInfo struct {
	NoCDN        PricePerTiB
	WithCDN      PricePerTiB
	TokenAddress common.Address
	TokenSymbol  string
	PriceList    *warmstorage.PriceList
}

type Provider struct {
	ID              types.BigInt   // provider ID from SPRegistry
	ServiceURL      string         // base URL of the provider's PDP HTTP API
	ServiceProvider common.Address // provider's EVM address
	Payee           common.Address // address that receives payments
}

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

type ProviderResolver interface {
	ResolveProvider(ctx context.Context, providerID sdktypes.BigInt) (Provider, error)
}

type PullPieceResult struct {
	PieceCID cid.Cid
	Status   PullStatus
}

type PullRequest struct {
	// Pieces must be PieceCIDv2 values whose raw sizes are between
	// chain.MinUploadSize and chain.MaxUploadSize.
	Pieces []cid.Cid
	From   func(cid.Cid) string // returns the HTTPS URL for a given piece CID
	// ExtraData is the required EIP-712 signed payload authorising the pull,
	// usually from PresignForCommit. Oversized payloads are rejected before
	// submission.
	ExtraData []byte
	// OnProgress is invoked for each piece status in every provider response.
	// It may be nil. Direct Pull and SubmitPull calls do not recover callback
	// panics.
	OnProgress func(pieceCID cid.Cid, status PullStatus)
}

type PullResult struct {
	// Status is the provider's overall status. In a SubmitPull result, a
	// complete status does not guarantee that every piece completed; check
	// each entry in Pieces. Pull returns an error in that case.
	Status PullStatus
	// Pieces lists every piece status the provider reports.
	Pieces []PullPieceResult
}

type PullStatus string

type SelectProviderContextOptions struct {
	ExcludeProviderIDs []types.BigInt
	DataSetMetadata    map[string]string
	WithCDN            *bool
}

type SelectUploadContextsOptions struct {
	Copies             int
	ExcludeProviderIDs []types.BigInt
	DataSetMetadata    map[string]string
	// AllowUnendorsedPrimary selects the primary from the full approved-provider
	// pool without an endorsement read. The zero value requires endorsement.
	AllowUnendorsedPrimary bool
	WithCDN                *bool
}

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

type ServiceParameters struct {
	EpochsPerMonth int64
	EpochsPerDay   int64
	EpochDuration  int64 // seconds per epoch
	MinUploadSize  int64
	MaxUploadSize  int64
}

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

type ServiceResolverOptions struct {
	// LegacyPieceStorageIDLimit enables compact-first reuse for this deployment.
	// Zero preserves the existing layout-independent selection order.
	LegacyPieceStorageIDLimit uint64
	// Payer is the EVM address assigned to contexts created by this resolver.
	// Set it to the paying account, not a delegated Storage signer address.
	Payer      common.Address
	SPRegistry PDPProviderSource
	// Endorsements is required only when automatic upload selection uses its
	// default endorsed-primary policy. It may be nil when callers always set
	// AllowUnendorsedPrimary or use explicit provider contexts.
	Endorsements EndorsedProviderSource
	WarmStorage  DataSetCatalog
	// CDNRetriever retrieves pieces for Payer without requiring an active
	// provider. nil limits data-set downloads to active providers.
	CDNRetriever     CDNRetriever
	DataSetValidator DataSetValidator
	DataSetDetails   DataSetDetailsCatalog
	// ProviderPing checks one automatically selected provider endpoint. The
	// resolver may call it concurrently for up to 16 candidates per selection;
	// concurrent selections have independent limits. Each call receives a
	// context whose deadline is no later than eight seconds; a shorter parent
	// deadline takes precedence. Implementations must be safe for concurrent use
	// and honor the context. nil uses [pdp.Client.Ping] with up to two retries for
	// transient failures.
	ProviderPing func(context.Context, string) error
	NewContext   ContextFactory // called per-provider to construct an upload context
}

type StorageContext interface {
	ContextIdentity() ContextIdentity
	ProviderID() types.BigInt
	GetProviderInfo() Provider
	DataSetRef() (DataSetRef, bool)
	// DataSetMetadata returns an independent copy of the target metadata.
	DataSetMetadata() map[string]string
	ServiceURL() string
	CDNEnabled() bool
	PieceURL(cid.Cid) string
	Store(context.Context, io.Reader, *StoreOptions) (*StoreResult, error)
	Download(context.Context, cid.Cid) (io.ReadCloser, error)
	// contains filtered or unexported methods
}

type StorageInfo struct {
	Pricing           PricingInfo
	Providers         []spregistry.PDPProvider
	ServiceParameters ServiceParameters
	Allowances        *Allowances
}

type StorageInfoReader interface {
	GetStorageInfo(ctx context.Context, client common.Address) (*StorageInfo, error)
}

type StoreError struct {
	ProviderID types.BigInt
	Endpoint   string
	Cause      error
}

type StoreOptions struct {
	// PieceCID, when defined, is a pre-computed PieceCIDv2 of the payload.
	// When set, the client skips inline commP calculation; the server still
	// verifies the uploaded bytes match this value.
	PieceCID cid.Cid
	// OnProgress is invoked after each non-empty Read from the reader, with
	// the cumulative bytes sent so far. It may be nil. It can run on the HTTP
	// transport goroutine; a panic aborts the upload and is re-raised with the
	// same value on the goroutine that called Store. The PDP client logs the
	// original stack at Error level when it has a logger.
	OnProgress func(bytesUploaded int64)
}

type StoreResult struct {
	PieceCID cid.Cid // PieceCIDv2 of the stored data
	Size     int64   // raw (unpadded) byte count
}

type SubmittedPiece struct {
	PieceCID cid.Cid
}

type TerminateServiceDebtError struct {
	Shortfall *big.Int
}

type TerminateServiceError struct {
	Stage      TerminateServiceStage
	Submission *TerminateServiceSubmission
	Receipt    *ethtypes.Receipt
	Cause      error
}

type TerminateServiceOptions struct {
	// SkipProvider broadcasts through FWSS. The service and its payments
	// continue until EndEpoch. The default provider path requires settlement.
	SkipProvider bool
	// WriteOptions apply only to direct submission and receipt waiting.
	// WithWait and WithOnSubmitted are overridden; WithConfirmations is kept.
	WriteOptions []warmstorage.WriteOption
	// DirectWaitTimeout bounds direct receipt waiting. A non-positive value
	// selects five minutes. SubmitTerminateService does not wait for a receipt.
	DirectWaitTimeout time.Duration
	// ProviderWaitTimeout bounds provider submission and, for TerminateService,
	// polling and reconciliation together. Zero selects five minutes; negative
	// adds no deadline beyond ctx.
	ProviderWaitTimeout time.Duration
	// PollInterval applies only to provider polling, not submission.
	PollInterval time.Duration
	// OnSubmitted receives an independent handle synchronously after positive
	// acknowledgement and before waiting. It does not indicate confirmation.
	// Errors also preserve recovery information; callback panics propagate.
	OnSubmitted func(TerminateServiceSubmission)
}

type TerminateServiceResult struct {
	// TxHash is the original transaction hash when available.
	TxHash *common.Hash
	// ConfirmedTxHash is the observed on-chain hash after any replacement.
	// Prefer it for receipt lookups when available; otherwise use TxHash.
	ConfirmedTxHash *common.Hash
	DataSetID       types.BigInt
	// EndEpoch is when service and payments end, not a data deletion time.
	EndEpoch types.Epoch
}

type TerminateServiceStage string

type TerminateServiceSubmission struct {
	DataSetID              types.BigInt `json:"dataSetId"`
	Direct                 bool         `json:"direct"`
	ProviderID             types.BigInt `json:"providerId"`
	Accepted               bool         `json:"accepted"`
	Queued                 bool         `json:"queued"`
	TransactionID          string       `json:"transactionId"`
	ConfirmedTransactionID string       `json:"confirmedTransactionId"`
}

type TerminateServiceWaitOptions struct {
	// Timeout bounds observation, including provider resolution and any chain
	// reconciliation. A non-positive value selects five minutes.
	Timeout time.Duration
	// PollInterval applies only to provider-relayed status polling.
	PollInterval time.Duration
	// WriteOptions apply only to direct receipt waiting. Timeout overrides
	// WithWait, and WithOnSubmitted is ignored. WithConfirmations is preserved.
	WriteOptions []warmstorage.WriteOption
}

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

type UploadBatcherOption func(*uploadBatcherConfig)

type UploadBatcherOptions struct {
	Identity ContextIdentity
	Signer   signer.StorageSigner
}

type UploadCommitTimeoutError struct {
	Submission CommitSubmission
}

type UploadContextSelection struct {
	// Contexts contains unique targets in primary-to-secondary order.
	Contexts []StorageContext
	// RequestedCopies is the requested copy count passed to the selector.
	RequestedCopies int
	// Complete reports whether Contexts contains exactly RequestedCopies targets.
	Complete bool
}

type UploadOptions struct {
	// Copies is the number of provider copies to store. It must be positive.
	Copies int
	// PieceMetadata is validated, signed, and emitted in the FWSS PieceAdded
	// event. FWSS does not persist it in contract state.
	PieceMetadata map[string]string
	// DataSetMetadata is stored with the data set on first creation.
	DataSetMetadata map[string]string
	// ExcludeProviderIDs skips these providers during automatic selection and
	// replacement.
	ExcludeProviderIDs []types.BigInt
	// AllowUnendorsedPrimary relaxes automatic primary selection to the complete
	// approved-provider pool and skips the endorsement query. The zero value keeps
	// strict endorsed-primary selection.
	AllowUnendorsedPrimary bool
	// WithCDN is tri-state: nil inherits the Client-level default
	// configured via synapse.WithCDN; non-nil explicitly overrides
	// for this upload. Declare a local variable to take its address:
	//
	//	b := true
	//	opts := &storage.UploadOptions{WithCDN: &b}
	WithCDN *bool
	// PieceCID, when defined, is a pre-computed PieceCIDv2 of the payload.
	// When set, the primary provider client skips inline commP calculation;
	// the server still verifies the uploaded bytes match this value.
	PieceCID cid.Cid
	// OnProgress is invoked after each non-empty Read from the upload
	// reader, with the cumulative bytes sent to the primary provider so
	// far. It may be nil.
	OnProgress func(bytesUploaded int64)
	// OnStored is invoked once the primary provider has confirmed storage of
	// the piece. It may be nil.
	OnStored func(providerID types.BigInt, pieceCID cid.Cid)
	// OnPiecesAdded is invoked after the on-chain AddPieces transaction is
	// submitted for a provider (primary or secondary), carrying the transaction
	// hash and the batch of pieces included in that transaction. During
	// Service.Upload, it may overlap other providers' submission and secondary
	// callbacks. It may be nil.
	OnPiecesAdded func(txHash string, providerID types.BigInt, pieces []SubmittedPiece)
	// OnPiecesConfirmed is invoked after the on-chain AddPieces transaction is
	// confirmed (CommitResult received) for a provider, carrying the assigned
	// on-chain IDs for each piece. During Service.Upload, this callback is
	// invoked sequentially after all commit workers finish. It may be nil.
	OnPiecesConfirmed func(dataSetID, providerID types.BigInt, pieces []ConfirmedPiece)
	// OnCopyComplete is invoked once a secondary provider's SP-to-SP pull
	// completes successfully. It is not fired for the primary (which stores
	// directly). Different providers may invoke it concurrently. It may be nil.
	OnCopyComplete func(providerID types.BigInt, pieceCID cid.Cid)
	// OnCopyFailed is invoked when a secondary provider's SP-to-SP copy
	// attempt fails. Presign failures are not copy attempts and still surface
	// only through FailedAttempts with CopyStagePresign. Primary store/commit
	// failures likewise surface through the Upload return value and
	// FailedAttempts. Different providers may invoke it concurrently. It may be nil.
	OnCopyFailed func(providerID types.BigInt, pieceCID cid.Cid, err error)
	// OnPullProgress is invoked for each piece status update during a
	// secondary-provider pull. Different providers may invoke it concurrently.
	// It may be nil.
	OnPullProgress func(providerID types.BigInt, pieceCID cid.Cid, status PullStatus)
}

type UploadResolver interface {
	// ResolveUploadContexts selects the initial targets for one automatic upload.
	ResolveUploadContexts(context.Context, SelectUploadContextsOptions) ([]StorageContext, error)
	// SelectReplacement selects one replacement target. ExcludeProviderIDs is the
	// deduplicated union of caller exclusions and every provider already selected
	// or attempted by the upload.
	SelectReplacement(context.Context, SelectProviderContextOptions) (StorageContext, error)
}

type UploadResult struct {
	PieceCID        cid.Cid // PieceCIDv2 of the stored data
	Size            int64   // raw (unpadded) byte count
	RequestedCopies int
	// Complete is true when all RequestedCopies were committed on-chain.
	// Equivalent to len(Copies) >= RequestedCopies.
	Complete       bool
	Copies         []CopyResult
	FailedAttempts []FailedAttempt
}

type UploadToContextsOptions struct {
	// PieceMetadata is validated, signed, and emitted in the FWSS PieceAdded
	// event. FWSS does not persist it in contract state.
	PieceMetadata map[string]string
	// PieceCID, when defined, is a pre-computed PieceCIDv2 of the payload.
	// When set, the primary provider client skips inline commP calculation;
	// the server still verifies the uploaded bytes match this value.
	PieceCID cid.Cid
	// OnProgress is invoked after each non-empty Read from the upload reader,
	// with the cumulative bytes sent to the primary provider so far. It may be nil.
	OnProgress func(bytesUploaded int64)
	// OnStored is invoked once the primary provider has confirmed storage of
	// the piece. It may be nil.
	OnStored func(providerID types.BigInt, pieceCID cid.Cid)
	// OnPiecesAdded is invoked after the on-chain AddPieces transaction is
	// submitted for a provider, carrying the transaction hash and submitted pieces.
	// It may overlap other providers' submission and secondary callbacks.
	// It may be nil.
	OnPiecesAdded func(txHash string, providerID types.BigInt, pieces []SubmittedPiece)
	// OnPiecesConfirmed is invoked after AddPieces is confirmed for a provider,
	// carrying the assigned on-chain IDs. It runs sequentially in target order
	// after all upload workers finish, unless canceled. It may be nil.
	OnPiecesConfirmed func(dataSetID, providerID types.BigInt, pieces []ConfirmedPiece)
	// OnCopyComplete is invoked once a secondary provider's SP-to-SP pull
	// completes successfully. It is not fired for the primary. Different
	// providers may invoke it concurrently. It may be nil.
	OnCopyComplete func(providerID types.BigInt, pieceCID cid.Cid)
	// OnCopyFailed is invoked when a secondary provider's SP-to-SP copy attempt
	// fails. Presign and commit failures are reported through FailedAttempts.
	// Different providers may invoke it concurrently. It may be nil.
	OnCopyFailed func(providerID types.BigInt, pieceCID cid.Cid, err error)
	// OnPullProgress is invoked for each piece status update during a
	// secondary-provider pull. Different providers may invoke it concurrently.
	// It may be nil.
	OnPullProgress func(providerID types.BigInt, pieceCID cid.Cid, status PullStatus)
}