Skip to content

README.md

Latest commit

 

History

History
187 lines (158 loc) · 8.11 KB

README.md

File metadata and controls

187 lines (158 loc) · 8.11 KB
Raw

Verifiable Trust Infrastructure — Documentation

A guided tour of the workspace: what the VTA and VTC are, how to operate each one, how to integrate with them, and where the design decisions live.

How this tree is organised

graph LR
    concepts["01-concepts/<br/>(shared)"]
    vta["02-vta/<br/>(VTA operator + integrator)"]
    vtc["03-vtc/<br/>(VTC operator + integrator)"]
    ref["04-reference/<br/>(tables, paths, formats)"]
    design["05-design-notes/<br/>(history + implementation)"]

    concepts --> vta
    concepts --> vtc
    vta -.-> vtc
    vta --> ref
    vtc --> ref
    concepts -.-> design

    classDef shared fill:#f5f5f5,stroke:#555,color:#111
    classDef vta fill:#d4e6f9,stroke:#3a6fb0,color:#08305f
    classDef vtc fill:#e9d7f7,stroke:#7e3fa6,color:#3a0a5a
    classDef ref fill:#e8f5e9,stroke:#3e8e41,color:#1b3a1f
    classDef design fill:#fff3e0,stroke:#c77a00,color:#5a3b00
    class concepts shared
    class vta vta
    class vtc vtc
    class ref ref
    class design design
Loading

The dotted line from 02-vta/ to 03-vtc/ reflects the runtime relationship: a VTC is always provisioned on top of an existing VTA via the vtc-host DID template.

If you're trying to…

Task Start here
Understand VTI as a whole Overview
Decide between VTA and VTC Root README — Which service do you need?
Stand up a VTA from scratch VTA cold-start
Stand up a VTC on an existing VTA VTC getting started
Pick where to store the master seed VTA secret backends
Deploy a VTA inside a Nitro Enclave TEE architecture
Build an app that uses a VTA VTA integration guide
Provision a mediator / webvh-host / custom integration Provision-integration
Configure community membership policy VTC community lifecycle
Host a public community website VTC website + admin UX
Look up a BIP-32 path BIP-32 paths
Read the threat model Security model

Table of contents

Part I — Concepts (shared)

Both VTA and VTC build on the same foundation. Read this first.

  • Overview — what VTI is, what VTA and VTC each do, how they relate, the technology stack, request flow.
  • Architecture — workspace layout, crate map, shared module structure, API surface, how to add a new front-end binary.
  • Security model — defense-in-depth, key lifecycle, threat model, attack trees, cryptographic inventory, deployment checklist.

Part II — VTA

How to operate, deploy, and integrate against a VTA.

  • Cold-start — bootstrap a VTA + WebVH
    • mediator from scratch.
  • Non-interactive setup — scripted VTA provisioning via vta setup --from <file> for CI, sealed images, unattended bootstrap.
  • Seal and unseal — what the seal is, when it's set, how vta unseal works.
  • Secret-storage backends — AWS, GCP, Azure, HashiCorp Vault, OS keyring, KMS-TEE.
  • Feature flags — Cargo feature reference, deployment profiles, dependency graph.
  • TEE architecture — Nitro Enclave deployment, KMS bootstrap, vsock store, attestation chain.
  • Integration guide — building a third-party app that consumes VTA-managed keys.
  • DIDComm protocol — message types, schemas, authorization, wire shapes.
  • DID templates — authoring, uploading, resolution (context → global → built-in).
  • Provision-integration — the canonical flow for standing up mediators, webvh hosts, and apps via DID templates and sealed-transfer.
  • Runtime service management — enable / disable / migrate REST + DIDComm services on a running VTA without rebuilds.
  • DID:WebVH update — log-entry format, rotation, hosting.
  • Setup example — worked TOML for vta setup --from.

Part III — VTC

How to operate and integrate against a VTC.

  • Getting started — a working VTC in 10 minutes (assumes an already-running VTA).
  • Architecture — VTC module layout, keyspaces, dependency on the VTA.
  • Community lifecycle — member CRUD, join requests, removal dispositions, policies.
  • Credentials — VMC, VEC, status lists, renewal, DID rotation, custom endorsements.
  • Trust-registry integration — registry publish, membership sync, cross-community recognition.
  • Personhood + relationships — personhood assertion, VRC trust graph, custom endorsements.
  • Website + admin UX — public community website (live + managed modes), embedded admin SPA, routing modes.
  • Admin UX plugins — third-party plugin contract: on-disk layout, manifest schema, scope filters, and the daemon's admin_ui.plugin_dir scan + serve.
  • Feature flags — VTC Cargo feature reference.

Part IV — Reference

  • BIP-32 paths — the VTA's hierarchical-key derivation specification.
  • CLI style — conventions for flags, output, errors, and JSON modes across vta, vtc, pnm, cnm.

Part V — Design notes

In-flight or historical design documents kept for context. These are implementer-facing rather than operator-facing.

Conventions

  • Cross-references use relative links so the docs work both on GitHub and in any local Markdown viewer.
  • Code references in prose use the form path/to/file.rs:line so IDEs can jump to them directly.
  • Wire-format snippets are JSON for narrative clarity; the actual on-the-wire format is whatever the linked Rust types serialize to (CBOR for sealed payloads, JSON for VPs/VCs).
  • Mermaid diagrams render natively on GitHub. Where a diagram and a table convey the same information, both are kept — diagrams for the layout, tables for the lookup.

Contributing to the docs

If you're adding a new document:

  • Shared concept (applies to both VTA and VTC)? Add to 01-concepts/.
  • VTA operator / integrator how-to? Add to 02-vta/.
  • VTC operator / integrator how-to? Add to 03-vtc/.
  • Pure reference (tables, paths, formats)? Add to 04-reference/.
  • Implementation-detail design brief? Add to 05-design-notes/.

Update this index when you add or rename a chapter. Cross-references in the workspace README.md and CLAUDE.md may also need updating. The convention for paths inside Rust source comments is docs/<section>/<file>.md.