Skip to content

Latest commit

 

History

History
206 lines (162 loc) · 4.98 KB

canister-metadata.md

File metadata and controls

206 lines (162 loc) · 4.98 KB

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. Conflicts with "content".

content

A string containing the wasm section content directly. Conflicts with "path".

Canister Metadata Standard

Contents should be valid UTF-8 text.

candid:args

Parsed with candid:service to get the init arguments type of the canister.

candid:service

The candid interface of the canister which excludes the init arguments type.

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.

dfx

A json text for dfx usage. It consists of independent optional objects.

pullable

The pullable object is necessary for the canister to be pullable.

Check pull-dependencies for more details of each field and how to set it in dfx.json.

{
  "pullable": {
    "wasm_url": "http://example.com/a.wasm",
    "wasm_hash": "d180f1e232bafcee7d4879d8a2260ee7bcf9a20c241468d0e9cf4aa15ef8f312",
    "dependencies": [
      "yofga-2qaaa-aaaaa-aabsq-cai"
    ],
    "init_guide": "A natural number, e.g. 10."
  }
}

tech_stack

The tech_stack object provides a standard format to show the technologies involved to build the canister.

Check tech-stack for more details and how to set it in dfx.json.

{
  "tech_stack": {
    "language": {
      "rust": {
        "version": "1.75.0"
      }
    },
    "cdk": {
      "ic-cdk": {
        "version": "0.13.0"
      }
    },
    "lib": {
      "ic-cdk-timers": {},
      "ic-stable-structures": {}
    },
    "other": {
      "bitcoin": {
        "address": "bcrt1qfe264m0ycx2vcqvqyhs0gpxk6tw8ug6hqeps2d"
      }
    },
    "tool": {
      "dfx": {}
    }
  }
}

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",
      "dependencies": [
        "dep1",
        "dep2"
      ],
      "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"
    },
    "dep1": {
      "type": "pull",
      "id": "rrkah-fqaaa-aaaaa-aaaaq-cai"
    },
    "dep2": {
      "type": "pull",
      "id": "ryjl3-tyaaa-aaaaa-aaaba-cai"
    }
  },
  "version": 1
}