ERC-20 Registration

Learn how to register interoperable ERC-20s through Kynno Governance. {synopsis}

The ERC-20 Module (also known as x/erc20) allows users to instantly convert ERC-20 tokens into native Cosmos Coins, and vice versa. This allows users to exchange assets interchangeably in two entirely different layers, the EVM and Cosmos.

Application-wise, the ERC-20 module allows DeFi protocols to seamlessly integrate with Kynno and the Cosmos ecosystem. Using the module, developers can build smart contracts on Kynno and use the generated ERC-20 tokens for other applications on the Cosmos ecosystem, such as:

  • earning $OSMO staking rewards
  • taking part in governance proposals by voting with $ATOM

Registering an interoperable ERC-20 means registering a new mapping between an ERC-20 token contract and a Cosmos Coin denomination, also known as a Token Pair. Token Pairs enable users to convert ERC-20 tokens into their native Cosmos Coin representation, and can only be created via a governance proposal.

To register an ERC-20, consider the following stages:

  1. Drafting the ERC-20 Proposal
  2. Submitting the ERC-20 Proposal
  3. The On-Chain ERC-20 Proposal

Drafting the ERC-20 Proposal

The following topics must be addressed when drafting an ERC-20 Proposal:

  1. Applicant(s) - the profile of the person(s)/entity making the proposal
    • who you are and your involvement in Cosmos and/or other blockchain networks
    • an overview of team members involved and their relevant experience
    • brief mission statement for your organization/business (if applicable) eg. website
    • past work you've done eg. include your Github
    • some sort of proof of who you are eg. Keybase
  2. Background Information - promote understanding of the ERC-20 Module
  3. Solution - generally how ERC-20 Module changes will be made
    • a brief explanation of what the proposal will do if it passes
    • a brief explanation of the precautions taken, how it was tested, and who was consulted prior to making the proposal
    • a breakdown of the proposal's payload, and third-party review
    • a brief explanation of the risks involved (depending on the direction of IBC Coin, ERC-20)
    • ensure the following are both adhered to and documented:
      • the contracts are verified through the EVM explorer
      • the contracts are deployed open-source
      • the contracts do not extend the IERC20.sol interface through a malicious implementation
      • the contracts use the main libraries for ERC-20s (eg. OpenZeppelin, dapp.tools)
      • the transfer logic is not modified (i.e. transfer logic is not directly manipulated)
      • no malicious Approve events can directly manipulate users' balance through a delayed granted allowance

Submitting the ERC-20 Proposal

After the drafting process, the ERC-20 Proposal can be submitted.

Formatting the Proposal's Text

The ideal format for a proposal is as a Markdown file (ie. .md) in a Github repo or HackMd. Markdown is a simple and accessible format for writing plain text files that is easy to

learn. See the Github Markdown Guide for details on writing markdown files.

Submit the Proposal to Testnet

:::tip Note: For a more detailed description of how to submit a proposal to testnet, check out the submitting guide. :::

To submit a proposal to testnet through the command line with `kynnod', use the following command:

kynnod tx gov submit-proposal \
  --title=<title> \
  --description=<description> \
  --type="Text" \
  --deposit="1000000akynno" \
  --from=<mykey> \
  --chain-id=<testnet_chain_id>
  --node <address>

However, note that if the CLI is used to create a proposal, and description is set using a flag, the text will be escaped which may have undesired effects. If the proposal creator is using markdown or line breaks it's recommended to put the proposal text into a json file and include that file as part of the CLI proposal, as opposed to individual fields in flags. The process of creating a json file containing the proposal can be found here, and the CLI command for submitting the file is below:

kynnod tx gov submit-proposal --proposal=<path_to_json>

You may want to submit your proposal to the testnet chain before the mainnet for a number of reasons, such as wanting to see what the proposal description will look like, to share what the proposal will look like in advance with stakeholders, and to signal that your proposal is about to go live on the mainnet.

Submitting your proposal to the testnet increases the likelihood of engagement and the possibility that you will be alerted to a flaw before deploying your proposal to mainnet.

The On-Chain ERC-20 Proposal

:::tip Note: To learn how to submit a proposal to mainnet, see above, and also check out the submitting guide. :::

A majority of the voting community should probably be aware of the proposal and have considered it before the proposal goes live on-chain. If you're taking a conservative approach, you should have reasonable confidence that your proposal will pass before risking deposit contributions. Make revisions to your draft proposal after each stage of engagement.

The Deposit Period

The deposit period currently lasts 14 days. If you submitted your transaction with the minimum deposit (10 KYN), your proposal will immediately enter the voting period. If you didn't submit the minimum deposit amount (currently 10 KYN), then this may be an opportunity for others to show their support by contributing (and risking) their KYN as a bond for your proposal. You can request contributions openly and also contact stakeholders directly (particularly stakeholders who are enthusiastic about your proposal). Remember that each contributor is risking their funds, and you can read more about the conditions for burning deposits here.

This is a stage where proposals may begin to get broader attention. Most popular explorers currently display proposals that are in the deposit period, but due to proposal spamming, this may change.

A large cross-section of the blockchain/cryptocurrency community exists on Twitter. Having your proposal in the deposit period is a good time to engage the KYN community to prepare validators to vote and KYN-holders that are staking.

The Voting Period

At this point you'll want to track which validator has voted and which has not. You'll want to re-engage directly with top stake-holders, ie. the highest-ranking validator operators, to ensure that:

  1. they are aware of your proposal;
  2. they can ask you any questions about your proposal; and
  3. they are prepared to vote.

Remember that any voter may change their vote at any time before the voting period ends. That historically doesn't happen often, but there may be an opportunity to convince a voter to change their vote. The biggest risk is that stakeholders won't vote at all (for a number of reasons). Validator operators tend to need multiple reminders to vote. How you choose to contact validator operators, how often, and what you say is up to you--remember that no validator is obligated to vote, and that operators are likely occupied by competing demands for their attention. Take care not to stress any potential relationship with validator operators.