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 Cause receipt chain and forwards a `/blob/reject` (Cause itself is not forwarded — it is routing metadata, meaningless to the node). A missing or unknown Cause 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 ErrInvalidCause = errors.New(InvalidCauseErrorName, "cause invocation does not match release arguments")

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

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

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 node drops the space's allocation and deletes any received bytes once no space holds an allocation or acceptance for the digest.

A blob that THE INVOKING SPACE has accepted is refused with BlobAccepted — a space's accepted blobs are released via `/blob/remove`, never rejected. The guard is scoped to the invoking space, not the digest: another space's acceptance of the same bytes must not block the reject — the node simply drops this space's 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).