Inter Protocol Vaults: Contract Implementations

BLDer Community,

A prior forum post gave a high level overview of Agoric’s upcoming Mainnet 1B platform release. As mentioned in that post, Agoric OpCo has also invested considerable time writing the software that would be required for an expansion of Inter Protocol to include Vaults, as outlined in previous community documents such as the Agoric White Paper, Inter Protocol White Paper, and forum posts.

The following set of posts gives an overview of the core smart contracts and the associated functionality they enable. Please note that this implementation of the Vaults design as described in the documents above required choices in implementation at a greater level of detail. The BLD Staker community should consider these posts and the software references provided, and participate in discussions to determine whether to implement these contracts.

Sections include:

  • Vaults Contracts
  • Liquidation Details
  • Liquidation Auction Details
  • Example Auction CLI Bidding Tool
  • Protocol Reserve
  • Decentralized Oracle Network

Note these are currently running in Devnet and other testnets to verify functionality. Please be aware that while these posts outline the core functionality, they are not a complete and comprehensive description of the contracts. If there are areas that you’d like us to elaborate on, please ask in the discussion.

6 Likes

Core Vaults Contracts:

The vault contracts have access to the IST mint, receive a price feed from the Flux Aggregator Contract (see below), and work in tandem to allow a user to lock a collateral asset and mint IST against that asset, subject to several parameter constraints.

Once a Vault is opened, the holder can adjust it by depositing/withdrawing collateral and minting/burning IST in any combination, so long as their resulting vault meets those core parameter constraints. Users may open multiple vaults of the same type if they wish.

Key governed parameters include:

  1. Minimum Initial Debt - newly opened Vaults must mint at least this minimum amount of IST
  2. Liquidation Margin - (asset value based on price feed / minted IST) - the ratio below which a vault is liquidated, using the locked liquidation price (see below)
  3. Minimum Collateralization Ratio - (asset value based on price feed / minted IST) - expressed as a positive buffer amount above the liquidation margin (e.g., a liquidation margin of 150% with a buffer of 20% = 170% for minimum collateralization ratio). This represents the lowest collateralization ratio that a user can create or adjust their vault to
  4. Stability Fee - fee charged for maintaining an open Vault. Expressed as an annual percentage but charged more frequently
  5. Liquidation Penalty - penalty charged if vault is liquidated
  6. Mint Limit - the maximum net IST minted by a given Vault Manager for all its associated vaults. Currently, Vault Managers are 1:1 with collateral type

The above parameters, and several more, can be adjusted by a quorum vote of the Economic Committee, as described in their charter.

3 Likes

Liquidation

The code for determining which Vaults get liquidated lives within the vaultFactory. This code deals with ordering Vaults for liquidation, passing them to an auctioneer, burning IST raised for debt, and distributing additional penalties, proceeds, and/or shortfall to the reserve and/or to vault holders. See,

Effective liquidation is critical for maintaining the solvency of the protocol. Vaults allow IST to be minted against collateral which fluctuates in value and may fall below the value that was minted, which has the potential to leave the protocol less than fully backed. To avoid this, Vaults are liquidated when their ratio of collateral value to debt falls below the preset collateral-specific Liquidation Margin.

Liquidations are checked for on a regular basis - for example, every hour - and the price used to conduct liquidations is locked at some known time ahead of the liquidation auction - for example, every hour. Vaults will be liquidated based on the price that was locked ahead of time, regardless of what the market price does in the intervening period. This gives users a clear signal ahead of time when their Vault will be liquidated, and allows them to adjust their Vault back to a safe position. It is in the user’s best interests, as well as the protocol’s, to avoid liquidations. The contracts provide support so that third parties can write push notification capabilities that Vault holders could subscribe to.

