Algo Builder

The Algo Builder project is composed from the following packages:

• algob: framework to automate development of Algorand Assets and Smart Contracts.
• types/algosdk: TypeScript typings for algosdk-js.
• runtime: light algorand runtime and TEAL interpreter.

Objectives

Algo Builder is an trustworthy framework for Algorand dapps (Decentralized Applications). Its main goal is to make shipping Algorand applications simple, efficient, and scalable. Think about it as a Truffle suite for Algorand. The framework provides following functionality through the algob tool:

• REPL (console Read-Eval-Print-Loop) to quickly and easily interact with Algorand Standard Assets and Smart Contracts
• integrated testing framework,
• helpful boilerplates allowing developers to focus on use-cases rather than code organization, examples
• algorand private net
• templates/examples and guides to easily onboard developers

To attract more web developers we plan to build a JavaScript DSL for TEAL with TypeScript bindings (for TEAL inputs). Furthermore we would like to collaborate with SDKs teams to improve the overall development experience and make it ready for enterprise projects. Finally we want to collaborate with Algorand Wallet team to ensure a smooth wallet integration.

Documentation

• Landing Page
• User Guide
• API docs
• Runtime API docs

Templates

• Smart Contracts
• dapps (webapps integrated with smart contracts)

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

Pre requirements

Make sure your yarn global bin directory is in your `$PATH**.

Installation from master

We recommend installation from GitHub master branch if you want to play with templates and examples (all our example smart contracts are tested against master). The master branch corresponds to the latest released version.

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

Upgrading

If you use installation from 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

Installation from released version

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

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

Usage

Quick start

Create a blockchain

• Use Private Net Quick Start.
• Or install a node with any other network.
• Remember to set "EnableDeveloperAPI": true in the node config.json

Create an algob project

1. Create a new yarn/npm project:

    mkdir my_new_project
    cd my_new_project
    yarn init
   

2. Install algob in the project (unless you already installed it globally) and initialize the workspace.

    yarn add @algo-builder/algob
    yarn run algob init .
   

   The init command expects a directory where to initialize the workspace and creates sample project files there. Refer to /docs/guide/README for more information.

3. Verify if it was installed correctly:

    yarn run algob help
   

4. Update the algob.config.js file. Make sure you have access to a running Algorand node (algod). Check Algorand instructions how to install and run it.

   • set correct host address, port and token (if you are using the private-net, then check algod.net and algob.token files in node_data/PrimaryNode/)
   • Note: If you are using private-net from infrastructure, you don't need to update the network config because they are already configured.
   • you can define multiple networks.
   • update the account list (sample project uses a sample account which doesn't have any ALGO, for transaction executions you need to have an active account with ALGOs). See the comments in algob.config.js for more information.
   • Note: If you follow infrastructure instructions, you don't need to do this step as well because command will fund the master account.

5. Add assets and smart-contracts in the assets directory.

6. Add deployment scripts in scripts directory.

7. Run yarn run algob deploy to compile and deploy everything.

8. Run yarn run algob run scriptPath/scriptName to run script.

9. To run algob on different network (by default the default network is used) use

    yarn run algob --network <other_network_name>  <command>
   

Examples

Our /examples directory provides few projects with smart contracts and ASA. Check the list.

• Please start with reading Algorand reference documentation about smart contract.
• Don't forget to study Algorand smart contract guidelines.
• Go to the examples/ref-templates to see how the reference templates are implemented.
• Then go to examples/asa to learn how you can easily manage and deploy ASA with algob.
• Check other examples as well.

Using algob with a TypeScript project

You can use algob within a TS project. You can write your scripts and tests in TS. However to use them with algob you firstly need to compile the project to JS.

TIP: Use tsc --watch to update the build in a realtime while you develop the project

TODO: we are planning to provide a template for TS projects. task.

dApp Templates

In the Algo Builder dApp Templates repository, several templates can be found to use as a base for implementing dApps.

Using the algob unbox-template command, the developers can get a pre-built dApp project containing scripts to deploy assets and smart contracts with react.js interactive frontend. The templates use AlgoSigner to securely sign and send transactions to an Algorand Blockchain Network.

Detailed description about the templates can be found here.

Contributing

Development

The project development is open and you can observer a progress through Pivotal tracker board.

Branch policy

• The active branch is develop - all ongoing work is merged into the develop branch.
• master is the release branch - develop is merged into master during the release.
• Hot fixes are cherry picked to master.

Working with monorepo

We use yarn workspaces to manage all sub packages. here is a list of commands which are helpful in a development workflow

• yarn workspaces info
• yarn workspaces list
• yarn workspaces <package-name> <command>, eg: yarn workspaces mypkg1 run build or yarn workspaces mypkg1 run add --dev react
• yarn add algosdk -- will add algosdk to all sub projects (workspaces)

yarn does not add dependencies to node_modules directories in either of your packages  –  only at the root level, i.e., yarn hoists all dependencies to the root level. yarn leverages symlinks to point to the different packages. Thereby, yarn includes the dependencies only once in the project.

You have to utilize yarn workspaces’ noHoist feature to use otherwise incompatible 3rd party dependencies working in the Mono-Repo environment.

Testing

Each package has rich test suites. Whenever you add something new make sure you provide a test.

Restarting tests by hand is a bit more time consuming. We are using mocha framework to execute tests. It has a very useful feature: mocha --watch -- which will monitor for all file changes and re-execute tests when a file changed without adding a time overhead to start node and load all TypeScript modules.

To execute tests in a workspace (eg packages/runtime) run:

cd packages/runtime
yarn run test

To execute and watch tests in a workspace (eg packages/runtime) run:

cd packages/runtime
yarn run test -w

To execute tests in all workspaces, run the following from the root directory:

yarn run test

To execute and watch tests in all workspaces, run the following from the root directory. Note: it will spawn multiple processes in the same terminal session. So if you want to stop the all processes you can either call pkill -f mocha or kill the terminal session.

yarn run test:watch

NOTE: For the moment test watching in packages/algob is not stable because of tear down issues in some test suites. We advise to not use test watcher in packages/algob.