LAYER 2 — PRIMARY BUILD

Trust Spanning — VTAs & TSP

The Trust Spanning Protocol (TSP, Rev 3) provides authenticated messaging, relationship establishment, and end-to-end encryption between Verifiable Trust Agents, independent of the underlying transport. Version 0.2.0 implements Direct Mode over libp2p using the experimental wire format, with support for post-quantum signing and hybrid key encapsulation.

Active — Direct Mode released in v0.2.0

What is the Trust Spanning Layer?

Layer 2 lets Verifiable Trust Agents (VTAs) establish protocol relationships and exchange signed messages, with optional end-to-end encryption. Changing signed content causes verification against the original signature to fail. Protocol authentication is distinct from credential evaluation and authorization.

The protocol at this layer is the Trust Spanning Protocol (TSP). TSP is transport-agnostic — it defines the message format, signing, encryption, and relationship handshake, but does not dictate how messages are physically delivered. The current implementation uses libp2p as the transport, but TSP could equally run over HTTP, Bluetooth, QR codes, or any other channel.

TSP shares DIDComm's support for authenticated messaging between DID-identified parties. It is a separate protocol with its own wire format and relationship model. Our Rev 3 implementation uses CESR 2.0 (Composable Event Streaming Representation) for message encoding and framing, Ed25519 signing with support for ML-DSA-65 post-quantum signatures, and HPKE-Base encryption. Its explicit relationship handshake uses XRFI (invite), XRFA (accept), and XRFD (decline) messages.

What's Implemented

The v0.2.0 documentation describes Direct Mode, VTA creation, peer relationship establishment, mutual acknowledgment, agent name registration, confidential messaging, and profile-card retrieval. The component descriptions below explain their roles in the protocol.

🌐

P2P Transport Interface

A clean TspTransport abstraction wrapping libp2p — TCP connections, noise encryption, yamux multiplexing, and the /tsp/1.0.0 protocol handler.

✅ Complete
🔢

Cryptographic Primitives

Ed25519 and ML-DSA-65 (post-quantum) signing, X25519 key agreement, and HPKE-Base confidential messaging (RFC 9180) with an ML-KEM-768 + X25519 hybrid KEM option. CESR framing represents the resulting material; it is separate from those cryptographic operations.

✅ Complete
🪪

Verifiable Identifiers

Creation, resolution, and verification for the documented did:scid:vh and did:peer:4 methods. Resolution and update requirements depend on the method and available history.

✅ Complete
🗄️

Encrypted Key Storage

SQLite-backed keystore with Argon2id key derivation and AES-256-GCM authenticated encryption. Secure local storage for VID key pairs.

✅ Complete
🔐

TSP Message Sealing & Opening

tspSeal() and tspOpen() construct and process TSP messages, including signed application payloads and confidential messages. Peers need compatible framing and proof mechanisms.

✅ Complete
🤝

Relationship Establishment

Peer relationship invitation and acknowledgment, OOBI (Out-of-Band Introduction) encoding for discovery, and a persistent relationship store. These records do not establish unique personhood.

✅ Complete
🔗

RelationshipManager

High-level orchestration API that ties together identity, transport, and message handling. The primary interface for building applications on Layer 2.

✅ Complete
🔒

HPKE Confidential Messaging

End-to-end encryption for confidential messages using HPKE-Base (DHKEM(X25519, HKDF-SHA256) + ChaCha20/Poly1305), with an optional ML-KEM-768 + X25519 hybrid KEM for post-quantum secrecy. Sender authenticity comes from the surrounding signed envelope, not from the HPKE mode.

✅ Complete
🗺️

Routed Mode

Planned TSP protocol routing through intermediaries. It is distinct from libp2p transport relay and does not follow merely from support for rotatable identifiers.

Planned

How TSP Works

1. Identity: Verifiable Identifiers (VIDs)

A VID identifies a participant, while a VTA is the digital agent representing that participant. DID methods supply the rules for creation, resolution, verification material, and updates. The stack documents did:scid:vh and did:peer:4; identifier control alone is not proof of real-world identity.

2. Discovery: OOBI

To connect, one party shares an Out-of-Band Introduction (OOBI) — a small JSON object containing their VID and their libp2p transport address (PeerID + multiaddrs). This can be shared via QR code, link, copy-paste, or any out-of-band channel. The OOBI is not a secret.

3. Relationship establishment

The initiating party invites a peer to establish a relationship. The peer can accept or decline, and the agents record the outcome. A subsequent two-way mutual acknowledgment ceremony records peer confirmation; it does not establish that either endpoint represents a unique human.

4. Messaging: signed payloads and confidential messages

Once a relationship is established, parties can exchange:

  • Signed application payloads — chat, credentials, and other application data carried in a signed TSP envelope. The receiver checks the signature against the applicable verification material for the sender’s identifier. Signatures may use Ed25519 or ML-DSA-65 (post-quantum).
  • Confidential messages — HPKE-Base encrypted application payloads for the intended recipient, with the surrounding signed envelope binding the sender. Encryption, sender authentication, and the application’s decision to accept a payload are separate checks.

Wire formats and compatibility

Deployments must align message framing, relationship exchanges, cryptographic suites, DID methods, and supported versions. The API Reference describes the package interfaces used to seal, open, and inspect messages.

CESR encodes and frames data. Signing, verification, key agreement, and encryption are separate operations. The presence of a cryptographic primitive does not establish end-to-end support for a particular protocol option.

What's Next for Layer 2

The following capabilities are planned for future development:

  • Routed Mode — messages routed through one or more intermediary nodes, with routing behavior and privacy properties to be assessed for that implementation
  • did:scid:vh production hardening — finalizing the rotation ceremony UX and Witness VTC bootstrapping for production deployments
  • Nested messages — TSP messages carrying other TSP messages (for relay and forwarding scenarios)
  • Transport connectivity — continued work on NAT traversal and relay reliability, separate from planned TSP Routed Mode
  • Additional transports — HTTP webhook, Bluetooth, QR-code-based message exchange
← Layer 1: Trust Support Layer 3: Trust Tasks →