Arbiter AmAmm - HackMD

# Arbiter AmAmm ### Version: 0.4.3 --- ## 1. Overview An **Harberger Lease Hook** manages auctions for the right to manage and collect swap fees from a specific AMM pool. The auction is being run continuously and users can overbid the current winner at any time to get the rights starting from the next block. The auctions may be run in either of AMM pool trading tokens or any other token. The proceeds from the auction are distributed to the Liquidity Providers of the pool. - **In case one of pool's trading tokens is used as a bid/rent token**, auction proceeds are distributed seamlessly to LPs using donations. No additional action is required from liquidity providers. In this version, the contract uses the following hooks - `beforeInitialize` - `beforeAddLiquidity` - `beforeRemoveLiquididty` - `beforeSwap` - **In case other token is being used as bid/rent token**, Liquidity Providers are required to `subscribe` to the hook using `PositionManager` to be eligible for rewards. Rewards are distributed proportionally to `SecondsPerSubscribedLiquididty`, which works as `SecondsPerLiquididty` from V3 but measures liquidity only for the time subscription is active. Rewards are distributed continuously and can be collected by Liquidity Providers by calling the `collectReward` function on the hook. On top of the contract being ISubscriber, it also uses the following hooks - `beforeInitialize` - `beforeSwap`. --- ## 2. Mechanisms ### 2.1. Harberger Lease Auction #### 2.1.1. Overview - Users deposit the bidding token into the auction contract as a **deposit**. - They place **bids** specifying: - **`poolKey`**: The key of the pool they want to become the Lessee - **`rentPerBlock`**: The amount they are willing to pay per block. - **`rentEndBlock`**: The block number until which they wish to hold the right. - **`strategyAddress`**: Address of contract implementing `IArbiterAmmStrategy`. - The **highest bidder** becomes the **Winner** or **Current Lessee**. The hook will use its strategy to control the PoolFees and transfer all swap fees to it. #### 2.1.2. Core Concepts - **Continuous Auction**: Right to collect fees can be taken over at any time by overbidding. - **Rent Payment**: The Winner pays rent continuously, deducted from their deposit. - **Dynamic Ownership**: Ownership transitions smoothly based on the bidding and rent payments. #### 2.1.3. Key Parameters - **`MINIMUM_RENT_TIME_IN_BLOCKS`**: Ensures that rent periods are of a minimum duration. - **`RENT_FACTOR`**: Controls how much higher a new bid must be to overbid the current Winner. - **`TRANSITION_BLOCKS`**: In the final blocks of a rent period, any bid is sufficient to overbid. ### 2.2 Fee Collection and Distribution #### 2.2.1. Custom Swap Fees - The Winner can control custom swap fees by implementing the `IArbiterFeeProvider` interface. - The `getSwapFee` function determines the fee for each swap, the gas cost of the call must be smaller than "GET_SWAP_FEE_GAS_LIMIT". #### 2.2.2. Fee Distribution - Swap fees collected are split between the Winner and the LPs in proportion controlled by the hook owner ( Arbiter Mutlisig&Timelock, in future ArbiterDAO) (this parameter will be optimized with time to build the most beneficial systems for all parties) ### 2.3. Rent distribution to Liquidity Providers #### 2.3.1. Subscription Requirement - **In case of pool tokens being used as bid/rent token** there are no requirements. - **In case of other tokens being used as bid/rent token** LPs must subscribe to the hook to be eligible for rewards. #### 2.3.2. RentDistribution - **In case of pool tokens being used as bid/rent token** - Rent is distributed using the `donate` method on each swap and liquidity modification. - Rent is distributed to active tick - **In case of Protocol Token being used as the bid/rent token** - Rewards are distributed proportionally to the `SecondsPerSubscribedLiquidity`. - The mechanism of tracking for each tick `RewardsPerLiquididtyOutside` and `RewardPerLiquididtyTotal` is used to determine the due reward for Subscribed Positions. For each subscribed position contract tracks `RewardPerLiquididtyDistributed`. #### 2.3.3. Reward Collection - **In case of pool tokens being used as bid/rent token** - automatic via donate (no actions needed from LPs to collect) - **In case of Protocol Token being used as the bid/rent token** - LPs collect their rewards by calling `collect rewards` on the hook. --- ## 3. Implementation Details ### 3.1. Functionalities #### 3.1.1. `deposit` - **Purpose**: Allows users to deposit rent currency tokens into the contract. - **Process**: - Transfers Vault tokens from the user to the contract. - Updates the user's deposit balance. #### 3.1.2. `overbid` - **Purpose**: Allows users to place a bid for controlling swap fees. - **Validation**: - Check if desired rent end block number is sufficiently in the future (by at least `MINIMUM_RENT_TIME_IN_BLOCKS`). - Ensures the new `rentPerBlock` is higher by `RENT_FACTOR` unless within `TRANSITION_BLOCKS`. - Confirms the user has enough deposit to cover the total rent. - **Process**: - Refunds the remaining rent to the previous Winner. - Deducts the required rent from the new bidder's deposit. - Updates the `RentData` and `PoolHookState`. - Sets the bidder as the new Winner. #### 3.1.3. `withdraw` - **Purpose**: Allows users to withdraw their unallocated deposits. - **Process**: - Validates the withdrawal amount. - Transfers tokens back to the user. - Updates the user's deposit balance. #### 3.1.3. `beforeSwap` - **Purpose**: Adjusts swap fees during swaps. - **Process**: - Calls `_payRent` to handle any pending rent payments. - Determines the swap fee using the current strategy. - Charges custom swap fees and adjusts LP fees accordingly. #### 3.1.5. `_payRent` - **Purpose**: Internal function to handle rent payments. - **Process**: - Calculates the number of blocks elapsed since the last rent payment. - Deducts the rent from the Winner's deposit. - Distribute the rent to LPs by donating to the pool. - Handles strategy changes if the winner has changed. #### 3.1.6. `changeStrategy` - **Purpose**: Allows the winner to change the strategy starting from the next block. #### 3.1.7 `ICLSubscriber` - **Purpose**: In case of a Protocol Token being used as a bid/rent token, the ICLSubscriber is used to track users `liquididityPerSecond`. ## 4. Use Cases and Workflows ### 4.1. Bidders/Strategists #### 4.1.1. Depositing Tokens - **Action**: Call `makeDeposit` with the desired amount of specified `asset`. - **Result**: Tokens are transferred to the contract and added to the user's deposit balance. #### 4.1.2. Placing a Bid - **Action**: Call `overbid` with `poolKey`, `rentPerBlock`, `rentEndBlock`, and `strategy` addresses. - **Validation**: - Checks for minimum rent time and overbidding requirements. - Ensures sufficient deposit. - **Result**: If successful, the user becomes the new Winner, and the provided `strategy` will be used from the next block. #### 4.1.3. Implementing a Strategy - **Requirement**: Deploy a contract implementing `IArbiterAmmStrategy`. - **Functionality**: - Define custom logic for swap fees within allowed parameters. - Ensure compliance with gas limits (`GET_SWAP_FEE_GAS_LIMIT`). #### 4.1.3. Monitoring Rent and Managing Strategy - **Action**: Keep track of `rentEndBlock` and potential overbids. - **Strategy Update**: If needed, call `changeStrategy` to update the strategy contract. #### 4.1.5. Withdrawing Deposits - **Action**: Call `withdraw` with the desired amount. - **Result**: Unallocated deposits are returned to the user. ### 4.2. Liquidity Providers (LPs) - **In case of pool tokens being used as bid/rent token** there is nothing required to do. - **In case of other tokens being used as bid/rent token** 4.2.1. & 4.2.2 apply #### 4.2.1. Subscribing to the Pool - **Action**: Subscribe to the hook using `PoolManager`. - **Process**: - Interact with `ILiquididityPerSecondTrackerHook` to register for rewards. - **Result**: The LP's liquidity is tracked for reward distribution. #### 4.2.2. Collecting Rewards - **Action**: Call `collectRewards` whenever to collect rent. - **Process**: - The contract calculates and transfers the accumulated rewards to the LP. - **Result**: LP receives their share of the rent distributed. --- ## 5. Third-Party Integration Requirements - **Strategy Contracts**: - SHOULD implement `IArbiterAmmStrategy`. - SHOULD handle the `getSwapFee` function efficiently within gas limits. - **LP Subscription Interfaces**: - Third-party UIs should integrate with hook (`ICLSubscriber`) for LP subscriptions. --- ### B. Interfaces #### B.1. `IArbiterAmAmmHarbergerLease` Implemented by our hooks to manage the auctions and pool lease. [Refer to the provided code snippets in the zipped package.] #### B.2. `ILiquididityPerSecondTrackerHook` Implemented to track SecondsPerSubscribedLiquididty. **!! It will be removed and replaced by IRewardPerSubscribedLiquididty!!** [Refer to the provided code snippets in the zipped package.] #### B.3. `IArbiterAmmWithCakeRewards` Combines B.1 & B.2 to allow for tokens not from pools' trading tokens to be used for renting. [Refer to the provided code snippets in the zipped package.] #### B.3. `IArbiterFeeProvider` should be implemented by strategists [Refer to the provided code snippets in the zipped package.] #### B.5. `IArbiterAmmStrategy` Contract must be implemented by the strategists [Refer to the provided code snippets in the zipped package.] ---