The Pickup Protocol 3.0: delivery-request, delivery, messages-received

Mediation gets messages into a queue. Pickup is how they get out. It is the protocol an agent speaks when it wakes up and asks "did anything arrive while I was gone?"

Why a protocol at all, instead of just sending it

Because the mediator cannot push to an agent that is offline (that is the entire reason the mediator exists) the agent must pull. And because a pull can fail halfway, the protocol needs an acknowledgement step. Without one, a mediator either deletes messages it never successfully delivered, or keeps them forever.

Pickup 3.0 is three messages that solve exactly that.

1 · `delivery-request`, "what do you have for me?"

The agent asks the mediator for queued messages, optionally limited to a batch size. The mediator answers with what it holds for the recipient keys on that agent's keylist.

Batch size is a real decision, not a default to ignore. Small batches mean more round trips; large ones mean a bigger failure unit if the connection drops mid-transfer.

2 · `delivery`, the mediator hands them over

The mediator returns the queued envelopes as attachments. Each is still encrypted end to end between the original sender and you: the mediator is handing over ciphertext it never opened, in the same state it received it.

At this moment the messages exist in two places: the agent has them, and the mediator still does. That redundancy is deliberate, and step 3 is what resolves it.

3 · `messages-received`, the acknowledgement that actually deletes

The agent confirms which message IDs it successfully received. Only then does the mediator drop them.

This is the step people skip, and skipping it has one loud symptom and one quiet one:

Loud: the same messages are delivered again on every pickup, forever.
Quiet: the queue grows without bound, and eventually hits whatever limit the mediator enforces, see queue depth and backpressure.

Acknowledge after you have durably stored the message, not when you have merely received it. Acknowledging on receipt and then crashing before you persist is how a message is lost permanently: the mediator has already deleted its copy, correctly, because you said you had it.

The exchange, in order

agent  --delivery-request-->   mediator     (optional batch limit)
agent  <--delivery------------ mediator     (queued envelopes, still encrypted)
        ...agent decrypts and DURABLY STORES...
agent  --messages-received-->  mediator     (the ids it actually kept)
        ...mediator deletes exactly those...

Checking the endpoint is alive

Pickup runs over the same DIDComm endpoint as everything else, and it validates input before doing anything:

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://relay.solidus.network/didcomm
# 400

400 is the right answer to an empty body: it proves the route exists and is parsing. A 404 means you have the wrong path. This is the cheapest smoke test in the integration.

Live delivery, when you are already connected

If an agent is connected and wants messages pushed as they arrive rather than polled for, Pickup 3.0 also covers live-mode delivery. It is an optimisation on the same model, not a different one: the acknowledgement still governs deletion.

What this tells the mediator about you

Every pickup is a signal: this agent is online, now, from this address, and it had this many messages waiting. Pickup timing is one of the clearest metadata traces a mediator sees, and it is a good approximation of your activity schedule.

Nothing about that is fixable at the protocol layer, and it is enumerated honestly in what a mediator can and cannot see. If your threat model cares about when you are online rather than what you send, read that before this.

Operator-side view

An operator sees deliveries and acknowledgements as events, counts, timings, outcomes, never message contents. How that is exposed without reading bodies is webhooks and delivery logs.

The operator console at relay.solidus.network renders sample data and says so on the page. Any queue or delivery figure you see there is illustrative. Do not cite it as a metric, ours or anyone's.