Bidding for Liquidated Collateral

As of Vaults launch - bidders will be able to bid on liquidated vaults collateral via a CLI (Command Line Interface) tool. Bidding UIs may be built by the community or in the future by the Inter Protocol team.

The first thing you'll need to do is install and configure the CLI tool. Follow instructions at Inter Protocol Liquidation Bidding Test Tool installation/setup readme.

TLDR: CLI Commands for Bidding

The following commands will clone the Agoric SDK, install tooling, and place a bid. You will need to modify them for your bidding details. If you are not using a Ledger to sign, you'll need to do key management differently. See below for additional details.

Set-up and Configuration

git clone https://github.com/Agoric/agoric-sdk
cd agoric-sdk
SKIP_DOWNLOAD=false ./bin/agd build
export PATH=$PWD/bin:$PATH
alias inter="yarn run --silent agops inter"
export AGORIC_NET=main

Add account (Ledger)

agd keys add bid-acct --ledger --coin-type=118

Note: "bid-acct" is a name for the account and is used below in examples. However, feel free to name the account however you wish. This key command will use the derivation path for account 0 with that ledger seed phrase.

If you want to bid on a non-ledger account, you will need to handle key management in the CLI differently. Be careful of which options display seed phrases or store them in the clear on your machine. Use the --help command on "agd keys add" for details.

Place a bid (by Price)

inter bid by-price --price 9 --give 50IST --maxBuy 10000ATOM --generate-only --from bid-acct >spend-action.json
agd --node=https://main.rpc.agoric.net:443 tx swingset wallet-action --allow-spend "$(cat spend-action.json)" --chain-id=agoric-3 --fees=5000ubld --from bid-acct --sign-mode amino-json

Modify the bid details above to match what you desire. The example places a bid of 50 IST for ATOM (maximum of 10000) at a price of $9.

If you are not using a Ledger, the second command should not include the --sign-mode amino-json modifier

Place a bid (by Discount)

inter bid by-discount --discount 5 --give 50IST --maxBuy 10000ATOM --generate-only --from bid-acct >spend-action.json
agd --node=https://main.rpc.agoric.net:443 tx swingset wallet-action --allow-spend "$(cat spend-action.json)" --chain-id=agoric-3 --fees=5000ubld --from bid-acct --sign-mode amino-json

Modify the bid details above to match what you desire. The example places a bid of 50 IST for ATOM (maximum of 10000) at a 5% discount to the oracle price. Note that "oracle price" refers to the oracle price at the start of the auction.

If you are not using a Ledger, the second command should not include the --sign-mode amino-json modifier

Liquidation Bidding Discussion & Details

Things to Know

  • Important: to support some critical bidding capabilities, bids for Inter Protocol do not benefit from Zoe offer-safety

  • You must specify if you are bidding for a particular collateral type by using the '--maxBuy' argument i.e. '--maxBuy 5000stATOM' infers you are a) bidding for stATOM and b) for a maximum of 5000 stATOM. For ATOM it would be '--maxBuy 5000ATOM' etc.

  • You can bid at specific prices or at discounts to the oracle price. The oracle price is locked at the start of the auction and discounts calculate off of that price (i.e., they do not update in real time as the market shifts during the course of the auction)

  • You can place liquidation bids even when there is no active liquidation happening. The bid will remain in the auction order book until it is filled or cancelled

  • Once a bid is placed, the IST amount you are bidding with is removed from your wallet balance.

  • If your bid is successful, you will receive the collateral as payout as per your bid terms.

  • If you cancel an active/existing bid, your IST will be returned to your wallet balance.

  • Your bid may also be partially filled if it is the concluding bid of the auction. Partially filled bids will remain in the order book to be fully filled in future auctions unless they are exited

Check Auction Status

While you can place liquidation bids even when there is no active liquidation happening, it may be useful in your bidding strategy to know whether a liquidation is taking place and where the auction is at that point in time amongst others.

