Implement Merkle whitelist lifecycle management

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): enhancement, protocol, security

Background

docs/rfcs/merkle-whitelist-lifecycle.md specifies a design for managing Merkle-tree-based allowlists (creation, proof generation, rotation, revocation) for gated resources, but there is no corresponding implementation in src/.

Problem

Consumers wanting to gate a resource behind a Merkle allowlist currently have no SDK support — they'd need to hand-roll tree construction, proof generation, and on-chain root updates themselves, with no guarantee of matching the on-chain verification logic.

Expected Outcome

A MerkleWhitelist module implementing the full lifecycle from the RFC: building a tree from a wallet list, generating proofs for a given address, and producing the root-rotation payload needed to update the on-chain allowlist root.

Suggested Implementation

Implement tree construction and proof generation matching the exact leaf-encoding and hashing scheme specified in the RFC (this must match on-chain verification exactly, or proofs will fail verification). Add a rotation helper that diffs an old and new wallet list and produces the minimal on-chain update payload if the RFC specifies incremental updates, or a full new-root payload otherwise.

Acceptance Criteria

• Leaf encoding and hashing exactly match the scheme in docs/rfcs/merkle-whitelist-lifecycle.md
• Generated proofs verify correctly against a reference on-chain-style verifier implemented in tests (e.g. a minimal JS re-implementation of the verification logic, or against guildpass-core's contract test fixtures if accessible)
• Rotation/revocation flow implemented per the RFC's lifecycle stages
• Unit tests include a large (1000+ leaf) tree to validate proof generation performance and correctness at scale
• pnpm test:run passes

Likely Affected Files/Directories

• docs/rfcs/merkle-whitelist-lifecycle.md
• src/crypto/secp256k1.ts
• src/admin/whitelistAdmin.ts
• src/admin/index.ts

[iamdikko]

Can I have a shot at this, maintainer? Expect a pr in a few hours

[grantfox-oss]

🦊 GrantFox — @iamdikko has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #428)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@iamdikko's PR #441 was approved and merged by @Lakes41.

🏆 @iamdikko: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (293 total points). Track your full progress on GrantFox.

👏 Great work, @iamdikko! Keep contributing to Adamantine-guild.