⚠️ Breaking Changes in Ledger ICRC/ICP JavaScript Libraries

Hey JavaScript IC devs :wave:,

Recently, we’ve observed sometimes a bit of confusion regarding which libraries should be used for interacting with which type of ledger. To address this and prevent future misunderstandings, we’ve introduced the following breaking changes in ic-js, which have just been published to NPM:

  • ICP ledger-related features have been relocated from @dfinity/nns to a new dedicated library called @dfinity/ledger-icp

  • ICRC ledger-related features have been moved as well. The library @dfinity/ledger has been deprecated, renamed, and replaced by @dfinity/ledger-icrc

  • @dfinity/ledger is still available on NPM (for now), but it’s deprecated and will be retired at some point

In simpler terms:

Additionally, we’ve decided to adopt semantic versioning. Since everything is functioning smoothly now, all libraries have been bumped to at least v1.0.0. :partying_face:

Furthermore, we’ve enhanced our CI pipeline. This means that upon new releases, only the libraries that have received changes will be published, in contrast to our previous practice of publishing everything each time.

To provide a clear overview, we’ve introduced a release table in each release. This allows you to easily identify what has been updated or remains unchanged. You can see an example of today’s last release here :point_right: https://github.com/dfinity/ic-js/releases/tag/2023.10.02-1515Z

Library Version Status
@dfinity/ckbtc v1.0.1 Patched
@dfinity/cmc v1.0.0 Unchanged
@dfinity/ic-management v1.0.0 Unchanged
@dfinity/ledger v1.0.0 Deprecated :x:
@dfinity/ledger-icp v1.0.0 New :rocket:
@dfinity/ledger-icrc v1.0.0 New :rocket:
@dfinity/nns v2.0.0 Breaking Changes :warning:
@dfinity/nns-proto v1.0.0 Unchanged
@dfinity/sns v1.0.0 Patched
@dfinity/utils v1.0.0 Unchanged

Hope that’s cool?

Please don’t hesitate to reach out with any questions or observations!


So is the plan for the ICP and ICRC ledgers to be one and the same eventually? Why is ICP a distinct ledger from ICRC?


I don’t work in the FI team, so they can provide a better answer, but basically, there will always be a few differences because the ICP ledger and index canister will have to work with ICP account identifiers, which cannot be decoded I understand. So, while some interfaces are the same, e.g. it’s possible to make ICRC transfer with ICP ledger too, it will never be possible to have everything 100% entirely similar, e.g. the ICP Index canister returns ICP account identifier and not ICRC accounts.

Considering that these libraries interact with the ledger and index canister, we believe that shipping this way will help avoid confusion for consumers of the JS libraries.

Makes sense?