---
slug: vta/services/rollback
version: "1.0"
title: VTA Services — Rollback
summary: An operator reverts a transport to its previous settings by writing a new log entry.
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: REQUIRED
  rationale: Changes what the world believes about reaching this agent, exactly as enable and update do.
issuedAtRequirement:
  requirement: REQUIRED
  rationale: A rollback reverts the service to a previous release, so what it discards is decided by when it runs. Replayed, it discards a release deployed since the first execution.
sideEffects:
  level: mutating
  rationale: "Writes a new DID-document log entry restoring earlier settings."
exposure:
  discloses: metadata
  actsAsSubject: false
errorCodes:
  - code: vta/services/rollback:notFound
    meaning: No such transport is configured on this agent.
    retryable: false
  - code: vta/services/rollback:conflict
    meaning: There is no previous state to restore.
    retryable: false
  - code: vta/services/rollback:notAuthorized
    meaning: The caller is not a super-admin.
    retryable: false
related:
  - vta/services/update
  - vta/services/enable
---

## Abstract

**VTA Services — Rollback** reverts a transport to its previous advertised
settings.

It does so by writing a **new** log entry. The did:webvh log is append-only, so
a rollback is a forward step that restores an earlier state — never an erasure
of what happened. Anyone auditing the document afterwards sees the mistake and
the correction, which is the intended behaviour and not a limitation to work
around.

## When there is nothing to write

If the previous state already equals the current one, the rollback writes
nothing and answers `kind: "noOp"` with no `logEntryVersionId`. That is a
**success**: the requested state holds. Reporting it as a failure would be
wrong, and reporting it as an ordinary success would name a log entry that does
not exist — which is why `kind` is required and `logEntryVersionId` is not.

## 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.

## 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** reject a payload whose `config` members do not belong to the named `service`, rather than ignoring the surplus member. It **MUST** write a did:webvh log entry for every accepted change, and **MUST** report `serverless: true` when that entry was not published.

## Authorization

Authority is **super-admin**. Every task in this family edits — or reads — what
the agent tells the world about reaching it, and the ACL has no finer capability
for a subset of transports.

A `proof`, where present, establishes that the producer authored the request. It
is not the authorization; the caller's super-admin role is.

## Request

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

## Response

```json
{
  "id": "00000006-0000-4000-8000-000000000002",
  "type": "https://trusttasks.org/spec/vta/services/rollback/1.0#response",
  "issuer": "did:web:vta.example",
  "recipient": "did:key:z6MkOperator",
  "issuedAt": "2026-08-19T09:10:01Z",
  "threadId": "00000006-0000-4000-8000-000000000001",
  "payload": {
    "result": {
      "kind": "updated",
      "logEntryVersionId": "5-zQmLogEntry",
      "effectiveAt": "2026-08-19T09:10:01Z",
      "vtaDid": "did:webvh:QmAgent:vta.example",
      "serverless": false
    }
  }
}
```

## Security & Privacy

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 `drainUntil` is in the future the
  old mediator is still accepting delivery. Reporting "disabled" at that point is
  wrong in the direction that loses messages.

