01↗
System architecture
Clients, gateway, Go node, contracts, data planes, and source-of-truth rules.
Kode/Docs
PROTOCOL DOCUMENTATION · DRAFT V1Build on verified
Build on verified
foundations.
The technical source of truth for Kode’s repository format, wallet authorization, P2P synchronization, EVM coordination, and engineering procedures.
7 accepted ADRs30 source documentsEnglish · normative drafts
01
START HERE
Documentation map
Kode separates explanatory engineering guidance from normative specifications. Protocol behavior must follow the specifications; implementation changes cannot silently redefine them.
02↗
Repository objects
Canonical DAG-CBOR objects, CIDs, commits, attestations, refs, and private encryption.
03↗
Wallet authorization
SIWE challenges, device delegation, capabilities, policy evaluation, and session security.
04↗
P2P protocol
go-libp2p negotiation, verified object transfer, ref sync, discovery, and rate limits.
05↗
EVM contracts
Repository registry, access policy, compare-and-swap branches, PRs, and approvals.
06↗
Threat model
Assets, trust boundaries, primary attacks, mitigations, and security invariants.
07↗
Testing strategy
Cross-language conformance, fuzzing, invariants, P2P adversarial tests, and E2E flows.
08↗
Operations
Environments, observability, backups, recovery, key rotation, releases, and incidents.
02
SELECTED METHODS
Technical defaults
Canonical encodingDAG-CBOR
One logical object must always produce one byte representation.
Content identityCIDv1 · SHA-256
Objects are verified by content rather than storage location.
Routine signingEd25519 device keys
Wallet-delegated keys avoid prompting users for every commit.
Root identitySIWE · EIP-712
Wallet signatures establish identity and delegate explicit capabilities.
Peer networkgo-libp2p
QUIC-first encrypted transport with discovery and NAT traversal.
ConsensusEVM contracts
Only shared policy, protected refs, PR state, and hashes move on-chain.
03
SYSTEM FLOW
From wallet to verified state
CORE RULE
Wallet identity does not automatically grant repository access. The Go boundary evaluates explicit policy for every protected operation.
04
ENGINEERING PROCEDURE
Specification before implementation
- 01Classify the change
Identify UI, application, protocol, object-format, security, or contract impact.
- 02Record the decision
Security-sensitive and interoperable behavior begins with an accepted ADR.
- 03Write executable rules
Define fields, bounds, errors, valid fixtures, and invalid fixtures.
- 04Implement both boundaries
Go and TypeScript must pass the same canonical test vectors.
- 05Attack the assumptions
Run fuzz, invariant, adversarial, authorization, and recovery tests.