Developer Documentation & Website Design
Overview
This document captures the design for Layr8’s developer documentation website, aimed at taking developers from zero knowledge of decentralized identity to building production systems.
Target audience: Developers familiar with REST APIs, databases, TCP/IP — but new to DIDs, VCs, DIDComm, and decentralized identity.
Journey: Understand → Envision → Build → Integrate
Terminology Decision
| Term | Usage |
|---|---|
| Agent | Primary term — emphasizes “acting on behalf of” |
| Digital Twin | Secondary term — for IoT/physical-world contexts |
| Plugin | Technical term — code that gives an agent behavior |
| Node | Infrastructure — hosts agents, provisioned via portal.layr8.io |
Both “agent” and “twin” are valid. Lead with “agent” (resonates with AI moment), use “digital twin” for IoT scenarios.
Core Mental Model
Agent (the whole entity) ├── DID ─────────── "who you are" (unique identifier, decentralized) ├── Keys ────────── "how you prove you're you" (cryptographic, never shared) ├── Wallet ─────────┬─ Passport (VC) │ ├─ Driver's License (VC) │ ├─ Costco Membership (VC) │ └─ Employee Badge (VC) ├── Policies ────── "what you allow others to do" └── Behavior ────── "what you can do" (plugins)Key insight: The DID is who you are. VCs are credentials you carry — issued by others, presented when needed, cryptographically verifiable without calling home.
Website (layr8.io) Revisions
Current State
- Headline: “Enterprise-Grade Decentralized Messaging”
- Positions as B2B messaging solution
- Buries the identity paradigm shift
- No clear developer path
Proposed Revisions
New positioning: Lead with the paradigm shift, not the feature set.
Possible headlines (to be tested via survey):
- “The identity layer for the internet. Every agent proves who it is — no central authority required.”
- “What Stripe did for payments, we’re doing for identity.”
- “Your AI agents need identity. Give them cryptographic proof.”
- “EU mandates digital identity wallets by 2026. We’re the infrastructure.”
Homepage structure:
- Hook — one sentence that creates curiosity
- 30-second “aha” — Layer 8 explained visually
- Three paths: Understand it | Try it | See use cases
- Social proof (when available)
Documentation Site Structure
Part 1: The Paradigm Shift
Approach: Problem-forward intro → narrative walkthrough → deep dive for specs
1.1 The Problem with Identity Today
~500 words
- The API key mess — secrets scattered, no proof of who
- OAuth’s limits — awkward for machine-to-machine, multi-org
- Central authority problem — IdP down = everything down
- No portable proof — every service re-verifies from scratch
Hook: “What if identity was built into the protocol itself?“
1.2 A Day in the Life (Narrative)
~800 words
Characters:
- Alice (person with personal agent)
- Alice’s agent (software acting on her behalf)
- Bob’s Marketplace (service, also an agent)
- Acme Corp (Alice’s employer, issues credentials)
Story:
- Alice’s agent wants to buy from Bob’s Marketplace
- Bob: “Prove you’re human over 18” → Alice presents government VC
- Bob: “Prove you can spend from Acme’s account” → Alice presents employee VC
- Transaction completes — no API keys, no central auth server called
1.3 The Building Blocks
~400 words each
DIDs — “Who you are”
- Like a username, but you control it
- Resolves to document with public keys
- Methods: did:web, did:peer, did:ethr
VCs — “What you can prove”
- Credentials you carry (passport, license, badge)
- Issued by one party, held by you, verified by anyone
- Selective disclosure (prove over 18 without revealing birthdate)
DIDComm — “How you communicate”
- Encrypted messaging between DIDs
- Peer-to-peer, no server in middle
- Protocol-based (trust-ping, issue-credential, present-proof)
Agents — “Software with identity”
- Agent = DID + keys + credentials + behavior
- Can represent people, companies, devices, AI
- Plugins give agents capabilities
Contextual diagrams:
AI Agent (Claude Assistant) ├── DID ─────────── did:web:acme.com:agents:purchasing-bot ├── Keys ────────── Ed25519 signing key (in KMS) ├── Wallet ─────────┬─ "Authorized by Acme Corp" (VC) │ ├─ "Spending limit: $500/day" (VC) │ └─ "Department: Engineering" (VC) ├── Policies ────── "Accept requests from verified employees only" └── Behavior ────── order supplies, approve expenses (plugins)Smart Door Lock (Digital Twin) ├── DID ─────────── did:web:building.com:devices:door-42 ├── Keys ────────── Hardware security module ├── Wallet ─────────┬─ "Installed by SecureCo" (VC) │ ├─ "Building: 123 Main St" (VC) │ └─ "Maintenance valid until 2026" (VC) ├── Policies ────── "Unlock for residents + authorized guests" └── Behavior ────── lock, unlock, report status (plugins)1.4 Deep Dive (For the Curious)
Links to detailed spec explanations:
- W3C DID Core Spec
- W3C VC Data Model
- DIDComm v2
- Trust frameworks
Part 2: See What’s Possible
2.1 AI Agents with Verifiable Identity
The problem: How does a vendor know the AI agent calling their API is actually authorized?
The shift: Agent carries cryptographic proof. Vendor verifies instantly.
Use cases:
- AI assistant that books travel, purchases supplies
- Autonomous agents negotiating B2B contracts
- Multi-agent workflows across organizations
2.2 IoT & Digital Twins
The problem: IoT devices authenticate via certificates managed by central CA.
The shift: Each device has its own identity. Access via verifiable credentials.
Use cases:
- Building access control
- Fleet management (trucks, containers)
- Industrial sensors with provenance
2.3 B2B Without EDI
The problem: EDI is expensive, brittle. Every new partner = months of integration.
The shift: Partners verify each other via credentials. Onboarding = presenting proof.
Use cases:
- Supply chain coordination
- E-ticketing
- Financial services (portable KYC)
2.4 Personal Identity on the Web
The problem: Anonymous (bots everywhere) or fully tracked (cookies). No middle ground.
The shift: Prove you’re human without revealing identity.
Use cases:
- Age verification without ID upload
- Portable subscriptions across publishers
- Comment sections for verified humans only
2.5 The “OMG” Section
Low friction (lead with these):
- Onboard once, verify everywhere
- No more API key rotation ceremonies
- Partner integration in hours, not months
- One login across everything you build
- Revocation that actually works
Visionary:
- Your AI works everywhere you do
- Reputation that travels with you
- Global business without borders
- The end of “Sign in with Google”
- Machines that prove their origin
- Content you can prove you created
- Instant trust between strangers
- Humanity-verified internet
Part 3: Build Something (The Sandbox)
Architecture
┌─────────────────────────────────────────────────────────────────┐│ Developer's World ││ ┌─────────────────┐ ┌─────────────────┐ ││ │ Developer's │ ──── │ Developer's │ ││ │ Plugin │ WS │ Node │ ││ │ (code they │ │ (portal.layr8) │ ││ │ write) │ │ │ ││ └─────────────────┘ │ Their Agent │ ││ │ did:web:... │ ││ └────────┬────────┘ │└────────────────────────────────────┼────────────────────────────┘ │ DIDComm┌────────────────────────────────────┼────────────────────────────┐│ Sandbox World │ ││ ┌────────┴────────┐ ││ │ Sandbox Node │ ││ │ │ ││ │ ┌───────────┐ │ ││ │ │ Bots │ │ ││ │ │ Issuers │ │ ││ │ │ Verifiers │ │ ││ │ │ Devices │ │ ││ │ └───────────┘ │ ││ └─────────────────┘ │└─────────────────────────────────────────────────────────────────┘3.1 Quickstart (5 minutes)
- Sign up at portal.layr8.io → node provisioned
- Clone quickstart repo (JS/Elixir/Go)
- Add credentials, run plugin
- Agent connects, talks to sandbox bots
3.2 Sandbox World — Agent Tiers
Tier 1: Hello World
| Agent | What it does | What you learn |
|---|---|---|
| Echo Bot | Sends back whatever you send | Basic message structure |
| Greeter | Welcomes you, lists agents | The sandbox is alive |
Tier 2: Protocols
| Agent | What it does | What you learn |
|---|---|---|
| Ping Pong | Responds to trust-ping | Simplest protocol |
| Chat Bot | Basic conversation | basic-message protocol |
| Thread Bot | Multi-turn, remembers context | Thread IDs, state |
Tier 3: Credentials 101
| Agent | What it does | What you learn |
|---|---|---|
| Credential Kiosk | Issues “Sandbox Explorer” badge | Receiving a VC |
| Bouncer | Lets you in with badge | Presenting a VC |
| Inspector | Shows your credentials | Wallet inspection |
Tier 4: Relationships & Peer DIDs
| Agent | What it does | What you learn |
|---|---|---|
| Friend Bot | Initiates DID exchange | Out-of-band, DID exchange |
| Peer DID Demo | Creates did:peer for relationship | Private pairwise DIDs |
| Introducer | Introduces via peer DID | Mediated connections |
| Address Book | Shows relationships | did:web vs did:peer |
Tier 5: Credential Flows
| Agent | What it does | What you learn |
|---|---|---|
| University | Issues diploma after quiz | Full issue-credential protocol |
| Employer | Verifies diploma, issues employment | Chained credentials |
| Bank | Opens account with employment VC | Multi-credential verification |
Tier 6: Selective Disclosure & ZKP
| Agent | What it does | What you learn |
|---|---|---|
| Age Gate | ”Prove over 21” from birthdate VC | ZKP predicates |
| Salary Verifier | ”Prove over $50k” | Range proofs |
| Membership Prover | Prove set membership | Unlinkable proofs |
| Anonymous Survey | Respond as graduate, not which | Anonymous credentials |
Tier 7: Revocation
| Agent | What it does | What you learn |
|---|---|---|
| Temp Badge Issuer | Credential expires in 5 min | Expiration handling |
| Fickle Employer | Issues then revokes | Revocation registries |
| Revocation Checker | ”Is this still valid?” | Status checking |
| The Fired | Rejects after revocation | Full revocation flow |
Tier 8: Policies & Authorization
| Agent | What it does | What you learn |
|---|---|---|
| VIP Room | Requires 3+ credentials | Credential count policy |
| Time Lock | Only responds certain hours | Time-based policy |
| Rate Limiter | Rejects if too fast | Rate limiting |
| Delegator | Accepts delegated auth | Delegation chains |
| Geo Fence | Requires location credential | Claim-based policy |
Tier 9: IoT & Device Twins
| Agent | What it does | What you learn |
|---|---|---|
| Virtual Thermostat | Reports temp, accepts commands | Device twin basics |
| Smart Lock | Unlock with credential | Device access control |
| Sensor Network | 5 sensors, each with DID | Fleet identity |
| Device Provisioning | Claim unclaimed device | Ownership transfer |
| Firmware Updater | Only manufacturer-signed updates | Secure updates |
Tier 10: Blockchain & Anchoring
| Agent | What it does | What you learn |
|---|---|---|
| Chain Explorer | Shows DID on testnet | did:ethr, resolution |
| Timestamp Bot | Anchors hash to testnet | Proof of existence |
| NFT Badge Issuer | Badge that’s also NFT | VC + NFT hybrid |
| Verifiable Registry | On-chain revocation | Decentralized revocation |
Tier 11: AI Agent Identity & Interop
Context: Google’s A2A protocol enables agent-to-agent communication. Anthropic’s MCP connects agents to tools. Both lack cryptographic identity — Layr8 provides the missing layer.
| Agent | What it does | What you learn |
|---|---|---|
| AI Greeter | LLM-powered agent with its own DID | AI agents need identity too |
| MCP Bridge | Exposes sandbox tools via Model Context Protocol | Layr8 as MCP server |
| A2A Gateway | Translates A2A ↔ DIDComm messages | Protocol interoperability |
| Tool Authorizer | Validates AI agent credentials before granting tool access | Authorization for AI tools |
| Delegation Bot | Issues scoped, time-limited credentials to AI assistants | ”Act on my behalf” patterns |
| Audit Trail | Logs all AI agent actions with cryptographic proofs | Accountability & compliance |
| Capability Negotiator | A2A-style capability discovery over DIDComm | Agent discovery patterns |
Tier 12: Multi-Agent AI Workflows
Build with LangGraph, CrewAI, or Microsoft Agent Framework — but with verifiable identity.
| Scenario | Agents | What you learn |
|---|---|---|
| Marketplace | Buyer + Seller + Escrow | Multi-party coordination |
| Travel Desk | Agent + Airline + Hotel | Orchestration |
| Referral Chain | A → B → C | Trust propagation |
| AI Research Team | Researcher + Analyst + Writer (each with DID) | Multi-agent + identity |
| Human-in-Loop | AI proposes action, human approves via signed VC | Approval workflows |
| Cross-Org AI | Your AI talks to partner’s AI, both verified | B2B agent interop |
| Tool Marketplace | AI discovers and pays for tools with credentials | Economic agents |
Tier 13: Real-World Simulations
| Simulation | What it models |
|---|---|
| E-Ticket Flow | Truck → Checkpoint → Weigh Station → Destination |
| KYC Relay | User → Bank → Credit Bureau → Bank |
| IoT Onboarding | Device → Manufacturer → Owner → Service |
| Supply Chain | Product → Manufacturer → Shipper → Retailer → Customer |
| AI Assistant Onboarding | User → Employer → AI Agent → Tools |
| Agentic Commerce | AI Buyer → Marketplace → AI Seller → Payment |
Tier 14: Social / Build Your Own
| Feature | What you learn |
|---|---|
| Public Chat Room | Multi-party messaging with real developers |
| DM a Developer | Peer-to-peer human communication |
| Agent Directory | Discovery |
| Trading Post | Peer credential exchange |
| Puzzle Master | Multi-developer cooperation |
| Leaderboard | Social proof |
Build Your Own Client Challenges:
| Challenge | What you build |
|---|---|
| CLI Chat | Terminal-based client |
| Web Chat | Browser-based client |
| Mobile Wallet | View/present credentials |
| Bot Builder | Deploy your own agent to sandbox |
| AI Agent Wrapper | Give your LLM a DID and credentials |
| MCP Server | Expose your tools via MCP + DIDComm |
3.3 Badge Progression
| Badge | How to earn | Tier |
|---|---|---|
| 🎫 Explorer | Complete Tier 1-3 | Quickstart |
| 🤝 Connector | Establish 3 peer DID relationships | 4 |
| 🎓 Graduate | Complete credential flows | 5 |
| 🔐 Privacy Pro | Complete ZKP challenges | 6 |
| ⏰ Survivor | Use credential before revocation | 7 |
| 🌡️ Device Whisperer | Control 3 IoT twins | 9 |
| ⛓️ Chain Verified | Anchor something to testnet | 10 |
| 🤖 AI Wrangler | Connect an AI agent with verifiable identity | 11 |
| 🔌 Protocol Bridge | Successfully bridge A2A or MCP to DIDComm | 11 |
| 🎭 Delegator | Issue delegation credential to an AI assistant | 11 |
| 🏗️ Architect | Complete multi-agent workflow | 12 |
| 🤝 AI Orchestrator | Run multi-agent AI workflow with DIDs | 12 |
| 💬 Social Butterfly | Chat with 5 developers | 14 |
| 🛠️ Builder | Deploy own agent to sandbox | 14 |
| 🏆 Veteran | Earn all badges | All |
Key feature: Badges are real VCs. Persistent. Yours forever.
3.4 Deploying to Production
- Custom domains
- Production DID methods
- Observability setup
- Scaling considerations
Part 4: Go Deeper
4.1 Architecture
- Node internals
- Message pipeline
- Plugin channels
- Thread router
4.2 Protocol Reference
| Protocol | Messages |
|---|---|
| trust-ping | ping, ping-response |
| basic-message | message |
| out-of-band | invitation |
| did-exchange | request, response, complete |
| issue-credential | offer, request, issue, ack |
| present-proof | request, presentation, ack |
| report-problem | problem-report |
4.3 API Reference
- WebSocket Plugin API
- REST API
- ExPluginClient (Elixir SDK)
4.4 DID Methods
| Method | When to use |
|---|---|
| did:web | Public, discoverable |
| did:peer | Private, pairwise |
| did:ethr | Blockchain-anchored |
4.5 Credential Formats
| Format | ZKP | When to use |
|---|---|---|
| JWT VC | No | Simple, widely supported |
| JSON-LD VC | No | Semantic interop |
| AnonCreds | Yes | Selective disclosure |
4.6 Security & Key Management
- Key storage options
- Key rotation
- Revocation
- Policy enforcement
4.7 Deployment
- Node tiers (Free, Starter, Scale, Enterprise)
- Custom domains
- Observability
- Clustering
Part 5: Integration & Migration
5.1 OAuth/SSO Integration
- IdP becomes issuer, not runtime dependency
- Hybrid patterns for transition
5.2 API Key Migration
- New integrations on DIDComm
- API gateway translation layer
5.3 mTLS/Certificate Migration
- Similar trust model, decentralized issuance
- Coexistence during transition
5.4 AI Agent Integration
The Emerging Standards Landscape:
| Protocol | Purpose | Governance | Layr8 Relationship |
|---|---|---|---|
| A2A (Agent2Agent) | Agent-to-agent communication | Linux Foundation (150+ orgs) | DIDComm is A2A with crypto identity |
| MCP (Model Context Protocol) | Connect agents to tools/data | Agentic AI Foundation | Layr8 plugins can be MCP servers |
| DIDComm v2 | Secure agent messaging | DIF (Decentralized Identity Foundation) | Layr8 native protocol |
Why identity matters for AI agents:
- A2A lets agents discover capabilities but doesn’t verify who the agent represents
- MCP connects tools but doesn’t prove authorization to use them
- Credentials express authorization, not just authentication
- Audit trail with cryptographic proof of every AI action
- Delegation chains: “This AI acts for Alice, who works for Acme”
Integration patterns:
- MCP + Layr8: Expose your Layr8 agent as an MCP server; AI assistants connect with verified identity
- A2A Bridge: Translate A2A messages to DIDComm, adding cryptographic signatures
- LangGraph/CrewAI: Each agent in your workflow gets a DID and credentials
- Human-in-loop: AI requests approval via present-proof; human signs VC to authorize
5.5 Compliance & Standards
| Standard | Layr8 Alignment |
|---|---|
| W3C DID Core | Native support |
| W3C VC Data Model | JWT and JSON-LD |
| DIDComm v2 | Core protocol |
| eIDAS 2.0 / EUDI | VC-compatible |
| ISO 18013-5 (mDL) | Interop path |
Market Context
Regulatory Tailwind
- EU eIDAS 2.0: By Nov 2026, all EU governments must offer digital identity wallets. By Nov 2027, businesses must accept them. 83 million wallets expected by end of 2025.
- Bhutan: 800K citizens on SSI since Oct 2023. First nation to anchor national ID on Ethereum.
Competitive Positioning
| Company | Headline | Approach |
|---|---|---|
| Dock/Truvera | ”#1 Decentralized ID Platform” | Speed (“12x faster”), additive to existing |
| SpruceID | ”Credentials transformed” | Scale proof (“3M+ digital IDs”) |
| Trinsic | Developer platform | SDK-first, pivoted 2024 |
Layr8 Positioning
“The Oracle of identity” — reliable infrastructure developers trust and advocate for internally. Not flashy, just always there, always works.
Survey for Message Testing
A developer survey has been designed to test:
- Awareness of EU/global identity mandates
- Pain level with current identity/auth
- Which positioning resonates (identity layer, Stripe analogy, AI agents, EU compliance)
- What drives trial (quickstart, docs, case studies, open source)
See separate survey document for full questionnaire.
Next Steps
- Run developer survey to validate messaging
- Revise layr8.io homepage based on results
- Build documentation site structure
- Implement sandbox world (prioritize Tier 1-5 first)
- Create quickstart repos (JS, Elixir, Go)
- Launch beta with badge system
Open Questions
- Documentation platform choice? (Docusaurus, GitBook, custom)
- Sandbox hosting/scaling approach?
- Badge NFT integration — optional or core?
- Quickstart language priority order?