blob

var Abort = binding.Bind[*AbortArguments, *AbortOK](command.MustParse("/blob/abort"))

Abort (/blob/abort) abandons an in-flight upload of a PARKED blob — allocated but never accepted, whether or not the bytes ever reached the storage node. It is the client-facing abandon verb: an upload ends in exactly one of `/blob/accept` (commit) or an abort that the upload service translates into `/blob/reject` on the storage node holding the allocation.

Served by the upload service (subject = the space). A parked blob has no registration or acceptance to look the storage node up by, so the service recovers it from the receipt chain of the Add task, and forwards a `/blob/reject` of the allocation the add made. A missing or unknown Add fails with MissingCause. Blobs the space has accepted are released via `/blob/remove` instead; if the node refuses the translated reject with BlobAccepted, the service surfaces that named failure in the abort receipt. The abort mutates no upload-service state, so a failed abort is safely retryable.

Idempotent: aborting an unknown or already-rejected blob succeeds. The receipt carries no payload (Unit).

var Accept = binding.Bind[*AcceptArguments, *AcceptOK](command.MustParse("/blob/accept"))

var Add = binding.Bind[*AddArguments, *AddOK](command.MustParse("/blob/add"))

var Allocate = binding.Bind[*AllocateArguments, *AllocateOK](command.MustParse("/blob/allocate"))

var ErrBlobAccepted = errors.New(BlobAcceptedErrorName, "blob has been accepted by the space; release the claim via /blob/remove")

var ErrBlobDigestMismatch = errors.New(BlobDigestMismatchErrorName, "received data does not hash to the reported digest")

ErrBlobDigestMismatch is the failure for a digest mismatch.

var ErrInvalidCause = errors.New(InvalidCauseErrorName, "cause invocation does not match release arguments")

var ErrMissingCause = errors.New(MissingCauseErrorName, "abort requires the /blob/add task that parked the blob")

var ErrUnknownCause = errors.New(UnknownCauseErrorName, "unknown cause invocation")

var ErrUnsupportedDigestCode = errors.New(UnsupportedDigestCodeErrorName, "adding a blob by digest code is supported only for sha2-256")

ErrUnsupportedDigestCode is the failure for an unsupported digest code.

var List = binding.Bind[*ListArguments, *ListOK](command.MustParse("/blob/list"))

var Reject = binding.Bind[*RejectArguments, *RejectOK](command.MustParse("/blob/reject"))

Reject (/blob/reject) is the "don't accept" inverse of `/blob/accept`: it retires a PARKED blob — allocated, never accepted, whether or not its bytes were ever received. A blob's lifecycle on a storage node ends in exactly one of `/blob/accept` (commit: aggregation, location claim, registration) or `/blob/reject` (drop: allocation released, bytes deleted).

Served by storage nodes (subject = the provider DID, invoked by the upload service under its registration delegation, typically translating a client `/blob/abort`). The allocation is named by the `/blob/allocate` task that made it, and the node knows which space and blob it is for. The node drops the allocation and deletes any received bytes once no space holds an allocation or acceptance for them.

A blob that the allocation's space has accepted is refused with BlobAccepted — a space's accepted blobs are released via `/blob/remove`, never rejected. The guard is scoped to that space, not the digest: another space's acceptance of the same bytes must not block the reject — the node simply drops this allocation and retains the bytes for the space that still claims them.

Idempotent: rejecting an unknown or already-rejected blob succeeds. The receipt carries no payload (Unit).

var Release = binding.Bind[*ReleaseArguments, *ReleaseOK](command.MustParse("/blob/release"))

Release (/blob/release) is the claim-release inverse of `/blob/allocate`: it drops one space's reference to a blob on a storage node. It is the upload service's translation of a client `/blob/remove`.

Served by storage nodes (subject = the provider DID, invoked by the upload service under its registration delegation; the space travels in the arguments, matching Allocate/Accept). The node drops the space's allocation, acceptance and location claim. Bytes are physically deleted only when no space claims the digest anymore — and an accepted blob's bytes may additionally be retained until its PDP aggregate root is fully retired on-chain. Physical deletion is always asynchronous: the removal machinery re-verifies zero claims before every destructive step.

The release carries Cause, a link to the originating `/blob/remove` task, and the remove invocation itself MUST ride in the request container so the node can verify the release is legitimate rather than trusting the upload service: the node rejects releases whose cause invocation is absent or not a `/blob/remove` task (UnknownCause), or whose subject/digest do not match the release's Space/Digest (InvalidCause).

Idempotent: releasing an unknown or already-released blob succeeds. The receipt carries no payload (Unit).

var Remove = binding.Bind[*RemoveArguments, *RemoveOK](command.MustParse("/blob/remove"))

Remove (/blob/remove) releases a space's claim on an ACCEPTED blob.

Served by the upload service (subject = the space). The service validates the caller's space authority, recovers every storage node holding the blob (the primary via the registration's receipt chain, plus any non-failed replicas), forwards a `/blob/release` to each, and deregisters the blob last — so the receipt chain to the primary survives for a retry if every forward fails. Forwarding is best-effort: the node-side handler is idempotent and unclaimed allocations expire, so a missed node is reconciled by provider-side hygiene.

Parked (never-accepted) blobs are abandoned via `/blob/abort` instead.

Idempotent: removing an unknown or already-removed blob succeeds. The receipt carries no payload (Unit).

var Replicate = binding.Bind[*ReplicateArguments, *ReplicateOK](command.MustParse("/blob/replicate"))

Replicate is a capability that allows an agent to replicate a Blob into a space identified by did:key in the `with` field.

A Replicate capability may only be invoked after a `/blob/accept` receipt has been receieved, indicating the source node has successfully received the blob. Each Replicate task MUST target a different node, and they MUST NOT target the original upload target.

The Replicate task receipt includes async tasks for `/blob/replica/allocate` and `/blob/replica/transfer`. Successful completion of the `/blob/replica/transfer` task indicates the replication target has transferred and stored the blob. The number of `/blob/replica/allocate` and `/blob/replica/transfer` tasks corresponds directly to number of replicas requested.

var Retrieve = binding.Bind[*RetrieveArguments, *RetrieveOK](command.MustParse("/blob/retrieve"))

Retrieve is the service-level retrieval capability (e.g. used by the indexer to fetch content claims from a Piri node). It is NOT space-scoped: any holder of a valid delegation for `/blob/retrieve` may fetch the blob by digest, regardless of which space it was originally stored under.

For user-facing retrieval that requires an allocation in a specific space see `libforge/commands/content.Retrieve` (the `/content/retrieve` capability).