How-To: Participate in the SNS decentralization swap via quill

Background and objective

The goal of this page is to explain how you participate in the SNS decentralization swap via quill, including an example.
It assumes that you have a working installation of quill and are familiar with the tool. For an introduction into quill, please see here. For instructions on how to install and use quill please see the readme on GitHub and the quill documentation.

For more information on the SNS, see the SNS FAQ.

Disclaimer: participation in any SNS is at your own risk.

Command syntax to participate in the SNS decentralization swap via quill

To participate in the swap via quill, two sequential commands are required. The first (1) command is to get a ticket from the swap canister specifying the amount you'd like to participate with. The second (2) command uses fields from the response of the first command to transfer tokens and notify the swap canister. The syntax is as follows

(1)

 quill sns \
 --pem-file <PEM_FILE> \
 --canister-ids-file <SNS_CANISTER_IDS_FILE> \
 new-swap-ticket \
 --amount-icp-e8s <AMOUNT>

(2)

 quill sns \
 --pem-file <PEM_FILE> \
 --canister-ids-file <SNS_CANISTER_IDS_FILE> \
 pay \
 --amount-icp-e8s <AMOUNT> \
 --ticket-creation-time <TICKET_CREATION_TIME> \
 --ticket-id <TICKET_ID>

where

<PEM_FILE> is the path to the Privacy-Enhanced Mail (PEM) file created when quill was set up.
<SNS_CANISTER_IDS_FILE> is the path to the json file containing the canister ids of an SNS.
<AMOUNT> is the amount of ICP you'd like to participate with denoted in "e8s equivalent" (10E-8 of ICP)
<TICKET_CREATION_TIME> is the ticket creation time returned in the response from the `new-swap-ticket` quill command.
<TICKET_ID> is the ticket id returned in the response from the `new-swap-ticket` quill command.

Example

Assume that you have a set-up where your PEM file is called identity.pem and the contents of the <SNS_CANISTER_IDS_FILE> looked like this:

{
    "governance_canister_id": "53zcu-tiaaa-aaaaa-qaaba-cai",
    "index_canister_id": "5o6tz-saaaa-aaaaa-qaacq-cai",
    "ledger_canister_id": "54yea-6qaaa-aaaaa-qaabq-cai",
    "root_canister_id": "5s2ji-faaaa-aaaaa-qaaaq-cai",
    "swap_canister_id": "5j7vn-7yaaa-aaaaa-qaaca-cai"
 }

Then the corresponding quill command for participating in an SNS decentralization swap with 1 ICP would look like this

 $ quill sns \ 
 --pem-file identity.pem \
 --canister-ids-file sns_canister_ids.json \
 new-swap-ticket \ 
 --amount-icp-e8s 100000000

 Request ID: 0xf613fd9e114534cbe16f5eae98442cd10bd26686231c391819dbe14f76595eaf
 (
   record {
     result = opt variant {
       Ok = record {
         ticket = opt record {
           creation_time = 1_677_282_561_339_427_861 : nat64;
           ticket_id = 0 : nat64;
           account = opt record {
             owner = opt principal "2ou35-xlilo-urfxh-c42wb-dq3ai-kq74a-wez2y-jwazm-rdqon-2d53v-lqe";
             subaccount = null;
           };
           amount_icp_e8s = 100_000_000 : nat64;
         };
       }
     };
   },
 )

some fields from the new-swap-ticket command must be used in the following pay command

 $ quill sns \
 --pem-file identity.pem \
 --canister-ids-file sns_canister_ids.json \
 pay \
 --amount-icp-e8s 100000000 \ 
 --ticket-creation-time 1677282561339427861 \
 --ticket-id 0

 (
   record {
     icp_accepted_participation_e8s = 100_000_000 : nat64;
     icp_ledger_account_balance_e8s = 100_000_000 : nat64;
   },
 )