When a liquidation occurs, the system groups all liquidated vaults of a single collateral type together for auction to meet the total debt of all liquidated vaults. There are multiple possible pathways depending on the result of that auction:

  1. Some collateral is sold and covers the debt: a penalty is taken and transferred to the Reserve, and some vaults may receive remaining unsold collateral (ordered by Vault collateralization ratio at time of liquidation)
  2. All collateral is sold but fails to cover the debt: no penalty is taken, and a shortfall is transferred to the reserve. All liquidated vaults are zeroed out.
  3. Some collateral fails to sell and the debt is not covered: the system attempts to reconstitute user Vaults one by one (minus the liquidation penalty), ordered by Vault collateralization ratio at time of liquidation. Vaults that can’t be fully reconstituted are zeroed out, and a shortfall and excess collateral are transferred to the reserve.
2 Likes

Liquidation Auction

The auction code covers the execution of the collateral liquidation auction itself. See,

The system employs a descending clock auction which starts at or above the current oracle price (as opposed to the locked price which triggers liquidation), and steps down in price filling bids as it goes. Its operation is based on a number of tunable parameters. Below is an example scenario demonstrating how the auction functions:

Assume the market price for collateral at the start of the auction is $10.

The auction’s first price step is set at $10.50, based on a 105% setting for its starting rate parameter

  • During this step, the auction fills any bids at or above $10.50 at its step price of $10.50, ordered by time the bid was received. “Bids by discount” are translated to priced bids based on the starting price of $10.00 and considered in this step
  • This step lasts for 180 seconds, based on the auction’s ClockStep parameter setting

The auction’s second step is set at a price of $10.00, based on its DiscountStep parameter setting of 5% (i.e., 5% of the starting price is $0.50)

  • During this step, the auction fills any bids at or above $10.00 at its step price of $10.00, ordered by time the bid was received. “Bids by discount” are translated to priced bids based on the starting price of $10.00 and considered in this step
  • This step lasts for 180 seconds, based on the auction’s ClockStep parameter setting

The auction proceeds by stepping down in the above manner. If it hasn’t reached its IST target amount or sold all its collateral, it continues stepping down until it completes its step at $6.50, based on its LowestRate parameter setting of 65%.

Most auctions will complete without reaching their final step. Bids that enter during the auction will be considered at any step where they are at or above the step price, however bids are filled in order of arrival.

The parameters governing the function of the auction may be set at launch. As written, the contracts grant the Economic Committee a temporary capacity to handle these parameters as the protocol stabilizes. Auction operational tuning is not part of the Economic Committee’s charter, and so an important topic of discussion may be how the community expects this capability to be used.

2 Likes

Example Bidding CLI Tool

Agoric OpCo has built a CLI tool for testing bidding on liquidation auctions. Bidding on liquidation auctions is also accessible via standard APIs. This tool also illustrates how to use the API via cosmjs. You may find it here:

This tool allows a user to place bids on liquidation auctions at any time. Bids must include the IST to be used, and may be formulated as by-price or by-discount. As described above in the auction section, bids by-discount are calculated against the price of collateral at the start of the auction.

3 Likes

Protocol Reserve

The Protocol Reserve acts as the accounting hub of the protocol and maintains assets earned as fees or contributed in other ways. See,

The Protocol Reserve has no end user facing elements. It primarily acts to manage accounting functions of the protocol. These include:

  1. Hold assets from protocol fees such as IST from Stability Fees or collateral assets taken from Liquidation Penalties
  2. Hold other assets contributed via asset transfers. For example, an external party could raise funds to contribute directly to the Reserve
  3. Track shortfalls from unsuccessful liquidations
  4. Burn IST to reduce shortfall 1:1 through a governed API call

This fourth item is a function that the Economic Committee can call on the Reserve contract. Since the action is not time-sensitive, the Economic Committee may choose to require a signaling vote from BLD Stakers before executing this authority.

3 Likes

Decentralized Oracle Network and Price Feed

The Vaults contracts rely on a robust price feed for accepted collateral. A decentralized oracle network composed of 5 Agoric validators with Chainlink node operation experience, led by Simply Staking, has been created that can support this effort.

Price submission by the node operators reaches the fluxAggregatorContract which takes a median of its inputs and provides a price feed that is consumed by the Vaults contracts. Oracle node operators may be added or removed from the network based on guidance from Simply Staking, with the Economic Committee acting in a temporary capacity as the executor of that guidance.

5 Likes

Contract Deployment Options

Agoric OpCo has also spent considerable time testing contract deployment with multiple approaches:

  1. Separate contract installation and deployment from chain upgrade, as expected for future third-party contract deployment
  2. Integrated installation and deployment of the Inter contracts, as was done with PSM installation

Approach #1 in practice is more complex than will be required for third-party contracts because Inter contracts get privileged authority to mint native IST. Thus, it entails some execution and governance fatigue risks, and takes longer to complete.

Approach #2 reduces the cost and effort of deployment, but requires that the Inter Protocol community determine and recommend the specific code and configuration (e.g., in a signaling proposal) to include with the platform upgrade. The community should consider both options and decide which is best.

4 Likes

Next Steps

The Vaults release is close to reaching its final production-readiness milestone, and now is the time for the community to prepare for the discussions and governance activities that would upgrade the Agoric chain to add Vaults to Inter Protocol.

To kick off the launch process, members of the community should take the lead on next steps and:

  • Participate in discussions in the Community forum, and deliberate on which approaches outlined above will be best for the future stability, decentralization, and success of Inter Protocol.
  • Stake your tokens to ensure that you are ready to vote as on-chain proposals go live during the run up to launch.
  • Stay tuned to community spaces like Twitter and Discord throughout the month of May for notifications about critical launch milestones like testnet exercises and on-chain governance proposals.
  • Participate in on-chain governance by creating and voting on proposals important to launch.

The BLD Staker community decides what will happen next on the Agoric chain and Inter Protocol and drives the launch of mainnet-1b and Vaults. As core developers prepare to cut the next release of the Agoric SDK, it is up to the community to prepare for the next launch in the Agoric Ecosystem.

4 Likes

Thank you, @rowland. Well written and informative.

Concerning the path forward, highlighted in this post: DCF would be supportive of approach #2 (above), that is, integrated installation and deployment. That option is the most time and cost efficient.

In terms of timing, given this chain of posts and your previous on the 1B release, I think we have the beginnings of a discussion that would support the launch of a signalling proposal, and we would be happy to help with that. The community does need to weigh in on configuration issues and parameter controls, but that too can be addressed in the signalling proposal. If we consider this latest thread as the starting period for the discussion, that means there should be a 5 days wait (the discussion period) before moving to the signalling proposal. If anyone has any objections to that process, please do speak up!

4 Likes

Hi Rowland. Thanks for the update! Exciting to see us getting closer to the Vaults launch!

If we proceed with Approach #2, which I see that @ricDCF has supported, is the “specific code and configuration” baked into the binaries for the release? Are we able to change this configuration later through governance proposals, or do changes require network upgrades?

DC

3 Likes

The security assessment of Vaults is now available at Agoric - Security. This security review is a key milestone for production readiness of the platform.
The assessment team from Atredis Partners surfaced 1 low severity and 1 informational issue.
If you’re interested in learning more about the Vaults contracts or want to review the full security assessment read more here.

3 Likes

Future upgrades to the contracts can occur without a chain upgrade! A big part of the platform work that went into this release was enabling that capability. Note that those upgrades will still require a chain vote (limited to executing the contract upgrade).

After this release, only upgrades to the Agoric VM will require chain upgrades.

2 Likes

Validatrium supports cost and time efficient approach

2 Likes

That’s great. We voted in support of the signaling proposal that advocates this approach.

DC

3 Likes

We (knowable.vc) have voted ‘yes’ on Prop32. It’s outside of our wheelhouse, but we have confidence in Rowland and the OpCo to responsibly deliver a mechanistically secure, well-configured, and well-audited update, and we have yet to see any dissenting opinions.

