docs(ICRC_Ledger): FI-1621: Add docs on changing ledger token metadata (

#3947) * Add docs on changing ledger token metadata * Apply suggestions from code review Co-authored-by: Jessie Mongeon <[email protected]> --------- Co-authored-by: Jessie Mongeon <[email protected]>
dfinity · Jan 21, 2025 · f187fed · f187fed
1 parent 6850de2
commit f187fed
Showing 1 changed file with 25 additions and 0 deletions.
diff --git a/docs/developer-docs/defi/tokens/create.mdx b/docs/developer-docs/defi/tokens/create.mdx
@@ -153,6 +153,31 @@ If you want to deploy your ICRC-1 token on the mainnet, follow these steps:
 
 - Be sure that your ledger canister has cycles attached to the `create_canister` messages, using the `cycles_for_archive_creation`.
 
+## Changing your token metadata
+
+:::info
+The initialization and upgrade arguments of the ICRC-1 ledger are not specified in the [standard](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md). Thus, the arguments defined in this section are dependent on the reference implementation of the ICRC-1 ledger. If you build your own ICRC-1 ledger, you may use different initialization arguments.
+:::
+
+Token metadata, such as the token name, symbol, and logo, is set using the [`InitArgs`](https://github.com/dfinity/ic/blob/ad6df00098cf25d8df29a469c0a4504979a411c1/rs/ledger_suite/icrc1/ledger/src/lib.rs#L253-L266) when the ledger is installed.
+This metadata can subsequently be changed using the [`UpgradeArgs`](https://github.com/dfinity/ic/blob/ad6df00098cf25d8df29a469c0a4504979a411c1/rs/ledger_suite/icrc1/ledger/src/lib.rs#L324-L342) when the ledger is upgraded.
+Note that such an upgrade can also be performed by upgrading the ledger canister to the same Wasm that it is currently running, which results in the metadata being changed, but the functional behavior of the ledger otherwise remaining the same.
+
+The reference implementation of the ICRC-1 ledger interprets some metadata, whereas other metadata is simply stored and returned in the response to an `icrc1_metadata` query.
+The former covers the following:
+
+- The token name.
+
+- The token symbol.
+
+- The number of decimals.
+
+- The transaction fee.
+
+The above values should be set using the explicitly provided fields in the `InitArgs` or `UpgradeArgs`, for canister installs or upgrades, respectively, e.g., the `token_symbol` field for setting the token symbol.
+Other metadata, such as the token logo, should be set as `(key, value)` pairs in the `metadata` `Vec`.
+The format **should** follow what is specified in the [standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1#metadata), e.g., for the token logo, the metadata key should be `icrc1:logo`.
+
 ## Next steps
 
 [Learn how to interact with the ICRC-1 ledger](./ledger/usage/icrc1_ledger_usage.mdx)