Tutorials
No Results
Tutorial Image

Intermediate · 30 minutes

LimitOrder Contract with Python

This tutorial is intended to help you call a Limit Order Contract using Python. Templates are prebuilt TEAL programs that allow parameters to be injected into them from the SDKs that configure the contract. In this example, we are going to instantiate the LimitOrder Template and show how it can be used with a transaction.

Requirements

Background

Algorand provides many templates for Smart Contract implementation in the SDKs. The LimitOrder Contract is just one of the templates and is described in the reference documentation. Limit Order Contracts are contract accounts that can disburse Algos for Algorand Assets in a defined ratio. Additionally, a minimum withdrawal amount can be set. If the funds are not claimed after a certain period of time, the original owner can reclaim the remaining funds.

1. Get Asset Owner and the Contract Owner Accounts

The Limit Order template can be instantiated with a set of predefined parameters that configure the Limit Order contract. These parameters should not be confused with Transaction parameters that are passed into the contract when using the Limit Order. These parameters configure how the Limit Order will function:

  • TMPL_ASSET: Integer ID of the asset
  • TMPL_SWAPN: Numerator of the exchange rate (TMPL_SWAPN assets per TMPL_SWAPD microAlgos, or better)
  • TMPL_SWAPD: Denominator of the exchange rate (TMPL_SWAPN assets per TMPL_SWAPD microAlgos, or better)
  • TMPL_TIMEOUT: The round after which all of the algos in this contract may be closed back to TMPL_OWN
  • TMPL_OWN: The recipient of the asset (if the order is filled), or of the contract’s algo balance (after TMPL_TIMEOUT)
  • TMPL_FEE: The maximum fee used in any transaction spending out of this contract
  • TMPL_MINTRD: The minimum number of microAlgos that may be spent out of this contract as part of a trade

So for example, If you want to specify that the contact will approve a transaction where it is willing to spend 3000 microAlgos for 1 Asset with id of TMPL_ASSET, you would set the TMPL_SWAPN parameter to 1 and the TMPL_SWAPD to 3000. The TMPL_MINTRD should be set to 2999 in this example as it must be less than the amount of microAlgos for the one asset.

For this tutorial, we first need to define, the owner of the contract, and the owner of the asset with asset id = TMPL_ASSET.

from algosdk import algod, mnemonic, transaction, template
# Create an algod client
algod_token = "<your-api-token>"
algod_address = "http://<your-algod-host>:<your-algod-port>"
client = algod.AlgodClient(algod_token, algod_address)

owner = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
asset_owner_mn = (
    "portion never forward pill lunch organ biology"
    " weird catch curve isolate plug innocent skin grunt"
    " bounce clown mercy hole eagle soul chunk type absorb trim")
asset_owner_sk = mnemonic.to_private_key(asset_owner_mn)

2. Create Limit Order Template

The template can now be created with the correct ratio for assets to microAlgos.

from algosdk import algod, mnemonic, transaction, template
# Create an algod client
algod_token = "<your-api-token>"
algod_address = "http://<your-algod-host>:<your-algod-port>"
client = algod.AlgodClient(algod_token, algod_address)

owner = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
asset_owner_mn = (
    "portion never forward pill lunch organ biology"
    " weird catch curve isolate plug innocent skin grunt"
    " bounce clown mercy hole eagle soul chunk type absorb trim")
asset_owner_sk = mnemonic.to_private_key(asset_owner_mn)

ratn = 1
ratd = 3000
expiry_round = 5000000
min_trade = 2999 
max_fee = 2000
assetID = 316084

## Inject template data into LimitOrder template
limit = template.LimitOrder(owner, assetID, ratn, ratd, expiry_round, min_trade, max_fee)
# Get the address for the escrow account associated with the logic
# This account needs to be funded before calling a transaction
# against it
addr = limit.get_address()
print("Escrow Address: {}\n".format(addr))
# Retrieve the program bytes
# The program bytes can be saved at this point
# to be used at a later time or
# in a different application
program = limit.get_program()

At this point, the Limit Order contract account must be funded before any transactions can be issued against it. Use the dispenser to do this now. Also, note that program bytes can be saved to use at a later time or in another application at this point.


Learn More
- Add Funds using Dispenser
- Smart Contracts - Contract Accounts

3. Create and Submit Transaction against Contract

The Limit Order contract template offers a helper method to create the proper transactions against the contract called get_swap_assets_transactions. This function takes an asset_amount and a micro_algo_amount for the total transaction and creates two transactions, one for each receiver and then groups these two transactions into an atomic transfer. The first transaction is signed with the program logic and the second transaction is signed with the secret key of the asset owner. The bytes of the grouped transactions to submit are returned. These bytes can then be submitted to the blockchain.

from algosdk import algod, mnemonic, transaction, template
# Create an algod client
algod_token = "<your-api-token>"
algod_address = "http://<your-algod-host>:<your-algod-port>"
client = algod.AlgodClient(algod_token, algod_address)

owner = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
asset_owner_mn = (
    "portion never forward pill lunch organ biology"
    " weird catch curve isolate plug innocent skin grunt"
    " bounce clown mercy hole eagle soul chunk type absorb trim")
asset_owner_sk = mnemonic.to_private_key(asset_owner_mn)

ratn = 1
ratd = 3000
expiry_round = 5000000
min_trade = 2999 
max_fee = 2000
assetID = 316084

## Inject template data into LimitOrder template
limit = template.LimitOrder(owner, assetID, ratn, ratd, expiry_round, min_trade, max_fee)
# Get the address for the escrow account associated with the logic
# This account needs to be funded before calling a transaction
# against it
addr = limit.get_address()
print("Escrow Address: {}\n".format(addr))
# Retrieve the program bytes
# The program bytes can be saved at this point
# to be used at a later time or
# in a different application
program = limit.get_program()

# Create the grouped transactions against 
# the Limt contract
# asset_amount
asset_amount = 1
micro_algo_amount = 3000
# Get suggested parameters from the network
tx_params = client.suggested_params()
# set fee to 0 to get minimum fee
fee = 0
# contract, amount: int, fee: int, first_valid, last_valid, gh
txns = limit.get_swap_assets_transactions(program, asset_amount, 
                                          micro_algo_amount, asset_owner_sk, 
                                          tx_params.get('lastRound'), 
                                          tx_params.get('lastRound') + 1000, 
                                          tx_params.get('genesishashb64'), fee)
txn = txns[0].transaction
txid = client.send_transactions(txns)
print("Transaction ID: {}".format(txid))


Learn More
- Atomic Transfers

teal

contract

limit order

April 12, 2020