Read+write canister wasm module metadata

Developers
1

I’m having a look at the README of ic-wasm.

Do I understand correctly that I can add or overwrite any kind of custom metadata to a wasm module?

Like:

$ ic-wasm input.wasm -o output.wasm metadata hello:world -d "that's my metadata info" -v public

If so, once deployed on a local replica or mainnet, is there a way to read this metadata from a dapp (frontend), e.g. using agent-js?

2 Likes
2

Yes, the metadata section can be customized with arbitrary sub-sections (private or public); beyond that, I’m not aware of any standard being enforced for which metadata subsections. (Some tools, e.g., DFX, seem to be creating their own metadata standard within a particular metadata subsection, e.g. icp:public dfx, followed by a string in JSON notation).

Speaking of DFX, it has a nice feature for reading the metadata section of a deployed canister, e.g., the following git_commit_id metadata sub-section:

dfx canister --network ic metadata $CANISTER git_commit_id

I’m pretty sure one could read the metadata via an agent library, but I’ve not tried that with agent-js.

Note that a matadata section of a compressed (gzipped) WASMs is itself not compressed.

A great metadata entry that I would recommend to add to any canister is candid:service, pointing to the canister’s Candid definition.

3 Likes
3

Thanks for the answer and confirmation. Is there is any limitation such as size or types? Any specification available somewhere?

That’s the second important aspect of my question. I would be really curious to know about this as it would be an interesting reason why I would foreseen the use of those metadata sections.

1 Like
4

You can define at most 16 metadata sections, and the combine content size cannot exceed 1M. See interface-spec/spec/index.md at master · dfinity/interface-spec · GitHub.

agent-js example: agent-js/e2e/node/basic/canisterStatus.test.ts at main · dfinity/agent-js · GitHub

4 Likes
5

That’s great, thanks for the answer and links.

@aterga mentionned that dfx seem to be creating particular metadata, so it’s 16 counting does already used by dfx or it’s minus those? if minus, do we know how many sections dfx is using?

Do I get it right, the argument paths should then be used as the key?

e.g. given a public metadata “hello:world”

$ ic-wasm input.wasm -o output.wasm metadata hello:world -d "that's my value" -v public

I would query it as following:

const request = await CanisterStatus.request({
      canisterId: Principal.from(counterObj.canisterId),
      agent,
      paths: ['hello:world'],
    });

Correct?

6

Yes, metadata made by dfx are counted towards the 16 limit. I think you can opt-out this behavior in dfx.json. I think dfx only add 2-3 metadata sections. You can check it by running ic-wasm a.wasm metadata to list all metadata in a wasm binary.

Do I get it right, the argument paths should then be used as the key?

Most likely, but better to check with the documentation. There are some options to config the output type, here is another example: candid/tools/ui/src/candid.ts at master · dfinity/candid · GitHub

2 Likes
7

Thanks for the details, looks promising!

1 Like
8

You can also configure metadata in dfx.json. Here’s the documentation: sdk/docs/concepts/canister-metadata.md at master · dfinity/sdk · GitHub

1 Like