feat(token): add batch_mint() function for multi-recipient minting

[ACodehunter]

Summary

Adds a batch_mint() function to the token contract for efficient multi-recipient minting, as specified in Issue #12. This enables gas-efficient token distributions and airdrops.

Problem

Currently, minting to multiple addresses requires separate transactions for each recipient. This is expensive on gas and slow for initial token distributions or airdrops.

Solution

Implemented batch_mint() that mints tokens to multiple recipients in a single atomic transaction.

Changes

Contract Updates (lib.rs)

New Types

• Recipient struct: Type-safe representation of mint recipients with address and amount

New Functions

• batch_mint(recipients: Vec<Recipient>): Mint to multiple recipients atomically
  • Admin-only access control
  • Paused contract check
  • Validates all amounts are positive (full revert on any invalid entry)
  • Emits individual mint events per recipient for off-chain indexing
  • Updates total supply atomically once at the end

SDK Updates (client.ts)

• batchMint(recipients: [string, bigint][], source: Keypair): SDK wrapper for batch minting
  • Accepts array of [address, amount] tuples
  • Handles ScVal conversion internally

Tests (test.rs)

Added 8 comprehensive tests:

Success Cases

1. ✅ Single recipient: Works with 1 recipient
2. ✅ Five recipients: Works with 5 recipients
3. ✅ Ten recipients: Works with 10 recipients

Failure Cases

4. ✅ Empty list: Panics with "recipients list cannot be empty"
5. ✅ Zero amount: Full revert with "mint amount must be positive"
6. ✅ Negative amount: Full revert with "mint amount must be positive"
7. ✅ Paused state: Panics with "contract is paused"

Supply Verification

8. ✅ Atomic supply update: Supply is correct after batch mint

Acceptance Criteria

• ✅ batch_mint() works with 1, 5, and 10 recipients
• ✅ Single invalid entry (0 or negative amount) causes full revert
• ✅ Supply is correct after batch mint
• ✅ SDK method added and documented
• ✅ Tests cover success, partial failure, empty list, and paused state

Implementation Details

Two-Pass Validation

The function uses a two-pass approach:

1. First pass: Validate all amounts are positive
2. Second pass: Perform all mints and calculate total

This ensures atomicity - if any recipient has an invalid amount, the entire batch reverts before any state changes.

Gas Efficiency

• Single transaction overhead instead of N transactions
• Single supply update at the end
• Individual events for indexing without blocking execution

Event Emissions

Each recipient gets their own mint event with:

• Admin address
• Recipient address
• Amount minted
• New balance
• Running supply total

This allows indexers to track individual mints within a batch.

Usage Example

Contract (Rust)

let recipients = vec![
    &env,
    Recipient { address: addr1, amount: 1000 },
    Recipient { address: addr2, amount: 2000 },
    Recipient { address: addr3, amount: 3000 },
];
contract.batch_mint(&recipients);

SDK (TypeScript)

await client.batchMint([
    ['GADDR1...', BigInt(1000)],
    ['GADDR2...', BigInt(2000)],
    ['GADDR3...', BigInt(3000)],
], adminKeypair);

Use Cases

• Token Launch: Initial distribution to founding team and investors
• Airdrops: Distribute tokens to community members
• Rewards: Batch reward distribution
• Testing: Quick setup of multiple token holders for testing

Closes #12

[drips-wave]

@ACodehunter 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

[p3ris0n]

@ACodehunter please fix issues