@ohos-ports/azle 0.33.0-beta.0

package/src/stable/lib/ic_apis/candid_decode.ts

@@ -0,0 +1,26 @@
+/**
+ * Decodes binary Candid value bytes into its string representation.
+ *
+ * @param candidBytes - The binary Candid value bytes to decode
+ * @returns The decoded Candid value string
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function candidDecode(candidBytes: Uint8Array): string {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.candidDecode(
+            candidBytes.buffer instanceof ArrayBuffer
+                ? candidBytes.buffer
+                : new Uint8Array(candidBytes).buffer
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.candidDecode(candidBytes);
+    }
+
+    return '';
+}

package/src/stable/lib/ic_apis/candid_encode.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a Candid value string into its binary representation.
+ *
+ * @param candidString - A Candid value string
+ * @returns The encoded binary Candid value bytes
+ *
+ * @remarks
+ *
+ * To help with type inference during encoding, you may wish to add explicit type annotations
+ * to your Candid value strings e.g. `(100_000_000: nat)` instead of `(100_000_000)`.
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function candidEncode(candidString: string): Uint8Array {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return new Uint8Array(
+            globalThis._azleIcExperimental.candidEncode(candidString)
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.candidEncode(candidString);
+    }
+
+    return new Uint8Array();
+}

package/src/stable/lib/ic_apis/canister_cycle_balance.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns the amount of cycles owned by and available to the canister.
+ *
+ * @returns The cycle balance. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @remarks
+ *
+ * - The cycle balance is calculated as follows:
+ *   - start at 0
+ *   - add the current cycle balance before the execution of the current message
+ *   - subtract a reserve to pay for the execution of the current message
+ *   - subtract any cycles queued up to be sent via `ic0.call_cycles_add` and `ic0.call_cycles_add128`
+ * - unused cycles from the reserve may be added back to the balance after message execution
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function canisterCycleBalance(): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(globalThis._azleIcExperimental.canisterCycleBalance());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.canisterCycleBalance();
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/canister_self.ts

@@ -0,0 +1,25 @@
+import { Principal } from '@dfinity/principal';
+
+/**
+ * Returns the `Principal` of the canister.
+ *
+ * @returns The `Principal` of the canister
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function canisterSelf(): Principal {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return Principal.fromText(
+            globalThis._azleIcExperimental.canisterSelf()
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return Principal.fromUint8Array(globalThis._azleIc.canisterSelf());
+    }
+
+    return Principal.fromHex('04');
+}

package/src/stable/lib/ic_apis/canister_version.ts

@@ -0,0 +1,33 @@
+/**
+ * Returns the canister's version number, which is incremented by ICP on certain operations.
+ *
+ * @returns The canister's version number. Represented as a u64 (max size 2^64 - 1)
+ *
+ * @remarks
+ *
+ * The version number starts at 0 upon canister creation. The version number is guaranteed to increase when:
+ * - Changes to canister code
+ * - Changes to canister settings
+ * - Changes to canister running status (Running/Stopping/Stopped)
+ * - Changes to memory (WASM memory or stable memory)
+ * - Any successful management canister call (`update_settings`, `load_canister_snapshot`, `install_code`, `install_chunked_code`, `uninstall_code`, `start_canister`, and `stop_canister`)
+ * - Canister runs out of cycles and code is uninstalled
+ * - Successful execution of update methods, heartbeats, global timers, or response callbacks
+ *
+ * Note: The system may arbitrarily increment the version at any time, even when
+ * no observable changes occur
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function canisterVersion(): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(globalThis._azleIcExperimental.canisterVersion());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.canisterVersion();
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/certified_data_set.ts

@@ -0,0 +1,35 @@
+/**
+ * Sets the canister's certified data.
+ *
+ * @param data - The data to certify (max 32 bytes)
+ *
+ * @returns void
+ *
+ * @remarks
+ *
+ * - Used in conjunction with `dataCertificate`
+ * - Limited to 32 bytes of data (traps if exceeded)
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@preUpgrade
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function certifiedDataSet(data: Uint8Array): void {
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.certifiedDataSet(
+            data.buffer instanceof ArrayBuffer
+                ? data.buffer
+                : new Uint8Array(data).buffer
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.certifiedDataSet(data);
+    }
+}

package/src/stable/lib/ic_apis/chunk.ts

@@ -0,0 +1,42 @@
+import { call } from './call';
+import { canisterSelf } from './canister_self';
+
+/**
+ * Resets the instruction limit after the await point.
+ *
+ * @returns Promise\<void\>
+ *
+ * @remarks
+ *
+ * - **Important**: Makes an inter-canister call to the canister itself
+ *   - Global state can change from before the await point to after the await point
+ *   - All code running after the await point will be in one of the following call contexts
+ *     - after a successful inter-canister await
+ *     - after an unsuccessful inter-canister await
+ *     - the original call context
+ * - See [the current instruction limits](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits)
+ *
+ * - **Call Context**:
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export async function chunk(): Promise<void> {
+    if (
+        globalThis._azleIc === undefined &&
+        globalThis._azleIcExperimental === undefined
+    ) {
+        // This allows chunk to behave similarly in Node.js
+        // because the continuation of its await or the .then callback
+        // will run after a new macrotask, allowing all previously queued microtasks
+        // to complete (this change was motivated by the event_loop tests)
+        return new Promise((resolve) => setTimeout(resolve));
+    }
+
+    await call<undefined, Uint8Array>(canisterSelf(), '_azle_chunk', {
+        cycles: 0n,
+        raw: true
+    });
+}

package/src/stable/lib/ic_apis/clear_timer.ts

@@ -0,0 +1,53 @@
+/**
+ * Cancels a timer previously created with `setTimer` or `setTimerInterval`.
+ *
+ * @param timerId - The ID of the timer to cancel, as returned by `setTimer` or `setTimerInterval`. Represented as a u64 (max size 2^64 - 1)
+ *
+ * @returns void
+ *
+ * @remarks
+ * - Does nothing if timer is already cancelled
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@preUpgrade
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function clearTimer(timerId: bigint): void {
+    if (
+        globalThis._azleIc === undefined &&
+        globalThis._azleIcExperimental === undefined
+    ) {
+        return;
+    }
+
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.clearTimer(timerId.toString());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.clearTimer(timerId.toString());
+    }
+
+    deleteGlobalTimerCallback(timerId);
+}
+
+function deleteGlobalTimerCallback(timerId: bigint): void {
+    if (globalThis._azleDispatch === undefined) {
+        throw new Error('globalThis._azleDispatch is undefined');
+    }
+
+    globalThis._azleDispatch({
+        type: 'DELETE_AZLE_TIMER_CALLBACK',
+        payload: timerId,
+        location: {
+            filepath: 'azle/src/stable/lib/ic_apis/clear_timer.ts',
+            functionName: 'deleteGlobalTimerCallback'
+        }
+    });
+}

package/src/stable/lib/ic_apis/cycles_burn.ts

@@ -0,0 +1,32 @@
+/**
+ * Attempts to irrevocably remove the specified amount of cycles from the canister's balance.
+ *
+ * @param amount - The number of cycles to burn. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @returns The number of cycles actually burned. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@preUpgrade
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function cyclesBurn(amount: bigint): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(
+            globalThis._azleIcExperimental.cyclesBurn(amount.toString())
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.cyclesBurn(amount.toString());
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/data_certificate.ts

@@ -0,0 +1,30 @@
+/**
+ * Returns the data certificate authenticating the canister's certified data.
+ *
+ * @returns The data certificate, or undefined if called outside of the following:
+ *   - a non-replicated query call from an ingress message
+ *   - a composite query call from an ingress message before an inter-canister await
+ *
+ * @remarks
+ *
+ * - Used in conjunction with `setCertifiedData`
+ * - Enables query calls to return certified responses
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function dataCertificate(): Uint8Array | undefined {
+    if (globalThis._azleIcExperimental !== undefined) {
+        const result = globalThis._azleIcExperimental.dataCertificate();
+
+        if (result === undefined) {
+            return undefined;
+        }
+
+        return new Uint8Array(result);
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.dataCertificate();
+    }
+}

package/src/stable/lib/ic_apis/in_replicated_execution.ts

@@ -0,0 +1,20 @@
+/**
+ * Checks if the current call is in replicated or non-replicated execution mode.
+ *
+ * @returns true if in replicated execution mode, false otherwise
+ *
+ * @remarks
+ * - **Call Context**:
+ *   - any
+ */
+export function inReplicatedExecution(): boolean {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.inReplicatedExecution();
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.inReplicatedExecution();
+    }
+
+    return false;
+}

