Algo Builder docs

For more in-depth description you can look at the project specification.

Setup

Requirements

  • Node 12+
  • Connection to an Algorand node. Follow our infrastructure README for instructions how to setup a private network (using Algorand node binaries or docker based setup). NOTE: TEAL compilation requires Developer API to be enabled ("EnableDeveloperAPI": true in the node config.json).
  • Python 3.7+ (for PyTeal) with pyteal. Please read below how to install it.
  • Yarn v1.22+ or NPM v6.0+

Installation

To install algob globally in your system you can use:

  • Using Yarn: yarn global add @algo-builder/algob
  • Using NPM: npm install -g @algo-builder/algob

Installation from source:

git clone https://github.com/scale-it/algo-builder.git
cd algo-builder
yarn install
yarn build
cd packages/algob
yarn link

Setting up the system $PATH

Make sure your yarn global bin (or npm bin -g if you are using NPM) directory is in your $PATH (instructions for Linux and MacOS, instructions1 and instructions2 for Windows).

Upgrading

If you use installation from source (master), don’t forget to pull the latest changes to not to miss the updates:

cd path/to/algo-builder
git pull -p
yarn install
yarn build

Algorand Node requirements

  • algod v2.1.6-stable or higher

Make sure that the node you are connecting to has a "EnableDeveloperAPI": true option set in the <node_data>/config.json. This is required to compile smart contracts using REST / SDK.

PyTeal

algob supports TEAL smart contracts written in PyTeal. To use them, you have to have pyteal package available in your Python context:

Using Pipenv

We recommend to use pipenv and use virtual environments. Pipenv is a packaging tool for Python that solves some common problems associated with the typical workflow using pip, virtualenv, and the good old requirements.txt. In addition to addressing some common issues, it consolidates and simplifies the development process to a single command line tool. It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your Pipfile as you install/uninstall packages.

With pipenv installed you can use the Pipfile and Pipfile.lock files from this repository and copy it to your project. Then:

pipenv sync
pipenv shell

The pipenv shell will spawn a shell within the virtualenv with all required packages available in Python3 context. You will need to run algob within that python virtualenv context.

Using pip3

Otherwise you can use a system/user-wide pyteal installation:

pip3 install pyteal

Help

Help prints information about top-level tasks:

algob help

Help with additional arguments prints information about a specific task:

algob help deploy

or

algob -h deploy

Project initialization

To start using algob you must first create a project similar to what yarn and npm would do. It can be done using this command:

algob init my-project

This will create a directory my-project and put multiple files into it.

In the my-project folder you’ll have following items:

  • assets/: Directory for assets and contracts files
  • scripts/: Directory for scripts to deploy and run your assets and contracts
  • tests/: Directory for test files for testing your assets and contracts
  • algob.config.js: Algob configuration file

A sample-project is provided for your reference.

Further information about the sample-project can be found here

NOTE: a) You can put smart contracts directly in /assets directory as well as in /assets subdirectory. For example, you can store your PyTEAL files in assets/pyteal/<file.py>. b) By default algobpy package (a helper package to pass compilation parameters to PyTEAL programs) is stored in /assets/algobpy folder. algob is looking for all .py and .teal files when loading smart contracts, except files stored in /assets/algobpy. You can use the /assets/algobpy directory to store custom Python modules and conflicts when loading TEAL smart contracts. Read more about usage of algobpy here.

Checkpoints

algob uses local file system files to version its state. These files are called checkpoints and they save information about deployed assets/contracts. As they are checked-in into Version Control System you can use them to track the deployed state of your assets.

Read more about checkpoints here.

Typescript Projects

Typescript project requires a transpilation to js files. So that algob can execute js files. To develop in typescript, please remember these points:

  • Make sure to compile your ts project using yarn build (which runs tsc --build .) Never forget to compile files.
  • TIP: If you are actively developing, please use yarn build:watch(tsc -w -p .) to build or compile your .ts files in real time (this is recommended).
  • Transpiled js files should be present in build folder, therefore outDir in tsconfig.json should be set as:

    “outDir”: “./build/scripts”

  • Typescript example htlc-pyteal-ts. This example project shows how to build with typescript in algob.