harb/onchain/GEMINI.md

Project Overview

This project is a Solidity-based decentralized finance (DeFi) application built using the Foundry framework. The core of the project revolves around the Kraiken token, a sophisticated liquidity management strategy, and a unique staking mechanism.

Core Contracts

• Kraiken.sol: An ERC20 token with a self-assessed tax staking system. The supply is managed by a LiquidityManager, and a stakingPool receives a proportional share of all mints and burns. There's a 20% cap on the total supply that can be staked.

• LiquidityManager.sol: Implements a three-position liquidity strategy:

  • ANCHOR: A narrow, near-price position.
  • DISCOVERY: A wider position that borders the anchor.
  • FLOOR: A deep liquidity position at a VWAP-adjusted price. This strategy uses asymmetric slippage to prevent arbitrage.

• VWAPTracker.sol: Stores historical price data (as price squared in X96 format) to provide a time-weighted average price. It includes a getAdjustedVWAP() function that accounts for capital inefficiency.

• Optimizer.sol: A dynamic and upgradeable contract that reads staking sentiment (percentage of tokens staked, average tax rate) and returns four parameters to adjust the liquidity positions.

• Stake.sol: A self-assessed tax system where users can stake their Kraiken tokens. It features a continuous auction mechanism for staking positions.

Architecture

The system is designed around a dominant liquidity manager strategy. The LiquidityManager controls the token supply and manages the three-tiered liquidity positions. The Optimizer dynamically adjusts the parameters of these positions based on market conditions and staking sentiment. The Stake contract provides a competitive environment for users to earn rewards, with a "snatching" mechanism that adds a game-theoretic layer to the staking strategy.

Building and Running

Dependencies

• Foundry

Installation

1. Clone the repository:

   git clone <repository-url>
   

2. Initialize and update submodules:

   git submodule init
   git submodule update
   

3. Install uni-v3-lib dependencies:

   cd lib/uni-v3-lib
   yarn
   

Build

forge build

Testing

forge test

For more verbose output:

forge test -vvv

To run tests matching a specific contract:

forge test --mc TestContractName

Deployment

The project includes scripts for deploying to Base Sepolia.

source .env
forge script script/BaseSepoliaDeploy.sol:BaseSepoliaDeploy --slow --broadcast --verify --rpc-url ${BASE_SEPOLIA_RPC_URL}

Fuzzing Analysis

The project includes a sophisticated fuzzing framework to test the resilience of the trading strategy under various market conditions.

Running Fuzzing Tests

# Basic test with default parameters
./analysis/run-fuzzing.sh BullMarketOptimizer runs=20

# Advanced test with custom parameters
./analysis/run-fuzzing.sh BullMarketOptimizer runs=50 staking=on buybias=85 trades=60 stakingbias=95

Fuzzing Parameters

• runs=N: Number of fuzzing scenarios (default: 20)
• staking=on|off: Enable/disable staking (default: on)
• buybias=N: 0-100% bias towards buying vs selling (default: 50)
• trades=N: Number of trades per scenario (default: 15)
• stakingbias=N: 0-100% bias towards staking vs unstaking (default: 80)

Advanced Recording & Replay

The framework can record and replay scenarios that trigger invariant violations.

• Record scenarios:

  ./analysis/run-recorded-fuzzing.sh BullMarketOptimizer runs=50
  

• Replay a scenario:

  ./analysis/replay-scenario.sh <RUN_ID> <SEED_NUMBER>
  

Optimizer Strategies

The fuzzing framework can be run with different optimizer strategies:

• BullMarketOptimizer: Aggressive risk-taking.
• BearMarketOptimizer: Conservative positioning.
• NeutralMarketOptimizer: Balanced approach.
• WhaleOptimizer: Large capital movements.
• ExtremeOptimizer: Cycles through parameter extremes.
• MaliciousOptimizer: Intentionally adversarial parameters.

Development Conventions

• Code Style: The code follows standard Solidity style conventions.
• Testing: The project uses Foundry for testing. The test directory contains the test files.
• Access Control: The contracts use a combination of onlyLiquidityManager modifiers and owner checks to enforce access control.
• Important: Do not modify implementation files like LiquidityProvider or ThreePositionStrategy.

Key Files

• test/helpers/UniswapTestBase.sol: Test helper for Uniswap pool setup.
• test/helpers/KraikenTestBase.sol: Common test utilities.
• lib/uni-v3-lib/: Uniswap V3 math library.
• UNISWAP_V3_MATH.md: Reference for the Uniswap V3 math.