package/src/stable/lib/ic_apis/index.ts

@@ -0,0 +1,37 @@
+export {
+    call,
+    CallError,
+    CallOptions,
+    CallPerformFailed,
+    CallRejected,
+    CleanupCallback,
+    InsufficientLiquidCycleBalance
+} from './call';
+export { candidDecode } from './candid_decode';
+export { candidEncode } from './candid_encode';
+export { canisterCycleBalance } from './canister_cycle_balance';
+export { canisterSelf } from './canister_self';
+export { canisterVersion } from './canister_version';
+export { certifiedDataSet } from './certified_data_set';
+export { chunk } from './chunk';
+export { clearTimer } from './clear_timer';
+export { cyclesBurn } from './cycles_burn';
+export { dataCertificate } from './data_certificate';
+export { inReplicatedExecution } from './in_replicated_execution';
+export { isController } from './is_controller';
+export { msgArgData } from './msg_arg_data';
+export { msgCaller } from './msg_caller';
+export { msgCyclesAccept } from './msg_cycles_accept';
+export { msgCyclesAvailable } from './msg_cycles_available';
+export { msgCyclesRefunded } from './msg_cycles_refunded';
+export { msgMethodName } from './msg_method_name';
+export { msgReject } from './msg_reject';
+export { msgRejectCode } from './msg_reject_code';
+export { msgRejectMsg } from './msg_reject_msg';
+export { msgReply } from './msg_reply';
+export { performanceCounter } from './performance_counter';
+export { randSeed } from './rand_seed';
+export { setTimer } from './set_timer';
+export { setTimerInterval } from './set_timer_interval';
+export { time } from './time';
+export { trap } from './trap';

