Skip to content

Implement BitYield Pro Core Protocol Architecture#1

Open
peter-curl wants to merge 11 commits intomainfrom
feat/implementation
Open

Implement BitYield Pro Core Protocol Architecture#1
peter-curl wants to merge 11 commits intomainfrom
feat/implementation

Conversation

@peter-curl
Copy link
Owner

@peter-curl peter-curl commented Mar 22, 2025

Overview

This PR introduces the foundational architecture for BitYield Pro - a decentralized yield optimization protocol designed for Bitcoin DeFi on Stacks L2. The implementation establishes secure multi-strategy yield generation with institutional-grade risk parameters while maintaining full SIP-010 compliance.

Key Value Propositions

Bitcoin-Centric Design

  • SIP-010 token standard integration for native BTC asset handling
  • SAT-denominated deposit limits ($50 min - $10M max)
  • Block-height-based reward calculations aligned with Bitcoin blocks

Enterprise-Grade Security

  • Emergency shutdown toggle with single transaction execution
  • Protocol whitelisting system with active/inactive states
  • APY range validation (0-100%) and allocation caps (10k bps max)

Protocol-Owner Controls

  • Dynamic APY adjustments per strategy
  • Token/Protocol whitelisting governance
  • Platform fee configurability (capped at 10%)

Technical Implementation

Core Components

Feature Technical Highlights
Deposit Engine user-deposits map + min/max SAT validation
Reward System Block-weighted APY calc + fee-adjusted claims
Strategy Mgmt Protocol status toggles + allocation rebalancing
Token Security Whitelist verification pre-transfer hooks

Architectural Flow

graph TD  
    A[User Deposit] --> B{Token Whitelist Check}  
    B -->|Approved| C[TVL Update]  
    C --> D[Protocol Rebalance]  
    D --> E[Yield Generation]  
    E --> F[Reward Accrual]  
    F --> G[Claim Execution]
Loading

Changes Included

Protocol Infrastructure

  1. Data Architecture

    • User state tracking (user-deposits, user-rewards)
    • Protocol registry (protocols, strategy-allocations)
    • Approved assets ledger (whitelisted-tokens)

  2. Economic Controls

    • calculate-rewards with APY/block/TVL factors
    • safe-token-transfer with pre-validation checks
    • rebalance-protocols allocation enforcer

  3. Admin Governance

    • Protocol lifecycle management (add/update/toggle)
    • platform-fee-rate parameterization
    • Emergency circuit breaker pattern

Notes for Reviewers

  1. Bitcoin Alignment

    • All time calculations use stacks-block-height for L1 sync
    • SAT precision maintained via 8-decimal floor in transfers

  2. Upgrade Path

    • Protocol parameters designed for future DAO control
    • Allocation engine structured for cross-protocol yield swaps

  3. Risk Disclosure

    • Initial release caps protocol count at 5 (ID 1-5)
    • Emergency shutdown disables deposits but permits withdrawals

peter-curl added 11 commits March 22, 2025 13:49
@peter-curl
feat: Add data maps for user deposits, rewards, protocols, and whitel…
de527c8 
…isted tokens

- Introduced `user-deposits` map to track user deposit amounts and last deposit block.
- Added `user-rewards` map to manage pending and claimed rewards for users.
- Defined `protocols` map to store protocol details, including name, status, and APY.
- Implemented `strategy-allocations` map for managing protocol-specific allocation percentages.
- Created `whitelisted-tokens` map to track approved tokens for the protocol.
@peter-curl
feat: Add SIP-010 token interface and validation functions
8ee5420 
- Implemented `sip-010-trait` to define the SIP-010 token standard interface for seamless Bitcoin asset integration.
- Added `is-contract-owner` private function to verify contract ownership.
- Introduced validation functions:
  - `is-valid-protocol-id` to ensure protocol IDs are within valid range.
  - `is-valid-apy` to validate APY values against defined limits.
  - `is-valid-name` to check for valid protocol names.
@peter-curl
feat: Add protocol management functions for adding and updating proto…
6c8e1d8 
…cols

- Implemented `add-protocol` function to allow the contract owner to add new protocols with a unique ID, name, and initial APY.
  - Includes validation for protocol ID, name, and APY.
  - Ensures the protocol does not already exist before adding.
  - Initializes the protocol as active with a default allocation of 0.

- Added `update-protocol-status` function to enable the contract owner to activate or deactivate existing protocols.
  - Validates protocol ID and ensures the protocol exists before updating its status.
@peter-curl
feat: Add protocol APY update and enhanced token validation functions
560770c 
- Implemented `update-protocol-apy` function to allow the contract owner to update the APY of an existing protocol.
  - Includes validation for protocol ID, existence, and APY range.
  - Ensures secure updates by merging the new APY into the protocol's data.

