Certificate

Tooling for offline transaction creation

Building stake pool registration certificate

Builds a stake pool registration certificate.

jcli certificate new stake-pool-registration \
    --vrf-key <vrf-public-key> \
    --kes-key <kes-public-key> \
    --start-validity <seconds-since-start> \
    --management-threshold <THRESHOLD> \
    --owner <owner-public-key> \
    [--operator <operator-public-key>] \
    [<output-file>]

Where:

--operator <operator-public-key> - optional, public key of the operator(s) of the pool.
output-file - optional, write the output to the given file or print it to the standard output if not defined

Retiring a stake pool

It is possible to retire a stake pool from the blockchain. By doing so the stake delegated to the stake pool will become dangling and will need to be re-delegated.

Remember though that the action won’t be applied until the next following epoch. I.e. the certificate will take a whole epoch before being applied, this should leave time for stakers to redistribute their stake to other pools before having their stake becoming dangling.

It might be valuable for a stake pool operator to keep the stake pool running until the stake pool retirement certificate is fully applied in order to not miss any potential rewards.

example:

jcli certificate new stake-pool-retirement \
    --pool-id <STAKE_POOL_ID> \
    --retirement-time <seconds-since-start> \
    [<output-file>]

where:

output-file - optional, write the output to the given file or print it to the standard output if not defined.
--retirement-time - is the number of seconds since the start in order to make the stake pool retire. 0 means as soon as possible.
--pool-id - hex-encoded stake pool ID. Can be retrieved using jcli certificate get-stake-pool-id command. See here for more details.

Building stake pool delegation certificate

Builds a stake pool delegation certificate.

jcli certificate new stake-delegation <STAKE_KEY> <STAKE_POOL_IDS> [--output <output-file>]

Where:

-o, --output <output-file> - optional, write the output to the given file or print it to the standard output if not defined
<STAKE_KEY> - the public key used in the stake key registration
<STAKE_POOL_IDS>... - hex-encoded stake pool IDs and their numeric weights in format “pool_id:weight”. If weight is not provided, it defaults to 1.

Building update proposal certificate

Builds an update proposal certificate.

jcli certificate new update-proposal \
    <PROPOSER_ID> \
    <CONFIG_FILE> \
    [<output-file>]

Where:

<PROPOSER_ID> - the proposer ID, public key of the one who will sign this certificate
<CONFIG_FILE> - optional, the file path to the config file defining the config param changes. If omitted it will be read from the standard input.
output-file - optional, write the output to the given file or print it to the standard output if not defined

For example your config file may look like:


  # The block0-date defines the date the blockchain starts
  # expected value in seconds since UNIX_EPOCH
  #
  # By default the value will be the current date and time. Or you can
  # add a specific time by entering the number of seconds since UNIX
  # Epoch
- Block0Date: 17

  # This is the type of discrimination of the blockchain
  # if this blockchain is meant for production then
  # use 'production' otherwise use 'test'.
- Discrimination: test

  # The initial consensus version:
  #
  # * BFT consensus: bft
  # * Genesis Praos consensus: genesis
- ConsensusVersion: bft

  # Number of slots in each epoch.
- SlotsPerEpoch: 42

  # The slot duration, in seconds, is the time between the creation
  # of 2 blocks
- SlotDuration: 79

  # Epoch stability depth
- EpochStabilityDepth: 12

  # Genesis praos active slot coefficient
  # Determines minimum stake required to try becoming slot leader, must be in range (0,1]
- ConsensusGenesisPraosActiveSlotsCoeff: "0.004"

  # This is the size, in bytes, of all the contents of the block (excluding the
  # block header).
- BlockContentMaxSize: 96

  # Add a new bft leader
- AddBftLeader: ed25519_pk1g53asm6l4gcwk2pm5ylr092umaur5yes47rqv7ng5yl525x8g8mq5nk7x7

  # Remove a bft leader
- RemoveBftLeader: ed25519_pk1a3sjcg6gt4d05k5u6uqyzmsap8cjw37ul9cgztz8m697lvkz26uqg49nm3

  # The fee calculations settings
  #
  # total fees: constant + (num_inputs + num_outputs) * coefficient [+ certificate]
- LinearFee:
    # this is the minimum value to pay for every transaction
    constant: 57
    # the additional fee to pay for every inputs and outputs
    coefficient: 14
    # the additional fee to pay if the transaction embeds a certificate
    certificate: 95
    # (optional) fees for different types of certificates, to override the one
    # given in `certificate` just above
    #
    # here: all certificate fees are set to `4` except for pool registration
    # and stake delegation which are respectively `5` and `2`.
    per_certificate_fees:
      # (optional) if not specified, the pool registration certificate fee will be
      # the one set by linear_fees.certificate
      certificate_pool_registration: 5
      # (optional) if not specified, the delegation certificate fee will be
      # the one set by linear_fees.certificate
      certificate_stake_delegation: 2
      # (optional) if not specified, the owner delegation certificate fee will be
      # the one set by linear_fees.certificate. Uncomment to set the owner stake
      # delegation to `1` instead of default `4`:
      certificate_owner_stake_delegation: 1

  # Proposal expiration in epochs
- ProposalExpiration: 68

  # The speed to update the KES Key in seconds
