BrightChain Documentation
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
Quorum system, voting architecture, and brokered anonymity.
| Document | Description |
|---|---|
| Quorum System | Technical deep-dive: Shamir’s Secret Sharing, threshold governance |
| Quorum Overview | High-level quorum 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 |