package ic_sns_swap.pb.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: GetBuyerStateResponse, Participant, Swap

• optional TransferableAmount icp = 5

  The amount of ICP accepted from this buyer. ICP is accepted by first making a ledger transfer and then calling the method `refresh_buyer_token_e8s`. Can only be set when a buyer state record for a new buyer is created, which can only happen when the lifecycle state is `Open`. Must be at least `min_participant_icp_e8s`, and at most `max_participant_icp_e8s`. Invariant between canisters in the OPEN state: ```text icp.amount_e8 <= icp_ledger.balance_of(subaccount(swap_canister, P)), ``` where `P` is the principal ID associated with this buyer's state. ownership * PENDING - a `BuyerState` cannot exist * OPEN - owned by the buyer, cannot be transferred out * COMMITTED - owned by the SNS governance canister, can be transferred out * ABORTED - owned by the buyer, can be transferred out

• optional bool has_created_neuron_recipes = 6

  Idempotency flag indicating whether the neuron recipes have been created for the BuyerState. When set to true, it signifies that the action of creating neuron recipes has been performed on this structure. If the action is retried, this flag can be checked to avoid duplicate operations.

Used in: RestoreDappControllersResponse, SetDappControllersCallResult, SetDappControllersResponse.FailedUpdate, SetModeCallResult, SettleCommunityFundParticipationResult

• optional int32 code = 1

• string description = 2

Information about a Neurons' Fund investment. The NNS Governance canister is the controller of these neurons.

Used in: SnsNeuronRecipe

• string hotkey_principal = 1

• fixed64 nns_neuron_id = 2

Represents one NNS neuron from the Neurons' Fund participating in this swap.

Used in: CfParticipant

• fixed64 nns_neuron_id = 1

  The NNS neuron ID of the participating neuron.

• uint64 amount_icp_e8s = 2

  The amount of ICP that the Neurons' Fund invests associated with this neuron.

• optional bool has_created_neuron_recipes = 3

  Idempotency flag indicating whether the neuron recipes have been created for the CfNeuron. When set to true, it signifies that the action of creating neuron recipes has been performed on this structure. If the action is retried, this flag can be checked to avoid duplicate operations.

Represents a Neurons' Fund participant, possibly with several neurons.

Used in: ic_nns_governance.pb.v1.ProposalData, ListCommunityFundParticipantsResponse, NeuronsFundParticipants, OpenRequest, Swap

• string hotkey_principal = 1

  The principal that can vote on behalf of these Neurons' Fund neurons.

• repeated CfNeuron cf_neurons = 2

  Information about the participating neurons. Must not be empty.

Used in: GetStateResponse

• uint64 buyer_total_icp_e8s = 1

• optional uint64 direct_participant_count = 3

  Current number of non-Neurons' Fund swap participants

• optional uint64 cf_participant_count = 4

  Current number of Neurons' Fund swap participants. In particular, it's the number of unique controllers of the neurons participating in the Neurons' Fund.

• optional uint64 cf_neuron_count = 5

  Current number of Neurons' Fund neurons participating in the swap May be greater than cf_participant_count if multiple neurons in the Neurons' Fund have the same controller.

• float sns_tokens_per_icp = 2

  Current approximate rate SNS tokens per ICP. Note that this should not be used for super precise financial accounting, because this is floating point.

• optional uint64 direct_participation_icp_e8s = 6

  Current amount of contributions from direct swap participants.

• optional uint64 neurons_fund_participation_icp_e8s = 7

  Current amount that the Neurons' Fund promises to participate with if the swap were to successfully finalize now. Until the swap's success criterium is satisfied, this value is merely a progress indicator.

Information about a direct investor.

Used in: SnsNeuronRecipe

• string buyer_principal = 1

Request a refund of tokens that were sent to the canister in error. The refund is always on the ICP ledger, from this canister's subaccount of the caller to the account of the caller.

• optional ic_base_types.pb.v1.PrincipalId source_principal_id = 1

  Principal who originally sent the funds to us, and is now asking for any unaccepted balance to be returned.

• oneof result

  • ErrorRefundIcpResponse.Ok ok = 1

  • ErrorRefundIcpResponse.Err err = 2

Request was not successful, and no funds were transferred.

Used in: ErrorRefundIcpResponse

• optional Err.Type error_type = 1

• optional string description = 2

Used in: Err

• TYPE_UNSPECIFIED = 0

• TYPE_INVALID_REQUEST = 1

  There is something wrong with the request. If repeated, the request will always be rejected.

• TYPE_PRECONDITION = 2

  Most likely, the canister is in the wrong Lifecycle. More generally, the system is not yet in a state where the request can be fulfilled, but it might enter a suitable state later. In this case, the same request might be accepted later.

• TYPE_EXTERNAL = 3

  Most likely, a request to the ledger failed, in which case, it can be assumed that no funds were transferred. In general, this is caused by something outside this canister, which usually means some other canister (such as ledger).

Request was completed successfully.

Used in: ErrorRefundIcpResponse

• optional uint64 block_height = 1

  The ledger transfer went through at this block height.

Once a swap is committed or aborted, the tokens need to be distributed, and, if the swap was committed, neurons created.

(message has no fields)

Response from the `finalize_swap` canister API.

Used in: GetAutoFinalizationStatusResponse, Swap

• optional SweepResult sweep_icp_result = 1

• optional SweepResult sweep_sns_result = 2

• optional SweepResult claim_neuron_result = 3

• optional SetModeCallResult set_mode_call_result = 4

• optional SetDappControllersCallResult set_dapp_controllers_call_result = 5

• optional SettleCommunityFundParticipationResult settle_community_fund_participation_result = 6

• optional SweepResult create_sns_neuron_recipes_result = 8

• optional SettleNeuronsFundParticipationResult settle_neurons_fund_participation_result = 9

• optional string error_message = 7

  Explains what (if anything) went wrong.

(message has no fields)

• optional bool is_auto_finalize_enabled = 1

  Reflects whether auto-finalization has been enabled via in the init parameters (`should_auto_finalize`).

• optional bool has_auto_finalize_been_attempted = 2

  True if and only if auto-finalization has been started.

• optional FinalizeSwapResponse auto_finalize_swap_response = 3

  Will be populated with the FinalizeSwapResponse once auto-finalization has completed.

• optional ic_base_types.pb.v1.PrincipalId principal_id = 1

  The principal_id of the user who's buyer state is being queried for.

• optional BuyerState buyer_state = 1

(message has no fields)

• uint64 buyers_total = 1

  The total amount of ICP deposited by buyers.

(message has no fields)

Request struct for the method `get_derived_state`

(message has no fields)

Response struct for the method `get_derived_state`

• optional uint64 buyer_total_icp_e8s = 1

• optional uint64 direct_participant_count = 3

  Current number of non-Neurons' Fund swap participants