3 Likes

Awesome writeup - thanks @rowland. I am supportive of the integrated installation (option 2) for expediency.

Regarding the oracle implementation, there are a few areas I am curious to learn more about!

1. Will the data be coming from an official Chainlink data feed?

In the Agoric dev docs, I see an officially sponsored price authority and Any API mentioned. Are node operators submitting prices to the Agoric oracle network the same way they would the Chainlink network, pulling prices from the Any API and sending the Agoric network, or something else?

If the solution leverages official Chainlink data feeds, which one(s) is the team planning to use at launch? If I search for ATOM, I can see pricing is available from three networks - Arbitrum, BSC, and Moonbeam, each with a slightly different oracle operator set. Will this solution leverage one of these existing feeds, create a new feed, or something else?

Also, ~6 months ago I remember seeing a table on the Chainlink site that contained the underlying price sources - (Coinbase, Binance, Coingecko, Uniswap v3, etc), but am no longer am to find it. Would be curious if this type of information is available for the Agoric price feed (perhaps including venues like Crescent and Osmosis)!

2. From the devnet demo it seems like ATOM may be the only asset as launch, but how will bridging/depeg risks for assets like axlETH and gravETH be accounted for?

The ETH/USD price feed is probably the most live/robust, but wouldn’t account for a scenario like Nomad. And price feeds for gravETH and axlETH may have idiosyncracies due to lower liquidity.

3. Will the solution be able to support liquid staking derivatives, like stATOM and stOSMO?

If yes, is the idea to incorporate a price feed into the Agoric oracle network, and pipe this into the fluxAggregator contract? Or is the team considering integrating additional oracles (i.e. Osmosis TWAP) directly to a price authority contract?

4. What is the oracle mechanism for IST? Will assets be quoted in USD, and then converted to the market price of IST?

5. What is the process for adding new assets to the oracle contract? Is this controlled by econ committee governance?

Presumably, community builders (hi :wave:) will be looking to leverage these price feeds for the applications, so I am curious to know how this will work!

6. If official chainlink price feeds are not being leveraged, how is the team thinking about the long-term robustness and decentralization of the oracle network?

This is a bit open-ended, and I’m happy to expound on it. But more so am just looking to understand the future direction and plans!

1 Like

slightly tangential…

oops… those are pretty out of date. I just opened an issue about that. Note that we most likely won’t cover the operational aspects that you’re mostly asking about here, but for the API and such, stay tuned to…

Excellent question! This is what BLD staker governance is all about. As it says in the Inter whitepaper:

Governance determines the approved collateral types

That decision hasn’t been delegated to anything smaller than the whole BLD staker voting process. So to question 5, no, the econ committee can’t add a new collateral type.

So a proposal to bring on axlETH or the like as a Vaults collateral involves discussing such risks to the satisfaction of the BLD stakers.

Recall also from the Inter whitepaper:

2.5 Multiple levels of protection
The Inter Protocol implements several levels of economic protection to ensure that IST remains
100 percent backed, even in the case of a large drop in the price of collateral:

  1. Overcollateralization and Liquidation
  2. Reserve pool and IST fees
  3. BLD issuance

By way of precedent, recall the proposal to add PSM contracts for DAI_axl and DAI_grv:

The Economic Committee also has an important role to play: once the decision to approve a collateral type is made, the EC controls parameters noted above: Mint Limit, Collateralization Ratio, etc. These parameters can be used to mitigate bridge risk.

Again, by way of precedent, recall the discussion of starting small and expanding those limits for the PSM launch:

1 Like

Yes; any asset that can be transferred over IBC works the same way, as far as the contracts and related software are concerned.

How to arrange for reliable oracles is an important consideration in a BLD staker decision to bring on another collateral type. I’m not aware of any plan of record beyond for oracles ATOM, but I think there has been some brainstorming along the lines you note. I’ll let others share any brainstorming they care to :slight_smile:

1 Like