- KesUpdateSpeed: 120

  # Increase the treasury amount
- TreasuryAdd: 10000

  # Set the total reward supply available for monetary creation
- RewardPot: 100000000000000

  # Set the treasury parameters, this is the tax type, just as in stake pool
  # registration certificate parameters.
  #
  # When distributing the rewards, the treasury will be first serve as per
  # the incentive specification document
- TreasuryParams:
    # the fix value the treasury will take from the total reward pot of the epoch
    fixed: 1000
    # the extra percentage the the treasury will take from the reward pot of the epoch
    ratio: "1/10"
    # it is possible to add a max bound to the total value the treasury takes
    # at each reward distribution. For example, one could cap the treasury tax
    # to 10000. Uncomment the following line to apply a max limit:
    max_limit: 10000

  # set the reward supply consumption. These parameters will define how the
  # total_reward_supply is consumed for the stake pool reward
  #
  # There's fundamentally many potential choices for how rewards are contributed back, and here's two potential valid examples:
  #
  # Linear formula: constant - ratio * (#epoch after epoch_start / epoch_rate)
  # Halving formula: constant * ratio ^ (#epoch after epoch_start / epoch_rate)
- RewardParams:
    halving: # or use "linear" for the linear formula
      # In the linear formula, it represents the starting point of the contribution
      # at #epoch=0, whereas in halving formula is used as starting constant for
      # the calculation.
      constant: 2

      # In the halving formula, an effective value between 0.0 to 1.0 indicates a
      # reducing contribution, whereas above 1.0 it indicate an acceleration of contribution.
      #
      # However in linear formula the meaning is just a scaling factor for the epoch zone
      # (current_epoch - start_epoch / epoch_rate). Further requirement is that this ratio
      # is expressed in fractional form (e.g. 1/2), which allow calculation in integer form.
      ratio: 3/68

      # indicates when this contribution start. note that if the epoch is not
      # the same or after the epoch_start, the overall contribution is zero.
      epoch_start: 89

      # the rate at which the contribution is tweaked related to epoch.
      epoch_rate: 20

  # Fees for different types of certificates, to override the one
  # given in `certificate` just above.
- PerCertificateFees:
    # (optional) if not specified, the pool registration certificate fee will be
    # the one set by linear_fees.certificate
    certificate_pool_registration: 5
    # (optional) if not specified, the delegation certificate fee will be
    # the one set by linear_fees.certificate
    certificate_stake_delegation: 2
    # (optional) if not specified, the owner delegation certificate fee will be
    # the one set by linear_fees.certificate. Uncomment to set the owner stake
    # delegation to `1` instead of default `4`:
    certificate_owner_stake_delegation: 1

  # Set where to send the fees generated by transactions activity.
  #
  # It is possible to send all the generated fees to the "treasury"
- FeesInTreasury: rewards

- RewardLimitNone

  # Limit the epoch total reward drawing limit to a portion of the total
  # active stake of the system.
  #
  # for example, if set to 10%, the reward drawn will be bounded by the
  # 10% of the total active stake.
- RewardLimitByAbsoluteStake: 22/72

  # Settings to incentivize the numbers of stake pool to be registered
  # on the blockchain.
  #
  # These settings does not prevent more stake pool to be added. For example
  # if there is already 1000 stake pools, someone can still register a new
  # stake pool and affect the rewards of everyone else too.
  #
  # if the threshold is reached, the pool doesn't really have incentive to
  # create more blocks than 1 / set-value-of-pools % of stake.
- PoolRewardParticipationCapping:
    min: 8
    max: 52

  # Add a new committee id
- AddCommitteeId: 8103973beaa56f4e9440004ee8e8f8359ea18499d4199c1b018c072e7f503ea0

  # Remove a committee id
- RemoveCommitteeId: 6375dcdd714e69c197e99c32486ec28f166a50da7a1e3694807cd8a76f1c8175

- PerVoteCertificateFees:
    certificate_vote_plan: 52
    certificate_vote_cast: 57

  # The transaction max expiry epochs
- TransactionMaxExpiryEpochs: 91

Building vote cast certificate

Builds a vote cast certificate.

Public vote cast

jcli certificate new update-cast public \
    --choice <choice> \
    --proposal-index <proposal-index> \
    --vote-plan-id <vote-plan-id> \
    --output <output-file>

Where:

<choice> - the number of choice within the proposal you vote for
<proposal-index> - the number of proposal in the vote plan you vote for
<vote-plan-id> - the vote plan identified on the blockchain
<output-file> - optional write the output to the given file or print it to the standard output if not defined

Private vote cast

jcli certificate new update-cast private \
    --choice <choice> \
    --options-size <options> \
    --proposal-index <proposal-index> \
    --vote-plan-id <vote-plan-id> \
    --key-path <secret-key>
    --output <output-file>

Where:

<choice> - the number of choice within the proposal you vote for
<options> - size of voting options
<proposal-index> - the number of proposal in the vote plan you vote for
<vote-plan-id> - the vote plan identified on the blockchain
<secret-key> - optional key to encrypt the vote with, if not provided read secret key from the stdit
<output-file> - optional write the output to the given file or print it to the standard output if not defined

Catalyst Voting System - Core Technology