feat(soroban-contracts): Add Merkle distributor contract for proof-based airdrops (#248) - #284
Merged
manoahLinks merged 2 commits intoApr 27, 2026
Conversation
… for airdrops (crowdpass-live#248) Implements a Soroban smart contract that distributes tokens to eligible recipients using Merkle proof verification — the canonical pattern for gas-efficient, permissionless airdrops. ## Contract design - Merkle root is committed at initialization; only recipients whose (address, amount) pair is included in the tree can claim. - Leaf encoding: SHA-256( sha256(address_str) ‖ amount_u64_le ) - Proof verification: sorted-pair hashing at every node, matching the most common off-chain Merkle tree libraries. ## Features - Single-claim guard: each index stored in persistent storage; double claims are rejected with AlreadyClaimed. - Multi-token support: any SEP-41 / Soroban token address. - Expiry: optional UNIX timestamp; claims blocked after expiry. - Sweep: admin can recover unclaimed tokens after expiry. - Fund: any approved address can top-up the distributor balance. - Checks-Effects-Interactions: claim flag set before token transfer. - Upgradeable: inherits project-wide time-lock upgrade pattern. - Rich events: Claimed, Swept. ## Tests (17 / 17 pass) - Initialization: success, double-init guard - Single-leaf tree: happy path, double-claim, invalid proof, wrong amount - Two-leaf tree: both recipients claim, wrong-index rejection - Four-leaf tree: all 4 recipients claim in sequence - Expiry: claim before/after expiry, set_expiry query - Sweep: after expiry, before expiry, no expiry configured - Fund: balance increases correctly - InsufficientBalance guard - is_claimed default false Closes crowdpass-live#248
|
@amankoli09 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements
MerkleDistributor, a Soroban smart contract that distributestokens to eligible recipients using Merkle proof verification — the
canonical pattern for gas-efficient, permissionless airdrops.
Closes #248
Changes
New contract:
soroban-contract/contracts/merkle_distributor/Cargo.tomlsoroban-sdk+upgradeablesrc/lib.rssrc/test.rsModified
soroban-contract/Cargo.toml— registeredmerkle_distributoras a workspace memberHow It Works
Leaf encoding