View source for How-To: SNS swap participation via quill

__NUMBEREDHEADINGS__
The goal of this page is to explain how to participate in the SNS sale via quill.
== Background and objective ==
* We assume that you have a working installation of quill and are familiar with the tool. For an introduction into quill, please see [https://medium.com/dfinity/introducing-quill-a-ledger-and-governance-toolkit-for-the-internet-computer-1df086ce5642 here]. For instructions on how to install and use quill please see the readme on [https://github.com/dfinity/quill GitHub] and the [https://internetcomputer.org/docs/current/references/quill-cli-reference/ quill documentation].
* For local testing with a local testnet see the corresponding [https://internetcomputer.org/docs/current/developer-docs/integrations/sns/get-sns/local-testing documentation]
* More information on SNS can be found [https://internetcomputer.org/sns/ here]
== Quill commands to participate in an SNS sale ==
For some more information on the commands that you can run with quill run '''quill help''' or '''quill sns help''' for SNS-specific commands. 
=== 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 [https://internetcomputer.org/docs/current/references/cli-reference/dfx-identity#:~:text=dfx%20identity%20new%E2%80%8B,new%20command%20in%20any%20project. 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:
<pre>
-----BEGIN EC PRIVATE KEY-----
MHQCAQEEICJxApEbuZznKFpV+VKACRK30i6+7u5Z13/DOl18cIC+oAcGBSuBBAAK
oUQDQgAEPas6Iag4TUx+Uop+3NhE6s3FlayFtbwdhRVjvOar0kPTfE/N8N6btRnd
74ly5xXEBNSXiENyxhEuzOZrIWMCNQ==
-----END EC PRIVATE KEY-----
</pre>
* 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 sale you want to participate in):
<pre>
{
"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"
}
</pre>
You can find the correct canister Ids from [https://dashboard.internetcomputer.org/canister/qaa6y-5yaaa-aaaaa-aaafa-cai 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. 

=== Check Status of SNS ===
To verify that your setup works and the SNS is up and running. 
<pre>
quill --pem-file <path> sns --canister-ids-file <path> status
</pre>
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 sale the canister "swap" is important. It should look something like this: 

<pre>
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";
    };
</pre>
It's vital that the canister's status in '''running'''.

=== Getting SNS Sale parameters === 
Before being able to buy any tokens, it is important to know what the parameters of the sale are. You can query them via '''dfx''':
<pre>
dfx canister --network https://ic0.app call <swap_canister_id> get_sale_parameters "(record {})"
</pre>
The response should look something like this: 
<pre>
(
  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;
      sale_delay_seconds = null;
      max_participant_icp_e8s = 20_000_000_000 : nat64;
      min_icp_e8s = 5_000_000_000 : nat64;
    };
  },
)
</pre>
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 sale. 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'''. 
=== 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:
<pre>
quill --pem-file <path> sns --canister-ids-file <path> new-sale-ticket --amount-icp-e8s <amount_to_be_purchased> > PATH/tx_new_ticket.json
</pre>
To do a dry run of this transaction run 
<pre>
quill --pem-file <path> sns --canister-ids-file <path> send --dry-run PATH/tx_new_ticket.json
</pre>
It will show you the full transaction without sending it. To actually send the transaction use:
<pre>
quill --pem-file <path> sns --canister-ids-file <path> send PATH/tx_new_ticket.json
</pre>
The response will look something like this:
<pre>
(
  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;
        };
      }
    };
  },
)
</pre>
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:
<pre>
dfx canister --network https://ic0.app --identity PATH/identity.pem --update call 
 <swap_canister_id>  notify_payment_failure "(record {})"
</pre>
Now you can request a new ticket. 
=== 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: 
<pre>
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
</pre>
To do a dry run of this transaction run 
<pre>
quill --pem-file <path> sns --canister-ids-file <path> send --dry-run PATH/tx_pay.json
</pre>
and send it with:
<pre>
quill --pem-file <path> sns --canister-ids-file <path> send PATH/tx_pay.json
</pre>
You will have to sign multiple transactions during this process.
The response will look something like this
<pre>
(
  record {
    icp_accepted_participation_e8s = 100_000_000 : nat64;
    icp_ledger_account_balance_e8s = 100_000_000 : nat64;
  },
)
</pre>
The return value '''icp_accepted_participation_e8s''' shows how many ICPs were already accepted in the SNS sale and the return value '''icp_ledger_account_balance_e8s''' shows how many ICPs have been sent to the SNS sale canister. If at the end of the sale, 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 sale after the sale has concluded. Should the SNS sale abort you will get the amount '''icp_accepted_participation_e8s''' refunded automatically. 
=== Checking your balance ===
To query your balance of all accepted ICP during a SNS sale run 
<pre>
quill --pem-file <path> sns --canister-ids-file <path> get-sale-participation
</pre>
To query your balance of the SNS ledger run 
<pre>
quill --pem-file <path> sns --canister-ids-file <path> balance
</pre>
While the sale is still ongoing the return will most likely be 
<pre>
(0 : nat)
</pre>
This is the balance of the SNS ledger which will '''NOT''' be updated until the sale is over and the SNS tokens are allocated. Thus, any purchase you make during the sale 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 sale canister you need to look at the return value of when you called '''pay'''.