How-To: SNS swap participation via quill

The goal of this page is to explain how to participate in the SNS swap via quill.

1 Background and objective

• It is assumed 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 local testing with a local testnet see the corresponding documentation
• More information on SNS can be found here

2 Quill commands to participate in an SNS swap

For some more information on the commands that you can run with quill run quill help or quill sns help for SNS-specific commands.

2.1 Prerequisites

• PEM file: To use quill you need your secret key in a PEM file. For help on how to create new identities and manage them see the corresponding documentation for dfx here. Save the path to the PEM file as you will need it later. The content of the PEM file should look something like this:

-----BEGIN EC PRIVATE KEY-----
MHQCAQEEICJxApEbuZznKFpV+VKACRK30i6+7u5Z13/DOl18cIC+oAcGBSuBBAAK
oUQDQgAEPas6Iag4TUx+Uop+3NhE6s3FlayFtbwdhRVjvOar0kPTfE/N8N6btRnd
74ly5xXEBNSXiENyxhEuzOZrIWMCNQ==
-----END EC PRIVATE KEY-----

• Canister Ids file: You will need a file which stores the mappings of canister ids to their names. It should look something like this (Note: The actual ids will be different for the swap you want to participate in):

{
"root_canister_id":"sgymv-uiaaa-aaaaa-aaaia-cai",
"governance_canister_id":"sbzkb-zqaaa-aaaaa-aaaiq-cai",
"index_canister_id":"s24we-diaaa-aaaaa-aaaka-cai",
"swap_canister_id":"sp3hj-caaaa-aaaaa-aaajq-cai",
"ledger_canister_id":"si2b5-pyaaa-aaaaa-aaaja-cai"
}

You can find the correct canister Ids from the SNS-W. Click ‘+’ next to list_deployed_snses, and then click “Call”. Create a file called canister_ids and insert the SNS canister ids in the format from above.

2.2 Check Status of SNS

To verify that your setup works and the SNS is up and running.

quill --pem-file <path> sns --canister-ids-file <path> status

Quill will ask you to sign and send this transaction. The response will be a description of each canister that make up the SNS. For participation in the SNS swap the canister "swap" is important. It should look something like this:

swap = opt record {
      status = opt record {
        controller = principal "r7inp-6aaaa-aaaaa-aaabq-cai";
        status = variant { running };
        freezing_threshold = 2_592_000 : nat;
        balance = vec { record { blob "\00"; 30_000_000_000_000 : nat } };
        memory_size = 11_029_070 : nat;
        cycles = 30_000_000_000_000 : nat;
        settings = record {
          controller = principal "r7inp-6aaaa-aaaaa-aaabq-cai";
          freezing_threshold = 2_592_000 : nat;
          controllers = vec { principal "r7inp-6aaaa-aaaaa-aaabq-cai" };
          memory_allocation = 0 : nat;
          compute_allocation = 0 : nat;
        };
        idle_cycles_burned_per_day = 0 : nat;
        module_hash = opt blob "d\92\91\d2W:^\05\d9\ac\ec\a0\cd\a6=\de\df\1b\0f\c9\86\e6\8d\86+\d0\01\8b\f8f\81\b1";
      };
      canister_id = opt principal "sp3hj-caaaa-aaaaa-aaajq-cai";
    };

It's vital that the canister's status in running.

2.3 Getting SNS Swap parameters

Before being able to buy any tokens, it is important to know what the parameters of the swap are. You can query them via dfx:

dfx canister --network https://ic0.app call <swap_canister_id> get_swap_parameters "(record {})"

The response should look something like this:

(
  record {
    params = opt record {
      min_participant_icp_e8s = 100_000_000 : nat64;
      neuron_basket_construction_parameters = opt record {
        dissolve_delay_interval_seconds = 31_536_000 : nat64;
        count = 3 : nat64;
      };
      max_icp_e8s = 50_000_000_000 : nat64;
      swap_due_timestamp_seconds = 1_677_398_018 : nat64;
      min_participants = 3 : nat32;
      sns_token_e8s = 500_000_000_000 : nat64;
      swap_delay_seconds = null;
      max_participant_icp_e8s = 20_000_000_000 : nat64;
      min_icp_e8s = 5_000_000_000 : nat64;
    };
  },
)

