Contract integration

How to calculate prices at your Antelope smart contract

Interfaces

Make sure to import the TWAP Markets table interface otherwise the query will error with attempts to access data past the datastream.

```cpp
struct [[eosio::table]] markets{
        uint64_t id;
        eosio::name payer;
        eosio::asset target; // 0 amount of target token
        uint8_t position; // 0 = tokenA, 1 = tokenB
        uint8_t stored_days; // in days
        uint16_t delay_period; // in minutes
        uint32_t stale_after; // in seconds
        uint64_t market_id;
        int64_t cumulated_tick;
        uint16_t target_ticks_amount;
        uint16_t target_ticks_cumulated;
        int32_t initial_timestamp; // in seconds
        int32_t last_update; // in seconds
        std::string description;
        uint64_t primary_key() const { return id; }
        uint64_t market_key() const { return market_id; }
    };

    typedef multi_index<"markets"_n, markets,
        indexed_by<"market"_n, const_mem_fun<markets, uint64_t, &markets::market_key>>
    >markets_table;
```

Query

The next step is to query the TWAP contract by querying the markets table. Notice the scope we store data is the TWAP contract's value:

```cpp
eosio::name twap_contract = "breederstwap"_n;
markets_table markets(twap_contract, twap_contract.value);
auto market_itr = markets.find(market_id);

// check the market exists
check(market_itr != markets.end(), "Market does not exist.");
```

Then we utilize pointers to query each of the table's available data

Cumulated tick

int64_t cumulated_tick = market_itr-> cumulated_tick;

Last update

int32_t last_update = market_itr-> last_update;

Observation

As these table calls are not state-altering the TWAP contract, there is no need to copy the pointer value to a variable.

Price calculation

The contract is expected to know the amount of decimals of both tokens.

double conversion_factor = std::pow(10, tokenADecimals - tokenBDecimals);
int64_t avg_tick = ((market_itr-> cumulated_tick * 10000 ) / market_itr-> target_ticks_cumulated) / 10000;

double avg_price = std::pow(1.0001, avg_tick);

double true_tokenB_price = avg_price * conversion_factor 
double true_tokenA_price = (10000 / true_tokenB_price) / 10000;

Security

Make sure to check certain conditions before utilizing the price to validate requests.

Price staleness

Ensure the last_update for the price has not happened for longer than the stale_after defined period.

check(market_itr-> last_update + market_itr-> stale_after <= current_time_point().sec_since_epoch(), "Stale market");

Amount of cumulated ticks

Make sure the market is ready to be utilized.

During the initial deployment, markets haven't yet accumulated enough observations for the TWAP mechanism to work as intended. The recommendation is to freeze the utilization of this market until it has reached the target ticks amount:

check(market_itr-> target_ticks_cumulated == market_itr-> target_ticks_amount, "Target ticks not reached yet");

A project may choose to accumulate observations over a time period that is too long to wait. The recommendation is to define thresholds and handle the price based on its amount:

uint16_t custom_threshold = MINIMUM_TICKS_TARGET;
check(market_itr-> target_ticks_cumulated >= custom_threshold, "Target ticks not reached yet");

int64_t avg_tick = ((market_itr-> cumulated_tick * 10000 ) / market_itr-> target_ticks_cumulated) / 10000;