Cross-Contract Callback Interface Implementation Summary

Overview

A standardized cross-contract callback interface has been successfully implemented for the StellarFlow Price Oracle. This enables downstream Soroban contracts (Lending protocols, DEXs, etc.) to subscribe to real-time price updates without polling.

What's New

1. Core Interface

Subscription Functions (Public API in PriceOracleClient):

// Register a contract to receive price update callbacks
pub fn subscribe_to_price_updates(callback_contract: Address) -> Result<(), String>

// Unregister a contract from callbacks
pub fn unsubscribe_from_price_updates(callback_contract: Address) -> Result<(), String>

// Get list of all subscribed contracts
pub fn get_price_update_subscribers() -> Vec<Address>

2. Standard Callback Interface

Subscriber contracts must implement:

pub fn on_price_update(env: Env, payload: PriceUpdatePayload)

Where PriceUpdatePayload contains:

asset: Symbol (NGN, KES, GHS, etc.)
price: i128 (normalized to 9 decimals)
timestamp: u64 (ledger timestamp)
provider: Address (who submitted the price)
decimals: u32 (always 9)
confidence_score: u32 (0-100)

3. Automatic Callback Invocation

Callbacks are automatically triggered when prices are updated:

✅ update_price() - authorized provider updates
✅ set_price() - admin price setting

Architecture

┌─────────────────────────────────────────────────────────┐
│          StellarFlow Price Oracle (lib.rs)              │
│                                                          │
│  ┌────────────────────────────────────────────────┐    │
│  │ Public Contract Interface                      │    │
│  │  - update_price()                              │    │
│  │  - set_price()                                 │    │
│  │  - subscribe_to_price_updates()                │    │
│  │  - unsubscribe_from_price_updates()            │    │
│  │  - get_price_update_subscribers()              │    │
│  └────────────────────────────────────────────────┘    │
│                        ↓                                 │
│  ┌────────────────────────────────────────────────┐    │
│  │ Callbacks Module (callbacks.rs)                │    │
│  │  - subscribe()                                 │    │
│  │  - unsubscribe()                               │    │
│  │  - get_subscribers()                           │    │
│  │  - notify_subscribers()                        │    │
│  │  - try_invoke_callback()                       │    │
│  └────────────────────────────────────────────────┘    │
│                        ↓                                 │
│  ┌────────────────────────────────────────────────┐    │
│  │ Types Module (types.rs)                        │    │
│  │  - PriceUpdatePayload                          │    │
│  │  - DataKey::PriceUpdateSubscribers             │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
└─────────────────────────────────────────────────────────┘
                           ↓
        ┌──────────────────┬──────────────────┐
        ↓                  ↓                  ↓
    Lending           DEX/AMM            Other
    Protocol          Protocol           Protocols
    
    on_price_update() callbacks

File Structure

contracts/price-oracle/src/
├── lib.rs                      (Main contract, updated)
│   └── Subscription functions
│   └── Callback integration
├── types.rs                    (Updated)
│   └── PriceUpdatePayload struct
│   └── DataKey::PriceUpdateSubscribers
├── callbacks.rs                (NEW)
│   └── Subscription management
│   └── Callback invocation
├── auth.rs
├── math.rs
├── median.rs
├── asset_symbol.rs
└── test.rs                     (Extended)
    └── 11 new callback tests

CALLBACK_INTERFACE.md           (NEW)
└── Comprehensive documentation

Quick Start

For Lending Protocol Developers

Implement callback in your contract:

#[contract]
pub struct MyLendingPool;

#[contractimpl]
impl MyLendingPool {
    pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
        // Check for liquidation opportunities
        // Update collateral requirements
        // Trigger rebalancing if needed
    }
}

Subscribe to oracle:

let oracle = PriceOracleClient::new(&env, &oracle_address);
oracle.subscribe_to_price_updates(&my_contract_address)?;

Receive automatic updates:

When price changes → Oracle calls on_price_update() → React immediately

For DEX Developers

Implement callback:

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    // Rebalance liquidity pools
    // Check slippage limits
    // Adjust fee tiers
    // Emit events for off-chain systems
}

Subscribe:

oracle.subscribe_to_price_updates(&dex_contract)?;

Testing

Included Tests

The implementation includes 11 comprehensive tests:

