feat: MAX_BATCH_SIZE, batch_fill/cancel_intent, and resource analysis…

[Keengfk]

feat: declare MAX_BATCH_SIZE, add batch_fill/cancel_intent, and document batch
resource limits (#149)

───────────────────────────────────────────────────────────────────────────────

MAX_BATCH_SIZE was referenced across four batch functions but never declared,
meaning the contract wouldn't compile. This PR defines it — along with three
other undeclared constants — adds the two missing batch entrypoints, and
delivers the write-entry analysis that justifies the chosen limit.

Constants declared

All four were in use but missing from the constants section:

┌────────────────────────┬────────┬─────────────────────────────────────────┐
│ Constant │ Value │ Rationale │
├────────────────────────┼────────┼─────────────────────────────────────────┤
│ MAX_BATCH_SIZE │ 10 │ Derived from per-item write-entry │
│ │ │ analysis; see §3 in docs/149 │
├────────────────────────┼────────┼─────────────────────────────────────────┤
│ SLASH_COOLDOWN │ 3600 s │ Confirmed by existing test that passes │
│ │ │ time 3600 s and expects success │
├────────────────────────┼────────┼─────────────────────────────────────────┤
│ MAX_EXTENSION_DURATION │ 300 s │ One full fill window; matches │
│ │ │ FILL_WINDOW │
├────────────────────────┼────────┼─────────────────────────────────────────┤
│ CANCEL_COOLDOWN │ 60 s │ Short enough not to inconvenience │
│ │ │ legitimate users; long enough to deter │
│ │ │ spam │
└────────────────────────┴────────┴─────────────────────────────────────────┘

DataKey variants declared

13 variants were referenced throughout the contract but absent from the enum
(would fail to compile): CancelCooldown, ExtensionGranted, Config, UserIntents,
AllowedDstTokenList, MinBondMultiplier, BidWindowEnabled, PendingAdmin,
PendingDstTokenAdd, PendingDstTokenRemove, AllowedSrcChain,
SrcChainAllowlistEnabled, UserNonce. Each is documented inline with its storage
tier and semantics.

Batch functions added

batch_fill_intent(env, solver, Vec<(BytesN<32>, i128)>) and
batch_cancel_intent(env, user, Vec<BytesN<32>>) — both follow the same pattern
as the existing batch_submit_intent and batch_accept_intent: bounded by
MAX_BATCH_SIZE, atomic (a failure on any item reverts the whole batch), with a
doc comment linking to the resource analysis.

MAX_BATCH_SIZE justification (docs/149 §3)

The binding constraint is the mainnet 200 written-entries-per-transaction cap
(Protocol 27). fill_intent is the most expensive batched operation:

┌───────┬─────────────────┐
│ Entry │ Writes per item │
├───────┼─────────────────┤
│ │ │
├─────────────────────────┼─────────────────┤
│ │ │
├──────────────────────────────┼─────────────────┤
│ │ │
├─────────────────────────────────────────────────────────┼─────────────────┤
│ │ │
└─────────────────────────────────────────────────────────┴─────────────────┘

At MAX_BATCH_SIZE = 10: ≤ 51 writes against a 200-entry limit — over 70%
headroom. This margin covers future additions to fill_intent's footprint,
Soroban host overhead, and a potential limit reduction after a validator vote.
All four batch operations are compared in a table; fill_intent dominates, so
the limit is safe for all of them.

Tests added

Five tests under // ─── #149: batch boundary stress tests in test.rs:

• batch_fill_intent_at_max_batch_size_completes — submits, accepts, and fills
  exactly MAX_BATCH_SIZE intents in one batch call; asserts all end Filled and
  solver's fills_completed equals MAX_BATCH_SIZE
• batch_cancel_intent_at_max_batch_size_completes — cancels MAX_BATCH_SIZE
  intents (one per distinct user to avoid CANCEL_COOLDOWN collision within the
  batch)
• batch_cancel_single_user_trips_cancel_cooldown_after_first_item — documents
  and asserts that a single user cannot cancel two intents in one batch call
  because CANCEL_COOLDOWN fires on the second item
• batch_fill_intent_over_limit_rejected — MAX_BATCH_SIZE + 1 items is rejected
• batch_cancel_intent_over_limit_rejected — same for batch_cancel_intent

What's still TBD

Per-entrypoint CPU-instruction numbers remain TBD in docs/149 §5 — they require
the resource-benchmarking harness (tracked separately). The write-entry
analysis is the complete deliverable for this issue's "verify the limit is
safe" requirement.

closes #277

[drips-wave]

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