[Smart Contracts] Oracle-Triggered Conditional Streaming & KPI-Gated Milestone Releases

[blurbeast]

Overview & Background

Fixed-rate or strictly time-dependent streams cannot adapt to dynamic real-world conditions. Grants, bounty programs, and venture vesting often require condition-gated releases—such as unlocking a tranche only when a token reaches a specific price ceiling, or when a trusted third-party oracle attests that a development milestone, GitHub release, or KPI metric has been achieved. Integrating Soroban oracle interfaces (such as SEP-0040 or Reflector Oracle) allows FlowFi to pioneer dynamic condition-driven streaming.

---

Detailed Problem Statement

1. Inability to Peg Streams to Real-World Value:
   • In volatile cryptocurrency markets, paying contractors in native tokens (e.g. XLM) at a fixed token-per-second rate results in unfair wage inflation or deflation as price fluctuates against USD.
2. Manual Milestone Approvals:
   • Grant committees must manually execute contract cancellations or deployments when grantees meet or fail milestones, introducing latency and administrative overhead.
3. No Standardized Soroban Oracle Hook:
   • FlowFi's contract has no extensible callback or read interface to query on-chain price feeds or verifiable attestations.

---

Technical Specification & Architecture

1. Oracle Interface Integration (SEP-0040 / Reflector Interface)

#[contractclient(name = "OracleClient")]
pub trait PriceOracle {
    fn lastprice(env: Env, asset: Asset) -> Option<PriceData>;
}

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PriceData {
    pub price: i128,
    pub timestamp: u64,
}

2. Condition-Gated Vesting Model (types.rs)

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum UnlockCondition {
    TimeOnly { unlock_time: u64 },
    PriceTarget { oracle_address: Address, target_price: i128, is_above: bool },
    OracleAttestation { oracle_signer: Address, attestation_id: BytesN<32> },
}

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ConditionalMilestone {
    pub milestone_id: u32,
    pub amount: i128,
    pub condition: UnlockCondition,
    pub is_unlocked: bool,
}

3. Verification & Trigger Entrypoint

pub fn verify_and_unlock_milestone(
    env: Env,
    caller: Address,
    stream_id: u64,
    milestone_id: u32,
) -> Result<i128, StreamError>

• Query oracle contract via cross-contract call.
• Verify price timestamp freshness (revert if stale > 3600 seconds).
• If condition evaluated to true:
  • Mark milestone.is_unlocked = true.
  • Add milestone.amount to claimable balance.
  • Emit MilestoneConditionUnlocked event.

---

Target Files

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

---

Acceptance Criteria

• Contract can query external SEP-0040 price oracle and verify target price condition.
• Stale oracle data older than max threshold is rejected with StreamError::OracleDataStale.
• Successful condition verification transitions milestone to unlocked state and enables recipient claim.
• Unauthorized or false conditions cannot trigger premature milestone unlock.
• Unit tests with mock oracle simulate price triggers, timestamp staleness, and attestation verification.

[Lekegold23]

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

Hello maintainer, I can fix this issue please assign

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

[sojetunde8]

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

I can fix this.

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

[drips-wave]

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

🧑‍💻 @sojetunde8: 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 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@sojetunde8's PR #1556 was approved and merged by @K1NGD4VID.

🏆 @sojetunde8: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,166 total points). Track your full progress on GrantFox.

👏 Great work, @sojetunde8! Keep contributing to LabsCrypt.

[drips-wave]

This issue has been marked as completed by a Drips Wave moderator for @sojetunde8 as part of the Stellar Wave Program's 9th Wave 🥳

Moderator's reason: [Auto-assessed] The PR was successfully merged by maintainer @K1NGD4VID on 2026-10-06T10:36:16Z (commit/merge timestamp mergedAt), fulfilling the requirements for Issue #1482.

😎 @sojetunde8: You earned 150 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.

ℹ️ Note: This issue was marked complete via moderation. Points were issued even though the GitHub issue remains open.