Munera is a highly optimized, secure, and scalable decentralized airdrop protocol built on EVM-compatible chains. It utilizes Merkle Tree cryptography to achieve maximal gas efficiency for creators, shifting the computational cost of verification to the claiming phase.
Unlike traditional airdrops that store thousands of addresses on-chain (incurring massive deployment costs), Munera stores only a single 32-byte cryptographic root on the blockchain. The bulk recipient data is secured off-chain via decentralized storage (IPFS).
1.1 Architectural Diagram
2.0 CORE MECHANISMS & SECURITY
2.1 The Merkle Engine (Efficiency & Integrity)
The heart of Munera is the Merkle Tree generation.
Data integrity: The off-chain recipient list is hashed into a binary tree using keccak256. The top hash (the "Root") is committed to the blockchain.
Tamper-Proof: Any modification to the off-chain CSV list (changing an address or amount by even one bit) would result in a completely different Root hash. Since the on-chain contract only accepts proofs matching the stored Root, the off-chain data is cryptographically guaranteed to be authentic.
Gas Optimization: The contract does not need to loop through arrays. It performs a series of hash verifications (O(log n) complexity), making claiming cheap regardless of list size (100 users vs 100,000 users have similar verification costs).
2.2 Smart Contract Protocols
A. The Factory (MuneraFactory.sol)
Role: Standardized deployment of Distributor contracts.
Security: Ensures new airdrops start with clean states.
Monetization: Manages protocol fee collection (native currency or designated ERC20 fee token) prior to deployment.
B. The Distributor (MuneraDistributor.sol)
The vault and verifier.
Immutable Root: The Merkle Root is set upon creation.
Update Mechanism (Secure): The Root can be updated by the owner (admin) to expand the list. The contract calculates the new required funding versus the current balance to ensure solvency before accepting the new root.
Double-Claim Protection: Utilizes a mapping (mapping(uint256 => uint256) private claimedBitMap) based on the user's unique index in the CSV list to mark claims. Once an index is marked, it cannot be claimed again. This is cheaper than mapping by address.
Emergency Controls: Includes withdrawRemainingTokens, accessible only by the contract owner (Ownable), allowing recovery of unclaimed funds after the campaign concludes.
2.3 Off-Chain Data Resilience (IPFS)
Munera does not rely on centralized servers for user lists. The JSON Manifest (containing addresses, amounts, indices, and individual Merkle Proofs) is pinned to IPFS via Pinata.
Decentralization: Data remains accessible as long as it is pinned by at least one node.
Verification: The on-chain contract stores the IPFS CID string, creating an immutable link to the exact version of the data used to generate the root.
MUNERA OPERATOR'S MANUAL
Welcome to Munera, the ultimate tool for distributing digital assets with precision and speed. Whether you are an architect aiming to reward your community or a beneficiary looking to claim your share, this guide will navigate you through the protocol.
🔋 FOR CREATORS (The Architects)
Deploying a Munera drop is a three-step process: Synthesize, Fund, & Deploy.
STEP 1: Data Synthesis (Create Tab)
You need two things: the token contract address you wish to distribute and the recipient list.
The Recipient List Format: You have two options for inputting your data.
Option A: Manual Input (Small batches) Paste directly into the terminal window.
Plaintext
Option B: Bulk Upload (Whale size lists) For thousands of addresses, click the [UPLOAD CSV] button. Prepare a .txt or .csv file with the same format as above (address space amount).
⚠️ VITAL PROTOCOL NOTE: The system automatically handles token decimals. If you write "100", the user gets exactly 100 tokens.
STEP 2: Calculation & Security Check
Click [CALCULATE]. The Munera Engine will:
Validate all addresses and amounts.
Generate the cryptographic Merkle Root.
Upload the secure manifest to IPFS decentralized storage.
Once complete, you will see the "Manifest Ready" status.
STEP 3: Deployment Sequence
Click [DEPLOY PROTOCOL]. Your wallet will prompt for two transactions:
Approval Matrix: Granting permission for the Munera Factory to move the exact total amount of tokens from your wallet.
Genesis Transaction: The actual creation of your Munera Distributor contract on the blockchain.
Once deployed, share the generated Contract Address with your community!
⚙️ MANAGING YOUR DROP (Manage Tab)
Expanding the List (Update Root): Forgot someone? No problem.
Paste your NEW, COMPLETE list (including old users + new users).
Click [GENERATE ROOT].
The system calculates the difference. Click [INJECT DEFICIT] to fund only the new tokens required.
Click [UPDATE PROTOCOL] to set the new root on-chain.
Emergency Withdraw: Campaign over? As the admin, use the red [WITHDRAW FUNDS] button to pull all unclaimed tokens back to your wallet instantly.
💎 FOR CLAIMERS (The Beneficiaries)
Claiming via Munera is passive and automatic. You do not need links or codes.
How to Secure Your Assets:
Connect: Link your wallet to the Munera Interface.
Auto-Scan: Navigate to the [CLAIM] tab. The protocol automatically scans the blockchain for any active Munera deployments where your address is listed.
Execute: If eligible drops are found, they will appear as cards showing the token symbol and amount. Click [CLAIM NOW] and confirm the transaction.
Scanning Status:
Verified (Cyan): Tokens are waiting for you.
Secured (Green): You have already successfully claimed these tokens.
No Pending Claims: Your current wallet is not in any active distribution lists.
