docs: add STREAM_MATH.md with worked examples and edge cases (#791) - #831
docs: add STREAM_MATH.md with worked examples and edge cases (#791)#831tilljack60-cmd wants to merge 1 commit into
Conversation
…ver#791) - Create docs/STREAM_MATH.md with full formula derivations, symbol table, two worked examples (1000 USDC 6-month claim, 9-month cancel), and five edge cases (before start, after end, cliff stream, instant cancel, zero-duration guard) - Add status rules reference table and implementation cross-reference - Link STREAM_MATH.md from README section 3 - Link STREAM_MATH.md from docs/CONTRACT_BINDINGS.md
|
@tilljack60-cmd is attempting to deploy a commit to the ritik4ever's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
@tilljack60-cmd 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! 🚀 |
📝 WalkthroughWalkthroughAdds ChangesStream math documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/STREAM_MATH.md`:
- Around line 458-460: Correct the `R` and `A_vested` row in
`docs/STREAM_MATH.md`: update the `claimable()` return-value reference to point
to the actual internal vesting calculation in `contracts/src/lib.rs`, or
describe these values as intermediate state rather than returned values. Leave
the other cross-reference rows unchanged.
- Around line 441-446: Update the status table in STREAM_MATH.md so the
active-state note uses R ∈ [0, 1) to include t = t_start, and explicitly state
that canceled takes precedence over the scheduled, active, and completed
time-based statuses, including when t ≥ t_end.
- Around line 419-420: Update the division-by-zero failure description for the
integer-arithmetic formula R = Δt / d in STREAM_MATH.md to remove NaN and state
only the applicable behavior: a runtime trap or panic. Preserve the surrounding
explanation and formula.
- Around line 40-42: Update the A_claimable definition in docs/STREAM_MATH.md,
including the corresponding repeated definition, to document the contract’s
zero-floor behavior using max(0, A_vested - A_claimed) rather than direct
subtraction. Keep the existing meaning that the result is withdrawable
immediately.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: c2b641bc-a7c5-4b68-90a8-397e14c419d3
📒 Files selected for processing (3)
README.mddocs/CONTRACT_BINDINGS.mddocs/STREAM_MATH.md
| | $A_{claimed}$ | number | Tokens the recipient has already withdrawn | | ||
| | $A_{claimable}$ | number | $A_{vested} - A_{claimed}$ — withdrawable right now | | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the contract’s zero-floor for claimable amounts.
contracts/src/lib.rs:382-387 returns max(0, vested - claimed), while this reference defines direct subtraction. Use the clamped formula consistently so the authoritative document matches on-chain behavior.
Proposed wording
-| $A_{claimable}$ | number | $A_{vested} - A_{claimed}$ — withdrawable right now |
+| $A_{claimable}$ | number | $\max(0, A_{vested} - A_{claimed})$ — withdrawable right now |
-$A_{claimable} = A_{vested} - A_{claimed}$
+$A_{claimable} = \max(0, A_{vested} - A_{claimed})Also applies to: 80-84
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/STREAM_MATH.md` around lines 40 - 42, Update the A_claimable definition
in docs/STREAM_MATH.md, including the corresponding repeated definition, to
document the contract’s zero-floor behavior using max(0, A_vested - A_claimed)
rather than direct subtraction. Keep the existing meaning that the result is
withdrawable immediately.
| Division by zero in $R = \Delta t / d$ would produce `NaN` or a runtime | ||
| panic. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove NaN from the integer-arithmetic failure description.
The contract stores amounts as i128; division by zero would trap/panic, not produce NaN. Describe the applicable integer failure mode.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/STREAM_MATH.md` around lines 419 - 420, Update the division-by-zero
failure description for the integer-arithmetic formula R = Δt / d in
STREAM_MATH.md to remove NaN and state only the applicable behavior: a runtime
trap or panic. Preserve the surrounding explanation and formula.
| | Status | Condition | Notes | | ||
| |---|---|---| | ||
| | `scheduled` | $t < t_{start}$ | Stream exists but vesting has not started | | ||
| | `active` | $t_{start} \le t < t_{end}$ | Vesting in progress; $R \in (0, 1)$ | | ||
| | `completed` | $t \ge t_{end}$ | Full amount vested; $R = 1$ | | ||
| | `canceled` | Explicit `cancel()` call | Frozen at $A_{vested\_at\_cancel}$; no further vesting | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify status boundaries and cancellation precedence.
active includes t = t_start, where R = 0, so the note should use R ∈ [0, 1). Also, a canceled stream can satisfy t ≥ t_end; explicitly state that canceled takes precedence over time-based statuses.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/STREAM_MATH.md` around lines 441 - 446, Update the status table in
STREAM_MATH.md so the active-state note uses R ∈ [0, 1) to include t = t_start,
and explicitly state that canceled takes precedence over the scheduled, active,
and completed time-based statuses, including when t ≥ t_end.
| | `Δt` clamp | `backend/src/services/streamStore.ts` | `contracts/src/lib.rs` → `claimable()` | | ||
| | `R` and `A_vested` | `streamStore.ts` `computeProgress()` | `claimable()` return value | | ||
| | `A_claimable` | `streamStore.ts` `computeProgress()` | `claimable()` | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Correct the contract cross-reference for R and A_vested.
contracts/src/lib.rs:382-387 shows that claimable() computes intermediate vesting state but returns only the final claimable i128; it does not return R or A_vested. Point this row to the actual internal vesting calculation, or describe those values as intermediate rather than return values.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/STREAM_MATH.md` around lines 458 - 460, Correct the `R` and `A_vested`
row in `docs/STREAM_MATH.md`: update the `claimable()` return-value reference to
point to the actual internal vesting calculation in `contracts/src/lib.rs`, or
describe these values as intermediate state rather than returned values. Leave
the other cross-reference rows unchanged.
|
Hi @tilljack60-cmd, This PR could not be merged because it has merge conflicts with the target branch. Please resolve the merge conflicts, push the updated changes, and the PR can be reviewed and merged. Thank you! |
2 participants
Creates docs/STREAM_MATH.md as the authoritative, standalone reference for StellarStream's vesting math, expanding the brief formula summary
in README § 3 into a full document.
Changes
docs/STREAM_MATH.md (new) — 466 lines covering:
Core symbol/variable definitions table
Formula derivations explaining the clamp, vesting ratio, and cancel accounting
Two worked examples with step-by-step arithmetic:
Five edge cases: claim before start, claim after end, cliff stream (with its own mini-example), instant cancel at t_start, zero-duration
guard
Status rules reference table (scheduled / active / completed / canceled)
Implementation cross-reference mapping each math concept to its source file
README.md — adds > Full derivations, worked examples, and edge cases callout in § 3 pointing to the new doc
docs/CONTRACT_BINDINGS.md — adds a callout at the top linking to STREAM_MATH.md for the math behind claimable(), claim(), and cancel()
Acceptance criteria checklist
Notes
CONTRACT_ABI.md referenced in the issue does not exist in this repo — docs/CONTRACT_BINDINGS.md is the equivalent file and has been updated
instead. The cliff stream section is documented as planned since the feature is not yet in the MVP contract.
closes #791
Summary by CodeRabbit