docs: add docs-as-code process and one ADR per feature
docs/docs-as-code.md defines the workflow; docs/adr holds 31 ADRs (retroactive, reconstructed from code and changelog) with a template and index. docs/check-docs.sh validates ADR structure, index, cited code paths, relative links and CLAUDE.md/AGENTS.md sync.
This commit is contained in:
1 parent
ce8d777c63
commit
b292590cdc
36 files changed
+987
No files matched your search
@@ -0,0 +1,27 @@
|
||||
# 0006. Anchor headers to hardcoded checkpoints and skip PoW validation
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Area:** SPV
|
||||
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
|
||||
|
||||
## Context
|
||||
|
||||
Palladium uses LWMA difficulty with 2-minute blocks. An SPV client cannot recompute LWMA without the full header history, and NBitcoin assumes Bitcoin's retargeting rules, so checking proof of work client-side would either be wrong or require downloading every header.
|
||||
|
||||
## Decision
|
||||
|
||||
Set `SkipPowValidation = true` in the profile and anchor trust to hardcoded checkpoints instead. For each header used in a Merkle proof, `WalletSynchronizer.AnchorToCheckpointAsync` downloads the intervening headers, verifies the prev-hash chain back to the nearest checkpoint at or below that height, and requires that checkpoint's hash to match exactly. Mainnet carries a checkpoint every 20,000 blocks.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A server cannot feed an alternative history below the newest checkpoint.
|
||||
- Headers above the newest checkpoint are linked but their work is not verified; this is an accepted limitation documented in `SECURITY.md`.
|
||||
- Testnet/regtest have no checkpoints, so headers there are trusted at face value.
|
||||
- Checkpoints must be extended with releases; a wrong checkpoint would reject every honest server.
|
||||
|
||||
## References
|
||||
|
||||
- `src/Core/Spv/WalletSynchronizer.cs`
|
||||
- `src/Core/Spv/BlockHeaderInfo.cs`
|
||||
- `src/Core/Chain/ChainProfiles.cs`
|
||||
- `SECURITY.md`
|
||||
Reference in new issue
Block a user