Charli3 Technical Documentation- Swap Contract: part 2

Charli3
6 min readMar 1, 2023

--

Swap Contract- Part 1: https://oraclecharli3.medium.com/charli3-technical-documentation-swap-contract-part-1-21866ed1e780

In Part 2 of the Swap Contract we take a deeper look at reading the oracle feed, the parameters behind a swap, and the libraries/tools used to do so. This document is a bit longer, but full of great information. If you find yourself with questions, please feel open to bringing them to our social media channels and speaking with the team.

Swap Use

Now, we will delve into the implementation of the “swap A” and “swap B” transactions within the Python code. It is assumed that the creation and filling of liquidity for the swap UTXO have already been accomplished.

Contract’s arguments

To begin, we need to specify::

  • the address of the oracle contract and its UTXO feed NFT identifier
  • the address of the swap contract and its UTXO NFT identifier
  • the address of the user’s wallet, and the details of the assets being traded.

As in this example, we don’t need to provide tADA information as it does not contain a policy ID or asset name. It is assumed that a valid oracle contract already exists on the blockchain and you are able to use that one, or that you can deploy your own for testing purposes if using a private testnet.

Copyright: © Charli3, 2021–2023
Copyright: © Charli3, 2021–2023

The Pycardano library supports mnemonic wallets. In this example, we utilize a 24-word Shelley-compatible wallet to sign transactions by restoring an existing wallet via the wallet recovery phase.

Reading an oracle feed

The oracle feed data is specified in a standard format (CIP), created using a dedicated Haskell library. We use the library’s generic data type to create the inline oracle data. Anyone can access the information by reading the UTXO containing this data as a reference UTXO.

Copyright: © Charli3, 2021–2023

The Haskell code snippet reads the datum and retrieves the integer value which serves as the exchange price. It is worth noting that the on-chain code verifies that the oracle feed UTXO is the sole input reference UTXO.

The python library has built-in functions that simplify the search and retrieval of the data feed. We only need to provide the oracle’s address to search for available UTXOs, then search for the UTXO that holds the oracle fee NFT. Finally, the get_price() function will retrieve the integer value from the datum list structure.

Copyright: © Charli3, 2021–2023

SwapB transaction (tADA for tUSDT)

The swapB transaction exchanges a specified amount of tADA for tUSD at the exchange rate provided by an oracle. To handle decimal precision, a variable called coin precision is used, which is set as a multiple of 1, for example 1,000,000. This allows for evaluating the exact decimal precision when working with integers, for example 2400000 with a coin precision of 1000000 is evaluated as 2.4.

Copyright: © Charli3, 2021–2023

SwapA transaction (tUSDT for tADA)

The SwapB transaction is exactly the opposite operation of SwapA

Copyright: © Charli3, 2021–2023

Transaction submission of a swap operation

We will provide detailed instructions on how to submit a swapB transaction, which is similar to the process for submitting a swapA transaction. Before continuing, we recommend reviewing the Pycardano documentation on transactions.

  • 1st: we need to define a class SwapContract that receives the contract's arguments
Copyright: © Charli3, 2021–2023
Copyright: © Charli3, 2021–2023

The swap class stores information about assets. We do not need to add information for the tADA asset as its fields contain empty values.

Copyright: © Charli3, 2021–2023
  • 2nd: We then query and process the necessary information to construct the transaction.
Copyright: © Charli3, 2021–2023
  • 3rd : We create two UTXOs using the processed information. The first UTXO goes to the swap address, it contains the amount of tADAspecified by the user, and a decreased quantity of tUSDT
Copyright: © Charli3, 2021–2023
  • 4th , the second UTXO goes to the user’s wallet address. This UTXO pays the user the tUSDT earned from the swap operation.
Copyright: © Charli3, 2021–2023
Copyright: © Charli3, 2021–2023

Finally, we gather the information from the previous steps in the Pycardano builder, in this way we construct the swapB transaction. Finally, we sign and send it to the blockchain

Copyright: © Charli3, 2021–2023

Command line interface

The python swap contract has a command line interface to easily submit transactions. To access it, first, navigate to the src directory. Then, run the command python main.py -h to display helpful information on how to use the command line options. This command line interface is built using the Argparse python library.

Copyright: © Charli3, 2021–2023

The command line interface supports four different commands, each with its own options.

For example:

  • you can change tADA asset for tUSDT using the command: python main.py trade tADA --amount N.
  • Another useful command is python main.py swap-contract --liquidity which allows verification of the swap contract liquidity
  • And for querying the contract's address python main.py swap-contract --address.

Additionally, you can also retrieve information from the oracle feed by using the command python main.py oracle-contract --feed.

Copyright: © Charli3, 2021–2023

When executing the start swap function, it’s important to remember to replace the token variable ‘asset_name' in the 'mint.py' file. Keep in mind that each NFT must be unique for each new UTXO, and the policy id cannot be changed via python code. After the execution, update the values at the 'swap_nft' variable in the 'main.py' file.

Copyright: © Charli3, 2021–2023
Copyright: © Charli3, 2021–2023

We are happy to present this Charli3 technical documentation and will continue to bring the public more information about the inner workings of our Oracle, helping to educate on the building blocks of DeFi.

--

--