feat: add scorer-kit

Cargo.toml

@@ -9,6 +9,7 @@ edition = "2018"
 
 [dependencies]
 lightning = { version = "0.2.0", features = ["dnssec"] }
+scorer_kit_lightning = { package = "lightning", git = "https://github.com/synonymdev/rust-lightning", rev = "fe9a6ebd3a07f2fcb1febeac7bf22dd7b6a665a1", features = ["std"] }
 lightning-block-sync = { version = "0.2.0", features = [ "rpc-client", "tokio" ] }
 lightning-dns-resolver = { version = "0.3.0" }
 lightning-invoice = { version = "0.34.0" }
@@ -24,7 +25,11 @@ bitcoin-bech32 = "0.12"
 bech32 = "0.8"
 libc = "0.2"
 
+anyhow = "1"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
+clap = { version = "4", features = ["derive"] }
+csv = "1"
+humansize = "2"
 rand = "0.4"
 serde_json = { version = "1.0" }
 serde = { version = "1.0", features = ["derive"] }

README.md

@@ -16,6 +16,76 @@ The only CLI argument is the storage directory path. All configuration is read f
 
 Use `config.example.toml` in the repo root as a template for your config file.
 
+## scorer-kit
+
+`scorer-kit` is an offline developer tool for LDK scorer files. It can inspect,
+decode, compare, validate, and merge serialized `ChannelLiquidities` binaries
+without starting a node.
+
+Build or run it with:
+
+```sh
+cargo run --bin scorer-kit -- --help
+```
+
+Common flows:
+
+```sh
+# Summarize a scorer binary.
+cargo run --bin scorer-kit -- inspect ./scores-z.bin --label source-z
+
+# Decode the full scorer binary to JSON, including historical buckets.
+cargo run --bin scorer-kit -- decode ./scores-z.bin \
+  --label source-z \
+  --save ./source-z.decoded.json
+
+# Compare two scorer binaries.
+cargo run --bin scorer-kit -- compare ./scores-z.bin ./scores-b.bin \
+  --left-label source-z \
+  --right-label source-b
+
+# Merge two scorer binaries using the default richer-history duplicate policy.
+cargo run --bin scorer-kit -- merge ./scores-z.bin ./scores-b.bin \
+  --label source-z \
+  --label source-b \
+  --output ./merged-richer-history.bin \
+  --report ./merged-richer-history.report.json
+
+# Overlay only selected incoming channels onto a baseline scorer binary.
+cargo run --bin scorer-kit -- node-scids \
+  --graph ./network_graph_cache \
+  --node <node-pubkey> \
+  --scores ./scores-b.bin \
+  --save ./selected.scids
+cargo run --bin scorer-kit -- merge ./scores-z.bin ./scores-b.bin \
+  --label source-z \
+  --label source-b \
+  --policy prefer-last \
+  --overlay-scids-file ./selected.scids \
+  --output ./merged.bin \
+  --report ./merged.report.json
+```
+
+The default merge policy is `richer-history`: unique entries are preserved, and
+duplicate short-channel-id entries keep whichever side has stronger historical
+signal. Other policies are available via `--policy prefer-first`,
+`--policy prefer-last`, `--policy combine`, and `--policy newer`.
+
+Use `--overlay-scid` / `--overlay-scids-file` when only selected incoming
+channels should be merged. The first input is treated as the baseline and is not
+filtered; every later input is reduced to the listed short-channel-ids before
+merge policies are applied.
+
+Use `node-scids` to derive that allowlist from a serialized LDK `NetworkGraph`.
+Scorer binaries only contain short-channel-ids, so node-level selection needs the
+graph to map node pubkeys to channel IDs. Pass `--node` directly, or pass
+`--invoice` to recover the payee pubkey from a Bolt11 invoice. Passing `--scores`
+intersects the graph channels with a scorer file so the allowlist only includes
+channels that have incoming score entries.
+
+Tracked scorer snapshots live in `data/scores/`, including decoded JSON reports
+and the selected overlay candidate at `data/scores/merged.bin`.
+
 ## Configuration
 
 Config is loaded from `<storage_dir>/.ldk/config.toml` and strictly validated. Unknown

data/scores/README.md

@@ -0,0 +1,57 @@
+# scores data
+
+These files are generated by `scorer-kit`. They use sanitized labels so the
+fixtures document scorer structure without embedding local paths, URLs, or
+source-specific names.
+
+- `source-z.decoded.json`: decoded scorer snapshot Z.
+- `source-b.decoded.json`: decoded scorer snapshot B.
+- `merged-richer-history.decoded.json`: decoded output from merging source-z
+  first, then source-b, using `--policy richer-history`.
+- `merged-richer-history.report.json`: merge audit report, including duplicate
+  decisions and summary counts.
+- `merged.bin`: serialized scorer candidate generated by keeping
+  source-z as baseline and overlaying only selected incoming source-b entries.
+- `merged.decoded.json`: decoded JSON view of `merged.bin`.
+- `merged.report.json`: selected-channel overlay merge audit report.
+
+For production-style review, prefer an explicit selected-channel overlay:
+source-z first as the baseline, source-b second as the incoming overlay,
+`--policy prefer-last`, and `--overlay-scids-file <selected.scids>`.
+Use `scorer-kit node-scids --graph <network_graph_cache> --node <node-pubkey>
+--scores <source-b.bin> --save <selected.scids>` to derive that allowlist from a
+serialized LDK network graph. `--invoice <bolt11>` can be used instead of
+`--node` when the payee pubkey should be recovered from an invoice.
+
+Regenerate with:
+
+```sh
+cargo run --bin scorer-kit -- decode <source-z.bin> \
+  --label source-z \
+  --compact \
+  --save data/scores/source-z.decoded.json
+cargo run --bin scorer-kit -- decode <source-b.bin> \
+  --label source-b \
+  --compact \
+  --save data/scores/source-b.decoded.json
+cargo run --bin scorer-kit -- merge <source-z.bin> <source-b.bin> \
+  --label source-z \
+  --label source-b \
+  --output target/scorer-kit/merged.bin \
+  --report data/scores/merged-richer-history.report.json
+cargo run --bin scorer-kit -- decode target/scorer-kit/merged.bin \
+  --label merged-richer-history \
+  --compact \
+  --save data/scores/merged-richer-history.decoded.json
+cargo run --bin scorer-kit -- merge <source-z.bin> <source-b.bin> \
+  --label source-z \
+  --label source-b \
+  --policy prefer-last \
+  --overlay-scids-file <selected.scids> \
+  --output data/scores/merged.bin \
+  --report data/scores/merged.report.json
+cargo run --bin scorer-kit -- decode data/scores/merged.bin \
+  --label merged \
+  --compact \
+  --save data/scores/merged.decoded.json
+```