The important parameters for the payment flow are the min_participant_icp_e8s and max_participant_icp_e8s with the former being the minimum amount of ICP per particpant and the latter being the maximum amount of ICP per participant to participate in the swap. Note that for your first payment you will have to pay with at least as many ICP as the number min_participant_icp_e8s suggests, otherwise your request will be denied. Any purchase after that can be of any amount as long as the total amount of ICP used for purchases is not higher than max_participant_icp_e8s.

2.4 Getting a Ticket

The first step in the actual payment flow is to acquire a ticket via quill. You can specify the amount you want to purchase but note that for the first time, it has to be at least as high as min_participant_icp_e8s. The first command to get a ticket will create the transaction and has to be stored before it can be sent. For that purpose choose a path for this tx.json file:

quill --pem-file <path> sns --canister-ids-file <path> new-swap-ticket --amount-icp-e8s <amount_to_be_purchased> > PATH/tx_new_ticket.json

To do a dry run of this transaction run

quill --pem-file <path> sns --canister-ids-file <path> send --dry-run PATH/tx_new_ticket.json

It will show you the full transaction without sending it. To actually send the transaction use:

quill --pem-file <path> sns --canister-ids-file <path> send PATH/tx_new_ticket.json

The response will look something like this:

(
  record {
    result = opt variant {
      Ok = record {
        ticket = opt record {
          creation_time = 1_677_227_094_330_351_716 : nat64;
          ticket_id = 2 : nat64;
          account = opt record {
            owner = opt principal "iowfl-yzooa-br3dt-77erl-nlm7f-kplhq-php75-hw3an-aeqn2-swh4t-3qe";
            subaccount = null;
          };
          amount_icp_e8s = 100_000_000 : nat64;
        };
      }
    };
  },
)

In this case, the amount specified was 100 Million e8 ICP. The important information here is the ticket_id and the creation_time, you will need them in the next step. Note that you cannot create another ticket while a ticket is still open. Use the ticket within 24 hours or the time stamp on the ticket will be outdated and it can no longer be used. To delete an existing ticket call:

dfx canister --network https://ic0.app --identity PATH/identity.pem --update call 
 <swap_canister_id>  notify_payment_failure "(record {})"

Now you can request a new ticket.

2.5 Sending the Payment Transaction

A ticket was created and the actual payment can now be done. Similarly, to the previous step you have to create a file for the transaction, optionally perform a dry run to see the transaction before sending it and the send the transaction to the Internet Computer. Note that the creation_time format from the ticket has to be changed from '1_677_227_094_330_351_716 to 1677227094330351716 for the payment transaction to accept the timestamp format. The three commands are the following:

quill --pem-file <path> sns --canister-ids-file <path> pay --amount-icp-e8s <amount_to_be_purchased> --ticket-creation-time <creation_time> --ticket-id <ticket_id> > PATH/tx_pay.json

To do a dry run of this transaction run

quill --pem-file <path> sns --canister-ids-file <path> send --dry-run PATH/tx_pay.json

and send it with:

quill --pem-file <path> sns --canister-ids-file <path> send PATH/tx_pay.json

You will have to sign multiple transactions during this process. The response will look something like this

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

The return value icp_accepted_participation_e8s shows how many ICPs were already accepted in the SNS swap and the return value icp_ledger_account_balance_e8s shows how many ICPs have been sent to the SNS swap canister. If at the end of the swap, these two numbers are not equivalent and icp_ledger_account_balance_e8s is greater than icp_accepted_participation_e8s you can get a refund of your ICP that were not used in the SNS swap after the swap has concluded. Should the SNS swap abort you will get the amount icp_accepted_participation_e8s refunded automatically.

2.6 Checking your balance

To query your balance of all accepted ICP during a SNS swap run

quill --pem-file <path> sns --canister-ids-file <path> get-swap-participation

To query your balance of the SNS ledger run

quill --pem-file <path> sns --canister-ids-file <path> balance

While the swap is still ongoing the return will most likely be

(0 : nat)

This is the balance of the SNS ledger which will NOT be updated until the swap is over and the SNS tokens are allocated. Thus, any purchase you make during the swap will not be visible through this command. To check your balance of tokens that have already been committed and the total amount of ICP you have sent to the SNS swap canister you need to look at the return value of when you called pay.