✅ test_subscribe_to_price_updates - Basic subscription
✅ test_subscribe_duplicate_fails - Duplicate prevention
✅ test_multiple_subscribers - Multiple registrations
✅ test_unsubscribe_from_price_updates - Unsubscribe
✅ test_unsubscribe_nonexistent_fails - Error handling
✅ test_get_empty_subscriber_list - Empty state
✅ test_subscribe_unsubscribe_cycle - Lifecycle
✅ test_update_price_does_not_crash_with_subscribers - Integration
✅ test_set_price_with_subscribers - Admin integration
✅ test_subscribe_and_get_subscribers (callbacks.rs)
✅ test_unsubscribe (callbacks.rs)

Run tests with:

cd contracts/price-oracle
cargo test

Key Features

1. Event-Driven Architecture

No polling required
Immediate reaction to price changes
Real-time synchronization

2. Standardized Interface

Single on_price_update function signature
All subscribers implement the same contract
Easy integration for new protocols

3. Gas-Efficient

O(n) subscription operations (n = subscriber count)
O(1) callback dispatch per subscriber
Recommended max: ≤10 subscribers

4. Resilient Design

Failed callbacks don't block price updates
Errors logged internally, not propagated
Non-blocking callback semantics

5. Security

Oracle is authoritative source
Subscribers should validate caller
Price data immutable after callback

Usage Examples

Example 1: Liquidation Bot (Lending)

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    let asset = payload.asset;
    let new_price = payload.price;
    
    // Find positions to liquidate
    let positions = find_undercollateralized(&env, &asset, new_price);
    
    for position in positions.iter() {
        trigger_liquidation(&env, &position);
    }
}

Example 2: Pool Rebalancer (DEX)

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    let old_price = get_last_known_price(&env, &payload.asset);
    let price_change_pct = calc_pct_change(old_price, payload.price);
    
    // Rebalance if price moved >2%
    if price_change_pct.abs() > 200 {
        rebalance_pool(&env, &payload.asset, payload.price);
    }
}

Example 3: Price Feed Bridge

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    // Store price data for other protocols
    env.storage().instance().set(
        &DataKey::LatestPrice(payload.asset),
        &payload
    );
    
    // Emit event for off-chain indexing
    env.events().publish((
        Symbol::new(&env, "oracle_price_update"),
    ), (
        payload.asset,
        payload.price,
        payload.timestamp,
    ));
}

Error Handling

Subscription Errors

Error	Cause	Resolution
"Contract is already subscribed"	Duplicate subscription	Call unsubscribe first
"Contract not found in subscribers"	Unsubscribing non-subscriber	Verify contract is subscribed

Callback Execution

Callbacks are best-effort
Non-blocking: failures don't affect price storage
Implement defensive validation in on_price_update

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    // Validate data integrity
    assert!(payload.price > 0, "Invalid price");
    assert!(payload.timestamp <= env.ledger().timestamp(), "Future timestamp");
    
    // Your logic here
}

Performance Characteristics

Operation	Complexity	Notes
Subscribe	O(n)	n = subscriber count
Unsubscribe	O(n)	Linear search + remove
Get Subscribers	O(1)	Storage retrieval
Callback Dispatch	O(n*m)	n = subscribers, m = callback complexity
Price Update	O(1)	Async callback dispatch

Security Considerations

For Subscriber Contracts

Verify Oracle Source:

const ORACLE_ADDRESS: &str = "C...";

pub fn on_price_update(env: Env, payload: PriceUpdatePayload) {
    assert_eq!(env.invoker(), Address::from_contract_id(&env, ORACLE_ADDRESS));
}

Validate Payload:

// Check timestamp freshness
let now = env.ledger().timestamp();
assert!(payload.timestamp <= now && payload.timestamp > now - 300);

// Check price sanity
assert!(payload.price > 0 && payload.price < MAX_REASONABLE_PRICE);

Idempotent Updates:

// Design for replayability
// Store both price and update timestamp
// Check if update is newer before applying

Next Steps

For Developers

Read CALLBACK_INTERFACE.md for detailed documentation
Review test cases in src/test.rs
Implement on_price_update in your contract
Subscribe to the oracle
Test with mock contracts

For Integration

Add callback interface to your protocol
Update protocol state on on_price_update
Monitor callback gas usage
Set up event listeners for debugging
Deploy with ≤10 initial subscribers

Support

Version: 1.0.0
Status: ✅ Ready for Production
Last Updated: April 25, 2026

FilesExpand file tree

CALLBACK_IMPLEMENTATION_SUMMARY.md

Latest commit

History