Skip to main content

Control

Beginner
Concept

Overview​

A canister is managed by a list of controllers. A controller is specified by a principal, which can be self-authenticating, e.g. a dfx developer identity, or another canister. Canisters can have multiple controllers where each has the same administrative rights, or it can have no controller, in which case the canister becomes immutable (blackholed) and cannot be upgraded or deleted.

Setting the controllers of a canister​

When a canister is created, the default controller list contains the developer identity used to create the canister. Additional controllers can be specified during canister creation or they can be added in the future.

To specify a different controller upon canister creation, the dfx canister create --controller <controller> command can be used.

To update a canister's controllers after the canister has been created, the dfx canister update-settings command can be used with the --add-controller <controller> or --remove-controller <controller> flag to add or remove controllers respectively.

Actions available only to controllers​

  • Stopping and starting the canister.
  • Installing code in the canister.
  • Upgrading the canister.
  • Getting the status of the canister which includes its cycles balance, memory usage, and list of controllers.
  • Deleting the canister.
  • Updating settings like the freezing threshold, resource allocation, and controllers.

Common control models​

Developer or team of developers​

A canister is controlled by a single developer or a team of developers. Each developer has the same administrative rights over the canister. This is the most common control model for canisters in early development stages. This model can be made more secure by using a Hardware Security Module (HSM) to store the private key of the developer identity.

MultiSig​

A canister is controlled by a multi-signature canister. The multi-signature canister is controlled by a list of developers and requires a threshold number of signatures to perform administrative actions on the canister. This model is more secure than the single developer model, as it requires multiple developers to agree on an action before it can be performed.

A canister that can be used for this purpose is the Threshold canister.

Launchtrail​

The Launchtrail canister can be used to schedule the upgrade of a canister at a future time to give the public enough time to review the proposed changes. The canister also keeps a complete record of all actions and their execution results. The Launchtrail canister itself should be immutable without a controller.

Decentralized autonomous organization (DAO)​

A canister is controlled by a DAO, and all upgrades and administrative actions are decided by a vote of the DAO members. The most common DAO model for applications on the Internet Computer is the Service Nervous System (SNS).

The system canisters on ICP are controlled by the Network Nervous System (NNS) root canister, which allows administration of the canisters by NNS proposals.

Developers can also add the NNS root canister as a controller of their canister, to enable recovery of the canister by NNS proposal if other control methods are lost.

No controller​

A canister has no controller and is immutable. On ICP, this model is often called a blackholed canister. This is the model used by smart contracts on Ethereum.

Common errors related to controllers include: