ICP JavaScript SDK v3.0.0 is released!

Developers JavaScript
1

We have released v3.0.0 of the ICP JavaScript SDK libraries. This is a major release that introduces significant refactoring, API improvements, and breaking changes.

Among the key improvements, this release eliminates Buffer and similar dependencies, significantly reducing bundle size and improving performance across all packages.

What’s New

Here are some of the key changes introduced in this release:

  • API Refinements:

    • Many functions and class methods, especially within the @dfinity/candid package, have been standardized to use Uint8Array instead of a mix of ArrayBuffer and Uint8Array.
    • Error handling is now more straightforward with a single AgentError class, replacing the multiple error types from previous versions.
    • The defaultAgent global and ProxyAgent class have been removed to simplify the API and encourage more explicit agent management.

  • Dependency Modernization: Thanks to the new @dfinity/cbor package dependency, legacy libraries like Buffer and BigNumber have been removed. This led us to a significant reduction in the packages’ bundle size.

  • Support for Presigned Requests: The polling strategy for read_state has been updated to support presigned requests, a key feature for integrating with hardware wallets or other external signing solutions.

  • IC Spec Alignment: The lookup methods of the Certificate have been updated and renamed to align with the IC Interface Specification.

  • Clock Drift Calculation: The HttpAgent will now automatically adjust the ingress expiry time based on the latest subnet’s certified time. You can also sync the local time with the IC network before an error occurs by using the shouldSyncTime option.

  • New Documentation Site: The documentation has been completely rebuilt and is still available at agent-js.icp.xyz. The new site offers better search, navigation, and comprehensive API references.

Here’s the list of all the packages that have been upgraded to v3:

This release contains important breaking changes. We strongly recommend reviewing the full release notes for a complete list of changes and a guide to upgrading your projects.

Release Notes: https://agent-js.icp.xyz/release-notes/v300/.
Changelog: Release v3.0.0 · dfinity/icp-js-core · GitHub.

Future work

  • A fix for the long-standing issue of importing the IDL module from the @dfinity/candid package is on the way. It will likely be available in the v3.0.1 patch release.
  • More security improvements to how the HttpAgent manages the ingress expiry, clock drift and certificate freshness checks will come in the next weeks.
  • We are in the process of rebranding the packages names, and eventually publish them under a single modular package. This will likely lead us to deprecate some of the current @dfinity/... packages. In any case, we will make sure that the migration to the new package(s) will be as straightforward as possible. More on this soon.
  • We are planning to deprecate @dfinity/use-auth-client in favor of more adopted packages like ic-use-internet-identity, ic-use-actor or @ic-reactor/react. Again, more on this soon.
14 Likes
2

Here we go! v3.0.1 is out, fixing the long-standing IDL imports issue.

Changelog: Release v3.0.1 · dfinity/agent-js · GitHub

3 Likes
3

Please update peer deps in @dfinity/ledger-icrc package too

4

We can’t at this time. It requires changes in both the NNS dapp and OISY to handle the breaking changes introduced in Agent-js v3. Until those are addressed, tested and validated on mainnet, @dfinity/ledger-icrc and other ic-js libraries won’t be officially upgraded and released.

2 Likes
5

:tada: Amazing work on this major release! The improvements in bundle size, API clarity, and IC spec alignment are incredibly valuable for the ecosystem. Kudos to the team for pushing this forward :clap:

As the maintainer of the @ic-reactor packages, I’m excited to announce that I’ll be updating the libraries to support v3.0.0 very soon. This aligns perfectly with several new features we’ve been preparing, including enhanced canister management, better auth handling, and deeper modularity for IC dapps. :rocket:

Looking forward to seeing how the ecosystem evolves around this cleaner, leaner SDK. Thanks again for the awesome work!

6 Likes
6

Why can’t those apps keep using the old libraries?

7

For context: Until now, the approach for these feature libraries has always been to first integrate them into the NNS dapp and OISY. Once stabilized, we release updated versions to the community. For example, we update the .did files weekly, apply necessary patches, and develop new features. As a result, dapps often integrate new versions of the libraries multiple times a week—we iterate continuously. The goal is to improve the libraries, test them thoroughly through our pipelines and manual QA, and release only once everything has passed our acceptance criteria.

To answer your question: yes, I guess, we can technically modify our pipelines to support, say, two branches and apply patches to both. However, that would introduce additional overhead. And as mentioned above, our general practice is to ship once a feature has gone through the full development, testing and release flow.

That said, I need to clarify two things based on internal discussions this afternoon: the Foundation — and specifically the SDK team — is working on making the dapps compatible with v3.0.0.

Also, if anyone is interested in beta-testing a version of the ic-js libraries compatible with v3.0.0, you can try it. I didn’t share this yesterday because I wasn’t aware the versions had been manually tested. But for example, if you’re using @dfinity/ledger-icp and want to migrate to v3.0.0, you can try installing the beta version: npm i @dfinity/ledger-icp@beta.

8

ic-reactor v2 has just been released with full support for agent-js v3 right out of the box.

5 Likes
9

Cross posting for reference: ICP JavaScript SDK v4.0.0 is released!

3 Likes
10

@ZenVoich the dfinity/ic-js libraries have been updated to use the v3 version.

1 Like
11

@ZenVoich the ic-js libraries have been updated to use the latest version (v4 today) of the core library, see:

1 Like