BrightChain Documentation
Mathematics does not accept a search warrant. Where the state sees noise, the people find truth.
Welcome to the BrightChain documentation. This index organizes all project documents by topic so you can quickly find what you need.
For hands-on guides, start with the Walkthroughs.
Table of Contents
Overview & Vision
High-level project descriptions, the academic paper, and comparison analyses.
| Document | Description |
|---|---|
| BrightChain Summary | Project abstract, problem statement, and solution overview |
| BrightChain Writeup | Extended narrative covering history, analogies, and ecosystem vision |
| Academic Paper Draft | Formal paper: “BrightChain: A Unified Cryptographic Platform for Privacy-Preserving Decentralized Applications” |
| OFF System Comparison | Side-by-side analysis of BrightChain vs. the original OFF System |
Architecture & Design
Core architecture rules, block hierarchy, and system-wide design decisions.
| Document | Description |
|---|---|
| Architecture Rules | Dependency direction rules and ServiceLocator patterns |
| Block Hierarchy | Block type taxonomy: BaseBlock, RawDataBlock, CBL, Encrypted, etc. |
| Block Metadata | Metadata structure for temperature tracking, location, and access patterns |
| Data Temperature & Location | Temperature classification (Frozen → Viral) and location management |
| TUPLE Storage Architecture | OFF-compliant TUPLE storage model for plausible deniability |
| Pool-Based Storage Isolation | Namespace isolation specification for multi-tenant block storage |
Storage System
Storage pools, credits, markets, and file storage mechanics.
| Document | Description |
|---|---|
| Storage Overview | Simplified explanation of file → block → XOR → store pipeline |
| Storage Pools Architecture | Pool concepts, lifecycle, encryption modes, and cross-node coordination |
| Storage Pools API | Public API reference for IPooledBlockStore, adapters, and error types |
| Storage Credits | Joule-based credit system for resource allocation |
| Storage Market | Dynamic marketplace for storage pricing, bids, and offers |
| Member Storage | Public/private CBL split for member data |
Cryptography & Security
Encryption, key management, voting security, and cryptographic analyses.
| Document | Description |
|---|---|
| Block Encryption Review | End-to-end code review of block and encryption systems |
| ECIES-Paillier Bridge Analysis | Security analysis of the novel ECIES-to-Paillier key derivation |
| Key Rotation Strategies | Challenges and solutions for key rotation in distributed encrypted storage |
| Voting Security Best Practices | Production security guidelines for the VotingService |
| EncryptedBlock | EncryptedBlock class API reference |
| EncryptedOwnedDataBlock | EncryptedOwnedDataBlock class API reference |
Governance & Voting
BrightTrust system, voting architecture, and brokered anonymity.
| Document | Description |
|---|---|
| BrightTrust System | Technical deep-dive: Shamir’s Secret Sharing, threshold governance |
| BrightTrust Overview | High-level BrightTrust overview with implementation status |
| Voting System Architecture | 15+ voting methods, Paillier homomorphic encryption, audit logs |
| Node Management & Voting | Node types, states, and participation in governance |
Energy Economy
Joule-based energy tracking, operation costs, and economic protocol.
| Document | Description |
|---|---|
| Energy Economy Protocol | Full protocol specification for the Joule-based economy |
| Network Operation Costs | Cost table for node, block, and metadata operations |
Networking & Protocols
Network implementation, gossip delivery, UPnP, and client protocols.
| Document | Description |
|---|---|
| Network Implementation | Technology stack: Express, Socket.io, WebSocket options |
| Gossip Delivery Protocol | Epidemic-style gossip propagation for decentralized message delivery |
| Lumen Client Protocol | REST + WebSocket protocol between Lumen GUI and BrightChain node |
| Lumen Implementation Guide | Step-by-step guide for the Lumen client team |
| UPnP Architecture | UPnP port mapping subsystem: API, flows, and security |
| UPnP Configuration | Quick-start guide for enabling UPnP |
| UPnP Manual Testing | Testing UPnP port mapping with a real router |
Messaging & Communication
Message passing, email, gossip delivery, and the communication platform.
| Document | Description |
|---|---|
| Messaging System Architecture | Block-based message storage, routing, and delivery tracking |
| Message Passing API | MessageCBLService, MessageRouter, and EventNotificationSystem API |
| Communication System Architecture | “Discord meets Signal” — DMs, groups, and channels |
| Email System Architecture | Decentralized RFC 5322-compliant email on encrypted block storage |
Identity & Keybase Features
Paper keys, device provisioning, identity proofs, and user guides.
| Document | Description |
|---|---|
| Keybase Features Architecture | System architecture for Keybase-inspired features |
| Keybase Features Developer Guide | Service reference and integration patterns |
| Keybase Features User Guide | End-user guide: paper keys, device management, identity proofs |
| BrightPass Password Manager | VCBL-based password vault built on BrightChain encryption |
Applications
BrightHub social network and other application-layer designs.
| Document | Description |
|---|---|
| BrightHub Design | Technical design for the Twitter-like social network module |
| BrightHub Requirements | Full requirements document for BrightHub |
API Reference
Class and service documentation for core library types.
| Document | Description |
|---|---|
| StaticHelpersChecksum | Checksum calculation utilities (SHA3-512) |
| StaticHelpersTuple | Block tuple utilities (XOR, whitening, parity) |
| CrcService | CRC8, CRC16, CRC32 checksum service |
| EmailString | Validated email address class |
| Flags | Language flag mappings |
| HanselGretelBreadCrumbTrail | Breadcrumb tracing for debugging |
Test Documentation
Test specifications and coverage documentation.
| Document | Description |
|---|---|
| StaticHelpersChecksum Tests | Unit test documentation for checksum helpers |
| StaticHelpersECIES Tests | Unit test documentation for ECIES helpers |
Roadmaps & Implementation Status
Planning documents, progress reports, and implementation logs.
| Document | Description |
|---|---|
| Roadmap | Project roadmap with short/medium/long-term goals |
| Solo Developer Roadmap | Strategic roadmap for solo development with AI assistance |
| Implementation Roadmap | Phased implementation plan (TEL, replication, etc.) |
| Auth + Energy Implementation Plan | Plan for auth system with energy accounts |
| Week 1 Energy Foundation | Week 1 progress on energy economy implementation |
| Auth Implementation Complete | Auth + energy system completion report |
| React Implementation Complete | Auth + React frontend completion report |
| Email Service Integration | AWS SES email integration completion report |
Walkthroughs
Step-by-step guides from beginner to advanced.
| # | Guide | Difficulty | Time |
|---|---|---|---|
| 00 | Architecture Overview | Beginner | 20 min |
| 01 | Quickstart | Beginner | 15 min |
| 02 | Node Setup | Intermediate | 30 min |
| 03 | Storage Pools | Intermediate | 30 min |
| 04 | BrightDB Usage | Intermediate | 45 min |
| 05 | Building a dApp | Advanced | 60 min |
| 06 | Troubleshooting & FAQ | Beginner | 10 min |