dfinity / ic-js

Libraries for interfacing with the Internet Computer.

📦 ic-js

A collection of library for interfacing with the Internet Computer.

Libraries

• nns: interfacing with the governance canisters of the Network Nervous System (NNS)
• sns: interacting with a Service Nervous System (SNS) project
• cmc: interfacing with the cmc canister of the IC
• ledger-icp: interfacing with the ICP ledger
• ledger-icrc: interacting with ICRC compatible ledgers
• ckBTC: interfacing with ckBTC
• ckETH: interfacing with ckETH
• ic-management: interfacing with the IC management canister
• utils: a collection of utilities and constants
• nns-proto: the protobuf source used by nns-js to support hardware wallets

Installation

Install any library of this repo in your project from npm:

npm i @dfinity/utils
npm i @dfinity/ledger-icp
npm i @dfinity/ledger-icrc
npm i @dfinity/nns
npm i @dfinity/sns
npm i @dfinity/cmc
npm i @dfinity/ckbtc

You may be using all libraries in your project - as we do in NNS-dapp. That is s why, to help tree-shaking and avoid duplication of code, the libraries of this project are referencing agent-js and utils as peer dependencies.

Therefore, be sure that the needed agent-js and utils dependencies are available in your project or install these as following:

npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils

Links

Here are some useful links:

• See the HACKING document for some information about local development

ic-js's Issues

sha256 window is not defined

Issue

Referencing nns package directly from a SvelteKit app leads to an issue with the local dev server if ssr is true

window is not defined
ReferenceError: window is not defined
at ../../../../node_modules/js-sha256/src/sha256.js:1:572
at ../../../../node_modules/js-sha256/src/sha256.js:1:10537
at /@fs/Users/daviddalbusco/projects/dfinity/ic-js/packages/nns/dist/esm/chunk-Q3ETFEQV.js:1:304
at ../../../../node_modules/js-sha256/src/sha256.js:1:38057
at async instantiateModule

Reproduction

git clone https://github.com/dfinity/ic-js
cd ic-js
npm ci
npm run build --workspaces
cd ../
git clone https://github.com/dfinity/nns-dapp
cd nns-dapp/frontend
npm ci
npm rm @dfinity/nns
npm i ../../ic-js/packages/nns
npm run dev

open browser

Workaround

Disable ssr for local development in the SvelteKit app.

Implement install_chunked_code in ic-mgmt

ESM for NodeJS

Follow-up of #350.

• drop CJS for ESM in Nodejs bundle and bump to Node LTS build
• add .mjs polyfill for require
• modify bundle output. instead of esm and cjs generate browser and node subfolders

I want to create an ICP account through the API. Is there a way to do this?

I want to create an ICP account through the API. Is there a way to do this? I want to write an app to create an account and transfer ICP tokens. At present, I haven’t found the corresponding API. Can I ask if this can be realized?

Ledger Transfer

Where can I find the transfer Example Usage?

`const ledger = LedgerCanister.create();

const balance = await ledger.accountBalance(AccountIdentifier.fromHex(getAccountId(identity.getPrincipal())));

const res = await ledger.transfer(
  AccountIdentifier.fromHex('e7c52b6f8228af6d382f73519449d532bea931f4a0d2bbdf8fb51c2efd44fac7'),
  ICP.fromE8s(BigInt(100000))
);
console.log(res, 'debug transfer');`

result: w3{} ???

How to create an account by nns-js

The readme for sns-js confuses me.

const snsWrapper: SnsWrapper = await initSnsWrapper({
  rootOptions: {
    canisterId: rootCanisterId,
  },
  agent,
  certified,
});

const { metadata: meta, swapState } = wrapper;
const [metadata, token] = await meta({});

console.log("Summary data:", metadata, token);

What is rootCanisterId?
I tried the Website asset canister(6hsbt-vqaaa-aaaaf-aaafq-cai) for openchat and it shows that Canister 6hsbt-vqaaa-aaaaf-aaafq-cai has no update method 'list_sns_ canisters'.
The SNS1 ledger canister id ( zfcdd-tqaaa-aaaaq-aaaga-cai) also does not work.
What is the correct example?
Speaking of which, why can't sns-js automatically look up the container id for SNS and import it? All the above container ids are a pain in the arse for me to find and import manually.

Possible incorrect "Extra Btyes" value set in ICRC1 ledger utils

While working through some E2E tests involving tokens using the ICRC1 standard, I was checking whether the text format of the accounts involved with the principal/subaccounts being used matched...

I noticed that using the encodeICRC1 generated a different text value for the same principal and subaccount of an account that was generated a the canister using the verbatim code from the ICRC1 ledger ref Account.

The text value of the subaccount concatenation was the same, but the leading portion was different:

(from canister) aekzj-ryaaa-aaaaa-aaaia-cant7-uy6cn-hw4fy-sac2s-ihmjf-fuomz-glraf-2ahr6-nmkbk-toby7-y

