feat: add unlock amounts functionality

[andreivladbrg]

Closes #1043 and #1067

Since we have the invariant: $\text{cliff time} = 0 \implies \text{cliff unlock amount} = 0$, there are 6 possible scenarios in the streamedAmountOf function:

Scenario	Shape	Cliff Time	Start Amount	Cliff Amount
1	Simple Linear	❌	❌	❌
3	Simple Cliff	✅	❌	✅
3	Unlock Linear	❌	✅	❌
4	Unlock Cliff	✅	✅	✅
5	Constant, then linear (see below)	✅	❌	❌
6	Initial amount, constant, then linear (see below)	✅	✅	❌

Plot graphs with docs code

Scenario 5

Code to update the docs shapes with:

<FunctionPlot
  options={{
    data: [
      { fn: "0", range: [0, 25], color: "#f77423" },
      { fn: "(4/3) * (x - 25)", range: [25, 100], color: "#f77423" },
      {
        points: [
          [0, 0],
          [25, 0],
        ],
        fnType: "points",
        graphType: "polyline",
        color: "#f77423",
      },
    ],
  }}
/>

Scenario 6

Code to update the docs shapes with:

<FunctionPlot
  options={{
    data: [
      { fn: "25", range: [0, 50], color: "#f77423" }, // Constant at y=25 from x=0 to x=50
      { fn: "1.5 * (x - 50) + 25", range: [50, 100], color: "#f77423" }, // Linear rise with slope 1.5 starting from y=25 at x=50
      {
        points: [
          [0, 25],
          [50, 25],
        ],
        fnType: "points",
        graphType: "polyline",
        color: "#f77423",
      },
    ],
  }}
/>

---

Note: Since the mathematical logic has changed in SablierLockupLinear._calculateStreamedAmount, in order to achieve the previous cliff linear shape, it is required to pass an unlockAmount.cliff > 0; otherwise, the 5th scenario shape will be achieved. This is also the reason I needed to change the tests from warping to WARP_26_PERCENT instead of CLIFF_TIME, as many tests were failing. The cliff amount has a remainder of 2534 due to a different "streamable" range.

As you will see in the code, I am referring to the range that calculates the elapsed time as "streamable," which might be confusing since the entire function is called "streamed amount." However, we will eventually change this terminology to "vesting," so don’t mind the current terminology if you find it unclear.

---

Here's a diagram for visualizing the new function flow while reviewing.

New function flow

flowchart TD
    start_time_check([Is startTime >= current block timestamp?]):::check
    return_zero([Return 0]):::return
    end_time_check([Is current block timestamp >= endTime?]):::check
    return_deposited([Return depositedAmount]):::return
    cliff_time_check([Is cliffTime set and cliffTime > current block timestamp?]):::check
    return_start_unlock([Return start unlock amount]):::return
    unlock_sum_check([Is unlockAmountsSum >= depositedAmount?]):::check
    elapsed_calculation_check([Calculate elapsedTime and streamableDuration]):::calculation
    etp_calculation([Calculate elapsedTimePercentage]):::calculation
    streamable_amount_calc([Calculate streamableAmount]):::calculation
    streamed_amount_calc([Calculate streamedAmount]):::calculation
    final_check([Is streamedAmount > depositedAmount?]):::check
    return_withdrawn([Return withdrawn amount]):::return
    return_streamed([Return streamedAmount]):::return

    start_time_check -- "Yes" --> return_zero
    start_time_check -- "No" --> end_time_check
    end_time_check -- "Yes" --> return_deposited
    end_time_check -- "No" --> cliff_time_check
    cliff_time_check -- "Yes" --> return_start_unlock
    cliff_time_check -- "No" --> unlock_sum_check
    unlock_sum_check -- "Yes" --> return_deposited
    unlock_sum_check -- "No" --> elapsed_calculation_check

    elapsed_calculation_check --> etp_calculation
    etp_calculation --> streamable_amount_calc
    streamable_amount_calc --> streamed_amount_calc
    streamed_amount_calc --> final_check
    final_check -- "Yes" --> return_withdrawn
    final_check -- "No" --> return_streamed

    classDef check fill:#FFC107,stroke:#333,stroke-width:2px;
    classDef return fill:#4CAF50,stroke:#333,stroke-width:2px;
    classDef calculation fill:#03A9F4,stroke:#333,stroke-width:2px;

Loading

[andreivladbrg]

@smol-ninja the PR is ready for your review, I have updated the OP with some useful comments, please get first through them before reviewing,

[andreivladbrg]

@smol-ninja just rebased from refactor/singleton-contract. in case i have missed something, i have created a recovery branch.

Note: the size of the contract is at its limit, adding new things to the contract would require us to decrease the optimizer runs.

Contract	Size (B)	Margin (B)
SablierLockup	24,450	126

[smol-ninja]

Nice work on the PR. Reviewed the src and left my comments below.

[andreivladbrg]

@smol-ninja I have addressed all the src feedback, and I have finally rebased from test PRs—it was a mess… but we’re here. I hope I didn’t miss anything while rebasing.

[smol-ninja]

Nice work on tests. Left my review below.

Also created a PR: #1088 about Schedule struct that can be merged into this.

[smol-ninja]

This should be removed.

[smol-ninja]

Rationale behind removing them? Also, modifiers still exist in the corresponding test contracts.

[andreivladbrg]

same reason as here

#1075 (comment)

already tested in SETTLED status branch

also re this #1075 (comment)

we should consider for SETTLED this modifier for both now == end && now > end:

modifier runBothCases() {
    vm.warp({ newTimestamp: defaults.END_TIME() });
    _;

    vm.warp({ newTimestamp: defaults.END_TIME() + 1 });
    _;
}

[smol-ninja]

Approving the PR. There are still some unresolved comments regarding tests but since they are related to tests we can look into them later. The contract code looks good to me so given the audit date is near, feel free to merge it now.

[andreivladbrg]

Thanks, let's goo 🚀