Azle (Beta)

TypeScript CDK for the Internet Computer.

Discussion

Feel free to open issues or join us in the DFINITY DEV TypeScript Discord channel.

Installation

You should have the following installed on your system:

Node.js
npm
Rust
wasm32-unknown-unknown Rust compilation target
didc
dfx 0.8.4

Node.js

Run the following commands to install Node.js and npm. nvm is highly recommended and its use is shown below:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

# restart your terminal

nvm install 14

Rust

Run the following command to install Rust and the wasm32-unknown-unknown target:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustup target add wasm32-unknown-unknown

didc

Run the following command to install didc:

cargo install --git https://github.com/dfinity/candid didc

dfx

Run the following command to install dfx 0.8.4:

# Azle has been tested against version 0.8.4, so it is safest to install that specific version for now
DFX_VERSION=0.8.4 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

Common Installation Issues

Ubuntu
- error: linker cc not found (sudo apt install build-essential)
- is cmake not installed? (sudo apt install cmake)

Azle

In many ways developing with Azle is similar to any other TypeScript/JavaScript project. Imagine you have a project called backend:

Create a directory for your project
Create a package.json file
Install Azle
Create a dfx.json file
Create a directory and entry TypeScript file for your canister
Fill out your dfx.json file

Here are the commands you might run from a terminal to setup your project:

mkdir backend
cd backend
npm init -y
npm install azle
touch dfx.json
mkdir src
cd src
touch backend.ts

Your dfx.json should look like this:

{
    "canisters": {
        "backend": {
            "type": "custom",
            "build": "npx azle backend",
            "root": "src",
            "ts": "src/backend.ts",
            "candid": "src/backend.did",
            "wasm": "target/wasm32-unknown-unknown/release/backend.wasm"
        }
    }
}

Local Deployment

Start up an IC replica and deploy:

# Open a terminal and navigate to your project's root directory, then run the following command to start a local IC replica
dfx start

# Alternatively to the above command, you can run the replica in the background
dfx start --background

# If you are running the replica in the background, you can run this command within the same terminal as the dfx start --background command
# If you are not running the replica in the background, then open another terminal and run this command from the root directory of your project
dfx deploy

You can then interact with your canister like any other canister written in Motoko or Rust. To get started with calling your canister using dfx, see here.

Writing Canisters in TypeScript/JavaScript

See the examples in this respository.

If you want to ensure running the examples with a fresh clone works, run npm link from the Azle root directory and then npm link azle inside of the example's root directory. Not all of the examples are currently kept up-to-date with the correct Azle npm package.

Roadmap

Limitations

No stable memory access, all state is wiped after upgrades
Limited asynchronous TypeScript/JavaScript (generators only for now, no promises or async/await)
Third-party npm packages that you import may use unsupported syntax or APIs
Unknown security vulnerabilities
Unknown cycle efficiency relative to canisters written in Rust or Motoko
And much much more

Tips and Best Practices

Because Azle is built on Rust, to ensure the best compatibility use underscores to separate words in directory, file, and canister names
If you need 64-bit numbers of any kind, currently use float64

Contributing

All contributors must agree to and sign the Azle License Extension.

Please consider working on the good first issues and help wanted issues before suggesting other work to be done.

Before beginning work on a contribution, please create or comment on the issue you want to work on and wait for clearance from Demergent Labs.

See Demergent Labs' Coding Guidelines for what to expect during code reviews.

License

Azle's copyright is governed by the LICENSE and LICENSE_EXTENSION.

Decentralization

Please note that the following plan is very subject to change, especially in response to compliance with government regulations. Please carefully read the Azle License Extension to understand Azle's copyright and the AZLE token in more detail.

Azle's tentative path towards decentralization is currently focused on traditional open source governance paired with a new token concept known as Open Source tokens (aka OS tokens or OSTs). The goal for OS tokens is to legally control the copyright and to fully control the repository for open source projects. In other words, OS tokens are governance tokens for open source projects.

Azle's OS token is called AZLE. Currently it only controls Azle's copyright and not the Azle repository. Demergent Labs controls its own Azle repository. Once a decentralized git repository is implemented on the Internet Computer, the plan is to move Demergent Labs' Azle repository there and give full control of that repository to the AZLE token holders.

Demergent Labs currently owns the majority of AZLE tokens, and thus has ultimate control over Azle's copyright and AZLE token allocations. Demergent Labs will use its own discretion to distribute AZLE tokens over time to contributors and other parties, eventually owning much less than 50% of the tokens.

dansteren/azle