Intermediate · 15 minutes or less

Split Contract Template with Go

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.

Jason Weathersby Algorand

April 11, 2020

Golang

Requirements

Algorand Go 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 with 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
2. Create Split Template
3. Create and Submit Transaction against Contract

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 funds
TMPL_RCV2: the second recipient of the funds
TMPL_RAT1: for each TMPL_RAT2 microAlgos received by TMPL_RCV2, TMPL_RAT1 specifies how many are received by TMPL_RCV1
TMPL_RAT2: for each TMPL_RAT1 microAlgos received by TMPL_RCV1, TMPL_RAT2 specifies how many are received by TMPL_RCV2
TMPL_MINPAY: the minimum number of microAlgos that must be received by TMPL_RCV1 for a split withdrawal to succeed
TMPL_TIMEOUT: the round after which funds may be closed back to TMPL_OWN
TMPL_OWN: the address that funds may be closed to after TMPL_TIMEOUT
TMPL_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 can be no less than 10000 microAlgos.
For this tutorial, we first need to define, the owner of the contract, and the two receivers.

package main

import (
    "fmt"

    "github.com/algorand/go-algorand-sdk/client/algod"
    "github.com/algorand/go-algorand-sdk/templates"

)
// This example creates a contract account
func main() {
    // CHANGE ME
    const algodAddress = "http://<your-algod-host>:<your-algo-port>"
    const algodToken = "<your-api-token>"

    // Create an algod client
    algodClient, err := algod.MakeClient(algodAddress, algodToken)
    if err != nil {
        fmt.Printf("failed to make algod client: %s\n", err)
        return
    }
    // Inputs 
    owner := "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
    receiver1 := "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
    receiver2 := "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
}

2. Create Split Template

The Split template can now be instantiated with specific parameters.

package main

import (
    "fmt"

    "github.com/algorand/go-algorand-sdk/client/algod"
    "github.com/algorand/go-algorand-sdk/templates"

)
// This example creates a contract account
func main() {
    // CHANGE ME
    const algodAddress = "http://<your-algod-host>:<your-algo-port>"
    const algodToken = "<your-api-token>"

    // Create an algod client
    algodClient, err := algod.MakeClient(algodAddress, algodToken)
    if err != nil {
        fmt.Printf("failed to make algod client: %s\n", err)
        return
    }
    // Inputs 
    owner := "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
    receiver1 := "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
    receiver2 := "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
    ratn := 3
    ratd := 7
    expiryRound := uint64(5000000)
    maxFee := uint64(2000)
    minPay := 3000
    //Instaniate the Template
    split, err := templates.MakeSplit(owner, receiver1, receiver2, uint64(ratn), uint64(ratd), expiryRound, uint64(minPay), maxFee)
    if err != nil {
        fmt.Printf("Creating Contract Failed with %v\n", err)
    }
    // At this point the contract address can be funded
    // The program bytes can also be saved off 
    // to be used at a later time or in a
    // different application
    program := split.GetProgram()
    addr := split.GetAddress() 
    fmt.Printf("Escrow Address: %s\n" , addr )  
}

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 GetSplitFundsTransaction. 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.

package main

import (
    "fmt"

    "github.com/algorand/go-algorand-sdk/client/algod"
    "github.com/algorand/go-algorand-sdk/templates"

)
// This example creates a contract account
func main() {
    // CHANGE ME
    const algodAddress = "http://<your-algod-host>:<your-algo-port>"
    const algodToken = "<your-api-token>"

    // Create an algod client
    algodClient, err := algod.MakeClient(algodAddress, algodToken)
    if err != nil {
        fmt.Printf("failed to make algod client: %s\n", err)
        return
    }
    // Inputs 
    owner := "726KBOYUJJNE5J5UHCSGQGWIBZWKCBN4WYD7YVSTEXEVNFPWUIJ7TAEOPM"
    receiver1 := "THQHGD4HEESOPSJJYYF34MWKOI57HXBX4XR63EPBKCWPOJG5KUPDJ7QJCM"
    receiver2 := "AJNNFQN7DSR7QEY766V7JDG35OPM53ZSNF7CU264AWOOUGSZBMLMSKCRIU"
    ratn := 3
    ratd := 7
    expiryRound := uint64(5000000)
    maxFee := uint64(2000)
    minPay := 3000
    //Instaniate the Template
    split, err := templates.MakeSplit(owner, receiver1, receiver2, uint64(ratn), uint64(ratd), expiryRound, uint64(minPay), maxFee)
    if err != nil {
        fmt.Printf("Creating Contract Failed with %v\n", err)
    }
    // At this point the contract address can be funded
    // The program bytes can also be saved off 
    // to be used at a later time or in a
    // different application
    program := split.GetProgram()
    addr := split.GetAddress() 
    fmt.Printf("Escrow Address: %s\n" , addr )

    // Create a set of grouped transactions against
    // the split contract
    sp, err := algodClient.BuildSuggestedParams()
    if err != nil {
        fmt.Printf("Failed to Build Suggested Parameters with %v\n", err)
    }
    amount := 100000
    txnBytes, err := templates.GetSplitFundsTransaction(program, uint64(amount), sp)
    if err != nil {
        fmt.Printf("Creating Transactions Failed with %v\n", err)
    }
    txIDResponse, err := algodClient.SendRawTransaction(txnBytes)
    if err != nil {
        fmt.Printf("Sending failed with %v\n", err)
    }
    fmt.Printf("Transaction: %v\n", txIDResponse.TxID)  
}

Learn More
- Atomic Transfers