VRP Addon Attestation Layer — Specification v0.1
Status: Public draft — proposal for discussion (tracks issue #63). Additive by construction: addon rides the open layer vocabulary of Receipt Envelope v1 §3 ("a new trust layer = a new attestations[] entry — no central approval is required"). Nothing in this document changes what a receipt-v1 verifier MUST do today.
Published: 2026-08-01
Repository: https://github.com/vacationrentalprotocol/vrp-spec
Builds on: Receipt Envelope v1 (layer vocabulary §3, per-attestation freshness D2, signature input rule D5, key lifecycle §10), Core VRP v0.1 (signed offers, host JWKS), Booking Proof Chain v0.1 (supersession semantics).
1. Scope
This document defines the semantics of one attestation layer, addon, for add-on services a host sells against an existing offer or stay: late checkout, early check-in, stay extensions, and comparable extras.
The gap it closes: these sales already land in the payment rail and in the booking record, but they are not part of the host-signed, independently verifiable trust chain the way the offer, transport, and payment layers are. An agent that can verify *"this stay costs X"* today cannot verify *"and the 2-hour late checkout the guest bought belongs to that same stay, priced by the same host key."*
2. Layer semantics
| Property | Rule |
|---|---|
layer | Exactly "addon" |
| Cardinality | One attestation per sold add-on. Multiple add-ons on one stay = multiple addon entries in the flat attestations[] array (receipt-v1 §3) |
valid_from / valid_until | MUST be present; evaluated per attestation (D2) |
signature | Compact JWS over the addon artifact (D5), signed by a key published in the same host-node JWKS as the offer layer. Per-layer key separation is permitted (§10 K5) |
source | SHOULD point at the host JWKS used for verification |
ref | MUST carry the correlator of the base subject the add-on attaches to (offer id or booking correlator) |
The host is the merchant of record for the add-on; that is why the addon artifact is signed by the host-node key lineage and not by any platform key.
3. Addon artifact (the signed payload)
| Field | Requirement | Description |
|---|---|---|
addon_type | MUST | Open vocabulary string: late_checkout, early_checkin, extension, … New types need no central approval |
description | SHOULD | Short human-readable label, guest language |
quantity | SHOULD | Number + unit (e.g. { "value": 2, "unit": "hours" }, { "value": 1, "unit": "nights" }) |
price | MUST | { "amount": …, "currency": ISO-4217 } — the amount representation MUST match the one used by the receipt's payment layer for the same stay |
payment_ref | SHOULD | Correlator that reconciles this add-on with the payment layer entry (or PSP object) that charged it |
issued_at | MUST | ISO 8601 date-time of sale |
4. Verification
- A v1 verifier that does not recognize
addonMUST treat it like any other unknown layer: the JWS is verifiable, the semantics are opaque, and the presence of the entry MUST NOT fail the receipt. - An addon-aware verifier verifies the JWS per D5, evaluates freshness per D2, and correlates
refagainst the receipt subject before presenting the add-on as belonging to the stay.
5. Relationship to stay extensions and the proof chain
An extension add-on attests the sale. The resulting change to the stay window itself is a booking-level event and follows Booking Proof Chain v0.1 supersession semantics. When a superseding booking artifact exists, the addon attestation SHOULD reference the same booking correlator so the two chains reconcile. An addon attestation is never mutated; corrections are expressed as new attestations, consistent with the append-only spirit of the flat array.
6. Non-goals
- No new endpoint and no new runtime requirement for nodes or agents.
- No central registry of
addon_typevalues (open vocabulary per §3). - No pricing or policy semantics: how a host prices add-ons stays node-internal and is out of scope here.
- No change to refund mechanics; a refunded add-on is a payment-layer fact.
7. Worked example (non-normative)
{
"layer": "addon",
"valid_from": "2026-08-01T10:00:00Z",
"valid_until": "2026-08-02T10:00:00Z",
"ref": "booking_9f2c…",
"source": "https://example-host.example/.well-known/jwks.json",
"signature": "eyJhbGciOiJFZERTQSIsImtpZCI6Im5vZGUtb2ZmZXItMSJ9…",
"artifact": {
"addon_type": "late_checkout",
"description": "Late checkout until 14:00",
"quantity": { "value": 3, "unit": "hours" },
"price": { "amount": "350.00", "currency": "SEK" },
"payment_ref": "pi_3Qx…",
"issued_at": "2026-08-01T09:58:12Z"
}
}
8. Open questions (for discussion in #63)
- Amount representation: pin minor units, or inherit the node's declared convention from the base offer? (Draft above says: match the
paymentlayer.) - Should receipt-v2 fold well-known
addon_typevalues into a non-normative appendix for interop hints? - Refund expression: is a payment-layer fact enough, or does a
superseded_by-style pointer between addon attestations earn its place?
9. Neutrality
The spec is vendor-neutral. HemmaBo is a reference implementer, not an approval authority. Any node, on any stack, can sign and any party can verify an addon attestation without permission from anyone.
10. License
Specification text: dedicated to the public domain under CC0 1.0.