API Overview

We will need the vAMM volume on the market depth API so that we can show this in the order book for users.

Our understanding / assumption is that for performance reasons we cannot do this across the whole order book, since AMM volume goes to infinity price in theory. So the assumption is that you will provide it in some range of the mid, and to some level of granularity, and we will need to work out what is achievable through performance testing.

Outside this range we request some sort of estimate of the remainder of the shape, again probably at configurable resolution. To keep this info in one place I've assumed this will be on the same API and included as part of this ticket, but am open to other implementation options like a seperate API for that.

API request details

[ ] Include real known AMM volume at each price level on the market depth API
[ ] Include the estimated AMM volume at each price level

NB. The resolution of the price levels provided by AMM, the range between which the AMM volume is real, and outside which it is estimated should all be defined by network parameters and optimised during performance testing.

Filtering requirements (inputs)

[ ] Show only CLOB volume price levels
[ ] Show only AMM volume price levels
[ ] Show levels with both

Sample API output (optional)

{
    "price": "17250",
    "numberOfOrders": "1",
    "volume": "100",
    "volumeAAM": "0",
    "volumeAAMEstimated": "0"
},
{
    "price": "17249",
    "numberOfOrders": "1",

    // normal amount on book
    "volume": "100",      

    // amount on book from aam                
    "volumeAAM": "10",

    // I think this would always zero here?
    "volumeAAMEstimated": "0"
},
{
    "price": "17248",
    "numberOfOrders": "1",

    // no normal orders
    "volume": "0",            

    // but some aam              
    "volumeAAM": "100",
    "volumeAAMEstimated": "0"
},
{
    "price": "17247",
    "numberOfOrders": "1",

    // no normal orders
    "volume": "0",  

    // no aam 
    "volumeAAM": "0", 

    // but 500 estimated
    "volumeAAMEstimated": "500"
}

Questions

~TBC on the performance questions and whether we set these in the UI or if they are dictated by the network. Or maybe the max is dictated by the network but there is configurability beneath that in the UI? Dont know.~

~This configuarability would need to be avalable on both the actual order book volume that trades can be matched with AND the estimated volume out to the extremes of the range and be individually configurable so it can be optimised.~

All config around number of price levels / granularity will be handled by network params.

API test scenarios

Detailed scenarios that can be executed as feature tests to verify that the API has been implemented as expected.

GIVEN (setup/context) WHEN (action) THEN (assertion) For example... See here for more format information and examples.

Additional Details (optional)

Any additional information that provides context or gives information that will help us develop the feature.

I don't think we need to be able to control the price level granularity via the API, we already do this entirely client side, its snappier this way too. That said if the projected amount of aamEstimated price levels are huge we might run in to issues.
It would be better to avoid having multiple entries for the same price level, instead lets have additional fields. This will make it easier to project the book outwards and also have more detail on each price level
Type should probably follow some conventions we use elsewhere.. PRICE_LEVEL_TYPE_CLOB, PRICE_LEVEL_TYPE_AAM_ESTIMATED etc

Example asks:

{
    "price": "17250",
    "numberOfOrders": "1",
    "volume": "100",
    "volumeAAM": "0",
    "volumeAAMEstimated": "0"
    "type": "PRICE_LEVEL_TYPE_CLOB"
},
{
    "price": "17249",
    "numberOfOrders": "1",

    // normal amount on book
    "volume": "100",      

    // amount on book from aam                
    "volumeAAM": "10",

    // I think this would always zero here?
    "volumeAAMEstimated": "0"
    "type": "PRICE_LEVEL_TYPE_CLOB_AND_AAM"
},
{
    "price": "17248",
    "numberOfOrders": "1",

    // no normal orders
    "volume": "0",            

    // but some aam              
    "volumeAAM": "100",
    "volumeAAMEstimated": "0"
    "type": "PRICE_LEVEL_TYPE_AAM"
},
{
    "price": "17247",
    "numberOfOrders": "1",

    // no normal orders
    "volume": "0",  

    // no aam 
    "volumeAAM": "0", 

    // but 500 estimated
    "volumeAAMEstimated": "500"
    "type": "PRICE_LEVEL_TYPE_ESTIMATED_AAM"
}

vegaprotocol / vega

Enhance Market Depth API to include vAMM volume #11020