feat: stream withdrawal validation, factory cancel verification, fee documentation, and migration bounds (#621, #622, #623, #624)

[thefadah]

Summary of Changes

This unified PR resolves issues #621, #622, #623, and #624:

1. Issue stream: withdraw() has no dry-run/preview variant separate from withdrawable() #621 — stream: Dry-run withdrawal preview query (validate_withdraw)

   • Added read-only pub fn validate_withdraw(env: Env, amount: i128) -> Result<(), Error> to contracts/stream/src/lib.rs.
   • Executes exact pre-transfer validation checks identical to withdraw() (positive amount check, non-cancelled stream state, minimum withdrawal rate-limit interval, entitlement accrual, token balance availability, and split arithmetic validation) without mutating storage or transferring tokens.
   • Added unit tests covering positive validations, zero/negative amounts, zero-elapsed start state, cancelled streams, and rate limit intervals.

2. Issue factory: record_cancel() has no auth check and no stream identifier — callable by anyone, any number of times #622 — factory: Stream verification and idempotency for record_cancel

   • Updated pub fn record_cancel(env: Env, stream: Address) in contracts/factory/src/lib.rs to take the stream contract address.
   • Enforced verification that stream is a legitimate deployed stream (IsKnownStream), that it is currently in a cancelled state (stream.info().is_cancelled()), and that its cancellation has not already been recorded in CancelledStream(stream) storage.
   • Updated cancel_batch_streams to record CancelledStream(stream) to ensure direct or subsequent record_cancel calls do not double decrement.
   • Updated docs/security.md and added unit tests covering unverified addresses, active streams, once-only decrements, and idempotency.

3. Issue factory: estimate_fee() returns fully hardcoded constants — the _env parameter is unused #623 — factory: estimate_fee documentation and variant test coverage

   • Added doc comments on estimate_fee() documenting that returned CPU instructions and ledger entries are baseline profiling reference estimates for standard deployments, preserving _env for interface uniformity and potential dynamic fee adjustments.
   • Added comprehensive unit tests in contracts/factory/src/tests.rs verifying positive fee estimates and ledger entries across all 13 StreamOperation variants.

4. Issue factory: migrate_sender_index/migrate_recipient_index are permissionless with no cost bound on repeated calls #624 — factory: Migration page cap and already-migrated short-circuit

   • Defined MAX_MIGRATION_PAGES = 20 to cap caller-supplied max_pages in contracts/factory/src/index.rs.
   • Added short-circuiting to early return when an address index has already completed migration (!has(legacy_key) or cursor >= legacy_count), avoiding redundant page scans and unbounded transaction resource consumption.
   • Added unit tests verifying capped migration and early-exit no-ops.

---

Closes #621
Closes #622
Closes #623
Closes #624

[drips-wave]

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