Non-Custodial Seed Node Staking Contracts

For phase 0 contracts, please refer to here.

Non-custodial seed node staking in Zilliqa as described in ZIP-11 makes use of four contracts written in Scilla. This repository is the central portal that collates together the contracts, documentations around them, unit tests, and scripts to deploy and run the contracts on the network.

In the sections below, we describe in detail: 1) the purpose of each contract, 2) their structure and specifications, 3) running unit tests for the contracts.

Table of Content

• Overview
• SSNList Contract Specification
  • Roles and Privileges
  • Data Types
  • Immutable Parameters
  • Mutable Fields
  • Transitions
    • Housekeeping Transitions
    • Delegator Transitions
    • SSN Operation Transitions
    • Verifier Operation Transitions
    • Contract Upgrade Transitions
    • Other Transitions
• SSNListProxy Contract Specification
  • Roles and Privileges
  • Immutable Parameters
  • Mutable Fields
  • Transitions
    • Housekeeping Transitions
    • Relay Transitions
• gZILToken Contract Specification
• Multi-signature Wallet Contract Specification
  • General Flow
  • Roles and Privileges
  • Immutable Parameters
  • Mutable Fields
  • Transitions
    • Submit Transitions
    • Action Transitions

Overview

The table below summarizes the purpose of the four contracts that ZIP-11 will broadly use:

SSNList Contract Specification

The SSNList contract is the main contract that is central to the entire staking infrastructure.

Roles and Privileges

The table below describes the roles and privileges that this contract defines:

Data Types

The contract defines and uses several custom ADTs that we describe below:

1. SSN Data Type:

type Ssn =
| Ssn of Bool Uint128 Uint128 String String String Uint128 Uint128 Uint128 ByStr20

(* Each SSN has the following fields: *)

