Running the crank

The crank is a mechanism within the Levana Perps market contract to handle work items that don't fit into the normal blockchain transactional paradigm. This includes, but is not limited to:

  • Periodically collecting fees from users. Fee collection happens over time and is not tied to a specified user transaction, so some kind of extra mechanism needs to run these transactions.
  • Liquidations and other price triggers. These actions run in response to changes in the market price, not from an immediate action the user took.
  • More esoteric cases, such as resetting the LP balances in the extreme case of total liquidity pool liquidation. This handles the fact that there is an unbounded amount of computation to perform and it may need to span multiple transactions.

The common denominator here is that the crank handles core tasks that are vital to the health and stability of the platform. If fees are not collected and positions not liquidated, we can end up in an illiquid state, which violates the core premise of Levana Perps. So how does the crank get run?

Under normal circumstances, we leave cranks to a crank bot, which essentially:

  1. Queries the contract to determine if there's work available to be done.
  2. If there is work to be done, it "turns the crank."

While crank bots are ideal for this, this page documents how to manually run this process so that:

  • Others can implement their own crank bots.
  • If necessary, such as all crank bots being unavailable, individuals can run the crank themselves. This is key to the decentralization strategy of Levana Perps: cranking is a fully permissionless process that anyone can engage in. Furthermore, our goal is that, long term, crank fees and crank rewards will fully reimburse crankers for the gas fees they pay in cranking, making it a net-profit opportunity.

Resources

You'll need the list of factory contracts. We'll also be referencing the message API documentation. And finally, we'll use Levana's smart contract GUI for interacting with the contracts, though you can also use other approaches for interacting with the contracts.

OK, let's see how to crank!

Get the market contract

Open up the smart contract GUI, choose the network you want to query, and under "message type" choose "raw message." In the "contract address" field, enter the factory address from the list referenced above, e.g. osmo1ssw6x553kzqher0earlkwlxasfm2stnl3ms3ma2zz4tnajxyyaaqlucd45 for Osmosis. Then click on "query message."

Next, you can use the following query to list the markets available for that factory:

{"markets":{}}

At the time of writing, you'll get a response that looks like:

{
  "markets": [
    "ATOM_USD",
    "BTC_USD",
    "OSMO_USD",
    "SEI_USD",
    "axlETH_USD"
  ]
}

Next, you'll want to get information on the specific market you're trying to crank. Supposing you want to crank the ATOM market, you'll run the query:

{"market_info":{"market_id":"ATOM_USD"}}

Which will give you a result such as:

{
  "market_addr": "osmo1hd7r733w49wrqnxx3daz4gy7kvdhgwsjwn28wj7msjfk4tde89aqjqhu8x",
  "position_token": "osmo12dftzwa3dcuu7snpadu2ur9q8vcquuzy0ua292cupfvnj9r2qmlsp8u7hw",
  "liquidity_token_lp": "osmo1kp5nhg2eqcv8zwc0ndgjj7w8pk8dzhu58jfk4q0ptfywj2m42qvqhh9dcv",
  "liquidity_token_xlp": "osmo157qp6kjse4mkaw2wtrhl3a0djp6ymcgdg5vrmfk48ftsecx8pm3sc97vap",
  "price_admin": "osmo1qt08s00nfgrxvpx74hvucpctsffgnr6n54lgkd6lntgcylfs4u6qy6gy0m"
}

You'll want to use the market_addr field for further interactions. Copy/paste that value (osmo1hd7r733w49wrqnxx3daz4gy7kvdhgwsjwn28wj7msjfk4tde89aqjqhu8x) into the "contract address" field.

Check for crank work

To check for crank work, you'll want to make a status query. The status query looks like this:

{"status":{}}

This will return a lot of information on the protocol, such as the config and liquidity available. However, the primary thing we care is the next_crank field. If it's null, there's no current work to be done in the crank queue. If it's anything except null, there's work to be done. Also interesting are the following fields:

  "stale_liquifunding": null,
  "stale_price": null,
  "congested": false,

These indicate whether the protocol has reached staleness (when too much time has passed without a crank or price update) or become congested (when too many backlogged cranks are still waiting to be processed).

Assuming that there's some work on the crank queue, the next step is to execute it.

Run a crank

For the next step, click on "execute message" instead of "query message." The crank message itself is nice and simple:

{"crank":{}}

There are additional parameters you can set if you want, which are covered in the API documentation. But this message will execute up to 7 work items and send any crank rewards to the calling wallet.

And that's it! Now you too can be part of the proper functioning of the Levana Perps system.