• optional uint64 cf_participant_count = 4

  Current number of Neurons' Fund swap participants. In particular, it's the number of unique controllers of the neurons participating in the Neurons' Fund.

• optional uint64 cf_neuron_count = 5

  Current number of Neurons' Fund neurons participating in the swap May be greater than cf_participant_count if multiple neurons in the Neurons' Fund have the same controller.

• optional double sns_tokens_per_icp = 2

• optional uint64 direct_participation_icp_e8s = 6

  Current amount of contributions from direct swap participants.

• optional uint64 neurons_fund_participation_icp_e8s = 7

  Current amount of contributions from the Neurons' Fund.

Request struct for the method `get_init`

(message has no fields)

Response struct for the method `get_init`

• optional Init init = 1

Request struct for the method `get_lifecycle`

(message has no fields)

Response struct for the method `get_lifecycle`

• optional Lifecycle lifecycle = 1

• optional uint64 decentralization_sale_open_timestamp_seconds = 2

• optional uint64 decentralization_swap_termination_timestamp_seconds = 3

Request struct for the method `get_open_ticket`

(message has no fields)

Response struct for the method `get_open_ticket`

• oneof result

  • GetOpenTicketResponse.Ok ok = 1

  • GetOpenTicketResponse.Err err = 2

Request was not successful, and no ticket was created.

Used in: GetOpenTicketResponse

• optional Err.Type error_type = 1

Used in: Err

• TYPE_UNSPECIFIED = 0

• TYPE_SALE_NOT_OPEN = 1

• TYPE_SALE_CLOSED = 2

Request was completed successfully.

Used in: GetOpenTicketResponse

• optional Ticket ticket = 1

  If there is an open swap ticket for the caller then this field contains it.

Request struct for the method `get_sale_parameters`.

(message has no fields)

Response struct for the method `get_sale_parameters`.

• optional Params params = 1

TODO: introduce a limits on the number of buyers to include?

(message has no fields)

• optional Swap swap = 1

• optional DerivedState derived = 2

Copied from nns governance.proto.

Used in: SettleCommunityFundParticipationResult.Response, SettleNeuronsFundParticipationResponse

• GovernanceError.ErrorType error_type = 1

• string error_message = 2

Used in: GovernanceError

• ERROR_TYPE_UNSPECIFIED = 0

• ERROR_TYPE_OK = 1

  The operation was successfully completed.

• ERROR_TYPE_UNAVAILABLE = 2

  This operation is not available, e.g., not implemented.

• ERROR_TYPE_NOT_AUTHORIZED = 3

  The caller is not authorized to perform this operation.

• ERROR_TYPE_NOT_FOUND = 4

  Some entity required for the operation (for example, a neuron) was not found.

• ERROR_TYPE_INVALID_COMMAND = 5

  The command was missing or invalid. This is a permanent error.

• ERROR_TYPE_REQUIRES_NOT_DISSOLVING = 6

  The neuron is dissolving or dissolved and the operation requires it to be not dissolving (that is, having a non-zero dissolve delay that is accumulating age).

• ERROR_TYPE_REQUIRES_DISSOLVING = 7

  The neuron is not dissolving or dissolved and the operation requires it to be dissolving (that is, having a non-zero dissolve delay with zero age that is not accumulating).

• ERROR_TYPE_REQUIRES_DISSOLVED = 8

  The neuron is not dissolving and not dissolved and the operation requires it to be dissolved (that is, having a dissolve delay of zero and an age of zero).

• ERROR_TYPE_HOT_KEY = 9

  When adding or removing a hot key: the key to add was already present or the key to remove was not present or the key to add was invalid or adding another hot key would bring the total number of the maximum number of allowed hot keys per neuron.

• ERROR_TYPE_RESOURCE_EXHAUSTED = 10

  Some canister side resource is exhausted, so this operation cannot be performed.

• ERROR_TYPE_PRECONDITION_FAILED = 11

  Some precondition for executing this method was not met (e.g. the neuron's dissolve time is too short). There could be a change in the state of the system such that the operation becomes allowed (e.g. the owner of the neuron increases its dissolve delay).

• ERROR_TYPE_EXTERNAL = 12

  Executing this method failed for some reason external to the governance canister.

• ERROR_TYPE_LEDGER_UPDATE_ONGOING = 13

  A neuron has an ongoing ledger update and thus can't be changed.

• ERROR_TYPE_INSUFFICIENT_FUNDS = 14

  There wasn't enough funds to perform the operation.

• ERROR_TYPE_INVALID_PRINCIPAL = 15

  The principal provided was invalid.

• ERROR_TYPE_INVALID_PROPOSAL = 16

  The proposal is defective in some way (e.g. title is too long). If the same proposal is submitted again without modification, it will be rejected regardless of changes in the system's state (e.g. increasing the neuron's dissolve delay will not make the proposal acceptable).

• ERROR_TYPE_ALREADY_JOINED_COMMUNITY_FUND = 17

  The neuron attempted to join the Neurons' Fund while already a member.

• ERROR_TYPE_NOT_IN_THE_COMMUNITY_FUND = 18

  The neuron attempted to leave the Neurons' Fund but is not a member.

ICRC-1 Account. See https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1

Used in: Ticket

• optional ic_base_types.pb.v1.PrincipalId owner = 1

• optional bytes subaccount = 2

This function is called "ideal" because it serves as the guideline that the Neurons' Fund will try to follow, but may deviate from in order to satisfy SNS-specific participation constraints while allocating its overall participation amount among its neurons' maturity. In contrast, The "effective" matched participation function `crate::neurons_fund::MatchedParticipationFunction` is computed *based* on this one. TODO(NNS1-1589): Until the Jira ticket gets solved, this definition needs to be synchronized with that from nns/governance/proto/ic_nns_governance/pb/v1/governance.proto.

Used in: NeuronsFundParticipationConstraints

• optional string serialized_representation = 1

  The encoding of the "ideal" matched participation function is defined in `crate::neurons_fund`. In the future, we could change this message to represent full abstract syntactic trees comprised of elementary mathematical operators, with literals and variables as tree leaves.

The initialisation data of the canister. Always specified on canister creation, and cannot be modified afterwards. If the initialization parameters are incorrect, the swap will immediately be aborted.

Used in: GetInitResponse, Swap

• string nns_governance_canister_id = 1

  The canister ID of the NNS governance canister. This is the only principal that can open the swap.

• string sns_governance_canister_id = 2

  The canister ID of the governance canister of the SNS that this token swap pertains to.

• string sns_ledger_canister_id = 3

  The ledger canister of the SNS.

• string icp_ledger_canister_id = 4

  The ledger canister for the base token, typically ICP. The base token is typically ICP, but this assumption is not used anywhere, so, in principle, any token type can be used as base token.

• string sns_root_canister_id = 12

  Analogous to `sns_governance_canister_id`, but for the "root" canister instead of the governance canister.

• repeated string fallback_controller_principal_ids = 11

  If the swap is aborted, control of the canister(s) should be set to these principals. Must not be empty.

• optional uint64 transaction_fee_e8s = 13

  Same as SNS ledger. Must hold the same value as SNS ledger. Whether the values match is not checked. If they don't match things will break.

• optional uint64 neuron_minimum_stake_e8s = 14

  Same as SNS governance. Must hold the same value as SNS governance. Whether the values match is not checked. If they don't match things will break.

• optional string confirmation_text = 15

  An optional text that swap participants should confirm before they may participate in the swap. If the field is set, its value should be plain text with at least 1 and at most 1,000 characters.

• optional ic_nervous_system.pb.v1.Countries restricted_countries = 16

  An optional set of countries that should not participate in the swap.

• optional uint32 min_participants = 17

  The minimum number of buyers that must participate for the swap to take place. Must be greater than zero.

• optional uint64 min_icp_e8s = 18

  The total number of ICP that is required for this token swap to take place. This number divided by the number of SNS tokens being offered gives the seller's reserve price for the swap, i.e., the minimum number of ICP per SNS tokens that the seller of SNS tokens is willing to accept. If this amount is not achieved, the swap will be aborted (instead of committed) when the due date/time occurs. Must be smaller than or equal to `max_icp_e8s`.

• optional uint64 max_icp_e8s = 19

  The number of ICP that is "targeted" by this token swap. If this amount is achieved with sufficient participation, the swap will be triggered immediately, without waiting for the due date (`end_timestamp_seconds`). This means that an investor knows the minimum number of SNS tokens received per invested ICP. If this amount is achieved without reaching sufficient_participation, the swap will abort without waiting for the due date. Must be at least `min_participants * min_participant_icp_e8s`

• optional uint64 min_direct_participation_icp_e8s = 30

  The total number of ICP that is required to be "directly contributed" for this token swap to take place. This number divided by the number of SNS tokens being offered gives the seller's reserve price for the swap, i.e., the minimum number of ICP per SNS tokens that the seller of SNS tokens is willing to accept. If this amount is not achieved, the swap will be aborted (instead of committed) when the due date/time occurs. Must be smaller than or equal to `max_icp_e8s`.

• optional uint64 max_direct_participation_icp_e8s = 31

  The number of ICP that is "targeted" by this token swap. If this amount is achieved with sufficient participation, the swap will be triggered immediately, without waiting for the due date (`end_timestamp_seconds`). This means that an investor knows the minimum number of SNS tokens received per invested ICP. If this amount is achieved without reaching sufficient_participation, the swap will abort without waiting for the due date. Must be at least `min_participants * min_participant_icp_e8s`.

• optional uint64 min_participant_icp_e8s = 20

  The minimum amount of ICP that each buyer must contribute to participate. Must be greater than zero.

• optional uint64 max_participant_icp_e8s = 21

  The maximum amount of ICP that each buyer can contribute. Must be greater than or equal to `min_participant_icp_e8s` and less than or equal to `max_icp_e8s`. Can effectively be disabled by setting it to `max_icp_e8s`.

• optional uint64 swap_start_timestamp_seconds = 22

  The date/time when the swap should start.

• optional uint64 swap_due_timestamp_seconds = 23

  The date/time when the swap is due, i.e., it will automatically end and commit or abort depending on whether the parameters have been fulfilled.

• optional uint64 sns_token_e8s = 24

  The number of tokens (of `init.sns_ledger_canister_id`) that are being offered. The tokens are held in escrow for the SNS governance canister. Invariant for the OPEN state: ```text state.sns_token_e8s <= token_ledger.balance_of(<swap-canister>) ```

• optional NeuronBasketConstructionParameters neuron_basket_construction_parameters = 25

  The construction parameters for the basket of neurons created for all investors in the decentralization swap. Each investor, whether via the Neurons' Fund or direct, will receive `count` Neurons with increasing dissolve delays. The total number of Tokens swapped for by the investor will be evenly distributed across the basket. This is effectively a vesting schedule to ensure there is a gradual release of SNS Tokens available to all investors instead of being liquid immediately. See `NeuronBasketConstructionParameters` for more details on how the basket is configured.

• optional uint64 nns_proposal_id = 26

  The ID of the NNS proposal submitted to launch this SNS decentralization swap.

• optional NeuronsFundParticipants neurons_fund_participants = 27

  The Neurons' Fund participants of this SNS decentralization swap.

• optional bool should_auto_finalize = 28

  Controls whether swap finalization should be attempted automatically in the canister heartbeat. If set to false, `finalize_swap` must be called manually. Note: it is safe to call `finalize_swap` multiple times (regardless of the value of this field).

• optional NeuronsFundParticipationConstraints neurons_fund_participation_constraints = 29

  Constraints for the Neurons' Fund participation in this swap.

• optional bool neurons_fund_participation = 32

  Whether Neurons' Fund participation is requested.

Lifecycle states of the swap canister. The details of their meanings are provided in the documentation of the `Swap` message.

Used in: ic_nns_governance.pb.v1.ProposalData, GetLifecycleResponse, Swap

• LIFECYCLE_UNSPECIFIED = 0

  The canister is incorrectly configured. Not a real lifecycle state.

• LIFECYCLE_PENDING = 1

  In PENDING state, the canister is correctly initialized. Once SNS tokens have been transferred to the swap canister's account on the SNS ledger, a call to `open` with valid parameters will start the swap.

• LIFECYCLE_ADOPTED = 5

  In ADOPTED state, the proposal to start the decentralization swap has been adopted, and the swap will be automatically opened after a delay. In the legacy (non-one-proposal) flow, the swap delay is specified by params.sale_delay_seconds. In the one-proposal flow, the swap delay is specified by `init.swap_start_timestamp_seconds`.

• LIFECYCLE_OPEN = 2

  In OPEN state, prospective buyers can register for the token swap. The swap will be committed when the target (max) ICP has been reached or the swap's due date/time occurs, whichever happens first.

