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
}

type CommitKind string

type CommitRejectedError struct {
	Submission CommitSubmission
	Status     CommitStatus
}

type CommitRequest struct {
	Pieces    []PieceInput
	ExtraData []byte // EIP-712 signed payload; nil for the primary (create-or-add path)
	// OnSubmitted is invoked with the original transaction hash immediately
	// after the provider returns a valid submission handle, before confirmation.
	// It may be nil. Direct Commit calls do not recover callback panics.
	OnSubmitted func(txHash string)
}

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
	CurrentDataSetSizeBytes *big.Int
	WithCDN                 bool
}

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

type ContextFactoryOptions struct {
	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 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 CreateDataSetOptions struct {
	// 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 must be non-nil when resuming a submitted create.
	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 DataSetDetailsCatalog interface {
	GetClientDataSetsWithDetails(ctx context.Context, payer common.Address, onlyManaged bool) ([]*warmstorage.EnhancedDataSetInfo, error)
}

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

type DataSetInfo = warmstorage.EnhancedDataSetInfo

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

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

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

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 // when set, delegates to DownloadContext.Download; mutually exclusive with URL
	URL     string          // direct HTTP or HTTPS URL; validated against pieceCID on read completion
}

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

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

type FWSSTerminator interface {
	TerminateDataSet(ctx context.Context, dataSetID sdktypes.BigInt, opts ...warmstorage.WriteOption) (*sdktypes.WriteResult, 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)
}

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 int
	Available int
}

type MultiContextCosts struct {
	RatePerEpoch         *big.Int
	RatePerMonth         *big.Int
	Fees                 UploadFees
	Lockup               UploadLockup
	DepositNeeded        *big.Int
	RequiredLockupPeriod *big.Int
	NeedsFWSSMaxApproval bool
	Ready                bool
}

type MultiCostCalculator interface {
	CalculateMultiContextCosts(ctx context.Context, payer common.Address, dataSizeBytes *big.Int, refs []ContextCostRef, opts MultiCostOptions) (*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
	// PieceCount is the number of pieces added per context. Nil or non-positive
	// values default to one.
	PieceCount *big.Int
	// ExtraRunwayEpochs is additional runway (epochs) on top of the
	// minimum lockup period. Defaults to 0 when unset.
	ExtraRunwayEpochs int64
	// BufferEpochs is the deposit cushion above current lockup usage to
	// cover transaction latency. Zero uses the cost service default
	// (5 epochs).
	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

	// HTTPClient is used for URL-based downloads. nil installs a client with
	// a 24-hour timeout — long enough for multi-GiB transfers over typical
	// storage networks while preventing indefinite hangs. The default client
	// also disables environment-variable proxies to avoid proxy-assisted SSRF
	// bypass. When set, the SDK's built-in SSRF protection is bypassed
	// entirely: the provided Transport is responsible for implementing
	// equivalent safeguards (private-network rejection, DNS-rebind close
	// window, redirect filtering). 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

	// CommitConcurrency caps the number of concurrent on-chain Commit RPCs
	// issued across primary + secondary copies. Values <= 0 select the
	// default of 4. The cap only matters when RequestedCopies exceeds it.
	CommitConcurrency int

	// AllowPrivateNetworks disables the default SSRF protection applied to
	// URL-based Service.Download calls. When false (the default), the
	// built-in HTTP client refuses to dial local, private, multicast,
	// unspecified, or otherwise reserved address ranges and returns
	// ErrPrivateNetwork.
	// Set to true only when you knowingly need to download from a private
	// network (e.g. in-cluster storage). Ignored when HTTPClient is set.
	AllowPrivateNetworks bool

	// DownloadMaxBytes caps the number of bytes a single URL-based
	// Service.Download will return. Zero (the default) disables the cap.
	// Exceeding it 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.TerminateDataSet. Optional.
	DataSetTerminator FWSSTerminator

	// CostCalculator backs Service.CalculateMultiContextCosts and the
	// cost estimation inside Prepare. Optional.
	CostCalculator MultiCostCalculator

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

	// DataSetSizeReader backs the per-dataset size lookup performed by
	// Service.Prepare for existing-dataset contexts. Optional; when
	// nil, Prepare falls back to zero-size estimates. For
	// accurate add-pieces pricing, wire an implementation backed by
	// PDPVerifier.getDataSetLeafCount (leafCount * 32 bytes).
	DataSetSizeReader DataSetSizeReader

	// FWSSDataSetReader is used by explicit data-set resolution to read the
	// on-chain ClientDataSetID
	// and to equip returned contexts with upload-time ended-dataset
	// checks. When nil, those safety nets are skipped.
	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. A typed-nil value is treated as nil.
	Signer       signer.EVMSigner
	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.
	PayerAddress common.Address
}

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
	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)
	SchedulePieceDeletion(ctx context.Context, dataSetID, pieceID types.BigInt, extraData []byte) (common.Hash, 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)
	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 stored with the piece
}

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

	// DataSetLastProven is the wall-clock time of the most recent
	// proof submission for the enclosing data set. Zero time indicates
	// "never proven" or "unknown".
	DataSetLastProven time.Time

	// DataSetNextProofDue is the wall-clock deadline by which the next
	// proof must be submitted. Zero time indicates "unknown".
	DataSetNextProofDue 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

	// InChallengeWindow reports whether the data set is currently inside
	// its challenge window (proof submission is required).
	InChallengeWindow bool

	// HoursUntilChallengeWindow is the number of hours between now and
	// the start of the next challenge window. Zero when inside or past
	// the window.
	HoursUntilChallengeWindow float64

	// IsProofOverdue reports whether the proving deadline has passed
	// without a proof being submitted.
	IsProofOverdue bool
}

