An Algorand smart contract example using Beaker

This repository serves as an example to beginners. It contains an example of a working smart contract and its testing.

The example has been developed starting from AlgoBet, a very basic proposal of decentralized bet system powered by Algorand that was born during the 2022 edition of International School on Algorand Smart Contracts.

What you can see this repository

• Smart contract implemented using Beaker framework: src/contract.py.

• An example of parent-child architecture implemented using Beaker Precompile: src/parent.py is a parent contract, which can be used to spawn src/contract.py child contracts, using the approach described in algorand-devrel/parent-child-contracts.

• Examples of testing time-based transactions with sandbox in dev mode, overcoming the issues introduced by the sandbox explained here.

• An example of automated CI workflow (based on GitHub Actions) which compiles the smart contracts into TEAL code and runs tests: .github/workflows/tests.yml.

How to: deploy the smart contract and run a demo

Environment setup

A Python 3 installation and Algorand sandbox are required to run the demo or tests.

Clone the repository and its submodules, prepare a virtual environment and install the project requirements with:

git clone --recurse-submodules https://github.com/n-elia/algorand-beaker-example.git

python3 -m venv venv
source venv/bin/activate 

pip install -r src/requirements.txt
pip install -r src/test/requirements.txt

Run a Demo

To run a demo of this smart contract, a sandbox (note: it requires you a working docker-compose installation) must be up and running. To use the sandbox included in this repository:

cd src/test/sandbox
./sandbox up

# After sandbox loading, run the demo
python src/contract.py

The demo() method inside src/contract.py will be executed.

Run the demo using the testnet

The tests can be run deploying the sandbox and attaching it to the testnet:

cd src/test/sandbox
./sandbox up testnet

From sandbox folder, create a wallet and populate it with two accounts:

cd src/test/sandbox
./sandbox enter algod
goal wallet new mywallet
goal account new -w mywallet
goal account new -w mywallet

Note: keep track of wallet name and password for next steps!

Then, fund those accounts using the testnet bank faucet.

To make beaker.sandbox client able to access your wallet, create a src/.env file as follows:

cd src
touch .env

And paste this content:

TEST_SANDBOX_CONFIG=testnet
TEST_SANDBOX_WALLET_NAME=mywallet
TEST_SANDBOX_WALLET_PASS=mywalletpassword

Then, you will be able to run the demo script as explained in the previous subsection.

How to: run tests over the smart contract

Make GitHub run the tests for you

An automated GitHub Actions workflow is stored into .github/workflows/tests.yml. It contains two jobs, which will be run in parallel.
Both of them will:

• set up an Ubuntu 22.04 environment
• clone this repository and the sandbox submodule
• install Python 3.10 and this project's dependencies
• set up and run the sandbox

Then, one will compile the smart contracts into TEAL code, while the other one will execute the tests using the Makefile in repository root.

Both the jobs will upload some artifacts. The former will upload the TEAL code, while the latter will upload the test report. Artifacts are stored for 90 days.

The workflow is executed on each push or pull request. However, you can request an execution manually, by going into the "Actions" tab, selecting "Smart contract tests" and clicking on "Run workflow". Then, you can monitor the execution and, at the end of the run, download the artifacts.

Run tests using sandbox in dev configuration

Tests are implemented using the pytest test framework for Python. To run tests, the sandbox in devmode must be up and running. Therefore, we provided the test suite with the possibility to set up and teardown the sandbox network during each test session.

This repository contains sandbox as a submodule, and the provided scripts point to it. Therefore, you can choose between:

• setting up the src/test/sandbox-scripts/sandbox_setup.sh and src/test/sandbox-scripts/sandbox_teardown.sh shell scripts to point to your own sandbox directory.

• download sandbox submodule (note: it requires you a working docker-compose installation):

  # After moving in repo root directory
  git submodule init
  git submodule update

Then, you can enable automatic execution of those scripts at each run by using the --sandbox parameter on the pytest CLI.

To run the test suite with default settings, just issue:

# After moving in repo root directory
make test

The report will be located at src/test/reports/pytest_report.html. You can find a sample report there.

Run tests using sandbox to connect to devnet

To run tests deploying the contract on devnet, you have to implement the snippet shown in "Run the demo using the testnet" section into test_contract.py/TestBase.accounts(). Be sure to create enough accounts before running the tests.

Compile to TEAL

Beaker framework can also be used for exporting TEAL code of the developed application. The script src/teal/compile.py can be run to generate the Approval Program, Clear Program and transactions json:

python src/teal/compile.py