📦 DID namespaces and other Breaking Changes in @icp-sdk/canisters@3

Developers
1

Hi :waving_hand:

So, you’re gonna have to trust me a bit on this bro, but we shipped a breaking change in the latest version of @icp-sdk/canisters that aims to make the source code of your applications more readable and generally your projects better maintainable.

Indeed, instead of re-exporting each and every single Candid type that you may use through the library, all those types will now be exposed through DID namespaces.

For example, the Tokens type of the IcrcLedgerCanister is available within the related namespace IcrcLedgerDid.

import {
  type IcrcLedgerDid,
  IcrcLedgerCanister,
} from "@icp-sdk/canisters/ledger/icrc";

const { balance } = IcrcLedgerCanister.create({
  agent,
  canisterId,
});

const data: IcrcLedgerDid.Tokens = await balance({ owner });

I introduced this pattern a few months ago in Juno, and while at first I felt like it was a bit more verbose, I rapidly started liking the pattern. It’s just cleaner :broom:. So, we discussed it with my colleagues and we started adopting it for OISY, NNS dapp, and other libraries, which is why we’re shipping this change today.

In addition, since we were already there, we noticed several inconsistencies. For example, some canisters used uppercase while others used camelCase, or some were too generic - e.g., the ICP ledger canister was named LedgerCanister and not IcpLedgerCanister.

Finally, we got rid of the “Ng” keyword in the ICRC index canister because, on one hand, the keyword doesn’t make any sense for new developers, and on the other, to our knowledge, all known indexes have been using the latest implementation for a year or so.

All those changes can basically be resolved by a search-and-replace. You can find the upgrade guide there :backhand_index_pointing_right: https://javascript.icp.build/canisters/latest/upgrading/v3/

Let me know if you have questions!

Note: Aside from the @dfinity/ledger-icrc library, all those changes should not impact the legacy libraries. However, as mentioned a few weeks ago in the announcement, we warmly recommend you migrate to this new library as this is the way to move forward!

5 Likes