Azle Cloud Development Kit

Azle provides high-level performance tracking to compare efficiency across different releases. This document tracks changes in metrics like 'Baseline Weighted Efficiency' and 'Number of Instructions' for both Stable and Experimental modes.

Note: For granular performance data regarding how specific Candid data types perform, refer to the benchmarks example. This is the recommended resource for optimizing day-to-day performance in your Azle applications.

Azle runs in Stable Mode by default. This mode is designed for production use (targeting the 1.0 release) and focuses on API and runtime stability, security, performance, TypeScript/JavaScript support, ICP APIs, and Candid RPC.

Note: In Stable Mode, there is minimal support for the Node.js standard library, the npm ecosystem, and HTTP server functionality.

Azle applications (canisters) can be developed using one of two primary methodologies depending on your target client and serialization needs:

1. Candid RPC: This approach uses the Internet Computer's (ICP) Candid language. It exposes canister methods directly to Candid-speaking clients and uses Candid for serialization and deserialization. This is the standard approach for canister-to-canister or specialized client interaction.

   • Status: Release Candidate (heading towards 1.0).

2. HTTP Server: This approach uses traditional web server techniques. It allows you to write HTTP servers using popular libraries like Express and uses JSON for serialization and deserialization. This is ideal for standard web integration.

   • Status: Experimental.

By default, @query methods cannot perform cross-canister calls. To enable this capability, you must set the composite option to true in the decorator. This allows the method to be async and use the call function to interact with other canisters.

import { IDL, query, call } from 'azle';

export default class {
    @query([], IDL.Text, { composite: true })
    async crossCanisterQuery(): Promise<string> {
        const result = await call('canister-id', 'method_name', {
            returnIdlType: IDL.Text
        });
        return result;
    }
}

Azle provides an experimental HTTP Server methodology that allows you to develop applications using traditional web server techniques. This approach enables you to write servers using popular libraries like Express and use JSON for simple serialization and deserialization of data.

Note: HTTP Server functionality is currently marked as experimental and its stability/availability is not guaranteed for the long term.

Azle provides custom fetch implementations tailored for different contexts:

1. Client fetch: Used for authentication purposes (see Authentication).
2. Canister fetch: Used within a canister to perform:
   • Cross-canister calls to a Candid canister: Interacting with other canisters via their Candid interface.
   • Cross-canister calls to an HTTP canister: Interacting with canisters that expose HTTP interfaces.
   • HTTPS outcalls: Making requests to the external internet.

Class properties defined within your canister class automatically become persistent canister state. This allows you to store and modify data across different method calls.

import { IDL, query, update } from 'azle';

export default class {
    // This becomes persistent canister state
    counter: number = 0;
    users: Map<string, string> = new Map();

    @query([], IDL.Nat)
    getCounter(): number {
        return this.counter;
    }

    @update([], IDL.Nat)
    increment(): number {
        this.counter += 1;
        return this.counter;
    }
}

To enable cryptographic proofs for your query responses, you must use certifiedDataSet(data) inside an @update method. This function binds a specific piece of data (up to 32 bytes) to the canister's state so that subsequent @query calls can retrieve a corresponding certificate via dataCertificate().

Workflow:

1. In an @update call, prepare a Uint8Array of the data you wish to certify.
2. Call certifiedDataSet(data).
3. In a @query call, use dataCertificate() to return the proof alongside your data.

const encoder = new TextEncoder();
const data = encoder.encode(value.slice(0, 32));
certifiedDataSet(data);

Azle's experimental mode enables features like the Node.js standard library, the npm ecosystem, and HTTP server functionality. This mode is intended for developers who need early access to new features but must accept higher risks of bugs, security exploits, and breaking API changes.

To use experimental mode, you must explicitly enable it via a flag in dfx.json or through specific CLI commands during project creation.

The candidDecode function is intended for scenarios where you need to manually handle Candid-encoded data rather than relying on Azle's automatic argument decoding. Common use cases include:

• Processing raw argument data: Using msgArgData() to get the raw bytes of a call and then decoding them manually.
• Decoding external data: Handling data received from sources outside the standard Azle request lifecycle.
• Inter-canister calls: Manually parsing responses from other canisters.
• Stored data: Decoding Candid-encoded blobs retrieved from stable memory or other storage mechanisms.