(* ActiveStatus      : Bool *)
(*                     Represents whether the SSN has the minimum stake amount and therefore ready to participate in staking and receive rewards. *)
(* StakeAmount       : Uint128 *)
(*                     Total stake that can be used for reward calculation. *)
(* StakeRewards      : Uint128 *)
(*                     (Unwithdrawn) Reward accumulated so far across all cycles. It only includes the reward that the SSN can distribute to its delegators. It does not include SSN's own commission. *)
(* Name              : String *)
(*                     A human-readable name for this SSN. *)
(* URLRaw            : String *)
(*                     Represents "ip:port" of the SSN serving raw API requests. *)
(* URLApi            : String *)
(*                     Representing URL exposed by SSN serving public API requests. *)
(* BufferedDeposit   : Uint128 *)
(*                     Stake deposit that cannot be counted as a part of reward calculation for the ongoing reward cycle. But, to be considered for the next one. *)
(* Commission        : Uint128 *)
(*                     Percentage of incoming rewards that the SSN takes. Represented as an integer. If the commission is 10.5%, then it is multiplied by 10^7 and then resulting integer is set as commission. The assumption is that the percentage is up to 7 decimal places. *)
(* CommissionRewards : Uint128 *)
(*                     Number of ZILs earned as commission by the SSN. *)
(* ReceivingAddress   : ByStr20 *)
(*                     Address to be used to receive commission. *)

2. SsnStakeRewardShare Data Type:

type SsnStakeRewardShare = 
| SsnStakeRewardShare of ByStr20 Uint128 Uint128

(*  SSNAddress        : ByStr20 *)
(*                      Address of the SSN. *)
(*  CycleReward       : Uint128 *)
(*                      Integer representation of reward assigned by the verifier to this SSN for this cycle. *)
(*  TotalStakeAmount  : Uint128 *)
(*                      Total stake amount at a specific cycle.                                               *)

3. SSNCycleInfo Data Type:

type SSNCycleInfo =
| SSNCycleInfo of Uint128 Uint128

(*   Each SSNCycleInfo has the following fields: *)
(*   TotalStakeDuringTheCycle            : Uint128 *)
(*                                         Represents the amount staked during this cycle for the given SSN. *)
(*   TotalRewardEarnedDuringTheCycle     : Uint128 *)
(*                                         Represents the total reward earned during this cycle for the given SSN. *)

4. Error Data Type:

type Error =
  | ContractFrozenFailure (* Contract is paused *)
  | VerifierValidationFailed (* Initiator is not verifier *)
  | AdminValidationFailed (* Initiator is not admin *)
  | ProxyValidationFailed (* Caller is not proxy *)
  | DelegDoesNotExistAtSSN (* Delegator does not exist at the given SSN *)
  | DelegHasBufferedDeposit (* Delegator has some buffered deposit. *)
  | ChangeCommError (* Commission could not be changed *)
  | SSNNotExist (* SSN does not exist *)
  | SSNAlreadyExist (* SSN already exists *)
  | DelegHasUnwithdrawnRewards (* Delegator has unwithdrawn Rewards *)
  | DelegHasNoSufficientAmt (* Delegator does not have sufficient amount to withdraw *)
  | SSNNoComm (* SSN has no commission left to withdraw *)
  | DelegStakeNotEnough (* Delegator's stake is not above minimum *)
  | ExceedMaxChangeRate (* SSN is trying to modify the commission rate by over 1% *)
  | ExceedMaxCommRate (* SSN is trying to set the commission rate greater than the allowed max *)
  | InvalidTotalAmt (* Error when the total stake amount is being decreased by an illegal amount *)
  | VerifierNotSet (* Verifier's address is not set in the field *)
  | VerifierRecvAddrNotSet (* Verifier's reward address address is not set in the field *)
  | ReDelegInvalidSSNAddr (* Delegator cannot redelegate to same SSN address *)
  | AvailableRewardsError (* Verifier reward does not match computed SSN reward *)
  | InvalidSwapAddr (* Swap address is invalid; either the address is does not match the one in the request map or the address does not exists  *)
  | SwapAddrValidationFailed (* Requestor swap address is different *)
  | SwapAddrAlreadyExistsAsRequest (* There exists another swap request that is the inverse of this swap address pair; causing a cyclic request *)

Immutable Parameters

The table below lists the parameters that are defined at the contract deployment time and hence cannot be changed later on.

Mutable Fields

The table below presents the mutable fields of the contract and their initial values.

Transitions

Note that each of the transitions in the SSNList contract takes initiator as a parameter which as explained above is the caller that calls the SSNListProxy contract which in turn calls the SSNList contract.

Note: No transition in the SSNList contract can be invoked directly. Any call to the SSNList contract must come from the SSNListProxy contract.

All the transitions in the contract can be categorized into four categories:

• Housekeeping Transitions: Meant to facilitate basic admin-related tasks.
• Delegator Transitions: The transitions that the delegators will invoke as a part of the SSN operation.
• SSN Transitions: The transitions that the SSNs will invoke as a part of the SSN operation.
• Verifier Transitions: The transitions that the verifier will invoke as a part of the SSN operation.

Each of these category of transitions are presented in further detail below.

Housekeeping Transitions

Delegator Transitions

SSN Operation Transitions

Verifier Operation Transitions

Contract Upgrade Transitions

Contract State Migration Transitions

Other Transitions

SSNListProxy Contract Specification

SSNListProxy contract is a relay contract that redirects calls to it to the SSNList contract.

Roles and Privileges

The table below describes the roles and privileges that this contract defines:

Immutable Parameters

The table below lists the parameters that are defined at the contract deployment time and hence cannot be changed later on.

Mutable Fields

The table below presents the mutable fields of the contract and their initial values.

Transitions

All the transitions in the contract can be categorized into two categories:

• Housekeeping Transitions meant to facilitate basic admin related tasks.
• Relay Transitions to redirect calls to the SSNList contract.

Housekeeping Transitions

Relay Transitions

These transitions are meant to redirect calls to the corresponding SSNList contract. While redirecting, the contract prepares the initiator value that is the address of the caller of the SSNListProxy contract. The signature of transitions in the two contracts is exactly the same expect the added last parameter initiator for the SSNList contract.

Note: Any transition in SSNList contract that accepts money will have the corresponding transition in SSNListProxy accept the amount and then pass it during the message call.

gZILToken Contract Specification

gZILToken contract is a ZRC-2 compliant token contract with a few minor modifications. The contract defines two extra immutable variables init_minter (of type ByStr20) and end_block (of type BNum). The former is the initial minter of the contract allowed to mint tokens, while the latter stores the block number until which minting is allowed. It also introduces a mutable field minter(of type ByStr20) initialized to init_minter and a transition ChangeMinter(new_minter: ByStr20) to update the address of the minter. Since gZILToken won't require buring, the Burn transition from the ZRC-2 specification is removed.

The modified Mint transition to be called by the minter:

transition Mint(recipient: ByStr20, amount: Uint128)
  current_block <- & BLOCKNUMBER;
  is_minting_over = builtin blt end_block current_block;
  match is_minting_over with
  | True =>
  | False =>
    IsMinter;
    AuthorizedMint recipient amount;
    (* Prevent sending to a contract address that does not support transfers of token *)
    msg_to_recipient = {_tag: "RecipientAcceptMint"; _recipient: recipient; _amount: zero; 
                        minter: _sender; recipient: recipient; amount: amount};
    msgs = one_msg msg_to_recipient;
    send msgs
  end
end

The ChangeMintertransition to be called by the minter:

transition ChangeMinter(new_minter: ByStr20, initiator: ByStr20)
  IsOwner initiator;
  minter := new_minter;
  e = {_eventname: "ChangedMinter"; new_minter: new_minter};
  event e  
end

As tokens are rewarded when a delegator claims its staking rewards within the SSNList contract, the minter of the gZILToken contract will be the address of the SSNList contract.

Multi-signature Wallet Contract Specification

This contract has two main roles. First, it holds funds that can be paid out to arbitrary users, provided that enough people from a pre-defined set of owners have signed off on the payout.

Second, and more generally, it also represents a group of users that can invoke a transition in another contract only if enough people in that group have signed off on it. In the staking context, it represents the admin in the SSNList contract. This provides added security for the privileged admin role.

General Flow

Any transaction request (whether transfer of payments or invocation of a foreign transition) must be added to the contract before signatures can be collected. Once enough signatures are collected, the recipient (in case of payments) and/or any of the owners (in the general case) can ask for the transaction to be executed.

If an owner changes his mind about a transaction, the signature can be revoked until the transaction is executed.

This wallet does not allow adding or removing owners, or changing the number of required signatures. To do any of those, perform the following steps:

1. Deploy a new wallet with owners and required_signatures set to the new values. MAKE SURE THAT THE NEW WALLET HAS BEEN SUCCESFULLY DEPLOYED WITH THE CORRECT PARAMETERS BEFORE CONTINUING!
2. Invoke the SubmitTransaction transition on the old wallet with the following parameters:
   • recipient : The address of the new wallet
   • amount : The _balance of the old wallet
   • tag : AddFunds
3. Have (a sufficient number of) the owners of the old contract invoke the SignTransaction transition on the old wallet. The parameter transactionId should be set to the Id of the transaction created in step 2.
4. Have one of the owners of the old contract invoke the ExecuteTransaction transition on the old contract. This will cause the entire balance of the old contract to be transferred to the new wallet. Note that no un-executed transactions will be transferred to the new wallet along with the funds.

WARNING: If a sufficient number of owners lose their private keys, or for any other reason are unable or unwilling to sign for new transactions, the funds in the wallet will be locked forever. It is therefore a good idea to set required_signatures to a value strictly less than the number of owners, so that the remaining owners can retrieve the funds should such a scenario occur.

If an owner loses his private key, the remaining owners should move the funds to a new wallet (using the workflow described above) to ensure that funds are not locked if another owner loses his private key. The owner who originally lost his private key can generate a new key, and the corresponding address be added to the new wallet, so that the same set of people own the new wallet.

Roles and Privileges

The table below list the different roles defined in the contract.

Immutable Parameters

The table below lists the parameters that are defined at the contract deployment time and hence cannot be changed later on.

Mutable Fields

The table below presents the mutable fields of the contract and their initial values.

Transitions

All the transitions in the contract can be categorized into three categories:

• Submit Transitions: Create transactions for future signoff.
• Action Transitions: Let owners sign, revoke or execute submitted transactions.
• The _balance field keeps the amount of funds held by the contract and can be freely read within the implementation. AddFunds transition are used for adding native funds(ZIL) to the wallet from incoming messages by using accept keyword.

Submit Transitions

The first transition is meant to submit request for transfer of native ZILs while the other are meant to submit a request to invoke transitions in the SSNListProxy contract.

Action Transitions