package/src/stable/lib/ic_apis/is_controller.ts

@@ -0,0 +1,31 @@
+import { Principal } from '@dfinity/principal';
+
+/**
+ * Determines if a given `Principal` is a controller of the canister.
+ *
+ * @param principal - The `Principal` to check
+ *
+ * @returns true if the `Principal` is a controller of the canister, false if not
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function isController(principal: Principal): boolean {
+    if (globalThis._azleIcExperimental !== undefined) {
+        const principalBytes = principal.toUint8Array();
+
+        return globalThis._azleIcExperimental.isController(
+            principalBytes.buffer instanceof ArrayBuffer
+                ? principalBytes.buffer
+                : new Uint8Array(principalBytes).buffer
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.isController(principal.toUint8Array());
+    }
+
+    return false;
+}

package/src/stable/lib/ic_apis/msg_arg_data.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns the argument data of the current method call as bytes.
+ *
+ * @returns The argument bytes
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@inspectMessage
+ *   - \@update
+ *   - \@query, replicated and non-replicated
+ *   - \@query(..., { composite: true })
+ *   - after a successful inter-canister await
+ *   - after a successful inter-canister await from a composite query
+ */
+export function msgArgData(): Uint8Array {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return new Uint8Array(globalThis._azleIcExperimental.msgArgData());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgArgData();
+    }
+
+    return new Uint8Array();
+}

package/src/stable/lib/ic_apis/msg_caller.ts

