ic0

ic0  

An easy-to-use JavaScript API for the Internet Computer.

The ic0 package is a simple, straightfoward way to interact with canisters running on the Internet Computer (IC).

Installation

npm i --save ic0

Quick Start

Try running the following code from Node.js or a web application:

import ic from 'ic0';

const ledger = ic('ryjl3-tyaaa-aaaaa-aaaba-cai'); // Ledger canister

console.log(await ledger.call('name')); // Call the `name()` method

Easily call any Internet Computer canister using the following syntax:

import ic from 'ic0';

ic(canisterId).call(method, ...args); // IC mainnet

ic.local(canisterId).call(method, ...args); // Local replica

Local Canisters

The dfx start command hosts a local execution environment for developing canister smart contracts. Here is an example of how to call a local canister:

const backend = ic.local('rrkah-fqaaa-aaaaa-aaaaq-cai'); // Access a local canister

backend.call('myFunction', 123); // Call `myFunction(123)`

Basic usage:

const ledger = ic('ryjl3-tyaaa-aaaaa-aaaba-cai'); // Principal for the IC ledger

console.log(await ledger.call('name')); // => { name: 'Internet Computer' }

Advanced usage:

Replica canisters use agent-js behind the scenes.

import { replica, HttpAgent } from 'ic0';

const ic = replica(new HttpAgent({ ... })); // Use a custom agent from `@dfinity/agent`

const ledger = ic('ryjl3-tyaaa-aaaaa-aaaba-cai');

console.log(await ledger.call('name')); // => { name: 'Internet Computer' }

Mock Canisters

A mock canister makes it easy to mock the behavior of a canister.

Basic usage:

import { mockCanister } from 'ic0';

const mock = mockCanister({
    // Mock canister method named `echo()`
    async echo(x: number) {
        return x;
    }
});

console.log(await mock.call('echo', 123)); // => 123

Advanced usage:

Provide a fallback canister and/or compose several mocks by passing a second argument to the mockCanister() function:

import { mockCanister, replicaCanister } from 'ic0';

const ledger = replicaCanister(principal, agent);

const mockLedger = mockCanister({
    async echo(x: number) {
        return x;
    }
}, ledger); // Fall back to the deployed `ledger` canister

const mock = mockCanister({
    async runMock() {
        return this.call('echo', 456); // Call the mocked `echo()` function
    }
}, mockLedger); // Fall back to another mock canister

console.log(await mock.call('runMock')); // => 456

Related Projects

Check out the following GitHub repositories for more IC-related npm packages:

• agent-js: a collection of npm packages for building on the Internet Computer
• node-motoko: run Motoko programs directly in the browser
• mo-dev: a live-reload server for local Motoko dapp development
• @infu/icblast: a community-built library for exploring the IC and writing integration tests