Problem Statement
src/utils/tx_batch.rs currently provides only a minimal helper for grouping operations into a transaction. There is no supported workflow for a common real-world task: 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 today requires a developer to hand-roll sequence number management, chunk operations into valid transaction sizes, handle partial failures, and manually track which recipients were already paid — with a real risk of double-paying or silently skipping recipients if the process crashes 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.
Technical Scope
- Expand
src/utils/tx_batch.rs into a proper batch engine: CSV parsing/validation, chunking strategy, checkpoint read/write (atomic, matching the existing atomic-config-write pattern), retry/backoff integration with fee bumping.
- New
src/commands/batch.rs for the pay / status / resume subcommands.
- Dry-run mode must not touch the network beyond read-only balance/asset validation.
- Comprehensive tests: CSV validation edge cases, chunk-size boundary conditions, checkpoint resume after a simulated crash mid-run, and retry-then-fail accounting.
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).
Estimated Scope
Approximately 700 lines of new and modified Rust across the batch engine, CLI command, and tests.
Problem Statement
src/utils/tx_batch.rscurrently provides only a minimal helper for grouping operations into a transaction. There is no supported workflow for a common real-world task: 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 today requires a developer to hand-roll sequence number management, chunk operations into valid transaction sizes, handle partial failures, and manually track which recipients were already paid — with a real risk of double-paying or silently skipping recipients if the process crashes midway.Proposed Solution
Build a first-class
starforge batch paycommand that turns a CSV ofdestination,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.tx_bad_seqraces.<file>.batch-state.json) records the status of every row (pending,submitted,confirmed,failed) as the run progresses, written atomically after each transaction confirms.pendingrow — already-confirmed rows are never resubmitted.failedfor 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.Technical Scope
src/utils/tx_batch.rsinto a proper batch engine: CSV parsing/validation, chunking strategy, checkpoint read/write (atomic, matching the existing atomic-config-write pattern), retry/backoff integration with fee bumping.src/commands/batch.rsfor thepay/status/resumesubcommands.Acceptance Criteria
--dry-runreports accurate total cost without submitting any transaction.Estimated Scope
Approximately 700 lines of new and modified Rust across the batch engine, CLI command, and tests.