Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dfinity/node-ic0
An easy-to-use JavaScript API for the Internet Computer.
https://github.com/dfinity/node-ic0
blockchain browser canister internet-computer motoko nodejs npm smart-contracts typescript web3
Last synced: 2 months ago
JSON representation
An easy-to-use JavaScript API for the Internet Computer.
- Host: GitHub
- URL: https://github.com/dfinity/node-ic0
- Owner: dfinity
- License: apache-2.0
- Created: 2023-01-10T19:25:13.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-26T18:52:47.000Z (4 months ago)
- Last Synced: 2024-10-25T20:05:52.751Z (3 months ago)
- Topics: blockchain, browser, canister, internet-computer, motoko, nodejs, npm, smart-contracts, typescript, web3
- Language: TypeScript
- Homepage:
- Size: 396 KB
- Stars: 19
- Watchers: 6
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-internet-computer - node-ic0 - The ic0 package is a simple, straightforward way to interact with canisters running on the IC. (Client Libraries (Agents) / JavaScript/TypeScript)
README
# `ic0` [](https://www.npmjs.com/package/ic0) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/dfinity/ic0/issues)
> ### An easy-to-use JavaScript API for the [Internet Computer](https://internetcomputer.org/).
---
The `ic0` package is a simple, straightfoward way to interact with canisters running on the [Internet Computer](https://internetcomputer.org/) (IC).
## Installation
```sh
npm i --save ic0
```
## Quick Start
Try running the following code from Node.js or a web application:
```ts
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:
```ts
import ic from 'ic0';
ic(canisterId).call(method, ...args); // IC mainnet
ic.local(canisterId).call(method, ...args); // Local replica
```
## Local Canisters
The [`dfx start`](https://internetcomputer.org/docs/current/references/cli-reference/dfx-start) command hosts a local execution environment for developing canister smart contracts. Here is an example of how to call a local canister:
```ts
const backend = ic.local('rrkah-fqaaa-aaaaa-aaaaq-cai'); // Access a local canister
backend.call('myFunction', 123); // Call `myFunction(123)`
```
### Basic usage:
```ts
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](https://github.com/dfinity/agent-js) behind the scenes.
```ts
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](https://stackoverflow.com/a/2666006) the behavior of a canister.
### Basic usage:
```ts
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:
```ts
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](https://github.com/dfinity/agent-js): a collection of npm packages for building on the Internet Computer
- [node-motoko](https://github.com/dfinity/node-motoko): run Motoko programs directly in the browser
- [mo-dev](https://npmjs.com/package/mo-dev): a live-reload server for local Motoko dapp development
- [@infu/icblast](https://github.com/infu/icblast): a community-built library for exploring the IC and writing integration tests