# \[RFC\] Canister Metadata Standard **URL:** \ **Category:** Developers\ **Created:** [October 31, 2022, 4:54pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280 "2022-10-31T16:54:21Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![lwshang](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lwshang/32/3394_2.png) [@lwshang](https://forum.dfinity.org/u/lwshang)\ **Post date:** [October 31, 2022, 4:54pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/1 "2022-10-31T16:54:22Z")
# Objective The goal of developing Canister Metadata Standard is to improve the experience of integrating third party canisters. A service provider make its canister compliant with the standard. Then a consumer can easily pull the canister from the mainnet and set it up locally. # Background ## What is Canister Metadata? Canister is simply a Wasm module. Developer can add arbitrary data to a custom section of the Wasm module. Then the data can be fetched from the `metadata` path in system state tree. For more details, please check [this section](https://internetcomputer.org/docs/current/references/ic-interface-spec/#state-tree-canister-information) in IC specification. ## Why we need a standard? We plan to provide a complete workflow of third party canister integration for both service provider and consumer. Canister metadata is suitable for communication between the two parties. The consumer can understand the provider only if they speak “the same language” which is the standard we are proposing. ## How will the standard be executed？ In short, `dfx` will handle it. A service provider explicitly opt in this standard by declaring necessary metadata value in `dfx.json`. Then `dfx` will write metadata in the standard format into Wasm module custom section. When install canister, `dfx` will check if the metadata are complaint with the standard in case the developer modify metadata outside `dfx`. A service consumer, declare dependency canister ID in `dfx.json`, then `dfx` will request the metadata on-chain and setup the dependency canister locally. # Proposal Before the standard details, I want to state several principles for it: 1. Less is more 2. No obvious interference with other metadata use cases 3. Consider future evolvement The canister metadata can be viewed as key-value pairs. For simplicity, we only allow valid UTF-8 text in both key and pair. To avoid name conflicts, we prefix the keys with `dfx:`. And all metadata in this standard must have public visibility so that everyone can fetch them. ### `dfx:wasm_url` A URL to download canister Wasm module which will be deployed locally. Service provider is responsible for hosting the resource online. When consumer pull the canister, `dfx` will check if downloaded wasm hash match on-chain version. If not, a warning message will be shown. > We expect that it will be possible to download canister Wasm directly from IC itself. Then this metadata won’t be required. ### `dfx:deps` A list of `name:ID` pairs of direct dependencies separated by semicolon. This metadata helps resolve transitive dependencies recursively. For example, if the canister directly depends on: - `ledger` canister with mainnet ID `bbbbb-bb`; - `dex` canister with mainnet ID `ccccc-cc`; Then the value should be: `ledger:bbbbb-bb;dex:ccccc-cc`; ### `dfx:init` A message to guide consumers how to initialize this canister. If it is simple to initialize, the message can be just the command to be executed. If it is complicated, the message can be a URL point to the page with detailed initialization process. ### `candid:service` The canister interface in candid. `dfx` has supported automatically adding `candid:service` metadata. If service provider opt in this standard, this metadata is required to be public. # What next? We look forward to any comments, questions or feedbacks from the community. Please note that we are not proposing any new feature to Internet Computer itself. Instead, we are developing a recommended standard for the applications (canisters) on IC. And `dfx` will only write these metadata if the provider opt in this approach. We will stick to current design of the framework. Any suggestion on the details are welcome. After a short RFC period, we will put this standard in `sdk` repo and start implementation soon. ### `dfx.json` preview This is just a demo for how would provider/consumer write `dfx.json` to interact with canister metadata. It is not a part of the standard. Provider: ```json { "canisters": { "provider_app": { ..., "pull": { "wasm_url": "https://example.com/app.wasm.gz", "init": "https://example.com/readme.md" }, "dependencies": [ "ledger", "dex" ] }, "ledger": ..., "dex": ..., } } ``` Consumer: ```json { "canisters": { "app": { ..., "dependencies": [ "provider_app" ] }, "provider_app": { type: "pull", id: "ddddd-dd", } } } ``` ---
**Author:** ![domwoe](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/domwoe/32/5165_2.png) [@domwoe](https://forum.dfinity.org/u/domwoe)\ **Post date:** [November 2, 2022, 7:12am UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/2 "2022-11-02T07:12:04Z")
Thank you @lwshang. Given that devs are not dependent on `dfx` to set metadata but can also use tools like [ic-wasm](https://github.com/dfinity/ic-wasm) to add custom sections, this would benefit from a public registry to register/announce namespaces. ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [March 14, 2023, 7:35pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/3 "2023-03-14T19:35:24Z")
Demergent Labs is very interested in this. I would like to propose a `cdk` key-value pair. To keep it simple and avoid possible security implications with revealing too much information (such as a version), `cdk` could simply be the name of the CDK. Or, `cdk` could be a prefix like follows: `cdk:name`: The name of the CDK `cdk:version`: The version of the CDK One key use-case that we have in mind is for canister indexing services like `icscan` or the `IC dashboard` to allow totals and filtering of canisters by cdk name. Then we could know exact numbers of Rust, Motoko, Python, TypeScript, C++, etc canisters on the IC. ---
**Author:** ![domwoe](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/domwoe/32/5165_2.png) [@domwoe](https://forum.dfinity.org/u/domwoe)\ **Post date:** [March 22, 2023, 2:43pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/4 "2023-03-22T14:43:59Z")
@lwshang Are there any news about this and the integration in dfx? We revisited this in a twitter thread as a way to link to the source code from a canister. > ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [May 8, 2023, 10:51pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/5 "2023-05-08T22:51:58Z")
I would like to propose the following (updating my thoughts from a couple comments back): # cdk:name This is the name of the CDK that was used to produce the canister’s Wasm module binary e.g. `motoko`, `cdk-rs`, `azle`, `kybra`, `icpp`. # cdk:languages This is a list of strings indicating the source code languages that the CDK supports e.g. `motoko`, `rust`, `typescript;javascript`, `python`, `c++` # cdk:version This is the version of the CDK that was used to produce the canister’s Wasm module binary e.g. `1.2.3`, `0.16.2`, `2.3` ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [June 5, 2023, 4:33pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/6 "2023-06-05T16:33:46Z")
Any updates on pushing these standards forward? ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [June 5, 2023, 4:34pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/7 "2023-06-05T16:34:17Z")
Should these be ICRC standards? ---
**Author:** ![bitdivine](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/bitdivine/32/246_2.png) [@bitdivine](https://forum.dfinity.org/u/bitdivine)\ **Post date:** [June 6, 2023, 2:15pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/8 "2023-06-06T14:15:23Z")
Do we need a standard? AI will watch us all writing our code and tab completion will steer us towards a convention. 😉 ---
**Author:** ![bitdivine](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/bitdivine/32/246_2.png) [@bitdivine](https://forum.dfinity.org/u/bitdivine)\ **Post date:** [June 6, 2023, 2:17pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/9 "2023-06-06T14:17:33Z")
On a more serious note, maybe it just needs the cdk developers to reach a consensus on the cdk: metadata namespace. So, you, the motoko team and so on. Is there a IC cdk developers forum somewhere? ---
**Author:** ![bitdivine](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/bitdivine/32/246_2.png) [@bitdivine](https://forum.dfinity.org/u/bitdivine)\ **Post date:** [June 6, 2023, 2:25pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/10 "2023-06-06T14:25:59Z")
Personally I would be interested in expanding the detail of the `init` metadata. For me, the init args consist of feature flags and canister IDs. Can we have a convention by which init args are tuples and the second entry in the tuple is a map from canister names to IDs? That way the init argument can be made for all the canisters I work with in a standardized way. I am aware that this makes the rather crude assumption that for every name, there is just one canister ID, and that assumption doesn’t scale well. But this is a start. ---
**Author:** ![ZenVoich](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/zenvoich/32/5969_2.png) [@ZenVoich](https://forum.dfinity.org/u/ZenVoich)\ **Post date:** [September 4, 2023, 7:17pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/11 "2023-09-04T19:17:44Z")
> [@lastmjs](#): > > # cdk:name > > This is the name of the CDK that was used to produce the canister’s Wasm module binary e.g. `motoko`, `cdk-rs`, `azle`, `kybra`, `icpp`. Would love to see support for `cdk:name` ---
**Author:** ![bitdivine](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/bitdivine/32/246_2.png) [@bitdivine](https://forum.dfinity.org/u/bitdivine)\ **Post date:** [September 7, 2023, 8:52am UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/12 "2023-09-07T08:52:56Z")
Another thing that would be nice to standardize: **infrastructure:canister\_name** and **infrastructure:path** E.g. if I have an app with 3 canisters, and a couple of deployments of this app, I would have 6 canisters in total, with deployment and names that might be: - name= **my-dapp** and path= **test\_deployment/my-dapp** - name= **backend** and path= **test\_deployment/my-backend** - name= **my-archive** and path=**test\_deployment/my-archive[0]** - name= **my-dapp** and path= **prod/my-dapp** - name= **my-backend** and path= **prod/my-backend** - name= **my-archive** and path=**prod/my-archive[0]** Regarding name: A key motivation here is to reduce the risk of deploying the wrong wasm to a canister. If it is really easy to get names, we reduce the risk of error. We might even have a pre-upgrade check that refuses an upgrade request if names don’t match. Regarding ID: The motivation here is to have a structured way of distinguishing identical canisters, for the cases when there are multiple deployments of the same canister for any reason. Given two canisters with the same name, the deployment path, like a terraform path, makes it clear how that canister fits in to the rest of the infrastructure. Regarding both: It would be nice to get feedback from infra people, who have a lot of experience managing large terraform, ansible, cloudformation and other deployments. Not everything from the centralized world will apply to blockchain but I expect that some lessons will be transferrable. ---
**Author:** ![bitdivine](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/bitdivine/32/246_2.png) [@bitdivine](https://forum.dfinity.org/u/bitdivine)\ **Post date:** [September 7, 2023, 9:01am UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/13 "2023-09-07T09:01:34Z")
For metadata to be useful, it helps for it to be widespread, and for it to become widespread, it helps for it to be there by default, and for a standard to be there by default it helps to have it in tooling, and tooling is built on standards. Some things like `cdk:name` and `deployment:name` are information that tools such as dfx have already, so it feels as if the work needed to go from idea to widespread use is quite small. ---
**Author:** ![ZenVoich](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/zenvoich/32/5969_2.png) [@ZenVoich](https://forum.dfinity.org/u/ZenVoich)\ **Post date:** [October 19, 2023, 6:17am UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/14 "2023-10-19T06:17:16Z")
@lastmjs hi, I would like to count Azle/Kybra canisters too on [https://icp.zone](https://icp.zone) ([forum post](https://forum.dfinity.org/t/introducing-icp-zone-fancy-ic-stats/23371)) Currently I check if `motoko:compiler` custom section is presented(although it is private). What if Azle/Kybra will fill `azle:compiler` and `kybra:compiler` custom sections until `cdk:name` is standardized? ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [October 19, 2023, 1:56pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/15 "2023-10-19T13:56:54Z")
Is there a problem with just checking cdk:name even before it is standardized? Seems like it shouldn’t be too complicated? I’m currently waiting for dfx extensions to be implemented and testable before really putting the metadata infrastructure in place. ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [October 19, 2023, 1:58pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/16 "2023-10-19T13:58:21Z")
This seems very exciting though, if we put the metadata in place for Azle and Kybra, how much effort/how long before icp.zone could pick everything up? ---
**Author:** ![ZenVoich](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/zenvoich/32/5969_2.png) [@ZenVoich](https://forum.dfinity.org/u/ZenVoich)\ **Post date:** [October 19, 2023, 2:06pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/17 "2023-10-19T14:06:27Z")
> [@lastmjs](#): > > Is there a problem with just checking cdk:name even before it is standardized? Seems like it shouldn’t be too complicated? Yes, that’s even better. Will require only one request instead of many for each cdk > [@lastmjs](#): > > This seems very exciting though, if we put the metadata in place for Azle and Kybra, how much effort/how long before icp.zone could pick everything up? I don’t think it should be difficult, a few days maybe… ---
**Author:** ![lastmjs](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/lastmjs/32/3406_2.png) [@lastmjs](https://forum.dfinity.org/u/lastmjs)\ **Post date:** [October 19, 2023, 2:21pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/18 "2023-10-19T14:21:26Z")
Great, I’ll let you know then ---
**Author:** ![icpp](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/icpp/32/9310_2.png) [@icpp](https://forum.dfinity.org/u/icpp)\ **Post date:** [October 19, 2023, 10:52pm UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/19 "2023-10-19T22:52:21Z")
Same for icpp, the C++ CDK. We have dfx integrated now as a default post processing step during a build and can use it too for creating the custom section. ---
**Author:** ![ZenVoich](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/zenvoich/32/5969_2.png) [@ZenVoich](https://forum.dfinity.org/u/ZenVoich)\ **Post date:** [February 1, 2024, 6:09am UTC](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280/20 "2024-02-01T06:09:22Z")
I would love to count canisters on different languages to show on icp.zone. Any progress on supporting `cdk:name` in Azle/Kybra @lastmjs? In C++ CDK @icpp? Would helpful if Dfinity also will add support for this metadata section for Motoko/Rust canisters too(idk who to mention @domwoe @Vivienne) For now I make distinction between rust and motoko canisters by trying to get `motoko:compiler` section, which is hacky. Also, this section should be filled for dynamically spawned canisters from the parent canister, right? [Next page](https://forum.dfinity.org/t/rfc-canister-metadata-standard/16280.md?page=2)