Skip to content

Latest commit

 

History

History
117 lines (99 loc) · 4.67 KB

fip-0022.md

File metadata and controls

117 lines (99 loc) · 4.67 KB
Raw
fip title status type author created updated
22
Retire FIO Tokens
Final
Functionality
Pawel Mastalerz <[email protected]>
2020-11-25
2022-04-25

Abstract

This FIP proposes enabling of the retire action, which will allow the caller to burn their own tokens.

Modified actions:

Contract Action Endpoint Description
fio.token retire Added actor, validation and allow any account to call.

Motivation

The primary motivation is to support FIP-21, which introduces Staking Reward Pool, but also requires that Foundation tokens get burned to keep total token supply at 1B. It may be used in the future by the Foundation or any other token holder wanting to burn tokens.

This action exists already, but is restricted to eosio account.

Specification

Modifications to existing actions

retire

Added actor, validation and allow any account to call.

Request body

Parameter Required Format Definition
quantity Yes Int Amount of SUFs to retire.
memo Yes String Memo text (<256 bytes).
actor Yes 12 character string Valid actor of signer
Example
{
  "quantity": 1000000000000,
  "memo": "burn baby burn",
  "actor": "aftyershcu22"
}

Processing

  • Request is validated per Exception handling.
  • Retiring of tokens is not allowed by:
    • Accounts which have any amount of staked tokens at the time of retiring
    • Accounts which have any amount of tokens locked using General Locks (aka FIP-6 locks) at the time of retiring
  • Retiring of tokens locked using Genesis Locks (aka Mainnet Locks) is allowed. When retiring from accounts with Genesis Locks, locked tokens in the accounts are retired before unlocked tokens.
  • Account balance is decremented by quantity.
  • Total FIO token supply is decremented by quantity.
  • There is no chain fee associated with calling the retire action.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid quantity quantity is less than 1000000000000 400 "quantity" Value sent in, i.e. "1000" "Minimum 1000 FIO has to be retired"
Invalid memo memo is >256 bytes 400 "memo" Value sent in, i.e. "1000" "memo has more than 256 bytes"
Insufficient balance Balance is less than quantity 400 "quantity" Value sent in, e.g. "100000000000" "Insufficient balance"
Account staking Retire is called by account currently staking tokens. 400 "actor" Value sent in, e.g. "aftyershcu22" "Account staking cannot retire."
Account locking Retire is called by account currently having tokens locked via General Locks. 400 "actor" Value sent in, e.g. "aftyershcu22" "Account with partially locked balance cannot retire."
Signer not actor Signer not actor 403 Type: invalid_signature

Response body

Parameter Format Definition
status String OK if successful
Example
{
  "status": "OK"
}

Rationale

Use of existing action is deemed to be the best approach.

Implementation

Impacted source:

  • fio.contracts/fio.token/fio.token.cpp
  • fio/programs/clio/main.cpp
  • fio/plugins/chain_plugin/chain_plugin.hpp
  • fio/plugins/chain_plugin/chain_plugin.cpp
  • fio/plugins/chain_api_plugin/chain_api_plugin.cpp

Details:

  • Retire action of fio.token contract is modified
  • Authorization is changed from tokenissuer msig account to actor (parameter)
  • New fio assertions added to support exception handling
  • Send_response added
  • Max_transaction_size limit added
  • Retire action searches the accountstake table of fio.staking contract. Transaction is rejected if actor (parameter) is present in the table.
  • Search system lockedTokensTable for mainnet locks to be retired. Amount retired rolls over from mainnet lock amount to available balance.
  • Fails if there is an existing general lock for the actor
  • Fails if there is an existing staking amount for the actor
  • Token account balance that is burned is also removed from the stats table (supply)

Updates to development environment:

  • fio.devtools/scripts/actions/update_contracts.sh
  • fio.devtools/scripts/launch/04_create_accounts.sh
  • fio.devtools/scripts/launch/09_set_permissions.sh
  • fio.devtools/scripts/launch/19_bind_dev_contracts.sh

Release information

Released in:

Backwards Compatibility

No impact as this action has not been used.

Future considerations

Possible implementation to allow burning of tokens that are staked can be considered. This is currently not supported in the scope of this proposal.

Discussion link

https://fioprotocol.atlassian.net/wiki/spaces/WP/pages/34078744/FIO+Staking