Decentralized Oracle Network Smart Contract

A robust, production-ready Clarity smart contract for creating and managing a decentralized oracle network on the Stacks blockchain. This contract enables multiple oracles to submit off-chain data, aggregates their submissions, and provides reliable on-chain data feeds.

Overview

The Decentralized Oracle Network allows trusted oracles to submit real-world data to the blockchain, which is then aggregated and made available to other smart contracts and users. The system uses median and average calculations to ensure data integrity and reduce the impact of malicious or faulty oracles.

Key Features

Oracle Management

• Registration with Staking: Oracles must stake a minimum amount of STX tokens to participate
• Reputation Tracking: Monitors oracle performance and submission accuracy
• Stake Management: Oracles can increase their stake or deactivate and withdraw
• Activity Monitoring: Tracks total submissions and correct submissions per oracle

Data Feed System

• Custom Feeds: Create specialized data feeds with unique identifiers
• Multiple Data Types: Support for various data types (price feeds, weather, sports scores, etc.)
• Round-based Updates: Organized submission rounds for structured data collection
• Feed Lifecycle: Activate, deactivate, and reactivate feeds as needed

Data Aggregation

• Median Calculation: Primary aggregation method to filter outliers
• Average Calculation: Secondary metric for data analysis
• Minimum Oracle Requirement: Ensures sufficient data sources before finalization
• Timestamp Tracking: Records block height and timestamp for each submission

Subscription System

• Feed Subscriptions: Users can subscribe to specific data feeds
• Access Tracking: Monitors when subscribers last accessed feed data
• Easy Management: Simple subscribe/unsubscribe functions

Security Features

• Stake Requirements: Prevents spam and ensures oracle commitment
• Duplicate Prevention: Blocks multiple submissions from same oracle per round
• Authorization Checks: Validates oracle status and feed activity
• Owner Controls: Admin functions restricted to contract owner

Contract Functions

Public Functions

Oracle Functions

• register-oracle(stake-amount) - Register as an oracle with minimum stake
• deactivate-oracle() - Deactivate oracle status and withdraw stake
• increase-stake(additional-stake) - Add more stake to increase reputation

Feed Management

• create-feed(feed-id, name, data-type) - Create a new data feed
• deactivate-feed(feed-id) - Deactivate a feed (admin only)
• reactivate-feed(feed-id) - Reactivate a feed (admin only)

Data Submission

• submit-data(feed-id, value) - Submit data for current round
• finalize-round(feed-id, oracle-list) - Aggregate submissions and finalize round

Subscription

• subscribe-to-feed(feed-id) - Subscribe to a data feed
• unsubscribe-from-feed(feed-id) - Unsubscribe from a feed

Admin Functions

• update-min-stake(new-stake) - Update minimum stake requirement
• update-min-oracles(new-min) - Update minimum oracles per round
• update-validity-blocks(new-blocks) - Update data validity period

Read-Only Functions

• get-latest-data(feed-id) - Retrieve most recent aggregated data
• get-historical-data(feed-id, round) - Get data from specific round
• get-oracle-info(oracle) - Query oracle details and statistics
• get-feed-info(feed-id) - Get feed configuration and metadata
• get-current-round(feed-id) - Check current round number
• get-oracle-submission(feed-id, oracle, round) - View specific submission
• is-data-fresh(feed-id) - Check if feed data is within validity period
• get-network-stats() - Get overall network statistics
• is-subscriber(feed-id, subscriber) - Check subscription status

Configuration Parameters

Default Settings

• Minimum Stake: 1,000,000 microSTX (1 STX)
• Minimum Oracles Required: 3 oracles per round
• Data Validity Period: 144 blocks (~24 hours)

These parameters can be adjusted by the contract owner to optimize network performance.

Usage Example

1. Register as Oracle

(contract-call? .oracle-network register-oracle u1000000)

2. Create Data Feed

(contract-call? .oracle-network create-feed "BTC-USD" "Bitcoin Price Feed" "price")

3. Submit Data

(contract-call? .oracle-network submit-data "BTC-USD" 4500000)

4. Finalize Round

(contract-call? .oracle-network finalize-round "BTC-USD" 
  (list 'SP1... 'SP2... 'SP3...))

5. Read Latest Data

(contract-call? .oracle-network get-latest-data "BTC-USD")

Data Flow

1. Oracle Registration: Oracles stake tokens and register with the network
2. Feed Creation: Contract owner or authorized users create data feeds
3. Data Submission: Multiple oracles submit values for current round
4. Aggregation: After minimum oracles submit, round is finalized
5. Data Access: Consumers read aggregated median and average values
6. New Round: System advances to next round for fresh data

Error Codes

• u100 - Owner-only function called by non-owner
• u101 - Caller is not a registered oracle
• u102 - Oracle already exists
• u103 - Insufficient stake amount
• u104 - No data available
• u105 - Data is stale
• u106 - Invalid feed ID
• u107 - Minimum oracles not met
• u108 - Already submitted in current round
• u109 - Unauthorized action

Security Considerations

1. Stake Slashing: Current version returns full stake on deactivation. Consider implementing slashing for malicious behavior
2. Oracle Reputation: Reputation system is tracked but not enforced. Implement reputation-based rewards
3. Data Validation: Add range checks and sanity tests for submitted values
4. Time Delays: Consider adding delay periods for withdrawals
5. Governance: Implement decentralized governance for parameter updates

Best Practices

• Always maintain minimum oracle count for reliable data
• Set appropriate validity periods based on data update frequency
• Monitor oracle performance and reputation regularly
• Subscribe to feeds before consuming data in production
• Verify data freshness before making critical decisions
• Use median values for resilience against outliers

Future Enhancements

• Weighted averages based on oracle reputation
• Automatic stake slashing for incorrect submissions
• Multi-signature feed management
• Oracle rewards distribution system
• Cross-chain data bridging
• Historical data archiving
• Dynamic fee structures

Testing

Test the contract thoroughly before mainnet deployment:

1. Register multiple test oracles
2. Submit varied data points
3. Test edge cases (minimum oracles, invalid feeds)
4. Verify aggregation calculations
5. Test all error conditions
6. Monitor gas costs