View source for How-to: Interact with SNS canisters

This article explains how to interact with the canisters of SNS-1. It can also serve as an explanation of how to interact with an SNS and the dapp canisters it controls more generally. There are two ways to interact with canisters - via the [https://dashboard.internetcomputer.org/ dashboard], where you can click through a friendly user interface, or via the command line using [https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove DFX].

== What is SNS-1 ==
SNS-1 is envisaged to be the first SNS DAO to be created on the Internet Computer. Symbolically one aim for the SNS-1 is to be an experimental DAO owned and driven by the IC community. At conception, it consists only as a blank canvas for the community to paint the future upon. It signifies the beginning, an exemplar to experiment & educate with, and a beacon to inspire a community of SNSs.
The dapp the SNS-1 DAO initially controls can be found [https://sqbzf-5aaaa-aaaam-aavya-cai.ic0.app/ here]. Initially it just points to an immutable letter stored on a [https://internetcomputer.org/docs/current/concepts/trust-in-canisters/#complete-immutability blackholed canister].  

== Finding all SNS and dapp canisters == 

If you want to interact with a dapp and the SNS DAO that governs the dapp, you likely know either the dapp canister ID or the SNS root canister ID by which an SNS is identified.
This article first describes how, starting from SNS root canister ID, you can find and interact with all SNS and dapp canisters.

== Finding all SNS and dapp canisters - starting from SNS ==

	
====Get the SNS root canister ====
The SNS root canister is the SNS canister that knows about and controls all the other SNS canisters and the dapp canisters. Therefore it is the canister by which an SNS can be identified. Given this canister ID you can verify it is indeed an “official SNS” that runs an SNS wasm that has been vetted by the NNS. 
All SNS root canisters, and thus all SNSs, are listed in the NNS canister called SNS wasm modules canister, or SNS-W for short. SNS-W is a fixed canister ID in the NNS subnet and its canister ID is <syntaxhighlight inline>qaa6y-5yaaa-aaaaa-aaafa-cai</syntaxhighlight>. Call the method <syntaxhighlight inline>list_deployed_snses</syntaxhighlight> and find all root canister IDs in the returned list. You can now check that the SNS root canister ID you knew is one of them.

''' DFX.'''
 <nowiki> $ dfx canister --network ic call qaa6y-5yaaa-aaaaa-aaafa-cai list_deployed_snses '(record {})' </nowiki>

'''Dashboard.'''
In the SNS-W canister interface, navigate to the SNS-W canister, for example by entering its ID in the search bar. 
You will get to a [https://dashboard.internetcomputer.org/canister/qaa6y-5yaaa-aaaaa-aaafa-cai page] that summarises this canister and all its methods.
Click ‘+’ next to <syntaxhighlight inline>list_deployed_snses</syntaxhighlight>, and then click “Call”.
As SNS-1 is the first SNS, this list only contains one SNS record, where the <syntaxhighlight inline>root_canister_id</syntaxhighlight> is <syntaxhighlight inline>zxeu2-7aaaa-aaaaq-aaafa-cai</syntaxhighlight>.

====Get all SNS and dapp canister IDs==== 
From the last step, you know that the root canister ID has been verified as a “true” SNS root canister ID deployed through the blessed canister wasm path. You can next get the rest of the canister IDs associated with that SNS by calling <syntaxhighlight inline>list_sns_canisters</syntaxhighlight> on the SNS root canister.
This list contains a list of all canisters that collectively make up the SNS.
The response from this method also has a “dapps” entry that lists the dapp canisters that are governed by the SNS.

'''DFX.'''
 <nowiki> $ dfx canister --network ic call zxeu2-7aaaa-aaaaq-aaafa-cai list_sns_canisters '(record {} )' </nowiki>

''' Dashboard.'''
On the dashboard, enter the canister ID of SNS root in the search tab. You should see all the methods of SNS root now. Similarly to the last step, click ‘+’ next to <syntaxhighlight inline>list_sns_canisters</syntaxhighlight>, and then click “Call”. 
This will return the canister IDs of all SNS canisters and the dapp canisters. 

====Get the summary of all SNS and dapp canisters====
Finally, you can get the summary and ownership graph of the SNS including the dapps. To do so, call <syntaxhighlight inline>get_sns_canisters_summary</syntaxhighlight> on the SNS root canister. This will return the status of each canister in the SNS, including information such as the canister’s controller and cycles balance.

''' DFX. '''
 <nowiki> $ dfx canister --network ic call zxeu2-7aaaa-aaaaq-aaafa-cai get_sns_canisters_summary '(record {} )' </nowiki>

'''Dashboard.'''
On the dashboard, where you should still be in the SNS root canister interface from the last Step, click ‘+’ next to <syntaxhighlight inline>get_sns_canisters_summary</syntaxhighlight>. You see the option to choose an argument, but you don't have to select this. Click “Call”. 

====Verify the controller hierarchy ====
In an SNS, the control hierarchy is as follows.
The SNS root canister controls all SNS canisters, except for the swap canister that implements the decentralization swap and which is controlled by the NNS root canister. The SNS root canister also controls the dapp canisters that are governed by the NNS.
Thus you can check that all canister's controller except swap is SNS root (<syntaxhighlight inline>zxeu2-7aaaa-aaaaq-aaafa-cai</syntaxhighlight> in SNS-1) and that the swap canister's controller is NNS root <syntaxhighlight inline>r7inp-6aaaa-aaaaa-aaabq-cai</syntaxhighlight>. The swap cansiter also has itself as a controller for technical reasons.
Finally, the SNS root canister itself is controlled by the SNS governance canister (<syntaxhighlight inline>zqfso-syaaa-aaaaq-aaafq-cai</syntaxhighlight> in SNS-1). 

'''Dashboard.'''
You can verify all of this by inspecting what you received in <syntaxhighlight inline>get_sns_canisters_summary</syntaxhighlight> in the last step or you can search for the individual canister IDs, which will lead you to an overview page for each canister, where the controllers are summarised on top.

== Finding all SNS and dapp canisters - starting from the dapp ==
If you have a dapp canister ID, you can first query the canister to find its controller. If the dapp is controlled by an SNS, then this will return you the SNS root canister ID and you can then proceed as explained in the section above. 
Often you might just have the URL to interact with the dapp. For the SNS-1 dapp this is <syntaxhighlight inline>https://sqbzf-5aaaa-aaaam-aavya-cai.ic0.app/</syntaxhighlight>. To follow the above approach to find the underlying canister's controller, you need the dapp canister's ID, which you can get by removing <syntaxhighlight inline>.ic0.app</syntaxhighlight> from the URL.

== Inspecting the SNS canisters ==

'''DFX Preparation. '''
Download these snippets into an empty repo so that dfx can point at the correct network and correct canisters. This allows to call the canisters and read the output in a human friendly way.

Snippet 1: [https://gitlab.com/-/snippets/2431348 dfx.json and candid files]

====List the neurons that exist in SNS Governance====
Before the decentralization swap finishes, the only neurons are the developer and airdrop neurons. Thus, during this time, you can inspect all neurons and see with which neurons the governance cansiter was initialized.
In SNS governance, <syntaxhighlight inline>list_neurons</syntaxhighlight> returns the full neurons. 
This method is paginated: As it is possible that there are more neurons than fit into one message, <syntaxhighlight inline>list_neurons</syntaxhighlight> just returns a number of neurons that you can enter by choosing the parameter <syntaxhighlight inline>limit</syntaxhighlight>. The neurons have a deterministic order so you can get the "next portion" or next "page" by entering in <syntaxhighlight inline>start_page_at</syntaxhighlight> the last neuron of the previously returned page (which will not be included in the next page). Proceeding this way allows you to get the full list of neurons over multiple calls. 

''' DFX. '''
<syntaxhighlight> $ dfx canister --network ic call zqfso-syaaa-aaaaq-aaafq-cai list_neurons '(record { of_principal=null; limit=100: nat32; start_page_at=null  } )' </syntaxhighlight>

'''Dashboard.''' On the dashboard, navigate to the SNS governance canister by entering the canister ID in the search bar. 
For SNS-1, this is <syntaxhighlight inline>zqfso-syaaa-aaaaq-aaafq-cai</syntaxhighlight>.
Then, click ‘+’ next to <syntaxhighlight inline>list_neurons</syntaxhighlight>. You don't need to choose anything for <syntaxhighlight inline>of_principle</syntaxhighlight> if you want to look at all neurons. Choose a limit as described above. For the first page you don't need to select a <syntaxhighlight inline>start_page_at</syntaxhighlight> and can click “Call”. For the subsequent calls, adjust <syntaxhighlight inline>start_page_at</syntaxhighlight> as described above.

==== Check out how many tokens are sold in the decentralization swap. ====
As long as the SNS has not launched yet, there are some tokens reserved for the SNS decentralization swap. They are stored in the SNS ledger account that is owned by the SNS swap canister (previously called swap). Thus, to learn how many tokens are in the decentralization swap, call <syntaxhighlight inline>icrc1_balance_of</syntaxhighlight> to get the balance of the Swap canister. The returned value is given in fractions of 10E-8 of an SNS token.

'''(Future) Dashboard.''' ''For this to work, the SNS ledger canister needs to be upgraded a new version.''
<!--*On the dashboard, navigate to the SNS ledger canister by entering the canister ID in the search bar. Then, click ‘+’ next to <syntaxhighlight inline>icrc1_balance_of</syntaxhighlight>, and provide as the argument the ID of the SNS swap canister. Then press <syntaxhighlight inline>call</syntaxhighlight>. 
-->

'''DFX'''
<syntaxhighlight>
$ dfx canister --network https://ic0.app call zfcdd-tqaaa-aaaaq-aaaga-cai --query icrc1_balance_of '(record {owner = principal "zcdfx-6iaaa-aaaaq-aaagq-cai" })'
</syntaxhighlight>

<!--* 
DFX 
 <nowiki> $ dfx canister --network ic call sns-ledger icrc1_balance_of '(record { owner = principal "wmio3-kqaaa-aaaaa-aaasq-cai"; subaccount = null;})' </nowiki>
-->

====Learn how many tokens are in the SNS treasury.==== 
The SNS treasury is a SNS ledger account that is owned by SNS governance. Specifically, it is on a defined subaccount of the SNS governance’s ledger account. To learn it, use <syntaxhighlight inline>icrc1_balance_of</syntaxhighlight> to get the balance of the SNS ledger account with the following arguments: 

'''DFX'''
<syntaxhighlight>
dfx canister --network https://ic0.app call --query zfcdd-tqaaa-aaaaq-aaaga-cai icrc1_balance_of '(record {owner = principal "zqfso-syaaa-aaaaq-aaafq-cai"; subaccount = blob "\ce\c2\14\5a\75\0f\d4\a4\72\b2\a0\21\f6\df\f1\e4\a9\07\29\97\00\06\2a\0a\02\bc\1e\a6\5c\a2\92\58" })'
</syntaxhighlight>

<!--* 
=== DFX ===
 <nowiki> $ dfx canister --network ic call sns-ledger icrc1_balance_of '(record { owner = principal "w6ozc-gaaaa-aaaaa-aaarq-cai"; subaccount = opt vec {45;90;183;220;109;161;20;55;134;152;60;18;176;240;131;123;255;182;167;138;177;190;202;83;86;198;249;176;218;98;20;65}: opt vec nat8;})' </nowiki>
 -->

'''(Future) Dashboard.''' ''For this to work, the SNS ledger canister needs to be upgraded to a new version.''
<!--* On the dashboard, navigate to the SNS ledger canister by entering the canister ID in the search bar. Then, click ‘+’ next to <syntaxhighlight inline>icrc1_balance_of</syntaxhighlight>, and provide as the argument TODO. Then press “Call”.
-->