Page cover

Merkle-based Whitelisting

dotHYPE uses cryptographic allowlists to offer fair, scalable access to early mint phases—without revealing sensitive logic or requiring full onchain lists.

Merkle-based whitelisting is how we manage early access for select community members, partners, and contributors. This system allows addresses to claim names without relying on centralized off-chain logic, while still being efficient and secure.

This page covers how the allowlist system works, what’s visible to users and integrators, and how we preserve fairness while avoiding front-running.

🔐 Why Use Merkle Proofs

Merkle trees allow us to:

  • Prove an address is eligible without storing all addresses on-chain

  • Keep the allowlist verifiable but compact (just a root hash on-chain)

  • Prevent misuse by limiting each address to a single claim (or one per configured tier)

This approach keeps the system:

  • Transparent (proofs are user-verifiable)

  • Efficient (low gas footprint)

  • Secure (not guessable or enumerable by competitors)

✅ How It Works (Simplified)

  1. Off-chain, we generate a Merkle tree of all eligible addresses

  2. We store only the root hash on-chain

  3. Each user is given a Merkle proof—a series of hashes proving their address is in the tree

  4. During mint, the user submits their name, duration, and proof

  5. The contract:

    • Verifies the proof against the root

    • Checks the user hasn’t already used their spot

    • Mints the name if all checks pass

function registerWithMerkleProof(
  string calldata name,
  uint256 duration,
  bytes32[] calldata proof
) external payable returns (uint256);

🛡 Anti-Exploitation Measures

To ensure fairness and prevent abuse:

  • Each allowlisted address can mint only once during the phase

  • Proofs are not reusable

  • The Merkle root can only be updated by the protocol owner

  • Reserved names cannot be claimed via Merkle (they must be claimed via the reservation method)

This protects against address farming, multi-claim exploits, and ensures equality across wallets.

🧠 For Developers

To check if an address has used their spot:

function hasUsedAllowlistSpot(address user) external view returns (bool);

To reset usage for a list of addresses (e.g., in case of failed attempts):

function resetMerkleProofUsage(address[] calldata users) external onlyOwner;

To update the allowlist:

function setMerkleRoot(bytes32 _merkleRoot) external onlyOwner;

All allowlist generation and proof distribution is handled off-chain. You don’t need to expose full lists onchain or in your UI.

📣 Events Emitted

For indexers and dashboards:

event MerkleProofRegistration(string name, address indexed owner, uint256 duration);
event MerkleRootUpdated(bytes32 merkleRoot);

These events ensure transparent activity tracking while keeping individual proofs private.

👁️ Public Transparency, Private Integrity

dotHYPE's allowlist model balances:

  • 🧩 Public verifiability (via Merkle proof structure)

  • 🔐 Competitive opacity (roots only, no address indexing)

  • 🎯 Usage fairness (1 claim per eligible wallet)

For broader context, return to the Registration Mechanics → overview.

Last updated