Comment on page
Swap contract Demo
The swap contract is an interactive example, written in Python, that integrates data feed from a Charli3's oracle. The contract support trade operations, liquidity and minting operations.
After the Vasil upgrade, the Charli3 developer team faced the challenge of transitioning from the previous Haskell-based wallet architecture to a new architecture that fully supports Vasil's features. One important aspect of this transition was the creation of an oracle data feed as a reference input for various transactions. To achieve this, the team decided to rewrite a Haskell contract that utilizes reference inputs, leveraging the Pycardano, Python library. This approach enabled them to explore the capabilities of the library and develop a comprehensive tutorial on reading information from Charli3's oracles using contracts.
In this guide, we will demonstrate how to access the oracle feed through reference UTXOs and illustrate the process of creating transactions using Pycardano.
Before we proceed with the code, it's worth noting that while the off-chain portion of smart contracts can be rewritten in different programming languages, the on-chain code can only be written in Haskell (although there are rising alternative available). Keeping that in mind, this guide will focus on explaining the main functions of the smart contract, emphasizing the distinctions between the Haskell and Python implementations of the code.
The swap contract supports four primary operations:
- The Run swap transaction initiates the creation of a UTXO at the contract address, which includes a minted NFT. This NFT serves as an identifier for the UTXO that will hold two assets.
- The Add liquidity transaction allows the user to add specific amounts of tokens to the swap's UTXO. These token quantities must be available in the user's wallet.
- The Swap A transaction facilitates the exchange of asset A from the customers' wallet to the swap's UTXO in return for asset B.
- The Swap B transaction enables the exchange of asset B from the customers' wallet to the swap's UTXO in return for asset A.
The on-chain component of the swap contract validates that when multiplied by the oracle feed, the input tokens from the customers' wallet result in the deterministic addition or removal of assets from the swap contract's UTXO. It also adds or removes tokens from the user's wallet accordingly.
Furthermore, the contract guarantees that the "add liquidity" transaction is always an incremental operation.
Swap's validator
1
{- The validator argument contains information about the assets involved in the trade, the datum represents the unit type, the redeemer specifies the quantity of assets to be exchanged by the user, and the context provides transaction-related information.
2
-}
3
{-# INLINABLE mkSwapValidator #-}
4
mkSwapValidator
5
:: Swap
6
-> ()
7
-> SwapRedeemer
8
-> ScriptContext
9
-> Bool
10
mkSwapValidator Swap{..} _ (SwapA amountA) ctx =
11
mkSwapXValidator checkExchangeA coinB oracle amountA ctx
12
mkSwapValidator Swap{..} _ (SwapB amountB) ctx =
13
mkSwapXValidator checkExchangeB coinA oracle amountB ctx
14
mkSwapValidator swap _ AddLiquidity ctx =
15
mkAddLiqValidator swap ctx
The initial transaction, Run swap, establishes the contract's address and generates a UTXO that includes the minted SWAP NFT, serving as the pool liquidity.
The Pycardano library simplifies the setup of a Cardano development environment by integrating Blockfrost's services. To utilize these services, you need a Blockfrost account and a token ID to interact with the Cardano blockchain.
Environment's settings
1
BLOCKFROST_PROJECT_ID = "BLOCKFROST_API_PROJECT_ID"
2
BLOCKFROST_BASE_URL = "https://cardano-preprod.blockfrost.io/api"
The Start operation creates a unique SWAP NFT at a contract address. Once the SWAP UTXO is generated, it needs to be filled with assets to serve as a liquidity pool. The contract operates with a single UTXO for all transactions.
See below for the token name variable and quantity of tokens to mint.
Token Name
1
asset_name = "SWAP" #Token Name
2
nft_swap = MultiAsset.from_primitive(
3
{
4
policy_id.payload: {
5
bytes(asset_name, "utf-8"): 1, #Amount to mint
6
}
7
}
8
)
We proceed to invoke the mint function to automatically generate the UTXO containing the custom NFT.
Mint class and function
1
swap_utxo_nft = Mint(...) #Mint class (Hidden arguments)
2
swap_utxo_nft.mint_nft_with_script() #Creation of swap UTXO with NFT
Note: The example provided does not require the execution of the Start swap transaction. Its purpose is to showcase how to mint assets using Pycardano. In the actual implementation, this function is executed automatically when a new swap address is created through on-chain code.
The Add liquidity operation transfers a specified amount of the defined assets, USDT and TADA, from the user's wallets to the SWAP UTXO created earlier. This allows the contract to enable trades of assets from the UTXO with any user possessing any of the predetermined assets.
Note: To enhance the code:
- Use separate wallets for adding assets and trading with the swap contract, improving security and separation of concerns.
- Implement additional security measures like multi-signature or threshold signature schemes to ensure authorized participation in adding assets or trading.
Add liquidity class and function
1
swapInstance = SwapContract(...) #Swap contract class (Hidden args)
2
swapInstance.add_liquidity(amountA, amountB, ...) #The user's wallet associated must cover the asset amount expected by the liquidity function.
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.
To begin, you need to provide the following information:
- 1.Oracle contract address and its UTXO feed NFT identifier.
- 2.Swap contract address and its UTXO NFT identifier.
- 3.User's wallet address.
- 4.Details of the assets being traded.
Note that in this example, tADA information is not required as it doesn't contain a policy ID or asset name.
It is assumed that a valid oracle contract already exists on the blockchain, and you can use it for testing purposes. If using a private test-net, you have the option to deploy your own oracle contract.
swap contract's arguments
1
# Charli3's oracle contract address
2
oracle_address = Address.from_primitive(
3
"addr_test1wz58xs5ygmjf9a3p6y3qzmwxp7cyj09zk90rweazvj8vwds4d703u"
4
)
5
6
# Custom contract address (swap contract)
7
swap_address = Address.from_primitive(
8
"addr_test1wqhsrhfqs6xv9g39mraau2jwnaqd7utt9x50d5sfmlz972spwd66j"
9
)
10
11
# Oracle feed nft identity
12
oracle_nft = MultiAsset.from_primitive(
13
{
14
"8fe2ef24b3cc8882f01d9246479ef6c6fc24a6950b222c206907a8be": {
15
b"InlineOracleFeed": 1
16
}
17
}
18
)
19
20
# Swap nft identity
21
swap_nft = MultiAsset.from_primitive(
22
{"ce9d1f8f464e1e930f19ae89ccab3de93d11ee5518eed15d641f6693": {b"SWAP": 1}}
23
)
24
25
# Swap asset information
26
tUSDT = MultiAsset.from_primitive(
27
{"c6f192a236596e2bbaac5900d67e9700dec7c77d9da626c98e0ab2ac": {b"USDT": 1}}
28
)
29
30
#User's wallet addressython
31
user_address = w.user_address()
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.
The oracle feed data follows a standard format created with a Haskell library. Using the library's generic data type, we generate the inline oracle data. Accessing the information is as simple as reading the UTXO that holds this data as a reference UTXO.
The following on-chain Haskell code snippet demonstrates how to read the datum and extract the integer value representing the exchange price. Additionally, in this example we ensure that the oracle feed UTXO is the only input reference UTXO.
On-chain: Oracle feed reading
1
mOracleFeed :: Maybe OracleFeed
2
mOracleFeed =
3
case txInfoReferenceInputs $ scriptContextTxInfo ctx of
4
[txIn] -> case txOutDatum $ txInInfoResolved txIn of
5
NoOutputDatum -> Nothing
6
OutputDatumHash odh ->
7
case findDatum odh (scriptContextTxInfo ctx) of
8
Just dv -> PlutusTx.fromBuiltinData . getDatum $ dv
9
Nothing -> Nothing
10
OutputDatum dv ->
11
PlutusTx.fromBuiltinData . getDatum $ dv
12
[] -> traceError
13
"mkSwapXValidator: Empty reference input list"
14
_ -> traceError
15
"mkSwapXValidator: Only one reference input is allowed"
16
The Pycardano library offers convenient built-in functions for searching and retrieving the oracle feed. By providing the oracle's address, we can search for available UTXOs and locate the one that contains the oracle fee NFT (
OracleFeed). From there, the get_price() function can extract the integer value from the datum list structure.Off-chain: Oracle feed reading
1
def get_oracle_utxo(self) -> pyc.UTxO:
2
"""Get oracle's feed UTXO using NFT idenfier"""
3
oracle_utxos = self.context.utxos(str(self.oracle_addr))
4
oracle_utxo_nft = next((x for x in oracle_utxos if x.output.amount.multi_asset >= self.oracle_nft), None)
5
if oracle_utxo_nft is None:
6
raise ValueError("Oracle UTXO not found with NFT identifier")
7
return oracle_utxo_nft
8
9
def get_oracle_exchange_rate(self) -> int:
10
"""Get the oracle's feed exchange rate"""
11
oracle_feed_utxo = self.get_oracle_utxo()
12
oracle_inline_datum: GenericData = GenericData.from_cbor(
13
oracle_feed_utxo.output.datum.cbor
14
)
15
return oracle_inline_datum.price_data.get_price()
16
Let's take a closer look to the code:
Oracle feed inline datum
1
oracle_inline_datum: GenericData = GenericData.from_cbor(
2
oracle_feed_utxo.output.datum.cbor
3
)
Here's a breakdown of what each part does:
oracle_feed_utxo: This is an object that represents a UTXO of the transaction that contains the oracle feed.oracle_feed_utxo.output: This is a property of theoracle_feed_utxoobject that represents the output of the UTXO. We can access diferente pieces of information like address, amount, datum_hash, datum, script, etc. More information in pycardano's documentation.oracle_feed_utxo.output.datum: This is a property of the output that represents the CBOR-encoded datum associated with the output.oracle_feed_utxo.output.datum.cbor: This is the binary CBOR-encoded datum that is being parsed.GenericData.from_cbor: This is a static method of theGenericDataclass that takes in a CBOR-encoded byte string and returns aGenericDataobject. TheGenericDataobject is a custom data type that is defined in the datum.py file, see the code below.oracle_inline_datum: GenericData: This is a variable declaration that creates a new variable calledoracle_inline_datumof typeGenericData.This process is known as downcasting.= GenericData.from_cbor(oracle_feed_utxo.output.datum.cbor): This sets the value oforacle_inline_datumto the result of calling thefrom_cbormethod of theGenericDataclass with the CBOR-encoded datum as the argument.
In summary, this code extracts the CBOR-encoded datum from the oracle feed UTXO, parses it into a GenericData object using a static method, and assigns the result to the variable
oracle_inline_datum.Swap contract's datum file
1
@dataclass
2
class GenericData(PlutusData):
3
CONSTR_ID = 0
4
price_data: PriceData
5
@dataclass
6
class PriceData(PlutusData):
7
"""represents cip oracle datum PriceMap(Tag +2)"""
8
9
CONSTR_ID = 2
10
price_map: dict
11
12
def get_price(self) -> int:
13
"""get price from price map"""
14
return self.price_map[0]
15
16
def get_timestamp(self) -> int:
17
"""get timestamp of the feed"""
18
return self.price_map[1]
19
20
def get_expiry(self) -> int:
21
"""get expiry of the feed"""
22
return self.price_map[2]
23
24
@classmethod
25
def set_price_map(cls, price: int, timestamp: int, expiry: int):
26
"""set price_map"""
27
price_map = {0: price, 1: timestamp, 2: expiry}
28
return cls(price_map)
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, such as 1,000,000. This enables accurate evaluation of decimal precision when working with integers. For example, if we have 2,400,000 with a coin_precision of 1,000,000, it would be evaluated as 2.4.
SwapB
1
"""Exchange of asset B with A"""
2
amountA = self.swap_b_with_a(amountB)
3
4
def swap_b_with_a(self, amount_b: int) -> int:
5
"""Operation for swaping coin B with A"""
6
exchange_rate_price = self.get_oracle_exchange_rate()
7
return (amount_b * self.coin_precision) // exchange_rate_price
The SwapA transaction is exactly the opposite operation of SwapB
SwapA
1
"""Exchange of asset A with B"""
2
amountB = self.swap_a_with_b(amountA)
3
4
def swap_a_with_b(self, amount_a: int) -> int:
5
"""Operation for swaping coin A with B"""
6
exchange_rate_price = self.get_oracle_exchange_rate()
7
return (amount_a * exchange_rate_price) // self.coin_precision
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.
First, we need to define a class
SwapContract that receives the contract's argumentsSwap Contract Class
1
class SwapContract:
2
"""SwapContact to interact with the swap smart contract
3
4
Attributes:
5
context: Blockfrost class
6
oracle_nft: The NFT identifier of the oracle feed utxo
7
oracle_addr: Address of the oracle contract
8
swap_addr: Address of the swap contract
9
"""
10
11
def __init__(
12
self,
13
context: ChainQuery,
14
oracle_nft: pyc.MultiAsset,
15
oracle_addr: pyc.Address,
16
swap_addr: pyc.Address,
17
swap: Swap,
18
) -> None:
19
self.context = context
20
self.oracle_addr = oracle_addr
21
self.swap_addr = swap_addr
22
self.coin_precision = 1000000
23
self.swap = swap
24
self.oracle_nft = oracle_nft
The swap class stores information about assets. We do not need to add information for the tADA asset as its fields contain empty values.
Swap Class
1
class Swap:
2
"""Class Swap for interact with the assets in the swap operation
3
and identify the Swap's NFTs
4
5
Attribures:
6
swap_nft: The NFT identifier of the swap utxo
7
coinA: Asset
8
"""
9
10
def __init__(
11
self,
12
swap_nft: pyc.MultiAsset,
13
coinA: pyc.MultiAsset,
14
) -> None:
15
self.swap_nft = swap_nft
16
self.coinA = coinA
We then query and process the necessary information to construct the transaction.
Data processing
1
"""Exchange of asset B with A"""
2
oracle_feed_utxo = self.get_oracle_utxo() #Oracle's feed UTXO
3
swap_utxo = self.get_swap_utxo() #Swap's UTXO
4
amountA = self.swap_b_with_a(amountB) #Assets exchange
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 tUSDTSwap UTXO
1
#Query the available amount of assetB (tADA) at the swap address UTXO
2
amountB_at_swap_utxo = swap_utxo.output.amount.coin
3
4
#We multiply the user's asset by the lovelace rate and add it to the UTXO for the swap
5
updated_amountB_for_swap_utxo = amountB_at_swap_utxo + (amountB * 1000000)
6
7
#Additionally, we need to decrease the amount of tUSDT sent to the user's wallet.
8
updated_massetA_for_swap_utxo = self.decrease_asset_swap(amountA)
9
10
#We create a new value type with the updated asset values
11
amount_swap = pyc.transaction.Value(
12
coin=updated_amountB_for_swap_utxo,
13
multi_asset=updated_massetA_for_swap_utxo,
14
)
15
16
#Finally, we add the updated value, unit type and the swap's address to the output UTXO for the swap"
17
new_output_swap = pyc.TransactionOutput(
18
address=swap_address, amount=amount_swap, datum=pyc.PlutusData()
19
)
Fourth, the second UTXO goes to the user's wallet address. This UTXO pays the user the
tUSDT earned from the swap operation.User UTXO
1
#The user asset quantity to be added to the wallet (tUSDT received).
2
multi_asset_for_the_user = self.take_multi_asset_user(amountA)
3
4
#We create a value type with the user asset quantity (without tADA).
5
min_lovelace_amount_for_the_user = pyc.transaction.Value(
6
multi_asset=multi_asset_for_the_user
7
)
8
9
#Next, we creates an output UTXO using the previous value at the user's wallet.
10
min_lovelace_output_utxo_user = pyc.TransactionOutput(
11
address=user_address, amount=min_lovelace_amount_for_the_user
12
)
13
14
#The pycardano utils function min_lovelace_post_alonzo calculate minimum Lovelace to attach to the previous created UTXO.
15
min_lovelace = pyc.utils.min_lovelace_post_alonzo(
16
min_lovelace_output_utxo_user, self.context
17
)
18
19
#Now, we create a value type with the minumum tADA amount.
20
amount_for_the_user = pyc.transaction.Value(
21
coin=min_lovelace, multi_asset=multi_asset_for_the_user
22
)
23
24
#Finally, we add the calculated minimum tADA amount to the previously generated output UTXO on line 4.
25
new_output_utxo_user = pyc.TransactionOutput(
26
address=user_address, amount=amount_for_the_user
27
)
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.
Sign and sumbmission
1
builder = pyc.TransactionBuilder(self.context) #Pyacardano builder
2
(
3
builder.add_script_input(
4
utxo=swap_utxo, script=script, redeemer=swap_redeemer
5
)
6
.add_input_address(user_address) #User's wallet address
7
.add_output(new_output_utxo_user) #UTXO paying to the user
8
.add_output(new_output_swap) #UTXO paying to the swap contract
9
.reference_inputs.add(oracle_feed_utxo.input) #Oracle's reference UTXO
10
)
11
12
self.submit_tx_builder(builder, sk, user_address) #Sign and submission
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. python src/main.py -h
usage: python main.py [-h] {trade,user,swap-contract,oracle-contract} ...
The swap python script is a demonstrative smart contract (Plutus v2) featuring the interaction with a charli3's
oracle. This script uses the inline oracle feed as reference input simulating the exchange rate between tADA and tUSDT
to sell or buy assets from a swap contract in the test environment of preproduction.
positional arguments:
{trade,user,swap-contract,oracle-contract}
trade Call the trade transaction to exchange a user asset with another asset at the swap contract.
Supported assets tADA and tUSDT.
user Obtain information about the wallet of the user who participate in the trade transaction.
swap-contract Obtain information about the SWAP smart contract.
oracle-contract Obtain information about the ORACLE smart contract.
options:
-h, --help show this help message and exit
Copyrigth: (c) 2020 - 2023 Charli3
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 to verify the swap contract liquidity. And for query 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.python main.py oracle-contract --feed
Oracle feed:
* Exchange rate tADA/tUSDt 2.4
* Generated data at: 2022-12-01 14:06:58
* Expiration data at: 2023-12-01 15:06:04
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.mint.py
1
def mint_nft_with_script(self):
2
"""mint tokens with plutus v2 script"""
3
policy_id = plutus_script_hash(self.minting_script_plutus_v2)
4
asset_name = "SWAP" #Token Name
5
nft_swap = MultiAsset.from_primitive(
6
{
7
policy_id.payload: {
8
bytes(asset_name, "utf-8"): 1,
9
}
10
}
11
)
12
metadata = {
13
0: {
14
policy_id.payload.hex(): {
15
"Swap": {
16
"description": "This is a test token",
17
"name": asset_name,
18
}
19
}
20
}
21
}
22
Start swap transaction
1
python main.py swap-contract --start-swap
2
3
Swap's NFT information: #New NFT information
4
Currency Symbol (Policy ID): c6f192a236596e2bbaac5900d67e9700dec7c77d9da626c98e0ab2ac
5
Token Name: SWAP
main.py
1
swap_nft = MultiAsset.from_primitive(
2
{"c6f192a236596e2bbaac5900d67e9700dec7c77d9da626c98e0ab2ac": {b"SWAP": 1}}
3
) #Variable to update with the new NFT information