Repository navigation
[Smart Contracts] Oracle-Triggered Conditional Streaming & KPI-Gated Milestone Releases #1482
Description
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
- 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.
- Manual Milestone Approvals:
- Grant committees must manually execute contract cancellations or deployments when grantees meet or fail milestones, introducing latency and administrative overhead.
- 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.amountto claimable balance. - Emit
MilestoneConditionUnlockedevent.
- Mark
Target Files
contracts/stream_contract/src/types.rscontracts/stream_contract/src/lib.rscontracts/stream_contract/src/oracle.rscontracts/stream_contract/src/events.rscontracts/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.
Activity
Lekegold23 commentedon Sep 27, 2026
@Lekegold23 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @Lekegold23 to this issue.
sojetunde8 commentedon Sep 27, 2026
@sojetunde8 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @sojetunde8 to this issue.
drips-wave commentedon Sep 27, 2026
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 🌊
feat: conditional streams, analytics stack, developer portal, copy fe…
feat: conditional streams, analytics stack, developer portal, copy fe…
grantfox-oss commentedon Oct 6, 2026
🎉 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.
Merge pull request #1556 from sojetunde8/feature/1480-1483-platform-s…
drips-wave commentedon Oct 6, 2026
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.