Upgrading old ICRC1 token to the ICRC ledger suite

Developers
1

Is it safe to upgrade an older ICRC1 ledger WASM to the modern ICRC ledger suite?
Goal: Change name and add logo image to ICRC1 metadata

We are trying to update the token logo and description. The plan was to simply modify metadata without changing the WASM by using dfx with UpgradeArgs and --upgrade-unchanged

To do this, we need to provide the currently installed WASM.
ICPSwap informed us that this is the WASM used to deploy CLOUD token.
https://download.dfinity.systems/ic/f89cf257a4e88a5e2f6f29ab50ad4a49b0cb514d/canisters/ic-icrc1-ledger.wasm.gz

Hash: 75178691fce3ed6181ca2a4bf17f26c0ca12a88fda2c7a8eb867ae5281a4d1fd

But the hash of this WASM does not match the CLOUD ledger canister module hash. Hence, we are a bit in the unknown when it comes to the current version, although can guess depending on the time.

According to the canister upgrade history, CLOUD was created on June 10, 2023.

The CLOUD ICRC1 token was deployed with and currently runs WASM hash:

8ddd17ccaab8bd6adf337acb38f89b0db6db3c976f5768bb9a7ced5cef7bd481

We looked at many hashes of ic-icrc1-ledger.wasm releases from before CLOUD token was created, but did not find a match.

Given we don’t have the exact WASM, we believe it is necessary to upgrade the WASM to achieve our goal.

Internet Computer Docs regarding ICRC1 tokens used to say to use WASM based on the commit version of IC

For example: f89cf257a4e88a5e2f6f29ab50ad4a49b0cb514d https://download.dfinity.systems/ic/f89cf257a4e88a5e2f6f29ab50ad4a49b0cb514d/canisters/ic-icrc1-ledger.wasm.gz

Now the docs say to use the latest ICRC ledger suite release.

So long as we are upgrading the WASM, it seems best practice would be to upgrade to the latest icrc1-suite-ledger release.

There are currently 3 icrc-ledger-suite releases.

These releases must be installed oldest to newest.

We performed these upgrades locally in a development environment and it seemed successful.
But would like clarification and assurance that our approach is correct.

Code and instructions available here:

Helpful resource:

Viewed the canister history by using this playground

2 Likes
2

I’m not 100% sure, but last time I checked there were no changes to the ICRC ledger that were not backwards compatible. Therefore I would assume that it is safe to just use the latest wasm directly

4 Likes
3

Hi everyone,

I’m looking for some help with updating a token I deployed on the Internet Computer.

Context:

  • I have the seed phrase for a wallet created using PlugWallet.
  • I used this wallet with the ICP Swap platform to deploy an ICRC token.
  • Now I want to update the token’s metadata – specifically, to add a logo – without affecting token balances or data.

What I need to do:

  • Somehow connect or convert my PlugWallet identity to a DFX developer identity, so I can upgrade the canister using the DFX CLI.
  • Safely redeploy or upgrade the token canister, keeping all the current data and state intact.

Questions:

  1. Is there a way to import a PlugWallet (seed phrase or identity) into DFX?
  2. What’s the safest way to upgrade the ICRC token canister to update metadata without losing state?
  3. Has anyone done this after using ICP Swap to deploy a token?

Any help, tools, or tips would be appreciated!

Module Hash:

c393527a9068184267e1f845188bae58b13e0140b119c36145a0eff2cf9610bd

Thanks in advance :folded_hands:

4

I’ve never tried it, but you should be able to do the following according to the docs:

dfx identity import --seed-file path/to/file-with-seed-phrase.txt

Both DFX and Plug use the same key algorithm and derivation path, so it should result in the same principal.

You can verify this with:
dfx identity get-principal

5

Regarding question #2, have a look here. If you’re looking to only change the metadata, an option would be to upgrade to the same wasm module as the canister is currently running, but you would need to figure out which wasm/git commit the module hash you posted corresponds to. My quick search didn’t turn up any hits other than this thread, but the forum post linked above has some other pointers that could help figuring it out.

