From 147b3cf7f195134558ea9102aaf4560b6345eb1d Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Thu, 22 Jun 2023 15:55:39 -0500 Subject: [PATCH 01/16] Create sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 166 ++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md new file mode 100644 index 0000000000..956d555ace --- /dev/null +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -0,0 +1,166 @@ +# SNS asset canisters + +## Overview + +The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister) provides users with a way to store and retrieve static assets from a canister deployed on the IC. Generally, asset canisters are used to serve HTML, CSS, or JavaScript assets, which are typically part of an application's frontend. For this reason, the asset canister is also referred to as the frontend canister. For purposes of this guide, we'll refer to it as the asset canister. + +The asset canister of an SNS serves the frontend assets related to the SNS. The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be approved on via an SNS proposal. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. + + +/// Explain how the asset canister interacts with the SNS, including how it must be change before launch and how it can be adjusted after the launch (set permissions) +/// Link to into how the relevant proposals can be sent / how the assets can be updated + +This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. + +:::info +Note that you can interleave the steps for the asset canister from this section and the steps for the test canister (and also your own canister) within the SNS lifecycle. We list additional constraints in between the steps below. +::: + +## Deploying an asset canister + +To deploy an asset canister, the `./deploy_assets.sh` script found in the [SNS testing repo](https://github.com/dfinity/sns-testing) can be used. + +Then, the SNS can be deployed using the `./deploy_sns.sh ` script. After the SNS has been deployed, the following steps can be used to prepare the SNS canister for being handed off to the SNS: + +:::info +These steps should be run before the `open_sns_swap.sh` script is run according to the SNS lifecycle section. +::: + +- #### Step 1: To prepare the asset canister, run the following script: + +``` +./prepare_assets.sh +``` + +This grants the SNS governance canister the necessary permissions to manage access to the asset canister. + +- #### Step 2: Next, register the asset canister with the SNS by running the following script: + +``` +./register_dapp.sh +``` + +where is the canister ID of the asset canister. + +- #### Step 3: Then, register the SNS's managing permissions. +To test managing permissions in the asset canister via SNS proposals, you need to register the asset canister's functions to manage permissions with the SNS as generic functions. This is accomplished by running the following script: + +``` +./register_permission_assets.sh. +``` + +Now you can add or revoke a permission to the asset canister via SNS proposals. To this end, run the script: + +``` +./add_permission_assets.sh +``` + +or + +``` +./revoke_permission_assets.sh +``` + +respectively, where is the name of an identity to manage permissions for and is one of Commit, Prepare, and ManagePermissions. You can check the actual permissions by running: + +``` +dfx canister --network ${NETWORK} call assets list_permitted '(record {permission = variant {}})' +``` + +or by running the script: + +``` +./get_permission_assets.sh. +``` + +- #### Step 4: Make sure that you can still commit assets by running the script: + +``` +./commit_assets.sh +``` + +where is the HTTP path of the asset, e.g., `/myasset.txt` and is the ASCII-encoded content of the asset. + + +- #### Step 5: Testing all possible SNS launch scenarios includes testing a failed swap (e.g., if not enough funds have been raised) where the control of the asset canister is given back to your principal. + +You should run the following step after `finalize_sns_swap.sh` for an unsuccessful swap: + + - After a failed swap, you can run the script: + + ``` + ./take_ownership_assets.sh + ``` + + to reset the permissions of the asset canister back to only your principal having the Commit permission (in particular, with the SNS governance having no permission anymore). + + + + +## Submitting a proposal + +Imagine a scenario where you'd like to upload a frontend file to the SNS's asset canister. To do this, the governance canister must call the asset canister to upload the file. + +- #### Step 1: To get the governance canister to call the asset canister, we first make the proposal to `AddGenericNervousSystemFunction`, which is like adding a new proposal type that uploads files to the asset canister. + +- #### Step 2: Next, we can make an ExecuteGenericNervousSystemFunction proposal that will make the governance-canister call the asset-canister’s store method with a payload of the frontend asset Candid parameter for the ‘store’ method. + +- #### Step 3: Then, submit a new AddGenericNervousSystemFunction SNS Proposal to support the `commit_proposed_batch` API. + +The target canister id should be the asset canister (that is upgraded in the below upgrade steps) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. + +Submit an ExecuteNervousSystemFunction SNS Proposal with the output from: + +``` +dfx deploy --network ic --by-proposal +``` + +See the below upgrade steps for more information. + +## Upgrade steps + +- #### Step 1: Upgrade the asset canister (by proposal, as with any other canister) to the asset canister wasm bundled with dfx 0.14.1, available [here](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). + +- #### Step 2: After upgrading the asset canister by proposal, have someone with Prepare permission run: + +``` +dfx deploy --network ic --by-proposal +``` + +The output will contain something like this: + +``` +Proposed commit of batch 2 with evidence e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Either commit it by proposal, or delete it. +``` + +- #### Step 3: Save the batch number and the evidence value for use with the asset canister API. + +- #### Step 4: To ensure that others would be able to verify the evidence in the proposal, have someone else clone the dapp repo and run: + +``` +dfx deploy --network ic --compute-evidence +``` + +The computed evidence should match the evidence from step 2. + +- #### Step 5: Submit a new proposal to commit the batch, using the ‘New Canister APIs’ above. + +## Asset canister examples + +An example of an SNS asset canister is canister `sqbzf-5aaaa-aaaam-aavya-cai`, which is an asset canister part of the [Dragginz Dapp SNS](https://dashboard.internetcomputer.org/canister/sqbzf-5aaaa-aaaam-aavya-cai). + +By viewing the above asset canister, you can view example method that can be used to add, remove, or change assets. + +The following is an example of a simple 'store' method: + +``` +// Single call to create an asset with content for a single content encoding that +// fits within the message ingress limit. + store: (record { + key: Key; + content_type: text; + content_encoding: text; + content: blob; + sha256: opt blob + }) -> (); +``` From 6a4d66c24394381bdc3036c88572611739e0d8db Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Thu, 22 Jun 2023 15:56:16 -0500 Subject: [PATCH 02/16] Update sidebars.js --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index ce8d5a7b10..8bfeb4cede 100644 --- a/sidebars.js +++ b/sidebars.js @@ -454,6 +454,7 @@ const sidebars = { items: [ "developer-docs/integrations/sns/managing-sns/sns-governance", "developer-docs/integrations/sns/managing-sns/cycles-usage", + "developer-docs/integrations/sns/managing-sns/sns-asset-canister", ], }, ], From 8c7aa266d04c50eee43d39c2bf6c27c9f667e875 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Thu, 22 Jun 2023 16:06:05 -0500 Subject: [PATCH 03/16] Update sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 956d555ace..968cff09db 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -6,10 +6,6 @@ The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/fr The asset canister of an SNS serves the frontend assets related to the SNS. The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be approved on via an SNS proposal. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. - -/// Explain how the asset canister interacts with the SNS, including how it must be change before launch and how it can be adjusted after the launch (set permissions) -/// Link to into how the relevant proposals can be sent / how the assets can be updated - This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. :::info @@ -40,7 +36,7 @@ This grants the SNS governance canister the necessary permissions to manage acce ./register_dapp.sh ``` -where is the canister ID of the asset canister. +where `` is the canister ID of the asset canister. - #### Step 3: Then, register the SNS's managing permissions. To test managing permissions in the asset canister via SNS proposals, you need to register the asset canister's functions to manage permissions with the SNS as generic functions. This is accomplished by running the following script: @@ -61,7 +57,7 @@ or ./revoke_permission_assets.sh ``` -respectively, where is the name of an identity to manage permissions for and is one of Commit, Prepare, and ManagePermissions. You can check the actual permissions by running: +respectively, where `` is the name of an identity to manage permissions for and `` is one of Commit, Prepare, and ManagePermissions. You can check the actual permissions by running: ``` dfx canister --network ${NETWORK} call assets list_permitted '(record {permission = variant {}})' @@ -79,7 +75,7 @@ or by running the script: ./commit_assets.sh ``` -where is the HTTP path of the asset, e.g., `/myasset.txt` and is the ASCII-encoded content of the asset. +where `` is the HTTP path of the asset, e.g., `/myasset.txt` and `` is the ASCII-encoded content of the asset. - #### Step 5: Testing all possible SNS launch scenarios includes testing a failed swap (e.g., if not enough funds have been raised) where the control of the asset canister is given back to your principal. From 3864c1b4db621a0ce49a61b33724d5f82c98b75f Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Fri, 23 Jun 2023 10:18:03 -0500 Subject: [PATCH 04/16] Update sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 186 +++++++++--------- 1 file changed, 98 insertions(+), 88 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 968cff09db..86ffe4d6a3 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -2,122 +2,115 @@ ## Overview -The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister) provides users with a way to store and retrieve static assets from a canister deployed on the IC. Generally, asset canisters are used to serve HTML, CSS, or JavaScript assets, which are typically part of an application's frontend. For this reason, the asset canister is also referred to as the frontend canister. For purposes of this guide, we'll refer to it as the asset canister. +The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister) provides users with a way to store and retrieve static assets from a canister deployed on the IC. Generally, asset canisters are used to serve HTML, CSS, or JavaScript assets, which are typically part of a dapp's frontend. For this reason, the asset canister is also referred to as the frontend canister. For purposes of this guide, we'll refer to it as the asset canister. -The asset canister of an SNS serves the frontend assets related to the SNS. The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be approved on via an SNS proposal. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. +In the context of the SNS, a dapp's associated asset canister serves the frontend assets related to dapp and may also include a frontend to the SNS DAO, e.g., through which users can vote on governance proposals. -This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. - -:::info -Note that you can interleave the steps for the asset canister from this section and the steps for the test canister (and also your own canister) within the SNS lifecycle. We list additional constraints in between the steps below. -::: - -## Deploying an asset canister +The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a principal with the permission to do so. The SNS is the only one that can update the list of approved principals that have this permission, and any additions to this list approved on via an SNS proposal. This configuration assures that changes to the asset canister are only made by authorized principals that the SNS has agreed on through proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. -To deploy an asset canister, the `./deploy_assets.sh` script found in the [SNS testing repo](https://github.com/dfinity/sns-testing) can be used. +When a dapp's control is handed over to an SNS, this is also true for the associated asset canister. -Then, the SNS can be deployed using the `./deploy_sns.sh ` script. After the SNS has been deployed, the following steps can be used to prepare the SNS canister for being handed off to the SNS: +This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. -:::info -These steps should be run before the `open_sns_swap.sh` script is run according to the SNS lifecycle section. -::: +## Deploying an asset canister -- #### Step 1: To prepare the asset canister, run the following script: +To deploy an asset canister, first you will need an `assets.wasm.gz` file and a `candid/assets.did` file. Examples of these files can be downloaded with the commands: ``` -./prepare_assets.sh +curl -L "https://github.com/dfinity/sdk/raw/${DX_COMMIT}/src/distributed/assetstorage.wasm.gz" -o assets.wasm.gz +curl -L "https://raw.githubusercontent.com/dfinity/sdk/${DX_COMMIT}/src/distributed/assetstorage.did" -o candid/assets.did ``` -This grants the SNS governance canister the necessary permissions to manage access to the asset canister. - -- #### Step 2: Next, register the asset canister with the SNS by running the following script: +Next, you will need to configure your `dfx.json` file to specify your asset canister. An example `dfx.json` file can be found below: ``` -./register_dapp.sh +{ + "canisters": { + "nns-dapp": { + "type": "custom", + "candid": "", + "wasm": "nns-dapp.wasm" + }, + "internet_identity": { + "type": "custom", + "candid": "", + "wasm": "internet_identity.wasm" + }, + "sns_aggregator": { + "type": "custom", + "candid": "candid/sns_aggregator.did", + "wasm": "sns_aggregator.wasm" + }, + "test": { + "candid": "candid/test.did", + "type": "rust", + "package": "test" + }, + "assets": { + "build": "", + "candid": "candid/assets.did", + "type": "custom", + "wasm": "./assets.wasm.gz" + } + } +} ``` -where `` is the canister ID of the asset canister. +### Deploying locally -- #### Step 3: Then, register the SNS's managing permissions. -To test managing permissions in the asset canister via SNS proposals, you need to register the asset canister's functions to manage permissions with the SNS as generic functions. This is accomplished by running the following script: +To deploy your asset canister locally for testing purposes, the following command can be used: ``` -./register_permission_assets.sh. +dfx --provisional-create-canister-effective-canister-id deploy assets --network "local" --no-wallet ``` -Now you can add or revoke a permission to the asset canister via SNS proposals. To this end, run the script: +Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) -``` -./add_permission_assets.sh -``` +### Deploying on the mainnet -or +To deploy your asset canister to the mainnet, the following command can be used: ``` -./revoke_permission_assets.sh +dfx --provisional-create-canister-effective-canister-id deploy assets --network "IC" --wallet ``` -respectively, where `` is the name of an identity to manage permissions for and `` is one of Commit, Prepare, and ManagePermissions. You can check the actual permissions by running: +Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) -``` -dfx canister --network ${NETWORK} call assets list_permitted '(record {permission = variant {}})' -``` -or by running the script: +## Submitting an SNS proposal -``` -./get_permission_assets.sh. -``` - -- #### Step 4: Make sure that you can still commit assets by running the script: +The following asset canister APIs can be used within a proposal: ``` -./commit_assets.sh -``` - -where `` is the HTTP path of the asset, e.g., `/myasset.txt` and `` is the ASCII-encoded content of the asset. - - -- #### Step 5: Testing all possible SNS launch scenarios includes testing a failed swap (e.g., if not enough funds have been raised) where the control of the asset canister is given back to your principal. - -You should run the following step after `finalize_sns_swap.sh` for an unsuccessful swap: - - - After a failed swap, you can run the script: - - ``` - ./take_ownership_assets.sh - ``` - - to reset the permissions of the asset canister back to only your principal having the Commit permission (in particular, with the SNS governance having no permission anymore). - + type CommitProposedBatchArguments = record { + batch_id: BatchId; + evidence: blob; + }; + type ValidationResult = variant { Ok : text; Err : text }; + validate_commit_proposed_batch: (CommitProposedBatchArguments) -> (ValidationResult); + commit_proposed_batch: (CommitProposedBatchArguments) -> (); -## Submitting a proposal - -Imagine a scenario where you'd like to upload a frontend file to the SNS's asset canister. To do this, the governance canister must call the asset canister to upload the file. - -- #### Step 1: To get the governance canister to call the asset canister, we first make the proposal to `AddGenericNervousSystemFunction`, which is like adding a new proposal type that uploads files to the asset canister. - -- #### Step 2: Next, we can make an ExecuteGenericNervousSystemFunction proposal that will make the governance-canister call the asset-canister’s store method with a payload of the frontend asset Candid parameter for the ‘store’ method. - -- #### Step 3: Then, submit a new AddGenericNervousSystemFunction SNS Proposal to support the `commit_proposed_batch` API. +``` -The target canister id should be the asset canister (that is upgraded in the below upgrade steps) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. +An example can be found [here](https://github.com/dfinity/sdk/blob/master/e2e/tests-dfx/assetscanister.bash#L133). -Submit an ExecuteNervousSystemFunction SNS Proposal with the output from: +If the proposal is rejected, the preparer should use this new asset canister API: ``` -dfx deploy --network ic --by-proposal + type DeleteBatchArguments = record { + batch_id: BatchId; + }; + delete_batch: (DeleteBatchArguments) -> (); ``` -See the below upgrade steps for more information. -## Upgrade steps +## Submitting an SNS proposal and upgrading an asset canister -- #### Step 1: Upgrade the asset canister (by proposal, as with any other canister) to the asset canister wasm bundled with dfx 0.14.1, available [here](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). +- #### Step 1: First, upgrade the asset canister (by proposal, as with any other canister) to the asset canister wasm bundled with dfx 0.14.1, available [here](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). -- #### Step 2: After upgrading the asset canister by proposal, have someone with Prepare permission run: +- #### Step 2: After upgrading the asset canister by proposal, have someone with `Prepare` permission run: ``` dfx deploy --network ic --by-proposal @@ -139,24 +132,41 @@ dfx deploy --network ic --compute-evidence The computed evidence should match the evidence from step 2. -- #### Step 5: Submit a new proposal to commit the batch, using the ‘New Canister APIs’ above. +- #### Step 5: Submit a new proposal to commit the batch, using the APIs below: -## Asset canister examples +Use these asset canister APIs in the proposal: -An example of an SNS asset canister is canister `sqbzf-5aaaa-aaaam-aavya-cai`, which is an asset canister part of the [Dragginz Dapp SNS](https://dashboard.internetcomputer.org/canister/sqbzf-5aaaa-aaaam-aavya-cai). +``` + type CommitProposedBatchArguments = record { + batch_id: BatchId; + evidence: blob; + }; + type ValidationResult = variant { Ok : text; Err : text }; -By viewing the above asset canister, you can view example method that can be used to add, remove, or change assets. -The following is an example of a simple 'store' method: + validate_commit_proposed_batch: (CommitProposedBatchArguments) -> (ValidationResult); + commit_proposed_batch: (CommitProposedBatchArguments) -> (); ``` -// Single call to create an asset with content for a single content encoding that -// fits within the message ingress limit. - store: (record { - key: Key; - content_type: text; - content_encoding: text; - content: blob; - sha256: opt blob - }) -> (); + +An example can be found [here](https://github.com/dfinity/sdk/blob/master/e2e/tests-dfx/assetscanister.bash#L133). + +If the proposal is rejected, the preparer should use this new asset canister API: + +``` + type DeleteBatchArguments = record { + batch_id: BatchId; + }; + delete_batch: (DeleteBatchArguments) -> (); ``` + + +## Asset canister examples + +An example of an SNS asset canister is canister `sqbzf-5aaaa-aaaam-aavya-cai`, which is an asset canister part of the [Dragginz Dapp SNS](https://dashboard.internetcomputer.org/canister/sqbzf-5aaaa-aaaam-aavya-cai). + +## SNS GenericNervousSystemFunctions + +To submit a new `AddGenericNervouSystemFunction` SNS Proposal to support the `commit_proposed_batch` API, the target canister id should be the asset canister (that is upgraded in upgrade steps) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. + +To submit an `ExecuteNervousSystemFunction` SNS Proposal with the output from `dfx deploy --network ic --by-proposal` see upgrade steps above. From c4f7fb297da8daa33607cbdc883deea5aad33aea Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Fri, 23 Jun 2023 10:19:07 -0500 Subject: [PATCH 05/16] Update sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 32 +------------------ 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 86ffe4d6a3..ec2002d410 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -71,41 +71,11 @@ Once the asset canister has been deployed, the SNS can be launched. You can lear To deploy your asset canister to the mainnet, the following command can be used: ``` -dfx --provisional-create-canister-effective-canister-id deploy assets --network "IC" --wallet +dfx --provisional-create-canister-effective-canister-id deploy assets --network "ic" --wallet ``` Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) - -## Submitting an SNS proposal - -The following asset canister APIs can be used within a proposal: - -``` - type CommitProposedBatchArguments = record { - batch_id: BatchId; - evidence: blob; - }; - type ValidationResult = variant { Ok : text; Err : text }; - - - validate_commit_proposed_batch: (CommitProposedBatchArguments) -> (ValidationResult); - commit_proposed_batch: (CommitProposedBatchArguments) -> (); - -``` - -An example can be found [here](https://github.com/dfinity/sdk/blob/master/e2e/tests-dfx/assetscanister.bash#L133). - -If the proposal is rejected, the preparer should use this new asset canister API: - -``` - type DeleteBatchArguments = record { - batch_id: BatchId; - }; - delete_batch: (DeleteBatchArguments) -> (); -``` - - ## Submitting an SNS proposal and upgrading an asset canister - #### Step 1: First, upgrade the asset canister (by proposal, as with any other canister) to the asset canister wasm bundled with dfx 0.14.1, available [here](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). From c057fac9b52195794df384f0c01fa49d47893b1b Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Fri, 23 Jun 2023 10:26:08 -0500 Subject: [PATCH 06/16] Update sns-asset-canister.md --- .../integrations/sns/managing-sns/sns-asset-canister.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index ec2002d410..3162feb7a9 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -61,17 +61,21 @@ Next, you will need to configure your `dfx.json` file to specify your asset cani To deploy your asset canister locally for testing purposes, the following command can be used: ``` -dfx --provisional-create-canister-effective-canister-id deploy assets --network "local" --no-wallet +dfx deploy assets --network "local" --no-wallet ``` Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) ### Deploying on the mainnet +:::info +To deploy to the mainnet network, you will need a wallet that contains cycles. For more information on cycles wallets, please see [here](../../../setup/cycles/cycles-wallet.md). +::: + To deploy your asset canister to the mainnet, the following command can be used: ``` -dfx --provisional-create-canister-effective-canister-id deploy assets --network "ic" --wallet +dfx deploy assets --network "ic" --wallet ``` Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) From 26e91a52a3355bde108c9fd57cef6a28bc51d12d Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Fri, 23 Jun 2023 10:26:32 -0500 Subject: [PATCH 07/16] Update sns-asset-canister.md --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 3162feb7a9..7d92b75a32 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -64,7 +64,7 @@ To deploy your asset canister locally for testing purposes, the following comman dfx deploy assets --network "local" --no-wallet ``` -Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) +Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md). ### Deploying on the mainnet From b39dd4040bd8d82fc110e7e9dd588f42812cd0aa Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 08:00:10 -0500 Subject: [PATCH 08/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 7d92b75a32..c286202851 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -6,7 +6,7 @@ The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/fr In the context of the SNS, a dapp's associated asset canister serves the frontend assets related to dapp and may also include a frontend to the SNS DAO, e.g., through which users can vote on governance proposals. -The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a principal with the permission to do so. The SNS is the only one that can update the list of approved principals that have this permission, and any additions to this list approved on via an SNS proposal. This configuration assures that changes to the asset canister are only made by authorized principals that the SNS has agreed on through proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. +The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a principal with the permission to do so. The SNS is the only one that can update the list of approved principals that have this permission, and any changes to this list must be approved on via an SNS proposal. This configuration assures that changes to the asset canister are only made by authorized principals that the SNS has agreed on through proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. When a dapp's control is handed over to an SNS, this is also true for the associated asset canister. From 66cd9c4f95fd05bfa96216a7ac094847d0e1b0dd Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 08:00:41 -0500 Subject: [PATCH 09/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index c286202851..1f503fc385 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -69,7 +69,7 @@ Once the asset canister has been deployed, the SNS can be launched. You can lear ### Deploying on the mainnet :::info -To deploy to the mainnet network, you will need a wallet that contains cycles. For more information on cycles wallets, please see [here](../../../setup/cycles/cycles-wallet.md). +To deploy to the mainnet, you will need a wallet that contains cycles. For more information on cycles wallets, please see [here](../../../setup/cycles/cycles-wallet.md). ::: To deploy your asset canister to the mainnet, the following command can be used: From 865bb31fdcb03b59485f4453306e07b84bb937a6 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 09:47:55 -0500 Subject: [PATCH 10/16] Update sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 95 +++++++++++++++---- 1 file changed, 78 insertions(+), 17 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 1f503fc385..a92f386d4c 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -6,14 +6,22 @@ The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/fr In the context of the SNS, a dapp's associated asset canister serves the frontend assets related to dapp and may also include a frontend to the SNS DAO, e.g., through which users can vote on governance proposals. -The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a principal with the permission to do so. The SNS is the only one that can update the list of approved principals that have this permission, and any changes to this list must be approved on via an SNS proposal. This configuration assures that changes to the asset canister are only made by authorized principals that the SNS has agreed on through proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. - -When a dapp's control is handed over to an SNS, this is also true for the associated asset canister. +The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a submitting a proposal by a principal with the permission to do so. Once changes are proposed, they can be voted on by the SNS DAO. If approved, the SNS governance canister is the only one that can commit the approved changes. This configuration assures that changes to the asset canister are only made by approved proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. ## Deploying an asset canister +An asset canister must first be deployed before control of it can be handed over to an SNS. When a dapp's control is handed over to an SNS, this is also true for the associated asset canister. + +The general overview of deploying an asset canister during an SNS launch is as follows: +- First, the asset canister must be created with or upgraded to a Wasm file from [dfx 0.14.1+](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). +- Then, the dapp should hand control of the asset canister over to the SNS by setting the following permissions: + - The SNS governance canister is given `Commit` permissions. This is done by the previous developer using the `grant_permissions` command (see the granting permissions section below), otherwise the SNS must grant this permission once it is a controller. + - A whitelist of principals with `Prepare` permissions used to submit proposals is created. + - The user or developer creating the SNS should remove their own personal permissions. +- Lastly, the SNS's function should be registered to commit the configuration. + To deploy an asset canister, first you will need an `assets.wasm.gz` file and a `candid/assets.did` file. Examples of these files can be downloaded with the commands: ``` @@ -56,7 +64,9 @@ Next, you will need to configure your `dfx.json` file to specify your asset cani } ``` -### Deploying locally +Alternatively, any canister in the `dfx.json` file can be set as `"type": "assets"`, and dfx will automatically perform the above steps. + +### Deploying locally for testing To deploy your asset canister locally for testing purposes, the following command can be used: @@ -64,7 +74,7 @@ To deploy your asset canister locally for testing purposes, the following comman dfx deploy assets --network "local" --no-wallet ``` -Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md). +The asset canister should be deployed and have permissions configured before the dapp is handed over to an SNS. ### Deploying on the mainnet @@ -78,13 +88,69 @@ To deploy your asset canister to the mainnet, the following command can be used: dfx deploy assets --network "ic" --wallet ``` -Once the asset canister has been deployed, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) +The asset canister should be deployed and have permissions configured before the dapp is handed over to an SNS. + +## Configuring an asset canister's permissions + +When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed submit proposals that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit proposals are given the `Prepare` permission. + +Before the SNS can be launched, control of the asset canister must be handed over to the SNS. The SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. + +Once the asset canister has been handed over to the SNS, only the governance canister should have `Commit` rights, and principals in the whitelist should have `Prepare` rights. The developer who configured and deployed the SNS should have their permissions removed prior to launching the SNS. + +If the whitelist needs to be adapted or changed, the SNS can call `take_ownership` via a proposal, which must be added as a custom proposal type. This will clear all permissions, and give only the SNS governance canister `Commit` permissions. + +### Granting permissions + +To grant a principal permission within an asset canister, the following command can be used: + +``` +dfx canister call --network ic grant_permission +``` + +### Revoking permissions + +To revoke a principal's permission within an asset canister, the following command can be used: + +``` +dfx canister call --network ic revoke_permission +``` + +### Listing permissions + +To list permissions for an asset canister, the following command can be used: + +``` +dfx canister call --network ic list_permitted '(record {permission = variant {}})' +``` + +For example, to list all principals with the `Commit` permission: + +``` +dfx canister call --network ic oa7fk-maaaa-aaaam-abgka-cai list_permitted '(record {permission = variant {Commit}})' +``` + +To list all principals with the `Prepare` permission: + +``` +dfx canister call --network ic oa7fk-maaaa-aaaam-abgka-cai list_permitted '(record {permission = variant {Commit}})' +``` + +Once the asset canister has been deployed and permissions have been configured, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) + +## SNS GenericNervousSystemFunctions + +To submit a new `AddGenericNervousSystemFunction` SNS Proposal to support the `commit_proposed_batch` API, the target canister id should be the asset canister (that is upgraded in the upgrade steps below) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. + +To submit an `ExecuteNervousSystemFunction` SNS Proposal with the output from `dfx deploy --network ic --by-proposal` see upgrade steps below. ## Submitting an SNS proposal and upgrading an asset canister -- #### Step 1: First, upgrade the asset canister (by proposal, as with any other canister) to the asset canister wasm bundled with dfx 0.14.1, available [here](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). +Once an asset canister is under the control of the SNS, any changes must be done via an SNS proposal. + +Before submitting an SNS proposal to upgrade an asset canister, assure that the asset canister has been upgraded (by proposal) to use the Wasm bundled with [dfx 0.14.1+](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). -- #### Step 2: After upgrading the asset canister by proposal, have someone with `Prepare` permission run: +- #### Step 1: To submit an SNS proposal, first have a principal with `Prepare` permission run: ``` dfx deploy --network ic --by-proposal @@ -96,9 +162,9 @@ The output will contain something like this: Proposed commit of batch 2 with evidence e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Either commit it by proposal, or delete it. ``` -- #### Step 3: Save the batch number and the evidence value for use with the asset canister API. +- #### Step 2: Save the batch number and the evidence value for use with the asset canister API. -- #### Step 4: To ensure that others would be able to verify the evidence in the proposal, have someone else clone the dapp repo and run: +- #### Step 3: To ensure that others would be able to verify the evidence in the proposal, have someone else clone the dapp repo and run: ``` dfx deploy --network ic --compute-evidence @@ -106,7 +172,7 @@ dfx deploy --network ic --compute-evidence The computed evidence should match the evidence from step 2. -- #### Step 5: Submit a new proposal to commit the batch, using the APIs below: +- #### Step 4: Submit a new proposal to commit the batch, using the APIs below: Use these asset canister APIs in the proposal: @@ -135,12 +201,7 @@ If the proposal is rejected, the preparer should use this new asset canister API ``` -## Asset canister examples +## Asset canister example An example of an SNS asset canister is canister `sqbzf-5aaaa-aaaam-aavya-cai`, which is an asset canister part of the [Dragginz Dapp SNS](https://dashboard.internetcomputer.org/canister/sqbzf-5aaaa-aaaam-aavya-cai). -## SNS GenericNervousSystemFunctions - -To submit a new `AddGenericNervouSystemFunction` SNS Proposal to support the `commit_proposed_batch` API, the target canister id should be the asset canister (that is upgraded in upgrade steps) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. - -To submit an `ExecuteNervousSystemFunction` SNS Proposal with the output from `dfx deploy --network ic --by-proposal` see upgrade steps above. From 6d55d950e4aade56d50089301b27e5a77b795e2d Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 11:53:48 -0500 Subject: [PATCH 11/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index a92f386d4c..96013d94ab 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -6,7 +6,7 @@ The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/fr In the context of the SNS, a dapp's associated asset canister serves the frontend assets related to dapp and may also include a frontend to the SNS DAO, e.g., through which users can vote on governance proposals. -The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a submitting a proposal by a principal with the permission to do so. Once changes are proposed, they can be voted on by the SNS DAO. If approved, the SNS governance canister is the only one that can commit the approved changes. This configuration assures that changes to the asset canister are only made by approved proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. +The contents of the asset canister must be configured prior to the launch of the SNS. Any changes afterwards must be submitted by a principal with the permission to do so. Once changes are proposed, they can be voted on by the SNS DAO. If adopted, the SNS governance canister commits the approved changes and is the only one who can do so. This configuration assures that changes to the asset canister are only made by adopted proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. From 2af6bbbebcc7aebd96218043c3a038c6e77c7dfb Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 11:54:13 -0500 Subject: [PATCH 12/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 96013d94ab..5e95f6c364 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -94,7 +94,7 @@ The asset canister should be deployed and have permissions configured before the When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed submit proposals that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit proposals are given the `Prepare` permission. -Before the SNS can be launched, control of the asset canister must be handed over to the SNS. The SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. +During the SNS launch, control of the asset canister must be handed over to the SNS. Apart from assigning canister control to SNS root as with all dapp canisters, the SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. Once the asset canister has been handed over to the SNS, only the governance canister should have `Commit` rights, and principals in the whitelist should have `Prepare` rights. The developer who configured and deployed the SNS should have their permissions removed prior to launching the SNS. From 5d9ac0172175e5d494e583758db5ce73375803cd Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 11:54:24 -0500 Subject: [PATCH 13/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 5e95f6c364..818754ecf8 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -96,7 +96,7 @@ When configuring an asset canister, a set of permissions that contains a whiteli During the SNS launch, control of the asset canister must be handed over to the SNS. Apart from assigning canister control to SNS root as with all dapp canisters, the SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. -Once the asset canister has been handed over to the SNS, only the governance canister should have `Commit` rights, and principals in the whitelist should have `Prepare` rights. The developer who configured and deployed the SNS should have their permissions removed prior to launching the SNS. +Once the asset canister has been handed over to the SNS, only the governance canister should have `Commit` rights, and principals in the whitelist should have `Prepare` rights. The developer who configured and deployed the SNS should have their permissions removed during the SNS launch. If the whitelist needs to be adapted or changed, the SNS can call `take_ownership` via a proposal, which must be added as a custom proposal type. This will clear all permissions, and give only the SNS governance canister `Commit` permissions. From 4f22240645d27a7775f20e7bc230d76fa1e32d6e Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 11:54:33 -0500 Subject: [PATCH 14/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 818754ecf8..eaddba2396 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -136,7 +136,7 @@ To list all principals with the `Prepare` permission: dfx canister call --network ic oa7fk-maaaa-aaaam-abgka-cai list_permitted '(record {permission = variant {Commit}})' ``` -Once the asset canister has been deployed and permissions have been configured, the SNS can be launched. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) +Once the asset canister has been deployed and permissions have been configured, the SNS decentralization swap can be started. You can learn more about launching an SNS [here](../launch-sns/launch-sns.md) ## SNS GenericNervousSystemFunctions From 72265dc5411f424cb3d6cd42854c7d320206e229 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 14:52:33 -0500 Subject: [PATCH 15/16] Update docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md Co-authored-by: Lara Schmid <73884086+LaraAS@users.noreply.github.com> --- .../integrations/sns/managing-sns/sns-asset-canister.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index eaddba2396..6b578ee9d3 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -92,7 +92,7 @@ The asset canister should be deployed and have permissions configured before the ## Configuring an asset canister's permissions -When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed submit proposals that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit proposals are given the `Prepare` permission. +When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed to submit proposals that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit proposals are given the `Prepare` permission. During the SNS launch, control of the asset canister must be handed over to the SNS. Apart from assigning canister control to SNS root as with all dapp canisters, the SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. From 31d61ceb48c9964d37a399e10993de18b5127a74 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 26 Jun 2023 15:02:24 -0500 Subject: [PATCH 16/16] Update sns-asset-canister.md --- .../sns/managing-sns/sns-asset-canister.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md index 6b578ee9d3..8dd6a71456 100644 --- a/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md +++ b/docs/developer-docs/integrations/sns/managing-sns/sns-asset-canister.md @@ -6,7 +6,7 @@ The [asset canister](https://github.com/dfinity/sdk/tree/master/src/canisters/fr In the context of the SNS, a dapp's associated asset canister serves the frontend assets related to dapp and may also include a frontend to the SNS DAO, e.g., through which users can vote on governance proposals. -The contents of the asset canister must be configured prior to the launch of the SNS. Any changes afterwards must be submitted by a principal with the permission to do so. Once changes are proposed, they can be voted on by the SNS DAO. If adopted, the SNS governance canister commits the approved changes and is the only one who can do so. This configuration assures that changes to the asset canister are only made by adopted proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. +The contents of the asset canister must be configured prior to the launch of the SNS, and any changes afterwards must be made by a principal with the `Prepare` permission. Principals with this `Prepare` permission can make a batch of changes to the asset canister and then 'lock' those changes. To have those changes applied, a proposal must be submitted. Anyone can submit the proposal for the 'locked' changes. Once changes are proposed, they can be voted on by the SNS DAO. If approved, the SNS governance canister is the only one that can commit the approved changes. This configuration assures that changes to the asset canister are only made by approved proposals. These changes are referred to as 'upgrades' to the asset canister in the remainder of this document. This section is relevant if your project contains an asset canister and describes how you can test handing over control of an asset canister to an SNS. @@ -18,7 +18,7 @@ The general overview of deploying an asset canister during an SNS launch is as f - First, the asset canister must be created with or upgraded to a Wasm file from [dfx 0.14.1+](https://github.com/dfinity/sdk/blob/release-0.14.1/src/distributed/assetstorage.wasm.gz). - Then, the dapp should hand control of the asset canister over to the SNS by setting the following permissions: - The SNS governance canister is given `Commit` permissions. This is done by the previous developer using the `grant_permissions` command (see the granting permissions section below), otherwise the SNS must grant this permission once it is a controller. - - A whitelist of principals with `Prepare` permissions used to submit proposals is created. + - A whitelist of principals with `Prepare` permissions is created to give certain individuals the permission to upload changes to the asset canister. Changes must be approved through a proposal before they are applied to the asset canister. - The user or developer creating the SNS should remove their own personal permissions. - Lastly, the SNS's function should be registered to commit the configuration. @@ -92,7 +92,9 @@ The asset canister should be deployed and have permissions configured before the ## Configuring an asset canister's permissions -When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed to submit proposals that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit proposals are given the `Prepare` permission. +When configuring an asset canister, a set of permissions that contains a whitelist of principals must be created. This whitelist details who is allowed to submit changes that update assets in the asset canister. This whitelist must be configured prior to the SNS launch. Principals that are allowed to submit changes are given the `Prepare` permission. + +Once a principal with `Prepare` permissions submits changes to the asset canister, these changes are set in a 'locked' state. Then, anyone can submit a proposal that proposes the 'locked' changes be applied; there is no permission necessary to submit this proposal. During the SNS launch, control of the asset canister must be handed over to the SNS. Apart from assigning canister control to SNS root as with all dapp canisters, the SNS' governance canister should be added to the whitelist as a principal with `Commit` rights. Only principals with `Commit` rights may apply proposed changes. @@ -140,9 +142,13 @@ Once the asset canister has been deployed and permissions have been configured, ## SNS GenericNervousSystemFunctions +Generic proposals are a way for each SNS to define custom proposals. To commit changes to the asset canister, such generic proposals are used. + +To use a generic proposal, first this new proposal type has to be "registered" in the SNS. To do so, one uses a `AddGenericNervousSystemFunction` proposal. + To submit a new `AddGenericNervousSystemFunction` SNS Proposal to support the `commit_proposed_batch` API, the target canister id should be the asset canister (that is upgraded in the upgrade steps below) and the target function is `commit_proposed_batch`. The validate function should be `validate_commit_proposed_batch`. -To submit an `ExecuteNervousSystemFunction` SNS Proposal with the output from `dfx deploy --network ic --by-proposal` see upgrade steps below. +The `ExecuteNervousSystemFunction` SNS proposal is used to execute the newly registered proposal. To submit an `ExecuteNervousSystemFunction` SNS Proposal with the output from `dfx deploy --network ic --by-proposal` see upgrade steps below. ## Submitting an SNS proposal and upgrading an asset canister