Intermediate · 30 minutes

Hash Time Lock Contract Template With Python

This tutorial is intended to help you call a Hash Time Locked 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 HTLC Template and show how it can be used with a transaction.

Jason Weathersby Algorand

April 12, 2020

Python

Requirements

Algorand Python SDK
Access to an Algorand node

Background

Algorand provides many templates for Smart Contract implementation in the SDKs. The Hash Time Lock Contract is just one of the templates and is described in the reference documentation. Hash Time Lock Contracts are contract accounts that can disburse funds when the correct hash preimage (“password”) is passed as an argument. If the funds are not claimed with the password after a certain period of time, the original owner can reclaim them.

1. Create Template

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

TMPL_RCV: the address to send funds to when the preimage is supplied
TMPL_HASHFN: the specific hash function (sha256 or keccak256) to use
TMPL_HASHIMG: the image of the hash function for which knowing the preimage under TMPL_HASHFN will release the funds
TMPL_TIMEOUT: the round after which funds may be closed out to TMPL_OWN
TMPL_OWN: the address to refund funds to on timeout
TMPL_FEE: maximum fee of any transactions approved by this contract

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)
# Get suggested parameters from the network
tx_params = client.suggested_params()
# Specify TLHC-related template params.
template_data = {
    "owner": "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM",
    "receiver": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "hash_function": "sha256",
    "hash_image": "QzYhq9JlYbn2QdOMrhyxVlNtNjeyvyJc/I8d8VAGfGc=",
    "expiry_round": 5000000,
    "max_fee": 2000
}
## Inject template data into HTLC template
c = template.HTLC(**template_data)
# Get the address for the escrow account associated with the logic
addr = c.get_address()
print("Escrow Address: {}\n".format(addr))

2. Create the Logic Signature

Before the account can be used, it must be funded. The HTLC address represents the account’s address which we will fund using the dispenser for the purpose of this tutorial.

To use the HTLC contract in a transaction, a Logic Signature must be created. This will be used later to sign the transaction. The Logic Signature is a replacement for signing the transaction with a spending key. If you do not want to pass in parameters yet you can still create an lsig without the args. Later you can create a new lsig with the program and a set of args to be used to sign a transaction. In this example, we are passing the one transaction parameter (password) as we create the Logic Signature. Logic Signatures are further documented on the developer site.

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)
# Get suggested parameters from the network
tx_params = client.suggested_params()
# Specify TLHC-related template params.
template_data = {
    "owner": "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM",
    "receiver": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "hash_function": "sha256",
    "hash_image": "QzYhq9JlYbn2QdOMrhyxVlNtNjeyvyJc/I8d8VAGfGc=",
    "expiry_round": 5000000,
    "max_fee": 2000
}
## Inject template data into HTLC template
c = template.HTLC(**template_data)
# Get the address for the escrow account associated with the logic
addr = c.get_address()
print("Escrow Address: {}\n".format(addr))

# Retrieve the program bytes
program = c.get_program()
# Get the program and parameters and use them to create an lsig
# For the contract account to be used in a transaction
# In this example 'hero wisdom green split loop element vote belt'
# hashed with sha256 will produce our image hash
# This is the passcode for the HTLC 
args = [
    "hero wisdom green split loop element vote belt".encode()
]
# Add the program bytes and args to a LogicSig object 
lsig = transaction.LogicSig(program, args)

Learn More
- Add Funds using Dispenser
- Smart Contracts - Logic Signatures

3. Create and Sign the Transaction

A transaction can now be created that requests the funds from the HTLC Contract account. The amt should be set to 0 as the contract will close out all funds at once. The sender address should be set to the contract’s address. After the transaction is created, it can be signed with the Logic Signature as shown in the highlighted code below. Note that the receiver field is set to the Zero address as the contract automatically closes out to the receiver that was configured in the template creation. If this field is not set to the zero address the transaction will fail.

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)
# Get suggested parameters from the network
tx_params = client.suggested_params()
# Specify TLHC-related template params.
template_data = {
    "owner": "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM",
    "receiver": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "hash_function": "sha256",
    "hash_image": "QzYhq9JlYbn2QdOMrhyxVlNtNjeyvyJc/I8d8VAGfGc=",
    "expiry_round": 5000000,
    "max_fee": 2000
}
## Inject template data into HTLC template
c = template.HTLC(**template_data)
# Get the address for the escrow account associated with the logic
addr = c.get_address()
print("Escrow Address: {}\n".format(addr))

