Split Contract Template with Python
This tutorial is intended to help you call a Split 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 Split Template and show how it can be used with a transaction.
Python
Requirements
- Algorand Python SDK
- Access to an Algorand node
Background
Algorand provides many templates for Smart Contract implementation in the SDKs. The Split Contract is just one of the templates and is described in the reference documentation. Split Contracts are contract accounts that can disburse funds to two accounts at 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.
Steps
1. Assign the Contract Receiver Accounts
The Split template can be instantiated with a set of predefined parameters that configure the Split contract. These parameters should not be confused with Transaction parameters that are passed into the contract when using the Split. These parameters configure how the Split will function:
TMPL_RCV1: the first recipient of the fundsTMPL_RCV2: the second recipient of the fundsTMPL_RAT1: for each TMPL_RAT2 microAlgos received by TMPL_RCV2, TMPL_RAT1 specifies how many are received by TMPL_RCV1TMPL_RAT2: for each TMPL_RAT1 microAlgos received by TMPL_RCV1, TMPL_RAT2 specifies how many are received by TMPL_RCV2TMPL_MINPAY: the minimum number of microAlgos that must be received by TMPL_RCV1 for a split withdrawal to succeedTMPL_TIMEOUT: the round after which funds may be closed back to TMPL_OWNTMPL_OWN: the address that funds may be closed to after TMPL_TIMEOUTTMPL_FEE: the maximum fee that may be used by any individual transaction approved by this contract
So for example, if you want funds to be split such that for every 10 microAlgos, 3 will go to receiver 1 and 7 will go to receiver 2, TMPL_RAT1 will be set to 3 and TMPL_RAT2 will be set to 7. If the amount of a transaction can not be split with the desired ratio, the transactions will fail. The TMPL_MINPAY parameter must also be met for the transaction to succeed. So in this example, if TMPL_MINPAY was set to 3000, then the total transaction could be no less than 10000 microAlgos.
For this tutorial, we first need to define, the owner of the contract, and the two receivers.
from algosdk import algod, 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 = "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
receiver_1 = "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
receiver_2 = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
2. Create Split Template
The Split template can now be instantiated with specific parameters.
from algosdk import algod, 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 = "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
receiver_1 = "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
receiver_2 = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
ratn = 3
ratd = 7
expiry_round = 5000000
min_pay = 3000
max_fee = 2000
## Inject template data into Split template
split = template.Split(owner, receiver_1, receiver_2, ratn, ratd, expiry_round, min_pay, 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 = split.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 = split.get_program()
At this point, the split 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 split contract template offers a helper method to create the proper transactions against the contract called get_split_funds_transaction. This function takes an amount for the total transaction, creates two transactions (one for each receiver) and then groups these two transactions into an atomic transfer. These transactions are signed with the program logic and the function returns the resulting bytes to submit. These bytes can then be submitted to the blockchain.
from algosdk import algod, 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 = "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
receiver_1 = "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
receiver_2 = "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
ratn = 3
ratd = 7
expiry_round = 5000000
min_pay = 3000
max_fee = 2000
## Inject template data into Split template
split = template.Split(owner, receiver_1, receiver_2, ratn, ratd, expiry_round, min_pay, 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 = split.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 = split.get_program()
# Create the grouped transactions against
# the Split contract
amt = 1000000
# Get suggested parameters from the network
tx_params = client.suggested_params()
# contract, amount: int, fee: int, first_valid, last_valid, gh
txns = split.get_split_funds_transaction(program, amt, 1, tx_params.get('lastRound'), tx_params.get('lastRound') + 1000, tx_params.get('genesishashb64'))
txn = txns[0].transaction
txid = client.send_transactions(txns)
print("Transaction ID: {}".format(txid))
Learn More
- Atomic Transfers