Batch Transfer

[allquantor]

Motivation:

This change introduces a Batch-Transfer action to the token blueprint. This functionality is essential for scenarios requiring multiple token transfers from a single sender, such as airdrops, payroll, or reward distributions. Performing these transfers individually is inefficient, incurs higher message overhead, and lacks atomicity guarantees across the entire set of transfers. The Batch-Transfer action addresses these issues by allowing multiple transfers to be processed within a single message, ensuring atomicity and reducing memory usage on the token process.

Implementation Details:

• A new handler is added for messages with Action = "Batch-Transfer".
• The handler expects a CSV-formatted string in the msg.Data field, where each line represents a transfer in the format recipient_address,quantity.
• CSV Parsing: A simple, dependency-free CSV parser is included directly within the handler. It splits the input data by newlines and then by commas. This parser is intentionally minimal and assumes valid input adhering strictly to the specified format (no headers, quotes, or escaped commas). It has been tested separately to ensure correctness for its specific use case.
• Validation: The parser validates each entry, ensuring both recipient and quantity are present, the quantity consists only of digits, and the quantity is greater than zero.
• Atomic Balance Check & Update:
  • The total quantity required for all transfers in the batch is calculated.
  • The sender's (msg.From) balance is checked against this total quantity.
  • If the balance is sufficient, all balance updates (debiting the sender, crediting all recipients) are performed atomically within the handler's execution. If the balance check fails, an error is returned, and no balances are changed.
• Notifications:
  • A single Batch-Debit-Notice is always sent back to the sender (via msg.reply). This notice includes the total number of transfers (Count), the total quantity transferred (Total), and crucially, a Batch-Transfer-Init-Id tag containing the msg.Id of the original Batch-Transfer message for easy traceability.
  • Conditional Credit Notices: Following the same principle as the standard Transfer action, individual Credit-Notice messages are sent to each recipient only if the initiating Batch-Transfer message does not include the Cast = true tag. If Cast is present, these individual notifications are suppressed (recommended behavior).
  • Any tags prefixed with X- on the original Batch-Transfer message are forwarded to both the Batch-Debit-Notice and any individual Credit-Notice messages sent.

Caveats:

• The CSV parser is basic and expects a strict format (recipient,quantity).