commit ef4009793589243d2e89c42e7ce930d56bd202f4
parent 4921ff38f9e774b90501559ba42ed121ee15133f
Author: Jared Tobin <jared@jtobin.io>
Date: Tue, 10 Feb 2026 12:35:42 +0400
meta: docs
Diffstat:
3 files changed, 31 insertions(+), 34 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+dist-newstyle/
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,16 +1,16 @@
-# ppad-bolt8
+# ppad-auditor
-Haskell implementation of BOLT #8 (Lightning Network encrypted transport).
-
-Specification: https://github.com/lightning/bolts/blob/master/08-transport.md
+Haskell tool for static analysis of GHC aarch64 assembly with a focus
+on constant-time memory access auditing.
## Project Structure
-- `lib/` - library source (Lightning.Protocol.BOLT8)
+- `lib/` - library source (parser, CFG, analysis)
+- `app/` - CLI entrypoint
- `test/` - tests (tasty + tasty-hunit)
- `bench/` - benchmarks (criterion for timing, weigh for allocations)
- `flake.nix` - nix flake for dependency and build management
-- `ppad-bolt8.cabal` - cabal package definition
+- `ppad-auditor.cabal` - cabal package definition
- `CLAUDE.md` / `AGENTS.md` - keep these in sync
## Build and Test
@@ -30,8 +30,9 @@ Do not use stack. All dependency and build management via nix.
### ppad libraries (use freely)
-Use ppad libraries (github.com/ppad-tech, git.ppad.tech) liberally.
-Current dependencies: ppad-aead, ppad-hkdf, ppad-secp256k1, ppad-sha256.
+Use ppad libraries (github.com/ppad-tech, git.ppad.tech) when helpful.
+Current dependencies: aeson, bytestring, containers, megaparsec, text,
+optparse-applicative.
### External libraries
@@ -40,6 +41,8 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
**Ask for explicit confirmation before adding any library outside of:**
- GHC boot/core libraries
+- Current project deps: aeson, bytestring, containers, megaparsec,
+ optparse-applicative, text
- ppad-* libraries
- Test dependencies (tasty, QuickCheck, etc. for test-suite only)
- Benchmark dependencies (criterion, weigh for benchmark only)
@@ -48,18 +51,13 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
### Performance
-- Use strictness annotations (BangPatterns) liberally
-- Prefer UNPACK for strict record fields
-- Use MagicHash, UnboxedTuples, GHC.Exts for hot paths
-- Do not rely on UNBOX pragmas; implement primitives directly with
- MagicHash and GHC.Exts when needed
-- Use INLINE pragmas for small functions
-- Refer to ppad-sha256 and ppad-fixed for low-level patterns
+- Prefer strict data structures where it simplifies analysis
+- Avoid unnecessary allocations in hot paths (parsing, dataflow)
### Type safety
- Encode invariants into the type system
-- Use newtypes liberally (e.g., Sec, Pub, Session)
+- Use newtypes liberally (e.g., Reg, Sym, Label)
- Use ADTs to make illegal states unrepresentable
- Prefer smart constructors that validate inputs
@@ -86,7 +84,7 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
Use tasty to wrap all tests:
- tasty-hunit for unit tests with known vectors
- tasty-quickcheck for property-based tests
-- Source test vectors from specifications (RFC, BOLT spec, Wycheproof, etc.)
+- Source fixtures from real GHC aarch64 dumps and hand-crafted samples
Property tests should enforce invariants that can't be encoded in types.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,16 +1,16 @@
-# ppad-bolt8
+# ppad-auditor
-Haskell implementation of BOLT #8 (Lightning Network encrypted transport).
-
-Specification: https://github.com/lightning/bolts/blob/master/08-transport.md
+Haskell tool for static analysis of GHC aarch64 assembly with a focus
+on constant-time memory access auditing.
## Project Structure
-- `lib/` - library source (Lightning.Protocol.BOLT8)
+- `lib/` - library source (parser, CFG, analysis)
+- `app/` - CLI entrypoint
- `test/` - tests (tasty + tasty-hunit)
- `bench/` - benchmarks (criterion for timing, weigh for allocations)
- `flake.nix` - nix flake for dependency and build management
-- `ppad-bolt8.cabal` - cabal package definition
+- `ppad-auditor.cabal` - cabal package definition
- `CLAUDE.md` / `AGENTS.md` - keep these in sync
## Build and Test
@@ -30,8 +30,9 @@ Do not use stack. All dependency and build management via nix.
### ppad libraries (use freely)
-Use ppad libraries (github.com/ppad-tech, git.ppad.tech) liberally.
-Current dependencies: ppad-aead, ppad-hkdf, ppad-secp256k1, ppad-sha256.
+Use ppad libraries (github.com/ppad-tech, git.ppad.tech) when helpful.
+Current dependencies: aeson, bytestring, containers, megaparsec, text,
+optparse-applicative.
### External libraries
@@ -40,6 +41,8 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
**Ask for explicit confirmation before adding any library outside of:**
- GHC boot/core libraries
+- Current project deps: aeson, bytestring, containers, megaparsec,
+ optparse-applicative, text
- ppad-* libraries
- Test dependencies (tasty, QuickCheck, etc. for test-suite only)
- Benchmark dependencies (criterion, weigh for benchmark only)
@@ -48,18 +51,13 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
### Performance
-- Use strictness annotations (BangPatterns) liberally
-- Prefer UNPACK for strict record fields
-- Use MagicHash, UnboxedTuples, GHC.Exts for hot paths
-- Do not rely on UNBOX pragmas; implement primitives directly with
- MagicHash and GHC.Exts when needed
-- Use INLINE pragmas for small functions
-- Refer to ppad-sha256 and ppad-fixed for low-level patterns
+- Prefer strict data structures where it simplifies analysis
+- Avoid unnecessary allocations in hot paths (parsing, dataflow)
### Type safety
- Encode invariants into the type system
-- Use newtypes liberally (e.g., Sec, Pub, Session)
+- Use newtypes liberally (e.g., Reg, Sym, Label)
- Use ADTs to make illegal states unrepresentable
- Prefer smart constructors that validate inputs
@@ -86,7 +84,7 @@ Use only minimal external dependencies. Prefer GHC's core/boot libraries
Use tasty to wrap all tests:
- tasty-hunit for unit tests with known vectors
- tasty-quickcheck for property-based tests
-- Source test vectors from specifications (RFC, BOLT spec, Wycheproof, etc.)
+- Source fixtures from real GHC aarch64 dumps and hand-crafted samples
Property tests should enforce invariants that can't be encoded in types.
