ABI and accrual semantics

The stream clock

Everything is expressed against a clock that belongs to the stream and stops while the stream is paused:

stream_time = (paused_at ?? now) - paused_total

elapsed  = clamp(stream_time, start_time, end_time) - start_time
duration = end_time - start_time
vested   = 0                                    if stream_time < cliff_time
         = deposited × elapsed / duration       otherwise, rounding down

Reading paused_at is what makes the freeze actually freeze. The obvious alternative — treating the effective end asend_time + paused_total and comparing againstnow — is correct only after a resume. While a pause is still open, the current interval has not yet been added to paused_total, so that expression keeps advancing and the stream keeps accruing while supposedly frozen.

Pause stretches the schedule; it does not shorten it

Pausing freezes accrual and pushes the effective end forward by the paused duration. Total value delivered is unchanged — the schedule simply takes longer in wall-clock terms. The recipient can still withdraw while paused: pausing stops accrual, not access to what was already earned.

A pause spanning the cliff defers the cliff too

This is the subtlest interaction in the contract and the easiest thing to get wrong in a client. The cliff is gated onstream time, not wall-clock time. A stream that is frozen when its cliff date passes does not silently unlock.

That last point is the general rule: the cliff gates the payout, it does not delay accrual. Value accrues from start_time throughout; the cliff only decides when it becomes withdrawable. Passcliff_time == start_time for no cliff, orcliff_time == end_time for a single lump sum at maturity.

Cancellation settles exactly, and stays distinguishable

Cancelling computes vested at that instant, refundsdeposited − vested to the sender, then rewrites the schedule so the stream looks like one that matured:deposited drops to the vested amount andend_time is pulled back to the current point on the stream clock. Every later call clamps to the reduced deposit, sowithdraw needs no special case.

Cancelling a paused stream settles against the frozen clock, not the wall clock. Cancelling before the cliff refunds everything, because pre-cliff the entitlement is zero by definition.

Cancelled is sticky. A cancelled stream drained to zero stays cancelled; it never becomesdepleted. The two terminal states answer different questions — depleted means it ran to term and the recipient took everything, cancelled means the sender clawed back the remainder — so do not collapse them in a projection.

Top-up extends the duration and holds the rate

The per-second rate agreed at creation never changes;end_time moves forward byamount / rate instead. Holding the rate fixed is what makes a top-up safe to accept from an untrusted sender: it can neither accelerate nor dilute an existing schedule.

The extension rounds down, which is load-bearing rather than cosmetic. Rounding up would make the new duration slightly longer than exact, lowering the rate and thereforeretroactively reducing the amount already vested — breaking I3, letting withdrawn exceedvested, and letting a later cancel refund the sender tokens the recipient already held. A top-up too small to buy one second of schedule is rejected withTopUpTooSmall rather than absorbed by raising the rate.

Archived streams

Persistent entries expire. If a stream's entry is archived the tokens are not lost — they remain in the pooled balance — but the accounting entry is unreadable until restored.stream_exists(id) == false whileid < stream_count() is the signal: that stream has been archived, not that it never existed. Surface a restore action rather than an error. Every mutating call re-extends its entry's rent, and extend_stream_ttl is permissionless, so an actively used or swept stream will not reach this state.