Skip to content

docs(vindex): update tlog-vindex spec and add applications and architecture docs - #177

Merged
mhutchinson merged 1 commit into
transparency-dev:mainfrom
mhutchinson:vindex/pr-02a-docs
Oct 27, 2026
Merged

mhutchinson merged 1 commit into
transparency-dev:mainfrom
mhutchinson:vindex/pr-02a-docs

Conversation

@mhutchinson

Copy link
Copy Markdown
Contributor

Summary

Part 2a in the vindex v1 upstreaming stack (extracted from #172 so the spec, ecosystem vision, and high-level architecture can be reviewed before the individual subcomponent design docs in #172 / Part 2b).

  • Updates vindex/docs/tlog-vindex.md:
    • Simplifies c2sp.org/tlog-vindex-state@v1 to a strict 6-line unsigned input state commitment (input-origin, from, input-size, input-root, mpt-root), decoupling /keys verification from Input Log signature schemes and witness policies while advising operators to retain signed Input Log checkpoints out-of-band.
    • Shelves the pre-1.0 in-band map-fn commitment (recorded in ## Design Log pending ecosystem discussion on encoding and verification).
    • Parameterizes the Output Log symmetrically with <output-log-origin> and a checkpoint verification policy (dropping tlog-policy from the spec).
    • Drops the advisory limit query parameter on GET <index-url>/values for deterministic HTTP caching, drops the cross-lookup stateful commitment cache requirement, clarifies empty-range (from = input_size) empty_mpt_hash verification, and adds an explicit caller coverage-horizon check for from.
  • Adds vindex/docs/APPLICATIONS.md: Illustrates how Certificate Transparency, Merkle Tree Certificates, Go SumDB, Sigstore, and Sigsum map onto VIndex—who monitors each log, canonical key shapes, query-time prefix proofs, and epoch rotation (from > 0).
  • Adds vindex/docs/ARCHITECTURE.md: Defines the high-level 5-stage Map Sandwich pipeline, checkpoint promotion invariants, crash consistency model, auditing boundaries, operational characteristics, and architectural trade-offs.
  • Updates vindex/README.md: Aligns high-level terminology and indexes the core specification, applications, and architecture documents.

PR Stack Roadmap

  1. docs(vindex): retire legacy MVP and add C2SP tlog-vindex specification (docs(vindex): retire legacy MVP and add C2SP tlog-vindex specification #171)
  2. 2a: docs(vindex): update tlog-vindex spec and add applications and architecture docs (this PR)
    2b: docs(vindex): add subcomponent design documentation (docs(vindex): add subcomponent design documentation #172, stacked on 2a)
  3. feat(vindex): add wire codecs and metrics leaf packages
  4. feat(vindex/mapfn): add WASM guest SDK, wazero sandbox host, examples, and CLI
  5. feat(vindex/ingest): add tile-cached ingestion pipeline
  6. feat(vindex/kvstore): add Pebble inverted chunk storage engine
  7. feat(vindex/tree): add variable-length MPT state trie and output log publisher
  8. feat(vindex): add sync coordinator and C2SP HTTP read server
  9. feat(vindex/client): add verifiable C2SP client SDK and top-level Engine API
  10. feat(vindex/auditor): add independent full-log auditor
  11. feat(vindex/hammer): add continuous load-testing and verification hammer
  12. feat(vindex/cmd): add vindexd daemon, client CLI, dashboards, and e2e suite
  13. feat(vindex/sumdb): add Go SumDB index/verify binaries, Docker stack, and quickstart
  14. feat(vindex/mtc): add MTC and Static-CT personalities, clonelog, and auditor CLI

…ecture docs

- Simplify c2sp.org/tlog-vindex-state@v1 to 6 lines (omitting embedded input log checkpoint signatures and shelving in-band map-fn commitment pre-1.0) and clarify empty-range, MPT topology, and verification rules in docs/tlog-vindex.md.
- Add docs/APPLICATIONS.md illustrating how CT, MTC, Go SumDB, Sigstore, and Sigsum map onto VIndex (who monitors each log, canonical key shapes, prefix queries, and epoch rotation).
- Add docs/ARCHITECTURE.md defining the high-level 5-stage Map Sandwich pipeline, checkpoint promotion invariants, crash consistency, auditing boundaries, and architectural trade-offs.
- Update vindex/README.md to align terminology and index the high-level documentation.
@mhutchinson
mhutchinson merged commit 014cd7e into transparency-dev:main Oct 27, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants