Technical specification

About this project

How do you turn your volatile crypto assets into a stable store of value? How can you leverage your digital holdings for access to a secure, new form of money?

Equilibrium is a framework of smart contracts working in concert to let users generate stablecoins (called EOSDT) that are pegged to the U.S. dollar and backed by their own crypto holdings. The EOSDT stablecoin is a useful store of value with a variety of applications, like hedging against market turmoil, providing fiat-like quotes for currency pairs on decentralized exchanges, and even online payments with merchants that accept cryptocurrency. It allows for more intuitive crypto transactions — one EOSDT always equals one USD.

The Equilibrium framework consists of four smart contracts that operate as follows:

The market data smart contract references cryptocurrency prices from the external mSectionarket through a trustline provided by Oraclize.it.

The Position Smart Contract receives a user’s cryptocurrency and holds it without any human involvement or custody risk.

The Liquidation Smart Contract lets arbitrators and market participants make money by liquidating under-collateralized user positions. This happens automatically when their collateral drops below the critical level of 130%. Arbitrators can claim liquidated collateral or surplus EOSDT at a markdown from current market prices, an associated fee will be payable in NUT tokenSections, which are then burned. This mechanism reduces the total NUT supply, potentially leading to NUT price appreciation due to the critical utility of the NUT asset within the Equilibrium framework.

The Governance Smart Contract lets users who hold NUT submit proposals to change the framework’s parameters on risk and stability. NUT holders can also vote for a list of EOS block producers they want to support with a fracSectiontion of Equlibrium’s total EOS collateral. This feature drives the growth, development, and maturity of the entire EOS ecosystem.

EOS uses a delegated proof-of-stake concept, which grants the community lots of flexibility in making instant high-level decisions, like rollbacks and bug fixes, with a majority accord among designated stakeholders. This approval voting system stakes the top 21 EOS block producers to produce blocks — EOS token holders must stake tokens for three days in order to vote. The top 21 candidates form the block producing core, and the rest become backup block producers, their priority is also determined by the number of votes they get.

Staking an EOS coin is like paying an opportunity cost — you can't unstake it until three days later, and you don’t have any access to it until then. This little cost grants you access to the entire EOS system. If you stake them for bandwidth, it means you can send transactions, and the size of transaction will consume your bandwidth.

Equilibrium uses the EOS blockchain because it is faster than Ethereum, has near-zero transaction fees, and offers great infrastructure for implementing cross-chain solutions. It presently supports the EOS cryptocurrency.

Technology review

The best decentralized applications not only require fast transaction processing times, but an infrastructure robust enough to offer a high-quality experience to lots of users at once. Equilibrium is built on the EOSIO technology stack because it offers decentralized storage and general purpose infrastructure for running EOS dApps more effectively than competitors. Transaction fees are effectively zero here, there’s a thoughtful resource balancing process, and transaction processing times are faster. These features substantially distinguish EOSIO technology from other second-generation blockchains currently on the market.

Stability

The framework’s stability comes from backing the EOSDT supply with the equivalent amount of USD collateral (or more). EOSDT cryptocurrency is pegged to the value of $1 USD in order to achieve this. An external price feed values the collateral, and the system constantly monitors the ratio of collateral to the total EOSDT supply to make sure it always meets the minimum threshold.

There are several external actors and internal mechanisms that help maintain market equilibrium.

Market-makers

These are large actors who generate a lot of EOSDT for their massive collateral stakes. They’re willing to make the market at various exchanges by profiting on the price spread between EOSDT and USD.

Arbitrators

These are actors willing to profit on EOSDT’s price deviations from the $1 USD peg. The mechanics behind arbitrage are pretty straightforward: when the price of EOSDT rises above $1 USD, there’s added incentive to generate it by supplying collateral and selling it on the market. This increases the supply of EOSDT and brings its price down to $1 USD.

When price of EOSDT falls below $1 USD, there’s an incentive for position holders to buy EOSDT on the open market and pay back their positions. This reduces the supply of EOSDT and brings its price up to $1 USD.

Equilibrium fee

Position holders may be incentivized to sell or expand their EOSDT holdings by the equilibrium fee. The framework applies the Equilibrium fee every time a user takes an action and calculates this fee based on an annual percentage rate, defined by Equilibrium’s governance smart contract. At the launch of the framework, the Equilibrium fee will be set to 0% APR.

If there’s an excess market supply of EOSDT, governance may decide to raise the applicable fee to induce position holders to sell off their “expensive” positions, lowering the supply of the stablecoins. If there’s excess demand for EOSDT, governance may lower the interest rate to induce users to enter more “cheap” positions, increasing the total supply. This is reminiscent of how central banks adjust short-term interest rates to control the economy’s supply of money.

A bundle of smart contracts

This documentation serves as an introduction to the Equilibrium framework, giving you an understanding of how it was designed.

The core of the Equilibrium framework consists of the following smart contracts:

Account nameSource Contract NameDescription

eosdtcntract

eosdtcntract

This contract implements the position management logic for Equilibrium users

eosdtsttoken

eosio.token + temporary burn

The stablecoin contract is based on the native eosio.token contract, but has additional burn and issue methods to help control the system’s supply.

eosdtnutoken

eosio.token + permanent burn

This utility token contract manages the Native Utility Token (NUT). It’s based on the native eosio.token contract, but has an additional permanent burn method for controlling the utility token’s supply mechanics.

eosdtorclize

eosdtorclize

This contract stores and refreshes exchange rates for user collateral and utility tokens. It gets its data from the external service Oraclize.it (now known as Provable).

eosdtliqdatr

eosdtliqdatr

This contract handles the liquidation of undercollateralized user positions.

eosdtgovernc

eosdtgovernc

The framework’s governance contract provides a means for NUT token holders to vote on changing the framework’s parameters.

eosdtreserve

eosdtreserve

Separates the reserve contract for possible emergency funding in case of global settlement.

eosdtbpproxy

eosdtbpproxy

The block producer voting proxy account. Will be used for REX staking.

Positions contract

The positions contract sets the logic for a user’s position management. It also stores the framework’s global risk parameters, which specify how the system behaves and govern the position creation process and a user’s position management. Equilibrium’s global risk parameters are configured by a governance mechanism, which means that NUT holders get to vote on proposals to change the framework’s parameters. If the majority agrees on new parameters, those become the norm.

SettingsOn-Chain NameDescription

Critical collateralization ratio

critical_ltv

The minimum acceptable ratio of pledged collateral to loan value. This is set to 130% by default.

Equilibrium fee

stability_fee

This is 0% per year by default, payable in EOSDT stablecoins as an interest rate on EOSDT.

Admin fee

governance_fee

This is set to 1% per year by default, payable in NUT utility tokens. This mechanism permanently reduces the NUT supply when EOSDT is repaid.

Liquidation penalty

liquidation_penalty

The system charges a 15% liquidation penalty by default, taking that percentage of the position’s collateral.

Liquidator discount

liquidator_discount

Liquidated EOSDT and collateral gets a 5% discount to incentivize arbitrators to redeem it from the liquidation contract.

Liquidation price

liquidation_price

The final price set when the system undergoes global settlement and the position contract is locked for further user fund settlements.

NUT liquidation weight

nut_auct_ratio

This parameter defines what fraction of the liquidation penalty will go to separate EOS balance on the liquidator for buying out with NUT. This is set to 30% by default.

NUT discount

nut_discount

Liquidated collateral and profit from REX is available to buy from the liquidator for NUT at a 6% discount from the current NUT oracle price.

REX Profit Factor

profit_factor

This parameter defines the profit distribution from REX. By default, 50% of REX profit goes to collateral holders and another 50% goes to the liquidator contract to buy NUT.

Voting period

vote_period

The number of seconds the system votes to reset vote decay. Will be used in BP voting/REX functionality. Currently not used. This is 10 days (in seconds) by default.

Stake period

stake_period

This specifies the interval at which the system stakes collateral to the REX. It’s set to 5 days (in seconds) by default.

Actions and methods for position contracts

Method nameParameterDescription
positionaddThis contract implements the position management logic for Equilibrium users

maker:'eosaccname11'

type:'positionadd'

collateraladdAdd collateral to the position.

from:'eosaccname11'

memo:'position_id:2'

quantity:'1.0000 EOS'

to:'eosdtcntract'

type:'transfer'

debtgenerateGenerate stablecoins on the position.

debt:'1.000000000 EOSDT'

position_id:'2'

type:'debtgenerate'

collateraldelRemove collateral from the position.

collateral:'1.0000 EOS'

position_id:'2'

type:'colateraldel'

debtburnbackPay back and burn EOSDT.

from:'eosaccname11'

memo:'position_id:2'

quantity:'0.510000000 EOSDT'

to:'eosdtcntract'

type:'transfer'

positiondelCheck that a position is EOSDT-free. Return collateral to a position owner. Close the position.

position_id:'2'

type:'positiondel'

positiongiveTransfer position ownership to a new account.

position_id:'2'

to:'eosaccname22'

type:'positiongive'

margincallClose an undercollateralized position, move a position’s EOSDT, and transfer collateral with a penalty to the liquidator.

position_id:'2'

type:'margincall'

reinitThis Private system function calculates the accrued fees between consecutive calls before transferring it to the liquidator contract. This function is called every time a position method is called.Private system function
receiveeosThis authenticates a liquidator account and transfers a requested quantity of EOS to the liquidator contract.Private system function

Web application (self-service gateway)

Equilibrium users may visit https://gateway.eosdt.com to supply collateral and generate stablecoins in the form of EOSDT tokens. Every communication with the positions contract is handled via Scatter.

Users can deposit and withdraw collateral, generate stablecoins and and pay them back, and move or close their positions from an intuitive interface.

Liquidator contract

This contract manages the balance between surplus EOSDT and collateral. It also tracks the total amount of “bad” EOSDT from margin call positions.

Surplus EOSDT accumulates on the liquidator contract, accruing from the total system EOSDT supply based on the current equilibrium fee, That EOSDT is sold for collateral — a so-called “debt auction.” Debt auctions help distribute the system’s surplus EOSDT.

Collateral balance accumulates on the liquidator contract from positions that got a margin call. This collateral is sold in exchange for EOSDT — a so-called “collateral auction.” Collateral auctions cover for “bad” EOSDT originating from positions that got a margin call.

Liquidator contract actions and methods

Method / TransferDescriptionExample

Transfer EOS

This transfer lets you buy collateral from the liquidator contract at a discount on the current market price. It supplies surplus EOSDT to the liquidator contract.

from:'eosaccname11'

quantity:'0.510000000 EOSDT'

to:'eosdtliqdatr'

type:'transfer'

Transfer EOSDT

This transfer buys surplus EOSDT from the liquidator contract at a discount on the peg price by supplying collateral.

from:'eosaccname11'

quantity:'1.0000 EOS'

to:'eosdtliqdatr'

type:'transfer'

Transfer NUT

This transfer buys EOS collateral from the liquidator nut_collat_balance pool for NUT at a discount.

Private system function

reducedebts

This burns a minimum current “bad” EOSDT and surplus EOSDT on the liquidator contract. This internal function cancels out bad EOSDT by burning it and decreasing its supply.

Private system function

Arbitrator bot

The liquidator contract’s design lets Equilibrium users compete for arbitrage opportunities:

The liquidator contract constantly offers EOSDT and collateral for sale. An arbitrator bot can margin call risky positions and buy their bad EOSDT or collateral from the contract. Any user may run the bot to compete with other users, and they’ll be buying surplus EOSDT and/or liquidated collateral at an incentivizing liquidation discount.

Rates contract

The Equilibrium framework requires access to real time market prices for collateral, so that the system knows when to trigger margin calls for undercollateralized positions. Outside of accurately knowing collateral prices, the system also needs a price for the NUT utility token to calculate the corresponding admin fee when users repay their stablecoins.

Each time the system calls its reinit() function, the rates contract checks to see if there are any active queries needing collateral and utility token rates.

The contract will check the age of any active query. If it’s more than one minute old, it gets removed from the queries table. A new query is made by calling the refreshutil() function.

If there are no active queries needing price information, the system creates a deferred action that will call rates with refreshutil() function. The refresh function calls the oracle service and returns timestamped price data. If the last timestamp is more than one hour old, refreshutil() is automatically called again. If the last timestamp is more than six hours old, the rates contract method will throw an exception.

Rates contract actions and methods

Method nameDescriptionExample

refreshutil

This function contains a special instruction for Oraclize (now Provable™), which is constantly listening to the EOS blockchain for such data requests.

payer:'eosaccname11'

symbol:'EOS'

type:'refreshutil'

callback

Oraclize will fetch or compute a price result, then build, sign, and broadcast the transaction carrying that result. This transaction initiates the callback function.

Private system function

Governance contract

Equilibrium uses the native <strong>eosio.forum</strong>{" "} contract structure for system governance, but with the following modifications:

  1. There are two types of proposals: parameter change proposals and general proposals.
  2. Only NUT holders can create proposals.
  3. Proposals are valid for a maximum of 30 days.
  4. Expired proposals are frozen for three days.
  5. For a proposal to successfully pass, it requires:
  • A minimum of 51% of the current NUT supply to have been cast in the voting process, like a simple majority shareholder vote.
  • At least 55% of all votes were “Yes“.

Global shutdown

The global shutdown mechanism is a part of the positions contract. There is a separate emergency fund (the eosdtreserve contract) whose main purpose is to ensure users receive their full collateral in the event of system insolvency. At the time of global shutdown, any positions with a collateralization ratio of less than 100% will be funded directly from this contract.

Global shutdown actions and methods

Method nameDescriptionExample

globallock

This locks the positions contract, disabling all methods related to position management except close().
It also fixes the EOS/USD price pair, which facilitates user reimbursements. It sets the liquidation penalty and discount to 0%, and the critical collateralization ratio to 1.

Private system function

close

This method only works when the system is locked. It transfers bad EOSDT and position collateral after winding down all positions to a collateralization ratio of 1.

position_id:'2'

type:'positiondel_internal'

unlockliqdtr

This checks that there are no positions left and it calculates a final auction price, the liquidator contract’s bad EOSDT divided by its EOS balance. It unlocks liquidator methods.

Private system function

generatedebt

An auxiliary method to generate EOSDT at auction price when that EOSDT is needed to fulfill obligations elsewhere.

from:'eosaccname11'

quantity:'1.0000 EOS'

to:'eosdtliqdatr'

type:'generatedebt'

calcauctprice

An internal method to calculate a new auct_price on the liquidator contract when additional funds have been received from the emergency fund contract.

Private system function

Emergency fund contract

Positions table:

ParameterDescription

position_id

ID of the position

depositor

Primary key, name of the position holder’s account. Just Oone entry per depositor is allowed.

EOS_balance

The total amount of EOS deposited for this depositor/position_id

withdrawal_date

Set to 0 by default. This is populated when a user withdraws funds.

Settings table:

ParameterDescription

unstake_period

This parameter governs how long a user must wait before withdrawing EOS from the funds contract. This is set to 30 days (in seconds) by default.

Actions and Methods:

Method / TransferDescriptionExample

deposit / Transfer EOS

deposits EOS into the emergency fund contract.

from:'eosaccname11'

quantity:'100.0000 EOS'

to:'eosdtreserve'

type:'transfer'

withdraw

Withdraws EOS from the emergency fund contract. Withdrawals are subject to a 30-day lockup period.

position_id:'2'

to:'eosaccname22'

type:'withdraw'

sendeos

Calculates how much EOS needs to be transferred to the liquidator contract to align the liquidator’s auction_price with liquidation_price. Reduces each position on the funds contract based on its relative weight.

from:'eosaccname11'

type:'sendeos'

The Equilibrium framework is a software service with a consensus based governance system. EOSDT and Native Utility Token (NUT) are not a security or a regulated instrument. The use of this site and the Equilibrium self-service gateway is subject to Terms and Conditions, by accessing this site you agree to these Terms.