Help us shape the future of Go! Take the 2026 Go Developer Survey

storagecommit

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultRequestTimeout = 15 * time.Second
	DefaultAttentionAfter = 15 * time.Minute
)
View Source 
const CommitQueueWaitReason = "commit_queue"

CommitQueueWaitReason marks collection waiting for the submission queue.

View Source 
const MaxSubmittedRequestsPerDataSet = 4

MaxSubmittedRequestsPerDataSet bounds the requests of one data set that may be on chain without a known outcome.

View Source 
const ProviderRejectedWaitReason = "provider_rejected"

ProviderRejectedWaitReason is the wait reason of a request backing off after the provider refused it.

Variables

View Source 
var ErrNotEligible = errors.New("storage commit request cannot be sent yet")

ErrNotEligible means a ready request cannot be sent yet: its data set has no room, an older request goes first, it is backing off, or a member is still being transferred.

Functions

func DataSetRefusesWrites 

func DataSetRefusesWrites(err error) bool

DataSetRefusesWrites reports whether err means the data set will not accept a commit, because its storage service ended or its PDP payment did. Both are read from the chain before the provider is contacted.

func ExtraDataNonce 

func ExtraDataNonce(extraData []byte) (sdktypes.BigInt, error)

ExtraDataNonce returns the nonce an add-pieces authorization was signed with. FWSS accepts each nonce once per payer, so it names every submission of the same signed request on chain.

func MaxPieces 

func MaxPieces(dataSetID idtypes.OnChainID, legacyPieceStorageIDLimit uint64, configured int) int

MaxPieces is how many pieces one request to the data set may carry. Data sets below the deployment's compact cutoff keep the legacy piece limit; every request also stays within the add-pieces message size, which the configured maximum is validated against.

func NewRequestID 

func NewRequestID() (string, error)

NewRequestID returns a random identifier for a new commit request.

func ShouldSeal 

func ShouldSeal(in SealInput) (bool, time.Duration)

ShouldSeal reports whether a collecting request is eligible to be signed and, when it should not, how long it may wait before asking again. A zero wait means wait to be woken.

Types

type Advancer 

type Advancer struct {
	// Nonces reads the chain record that proves where a request's pieces landed.
	Nonces         synapse.CommitNonceReader
	RequestTimeout time.Duration
	AttentionAfter time.Duration
	Now            func() time.Time
}

Advancer decides what a request needs next from the provider's answers and the chain. It writes nothing: the caller records every outcome under its task fence.

func (*Advancer) Observe 

func (a *Advancer) Observe(ctx context.Context, c Commit) (observation Observation, observeErr error)

Observe resolves a submitted request. The provider's receipt is only a hint: a request is confirmed by its nonce record, and when the provider cannot answer, disagrees, or rejects it, the chain decides.

func (*Advancer) Prepare 

func (a *Advancer) Prepare(ctx context.Context, c Commit) Prepared

Prepare checks a ready request before it is sent. The nonce is read first: an earlier send may already be on chain, and FWSS rejects a reused nonce.

func (*Advancer) Prove 

func (a *Advancer) Prove(ctx context.Context, c Commit) (Proof, error)

Prove reads the request's FWSS nonce record. FWSS accepts a nonce once per payer and records `(next piece ID << 128) | data set ID`, so a consumed nonce names the piece IDs every send of the request could have produced. Every position is checked against PDPVerifier; a read that fails proves nothing.

func (*Advancer) Send 

func (a *Advancer) Send(ctx context.Context, c Commit, onSubmitted func(storage.CommitSubmission)) SendResult

Send submits the request's signed authorization once. onSubmitted runs when the SDK announces the provider's submission, whatever the call returns.

type AttentionCode 

type AttentionCode string

AttentionCode identifies a submitted request that needs operator review. 

const (
	// AttentionSubmissionMismatch means the request's nonce was consumed by
	// pieces other than the request's own. Nothing more is sent.
	AttentionSubmissionMismatch AttentionCode = "submission_mismatch"
	// AttentionDataSetUnavailable means the request's data set could not be
	// reached while a send of it may still land. Recovery keeps checking.
	AttentionDataSetUnavailable AttentionCode = "data_set_unavailable"
	// AttentionConfirmationTimeout means the request is still unregistered past
	// the attention threshold. Recovery keeps checking it, and sends it again
	// whenever no reply from the provider can settle it.
	AttentionConfirmationTimeout AttentionCode = "confirmation_timeout"
)

func ParseAttentionCode 

func ParseAttentionCode(value string) (AttentionCode, error)

