How lightning/bolts works
Main Components
a. Specification Documents: These are the markdown files (00-introduction.md, 01-messaging.md, 02-peer-protocol.md, …, 11-payment-encoding.md, 12-offer-encoding.md) which describe the protocols. They form the core “knowledge base” for the Lightning Network specs.
b. BOLT-Specific Directories: The directories “bolt04”, “bolt07”, and “bolt12” contain JSON test files and examples. They represent test cases and example formats for each of the critical protocol areas.
c. Proposals: The “proposals” directory (e.g., proposals/route-blinding.md) shows community or experimental additions for new protocol features.
d. Tools: The “tools” directory includes scripts (e.g., bolt3-bitcoind-test.sh, extract-formats.py, spellcheck.sh) that help validate and maintain consistency in the specs.
e. CI/CD and Contribution Artifacts: Files like .travis.yml, CONTRIBUTING.md, CoC.md, and the .gitattributes indicate how the project is maintained and integrated into a CI/CD pipeline.
Relationships and Data Flow
• The core protocol specification documents are the reference material.
• The BOLT directories provide concrete sample data/examples and tests that are linked to the protocols.
• The proposal files indicate potential changes or additions to these protocols.
• The tooling scripts interact with both the specification files and the test files for automated checks (e.g., to extract formats for validation or run tests against actual implementations).
• The CI/CD configuration (e.g., Travis CI) ties all these components together by automatically running tests and spell checks on the latest changes.
Architectural Patterns
• The project exhibits a “documentation-as-code” approach where the protocol specifications are maintained as versioned markdown files and test cases.
• There is a clear separation between the specification content (the “what” of the protocols) and the validation tools (the “how” they are verified and maintained).
• Although there is no runtime application, the pattern of separation is similar to a “layered architecture” with clear validation (test examples and tools) and content layers.
• A block for the core documentation (all the numbered markdown files).
• Separate blocks for the test directories: bolt04, bolt07, bolt12.
• A block for Proposals.
• A block for Tools.
• An integration block for CI/CD (Travis CI) and additional contribution guidelines (CONTRIBUTING.md, CoC.md).
• Specifications → BOLT Test Files (Validation)
• Tools → both Specifications and Test Files (Automated Operations)
• Proposals → Specifications (Feedback Loop)
• CI/CD → Tools/Tests/Specs (Automation Workflow)