1 Like
6

I tried to import the Plug wallet seed phrase, but it failed with the following error:
“Failed to create mnemonic from phrase: invalid word in phrase.”

The Plug wallet seed phrase contains 12 words.

7

Just gave it a try on my end, created a new Plug wallet, which resulted in the following seed phrase:

brain pluck volume actress domain evolve trade focus wheat brave helmet dismiss

Stored this in a txt file and then imported it:

dfx identity import plug-identity --seed-file phrase.txt

Then after confirming by entering my mac OS keychain password, I can switch to it and indeed see the same principal as seen in Plug:

dfx identity use plug-identity
dfx identity get-principal # muw7v-dvooi-6op3z-7niox-mk4gg-widqt-skakg-5g6as-bpvz4-ppmmb-uqe

Are you sure the file has exactly one space between each word and no leading or trailing spaces? Are you sure all words are in lower case? Are you sure all words are correctly spelled?

There are only 2048 different words in a seed phrase, you can find all possible words and their spelling here: BIP 39 Wordlist – Blockplate

1 Like
8

All good now — just a typo with the seed phrase. Once I entered the correct one, the identity loaded fine. Now onto the harder part: checking the installed ledger version, updating the metadata, and especially adding the token logo.

9

Hey Mathias,

Thanks again for the guidance earlier — much appreciated.

We’ve tracked down the exact WASM version our token ledger is running:

IC_VERSION=2e3589427cd9648d4edaebc1b96b5daf8fdd94d8

And here’s the canister we’re working with:

wqihv-qyaaa-aaaak-afjoa-cai

Token: WindogeXP (XP)
Links: X | Site

Our main goal is to update the token metadata, especially to add the token logo, without changing the actual logic. From what you mentioned, it sounds like we can upgrade using the same WASM module version to make these changes.

We’d love some help figuring out the best way to test this full process safely - ideally end-to-end - before we apply the changes on the live canister.

If there’s a recommended flow or best practices for testing metadata upgrades like this, we’d be grateful for any pointers.

Thanks again for all the support!

10

Finally I’ve found and test the dfx command I need to use to update the metadata only.

However, I’m currently stuck trying to find the correct Ledger WASM module.

Can someone help?

Ledger Canister ID: wqihv-qyaaa-aaaak-afjoa-cai

11

Hi @bobekas,
For testing the upgrade, trying to expand a bit on the forum post on upgrading the ledger suite, you could set up a test canister (either on mainnet, or in a local development environment using dfx and pocketic), create a representative number of transactions so that it as closely as possible reflects the production ledger, and then go through the upgrade and verification steps.

Regarding the WASM version - I’m not able to find the WASM that is installed.
IC_VERSION=2e3589427cd9648d4edaebc1b96b5daf8fdd94d8 refers to a commit from October 2023. However, when querying the git_commit_id from the canister (using dfx canister --ic metadata wqihv-qyaaa-aaaak-afjoa-cai git_commit_id), I get 794fc5b9341fa8f6a0e8f219201c35f0b5727ab9, a commit from May 2023. Neither of those WASMs (.gziped or not) (2e3589427c, 794fc5b934) have a sha256sum that matches the currently installed module hash of c393527a9068184267e1f845188bae58b13e0140b119c36145a0eff2cf9610bd. Do you have any more information on how you installed the WASM? E.g., the date you installed it, if you installed it using a script/which command(s) you used, did you build the WASM yourself (if so, how) or if you downloaded a pre-built WASM?

1 Like
12

Hi! Thanks a lot for the thorough investigation and support — really appreciate it. :folded_hands:

The token ledger was initially deployed via @ICPSwap, so they might be able to shed some light on the original WASM.

I found their developer Telegram group, so I’ll reach out to them there.