type PrepareOptions struct {
	// DataSize is required when Costs is nil, and must be zero when Costs
	// is set. It is the payload size in bytes used for cost calculation.
	DataSize uint64
	// Contexts is the exact set of upload targets used for cost calculation.
	// It is required when Costs is nil.
	Contexts []StorageContext
	// PieceCount is the number of pieces added to each context. Nil or
	// non-positive values default to one.
	PieceCount *big.Int
	// Costs short-circuits cost calculation. When set, no other
	// PrepareOptions fields are accepted.
	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. Zero falls back to
	// the cost service default. It is valid only when Costs is nil and
	// must be non-negative.
	BufferEpochs int64
}

type PrepareResult struct {
	// Costs is the aggregated cost calculation that drove the decision.
	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.
	DepositAmount *big.Int
	// IncludesApproval reports whether the call will also set the FWSS
	// operator to max allowance.
	IncludesApproval bool
	// Execute performs the funding operation. When approval is required,
	// Prepare fixes the approval decision and max lockup period from Costs;
	// 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    []cid.Cid
	From      func(cid.Cid) string // returns the HTTPS URL for a given piece CID
	ExtraData []byte               // EIP-712 signed payload authorising the pull
	// OnProgress is invoked after each piece status update during the pull.
	// It may be nil. Direct Pull calls do not recover callback panics.
	OnProgress func(pieceCID cid.Cid, status PullStatus)
}

type PullResult struct {
	Status PullStatus
	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
	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 {
	Payer            common.Address // EVM address of the paying account
	SPRegistry       PDPProviderSource
	WarmStorage      DataSetCatalog
	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)
	ServiceURL() string
	CDNEnabled() bool
	PieceURL(cid.Cid) string
	Store(context.Context, io.Reader, *StoreOptions) (*StoreResult, error)
	Download(context.Context, cid.Cid) (io.ReadCloser, error)
	PresignForCommit(context.Context, []PieceInput) ([]byte, error)
	Pull(context.Context, PullRequest) (*PullResult, error)
	Commit(context.Context, CommitRequest) (*CommitResult, error)
	Upload(context.Context, io.Reader, *UploadOptions) (*UploadResult, error)
}

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. Direct Store calls do
	// not recover callback panics.
	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 TerminateDataSetOptions struct {
	// WriteOptions are forwarded to warmstorage.TerminateDataSet.
	WriteOptions []warmstorage.WriteOption
}

type TerminateServiceDebtError struct {
	Shortfall *big.Int
}

type TerminateServiceOptions struct {
	// SkipProvider uses the direct FWSS transaction path. The new
	// TerminateService helper still waits for the receipt so it can return
	// EndEpoch. Use DataSetContext.Terminate or Service.TerminateDataSet for the
	// legacy hash-only direct write surface.
	SkipProvider bool
	// WriteOptions are used only when SkipProvider is true.
	WriteOptions []warmstorage.WriteOption
	// DirectWaitTimeout is used only when SkipProvider is true. Zero selects
	// the default wait timeout.
	DirectWaitTimeout time.Duration
	// ProviderWaitTimeout bounds provider relay submission plus status polling.
	// Zero selects the default wait timeout. Negative disables the added timeout
	// and leaves cancellation to ctx.
	ProviderWaitTimeout time.Duration
	// PollInterval is used only for provider-relayed status polling.
	PollInterval time.Duration
	// OnSubmitted is called when a transaction hash becomes known.
	OnSubmitted func(common.Hash)
}

type TerminateServiceResult struct {
	TxHash    *common.Hash
	DataSetID types.BigInt
	EndEpoch  types.Epoch
}

type UploadContextSelection struct {
	Contexts        []StorageContext
	RequestedCopies int
	Complete        bool
}

type UploadFees struct {
	CreateDataSetFee *big.Int
	AddPiecesFee     *big.Int
	Total            *big.Int
}

type UploadLockup struct {
	RateDeltaPerEpoch *big.Int
	StreamingLockup   *big.Int
	LifecycleLockup   *big.Int
	CDNLockup         *big.Int
	CacheMissLockup   *big.Int
	Total             *big.Int
}

type UploadOptions struct {
	// Copies is the number of provider copies to store. Service.Upload requires
	// a positive value. Explicit-context upload methods do not accept it.
	Copies int
	// PieceMetadata is stored with each piece on-chain.
	PieceMetadata map[string]string
	// DataSetMetadata is stored with the data set on first creation.
	DataSetMetadata map[string]string
	// ExcludeProviderIDs skips these providers only during auto-selection.
	ExcludeProviderIDs []types.BigInt
	// 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, different providers may invoke this callback
	// concurrently when commitConcurrency > 1. 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). 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. 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. It may be nil.
	OnPullProgress func(providerID types.BigInt, pieceCID cid.Cid, status PullStatus)
}

type UploadResolver interface {
	ResolveUploadContexts(context.Context, *UploadOptions) ([]StorageContext, bool, error)
	SelectReplacement(context.Context, map[string]types.BigInt, *UploadOptions) (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
}