Developer Docs

Choosing proposedAmount


Increment elies on Curve for its price discovery mechanism. One drawback of Curve pools is that they don't include a function for returning the exact number of tokens needed to swap for a certain number of tokens from a trade (like the exactOutputSwap function in Uniswap). This has a direct impact on closing SHORT positions, as Increment can't deterministically derive vQuote prices for vBase positions. proposedAmount is Increment's proposition to deal with this issue.
It's worth remembering that all pairs are quoted in "USD". For instance, all positions in the ETHUSD market, whether LONG or SHORT, are ultimately settled and accounted for in USD. See Quote currency and Base currency to learn more.

When is proposedAmount needed?

Attentive readers of the documentation might have noticed that coming up with a proposedAmount is needed in 3 situations:
1. When a trader wishes to close or partially reduce his position (see Long/Short Trading).
2. When a liquidator desires to liquidate the position of a trader who's out-of-the-money with regards to the margin requirements (see Liquidation)
3. When a liquidity provider is looking to remove liquidity from one market (see Liquidity Provision)
Traders and liquidity providers interacting with Increment via the frontend don't need to worry about determining a proposedAmount as this is done under the hood (though it's still worthwhile to understand).

How to determine the value of proposedAmount?

For LONG positions
When selling LONG positions, the method is easy since LONG positions are in effect vBase assets. Closing such positions is just a matter of selling them at whatever price the notional vBase is quoted at.
In practice, closing a LONG position in full can be done reliably by submitting positionSize as the proposedAmount. When partially reducing a position, proposedAmount is positionSize times the ratio by which the user wants to have his position reduced (e.g. trader wishes to reduce by 50% his position, proposedAmount = positionSize * 5e17).
For SHORT positions
Closing a SHORT position is harder because SHORT positions are in effect vBase liabilities. They need to be bought back (using vQuote tokens) at their current market price. This assumes that we know at which price the notional vBase is quoted at.
There's no deterministic way to get proposedAmount from the Curve Contract. The only way is to guess it.
A good way is to call getExpectedVBaseAmount till you get an amount equal or slightly bigger than the short position of the user (i.e. the absolute value of positionSize). For those familiar with Curve,getExpectedVBaseAmount is essentially a wrapper above Curve's get_dy function which simulates a swap on the market from vQuote to vBase without actually performing it.
Another option is to use the function getProposedAmount in ClearingHouseViewer. This function takes care of calling getExpectedVBaseAmount multiple times to get a correct value for vQuote in the case of SHORT positions - which is slightly more comfortable than having to do that on the client-side. It's a view function but beware of its high gas cost, don't use it inside another smart contract function call.
If the amount is insufficient to buy the vBase debt, try a larger amount. If the amount is deemed too big, such that it would generate an undesirable swing in the market, reduce it a bit.
When a user wishes to partially reduce a position (e.g. trader or LP), proposedAmount is still in vBase but its value is proportionally smaller than what it'd be if the user sold the entirety of the position.
The problem a user faces when trying to close his positions completely can be described as follows. The optimal proposedAmount, x* solves:
minx\min x
such that
SWAP(x)>=positionSizeSWAP(x) >= positionSize
, where SWAP(X) trades vQuote for VBase tokens.

How to know if a position is a LONG or a SHORT?

For traders and liquidators
If the position considered is a trading position, it's straightforward. Increment just needs to look at the direction of the position as it was recorded when the trader opened the position. If positionSize is positive and openNotional is negative, it means that the position is LONG. Otherwise, it is SHORT.
For liquidity providers
If the position at hand is a LP position, it is a bit harder. If the market shifted in such a way that the price of vBase increased between the moment the LP provided liquidity to the market and the moment the liquidity is removed, the LP now owns more vQuote and less vBase than initially provided. The position is deemed to "look like" a SHORT.
If the market moved in the opposite direction, the position is deemed to "look like" a LONG.
This is significant in that the profit an LP makes from its provision of liquidity comes both from the trading fees it incurs and, potentially more importantly, from the movement of the market to which it has provided liquidity. The change in virtual assets balances in pools can be compared to the impermanent loss (IL) of AMMs and make the LP position appear either LONG or SHORT.
Check out the liquidity provider flow example to see how a LP position looking like a SHORT is depicted.
Considering that it can be very hard to come up with an exact proposedAmount and that the amount might be missing the mark by only a few wei, Increment has a mechanism called dust collection to help closing positions. It collects tiny base amounts remaining from reduced base positions and give them to Insurance.
Last modified 20d ago