Thanks again!
We’ll take it from here and I’ll share any updates in this thread later.

13

Dear @bobekas Let me check with the devs—just to confirm, you’re asking for the specific WASM file used, so you can match it with the module hash, right?

1 Like
14

Exactly. The XP token was deployed on January 16, 2024.

Ledger Module hash: c393527a9068184267e1f845188bae58b13e0140b119c36145a0eff2cf9610bd

15

Sorry @bobekas
The devs have informed me that when they upgraded to the new version afterwards, the old version was overwritten, and unfortunately it can no longer be retrieved.

Dear Mathias @mathiasb
The dev used a standard installation command, without a custom script:
dfx deploy icrc1-ledger-XP --network ic
The XP token was deployed on January 16, 2024.

Would this information be sufficient to help you locate the WASM version that was used at that time? thanks so much!

1 Like
16

Based on my research, the ledger.did file from this commit appears to be identical to the .did version used by the XP token. However, the ledger.wasm hash differs.

What if we attempt a redeploy using UpdateArgs with updated metadata? What are the risks involved? Is it possible to revert the change if needed?

17

@ICPSwap: Do you know how the canister WASM was obtained for use in the dfx deploy icrc1-ledger-XP --network ic command? One flow I can think of is that the IC repository was checked out at commit 794fc5b9 (since that’s what the canister git_commit_id metadata reports), but then WASM was then either built using some non-standard means, or there were some local modifications made (but not committed), and then the canister was built the “regular” way (./gitlab-ci/container/build-ic.sh -c from the IC repository root) - this since the module hash of the running canister is neither 8ddd17cc nor dadfa91b (the hashes of the uncompressed and gzipped version of the ledger canister WASM, respectively).

@bobekas: The ledger.did file changes much less frequently than the WASM, and the Candid interface on the dashboard doesn’t show everything, but it does seem that the ledger.did file is from between 2023-05-10 (commit 794fc5b9), but before the commit on 2023-07-17 (commit 83d252f1), since the latter adds the icrc2 endpoints, which the deployed canister does not have.

What do you mean by attempting to “redeploy using UpdateArgs with updated metadata”? If you reinstall, you will lose the current state. What you want to do is upgrade, but you do need to provide a WASM, even if you only want to change the settings.

Without being able to determine the WASM that was used to deploy the ledger, and therefore not being able to test the upgrade from that specific version, there is more risk. However, there should not have been any breaking changes between the version that is deployed, up until the ledger-suite-icrc-2024-10-17 release, so upgrading to that would be the recommended approach. I would recommend testing with the 794fc5b9 version, even if the module hash doesn’t match, and making a canister snapshot before upgrading the production ledger. Then you could roll back to the snapshot in case of issues, but any transactions made in the meantime would also be rolled back.

1 Like
18

Thanks for the clarification — you’re absolutely right, I misspoke earlier. I didn’t mean to redeploy using reinstall, I meant to upgrade the canister while preserving state.

Here’s the plan I’m going to follow:

  1. Snapshot the canister to ensure we have a rollback point.
  2. Test the upgrade using the closest known version (794fc5b9), since it aligns with the git_commit_id metadata.
  3. Monitor for inconsistencies and confirm everything behaves as expected post-upgrade.
  4. If any issues arise, roll back using the snapshot.

Appreciate your insights — they’ve been very helpful in shaping a safer upgrade path.

2 Likes
19

After some research, it’s most likely this version:
https://download.dfinity.systems/ic/f89cf257a4e88a5e2f6f29ab50ad4a49b0cb514d/canisters/ic-icrc1-ledger.wasm.gz

We found it directly from the resources page, though it seems the content there has been updated:

we used directly without any modifications
cc @bobekas

20

Big thanks to @ICPSwap and all DFINITY developers - we’ve successfully updated the metadata on our Windows XP contract, and the logo is now live! :raising_hands:

We used release version 794fc5b9.

4 Likes