Part of Stem. This page defines the Offer method of the sync RPC specification. It is how a publish reaches the authority peers, and the only form of push.

The formal schema is attached as the schemaDefinition of this page: a struct {key, input, output} with key pinned to Offer.

Tells a peer that blobs exist for a scope and offers them. The receiver accepts only if its policy wants the scope and the caller can show authority for it, then fetches what it lacks from the caller and validates every blob into the claimed scope. Replaces AnnounceBlobs; there is no longer a push of arbitrary blobs.

Input

field	type	required	meaning
`scope`	data/scope	yes	The scope the offered blobs belong to.
`cids`	list of cid	yes	CIDs the caller holds for the scope.
`proof`	cid	no	A Grant that shows the caller's authority to write into the scope, when the caller is not the space owner.

Output

field	type	required	meaning
`id`	string	yes	Id of this transfer on the receiving peer; the receiver will Fetch wanted blobs from the caller under it.
`wanted`	list of cid	yes	CIDs the receiver will fetch. A CID the receiver already holds is never distinguished from one it refuses: both are simply absent.
`rejected`	list of rpc/type/rejection	yes	Offers refused outright, with reasons the receiver chooses to disclose.

Rules

Acceptance. The receiver accepts an offer when all of the following hold:

its policy wants scope: the most specific matching rule is not ignore, and if the receiver is not an authority peer of the space, the rule is follow or pin;

the sender has authority for the scope: the connection is bound to the space owner, or to an account that proof (and the grants it chains to) gives write on the scope's node, or the offer is for the comments facet and the sender is bound to the comments' author;

cids has at most ten thousand entries.

Otherwise the whole offer is refused with rejected entries whose reason is not-wanted or unauthorized, and nothing else happens.

Wanted. The receiver answers with the CIDs it will fetch. A CID it already holds is simply absent; the receiver never says which, so an offer cannot probe its store.

Fetching back. The receiver opens Fetch to the sender for wanted, under the transfer id. The sender serves them on the basis offer.

Validation. Each fetched blob must validate into the claimed scope: its signer must hold authority there, and it must be a Node of a resource in scope, or a Change, Snapshot, file or authority blob reachable from one. Anything else is rejected with out-of-scope or unauthorized. A blob that passes but still lacks a dependency is stashed and applied when the dependency arrives.

Ledger. One transfer row per offer, with received, indexed, stashed and rejected counts.

Today (HM24)

HM24's Syncing.AnnounceBlobs takes a bare list of up to two hundred thousand CIDs from any connected peer, fetches what it lacks over Bitswap and indexes it; the -syncing.allow-push flag exists but nothing reads it. The client side, Resources.PushResourcesToPeer, computes the related material and allow-lists it for that peer. Stem's Offer requires a claimed scope and proof, applies the policy, and validates every blob into the scope, which is the roadmap's "no more pushing of arbitrary blobs".

Example

{"key": "Offer", "input": {"scope": {"space": {"/": {"bytes": "7QEA…"}}, "node": "bafyrein6a6wfhym6l3vfz5zfkkibj5j6wjibagi3mnbqnspuq2idw52ijb", "depth": "subtree"}, "cids": [{"/": "bafy…31"}, {"/": "bafy…32"}, {"/": "bafy…33"}], "proof": {"/": "bafy…g1"}}}

{"id": "tx-7f3a", "wanted": [{"/": "bafy…32"}, {"/": "bafy…33"}], "rejected": []}

Input

Output

Rules

Today (HM24)

Example

See also