Skip to main content

ExperimentalInternetComputer

Low-level interface to the Internet Computer.

WARNING: This low-level API is experimental and likely to change or even disappear.

Value call​

let call : (canister : Principal, name : Text, data : Blob) -> async (reply : Blob)

Calls canister's update or query function, name, with the binary contents of data as IC argument. Returns the response to the call, an IC reply or reject, as a Motoko future:

  • The message data of an IC reply determines the binary contents of reply.
  • The error code and textual message data of an IC reject determines the future's Error value.

Note: call is an asynchronous function and can only be applied in an asynchronous context.

Example:

import IC "mo:base/ExperimentalInternetComputer";
import Principal "mo:base/Principal";

let ledger = Principal.fromText("ryjl3-tyaaa-aaaaa-aaaba-cai");
let method = "decimals";
let input = ();
type OutputType = { decimals : Nat32 };

let rawReply = await IC.call(ledger, method, to_candid(input)); // serialized Candid
let output : ?OutputType = from_candid(rawReply); // { decimals = 8 }

Learn more about Candid serialization

Function countInstructions​

func countInstructions(comp : () -> ()) : Nat64

Given computation, comp, counts the number of actual and (for IC system calls) notional WebAssembly instructions performed during the execution of comp().

More precisely, returns the difference between the state of the IC instruction counter (performance counter 0) before and after executing comp() (see Performance Counter).

NB: countInstructions(comp) will not account for any deferred garbage collection costs incurred by comp().

Example:

import IC "mo:base/ExperimentalInternetComputer";

let count = IC.countInstructions(func() {
  // ...
});

Value performanceCounter​

let performanceCounter : (counter : Nat32) -> (value : Nat64)

Returns the current value of IC performance counter counter.

  • Counter 0 is the current execution instruction counter, counting instructions only since the beginning of the current IC message. This counter is reset to value 0 on shared function entry and every await. It is therefore only suitable for measuring the cost of synchronous code.

  • Counter 1 is the call context instruction counter for the current shared function call. For replicated message executing, this excludes the cost of nested IC calls (even to the current canister). For non-replicated messages, such as composite queries, it includes the cost of nested calls. The current value of this counter is preserved across awaits (unlike counter 0).

  • The function (currently) traps if counter >= 2.

Consult Performance Counter for details.

Example:

import IC "mo:base/ExperimentalInternetComputer";

let c1 = IC.performanceCounter(1);
work();
let diff : Nat64 = IC.performanceCounter(1) - c1;

Function replyDeadline​

func replyDeadline() : Nat

Returns the time (in nanoseconds from the epoch start) by when the update message should reply to the best effort message so that it can be received by the requesting canister. Queries and non-best-effort update messages return zero.