New update Closes #58

[Enniwealth]

Build Resumable Batch Payment / Airdrop Engine with Checkpointing and Fee-Bump Retry (starforge batch)

Closes #58

Summary

This PR adds a first-class starforge batch command for safe, resumable CSV payouts (airdrops, contributor payments, faucet campaigns). It expands src/utils/tx_batch.rs into a full batch engine with CSV parsing/validation, operation chunking (100 ops/tx), atomic checkpoint files, and fee-bump / sequence retry on submission failures.
New commands:

• starforge batch pay --file recipients.csv --wallet payer --network testnet [--dry-run]
• starforge batch status --file recipients.csv
• starforge batch resume --file recipients.csv --wallet payer --network testnet
  Key behavior:
• Validates every CSV row up front (Stellar address checksum via stellar-strkey, amount format, asset format)
• --dry-run reports total cost (fees + amounts) with read-only balance validation — no transactions submitted
• Writes <file>.batch-state.json atomically after each confirmed transaction chunk
• Re-running batch pay auto-detects the checkpoint and resumes from the first pending row
• Failed chunks are retried with fee-bump / sequence refresh (up to --max-retries, default 3) before rows are marked failed; remaining chunks continue
• Already-confirmed rows are never resubmitted

Changes

Area	Details
src/utils/tx_batch.rs	CSV parser, row validation, chunking, checkpoint read/write, batch execution engine, unit tests
src/commands/batch.rs	pay / status / resume subcommands with confirmation flow
src/utils/horizon.rs	submit_payment_with_retry, fetch_transaction_by_hash, post_signed_transaction refactor
src/main.rs, commands/mod.rs, command_tree.rs	CLI wiring
Cargo.toml	csv dependency
README.md	Worked example (CSV format, sample run, resume after interruption)

Problem Statement

src/utils/tx_batch.rs previously provided only a minimal helper for grouping operations into a transaction. There was no supported workflow for paying out hundreds or thousands of recipients from a CSV file (e.g., a token airdrop, contributor payout, or testnet faucet campaign). Doing this safely required hand-rolling sequence number management, chunking operations into valid transaction sizes, handling partial failures, and manually tracking which recipients were already paid — with a real risk of double-paying or silently skipping recipients if the process crashed midway.

Proposed Solution

Build a first-class starforge batch pay command that turns a CSV of destination,amount,asset[,memo] rows into a safe, resumable, auditable payment run:

• starforge batch pay --file recipients.csv --wallet payer --network testnet [--dry-run] — validates every row (address checksum, asset existence, amount format) before submitting anything, and reports total cost (fees + amounts) up front.

• Operations are automatically chunked into the maximum operations-per-transaction Stellar allows, with sequence numbers reserved and incremented locally to avoid tx_bad_seq races.

• A checkpoint file (<file>.batch-state.json) records the status of every row (pending, submitted, confirmed, failed) as the run progresses, written atomically after each transaction confirms.

• If the process is interrupted or crashes, re-running the same command detects the checkpoint file and resumes from the first pending row — already-confirmed rows are never resubmitted.

• Failed transactions (e.g., insufficient fee, transient network error) are retried with fee-bump transactions, reusing the existing fee-bump/sequence-retry logic already shipped for single transactions, up to a configurable retry limit before being marked failed for manual review.

• starforge batch status --file recipients.csv — prints a summary (counts by status, total paid, total failed) from the checkpoint file without submitting anything.

• starforge batch resume --file recipients.csv — explicit resume entry point in addition to auto-detection.

Example Usage

CSV format (destination,amount,asset[,memo]):

destination,amount,asset,memo
GABC...XYZ,10,XLM,contributor-q1
GDEF...UVW,25,USDC:GISSUER...,payout

Sample run:

# Validate recipients and show total cost without submitting anything
starforge batch pay --file recipients.csv --wallet payer --network testnet --dry-run
# Execute the payout (writes recipients.csv.batch-state.json as it progresses)
starforge batch pay --file recipients.csv --wallet payer --network testnet
# Check progress without submitting
starforge batch status --file recipients.csv
# Resume after interruption (also auto-detected when re-running batch pay)
starforge batch resume --file recipients.csv --wallet payer --network testnet

If the process is killed mid-run, re-run the same batch pay command or use batch resume. Already-confirmed rows are never resubmitted; the checkpoint file records each row as pending, submitted, confirmed, or failed.

Acceptance Criteria

• A 1,000-row CSV payout completes correctly when the process is killed and resumed at least twice during the run, with no recipient paid twice and no recipient skipped.
• --dry-run reports accurate total cost without submitting any transaction.
• Failure of a single row does not abort the remainder of the batch.
• Documentation includes a worked example (airdrop CSV format, sample run, sample resume after interruption).

Test Plan

• cargo build succeeds
• starforge batch pay --file recipients.csv --wallet payer --network testnet --dry-run validates all rows and prints cost without submitting
• Live payout of a small CSV completes and writes recipients.csv.batch-state.json
• Kill the process mid-run, then starforge batch resume — confirmed rows are not double-paid, pending rows complete
• starforge batch status --file recipients.csv shows correct counts by status
• A single failed chunk does not abort the rest of the batch
• Unit tests in tx_batch.rs: CSV edge cases, chunk boundaries (101 rows → 2 txs), checkpoint resume, retry-then-fail accounting