# HARB Technical Design Document

## 1 - Project Overview

HARB is an economic experiment aimed at balancing issuance with taxation. The HARB token is structured to distribute value among participants in a manner that encourages participation, investment, and long-term engagement:
- Providing a Universal Basic Income(UBI), it caters to each and every token holder.
- With staking it introduces a new asset class that embodies a form of “partial ownership”, situated between private and common ownership.

This approach is designed to explore the dynamics of value distribution and economic sustainability within a decentralized economy.

## 2 - HARB Holders

HARB holders acquire and retain tokens to participate in the ecosystem, primarily benefiting from eligibility for UBI distributions.

### 2.1 UBI Distribution
- **Eligibility:** Available to all HARB holders, excluding stakers.
- **Mechanism:** Proportional to the [time-weighted average balance](https://v4-docs.netlify.app/protocol/design/twab-controller) of HARB held. The following formula is used to compute how much UBI a user is entitled to receive since the last claim:

$$UbiAmount = averageUbiPot * \frac{averageUserBalance}{averageTotalSupply}$$

**TODO:** describe TWAB Controller here

- Has to be claimed manually.

### 2.2 Tax Pool Contribution
- **Source:** Taxes from staked HARB fund the UBI pool. The tax rate is dynamic, and determined by a collective decision making process influenced by the expansion and contraction of the token supply.

## 3 - HARB Staking

By staking their tokens, stakers' percentage of the total supply of HARB is locked in and remains constant, safeguarding their investment's value against dilution from new token minting. This engagement provides dilution protection and the opportunity for strategic gains through active management of their staking positions.

### 3.1 Staking Mechanism

**Functionality:** Provides dilution protection without eligibility for basic income. The amount of HARB that can be staked is limited to 20% of its total supply. When holders stake, their HARB is transfered to the staking contract account. The staking contract subdivides this common pool with a percentage number for each user. 100% of the pool are represented by `AUTHORIZED_STAKE = 2 * 10^6 * 1 HARB`.

Staking freezes the user's share of the total supply. In exchange each holder receives a staking position, which is defined as follows:

struct StakingPosition {
    uint256 stakeShare;
    address owner;
    uint32 positionID;
    ...
}

Where:
- **stakeShare** represents the % of HARB total supply staked by the user. Its range is between **MIN_STAKE** and **AUTHORIZED_STAKE**, where `MIN_STAKE = AUTHORIZED_STAKE / 2000`. This effectively devides the stake into discrete sections of 0.01% of the HARB supply, prevening high fragmentation. fragmentation is undesired for [snatching](#34-Snatching), as it will increase the gas cost.
- **owner** is address of the user who owns the staking position,
- **positionID** unique identifier for each staking position, useful for tracking and managing individual stakes, especially in operations like snatch() and unstake().

**Share Calculation:** the stake amount follows a simple percentage calculation.

$$stakeShare = \frac{harbAmount * AUTHORIZED\_STAKE}{harbActiveSupply}$$

Where:
- **stakeShare** a percentage amount stakers receives for their HARB,
- **harbAmount** the amount of HARB which has been put into staking,
- **harbActiveSupply** the current total supply of harb excluding the staking contract's balance,
- **outstandingStake** the outstanding stake is the sum of all stake given to users. While not being part of the formulate, it is needed for limiting the stake to 20% of total supply of HARB. (TODO: can this be done in HARB instead of in stake? like `harbAmount + balanceOf(stakingPool) <= activeSupply * 0.2`)

The outstanding stake can not exceed authorized Stake, so the staking function needs to validate that `stakeShare + outstandingStake <= authrozideStake`.

**Unstaking:** ustaking is the inverste of the staking formula:

$$harbAmount = \frac{stakeShare * harbAciveSupply}{AUTHORIZED\_STAKE}$$

### 3.2 Harberger Tax Mechanism

Stakers actively participate in the Harberger Tax mechanism, setting their tax rates to maintain or improve their stake in the token supply.

- **Concept:** Allows staking positions to be "snatched" by others willing to pay a higher tax rate.
- **Dynamics:** Encourages active tax rate management, acting as a prediction market.

### 3.3 Tax Mechanism for Stakers
**Initial Rate:** Starts at 0%, adjustable by new stakers offering a higher rate.

**Structure** To enable the Harberger Tax the staking position struct is extended with two additional dates as follows:

struct StakingPosition {
    ... 
    uint32 lastTaxPaymentTimestamp;
    uint32 perSecondTaxRate;
}

Where:
- **lastTaxPaymentTimestamp** is a unix timestamp noting when the last tax payment was made for this staking position. It is ranging from the staking initiation time until the current block timestamp or the unstake event.
- **perSecondTaxRate** the rate applied to the staking position, stored in a way to allow per-second calculation.

The tax payment function for each staking position can be called at any time and calculates the **taxDue** as follows:

$$taxDue = \frac{stakeShare * harbActiveSupply}{AUTHORIZED\_STAKE} * \frac{elapsedTime * perSecondTaxRate}{10000}$$

Where
- **impliedHoldingExpiryTimestamp** `= (now - pos.creationTime < taxFloorDuration) ? pos.creationTime + taxFloorDuration : now;`
- **elapsedTime** `= ihet - position.lastTaxPaymentTimestamp`.

**Tax Floor Duration:** There is a minimum duration as basis for fee calculation, regardless of actual holding time, if a user decides to exit its staking position. It is set to 3 days. This disincentivises grieving other positions by snatching with a higher tax, then exiting the position immediately.

**Post-Tax Adjustment:** After paying the tax, the stakeShare is recalculated to reflect the decrease in the account's value. This involves recalculating the share as a percentage of the new total pool balance minus the tax paid.

$$newStakeShare = stakeShare - \frac{taxDue * AUTHORIZED\_STAKE}{activeSupply}$$

### 3.4 Snatching

**Concept:** Allows staking positions to be "snatched" by others willing to pay a higher tax rate.
**Dynamics:** Encourages active tax rate management, acting as a prediction market.

To make snatching less discrete and improve the UI, a snatch can extend accross many positions, and even include partial snatching of a position, as long as the new tax rate is higher than the tax rate of all positions touched.


Notice that a positoin can also be liquidated, if the accrued tax has consumed the whole balance of the stake.

## 4 - Token Economy Structure

### 4.1 Liquidity Manager Contract (LMC)
- **Role:** Entrusted with managing the liquidity pool on Uniswap V3 and endowed with the authority to mint and burn HARB tokens in response to market demands.
- **Key Functionality:** Features public `stretch()` and `shrink()` functions tasked with adjusting the liquidity position in line with prevailing market conditions.
- **Actions:** When the price diverges from the center of a liquidity position the functiosn will attempt to rebalance by minting HARB for an ETH overhang during `stretch()` or burning HARB for a HARB overhang during `shrink()`. Every time the `stretch()` function is called 5% of the newly gained ETH (the SAVINGS_RATE) will be channeled to a savings account in the LMC instead of being invested in the new liquidity position.
- **addLiquidity():** This is a special function with restricted access rights. It has the ability to take ETH from the savings account and create a new liquidity position with a custom range around the current tick.

The functions are visually explained in the following drawing:


A strategy can be implemented by carefully selecting the range, size and timing of new liquidity positions. Details are explained in [Liquidity Provisioning in HARB](https://hackmd.io/yNiN3TyETT2A1uwQVGYiSA).

### 4.2 Token Supply Mechanism
- **Initial Supply:** Commences at zero, with the supply dynamically regulated through minting and burning actions dictated by liquidity needs, as managed by the LMC.
- **Supply Adjustments:** Methodically executed by the LMC to counteract ETH overhang or HARB overhang, maintaining equilibrium in the liquidity pool.

### 4.3 Founders' Contribution and Rewards

- **Procedure:** Founders contribute 10 ETH, bootstrapping HARB liquidity on UniSwap V3.
- **Fee Allocation:** Liquidity Provider Fees directed to founders' multisig wallet as compensation.

### 4.4 Economic Activities
- **Trading:** Facilitated primarily through Uniswap V3, with additional market access provided by arbitrage bots that bridge liquidity across platforms.
- **Staking:** Designed to offer a hedge against dilution, allowing participants to secure a fixed proportion of the total supply. Stake is taxed by a self-assigned tax rate.
- **Basic Income:** Allocated to HARB holders on the basis of a time-weighted average balance, exclusive of staked amounts.

### 4.5 Minting & Burning

When new HARB tokens are minted, they must be allocated proportionally between the LMC's account and the staking contract's account. The formula

$$offsetAmount = \frac{stakingPoolBalance * mintAmount}{harbActiveSupply + dormantStake}$$

should be used, where:
- **offsetAmount** is the additional amount minted to the staking contract,
- **stakingPoolBalance** is the current size of the staking pool in HARB,
- **mintAmount** is the amount of HARB being minted to the account of the LMC,
- **harbActiveSupply** the current total supply of harb excluding the staking contract's balance,
- **AUTHORIZED_STAKE** a constant representing the maximum staking limit adjusted for precision by 5^10. See [Staking Mechanism](#31-Staking-Mechanism) for dietails.
- **dormantStake** `= AUTHORIZED_STAKE * 4`.

For burning HARB tokens, the goal is to reduce the stakingPoolBalance in a way that the staked tokens decrease in number but remain constant in percentage terms relative to the new total supply.

Assuming **harbBurned** is the amount of HARB to be removed from the account of the LMC, the formula to adjust the staking contract's balance could be expressed as:

$$offsetAmount = \frac{stakingPoolBalance * harbBurned}{harbActiveSupply − harbBurned + dormantStake}$$

Where:
- **offsetAmount** is the amount of HARB being removed from the staking pool.

### 4.6 Parameters and open Questions

- **Staking limit:** is the amount of HARB that can be staked. In the spec it is set to 20% of active supply. It affects dilution, and by that the volatility of the token. This can be any value up to 99% of the supply. when it is set to >= 50% it would lead to at least a quadrupling of total supply whenever active supply doubles. It could be adjustable after launch, if needed.
- **MIN_STAKE: (potential governance paramater)** set to `AUTHORIZED_STAKE / 2000` above. this limits the amount of stakers to max 2000. high fragmentation of stake is undesired, as snatching would potentially fail with block gas limit. first implementation will shed more light on cost and limits.
- **Initial Tax Rate:** set to 1% above. but could be 1/5/x%. a bit of basic income would probably be very encouraging for HARB holders at any time.
- **Max Tax Rate:** should there be a max tax? obivous points to cap it would be at 100%. why though?
- **Initial liquidity:** it is described as 10 ETH collected by founders. This can be any value, but obviously more initial liquidity would stability the price and create awareness for people monitoring the uniswap pool factory.
- **ERC 721 interface:** as each staking position has a `positionID`, the staking contract could implement the ERC721 interface with ease. I have decided to leave it out, together with a transfer function, to avoid confusion on decentrazide markets, where an NFT could be snatched while being on sale. ERC721 has a benefit of widely know, and making the stake more visible in wallets and 3rd party interfaces. need to weigh pros and cons for final decision.
- **Which network to launch on:** Optimism/Arbitrum/Mainnet?
- **SAVINGS_RATE:** the percentage of newly gained ETH that is not reinvested in a new position when `stretch()` is called on the LMC.

### 4.7 Risks
- **LP starvation:** LP ran out of money, no dilution -> no staking -> no tax -> no users. Worth [it's own document](https://hackmd.io/yNiN3TyETT2A1uwQVGYiSA)
- **inflation attack:** see [docs by open zepplin](https://docs.openzeppelin.com/contracts/4.x/erc4626#inflation-attack). the stake is a kind of vault and vulnerable too inflation attack. not sure I have fully mittigated it by putting the decimals of stake at `10^5 * 1 HARB`.
- **snatch collisions:** too many reverts could frustrate users.

## 5. Launch Network

### 5.1 Arbitrum
- has the [most TVL](https://info.uniswap.org/#/arbitrum/) among all Layer 2's in uniswap and in general
- has the most volume among [new projects and protocols](https://www.dextools.io/app/en/arbitrum/pairs)

### 5.2 Optimism
- [most volume](https://defillama.com/dexs/chains/optimism) in Uniswap; biggest TVL in velodrome
- mission alligned due to "Harberger Tax"

### 5.3 Base
- low TVL in [general](https://l2beat.com/scaling/tvl) and on [Uniswap](https://info.uniswap.org/#/base/)
- [many shitcoins ](https://www.dextools.io/app/en/base/pairs)