Skip to content

Latest commit

 

History

History
121 lines (94 loc) · 3.21 KB

canister-metadata.md

File metadata and controls

121 lines (94 loc) · 3.21 KB
Raw

Canister Metadata

Overview

Canisters can store custom metadata, which is available from the state tree at /canister/<canister id>/metadata/<name>.

You can configure this metadata in dfx.json, per canister, in the metadata array.

Here is a simple example:

{
  "canisters": {
    "app_backend": {
      "main": "src/app_backend/main.mo",
      "type": "motoko"
    },
    "app_frontend": {
      "dependencies": [
        "app_backend"
      ],
      "frontend": {
        "entrypoint": "src/app_frontend/src/index.html"
      },
      "source": [
        "src/app_frontend/assets",
        "dist/app_frontend/"
      ],
      "type": "assets",
      "metadata": [
        {
          "name": "alternative-domains",
          "visibility": "public",
          "path": "src/app_frontend/metadata/alternative-domains.cbor"
        }
      ]
    }
  },
  "version": 1
}

Fields

The JSON schema also documents these fields.

name

A string containing the name of the wasm section.

visibility

A string containing either private or public (the default).

Anyone can read the public metadata of a canister.

Only a controller of the canister can read its private metadata.

It is not possible to define metadata with the same name with both private and public visibility, unless they are for different networks.

networks

An array of strings containing the names of the networks that this metadata applies to.

If this field is absent, it applies to all networks.

If this field is present as an empty array, it does not apply to any networks.

If dfx.json contains more than one metadata entry with a given name, dfx will use the first entry that matches the current network and ignore any that follow.

path

A string containing the path of a file containing the wasm section contents.

The candid:service metadata

Dfx automatically adds candid:service metadata, with public visibility, for Rust and Motoko canisters.

You can, however, override this behavior by defining a metadata entry with "name": "candid:service". You can change the visibility or the contents.

For Motoko canisters, if you specify a path for candid:service metadata (replacing the candid:service definition generated by moc), dfx will verify that the candid:service definition you provide is a valid subtype of the definition that moc generated.

A more complex example

In this example, we change the visibility of the candid:service metadata on the ic and staging networks to private, but leave it public for the local network.

{
  "canisters": {
    "app_backend": {
      "main": "src/app_backend/main.mo",
      "type": "motoko",
      "metadata": [
        {
          "name": "candid:service",
          "networks": [ "ic", "staging" ],
          "visibility": "private"
        },
        {
          "name": "candid:service",
          "networks": [ "local" ],
          "visibility": "public"
        }
      ]
    },
    "app_frontend": {
      "dependencies": [
        "app_backend"
      ],
      "frontend": {
        "entrypoint": "src/app_frontend/src/index.html"
      },
      "source": [
        "src/app_frontend/assets",
        "dist/app_frontend/"
      ],
      "type": "assets"
    }
  },
  "version": 1
}