func (AttentionCode) Valid 

func (c AttentionCode) Valid() bool

type AttentionRecord 

type AttentionRecord struct {
	RequestID       string
	TaskID          *int64
	DataSetRowID    int64
	ProviderID      string
	DataSetID       string
	PieceCIDs       []string
	TxHash          *string
	ConfirmedTxHash *string
	SubmitError     string
	Code            AttentionCode
	SubmittedAt     time.Time
	AttentionAt     time.Time
}

AttentionRecord describes one submitted request flagged for operator attention.

type Commit 

type Commit struct {
	Request Request
	// Pieces are the request's piece CIDs in position order.
	Pieces []cid.Cid
	Target synapse.DataSetTarget
}

Commit is one request as the advancer acts on it.

type Confirmation 

type Confirmation struct {
	// TxHash is the request's latest recorded submission, if any.
	TxHash string
	// ConfirmedTxHash is set only when the provider reported the
	// transaction that included the pieces. A request proven by its nonce alone
	// may have landed in a different send.
	ConfirmedTxHash string
	FirstPieceID    sdktypes.BigInt
}

Confirmation is the chain proof of a request with the submission evidence that accompanied it.

type Observation 

type Observation struct {
	Kind         ObserveKind
	Confirmation *Confirmation
	// Attention, when set, is flagged on the request with this observation.
	Attention AttentionCode
	// DropEvidence clears the recorded transaction and status URL: the
	// provider's receipt for them did not describe this request.
	DropEvidence bool
	Cause        error
	Diagnostic   error
}

type ObserveKind 

type ObserveKind uint8

ObserveKind is what a submitted request needs next. 

const (
	// ObservePending means the request needs another observation.
	ObservePending ObserveKind = iota
	// ObserveConfirmed means the chain proves the request.
	ObserveConfirmed
	// ObserveResendDue means nothing of the request is on chain and it can be
	// submitted under its original authorization.
	ObserveResendDue
	// ObserveStop means the request's nonce was consumed by other pieces.
	// Nothing more is sent until an operator recovers it.
	ObserveStop
	// ObserveAbandon means the data set no longer accepts writes and nothing of
	// the request is on chain.
	ObserveAbandon
)

type PrepareOutcome 

type PrepareOutcome uint8

PrepareOutcome is what a ready request may do next. 

const (
	// PrepareSend means nothing of the request is on chain and its data set
	// accepts writes.
	PrepareSend PrepareOutcome = iota
	// PrepareConfirmed means an earlier send already landed.
	PrepareConfirmed
	// PrepareConflict means the request's nonce was consumed by other pieces.
	PrepareConflict
	// PrepareAbandon means the data set no longer accepts writes, so the request
	// can never land.
	PrepareAbandon
	// PrepareRetry means the chain could not be read.
	PrepareRetry
)

type Prepared 

type Prepared struct {
	Outcome PrepareOutcome
	Proof   Proof
	Cause   error
}

type Proof 

type Proof struct {
	Outcome      ProofOutcome
	FirstPieceID sdktypes.BigInt
}

type ProofOutcome 

type ProofOutcome uint8

ProofOutcome is what the chain says about a request's nonce. 

const (
	// ProofUnused means the nonce was not consumed: no send of the request has
	// landed.
	ProofUnused ProofOutcome = iota
	// ProofLanded means the request's pieces are on chain, in order, at
	// consecutive IDs of its data set.
	ProofLanded
	// ProofConflict means the nonce was consumed somewhere other than the
	// request's pieces in its data set, or the request cannot be read.
	ProofConflict
)

type Request 

