feat: implement Merkle Tree Bulk Initialization for vesting schedules

[BarryArinze]

🧩 Overview

This PR implements Merkle Tree Bulk Initialization for vesting schedules by adding an initialize_merkle_root function.

Instead of individually storing thousands of vesting schedules on-chain, the contract now stores a single 32-byte Merkle root representing all approved beneficiaries and schedules. Beneficiaries can later submit a valid Merkle Proof to activate their schedule and claim vested tokens.

This architecture dramatically reduces initialization/storage costs for large token distributions on Stellar.

⚙️ Key Features

• Added initialize_merkle_root(bytes32 root) admin function
• Stores a single Merkle root for bulk vesting allocations
• Added Merkle proof verification flow for beneficiaries
• Users can activate schedules with valid proofs
• Activated schedules integrate with existing claim logic
• Duplicate claims / duplicate activations prevented

🏗️ Implementation Details

Merkle Leaf Data Includes:

• beneficiary address
• token allocation
• vesting start timestamp
• cliff duration
• vesting duration
• category / tranche
• unique index or nonce

Contract Flow

1. Admin initializes Merkle root
2. User submits:
   • leaf data
   • Merkle proof
3. Contract verifies proof against stored root
4. If valid:
   • schedule activates
   • claiming becomes available

⛽ Gas Optimization Benefits

Previous Model

• 1,000+ schedules stored individually
• High initialization cost
• Expensive storage writes

New Model

• One root hash stored on-chain
• Users self-activate only when needed
• Significantly reduced deployment/setup cost
• Better scalability for mass distributions

🔐 Security Considerations

• Invalid proofs revert
• Duplicate leaf activation blocked
• Root initialization restricted to authorized role
• Existing claim accounting preserved
• Proof verification deterministic and tamper-resistant

🧪 Testing

Added coverage for:

• Root initialization success path
• Unauthorized root initialization revert
• Valid proof activation
• Invalid proof rejection
• Duplicate activation prevention
• Claim after activation
• Multiple users from same root

🚀 Impact

• Enables scalable airdrops and vesting campaigns
• Major gas/storage savings
• Cleaner architecture for large allocations
• Improved user-triggered activation model

🔗 Related Issue

Closes #199

🏷️ Labels

cryptography, gas-optimization, architecture

[drips-wave]

@BarryArinze 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! 🚀

Learn more about application limits