feat: Add Airdrop Distribution Agent

[dagangtj]

Overview

Implements an Airdrop Distribution Agent that automates token airdrops using the PayPol MultisendVaultV2 contract on Tempo L1.

Changes

• ✅ Created agents/airdrop-distributor/ from template
• ✅ Implemented batch distribution (up to 100 recipients per tx)
• ✅ Address validation (checksummed, non-zero)
• ✅ Balance checking before execution
• ✅ Dry-run mode for cost estimation
• ✅ Detailed per-recipient receipts with tx status
• ✅ CSV and JSON input format support
• ✅ Multi-token support (AlphaUSD, pathUSD, etc.)
• ✅ Graceful error handling with validation messages

Acceptance Criteria

• Agent registers on the PayPol marketplace
• Accepts recipient list in CSV or JSON format via job payload
• Validates all addresses (checksummed, non-zero)
• Calculates total distribution amount and checks treasury balance
• Executes batch transfers via MultisendVault contract
• Returns detailed receipt with tx hashes and per-recipient status
• Handles partial failures gracefully (some addresses may fail)
• Supports dry-run mode (estimate without executing)

Example Usage

JSON Format

{
  "prompt": "Distribute 1000 AlphaUSD to community members",
  "payload": {
    "token": "AlphaUSD",
    "recipients": [
      {"address": "0xabc...", "amount": "500"},
      {"address": "0xdef...", "amount": "300"},
      {"address": "0x123...", "amount": "200"}
    ],
    "dryRun": false
  }
}

CSV Format

{
  "prompt": "Airdrop from CSV",
  "payload": {
    "token": "AlphaUSD",
    "csv": "address,amount\n0xabc...,500\n0xdef...,300",
    "dryRun": false
  }
}

Testing

cd agents/airdrop-distributor
npm install
npm run dev

# Test with dry run
curl -X POST http://localhost:3002/execute \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Test", "payload": {"token": "AlphaUSD", "recipients": [{"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "amount": "10"}], "dryRun": true}}'

Contract Integration

Uses PayPolMultisendVaultV2 at 0x6A467Cd4156093bB528e448C04366586a1052Fab:

• executeMultiTokenBatch() for batch transfers
• getVaultBalance() for balance checks
• Emits IndividualTransfer events for per-recipient tracking

Author

@dagangtj

Closes #4