You can check the status as well as other important liquidation-specific pieces of information such as:

  • nextStartTime -> This is when the next auction is scheduled to take place. Time is in UTC.

  • startPrice -> Starting price of the auction. This is the current market price as per oracle.

  • currentPriceLevel -> Once the auction has started, this indicates the step price the auction is currently at.

  • startProceedsGoal -> This is the target IST debt amount based on liquidated vaults. The auction will keep ticking forward to sell enough collateral to satisfy this amount.

  • startCollateral -> The amount of collateral that has been liquidated and sent for auction.

  • collateralAvailable -> The amount of collateral remaining at that point in time of the auction. If the auction sells enough collateral to satisfy outstanding IST debt, the auction may end with unsold collateral which will be distributed back to vault holders (minus penalty fee).

  • DiscountStep -> This is the price step change size (in %) the auction will follow

  • ClockStep -> This is how long each price step last before proceeding to next downward price step change.

  • LowestRate -> This is the lowest discount rate the auction will reach before stopping. I.e. the auction will not sell collateral beyond this discount rate.

To check this run inter auction status --book 0 in your terminal window after you've installed the CLI bidding tool to check ATOM auction status or inter auction status --book 1 to check stATOM auction status. Sample output:

{
    "activeStartTime": "2023-07-05T15:22:00.000Z",
    "nextStartTime": "2023-07-05T15:32:00.000Z",
    "nextDescendingStepTime": "2023-07-05T15:23:40.000Z"
  },
  "book0": {
    "startPrice": "12.34 IST/ATOM",
    "currentPriceLevel": "10.489 IST/ATOM",
    "startCollateral": "0 ATOM",
    "collateralAvailable": "0 ATOM"
  },
  "params": {
    "DiscountStep": "5.00%",
    "ClockStep": "00:00:20",
    "LowestRate": "65.00%"
  }
}

The liquidation auctions will continue until enough IST has been raised to satisfy the liquidating debt, after which the liquidation will be complete. After each successful auction, liquidation status will update to reflect progress with liquidating collateral and debt reducing over time.

Placing Bids

When placing a bid you’ll need to specify the amount of IST you are bidding with and the collateral price you are willing to accept/have your bid filled at.

You can specify the price in one of two ways:

  1. specific price ($) -> (inter bid by-price --price X.XX --give XIST --maxBuy XATOM --from bid-acct)

  2. as a % discount to the oracle price (%) -> (inter bid by-discount --discount X --give XIST --maxBuy XATOM --from bid-acct)

