# Orderbook-based Segniorage Stablecoin

After the CoLoa hardfork, 3 new consensus contracts are deployed:
* [**NewSD**](https://explorer.nexty.io/address/0x0000000000000000000000000000000000045678) - the stablecoin ERC20 token, initialized with zero supply.
* [**MNTY**](https://explorer.nexty.io/address/0x0000000000000000000000000000000000034567) - the ERC20 wrapper of a million of NTY. Anyone can deposit NTY to get the token, and withdraw back to NTY anytime. This token is convenient for dapp usage including the Seigniorage DEX. The DEX will only interact with MNTY, and never NTY.
* [**Segniorage**](https://explorer.nexty.io/address/0x0000000000000000000000000000000000023456) - the on-chain DEX for MNTY/NewSD pair. Anyone can place limit order to exchange these 2 tokens. In the occasion of supply expansion or contraction, the orders of the appropriate direction will be absorbed by the consensus, in other words, consensus will execute an market order and filled as much order as necessary.

# 1. Consensus

## 1.1 Price Feed
* PriceSamplingInterval = 300 blocks (10 mins)
* PriceSamplingDuration = 302400 blocks (7 days)

NewSD/USD price can be fed to the consensus by the sealer/miner, every **PriceSamplingInterval** of block (~10 mins). Sealer can choose to feed the price or not. The median price is calculate by the median value of the last
**PriceSamplingDuration** blocks, (maximum 1008 values). The median price is only calculated when there's a super majority of sealers feed their prices. (That is 2/3 of 1008 = 672)

## 1.2 Exchange

DEX is an onchain decentralized exchange for MNTY/NewSD pair, built for converting between the two tokens. The limit orders placed there can be filled by other user order, or will be filled by the system absorptions.

The order ID is calculated as bellow:

OrderID = sha256(maker+index)

Where:
* **maker** is the address of the order maker
* **index** is the order index provided by the order maker

This allows user to manage their own off-chain order list, much like an HDWallet does.

## 1.3 Execution

In initialization phase of the block, before any user tx is included, the DEX.OnBlockInitilized() is executed by the consensus, generating the first tx and receipt in the block. This execution does:
* clear out any expired or finished absorption.
* unlock any finished preemptive lockdown.
* perform the market order to absorb the user limit order on the DEX.
* check the condition to trigger new preemptive absorption.

For every price block, the median price up to that block is passed to the DEX.OnBlockInitilized(MedianPrice), and the following additional actions are taken care by the execution:
* check any of the new condition to trigger new active/passion absorption.
* check any slashing condition to slash the preemptive initiator.

# 2. Absorption Mechanism

No NewSD is mint out of thin air, nor to anyone will. NewSD must be exchanged with NTY by the market demand itself.
There are 3 conditions for an absorption to be triggered.
1. [Passive](#21-Passive-Absorption)
2. [Active](#22-Active-Absorption)
3. [Preemptive](#24-Preemptive-Absorption-PeA)

## 2.1 Passive Absorption
Passive absorption is triggered when there is no absorption for a week. This is the most defensive supply absorption mechanism to make sure the supply will continuously adjust to even the smallest change of demand, when the network is mature and well adopted.

For Passive and Active conditions, NewSD supply change is always calculated by the fed Median Price.

$AbsorptionAmount = TargetSupply - Supply$
$AbsorptionAmount = Supply \times (MedianPrice - 1.0)$

## 2.2 Active Absorption
Active absorption is triggered when the price level is disruptively changed in an exponential ways, to quickly adjust to a new demand waves. An active absorption is triggered when.

$\dfrac{AbsorptionAmount}{LastAbsorptionAmount} \ge 2$ or $\le -\dfrac{1}2$

When the price keeps going in the same direction (up or down), the next supply Change must be at least two times as large as the last one. This condition allows the network quickly adjust to the sudden change of market demand, but still makes it exponentially expensive for adversaries to manipulate the price of NewSD.

When the price is changing in one direction (from up to down, or vice versa), the next supply change must be at least half as large as the last one, in opposite direction. This change of direction allow the network to wind down the absorption in a stabilizing market.

<img src="https://raw.githubusercontent.com/nextyio/gonex/gonex-edit/wiki/NewSD Absorption.svg?sanitize=true" alt="NewSD Absorption">

## 2.3 Absorption Process
For each block during the absorption, a market order is filled for the consensus with the amount of:

$AmountToAbsorbPerBlock = \dfrac{AbsorptionAmount}{AbsorptionDuration}$

If there's not enough limit order to fill, no more token supply is changed. Additional order can be placed during the absorption time.

The absorption will end after either:
* the target supply is reached, or
* the absorption time pass **AbsorptionDuration**

In the mainnet:

AbsorptionExpiration = 1 week
AbsorptionDuration = half a week

## 2.4 Preemptive Absorption (PeA)
This is the most complicated mechanism of absorption, but provide the necessary flexibility to adjust the supply without waiting for a price to be deviated too far from an anchoring value. Anyone can initialize a preemptive absorption with a stake and a price. PeA requires an voting auction before and Lockdown after the absorption.

### 2.4.1 Proposal Auction
The Auction for Initiator starts when the first intiator submits her proposal on chain. NTY holders will vote for them as soon as the proposal is submitted. Each vote can have the following values:
* Maker: address of the initiator.
* Amount: the amount of NewSD it wishes to change.
* Stake: the amount of MNTY to lock for slashing.
* SlashingRate: (optional) slashing rate.
* LockdownExpiration: (optinal) lockdown time (in block) for the Stake.

If SlashingRate and LockdownExpiration is not provided, the global version of the params is used.

Proposal Requirements:
* $Stake \ge \dfrac{2}{3}GlobalSuccessStake$
* $LockdownExpiration \ge \dfrac{2}{3}GlobalLockdownExpiration$
* $SlashingRate \ge \dfrac{2}{3}GlobalSlashingRate$

### 2.4.2 Voting and Ranking
Anyone with NTY and/or MNTY can vote for or against a proposal. The weight of each vote is the total of NTY and MNTY, and only calculate at the ranking time. An address votes for a proposal, then transfer all NTY and MNTY out after that will have zero weight after that.

A rank of the a proposal is calculate as below:

$Rank = Stake \times (\sum{VoteWeight_{Up}} - \sum{VoteWeight_{Down}})$

### 2.4.3. Activation
* No other *PeA* or Lockdown is in active. (The other 2 absorptions are allowed)
* There's atleast one Proposal satifies both of the following conditions:
* has proposed for atleast $GlobalLockdownExpiration/4$,
* has $Rank \ge \dfrac{2}{3}GlobalSuccessRank$ and $Rank \gt 0$

When the active condition is reached, the proposal with the highest Rank win the auction, and active a new Pre-emptive Absorption.

### 2.4.4 Adaptive Requirements
The following global params are adapting to each winning proposal and preemptive absorption:
* Proposal's Stake
* Proposal's SlashingRate
* Proposal's LockdownExpiration
* Pre-emptive Absoprtion winning Rank

The adapting formula:

$NewGlobalValue = \min\Big\{\dfrac{GlobalValue + NewValue}2,\dfrac{4}{3}GlobalValue\Big\}$

### 2.4.5 PeA Absorption
After the Voting Auction success, a new Pre-emptive Absorption is triggered with (Amount, LockdownExpiration, SlashingRate).
1. The absorption process is almost exactly the same with Active and Passive Absorption, except only **half** of the amount for each block is filled with orders from the exchange, the other half is preserved for [side absorption](#Side-Absorption)
2. PeA is treated exactly as Active and Passive Absorption: will override any on-going AA/PA, and will be overriden by new AA/PA if their condition is met.
3. A Lockdown is started independently with the absorption process. Lockdown prohibits new PeA, but does not prohibit new AA/PA. Lockdown is not canceled/aborted when by new AA/PA.

#### Side Absorption
For each limit order absorbed by a PeA, an identical limit order is filled for the PeA maker with her token allowance for the DEX. If the allowance and balance are not sufficient, the side absorption will simply be ignored.

The PeA absorption will continues until the target supply is reached, even when no side-absorption occur.

### 2.4.6 The Lockdown
During the lockdown, whenever the median price deviation goes in the opposite direction of the PeA:
* the absorption will be temporarily halted
* the maker will be slashed

The absorption will be resumed when the new median price goes in the same direction again.

The slashing MNTY amount is calculated as bellow:

$\sigma_{Price} = MedianPrice - 1.0$

$\sigma_{Absorption} = \dfrac{PeA.Amount}{TotalSupply}$

$ToSlash = \bigg|\dfrac{\sigma_{Price}}{\sigma_{Absorption}}\bigg| \times PeA.Stake \times PeA.SlashingRate$

The actual amount to be slashed must be positive and no more than the remaining stake.

$Slashed = \min\{ToSlash,RemainingStake\}$

If all the lockdown stake is slashed, the PeA will be prematurely stopped. Otherwise, the remaining stake will be refunded when the LockdownExpiration over.

### 2.4.7 Conclusion
Preemptive Absorption initiators are market makers, "bank" reserves, OTC dealers which are in control of large flows of money (NewSD). Not sitting outside of the system nor being centralized in anyway, they profit themselves by reserving and trading large amount of money (NewSD) while providing a high level of liquidity and stability to the network. As part of the decentralized system, anyone can be the Initiator, but without a large amount of fund, everyone can still be traders. NTY holders, initiators and traders together form a decentralized circle of stabilization, where each and everyone can profit themselves while provide the liquidity of NewSD as a service to the user of the network.