type Request struct {
	bun.BaseModel `bun:"table:storage_commit_requests,alias:commit_request"`

	RequestID        string             `bun:"request_id,type:text,pk"`
	StorageDataSetID int64              `bun:"storage_data_set_id,notnull"`
	Status           RequestStatus      `bun:"status,type:text,notnull"`
	TaskID           *int64             `bun:"task_id,nullzero"`
	PieceCount       int                `bun:"piece_count,type:integer,notnull"`
	ExtraDataHex     *string            `bun:"extra_data_hex,type:text,nullzero"`
	SealedAt         *time.Time         `bun:"sealed_at,nullzero"`
	FirstSentAt      *time.Time         `bun:"first_sent_at,nullzero"`
	Sends            int                `bun:"sends,type:integer,notnull"`
	SubmittedAt      *time.Time         `bun:"submitted_at,nullzero"`
	LastSentAt       *time.Time         `bun:"last_sent_at,nullzero"`
	TxHash           *string            `bun:"tx_hash,type:text,nullzero"`
	StatusURL        *string            `bun:"status_url,type:text,nullzero"`
	SubmitError      *string            `bun:"submit_error,type:text,nullzero"`
	Refusals         int                `bun:"refusals,type:integer,notnull"`
	RetryAt          *time.Time         `bun:"retry_at,nullzero"`
	FirstPieceID     *idtypes.OnChainID `bun:"first_piece_id,type:text"`
	ConfirmedTxHash  *string            `bun:"confirmed_tx_hash,type:text,nullzero"`
	ConfirmedAt      *time.Time         `bun:"confirmed_at,nullzero"`
	LastError        *string            `bun:"last_error,type:text,nullzero"`
	AttentionCode    *string            `bun:"attention_code,type:text,nullzero"`
	AttentionAt      *time.Time         `bun:"attention_at,nullzero"`
	CreatedAt        time.Time          `bun:"created_at,nullzero,notnull"`
	UpdatedAt        time.Time          `bun:"updated_at,nullzero,notnull"`
	SealRequestedAt  *time.Time         `bun:"seal_requested_at,nullzero"`
}

Request records one signed add-pieces authorization and its submission and confirmation evidence. It outlives the copies it registers.

func (*Request) BeforeAppendModel 

func (r *Request) BeforeAppendModel(_ context.Context, query bun.Query) error

BeforeAppendModel stamps the audit columns on insert. The database has no timestamp default, so every row is written with one encoding instead of two that sort against each other inside the same second.

func (Request) Sent 

func (r Request) Sent() bool

Sent reports whether a send of the request may ever have reached the provider. Its members are then pinned until the request is settled.

type RequestPiece 

type RequestPiece struct {
	bun.BaseModel `bun:"table:storage_commit_request_pieces"`

	ID               int64     `bun:"id,pk,autoincrement,identity"`
	RequestID        string    `bun:"request_id,type:text,notnull"`
	Position         int       `bun:"position,type:integer,notnull"`
	ContentID        int64     `bun:"content_id,notnull"`
	StorageDataSetID int64     `bun:"storage_data_set_id,notnull"`
	PieceCID         string    `bun:"piece_cid,type:text,notnull"`
	CreatedAt        time.Time `bun:"created_at,nullzero,notnull"`
}

RequestPiece names one piece of a sealed request at its position.

func (*RequestPiece) BeforeAppendModel 

func (p *RequestPiece) BeforeAppendModel(_ context.Context, query bun.Query) error

type RequestStatus 

type RequestStatus string

RequestStatus is the lifecycle of one signed add-pieces request. 

const (
	// RequestStatusCollecting gathers transferred copies of one data set. Nothing
	// has been signed, so members can still leave.
	RequestStatusCollecting RequestStatus = "collecting"
	// RequestStatusReady is signed. No send of it can be pending.
	RequestStatusReady RequestStatus = "ready"
	// RequestStatusSubmitted has been sent at least once in this period, and a
	// send may still land.
	RequestStatusSubmitted RequestStatus = "submitted"
	// RequestStatusConfirmed is proven on chain.
	RequestStatusConfirmed RequestStatus = "confirmed"
	// RequestStatusAbandoned can never land.
	RequestStatusAbandoned RequestStatus = "abandoned"
)

func (RequestStatus) Terminal 

func (s RequestStatus) Terminal() bool

Terminal reports whether the request has been settled.

func (RequestStatus) Valid 

func (s RequestStatus) Valid() bool

type SealInput 

type SealInput struct {
	Members int
	// OldestJoinedAt is when the longest-waiting member became ready.
	OldestJoinedAt time.Time
	Now            time.Time
	MaxPieces      int
	MaxWait        time.Duration
	// Draining means the data set takes no new copies.
	Draining        bool
	CachePressure   bool
	ManualRequested bool
}

SealInput is what decides whether a collecting request is eligible to be signed.

type SendKind 

type SendKind uint8

SendKind classifies what one SubmitCommit call left behind. 

const (
	// SendAccepted means the provider returned a submission.
	SendAccepted SendKind = iota
	// SendRefused means the provider answered with a 4xx. Curio answers every
	// add-pieces 4xx before sending that call's transaction.
	SendRefused
	// SendNotSent means the SDK refused the data set before contacting the
	// provider.
	SendNotSent
	// SendUnknown means a transaction may exist.
	SendUnknown
)

type SendResult 

type SendResult struct {
	Kind       SendKind
	Submission *storage.CommitSubmission
	Err        error
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.