Web5 Lexicon
This page records the web5 related lexicon that should be followed by client and server to be integrated into the web5 tech stack. The purpose is to add an optional Web5-aware layer to the AT Protocol Personal-Data-Server (PDS) surface by re-using the existing XRPC transport and Lexicon schema language.
All lexicon schemas are pure Lexicon 1 JSON and live under the NSID authority fans.web5.ckb.*. It shall be noted that most of the lexicons are still under draft proposing. Feel free to join in the discussion in the Pull requests of the WIPs.
did:ckb PDS Extension Lexicon
Section titled “did:ckb PDS Extension Lexicon”This defines the standard for did:ckb PDS extension lexicon. It introduces:
- a CKB-style account-flow (Nervos-CKB address, secp256k1 signature over repo root),
- pre-flight signing steps so wallets can prompt users once and re-use the signature for the actual write,
- a small set of index helpers for light-weight queries that do not require repository traversal.
All new schemas are published and MUST be resolved under the NSID authority fans.web5.ckb.* and can be imported side-by-side with the official com.atproto.* lexicons.
Design Goals
Section titled “Design Goals”- Wallet-native UX – the user sees only one signing prompt per logical action.
- Minimal delta – no forks inside repo data-structures; everything is ordinary AT-Protocol records.
- Incremental adoption – a PDS that does not understand these NSIDs can safely ignore them; clients that do can speak them with the supported PDS. A future-proof mechanism can be added to allow the PDS advertises the capability via
fans.web5.ckbin.well-known/supported-lexicon, etc.
Lexicon Overview
Section titled “Lexicon Overview”| File | Purpose | XRPC Type |
|---|---|---|
preCreateAccount.json | returns the unsigned repo root that must be signed by the CKB key | procedure |
createAccount.json | finalises account creation with the signed payload | procedure |
preDirectWrites.json | returns the unsigned commit for a batch write | procedure |
directWrites.json | applies the batch once the commit is signed | procedure |
preIndexAction.json | returns the challenge string for login / delete-account | procedure |
indexAction.json | verifies the signed challenge and performs the action | procedure |
indexQuery.json | cheap read-only helpers (counters, DID lookups, …) | query |
defs.json | shared shapes (signedRoot, etc.) | — |
Machine-readable schemas live in WIPs’s assets/lexicon/ckb/. Human-readable examples and sequence diagrams will be added in a future revision.
CKB-Specific Fields
Section titled “CKB-Specific Fields”ckbAddr– Nervos-CKB short-address (bech32m, testnet/mainnet prefix).signedBytes– secp256k1 personal-message signature (base64, 65-bytes, recoverable).signingKey– did:key string that must resolve to the same secp256k1 pubkey that signedsignedBytes.
Security Considerations
Section titled “Security Considerations”- The PDS must verify that
ckbAddrmatches the recovered pubkey before persisting any repo root. - Challenge messages must include the PDS origin to avoid cross-service replay.
- Clients should pin the PDS TLS certificate when obtaining the challenge to prevent MitM downgrade.
Backwards Compatibility
Section titled “Backwards Compatibility”None of the new procedures collide with existing com.atproto.* NSIDs. A legacy PDS returns status 501 for unknown methods; clients fall back to standard flows.
Reference Implementation
Section titled “Reference Implementation”A reference Rust SDK implementation is tracked in web5-rsky. Typescript SDK and PDS plugin might be added later.