dansteren / azle

TypeScript/JavaScript CDK for the Internet Computer

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:

1. Create a directory for your project
2. Create a package.json file
3. Install Azle
4. Create a dfx.json file
5. Create a directory and entry TypeScript file for your canister
6. 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

• Beta

  • TypeScript -> Candid compiler
  • Basic IC APIs
    • call
    • caller
    • canisterBalance
    • id
    • print
    • rawRand
    • time
    • trap
  • Basic primitive data types
    • int32
    • int16
    • int8
    • nat16
    • nat8
    • float64
    • float32
  • Many examples
  • Simple example-based unit tests
  • Excellent documentation
  • Video series

• 1.0

  • Advanced primitive data types
    • int
    • int64
    • nat
    • nat64
    • nat32
    • Principal
  • Advanced IC APIs
    • Stable memory
    • Certified data
    • Cycles management
  • Flexible stable memory access
  • Feature parity with Rust and Motoko CDKs
  • Inter-Canister Query Calls
  • Live robust examples
  • Robust property-based tests
  • Comprehensive benchmarks
  • Security audits
  • Optimized compilation

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.