# Subnet ## TensorUSD Subnet Architecture (SN113) ### Introduction TensorUSD (SN113) is a reserve-backed stablecoin subsystem within the Bittensor ecosystem designed to maintain 1:1 redeemability with the US Dollar. The subnet operates through a **dual-mechanism incentive model** that coordinates decentralized liquidation execution and price oracle maintenance. The subnet implements two parallel incentive mechanisms: * **Mechanism 0**: Liquidation Auction Participation (99% of total miner rewards) * **Mechanism 1**: Price Oracle Contributions (1% of total miner rewards) Both mechanisms run independently with separate reward systems, allowing miners to specialize or participate in both for maximum earnings. *** ### Dual-Mechanism Architecture #### Mechanism 0: Liquidation Auctions When collateral backing a vault becomes insufficient (collateral ratio drops below threshold), the system liquidates collateral via an auction process. Miners compete to acquire collateral at profitable prices while covering vault debt. **Key Activities:** * Monitor liquidation auctions in real-time * Evaluate profitability using live collateral prices * Submit competitive bids on-chain * Execute winning bids to acquire collateral **Reward Model:** * Base reward: 1.0 for paying exactly the debt amount * Bonus scaling: Up to 1.2x for overbidding 20%+ above debt * Multiple auction wins accumulate rewards * Rewards distributed via `mechid=0` weights #### Mechanism 1: Price Oracle Maintains accurate TAO/USD pricing by aggregating price submissions from multiple miners. The oracle uses a median-based consensus mechanism to ensure price reliability for the vault system. **Key Activities:** * Fetch TAO/USD price from CoinMarketCap API ( Room for improvement for miners) * Submit price data to oracle contract periodically (every 5 minutes) * Participate in multi-reporter consensus rounds * Maintain price accuracy for collateral valuation **Reward Model:** * Rewards based on price submission accuracy and timeliness * Consensus participation (submitting prices close to median) * Consistent oracle uptime and reliability * Rewards distributed via `mechid=1` weights *** ### System Components #### A) Miners Miners participate in one or both mechanisms to earn TAO emissions. **Mechanism 0 Miner (Liquidation)** **Core Responsibilities:** 1. **Monitor Auctions**: Listen to auction contract events for new liquidations and outbid events 2. **Evaluate Profitability**: Calculate expected profit using live collateral price from oracle 3. **Bidding Strategy**: * Initial bid: debt × (1 + initial\_percentage) * Increment when outbid: current\_bid × (1 + increment\_rate) * Respect max bid limits and minimum profit margins 4. **Submit Bids**: Execute on-chain transactions with hotkey metadata 5. **Token Management**: Approve TUSDT spending for auction contract **Configuration Options:** ```bash --bid.initial_percentage=0.0005 # Start at debt + 0.05% --bid.increment_rate=0.0005 # Increase by 0.05% when outbid --bid.max_percentage=0.95 # Maximum bid as % of collateral value --bid.min_profit_margin=0.0002 # Minimum 0.02% profit required ``` **Mechanism 1 Miner (Price Oracle)** **Core Responsibilities:** 1. **Fetch Market Price**: Query CoinMarketCap API for TAO/USD spot price 2. **Format Price**: Convert to u128 ratio format (price × 10^18) 3. **Submit to Oracle**: Submit price on oracle contract with hotkey metadata 4. **Maintain Uptime**: Submit prices at regular intervals (default: 300 seconds) 5. **Monitor Rounds**: Track current round ID and submission status **Configuration Options:** ```bash --oracle_contract.address=5FHneW... # Oracle contract address --cmc.api_key=YOUR_API_KEY # CoinMarketCap API key --price.submission_interval_seconds=300 # Submit every 5 minutes ``` *** #### B) Validators Validators ensure correctness and fairness by tracking on-chain activity and distributing rewards appropriately. Each mechanism has its own independent validation and reward calculation logic. **Dual-Mechanism Validation Architecture** Validators run **two independent forward passes** that sync separately: ``` ┌─────────────────────────────────────────────────────────────┐ │ Validator Main Loop │ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ Forward Mech 0 │ │ Forward Mech 1 │ │ │ │ (Liquidations) │ │ (Price Oracle) │ │ │ │ │ │ │ │ │ │ 1. Query DB for │ │ 1. Get round data │ │ │ │ auction wins │ │ from oracle │ │ │ │ 2. Calculate │ │ 2. Calculate │ │ │ │ rewards │ │ rewards │ │ │ │ 3. Update scores │ │ 3. Update scores │ │ │ │ │ │ │ │ │ │ ↓ (on completion) │ │ ↓ (on completion) │ │ │ │ │ │ │ │ │ │ - set_weights(0) │ │ - set_weights(1) │ │ │ └──────────────────────┘ └──────────────────────┘ │ │ ↑ ↑ │ │ └──────── Run Concurrently ────┘ │ │ (Independent sync cycles) │ └─────────────────────────────────────────────────────────────┘ ``` **Key Features:** * Both mechanisms run in parallel * Each mechanism syncs independently when its forward completes * Faster mechanism doesn't wait for slower one * Separate scores for each mechanisms **Mechanism 0 Validator (Liquidation)** **Core Responsibilities:** 1. **Event Listening**: Background thread monitors auction contract events * `AuctionCreated`: New liquidation auctions * `BidPlaced`: Miner bids submitted * `AuctionFinalized`: Auction winners determined 2. **Database Persistence**: Store auction outcomes in SQLite * Table: `auction_wins` * Schema: auction\_id, vault\_id, vault\_owner, bidder, hotkey, amount, tempo\_block 3. **Reward Calculation** (every \~180 blocks): * Query unprocessed wins within tempo window * Calculate per-miner rewards: ```python base_reward = 1.0 BONUS_THRESHOLD = 0.20 # 20% overpay for max bonus if bid_amount > debt: bonus_ratio = min((winning_bid - debt_balance) / debt_balance, BONUS_THRESHOLD) reward = bonus_ratio + BASE_REWARD return reward reward = base_reward + bonus ``` * Aggregate rewards by hotkey UID * Mark processed wins with current `tempo_block` 4. **Weight Setting**: set weights with `mechid=0` **Mechanism 1 Validator (Price Oracle)** **Core Responsibilities:** 1. **Round Monitoring**: Track oracle contract rounds * Get current round ID via `current_round_id()` * Monitor round progression and finalization 2. **Submission Tracking**: Query price submissions per round * Call `get_round_submissions(round_id)` * Extract miner hotkeys from submission metadata * Verify submission timeliness and accuracy 3. **Reward Calculation**: * Fetch median price for completed rounds via `get_round_price(round_id)` * Calculate accuracy scores (submissions close to oracle price) * Reward consistent participants 4. **Weight Setting**: set weights with `mechid=1` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tensorusd.com/components/subnet.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.