feat: stream checkpoints, recipient hook, withdrawal cooldown, dispute lock (#458, #459, #460, #461)

[frienzy514-png]

Summary

Implements the four assigned issues on the stream contract:

• Closes Implement stream checkpoint storage to record periodic withdrawal snapshots #458 — Stream checkpoint storage (periodic withdrawal snapshots)
• Closes Add stream recipient notification hook via cross-contract call on first withdrawal #459 — Recipient notification hook on first withdrawal (cross-contract call)
• Closes Implement configurable withdrawal cooldown period between consecutive withdrawals #460 — Configurable per-stream withdrawal cooldown
• Closes Add stream locking mechanism to prevent modifications during active dispute window #461 — Time-bounded dispute lock (blocks pause/transfer/cancel/rate-update)

#458 — Stream checkpoint storage

• checkpoint_stream(stream_id) — permissionless; records (ledger, timestamp, cumulative_withdrawn) if the configured interval (default 100 ledgers) has elapsed since the last checkpoint.
• withdraw() also opportunistically checkpoints once due, so normal usage rarely needs an explicit call.
• get_checkpoint_count, get_checkpoint(id, index), get_checkpoint_interval / set_checkpoint_interval (admin).

#459 — Recipient notification hook

• set_recipient_hook(sender, stream_id, hook_contract, hook_function) — sender-only, only before any withdrawal has occurred.
• On the stream's first withdrawal, hook_function(stream_id, recipient, amount) is invoked on hook_contract via try_invoke_contract — best-effort: a failing or missing hook never blocks the withdrawal, it just emits RecipientHookFailed instead of RecipientHookSuccess.
• clear_recipient_hook, get_recipient_hook.

#460 — Per-stream withdrawal cooldown

• New create_stream_with_cooldown(...) entry point (see note below on why it's separate) sets a minimum number of seconds between consecutive withdrawals by the recipient.
• withdraw() enforces whichever of the per-stream cooldown and the existing protocol-wide cooldown is stricter.
• get_stream_withdrawal_cooldown.

#461 — Dispute lock

• lock_stream_for_dispute(stream_id, lock_duration_ledgers) — admin-only; blocks pause_stream, cancel_stream, transfer_recipient, and update_stream_rate on that stream until the ledger window elapses. No unlock call is needed — enforcement just compares against the current ledger sequence, so it expires automatically.
• clear_dispute_lock (admin, lifts it early), is_dispute_locked.
• withdraw() and the contract-wide emergency_pause are intentionally unaffected.

All four features are additive and opt-in — no existing entry point's default behavior changes. New state lives in dedicated storage keys rather than new Stream fields, since Stream was already at the 40-field cap for #[contracttype] structs (see below).

Pre-existing breakage fixed first (separate commit)

Before any of the above, main did not compile — cargo check -p sorostream-stream failed with 28 errors (duplicate StreamError variants/discriminants exceeding the 50-variant cap, Stream at 43 fields exceeding the 40-field cap, create_stream exceeding Soroban's 10-parameter limit, several call sites out of sync with function signatures, get_protocol_stats using std Vec APIs unavailable on soroban_sdk::Vec, and more), and the test suite couldn't compile at all on top of that. This is unrelated to #458–461 — it's baked into the repo's sole initial commit — but had to be fixed for anything here to be buildable or testable. See the first commit's message for the full list; it's isolated from the feature commit so it's easy to review separately.

Two tests that assumed an unimplemented set_creation_tax admin function are now #[ignore]d with an explanatory reason (implementing that function is its own, unrelated feature).

Testing

• cargo check -p sorostream-stream — clean
• cargo test -p sorostream-stream --lib — 47 passed, 2 ignored (documented pre-existing gap), 0 failed
• cargo clippy -p sorostream-stream --lib --tests — 0 errors (a few pre-existing, unrelated warnings remain)
• cargo build -p sorostream-stream --target wasm32-unknown-unknown --release — succeeds

12 new integration tests cover each feature's happy path, error path, and interaction with withdraw().

Notes on design choices

• create_stream wasn't extended for Implement configurable withdrawal cooldown period between consecutive withdrawals #460. It was already at Soroban's hard 10-parameter-per-function limit (fixing that pre-existing overflow is part of the first commit). Rather than reshuffle its signature further, the cooldown ships as a new create_stream_with_cooldown entry point that delegates to create_stream internally, matching the existing pattern of create_stream_scheduled / create_stream_with_milestones.
• New Stream struct fields were avoided everywhere (checkpoints, the hook, the cooldown, the dispute lock) since Stream is already at the 40-field cap. Also worth knowing for future work on this contract: Option<T> for a custom #[contracttype] (or a tuple) does not round-trip through ScVal in this soroban-sdk version when nested inside another #[contracttype] struct field — it compiles under cargo check but breaks cargo test's client codegen. Hit this while freeing up field-count headroom in the first commit; documented inline where it matters (StreamQueryFilter.status).

[drips-wave]

@frienzy514-png 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

[frienzy514-png]

resolved