# Retrieve the program bytes
program = c.get_program()
# Get the program and parameters and use them to create an lsig
# For the contract account to be used in a transaction
# In this example 'hero wisdom green split loop element vote belt'
# hashed with sha256 will produce our image hash
# This is the passcode for the HTLC 
args = [
    "hero wisdom green split loop element vote belt".encode()
]
# Add the program bytes and args to a LogicSig object 
lsig = transaction.LogicSig(program, args)

# Before submitting this transaction, you must first make sure the escrow 
# account is sufficiently funded. Once it is funded, create and submit
# transactions from the escrow account like the transaction below.
# Transaction data
tx_data = {
    "sender": addr,
    "receiver": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ",
    "amt": 0,
    "close_remainder_to": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "fee": 1000,
    "flat_fee": True,
    "first": tx_params.get('lastRound'),
    "last": tx_params.get('lastRound') + 1000,
    "gen": tx_params.get('genesisID'),
    "gh": tx_params.get('genesishashb64')
}
# Instantiate a payment transaction type
txn = transaction.PaymentTxn(**tx_data)
# Instantiate a LogicSigTransaction with the payment txn and the logicsig
logicsig_txn = transaction.LogicSigTransaction(txn, lsig)

4. Send the Transaction to the Network

The final step is to send the transaction to the network. If the contract is funded, the transaction should succeed.

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)
# Get suggested parameters from the network
tx_params = client.suggested_params()
# Specify TLHC-related template params.
template_data = {
    "owner": "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM",
    "receiver": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "hash_function": "sha256",
    "hash_image": "QzYhq9JlYbn2QdOMrhyxVlNtNjeyvyJc/I8d8VAGfGc=",
    "expiry_round": 5000000,
    "max_fee": 2000
}
## Inject template data into HTLC template
c = template.HTLC(**template_data)
# Get the address for the escrow account associated with the logic
addr = c.get_address()
print("Escrow Address: {}\n".format(addr))

# Retrieve the program bytes
program = c.get_program()
# Get the program and parameters and use them to create an lsig
# For the contract account to be used in a transaction
# In this example 'hero wisdom green split loop element vote belt'
# hashed with sha256 will produce our image hash
# This is the passcode for the HTLC 
args = [
    "hero wisdom green split loop element vote belt".encode()
]
# Add the program bytes and args to a LogicSig object 
lsig = transaction.LogicSig(program, args)

# Before submitting this transaction, you must first make sure the escrow 
# account is sufficiently funded. Once it is funded, create and submit
# transactions from the escrow account like the transaction below.
# Transaction data
tx_data = {
    "sender": addr,
    "receiver": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ",
    "amt": 0,
    "close_remainder_to": "42NJMHTPFVPXVSDGA6JGKUV6TARV5UZTMPFIREMLXHETRKIVW34QFSDFRE",
    "fee": 1000,
    "flat_fee": True,
    "first": tx_params.get('lastRound'),
    "last": tx_params.get('lastRound') + 1000,
    "gen": tx_params.get('genesisID'),
    "gh": tx_params.get('genesishashb64')
}
# Instantiate a payment transaction type
txn = transaction.PaymentTxn(**tx_data)
# Instantiate a LogicSigTransaction with the payment txn and the logicsig
logicsig_txn = transaction.LogicSigTransaction(txn, lsig)

# Send the transaction to the network.
txid = client.send_transaction(logicsig_txn, headers={'content-type': 'application/x-binary'})
print("Transaction ID: {}".format(txid))

Create Publication