feat: Directory Attestation Provider

[jstuczyn]

Summary

Adds the producer side of the verifiable directory: nym-apis now produce and serve signed, quorum-verifiable DigestSnapshots (the data an AttestedTrustAnchor needs), plus generic scaffolding for signing/quorum-verifying arbitrary canonical "directory subsets". The producer logic lives in a new signer-agnostic library (nym-directory-attestation) so nym-nodes can later reuse it as a lower trust tier - the tier is purely the client's choice of which signer set it accepts, not a property of the format.

What's in it

New shared crate: common/directory-attestation

Signer-agnostic protocol + producer core, deliberately light deps (no client crates), so nym-validator-client gains a one-way edge to it and the graph stays a DAG.

Directory contract: snapshot cadence

• snapshot_interval stored as a plain on-chain Item (positive, admin-mutable, queryable), not committed into the LtHash digest.

nym-directory-client (consumer)

• Re-exports moved types so existing use paths compile unchanged.
• NymApiAttestationSource<C: NymApiClientExt> - concrete HTTP AttestationSource (per-tier newtype avoids the NymApiClientExt/NymNodeApiClientExt coherence clash).
• Subset client path: quorum_subset_digest (K-of-N on the committed hash, distinct-signer counting) + fetch_and_verify_subset (fetch once, recompute, fail closed).
• Whole-directory path: AttestedTrustAnchor::verified_directory - reuses the snapshot quorum, fetches bulk data from a source, verifies offline via verify_directory_offline, and is resilient (skips a source serving bad data for one serving good data; still fail-closed).

nym-api producer

• Producer config (retained-window count, settle-lag in blocks, source-anchor selection).
• Retained-window cache + periodic refresher that snapshots at contract cadence, verifies via a DirectoryTrustAnchor (default proven-RPC; never an attested anchor), and signs with the api identity key.
• HTTP routes under /v1/directory: snapshot/latest (settle-lagged), snapshot/{height}, paginated entries/{height} (whole directory), plus subset endpoints (producer-side subset computation deferred - see below).

NymApiClientExt (validator-client)

Typed methods for the above endpoints (directory_snapshot_latest/_at, directory_subset_digest/directory_subset, paginated get_directory_snapshot_data).

Notable decisions

• Whole-directory route is by height only, unsigned - the client drives it with the snapshot's height (no settle-lag skew), and the snapshot is the commitment (tamper → recompute fails closed).

Deferred (blocked upstream, noted in the spec)

• Untrusted-RPC producer anchor - needs the root-key/checkpoint bootstrap; the LightClientAnchor branch currently bail!s.
• Concrete directory subsets - the generic mechanism is in place, but real subset structures wait until nym-nodes start submitting data (producer-side /subset/* endpoints return None for now).

---

This change is 

[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 Plus

Run ID: 846feb84-0fc6-4e9d-b78b-5286ffdb0d4e

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-nym-api-structure

---

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.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs-nextra	Ready	Preview	Aug 21, 2026 10:55am
nym-explorer-v2	Ready	Preview	Aug 21, 2026 10:55am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nym-node-status	Ignored	Preview	Aug 21, 2026 10:55am