How To Bid

  1. By discount -> You’ll do this by entering the inter bid by-discount command. Example: Let’s say you want to place an 50 IST bid for ATOM (maximum of 10000) at a 10% discount price from the oracle price. When submitting a bid, use --generate-only to first output it to json:

    e.g. inter bid by-discount --discount 10 --give 50IST --maxBuy 10000ATOM --generate-only --from bid-acct >spend-action.json. (Note: it doesn't matter which address you use here, but the tool requires a well-formatted address or a name in your keyring)

  2. Then use agd to sign and broadcast the offer (including chain ID and fee amount); for example:

    1. Example operation (using a ledger):

      % agd --node=https://main.rpc.agoric.net:443 tx swingset wallet-action --allow-spend "$(cat spend-action.json)" --chain-id=agoric-3 --fees=5000ubld --from bid-acct --sign-mode amino-json

    2. Example output (using a ledger):

      {"body":{"messages":[{"@type":"/agoric.swingset.MsgWalletSpendAction","owner":"agoric1...","spend_action":"{"body":"#{\"method\":\"executeOffer\",\"offer\":{\"id\":\"bid-1688150122262\",\"invitationSpec\":{\"callPipe\":[[\"makeBidInvitation\",[\"$0.Alleged: BoardRemoteATOM brand\"]]],\"instancePath\":[\"auctioneer\"],\"source\":\"agoricContract\"},\"offerArgs\":{\"maxBuy\":{\"brand\":\"$0\",\"value\":\"+1000000000000\"},\"offerBidScaling\":{\"denominator\":{\"brand\":\"$1.Alleged: BoardRemoteIST brand\",\"value\":\"+100\"},\"numerator\":{\"brand\":\"$1\",\"value\":\"+70\"}}},\"proposal\":{\"give\":{\"Bid\":{\"brand\":\"$1\",\"value\":\"+50000000\"}}}}}","slots":["board05557","board0257"]}"}],"memo":"","timeout_height":"0","extension_options":[],"non_critical_extension_options":[]},"auth_info":{"signer_infos":[],"fee":{"amount":[{"denom":"ubld","amount":"5000"}],"gas_limit":"200000","payer":"","granter":""}},"signatures":[]}

    confirm transaction before signing and broadcasting [y/N]: y code: 0 codespace: "" data: "" events: [] gas_used: "0" gas_wanted: "0" height: "0" info: "" logs: [] raw_log: '[]' timestamp: "" tx: null txhash: 119D16E9F9A050FCDB4C450F3A3312E097C5BAFBA39871F2D30095878FED4D78

  3. You'll then need to confirm 'Y' to sign and broadcast - (you may have to approve in ledger if you're using one).

The output should include a tx hash such as 38E782E5A70D0704BC76323A7032B3C7FD4940B4EA4AE4CB64AFC9D203AF82A8 which you can look up in an explorer.

You can also confirm with inter bid list (operation more details on this further below):

inter bid list --from [your Agoric address]
{"id":"bid-1688145581493","price":"7 IST/ATOM","give":{"Bid":"0.003 IST"},"maxBuy":"1000000 ATOM","result":"Your bid has been accepted"}

By Price

You may also bid by a specific price rather than a calculated discount to the oracle price i.e. '-by-price --price 9.3' (to place a bid bid to buy ATOM for a price of $9.3) instead of '-by-discount --discount 10'.

List all of your bids

Once your bid is successful it will no longer appear in the above list. In order to see all bids (including those that were successful with payouts), you’ll need to append command with ‘–all’. Example:

inter bid list –from bid-acct –all

Output:

$ inter bid list --from bid-acct --all

{"id":"bid-1697252890125","discount":15,"give":{"Bid":"166.675 IST"},"maxBuy":"1000 stATOM","payouts":{"Bid":"0 IST","Collateral":"17.842423 stATOM"}}
{"id":"bid-1697746565122","discount":15,"give":{"Bid":"5 IST"},"maxBuy":"1000 stATOM","result":"Your bid has been accepted"}

Cancel bid

Once a bid is placed, the IST amount you are bidding with is removed from your wallet balance until the bid is successful (after which you receive your collateral payout) or you cancel your bid (after which your IST is refunded (reflected as a payout in output)).

The current design of our liquidation system constrains the ability to change an existing open bid. Instead, you will need to cancel the open bid and resubmit a new updated bid instead. To cancel a bid you’ll need to use the ‘inter bid cancel’ command then specify the bidID which you can grab from the bid list described above. Example: 

inter bid cancel bid-1697253297042 --from test-acct --keyring-backend=test

Output:

inter bid cancel bid-1697253297042 --from test-acct --keyring-backend=test
2023-10-25T19:45:45.794498078Z tx not in block 2131521 retrying...
2023-10-25T19:45:51.435408143Z tx not in block 2131522 retrying...
2023-10-25T19:45:51.435408143Z tx not in block 2131522 retrying...
2023-10-25T19:45:57.123880452Z tx not in block 2131523 retrying...
2023-10-25T19:46:02.865817964Z tx not in block 2131524 retrying...
2023-10-25T19:46:02.865817964Z tx not in block 2131524 retrying...
2023-10-25T19:46:08.52605143Z tx not in block 2131525 retrying...
cancel action is broadcast:
{"timestamp":"2023-10-25T19:46:02Z","height":"2131524","offerId":"bid-1697253297042","txhash":"E1FF10FE7E22ED165CCB734F9B26341A938F4FE0F8513BAA312865571E639053"}
bid bid-1697253297042 is no longer live
{"time":"2023-10-25T19:46:14.173352277Z","height":"2131526"}

Then check bid list, inter bid list --all --from test-acct --keyring-backend=test to confirm your IST has been refunded under ‘payouts’:

inter bid list --all --from test-acct --keyring-backend=test              
{"id":"bid-1697252890125","discount":15,"give":{"Bid":"166.675 IST"},"maxBuy":"1000 stATOM","payouts":{"Bid":"0 IST","Collateral":"17.842423 stATOM"}}
PreviousMinting IST - PSMNextIST Usage and Beyond

Last updated