---
slug: vta/services/drain/list
version: "1.1"
title: VTA Services Drain — List
summary: An operator sees which DIDComm mediators are draining and until when.
status: draft
targetFrameworkVersion: "0.5.0"
category: did-management
keywords:
  - vta
  - services
  - transport
  - did-document
authors:
  - Glenn Gore (https://github.com/stormer78)
parties:
  - role: Operator
    requirement: REQUIRED
    member: issuer
  - role: VTA
    requirement: REQUIRED
    member: recipient
proofRequirement:
  requirement: OPTIONAL
  rationale: A read with no durable state change.
sideEffects:
  level: none
  rationale: "Read only."
exposure:
  discloses: metadata
  actsAsSubject: false
errorCodes: []
related:
  - vta/services/disable
  - vta/services/drain/cancel
---

## Abstract

When a DIDComm mediator is disabled or replaced it enters a **drain**: no longer
advertised, still accepting delivery, until a deadline. **VTA Services Drain —
List** reports which mediators are in that state and when each one ends.

This is the call an operator needs before decommissioning mediator
infrastructure. An empty array means nothing is draining — the ordinary state,
not an error.

## Status of this Document

This is a **draft** *Trust Task specification* per [SPEC.md §5.3](/SPEC.md#53-maturity-levels); the schema **MAY** change without notice.

## Changes from 1.0

* Response `entries[].drainsUntil` → **`drainEndsAt`** (`DrainEntry`). Same type: a required RFC 3339 `date-time`.

The registry's naming-consistency pass gives one concept one name: `vta/_shared/0.1/service` called the instant a drain ends both `drainUntil` and `drainsUntil`. The shared `$ref`s move to `vta/_shared/0.8/service`, which carries the renamed members; nothing else in the payload changes.

Breaking on the wire, released as a `MINOR` increment under [§5.2](/SPEC.md#52-compatibility-rules)'s `draft` allowance. `1.0` remains published.

## Conformance

[[RFC2119]](https://www.rfc-editor.org/rfc/rfc2119) and [[RFC8174]](https://www.rfc-editor.org/rfc/rfc8174) apply.

A conforming **consumer** (the VTA) **MUST** answer only for transports the caller is authorized to see, and **MUST NOT** distinguish 'not configured' from 'not permitted' by latency or message.

## Authorization

Authority is **super-admin**. The advertised half of this answer is public in the
agent's DID document, but the unadvertised half — a transport configured and
disabled — is not, and it discloses operational intent.

A `proof`, where present, establishes that the producer authored the request, not
that it may read.

## Request

```json
{
  "id": "00000007-0000-4000-8000-000000000001",
  "type": "https://trusttasks.org/spec/vta/services/drain/list/1.1",
  "issuer": "did:key:z6MkOperator",
  "recipient": "did:web:vta.example",
  "issuedAt": "2026-08-19T09:10:00Z",
  "payload": {}
}
```

## Response

```json
{
  "id": "00000007-0000-4000-8000-000000000002",
  "type": "https://trusttasks.org/spec/vta/services/drain/list/1.1#response",
  "issuer": "did:web:vta.example",
  "recipient": "did:key:z6MkOperator",
  "issuedAt": "2026-08-19T09:10:01Z",
  "threadId": "00000007-0000-4000-8000-000000000001",
  "payload": {
    "entries": [
      {
        "mediatorDid": "did:web:old-mediator.example",
        "endpoint": "https://old-mediator.example/didcomm",
        "drainEndsAt": "2026-08-19T21:10:01Z"
      }
    ]
  }
}
```

## Security & Privacy

### Data carried

The request carries no filters. The response carries, for each draining DIDComm mediator, its DID, the endpoint where it is still reachable, and `drainEndsAt`.

### Correlation

The advertised half of the answer is public by construction: anyone may fetch the agent's DID document. The unadvertised half — a transport configured and disabled — is not, and discloses operational intent; the spec confines it to super-admins (see Authorization) and imposes no further rule.

### Retention

The task is read only and writes nothing; the spec imposes no retention rule on the exchange.

### Consent/purpose

The operator reads how its own agent is reached. No other party's data is involved, and the spec imposes no further rule.

### Threats

The advertised surface is public by construction — it lives in the agent's DID
document, which anyone may fetch. So the disclosure risk here is not the
*content* of a service entry but the *ability to change it*: an attacker who can
enable a transport can point the agent's traffic at infrastructure they control,
and every client that resolves the DID afterwards will believe it.

That is why every mutation in this family is super-admin only, and why each one
writes a signed log entry rather than flipping a runtime flag. The log is what
makes a change attributable after the fact.

Two failure modes are worth stating plainly:

- **`serverless: true` means nobody else can see the change yet.** The entry is
  written locally but not published; a consumer that reports success without
  surfacing this tells the operator a change is live when no verifier can
  observe it.
- **A drain is not a completed disable.** While `drainEndsAt` is in the future the
  old mediator is still accepting delivery. Reporting "disabled" at that point is
  wrong in the direction that loses messages.
