Skip to main content

3. Using third-party canisters

Third-party canisters are canisters that provide a public service at a static canister ID. Some examples are the DFINITY NNS and Internet Identity canisters, but third-party canisters can also be made by community developers. Using third-party canisters can be a good way to add additional functionalities to your dapp. For example, by integrating the Internet Identity canister into your dapp, you can enable identity and authentication for the users of your application.

dfx enables a dependency workflow, where a canister can be configured to pull third-party canisters that it depends on into the local environment. This can be useful for developers who are looking to test the accuracy of their integration with the third-party canister and perform tests without paying cycles or using production environments. It also drastically simplifies the local deployment of canisters like the II canister, since you don't need to obtain the Wasm and Candid files for the canisters yourself - dfx takes care of it in the background for you.

In this tutorial, you'll be focusing on pulling third-party canisters. If you're interested in developing third-party canisters that can be pulled by other developers, check out the documentation on dfx deps.

Pulling third-party canister dependencies​

Let's take a look at a basic example of pulling a third-party canister as a dependency. To do this, you'll use the dfx deps command, which is the dfx subcommand responsible for pulling canisters that are listed as dependencies of another canister in the project's dfx.json file.

Prerequisites​

Before you start, verify that you have set up your developer environment according to the instructions in 3 Developer environment setup.

Creating a new project​

To get started, create a new project in your working directory. Open a terminal window, navigate into your working directory (developer_journey), then use the commands:

Use npx azle new <project_name> to create a new project and navigate into the project directory:

npm install
dfx start --clean --background

Then, create a new project called dependencies and nagivate into the new project directory:

npx azle new dependencies
cd dependencies
npm install

You'll use the default 'Hello world' project in this example, then you'll pull the Internet Identity canister as a dependency of our backend canister.

First, open the dfx.json file in your project's directory. You need to configure your backend canister to have the dependencies of internet_identity, with canister ID rdmx6-jaaaa-aaaaa-aaadq-cai on the mainnet. This is the canister ID of the DFINITY canister used to interact with ICP's identity and authentication product called Internet Identity. The developer journey will dive deeper into II in a later tutorial; for now, you'll just use it to demonstrate how third-party canisters can be used. You can do so by editing our dfx.json file to reflect the following configuration:

{
  "canisters": {
    "backend": {
      "type": "custom",
      "main": "src/backend/index.ts",
      "dependencies": ["internet_identity"],
      "candid": "src/backend/index.did",
      "candid_gen": "http",
      "build": "npx azle backend",
      "wasm": ".azle/backend/backend.wasm",
      "gzip": true,
      "assets": [["src/frontend/dist", "dist"]],
      "build_assets": "npm run build",
      "metadata": [
        {
          "name": "candid:service",
          "path": "src/backend/index.did"
        },
        {
          "name": "cdk:name",
          "content": "azle"
        }
      ]
    },
    "internet_identity": {
      "type": "pull",
      "id": "rdmx6-jaaaa-aaaaa-aaadq-cai"
    }
  }
}

Next, run the dfx deps pull command:

dfx deps pull

By running this command, the following steps are executed:

  • First, the dependency canister is fetched and the Wasm for it is downloaded.

  • Then, the hash of the downloaded Wasm is verified against the hash of the deployed canister on the mainnet.

  • Next, a series of information is extracted from the downloaded Wasm file, such as the dfx metadata and Candid information.

The deps/ folder is also created in your project's root folder. The deps/pulled.json file will contain all major information regarding the project's dependencies. In this example, the deps/pulled.json file should resemble the following:

{
  "canisters": {
    "rdmx6-jaaaa-aaaaa-aaadq-cai": {
      "name": "internet_identity",
      "wasm_hash": "83aec6c49dc5b7e4112ca2b45a0093da4e68fa88c69c4d2810fd917a241cda1f",
      "wasm_hash_download": "83aec6c49dc5b7e4112ca2b45a0093da4e68fa88c69c4d2810fd917a241cda1f",
      "init_guide": "Use '(null)' for sensible defaults. See the candid interface for more details.",
      "init_arg": null,
      "candid_args": "(opt InternetIdentityInit)",
      "gzip": true
    }
  }
}

Using dfx deps​

Next, you'll set the init arguments for the dependency canisters using the dfx deps init command. An init argument is an argument that will be passed to the canister when it is deployed. This command will iterate over all listed dependencies in the pulled.json file and set an empty argument for any that do not require an init argument. For those that require an init argument, they will be returned so that they can be set manually. Run the command:

dfx deps init

Now it's time to deploy our pulled dependency canister. Run the command:

dfx deps deploy

Lastly, let's deploy our project all together with the dfx deploy command:

dfx deploy

The output will include a local Candid UI URL for both the backend canister, which has the default 'Hello world' code, and the local Candid UI URL for the Internet Identity canister.

Installing code for canister backend, with canister ID bkyz2-fmaaa-aaaaa-qaaaq-cai
Deployed canisters.
URLs:
  Backend canister via Candid interface:
    backend: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai
    internet_identity: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=rdmx6-jaaaa-aaaaa-aaadq-cai

Now, you can interact with the II canister locally using the CLI or the Candid UI. In a future tutorial you'll integrate your backend canister with the II canister. For now, that'll wrap up this module.

Need help?​

Did you get stuck somewhere in this tutorial, or feel like you need additional help understanding some of the concepts? The ICP community has several resources available for developers, like working groups and bootcamps, along with our Discord community, forum, and events such as hackathons. Here are a few to check out:

Next steps​

Next, let's take a deeper dive into an introduction of Candid and the role that it plays in development on ICP.