• LIFECYCLE_COMMITTED = 3

  In COMMITTED state the token price has been determined; on a call to finalize`, buyers receive their SNS neurons and the SNS governance canister receives the ICP.

• LIFECYCLE_ABORTED = 4

  In ABORTED state the token swap has been aborted, e.g., because the due date/time occurred before the minimum (reserve) amount of ICP has been retrieved. On a call to `finalize`, participants get their ICP refunded.

Some Neurons' Fund neurons might be too small, and some might be too large to participate in a given SNS swap. This causes the need to adjust Neurons' Fund participation from an "ideal" amount to an "effective" amount. * The ideal-participation of the Neurons' Fund refers to the value dictated by some curve that specifies how direct contributions should be matched with Neurons' Fund maturity. * The effective-participation of the Neurons' Fund refers to the value that the NNS Governance can actually allocate, given (1) the configuration of the Neurons' Fund at the time of execution of the corresponding CreateServiceNervousSystem proposal and (2) the amount of direct participation. This structure represents the coefficients of a linear transformation used for mapping the Neurons' Fund ideal-participation to effective-participation on a given linear (semi-open) interval. Say we have the following function for matching direct participants' contributions: `f: ICP e8s -> ICP e8s`; then the *ideal* Neuron's Fund participation amount corresponding to the direct participation of `x` ICP e8s is `f(x)`, while the Neuron's Fund *effective* participation amount is: ``` g(x) = (c.slope_numerator / c.slope_denominator) * f(x) + c.intercept ``` where `c: LinearScalingCoefficient` with `c.from_direct_participation_icp_e8s <= x < c.to_direct_participation_icp_e8s`. Note that we represent the slope as a rational number (as opposed to floating point), enabling equality comparison between two instances of this structure.

Used in: NeuronsFundParticipationConstraints

• optional uint64 from_direct_participation_icp_e8s = 1

  (Included) lower bound on the amount of direct participation (in ICP e8s) at which these coefficients apply.

• optional uint64 to_direct_participation_icp_e8s = 2

  (Excluded) upper bound on the amount of direct participation (in ICP e8s) at which these coefficients apply.

• optional uint64 slope_numerator = 3

  Numerator or the slope of the linear transformation.

• optional uint64 slope_denominator = 4

  Denominator or the slope of the linear transformation.

• optional uint64 intercept_icp_e8s = 5

  Intercept of the linear transformation (in ICP e8s).

Request struct for the method `list_community_fund_participants`.

• optional uint32 limit = 1

  The maximum number of elements that will be in the response. This is capped at 10_000.

• optional uint64 offset = 2

  Skip the first `offset` elements when constructing the response

Response struct for the method `list_community_fund_participants`.

• repeated CfParticipant cf_participants = 1

Request struct for the method `list_direct_participants`. This method paginates over all direct participants in the decentralization swap. Direct participants are participants who did not participate via the Neurons' Fund.

• optional uint32 limit = 1

  The limit of the number of Participants returned in each page, in range [0, 30,000]. If no value, or a value outside of this range is requested, 30,000 will be used.

• optional uint32 offset = 2

  Skip the first `offset` elements when constructing the response.

Response struct for the method `list_direct_participants`.

• repeated Participant participants = 1

  The list of Participants returned from the invocation of `list_direct_participants`. The list is a page of all the buyers in the Swap canister at the time of the method call. The size of the page is equal to either: - the max page size (30,000), - the corresponding `ListDirectParticipantsRequest.limit`, - the remaining Participants, if there are fewer than `limit` participants left. Pagination through the entire list of participants is complete if len(participants) < `ListDirectParticipantsRequest.limit`.

Request for the method `list_sns_neuron_recipes`

• optional uint32 limit = 1

  The maximum number of elements that will be in the response. This is capped at 10_000.

• optional uint64 offset = 2

  Skip the first `offset` elements when constructing the response

Response for the method `list_sns_neuron_recipes`

• repeated SnsNeuronRecipe sns_neuron_recipes = 1

The construction parameters for the basket of neurons created for all investors in the decentralization swap.

Used in: Init, Params

• uint64 count = 1

  The number of neurons each investor will receive after the decentralization swap. The total tokens swapped for will be evenly distributed across the `count` neurons.

• uint64 dissolve_delay_interval_seconds = 2

  The amount of additional time it takes for the next neuron to dissolve.

The id of a specific neuron, which equals the neuron's subaccount on the ledger canister (the account that holds the neuron's staked tokens).

Used in: SnsNeuronRecipe.NeuronAttributes

• bytes id = 1

Represents multiple Neurons' Fund participants.

Used in: Init

• repeated CfParticipant cf_participants = 1

Constraints for the Neurons' Fund participation in an SNS swap.

Used in: Init

• optional uint64 min_direct_participation_threshold_icp_e8s = 1

  The Neurons' Fund will not participate in this swap unless the direct contributions reach this threshold (in ICP e8s).

• optional uint64 max_neurons_fund_participation_icp_e8s = 2

  Maximum amount (in ICP e8s) of contributions from the Neurons' Fund to this swap.

• repeated LinearScalingCoefficient coefficient_intervals = 3

  List of intervals in which the given linear coefficients apply for scaling the ideal Neurons' Fund participation amount (down) to the effective Neurons' Fund participation amount.

• optional IdealMatchedParticipationFunction ideal_matched_participation_function = 4

  The function used in the implementation of Matched Funding for mapping amounts of direct participation to "ideal" Neurons' Fund participation amounts. The value needs to be adjusted to a potentially smaller value due to SNS-specific participation constraints and the configuration of the Neurons' Fund at the time of the CreateServiceNervousSystem proposal execution.

Request struct for the method `new_sale_ticket`

• uint64 amount_icp_e8s = 1

  The user-set amount of the ticket in ICP e8s

• optional bytes subaccount = 2

  The subaccount of the caller to be used for the ticket

Response struct for the method `new_sale_ticket`

• oneof result

  • NewSaleTicketResponse.Ok ok = 1

  • NewSaleTicketResponse.Err err = 2

Request was not successful, and no ticket was created.

Used in: NewSaleTicketResponse

• Err.Type error_type = 1

• optional Err.InvalidUserAmount invalid_user_amount = 2

  When `error_type` is `INVALID_USER_AMOUNT` then this field describes the minimum and maximum amounts.

• optional Ticket existing_ticket = 3

  When `error_type` is `TICKET_EXISTS` then this field contains the ticket that already exists.

Used in: Err

• uint64 min_amount_icp_e8s_included = 1

• uint64 max_amount_icp_e8s_included = 2

Used in: Err

• TYPE_UNSPECIFIED = 0

• TYPE_SALE_NOT_OPEN = 1

• TYPE_SALE_CLOSED = 2

• TYPE_TICKET_EXISTS = 3

  There is already an open ticket associated with the caller. When this is the `error_type`, then the field existing_ticket is set and contains the ticket itself.

• TYPE_INVALID_USER_AMOUNT = 4

  The amount sent by the user is not within the Swap parameters. When this is the `error_type`, then the field invalid_user_amount is set and describes minimum and maximum amounts.

• TYPE_INVALID_SUBACCOUNT = 5

  The specified subaccount is not a valid subaccount (length != 32 bytes).

• TYPE_INVALID_PRINCIPAL = 6

  The specified principal is forbidden from creating tickets.

Request was completed successfully.

Used in: NewSaleTicketResponse

• optional Ticket ticket = 1

  The created ticket.

Request struct for the method `notify_payment_failure`

(message has no fields)

Response for the method `notify_payment_failure` Returns the ticket if a ticket was found for the caller and the ticket was removed successfully. Returns None if no ticket was found for the caller.

• optional Ticket ticket = 1

• optional Params params = 1

  The parameters of the swap.

• repeated CfParticipant cf_participants = 2

  Neurons' Fund participation.

• optional uint64 open_sns_token_swap_proposal_id = 3

  The ID of the proposal whose execution consists of calling this method.

(message has no fields)

The parameters of the swap, provided in the call to `open`. Cannot be modified after the call to `open`.

Used in: ic_nns_governance.pb.v1.OpenSnsTokenSwap, GetSaleParametersResponse, OpenRequest, Swap

• uint32 min_participants = 1

  The minimum number of buyers that must participate for the swap to take place. Must be greater than zero.

• uint64 min_icp_e8s = 2

  The total number of ICP that is required for this token swap to take place. This number divided by the number of SNS tokens being offered gives the seller's reserve price for the swap, i.e., the minimum number of ICP per SNS tokens that the seller of SNS tokens is willing to accept. If this amount is not achieved, the swap will be aborted (instead of committed) when the due date/time occurs. Must be smaller than or equal to `max_icp_e8s`.

• uint64 max_icp_e8s = 3

  The number of ICP that is "targeted" by this token swap. If this amount is achieved with sufficient participation, the swap will be triggered immediately, without waiting for the due date (`end_timestamp_seconds`). This means that an investor knows the minimum number of SNS tokens received per invested ICP. If this amount is achieved without reaching sufficient_participation, the swap will abort without waiting for the due date. Must be at least `min_participants * min_participant_icp_e8s`.

• optional uint64 min_direct_participation_icp_e8s = 10

  The total number of ICP that is required for this token swap to take place. This number divided by the number of SNS tokens being offered gives the seller's reserve price for the swap, i.e., the minimum number of ICP per SNS tokens that the seller of SNS tokens is willing to accept. If this amount is not achieved, the swap will be aborted (instead of committed) when the due date/time occurs. Must be smaller than or equal to `max_icp_e8s`.

• optional uint64 max_direct_participation_icp_e8s = 11

  The number of ICP that is "targeted" by this token swap. If this amount is achieved with sufficient participation, the swap will be triggered immediately, without waiting for the due date (`end_timestamp_seconds`). This means that an investor knows the minimum number of SNS tokens received per invested ICP. If this amount is achieved without reaching sufficient_participation, the swap will abort without waiting for the due date. Must be at least `min_participants * min_participant_icp_e8s`.

• uint64 min_participant_icp_e8s = 4

  The minimum amount of ICP that each buyer must contribute to participate. Must be greater than zero.

• uint64 max_participant_icp_e8s = 5

  The maximum amount of ICP that each buyer can contribute. Must be greater than or equal to `min_participant_icp_e8s` and less than or equal to `max_icp_e8s`. Can effectively be disabled by setting it to `max_icp_e8s`.

• uint64 swap_due_timestamp_seconds = 6

  The date/time when the swap is due, i.e., it will automatically end and commit or abort depending on whether the parameters have been fulfilled.

• uint64 sns_token_e8s = 7

  The number of tokens (of `init.sns_ledger_canister_id`) that are being offered. The tokens are held in escrow for the SNS governance canister. Invariant for the OPEN state: ```text state.sns_token_e8s <= token_ledger.balance_of(<swap-canister>) ```

• optional NeuronBasketConstructionParameters neuron_basket_construction_parameters = 8

  The construction parameters for the basket of neurons created for all investors in the decentralization swap. Each investor, whether via the Neurons' Fund or direct, will receive `count` Neurons with increasing dissolve delays. The total number of Tokens swapped for by the investor will be evenly distributed across the basket. This is effectively a vesting schedule to ensure there is a gradual release of SNS Tokens available to all investors instead of being liquid immediately. See `NeuronBasketConstructionParameters` for more details on how the basket is configured.

• optional uint64 sale_delay_seconds = 9

  An optional delay, so that the actual swap does not get opened immediately after the adoption of the swap proposal.

A direct Participant in the decentralization swap.

Used in: ListDirectParticipantsResponse

• optional ic_base_types.pb.v1.PrincipalId participant_id = 1

  The PrincipalId of the participant.

• optional BuyerState participation = 2

  The BuyerState of the participant, which includes the amount of participation in e8s of a Token, and the transfer status of those tokens.

Informs the swap canister that a buyer has sent funds to participate in the swap. Only in lifecycle state `open`.

• string buyer = 1

  If not specified, the caller is used.

• optional string confirmation_text = 2

  To accept the swap participation confirmation, a participant should send the confirmation text via refresh_buyer_tokens, matching the text set during SNS initialization.

• uint64 icp_accepted_participation_e8s = 1

• uint64 icp_ledger_account_balance_e8s = 2

Request struct for the method restore_dapp_controllers.

(message has no fields)

Response of the method restore_dapp_controllers. Analogous to Rust type Result<SetDappControllersResponse, CanisterCallError>.

• oneof possibility

  • SetDappControllersResponse ok = 1

    TODO(NNS1-1589): Uncomment. ic_sns_root.pb.v1.

  • CanisterCallError err = 2

Analogous to Rust type Result<SetDappControllersResponse, CanisterCallError>.

Used in: FinalizeSwapResponse

• oneof possibility

  • SetDappControllersResponse ok = 1

    TODO(NNS1-1589): Uncomment. ic_sns_root.pb.v1.

  • CanisterCallError err = 2

Change control of the listed canisters to the listed principal id. Copy of the type in root.proto. TODO(NNS1-1589)

• optional SetDappControllersRequest.CanisterIds canister_ids = 1

• repeated ic_base_types.pb.v1.PrincipalId controller_principal_ids = 2

Used in: SetDappControllersRequest

• repeated ic_base_types.pb.v1.PrincipalId canister_ids = 1

Used in: RestoreDappControllersResponse, SetDappControllersCallResult

• repeated SetDappControllersResponse.FailedUpdate failed_updates = 1

Used in: SetDappControllersResponse

• optional ic_base_types.pb.v1.PrincipalId dapp_canister_id = 1

• optional CanisterCallError err = 2

Analogous to Rust type Result<SetModeResponse, CanisterCallError>.

Used in: FinalizeSwapResponse

• oneof possibility

  • SetModeCallResult.SetModeResult ok = 1

  • CanisterCallError err = 2

Used in: SetModeCallResult

(message has no fields)

Used in: ic_nns_governance.pb.v1.SetSnsTokenSwapOpenTimeWindow

• optional TimeWindow open_time_window = 1

  Duration must be between 1 and 90 days. The TimeWindow's end time but be greater than or equal to the TimeWindow's start time.

Response if setting the open time window succeeded.

(message has no fields)

Copied from nns governance.proto.

• optional uint64 open_sns_token_swap_proposal_id = 1

  The caller's principal ID must match the value in the target_swap_canister_id field in the proposal (more precisely, in the OpenSnsTokenSwap).

• oneof result

  Each of the possibilities here corresponds to one of two ways that a swap can terminate. See also sns_swap_pb::Lifecycle::is_terminal.

  • SettleCommunityFundParticipation.Committed committed = 2

  • SettleCommunityFundParticipation.Aborted aborted = 3

When this happens, maturity needs to be restored to Neurons' Fund neurons. The amounts to be refunded can be found in the ProposalData's `cf_participants` field.

Used in: SettleCommunityFundParticipation

(message has no fields)

When this happens, ICP needs to be minted, and sent to the SNS governance canister's main account on the ICP Ledger. As with Aborted, the amount of ICP that needs to be minted can be deduced from the ProposalData's cf_participants field.

Used in: SettleCommunityFundParticipation

• optional ic_base_types.pb.v1.PrincipalId sns_governance_canister_id = 1

  This is where the minted ICP will be sent. In principal, this could be fetched using the swap canister's get_state method.

• optional uint64 total_direct_contribution_icp_e8s = 2

  Total amount of contributions from direct swap participants.

• optional uint64 total_neurons_fund_contribution_icp_e8s = 3

  Total amount of contributions from the Neuron's Fund. TODO[NNS1-2570]: Ensure this field is set.

Used in: FinalizeSwapResponse

• oneof possibility

  • SettleCommunityFundParticipationResult.Response ok = 1

  • CanisterCallError err = 2

Used in: SettleCommunityFundParticipationResult

• optional GovernanceError governance_error = 1

  Can be blank.

Request to settle the Neurons' Fund participation in this SNS Swap. When a swap ends, the Swap canister notifies the Neurons' Fund of the swap's ultimate result, which can be either `Committed` or `Aborted`. Note that currently, the Neurons' Fund is managed by the NNS Governance canister. * If the result is `Committed`: - Neurons' Fund computes the "effective" participation amount for each of its neurons (as per the Matched Funding rules). This computation is based on the total direct participation amount, which is thus a field of `Committed`. - Neurons' Fund converts the "effective" amount of maturity into ICP by: - Requesting the ICP Ledger to mint an appropriate amount of ICP tokens and sending them to the SNS treasury. - Refunding whatever maturity is left over (the maximum possible maturity is reserved by the Neurons' Fund before the swap begins). - Neurons' Fund returns the Neurons' Fund participants back to the Swap canister (see SettleNeuronsFundParticipationResponse). - The Swap canister then creates SNS neurons for the Neurons' Fund participants. * If the result is Aborted, the Neurons' Fund is refunded for all maturity reserved for this SNS. This design assumes trust between the Neurons' Fund and the SNS Swap canisters. In the one hand, the Swap trusts that the Neurons' Fund sends the correct amount of ICP to the SNS treasury, and that the Neurons' Fund allocates its participants following the Matched Funding rules. On the other hand, the Neurons' Fund trusts that the Swap will indeed create appropriate SNS neurons for the Neurons' Fund participants. The justification for this trust assumption is as follows. The Neurons' Fund can be trusted as it is controlled by the NNS. The SNS Swap can be trusted as it is (1) deployed by SNS-W, which is also part of the NNS and (2) upgraded via an NNS proposal (unlike all other SNS canisters). This request may be submitted only by the Swap canister of an SNS instance created by a CreateServiceNervousSystem proposal. TODO(NNS1-1589): Until the Jira ticket gets solved, changes here need to be manually propagated to (sns) swap.proto.

• optional uint64 nns_proposal_id = 1

  Proposal ID of the CreateServiceNervousSystem proposal that created this SNS instance.

• oneof result

  Each of the possibilities here corresponds to one of two ways that a swap can terminate. See also sns_swap_pb::Lifecycle::is_terminal.

  • SettleNeuronsFundParticipationRequest.Committed committed = 2

  • SettleNeuronsFundParticipationRequest.Aborted aborted = 3

When this happens, all priorly reserved maturity for this SNS instance needs to be restored to the Neurons' Fund neurons.

Used in: SettleNeuronsFundParticipationRequest

(message has no fields)

When this happens, the NNS Governance needs to do several things: (1) Compute the effective amount of ICP per neuron of the Neurons' Fund as a function of `total_direct_participation_icp_e8s`. The overall Neurons' Fund participation should equal `total_neurons_fund_contribution_icp_e8s`. (2) Mint (via the ICP Ledger) and sent to the SNS governance the amount of `total_neurons_fund_contribution_icp_e8s`. (3) Respond to this request with `SettleNeuronsFundParticipationResponse`, providing the set of `NeuronsFundParticipant`s with the effective amount of ICP per neuron, as computed in step (1). (4) Refund each neuron of the Neurons' Fund with (reserved - effective) amount of ICP. Effective amounts depend on `total_direct_participation_icp_e8s` and the participation limits of a particular SNS instance, namely, each participation must be between `min_participant_icp_e8s` and `max_participant_icp_e8s`. - If a neuron of the Neurons' Fund has less than `min_participant_icp_e8s` worth of maturity, then it is ineligible to participate. - If a neuron of the Neurons' Fund has more than `max_participant_icp_e8s` worth of maturity, then its participation amount is limited to `max_participant_icp_e8s`. Reserved amounts are computed as the minimal upper bound on the effective amounts, i.e., when the value `total_direct_participation_icp_e8s` reaches its theoretical maximum.

Used in: SettleNeuronsFundParticipationRequest

• optional ic_base_types.pb.v1.PrincipalId sns_governance_canister_id = 1

  This is where the minted ICP will be sent.

• optional uint64 total_direct_participation_icp_e8s = 2

  Total amount of participation from direct swap participants.

• optional uint64 total_neurons_fund_participation_icp_e8s = 3

  Total amount of participation from the Neurons' Fund. TODO[NNS1-2570]: Ensure this field is set.

Handling the Neurons' Fund and transferring some of its maturity to an SNS treasury is thus the responsibility of the NNS Governance. When a swap succeeds, a Swap canister should send a `settle_neurons_fund_participation` request to the NNS Governance, specifying its `result` field as `committed`. The NNS Governance then computes the ultimate distribution of maturity in the Neurons' Fund. However, this distribution also needs to be made available to the SNS Swap that will use this information to create SNS neurons of an appropriate size for each Neurons' Fund (as well as direct) participant. That is why in the `committed` case, the NNS Governance should populate the `neurons_fund_participants` field, while in the `aborted` case it should be empty. TODO(NNS1-1589): Until the Jira ticket gets solved, changes here need to be manually propagated to (sns) swap.proto.

• oneof result

  • GovernanceError err = 1

  • SettleNeuronsFundParticipationResponse.Ok ok = 2

Represents one NNS neuron from the Neurons' Fund participating in this swap.

Used in: Ok

• optional uint64 nns_neuron_id = 1

  The NNS neuron ID of the participating neuron.

• optional uint64 amount_icp_e8s = 2

  The amount of Neurons' Fund participation associated with this neuron.

• optional string hotkey_principal = 3

  The principal that can vote on behalf of this neuron.

• optional bool is_capped = 4

  Whether the amount maturity amount of Neurons' Fund participation associated with this neuron has been capped to reflect the maximum participation amount for this SNS swap.

Request was completed successfully.

Used in: SettleNeuronsFundParticipationResponse

• repeated NeuronsFundNeuron neurons_fund_neuron_portions = 1

The result from settling the neurons' fund participation in finalization.

Used in: FinalizeSwapResponse

• oneof possibility

  • SettleNeuronsFundParticipationResult.Ok ok = 1

  • SettleNeuronsFundParticipationResult.Error err = 2

The failure branch of the result. This message can be set for a number of reasons not limited to - invalid state - replica errors - canister errors While some of these errors are transient and can immediately retried, others require manual intervention. The error messages and logs of the canister should provide enough context to debug.

Used in: SettleNeuronsFundParticipationResult

• optional string message = 1

The successful branch of the result. On subsequent attempts to settle neurons fund participation (for example: due to some later stage of finalization failing and a manual retry is invoked), this branch will be set with the results of the original successful attempt.

Used in: SettleNeuronsFundParticipationResult

• optional uint64 neurons_fund_participation_icp_e8s = 1

• optional uint64 neurons_fund_neurons_count = 2

Used in: ListSnsNeuronRecipesResponse, Swap

• optional TransferableAmount sns = 1

• oneof investor

  • DirectInvestment direct = 2

  • CfInvestment community_fund = 3

• optional SnsNeuronRecipe.NeuronAttributes neuron_attributes = 4

  Attributes of the Neuron to be created from the SnsNeuronRecipe

• optional SnsNeuronRecipe.ClaimedStatus claimed_status = 5

  The status of the SnsNeuronRecipe's creation within SNS Governance. This field is used as a journal between calls of `finalize`.

The various statuses of creation that a SnsNeuronRecipe can have in an SNS.

Used in: SnsNeuronRecipe

• CLAIMED_STATUS_UNSPECIFIED = 0

  Unused, here for PB lint purposes.

• CLAIMED_STATUS_PENDING = 1

  The Neuron is pending creation and can be claimed in SNS Governance.

• CLAIMED_STATUS_SUCCESS = 2

  The Neuron has been created successfully in SNS Governance.

• CLAIMED_STATUS_FAILED = 3

  The Neuron has previously failed to be created in SNS Governance, but can be retried in the future.

• CLAIMED_STATUS_INVALID = 4

  The Neuron is invalid and was not created in SNS Governance. This neuron cannot be retried without manual intervention to update its `NeuronParameters`.

Attributes of the Neuron to be created from the SnsNeuronRecipe

Used in: SnsNeuronRecipe

• uint64 memo = 1

  The memo to be used when calculating the Neuron's staking account in the SNS Ledger. See `nervous_system_common::compute_neuron_staking_subaccount`. The memo is used along with the a principal_id of the "controller" of the neuron. In the case of the decentralization sale, that will either be the PrincipalId of NNS Governance canister for Neurons' Fund investors, or the PrincipalId of the direct investor.

• uint64 dissolve_delay_seconds = 2

  The dissolve delay in seconds that the Neuron will be created with.

• repeated NeuronId followees = 3

  The list of NeuronIds that the created Neuron will follow on all SNS proposal actions known to governance at the time. Additional followees and following relations can be added after neuron creation. TODO[NNS1-1589] Due to the dependency cycle, the `swap` canister's protobuf cannot directly depend on SNS Governance NeuronId type. The followees NeuronId's are of a duplicated type, which is converted to SNS governance NeuronId at the time. of claiming.

The `swap` canister smart contract is used to perform a type of single-price auction (SNS/ICP) of one token type SNS for another token type ICP (this is typically ICP, but can be treated as a variable) at a specific date/time in the future. Such a single-price auction is typically used to decentralize an SNS, i.e., to ensure that a sufficient number of governance tokens of the SNS are distributed among different participants. State (lifecycle) diagram for the swap canister's state. ```text sufficient_participation && (swap_due || icp_target_reached) PENDING -------------------> ADOPTED ---------------------> OPEN -----------------------------------------> COMMITTED Swap receives a request The opening delay | | from NNS governance to has elapsed | not sufficient_participation | schedule opening | && (swap_due || icp_target_reached) | v v ABORTED ---------------------------------------> <DELETED> ``` Here `sufficient_participation` means that the minimum number of participants `min_participants` has been reached, each contributing between `min_participant_icp_e8s` and `max_participant_icp_e8s`, and their total contributions add up to at least `min_icp_e8s` and at most `max_icp_e8s`. `icp_target_reached` means that the total amount of ICP contributed is equal to `max_icp_e8s`. (The total amount of ICP contributed should never be greater than `max_icp_e8s`.) The dramatis personae of the `swap` canister are as follows: - The swap canister itself. - The NNS governance canister - which is the only principal that can open the swap. - The governance canister of the SNS to be decentralized. - The ledger canister of the SNS, i.e., the ledger of the token type being sold. - The ICP ledger canister, or more generally of the base currency of the auction. - The root canister of the SNS to control aspects of the SNS not controlled by the SNS governance canister. When the swap canister is initialized, it must be configured with the canister IDs of the other participant canisters. The next step is to provide SNS tokens for the swap. This normally happens when the canister is in the PENDING state, and the amount is validated in the call to `open`. The request to open the swap has to originate from the NNS governance canister. The request specifies the parameters of the swap, i.e., the date/time at which the token swap will take place, the minimal number of participants, the minimum number of base tokens (ICP) of each participant, as well as the minimum and maximum number (reserve and target) of base tokens (ICP) of the swap. Step 0. The canister is created, specifying the initialization parameters, which are henceforth fixed for the lifetime of the canister. Step 1 (State PENDING). The swap canister is loaded with the right amount of SNS tokens. A call to `open` will then transition the canister to the OPEN state. Step 2a. (State ADOPTED). The field `params` is received as an argument to the call to `open` and is henceforth immutable. The amount of SNS token is verified against the SNS ledger. The swap will be opened after an optional delay. The transition to OPEN happens automatically (on the canister heartbeat) when the delay elapses. Step 2a. (State OPEN). The delay has elapsed and the swap is open for participants who can enter into the auction with a number of ICP tokens until either the target amount has been reached or the auction is due, i.e., the date/time of the auction has been reached. The transition to COMMITTED or ABORTED happens automatically (on the canister heartbeat) when the necessary conditions are fulfilled. Step 3a. (State COMMITTED). Tokens are allocated to participants at a single clearing price, i.e., the number of SNS tokens being offered divided by the total number of ICP tokens contributed to the swap. In this state, a call to `finalize` will create SNS neurons for each participant and transfer ICP to the SNS governance canister. The call to `finalize` does not happen automatically (i.e., on the canister heartbeat) so that there is a caller to respond to with potential errors. Step 3b. (State ABORTED). If the parameters of the swap have not been satisfied before the due date/time, the swap is aborted and the ICP tokens transferred back to their respective owners. The swap can also be aborted early if it is determined that the swap cannot possibly succeed, e.g., because the ICP ceiling has been reached and the minimum number of participants has not been. The `swap` canister can be deleted when all tokens registered with the `swap` canister have been disbursed to their rightful owners. The logic of this canister is based on the following principles. * Message fields are never removed. * Integer and enum fields can only have their values increase (with one exception, viz., the timestamp field for the start of a transfer is reset if the transfer fails). Data flow for the Neurons' Fund. - A SNS is created. - Proposal to open a decentralization swap for the SNS is submitted to the NNS. - ProposalToOpenDecentralizationSale - The Neurons' Fund investment amount - The parameters of the decentralization swap (`Params`). - Call to open swap: - Parameters - Neurons' Fund investments - NNS Proposal ID of the NNS proposal to open the swap. - On accept of proposal to open decentralization swap: - Compute the maturity contribution of each Neurons' Fund neuron and deduct this amount from the Neurons' Fund neuron. - The swap is informed about the corresponding amount of ICP (`CfParticipant`) in the call to open. - Call back to NNS governance after the swap is committed or aborted: - On committed swap: - Ask the NNS to mint the right amount of ICP for the SNS corresponding to the Neurons' Fund investment (the NNS governance canister keeps track of the total). - On aborted swap: - Send the information about Neurons' Fund participants (`CfParticipant`) back to NNS governance which will return it to the corresponding neurons. Assign the control of the dapp (now under the SNS control) back to the specified principals. - On reject of proposal to open decentralization swap: - Assign the control of the dapp (now under the SNS control) back to the specified principals.

Used in: GetStateResponse

• Lifecycle lifecycle = 3

  The current lifecycle of the swap.

• optional Init init = 1

  Specified on creation. That is, always specified and immutable.

• optional Params params = 4

  Specified in the transition from PENDING to OPEN and immutable thereafter.

• repeated CfParticipant cf_participants = 5

  Neurons' Fund participation. Specified in the transition from PENDING to OPEN and immutable thereafter.

• map<string, BuyerState> buyers = 6

  Empty in the PENDING state. In the OPEN state, new buyers can be added and existing buyers can increase their bids. In the COMMITTED and ABORTED states, the amount cannot be modified, and the transfer timestamps are filled in. The key is the textual representation of the buyer's principal and the value represents the bid.

• repeated SnsNeuronRecipe neuron_recipes = 7

  When the swap is committed, this field is initialized according to the outcome of the swap.

• optional uint64 open_sns_token_swap_proposal_id = 9

  Gets set to whatever value is in the corresponding field of OpenRequest (that field is required at the application level).

• optional bool finalize_swap_in_progress = 10

  A lock stored in Swap state. If set to true, then a finalize_swap call is in progress. In that case, new finalize_swap calls return immediately without doing any real work. The implementation of the lock should result in the lock being released when the finalize_swap method returns. If a lock is not released, upgrades of the Swap canister can release the lock in the post upgrade hook.

• optional uint64 decentralization_sale_open_timestamp_seconds = 11

  The timestamp for the actual opening of the swap, with an optional delay (specified via params.sale_delay_seconds) after the adoption of the swap proposal. Gets set when NNS calls `open` upon the adoption of the swap proposal.

• optional uint64 decentralization_swap_termination_timestamp_seconds = 21

  The timestamp for the actual termination of the swap (committed or aborted).

• optional uint64 next_ticket_id = 12

  This ticket id counter keeps track of the latest ticket id. Whenever a new ticket is created this counter is incremented. It ensures that ticket ids are unique. The ticket IDs are sequential and next_ticket_id is assigned to a users new ticket upon successfully requesting a new ticket. It is incremented after a user requests a new ticket successfully.

• optional uint64 purge_old_tickets_last_completion_timestamp_nanoseconds = 13

  The last time the purge_old_tickets routine was completed.

• optional bytes purge_old_tickets_next_principal = 14

  The next principal bytes that should be checked by the next running purge_old_tickets routine.

• optional bool already_tried_to_auto_finalize = 17

  Set to true when auto-finalization is attempted. Prevents auto-finalization from being attempted more than once.

• optional FinalizeSwapResponse auto_finalize_swap_response = 18

  Set when auto-finalization finishes. Calling finalize manually has no effect on this parameter.

• optional uint64 direct_participation_icp_e8s = 19

  Amount of contributions from direct participants committed to this SNS so far.

• optional uint64 neurons_fund_participation_icp_e8s = 20

  Amount of contributions from the Neurons' Fund committed to this SNS so far.

Used in: FinalizeSwapResponse

• uint32 success = 1

  Success means that on this call to finalize, the item in the sweep succeeded.

• uint32 failure = 2

  Failure means that on this call to finalize, the item in the sweep failed but may be successful in the future.

• uint32 skipped = 3

  Skipped means that on a previous call to finalize, the item in the sweep was successful.

• uint32 invalid = 4

  Invalid means that on this call and all future calls to finalize, this item will not be successful, and will need intervention to succeed.

• uint32 global_failures = 5

  Global_failures does not map to individual items in the sweep, but number of global failures encountered in the sweep.

A device for ensuring that retrying (direct) participation does not result in multiple participation. Basically, this records a user's intent to participate BEFORE moving any funds. How this is used: before any money is sent, a user's agent must first look for an existing ticket. If one does not exist, then, a new one is created for the current participation that is now being attempted (for the first time). If there is already a ticket, then the new participation must be aborted. The surprise existence of the ticket indicates that there is a pending participation. In this case the user's agent must attempt to perform the same participation as stated in the ticket before doing anything else.

Used in: GetOpenTicketResponse.Ok, NewSaleTicketResponse.Err, NewSaleTicketResponse.Ok, NotifyPaymentFailureResponse

• uint64 ticket_id = 1

  Unique ID of the ticket

• optional ICRC1Account account = 2

  The account of the ticket. account.owner is the owner of this ticket.

• uint64 amount_icp_e8s = 3

  The user-set amount of the ticket in ICP e8s

• uint64 creation_time = 4

  The timestamp of creation of this ticket

Used in: SetOpenTimeWindowRequest

• uint64 start_timestamp_seconds = 1

• uint64 end_timestamp_seconds = 2

Used in: BuyerState, SnsNeuronRecipe

• uint64 amount_e8s = 1

  The amount in e8s equivalent that the participant committed to the Swap, which is held by the swap canister until the swap is committed or aborted.

• uint64 transfer_start_timestamp_seconds = 2

  When the transfer to refund or commit funds starts.

• uint64 transfer_success_timestamp_seconds = 3

  When the transfer to refund or commit succeeds.

• optional uint64 amount_transferred_e8s = 4

  The amount that was successfully transferred when swap commits or aborts (minus fees).

• optional uint64 transfer_fee_paid_e8s = 5

  The fee charged when transferring from the swap canister;