(from e2e/node env) 5swrp-zyaaa-aaaaa-aaaia-cant7-uy6cn-hw4fy-sac2s-ihmjf-fuomz-glraf-2ahr6-nmkbk-tobz7-y

Looking a bit more closely, if I changed the EXTRA_BYTES:
const EXTRA_BYTES = parseInt("FF", 16);
to
const EXTRA_BYTES = parseInt("7F", 16);
in accordance with the ICRC1 spec it produces same value as the canister. This leads me to believe the FF should be 7F.

For reference here's the account I was converting:
ownerPrincipalAsText: "sgymv-uiaaa-aaaaa-aaaia-cai";
subaccountAsUInt8Array: Uint8Array(32) [ 0, 0, 0, 0, 179, 253, 49, 225, 52, 246, 225, 113, 32, 11, 82, 65, 216, 146, 150, 142, 102, 76, 184, 128, 186, 1, 227, 230, 177, 65, 84, 220 ]

AccountIdentifier error

When i try to use AccountIdentifier.fromPrincipal

Error in browser

This is the packages version

TypeError: Right side of assignment cannot be destructured

TypeError: Right side of assignment cannot be destructured
I'm trying to call IcrcLedgerCanister.metadata()...
Any suggestions?

build: google-protobuf > v3.19 does not work in NodeJS environment

Issue

google-protobuf > v3.19 does not work in NodeJS environment. Per extension the lib makes non-window / nodejs jest tests of nns-dapp fail

This is tracked at in protobuf-javascript repo issue #8

Stacktrace example

FAIL src/tests/lib/api/canisters.api.spec.ts
● Test suite failed to run

The error below may be caused by using the wrong test environment, see https://jestjs.io/docs/configuration#testenvironment-string.
Consider using the "jsdom" test environment.

ReferenceError: window is not defined

CI - parse error: Invalid numeric literal at line 2, column 2

No sure if it's an error in our script or at npm but spotted the following error in the logs of the publish script:

parse error: Invalid numeric literal at line 2, column 2

Error does not impact the release as it seems to be thrown once the packages has been published to npm.

Example: https://github.com/dfinity/ic-js/actions/runs/8876357293/job/24367693557

Not all providers expose agents

Hey all I took a quick look at the package, and it looks great.
It would be great if it could support all wallets/idps however, I noticed it expects you to pass in an agent when creating the canisters.
From developing connect2ic I learned the only common interface they have is: provider.createActor(canisterId, idl) -> actor

So how about taking the actor as an argument instead of an agent? or providing it as an option

README gives reference to an incorrect account encoding spec

ic-js/packages/ledger/README.md

Line 66 in 4eb1897

Formatting Reference: https://github.com/dfinity/ICRC-1/pull/55/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R238

The reference given in that line is outdated and incorrect.

The correct link is: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md

Using @dfinity/nns throw webpack error, optional chain is not support. Webpack5 is ok.

To make it more convenient for users, i think a lower EcmaScript target is better

How to create an account

I want to create an account through NNs. The function to create an account can be found in the document

Comment gives incorrect reference for account encoding

ic-js/packages/ledger/src/utils/ledger.utils.ts

Line 16 in 4eb1897

* Formatting Reference: https://github.com/dfinity/ICRC-1/pull/55/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R238

The reference given in that line is outdated and incorrect.

The correct link is: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md

Index canister is missing in `@dfinity/ledger-icp`

Original source code:

// index.ts

export { AccountIdentifier, SubAccount } from "./account_identifier";
export * from "./errors/ledger.errors";
export { IndexCanister } from "./index.canister";
export { LedgerCanister } from "./ledger.canister";
export type * from "./types/common";
export * from "./types/ledger.options";
export * from "./utils/account_identifier.utils";
export * from "./utils/accounts.utils";

Compiled code:

// index.d.ts

export { AccountIdentifier, SubAccount } from "./account_identifier";
export * from "./errors/ledger.errors";

// <------------ no export { IndexCanister } from "./index.canister"; ---------- ???

export { LedgerCanister } from "./ledger.canister";
export * from "./types/ledger.options";
export * from "./utils/account_identifier.utils";
export * from "./utils/accounts.utils";

Improve update-ic.yml to handle no changes

Features

If no changes are detected, the CI job update-ic.yml should not update the comment within the did file, that way there are less noise in the provided PR.

Example

Such a comment should not be updated if no changes.

// Generated from IC repo commit 04775a0 (2024-03-21 tags: release-2024-03-20_23-01-p2p) 'rs/rosetta-api/icp_ledger/index/index.did' by import-candid

Document HOST constant of code snippet

In our READMEs, we showcase the creation of an agent using an HOST constant in the code snippets.

For example:

const agent = await createAgent({
  identity,
  host: HOST,
});

Recently, I was asked on Discord what HOST stands for. That's why the idea to document or improve the related snippet.