feat: Directory Client: TM Light Client Anchor

[jstuczyn]

Add a Tendermint light-client trust anchor for the directory client

What

Adds LightClientAnchor, a second DirectoryTrustAnchor implementation that verifies the block app_hash via the Tendermint light-client protocol (validator-set consensus) instead of trusting a configured RPC. It's a drop-in alternative to ProvenTrustAnchor, gated behind a new light-client feature on nym-directory-client.

Why

ProvenTrustAnchor (phase 1a) reads header[H+1].app_hash from a configured RPC and trusts it. LightClientAnchor (phase 1b) removes that honest-RPC assumption: starting from a caller-pinned checkpoint, it accepts an app_hash only after verifying the signed header carrying it against the trusted validator set. A forged header from an adversarial RPC fails verification before any downstream ICS23 proof is checked.

How

• Pinned checkpoint + skip verification. The anchor is constructed from a Checkpoint { height, signed_header, validators, next_validators } the caller has verified out-of-band. It verifies a target header directly from the checkpoint (one hop for a stable validator set), and on insufficient trusted-validator overlap (Verdict::NotEnoughTrust) bisects to the arithmetic midpoint and recurses instead of stepping every block.
• Below-head queries. Because the consumer requests arbitrary, out-of-order heights on one reused anchor, the state keeps both the advancing head and the immutable checkpoint; a query at a height the head already passed is re-verified from the checkpoint (the verifier cannot verify backwards), and a height below the checkpoint returns HeightBelowCheckpoint.
• Correct next_validators. Each verified hop fetches validators(target+1) and passes it as UntrustedBlockState.next_validators, tying the set the next skip hop trusts to the verified header's next_validators_hash.
• In-memory app-hash cache; caller-supplied Options (trust threshold, trusting period, clock drift) with nyx_default_options().

Testing

• New MockRpcClient (validator-client, behind a mocks feature) serving pre-registered commit/validators responses with a call log.
• Unit tests over real nyx mainnet fixtures covering: direct verification advances + caches, skip resolves in a single hop, cache hit avoids re-fetch, stale checkpoint fails, below-head/below-checkpoint handling, and bisection (via a checkpoint padded with a dominant non-signing validator, asserted through the commit call sequence).

---

This change is 

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nym-explorer-v2	Ready	Preview, Comment	Jul 9, 2026 12:48pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs-nextra	Ignored	Preview	Jul 9, 2026 12:48pm
nym-node-status	Ignored	Preview	Jul 9, 2026 12:48pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ce562259-a893-414f-9d4c-08b579c9dfb5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/directory-client-validator-verification

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}