- Added `validate-token` private function to verify if a token is whitelisted and approved.
  - Checks the token's contract against the `whitelisted-tokens` map.
  - Ensures only approved tokens can interact with the protocol.
@peter-curl
feat: Implement secure deposit management function
06d4d1b 
- Added `deposit` function to handle user deposits securely:
  - Validates the token using the `validate-token` function to ensure it is whitelisted and approved.
  - Enforces deposit constraints, including minimum and maximum deposit limits.
  - Prevents deposits during emergency shutdowns.
  - Transfers tokens safely from the user to the contract using `safe-token-transfer`.

- Updates user deposit records in the `user-deposits` map, including the deposit amount and block height.
- Adjusts the protocol's total TVL (`total-tvl`) to reflect the new deposit.
- Invokes `rebalance-protocols` to ensure proper allocation across strategies.
@peter-curl
feat: Add secure withdrawal and token transfer functions
797fba4 
- Implemented `withdraw` function to allow users to withdraw their deposited tokens:
  - Validates the token using `validate-token` to ensure it is whitelisted and approved.
  - Ensures the withdrawal amount does not exceed the user's current deposit.
  - Updates the `user-deposits` map to reflect the reduced deposit amount.
  - Adjusts the protocol's total TVL (`total-tvl`) to account for the withdrawal.
  - Transfers tokens securely back to the user using `safe-token-transfer`.

- Added `safe-token-transfer` private function to handle token transfers:
  - Validates the token before initiating the transfer.
  - Calls the SIP-010 `transfer` function to move tokens between accounts.
@peter-curl
feat: Add reward calculation and claiming functionality
7258f42 
- Implemented `calculate-rewards` private function:
  - Computes user rewards based on their deposit amount, weighted APY, and the number of blocks passed.
  - Uses a formula to ensure accurate APY-based reward distribution over time.

- Added `claim-rewards` public function:
  - Allows users to claim their accumulated rewards.
  - Validates the token using `validate-token` to ensure it is whitelisted and approved.
  - Ensures the calculated rewards are greater than zero before proceeding.
  - Updates the `user-rewards` map to reset pending rewards and increment claimed rewards.
  - Transfers the calculated rewards securely to the user using the SIP-010 `transfer` function.
@peter-curl
feat: Add protocol rebalancing, APY calculation, and getter functions
30c1057 
- Implemented `rebalance-protocols` private function:
  - Ensures total protocol allocations do not exceed 100% (10,000 basis points).
  - Validates allocation consistency across all protocols.

- Added `get-weighted-apy` private function:
  - Calculates the weighted average APY across all active protocols based on their allocations.

- Introduced `get-weighted-protocol-apy` private function:
  - Computes the weighted APY for a specific protocol, considering its allocation and active status.

- Added getter functions:
  - `get-protocol`: Retrieves protocol details by protocol ID.
  - `get-user-deposit`: Fetches user deposit details, including amount and last deposit block.
@peter-curl
feat: Add admin and helper functions for protocol and token management
82c21a2 
- Implemented `get-total-tvl` read-only function:
  - Retrieves the current total value locked (TVL) in the protocol.

- Added `is-whitelisted` read-only function:
  - Checks if a given token is whitelisted and approved for use in the protocol.

- Introduced admin functions:
  - `set-platform-fee`: Allows the contract owner to update the platform fee rate, with a maximum limit of 10% (1,000 basis points).
  - `set-emergency-shutdown`: Enables the contract owner to toggle the emergency shutdown state.
  - `whitelist-token`: Allows the contract owner to whitelist a token by marking it as approved.

- Added helper functions:
  - `get-protocol-list`: Returns a predefined list of supported protocol IDs.
  - `get-protocol-allocation`: Retrieves the allocation percentage for a specific protocol.
@peter-curl
fix: Correct block height reference in deposit and rewards calculations
9ca8cd4 
- Updated `deposit` function to use `stacks-block-height` instead of `block-height` for consistency with Stacks terminology.
- Adjusted `claim-rewards` function to calculate rewards based on `stacks-block-height` for accurate block-based reward distribution.
@peter-curl
docs: Add comprehensive README for BitYield Pro smart contract
547584c 
- Detailed overview of BitYield Pro's functionality, including multi-protocol yield strategies, SIP-010 compliance, and risk management.
- Key features section highlighting deposit limits, emergency shutdown, and transparent fee structure.
- Technical specifications covering contract architecture, key variables, and SIP-010 integration.
- Core functionality explained for deposit/withdrawal management, yield strategy management, reward calculation, and protocol administration.
- Security architecture section detailing risk management, emergency shutdown, and token whitelisting.
- Validation framework for APY range, protocol ID validation, and deposit sanity checks.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@peter-curl