@@ -0,0 +1,32 @@
+import { Principal } from '@dfinity/principal';
+
+/**
+ * Returns the `Principal` of the identity that initiated the current call.
+ *
+ * @returns The caller's `Principal`
+ *
+ * @remarks
+ *
+ * When called from:
+ * - \@init: `Principal` of the identity requesting installation
+ * - \@postUpgrade: `Principal` of the identity requesting upgrade
+ * - \@heartbeat: `Principal` of the management canister
+ * - timer: `Principal` of the management canister
+ * - inter-canister callee: `Principal` of the calling canister
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function msgCaller(): Principal {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return Principal.fromUint8Array(
+            new Uint8Array(globalThis._azleIcExperimental.msgCaller())
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return Principal.fromUint8Array(globalThis._azleIc.msgCaller());
+    }
+
+    return Principal.fromHex('04'); // the anonymous principal
+}

package/src/stable/lib/ic_apis/msg_cycles_accept.ts

@@ -0,0 +1,27 @@
+/**
+ * Moves up to `maxAmount` of the available cycles from the current call to the canister cycle balance.
+ *
+ * @param maxAmount - Maximum number of cycles to accept from the available cycles. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @returns The actual amount of cycles accepted. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - \@update
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function msgCyclesAccept(maxAmount: bigint): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(
+            globalThis._azleIcExperimental.msgCyclesAccept(maxAmount.toString())
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgCyclesAccept(maxAmount.toString());
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/msg_cycles_available.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns the amount of cycles that were transferred with the current call and are still available.
+ *
+ * @returns The amount of cycles available. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @remarks
+ *
+ * - Amount decreases as cycles are accepted by the canister
+ *
+ * - **Call Context**:
+ *   - \@update
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function msgCyclesAvailable(): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(globalThis._azleIcExperimental.msgCyclesAvailable());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgCyclesAvailable();
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/msg_cycles_refunded.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns the amount of cycles that were refunded from the last inter-canister call.
+ *
+ * @returns The amount of cycles refunded. Represented as a u128 (max size 2^128 - 1)
+ *
+ * @remarks
+ *
+ * - Can only be called after an inter-canister await
+ * - All unaccepted cycles transferred with an inter-canister call are automatically refunded to the calling canister at the end of the call
+ *
+ * - **Call Context**:
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function msgCyclesRefunded(): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(globalThis._azleIcExperimental.msgCyclesRefunded());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgCyclesRefunded();
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/msg_method_name.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns the name of the method being called during message inspection.
+ *
+ * @returns The name of the method
+ *
+ * @remarks
+ *
+ * - **Call Context**:
+ *   - \@inspectMessage
+ */
+export function msgMethodName(): string {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.msgMethodName();
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgMethodName();
+    }
+
+    return '';
+}

package/src/stable/lib/ic_apis/msg_reject.ts

@@ -0,0 +1,28 @@
+/**
+ * Rejects the current call with a message.
+ *
+ * @param message - The reject message
+ * @returns void
+ *
+ * @remarks
+ *
+ * - Produces reject code `CanisterReject (4)`
+ *
+ * - **Call Context**:
+ *   - \@update(..., { manual: true })
+ *   - \@query(..., { manual: true }), replicated and non-replicated
+ *   - \@query(..., { composite: true, manual: true })
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ *   - after a successful inter-canister await from a composite query
+ *   - after an unsuccessful inter-canister await from a composite query
+ */
+export function msgReject(message: string): void {
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.msgReject(message);
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.msgReject(message);
+    }
+}

package/src/stable/lib/ic_apis/msg_reject_code.ts

@@ -0,0 +1,40 @@
+/**
+ * Returns the reject code from the most recently executed inter-canister call.
+ *
+ * @returns The reject code as a number
+ *
+ * @remarks
+ *
+ * The currently supported reject codes are:
+ *
+ *   0: NoError
+ *
+ *   1: SysFatal
+ *
+ *   2: SysTransient
+ *
+ *   3: DestinationInvalid
+ *
+ *   4: CanisterReject
+ *
+ *   5: CanisterError
+ *
+ *   6: SysUnknown
+ *
+ * - **Call Context**:
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ *   - after a successful inter-canister await from a composite query
+ *   - after an unsuccessful inter-canister await from a composite query
+ */
+export function msgRejectCode(): number {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.msgRejectCode();
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgRejectCode();
+    }
+
+    return 6;
+}