[Smart Contracts] Support Non-Linear & Milestone Step-Vesting Streaming Schedules

[blurbeast]

Overview & Background

Currently, FlowFi only supports strict linear streaming, where tokens unlock continuously per second (rate_per_second). However, institutional grants, venture capital token distributions, and executive compensation packages frequently require milestone step-vesting (e.g. 25% unlock at 6 months, 25% at 12 months, followed by linear unlock for remaining tokens, or custom scheduled tranches).

---

Detailed Problem Statement

1. Incompatibility with Milestone Grants:
   • DAOs and protocols funding milestone-based development cannot model tranche releases within a single stream.
2. Manual Fragmented Workarounds:
   • Senders currently have to create separate individual streams for each milestone tranche, resulting in multiplied gas costs and fragmented tracking.
3. Lack of Dynamic Schedule Verification:
   • Recipient claimable calculations cannot evaluate discrete time-step unlock functions.

---

Technical Specification & Architecture

1. Milestone Vesting Step Model (types.rs)

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VestingStep {
    pub unlock_time: u64,
    pub unlock_amount: i128,
}

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VestingSchedule {
    Linear,
    StepTranches(Vec<VestingStep>),
    HybridCliffLinear { cliff_time: u64, cliff_unlock_amount: i128 },
}

2. Creation Entrypoint

pub fn create_step_vesting_stream(
    env: Env,
    sender: Address,
    recipient: Address,
    token_address: Address,
    steps: Vec<VestingStep>,
) -> Result<u64, StreamError>

3. Claimable Calculation Engine

• At any timestamp $T$, total claimable amount equals the sum of step.unlock_amount for all steps where step.unlock_time <= T, minus stream.withdrawn_amount.
• Cancellation rules: Senders can only refund steps where step.unlock_time > cancellation_time.

---

Target Files

• contracts/stream_contract/src/types.rs
• contracts/stream_contract/src/lib.rs
• contracts/stream_contract/src/test.rs

---

Acceptance Criteria

• Senders can deploy streams with up to 12 scheduled unlock steps.
• Recipient can claim exactly the cumulative unlocked step amounts at designated timestamps.
• Step times must be strictly monotonically increasing and total step amounts must equal deposited amount.
• Cancellation properly settles unlocked steps to recipient and returns unearned future steps to sender.

[abiolatousin-design]

@abiolatousin-design has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi, I’m available to work on this task and would appreciate the opportunity.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @abiolatousin-design to this issue.

[Ssoleed]

@Ssoleed has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

hi maintainer, can i pls work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ssoleed to this issue.

[Darkvader-ship-it]

@Darkvader-ship-it has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

can i work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Darkvader-ship-it to this issue.

[drips-wave]

Congratulations, @Darkvader-ship-it! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Darkvader-ship-it: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