feat: add `dot tx --batch` for submitting multiple transactions

Context

On-chain workflows frequently require submitting multiple transactions in sequence. Examples:

• Uploading chunked evidence data (dozens of TransactionStorage.store calls)
• Multi-step candidacy flows (apply, commit, allocate, submit)
• Batch operations across accounts

Currently, each transaction is a separate dot tx invocation that establishes a new connection, fetches metadata, signs, submits, and waits for finalization. For workflows with many sequential transactions, this overhead dominates.

Proposal

Add a --batch mode to dot tx that reads a list of transactions from a JSON file and submits them sequentially over a single connection:

Batch File Format

[
  {
    "call": "ProofOfInk.apply",
    "args": [],
    "chain": "people"
  },
  {
    "call": "ProofOfInk.commit",
    "args": [{"choice": {"type": "ProceduralAccount", "value": 0}}],
    "chain": "people"
  },
  {
    "call": "TransactionStorage.store",
    "args": ["0xdeadbeef..."],
    "chain": "bulletin"
  }
]

Usage

# Submit all transactions in sequence
dot tx --batch ./workflow.json --from candidate

# Dry-run to estimate total fees
dot tx --batch ./workflow.json --from candidate --dry-run

# Continue from a specific index (resume after failure)
dot tx --batch ./workflow.json --from candidate --start-at 5

Output

Progressive output showing each transaction's status:

Batch: 3 transactions from ./workflow.json

[1/3] ProofOfInk.apply (people)
  Tx:     0xabc123...
  Block:  #1234
  Status: ok

[2/3] ProofOfInk.commit (people)
  Tx:     0xdef456...
  Block:  #1235
  Status: ok

[3/3] TransactionStorage.store (bulletin)
  Tx:     0x789abc...
  Block:  #5678
  Status: ok

Batch complete: 3/3 succeeded

With --output json:

{
  "total": 3,
  "succeeded": 3,
  "failed": 0,
  "results": [
    { "index": 0, "call": "ProofOfInk.apply", "chain": "people", "txHash": "0xabc...", "block": 1234, "status": "ok" },
    ...
  ]
}

Design Considerations

Sequential vs Parallel Submission

• Default: Sequential (wait for finalization of each before submitting next). Safest, respects state dependencies.
• --parallel flag: Submit all at once with incrementing nonces. Faster but only safe for independent transactions on the same chain.
• --wait-for best_block vs --wait-for finalized: Configurable finality requirement per batch.

Cross-Chain Batches

When a batch contains transactions for different chains:

• Group by chain to reuse connections
• Maintain sequential ordering across chains
• Support --chain override per-entry in the JSON

Error Handling

• --stop-on-error (default): Stop batch on first failure, report index
• --continue-on-error: Continue with remaining transactions, report all results
• Resume: --start-at <index> to skip already-completed transactions

On-Chain Batch Alternative

Note: For multiple calls on the same chain, users can also use Utility.batchAll:

dot tx Utility.batchAll '[call1, call2, ...]' --from candidate --chain people

This is atomic (all-or-nothing) but limited to a single chain and a single block. The --batch flag handles cross-chain workflows, long sequences, and gives per-transaction feedback.

Implementation Notes

• Reuse a single ClientHandle per chain across the batch
• Parse the batch file with Bun.file()
• Nonce management: let polkadot-api handle nonces for sequential mode; explicit nonce offsets for parallel mode
• Consider supporting batch file generation from other commands (e.g., dot tx ... --dry-run --emit-batch appends to a batch file)

Why This Matters for Agent Workflows

An AI agent executing the DIM1 runbook could:

1. Generate a batch file with all required transactions
2. Submit it in one command instead of 30+ individual calls
3. Get a structured result to verify all steps completed

This is especially critical for Step F (evidence upload) which may require 30+ chunk upload transactions.

Labels

enhancement, agent-readiness

Start at the existing dot tx command entry point and trace how it creates a ClientHandle, parses arguments, submits transactions, and waits for finalization. Review the proposed Bun.file() batch format and determine how sequential, cross-chain, dry-run, resume, error-handling, and output requirements fit together. Done means the batch workflow and its documented options behave as specified, with structured results for each transaction.