Specification · Markdown source · Edit on GitHub · CC0 1.0

VRP Transparency Log — Specification v0.1

Status: Draft (pre-publication)

Published: 2026-06-13

Updated: 2026-07-04 — receipt leaves (vrp_receipt), leaf hashing rule, operator key discovery, STH archival, node read-through proxy, honest guarantee wording (issue #60-adjacent; per-booking inclusion proofs)

Canonical context: https://vacationrentalprotocol.com/contexts/v1

Repository: https://github.com/vacationrentalprotocol/vrp-spec

1. Scope

VRP Transparency Log v0.1 defines an optional, append-only, publicly verifiable log for VRP artifacts — portable attestations and signed verified-stay-offer references — so that trust history becomes non-repudiable and tamper-evident.

A transparency log proves two things and nothing more:

  1. Inclusion — a given artifact was recorded in the log.
  2. Append-only consistency — the log has only grown; nothing was silently rewritten or removed, not by the host, not by the log operator, not by HemmaBo.

This specification is an open standard layer on top of VRP. It does not define an OTA, a marketplace, a booking intermediary, a central issuer, a required registry, a ranking engine, a trust score, an accreditation program, or a certification company. A log operator is an auditor of records, never an authority over truth.

This layer is the no-gatekeeper alternative to an accredited certification authority: it provides institution-grade auditability of trust history without anyone needing to approve, accredit, or certify a node before its attestations can be trusted.

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174 when they appear in all capitals.

2. References

VRP Transparency Log v0.1 adapts established, proven transparency patterns:

It composes with the existing VRP layers:

3. Design Principles (no-gatekeeper)

These principles are normative and exist to prevent the transparency log from becoming the central authority that core VRP and VRP Portable Attestations explicitly reject.

  1. Optional. A VRP attestation or signed offer MUST remain fully verifiable standalone — issuer did:web document plus Ed25519 signature — without any transparency log. Log inclusion MUST NOT be a precondition for verification.
  2. Multi-operator. Anyone MAY operate a VRP transparency log. There MUST NOT be a single canonical log. HemmaBo MAY operate a reference log; the specification MUST NOT require HemmaBo's log, or any specific log, to exist or be consulted.
  3. Additive auditability. A verifier MAY require log inclusion as its own trust policy. The specification MUST NOT mandate it. Absence from any log MUST NOT, by itself, make a valid attestation or offer invalid.
  4. Auditor, not authority. A log operator is not an issuer, certifier, scorer, accreditor, or trust authority. Inclusion in a log MUST NOT be interpreted as approval, certification, or a trust score for the logged claim. A log records that an artifact existed at a time and that the record is append-only — never that the claim is endorsed.

4. Log Data Model

A VRP transparency log is a Merkle tree of leaves over VRP artifact hashes.

A log leaf SHOULD contain:

Registered artifact types:

A leaf MUST NOT contain the cleartext artifact, credential subject fields, or any guest data. Only the hash of the signed envelope is logged. This preserves the data-minimization guarantees of VRP Portable Attestations (Section 9).

4.1 Leaf hashing rule (normative)

For every JWS artifact type, artifact_hash MUST be computed over the exact compact JWS string as issued — the ASCII bytes of header.payload.signature exactly as they left the signer.

This is the same signature-input discipline as Receipt v1 D5 (verify over the JWS bytes as received, never re-canonicalize), applied to hashing. JSON canonicalization exists in VRP only for non-JWS correlators (for example MCP arguments_sha256) and never as a preprocessing step for leaf hashing.

A Signed Tree Head (STH) MUST contain:

An inclusion proof is the Merkle audit path proving a leaf is contained in the tree described by a specific STH. A consistency proof proves that the tree at tree_size N1 is a prefix of the tree at tree_size N2 — i.e. the log is append-only.

5. Log Identity and Keys

Each log has a log_id and publishes its Ed25519 public verification key. The log_id SHOULD be derived from the log's key or expressed as a did:web of the log's own operator domain, for example did:web:example-log.invalid.

STHs and entry promises MUST be signed with the log's Ed25519 key (EdDSA). A verifier MUST NOT infer a trust level, certification, or HemmaBo approval from a log_id.

5.1 Operator key discovery

A log MUST publish its Ed25519 verification key at a stable HTTPS URL on the log operator's own domain, and a verifier MUST validate every STH signature against the key published there.

The trust anchor for log statements is the operator's published key — never a key published by a host node, and never key material served through a node's read-through proxy (§7.2). A node cannot become an authority over its own history by re-serving the log.

Reference log (HemmaBo-operated):

6. Submission and Signed Entry Promise

An issuer (a host-domain DID) MAY submit an artifact hash to one or more logs. On acceptance, a log returns a Signed Entry Promise (SEP) — a signed commitment to include the entry within a stated Maximum Merge Delay (MMD), analogous to a Certificate Transparency SCT.

An issuer MAY embed received SEPs in its VRP Portable Attestation bundle so that a verifier can check the promise offline without contacting the log live. The SEP is a promise, not a proof of final inclusion; final inclusion is confirmed against an STH and an inclusion proof.

7. Log Endpoints (proposed)

A log MAY expose the following read endpoints on its own operator domain. These are proposed for v0.1 and are illustrated with the reserved, non-resolving example-log.invalid domain:

A log MUST serve these from a domain it controls. A log MUST NOT require a HemmaBo endpoint, registry, or approval.

The reference log serves these operations at https://www.hemmabo.com/api/vrp-tlog (latest STH; ?hash= inclusion proof; ?first=&second= consistency proof), with an archived-STH listing per §7.1.

7.1 STH archival

A log SHOULD persist a signed STH for every append and MUST make archived STHs publicly retrievable when it archives them.

Archived STHs are what make third-party append-only auditing possible without running a continuous monitor: any two archived STHs can be checked against a consistency proof at any later time, so a rewrite of history is cryptographically detectable against any earlier archived STH — not only against tree heads an external monitor happened to capture. A log that mints STHs only on demand provides inclusion proofs but leaves consistency auditing entirely to external observers; archival closes that gap from the log's first leaf.

7.2 Node read-through proxy (non-authoritative)

A host node MAY re-serve its log's read operations on the node's own domain, so that a guest or agent can fetch a proof where they booked:

Normative rules:

This split preserves the two-class architecture: the log stays federation-shared and operator-run (an auditor of records, §3), while the node remains the single origin for its own offers and receipts.

8. Verification

To verify inclusion of an artifact, a verifier MUST:

  1. Compute sha256:{hex} over the exact compact JWS of the artifact.
  2. Obtain an STH for the chosen log and verify the STH's Ed25519 signature against that log's published key.
  3. Obtain and verify the Merkle inclusion proof for the artifact hash against the STH root_hash and tree_size.

To audit append-only behavior over time, a verifier (or an independent monitor) MUST obtain two STHs and verify the consistency proof between their tree_size values. Archived STHs (§7.1) serve as the earlier tree head when no independently captured STH is available.

For the receipt-specific verifier walk-through (obtain verbatim → verify node signature → hash exact bytes → inclusion proof → operator-key STH check → consistency), see Receipt v1 §16.

8.1 What a proof removes trust in — and what it does not

The guarantee formulation is deliberately layered and MUST NOT be overstated:

A log is tamper-evident, never "immutable": an operator with storage access can physically rewrite bytes, but not undetectably against any previously published or archived STH. Implementations and verifiers MUST use the tamper-evident/cryptographically-detectable framing in user-facing language.

Normative limits:

9. Privacy and GDPR

Leaves contain only the SHA-256 of a signed envelope — never cleartext credentials, credential subject fields, or guest data. The log therefore reveals only that "an artifact with this hash was recorded at time T", never its contents.

This layer MUST uphold every data-minimization rule of VRP Portable Attestations v0.1 (Section 9): no guest name, email, phone number, payment instrument, guest DID, exact identifying stay dates, reviews, outcomes, risk, or scores may be derivable from a log entry.

10. Relationship to Other VRP Layers

11. Conformance

Signed conformance vectors are published under examples/conformance/log/: a documented test log key (did:web:example-log.invalid), a signed STH, inclusion proofs for a known leaf (positive and negative), and consistency proofs between two tree sizes — verifiable the same way the attestation vectors are (npm test, verify-tlog-vectors). The reference verifier is lib/vrp-tlog.mjs.

12. Non-Goals

VRP Transparency Log v0.1 is explicitly not:

It is the decentralized, no-gatekeeper alternative to an accredited certifying authority: verifiable, non-forgeable trust history that no single party — including HemmaBo — can rewrite.

13. License

Specification text: dedicated to the public domain under CC0 1.0. Reference code and conformance test vectors: Apache-2.0 (ADR 0007 D7).