Price Module Design

[epiro-ps]

Description

The Price Module is a system that updates the USD price of ADA on-chain every hour. It consists of the Price Module Validator, the Price Updater CLI, and the Price Worker.

Interactions

Price Updater

The Price Updater CLI can be called to initialize and update the dUSD to ADA oracle price data on-chain.

Acceptance Criteria

Price Module Validator

• The off-chain code will be built in CTL.
• The on-chain code will be written in Plutarch.
• The validator should be parameterized by the admin's public key.
• The validator will validate the following:
  • There is a previous price oracle UTxO being spent.
  • The previous price oracle UTxO is being spent by Admin.
  • The previous price oracle UTxO contains the Oracle ID NFT.
  • The datum has a list of tuples containing USD Price of ADA and the POSIX timestamp of when the price was observed.
  • The datum list does not exceed 48 entries.
  • The timestamp of the latest two entries of the datum list are at least an hour apart.
  • The timestamp of the first entry in the datum list is within an hour of the timestamp of the transaction.
  • The tail of the datum list matches the sequence of the previous price oracle UTxO's datum list starting from it's first element.
  • The timestamp of the previous price oracle UTxO is at least an hour behind the transaction.
  • The Oracle ID NFT is being moved to the new Price Oracle UTxO.

Price Updater

As an admin, I would like to run the Price Updater where the following is true

• I can run price-updater --help to get adequate documentation on how to use the executable.
• I can run the Price Updater with either a key wallet stored in a JSON file or a YubiHSM wallet.
  • Specifying the --keyWallet=<file path to keywallet> flag will load an skey JSON file by it's path.
  • If keyWallet is not specified, the YubiHSM will be used.
• I can run the command price-updater --network=<name of network associated with admin keys> ... resulting in the following
  • A configuration file is generated and placed at ./ containing the following structure:

    {  "nftAssetClass": "<asset class of price oracle NFT>"
    ,  "network": "<network that the oracle has been deployed to>"
    ,  "adminWallet": "<optional keywallet value provided>"
    }

• I can run the command price-updater --config=<path to generated config file> ... where the config file is valid, the following two outcomes are possible:
  • If the on-chain price data hasn't been updated in at least an hour, the script will attempt to update the price and return a message regarding the results of the transaction attempt.
  • If the on-chain price data has been updated in the last hour, the script will return a success message "Price data is already up to date" message

Implementation

Price Module Validator

The Price Module Validator is written in Plutarch. It runs whenever an Oracle UTxO is being spent.

Price Updater

The Price Update Script is a stand-alone executable that when run will ensure price data is posted on-chain. The code is written in purescript and will depend on the dusd-api and ctl for interacting with the chain. dusd-api should expose functions for updating and reading the price.

When the price updater is ran, it performs the following operations

• It checks if the --config flag is set
  • If it is set
  • Load the config file.
  • Run a Price Update
  • if it isn't set, run Initialization

Initialization

• Submits a transaction performing the following
  • Mints an Oracle NFT
  • Applies the NFT Asset Class and admin public key to the parameterized Price Module Validator to compute the script address.
  • Get the latest price and timestamp, which will come from the price feeder.
  • Creates and submits a UTxO at the price oracle address that contains the following
  • The Oracle NFT
  • Datum with a single member list containing latest price and timestamp

Price Update

• Submits a transaction performing the following:
  • Retrieve Oracle UTxO by the NFT Asset Class loaded from the config.
  • Retrieves Admin public key from config
  • Check if the datum of UTxO has price data from the last hour
  • If so
  • Apply the NFT Asset Class and admin public key to the parameterized Price Module Validator to compute the script and script address.
  • Get the latest price and timestamp, which will come from the price feeder.
  • Creates and submits a UTxO at the price oracle address that contains the following
    • The Oracle NFT
    • Datum with the latest the latest price and timestamp add to a list of prices no larger than 48 elements.
  • If not, return a success message informing the user that the on-chain price data is already up to date.

Price Worker

• The Price Worker is a cron that runs the Price Updater every minute.

[marijanp]

can you add a markdown in the repo, with a PR, so we can make annotations?

[epiro-ps]

@marijanp I broke this up into pieces here. Let me know if it would be easier to comment on if they were also pushed as docs in the repo.