Single source of truth for circulating kit and liquidity

[gkaracha]

To conform to TZIP-012 we need a total_supply view which provides the total supply of kit and liquidity tokens. Currently the former is stored as part of the parameters (parameters.circulating_kit) and the latter as part of the cfmm state (cfmm.lqt). Furthermore, the kit owned by the cfmm is currently tracked in the cfmm (cfmm.kit), but not on the ledger. To avoid inconsistencies it would be better to have a single source of truth: the ledger in the fa2_state.

Related: #133.

[gkaracha]

If we are gonna keep track of what checker owns as well, I guess we should be thorough.

So, some thoughts on who owns what: a) Checker holds/owns cfmm.kit (with 1mukit of that being immovable). b) Checker holds/owns 1n of liquidity (which is immovable). c) Liquidity providers hold/own parts of cfmm.lqt adding up to cfmm.lqt - 1n. Right now I think that the FA2 ledger keeps track of ( c ), but it does not keep track of either ( a ) or ( b ).

And some of my thoughts on how the amounts change and move, per entrypoint:

• entrypoint_mint_kit creates new kit owned by the burrow owner. We add it in its entirety to both the total circulating and the total outstanding.
• entrypoint_burn_kit destroys kit owned by the owner. Currently we remove it in its entirety from both the total circulating and the total outstanding. Some of that kit might end up as burrow.excess_kit but the only way to make that kit visible again is via minting, so it would get re-added then to the circulating and outstanding. I am not entirely sure it is OK to consider the parts of the amount that end up in the excess_kit field burned (that's what we are doing right now, because I thought it was OK, but I doubt it now). Probably we should instead treat each part separately:

  kit = up_to_outstanding + to_be_stored_as_excess

  The up_to_outstanding really should be removed from both the total kit in circulation and from the total outstanding kit. However, the excess should not really affect the total outstanding kit; we still need just as much kit to close all the other burrows. We probably shouldn't remove it from circulation either, because the burrow owner can "mint" it for free really, so I'd say it's pretty liquid. A big question is then: who owns the excess (as far as the fa2 ledger is concerned, I mean).

• entrypoint_buy_kit moves kit from checker's account to the sender's account.
• entrypoint_sell_kit moves kit from the sender's account to checker's account.
• entrypoint_add_liquidity moves kit from the sender's account to checker's account, and creates new liquidity tokens for the sender's acount.
• entrypoint_remove_liquidity moves kit from checker's account to the sender's account, and destroys liquidity tokens from the sender's account.
• entrypoint_liquidation_auction_place_bid accepts kit from the user, so it must move the old bid from checker to its owner, and move the new bid from the sender to checker.
• entrypoint_touch_liquidation_slices. Per slice: We remove kit_to_repay from the total kit in circulation and from the total outstanding kit. Since the kit is owned by checker (it must be owned by checker since placing a bid moves the kit to checker) I think we should destroy it from checker's account. We remove kit_to_burn from the total kit in circulation, but now the total outstanding kit. Still, since the kit is destroyed, I think we should also destroy it from checker's account.
• touch_with_index (the beast). We create some reward out of thin air, which is added to the sender's account, and also the total circulating kit. Touching the parameters increases the total outstanding kit by accrual_to_cfmm (also via imbalance but that is supposed to not count towards anything else, it's imbalance) which is also added to the total circulating kit. It is freshly minted, so it must be added to checker's account I believe. Touching also touches old slices so, per slice: We remove kit_to_repay from the total kit in circulation and from the total outstanding kit. Since the kit is owned by checker (it must be owned by checker since placing a bid moves the kit to checker) I think we should destroy it from checker's account. We remove kit_to_burn from the total kit in circulation, but now the total outstanding kit. Still, since the kit is destroyed, I think we should also destroy it from checker's account.
• The FA2 entrypoints move what they're supposed to move.

Any thoughts? (excuse the wall of text :upside_down_face:)

[gkaracha]

Just leaving a note here: the reason I didn't close this issue when #141 got merged is because I am still not entirely convinced about our current treatment of excess_kit. I overall still think that we should go about this more or less as I describe above

entrypoint_burn_kit destroys kit owned by the owner. Currently we remove it in its entirety from both the total circulating and the total outstanding. Some of that kit might end up as burrow.excess_kit but the only way to make that kit visible again is via minting, so it would get re-added then to the circulating and outstanding. I am not entirely sure it is OK to consider the parts of the amount that end up in the excess_kit field burned (that's what we are doing right now, because I thought it was OK, but I doubt it now). Probably we should instead treat each part separately:

kit = up_to_outstanding + to_be_stored_as_excess

The up_to_outstanding really should be removed from both the total kit in circulation and from the total outstanding kit. However, the excess should not really affect the total outstanding kit; we still need just as much kit to close all the other burrows. We probably shouldn't remove it from circulation either, because the burrow owner can "mint" it for free really, so I'd say it's pretty liquid. A big question is then: who owns the excess (as far as the fa2 ledger is concerned, I mean).

But I haven't gotten around to tweaking the current logic to separate the two amounts.