Kaia KIPs

404

Page not found :(

The requested page could not be found.

All

Draft

Number	Title	Author
223	Reduce calldata gas cost and introduce floor data gas	Lake, Ollie, Sawyer
226	Consensus liquidity for Kaia	Lewis, Ian, Ollie, Lake, and Aidan
227	Candidate and Validator Evaluation	Joseph, Lewis, Ian, Ollie, Lake
228	SetCode for EOA	Ollie, Garry, Shiki
239	EXTCODEHASH opcode for Kaia	Lewis
249	Slot-Based Auction on Kaia	Joseph, Lewis, Lake
276	eth_config JSON-RPC Method	Garry, Ollie
277	Self Validator Registration	Lewis, Ollie, Ian
279	BlobTx for Kaia	Ollie, Nasu, Shogo
286	Permissionless Validator Lifecycle	Lewis, Ian, Ollie, Lake, and Joseph
287	Permissionless Staking Policy	Lewis
290	Permissionless Smart Contracts	Lewis, Ian, Ollie, Lake, and Joseph

Review

Number	Title	Author
245	Transaction Bundle	Ian, Ollie
247	Gasless Transaction	Ian, Shiki, Ollie

Final

Number	Title	Author
3	Klaytn Keystore Format v4	Junghyun Colin Kim
7	Fungible Token Standard	Junghyun Colin Kim, Kyungup Kim
13	Interface Query Standard	Junghyun Colin Kim
17	Non-fungible Token Standard	Junghyun Colin Kim
34	Klaytn SDK Common Architecture	Jimin Kim, Seonyong Kim, Junghyun Colin Kim
37	Token Standard	Kyungkoo Kai Kim
71	Dynamic Gas Fee Pricing Mechanism	Woojin Lee (jared), Junghyun Colin Kim
81	Implementing the on-chain governance voting method	Yeri, Daniel, Aidan, Ollie, Eddie
82	A new GC reward structure due to abolition of the Gini coefficient	Yeri, Daniel, Aidan, Ollie, Sam, Uno, Eddie
87	NFT Avatar in Multi-Metaverse	Yeri Lee, Junghyun Colin Kim, Wonbae Kim, Seokrin Sung
97	Signed Data Standard	TaeRim Lee
103	Treasury Fund Rebalancing	Aidan, Toniya, Ollie, Ian
113	BLS public key registry	Ian, Ollie, Joseph, and Aidan
114	Supplant DIFFICULTY opcode with RANDOM	Ian, Ollie, Joseph, and Aidan
146	Unpredictable Proposer Selection	Ian, Ollie, Joseph, and Aidan
149	Unified System Contract Management Process	Lewis, Ian, Ollie, Lake, and Aidan
160	An Update of Treasury Fund Rebalancing	Ollie, Yumiel, Ian, Aidan
162	Priority Fee Mechanism	Ollie, Sawyer, Aidan
163	CnStakingV3 with public delegation	Lewis, Ian, Ollie, and Aidan

Active

Number	Title	Author
1	KIP Purpose and Guidelines	Junghyun Kim
201	KIP Process Upgrade	Neo Yiu

Abandoned

Number	Title	Author
237	Storage Compression	Lake, Ollie

Kaia KIPs A feed of all KIPs {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign kips = site.pages | sort: 'kip' %} {% for kip in kips %} {{ kip.title | xml_escape }} {{ kip.type | xml_escape }} {% if kip.discussions-to %} {{ kip.discussions-to | xml_escape }} {% endif %} {{ kip.content | xml_escape }} {{ kip.created | date_to_rfc822 }} {{ site.url }}{{ kip.url }} {{ site.url }}{{ kip.url }} {% endfor %}

Core

{% assign kips=site.pages|where:"type","Core"%} {% include kiptable.html kips=kips %}

Ecosystem

{% assign kips=site.pages|where:"type","Ecosystem" %} {% include kiptable.html kips=kips %}

Home

KIPs

Kaia Improvement Proposals (KIPs) describe standards for the Kaia platform, including core protocol specifications, client APIs, and contract standards.

Contributing

Review KIP-201.
Fork the repository by clicking "Fork" in the top right.
Add your KIP to the forked repository. There is a template KIP here.
Submit a Pull Request to Kaia's KIPs repository.

Note: We strongly recommend discussing KIP ideas with the community in the Developer Forum - TBD to collect feedback and validate ideas before submitting a Draft.

KIP status terms

Idea - An idea that is pre-draft. This is not tracked within the KIP Repository.
Draft - a KIP that is undergoing rapid iteration and changes.
Review - a KIP that is marked as a ready for and requested peer review by the reviewers.
Last Call - a KIP that is listed prominently as a pinned issue
Accepted - a KIP that has been in ‘Last Call’ for at least 2 weeks, any technical changes that were requested have been addressed by the author, and finally get approved by the Kaia core developers.
Final - a KIP that has been released as a standard specification. If a Core KIP is in ‘Final’, its implementation has been included in at least one Kaia client.

{% include types_lastcall.html %}

Kaia KIPs Last Call Review All KIPs which are in the two-week "last call" status, please help review these and provide your feedback! {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign kips = site.pages | sort: 'kip' %} {% for kip in kips %} {% if kip.status == "Last Call" %} {% capture description %}

KIP #{{ kip.kip }} - {{kip.title }} is in Last Call status. It is authored by {{ kip.author }} and was originally created {{ kip.created }}. It is in the type {{ kip.type }}. Please review and note any changes that should block acceptance.

{% if kip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ kip.discussions-to }}

{% else %}

Please visit the [kaia/KIPs issues to comment](https://github.com/kaiachain/KIPs/issues/{{kip.kip}}).

{% endif %}

{{ kip.content }} {% endcapture %} {{ kip.title | xml_escape }} {{ description | xml_escape }} {{ kip.date | date_to_rfc822 }} {{ site.url }}/{{ kip.url }} {{ site.url }}/{{ kip.url }} {% endif %} {% endfor %}

Tokenization

{% assign kips=site.pages|where:"type","Tokenization" %} {% include kiptable.html kips=kips %}

@import "minima";

Creative Commons Legal Code CC0 1.0 Universal CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER. Statement of Purpose The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work"). Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others. For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights. 1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following: i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; ii. moral rights retained by the original author(s) and/or performer(s); iii. publicity and privacy rights pertaining to a person's image or likeness depicted in a Work; iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; v. rights protecting the extraction, dissemination, use and reuse of data in a Work; vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof. 2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose. 3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose. 4. Limitations and Disclaimers. a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work.

Terms of Use

# Terms of Use ## 1. Your Use of Open Source Software We may make (but are not obligated to make) the source code of Kaia Blockchain Network Platform ("Platform"), the software on the Platform, etc. for download as open source software. If you use this open source software, you agree to be bound by and comply with any license that applies to this open source software. You will not indicate that you are associated with us in connection with your use, modifications or distributions of this open source software. ## 2. Services Provided on the Platform The Platform is a combination of peer-to-peer subnetworks of nodes transmitting transactions and blocks to execute value transfers and run smart contracts. The Core Cell Network ("CCN"), which is one of the subnetworks that constitute the Platform, verifies and executes transactions that occur on the Platform. The CCN is operated by Kaia Governance Council, which is a collective group of Core Cell Operators, and Kaia is not directly involved in any services that are provided in or individual transactions that occur on the Platform. ## 3. Your Installation of BApp on the Platform Your use of open source software is free of charge. However, you may be required to pay a certain number of KLAY as a transaction fee in order to execute a transaction on the Platform, including the installation of the BApp on the Platform. Once transaction is executed successfully and respective block generation is verified successfully by the Platform’s mechanism, the block is irreversibly stored in the blockchain. As such, your installation of the BApp and any other transactions on the Platform, as well as the submission of transaction fee is final and irrevocable. ## 4. User Content If you or the users of your BApp post, upload, input, provide or submit any content on the Platform (collectively, your "User Content"), you must ensure that the User Content provided by you or the users of your BApp at that or at any other time is true, accurate, up to date and complete and that any User Content you or the users of your BApp post, upload, input, provide or submit via the Platform do not breach or infringe legal rights of any third party. To the extent that is technically possible, you agree to prevent, remove or block access of any User Content that you or the users of your BApp post, upload, input, provide or submit via the Platform that violate or may violate legal rights (such as rights of privacy and publicity) of others or any applicable laws or regulations. We do not own, control or endorse any User Content that is transmitted, stored or processed via the Platform or sent to us and we are not responsible or liable for any User Content. We make no assurance that any of Your Content will be secured or that such content will remain confidential. You are solely responsible and liable for all of your User Content and for your use of any interactive features, links or information or content on the Platform, and you represent and warrant that (i) you own all intellectual property rights (or have obtained all necessary permissions) to provide your User Content and to grant the licenses in these Terms of Use; (ii) your User Content will not violate any agreements or confidentiality obligations; and (iii) your User Content will not violate, infringe or misappropriate any intellectual property right or other proprietary right, including the right of publicity or privacy, of any person or entity. You shall not include in User Content, or upload, transmit to or create or include in the Services environment any production data or any sensitive, proprietary, confidential or other data with particular data protection requirements such as personal data or personally identifiable information relating to an identified or identifiable natural person. You are prohibited from using the Platform to post or transmit any threatening, libellous, defamatory, obscene, scandalous, inflammatory, pornographic or profane material, any material that is contrary to applicable local, federal, or international laws and regulations, or any material that could constitute or encourage unlawful conduct. You must ensure that your User Content do not include such materials. We may from time to time monitor or review material transmitted or posted using the Network, and we reserve the right to delete any material we deem inappropriate. We are under no obligation to do so and assume no responsibility or liability arising from any material transmitted or posted using the Platform. You understand that any information you or users of your BApp upload to the Platform will be distributed among the blockchain nodes and may not removable due to technical limitations of the blockchain technology. You are entirely responsible for any and all activities that occur under your account or your BApp (if any). You agree to notify us immediately of any unauthorized use of your User Content, your BApp or account or any other breach of security. We will not be liable for any loss or damages that you may incur as a result of someone else using your User Content, your BApp or account, either with or without your knowledge. However, you could be held liable for losses incurred by us or another party due to someone else using your User Content, your BApp or account. You may not use anyone else’s User Content, your BApp or account at any time without the permission of such person or entity. By posting, uploading, inputting, providing or submitting your User Content to the Platform, you grant to participants of the Platform and any necessary sub-licensees a non-exclusive, worldwide, perpetual, right and permission to use, reproduce, copy, edit, modify, translate, reformat, create derivative works from, distribute, transmit, publicly perform and publicly display your User Content and sub-license such rights to others. If we have reason to believe that there is likely to be a breach of security, breach or misuse of the Platform or if you breach any of your obligations under these terms, we may suspend your use of the Platform at any time and for any reason.

{% if page.xsl %}{% endif %}Jekyll{{ site.time | date_to_xmlschema }}{{ page.url | absolute_url | xml_escape }}{% assign title = site.title | default: site.name %}{% if page.collection != "posts" %}{% assign collection = page.collection | capitalize %}{% assign title = title | append: " | " | append: collection %}{% endif %}{% if page.category %}{% assign category = page.category | capitalize %}{% assign title = title | append: " | " | append: category %}{% endif %}{% if title %}{{ title | smartify | xml_escape }}{% endif %}{% if site.description %}{{ site.description | xml_escape }}{% endif %}{% if site.author %}{{ site.author.name | default: site.author | xml_escape }}{% if site.author.email %}{{ site.author.email | xml_escape }}{% endif %}{% if site.author.uri %}{{ site.author.uri | xml_escape }}{% endif %}{% endif %}{% if page.tags %}{% assign posts = site.tags[page.tags] %}{% else %}{% assign posts = site[page.collection] %}{% endif %}{% if page.category %}{% assign posts = posts | where: "categories", page.category %}{% endif %}{% unless site.show_drafts %}{% assign posts = posts | where_exp: "post", "post.draft != true" %}{% endunless %}{% assign posts = posts | sort: "date" | reverse %}{% assign posts_limit = site.feed.posts_limit | default: 10 %}{% for post in posts limit: posts_limit %}{% assign post_title = post.title | smartify | strip_html | normalize_whitespace | xml_escape %}{{ post_title }}{{ post.date | date_to_xmlschema }}{{ post.last_modified_at | default: post.date | date_to_xmlschema }}{{ post.id | absolute_url | xml_escape }}{% assign excerpt_only = post.feed.excerpt_only | default: site.feed.excerpt_only %}{% unless excerpt_only %}{% endunless %}{% assign post_author = post.author | default: post.authors[0] | default: site.author %}{% assign post_author = site.data.authors[post_author] | default: post_author %}{% assign post_author_email = post_author.email | default: nil %}{% assign post_author_uri = post_author.uri | default: nil %}{% assign post_author_name = post_author.name | default: post_author %}{{ post_author_name | default: "" | xml_escape }}{% if post_author_email %}{{ post_author_email | xml_escape }}{% endif %}{% if post_author_uri %}{{ post_author_uri | xml_escape }}{% endif %}{% if post.category %}{% elsif post.categories %}{% for category in post.categories %}{% endfor %}{% endif %}{% for tag in post.tags %}{% endfor %}{% assign post_summary = post.description | default: post.excerpt %}{% if post_summary and post_summary != empty %}

{% endif %}{% assign post_image = post.image.path | default: post.image %}{% if post_image %}{% unless post_image contains "://" %}{% assign post_image = post_image | absolute_url %}{% endunless %}{% endif %}{% endfor %}

KIP Purpose and Guidelines

Sun, 10 Nov 2019 00:00:00 +0000

## What is a KIP? KIP stands for Kaia Improvement Proposal. A KIP is a design document providing information to the Kaia community, or describing a new feature for Kaia or its processes or environment. The KIP should provide a concise technical specification of the feature and a rationale for the feature. The KIP author is responsible for building consensus within the community and documenting dissenting opinions. ## KIP Rationale We intend KIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Kaia. Because the KIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. For Kaia implementers, KIPs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the KIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library. ## KIP Types There are three types of KIP: - A **Standard Track KIP** describes any change that affects most or all Kaia implementations, such as a change to the network protocol, a change in block or transaction validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Kaia. Furthermore Standard Track KIPs can be broken down into the following categories. Standards Track KIPs consist of two parts, a design document and implementation. - **Core** - improvements requiring a consensus fork as well as changes that are not necessarily consensus critical but may be relevant to core development. - **Networking** - includes improvements related to networking layers. - **Storage** - includes improvements related to storage layers. - **Interface** - includes improvements around client API/RPC specifications and standards, and also certain language-level standards like method names and contract ABIs. - **KCT** - includes improvements or standards related to Kaia compatible tokens. - **SDK** - includes improvements related to SDKs. - **Application** - application-level standards and conventions, such as name registries, URI schemes, library/package formats, and wallet formats. - A **Meta KIP** describes a process surrounding Kaia or proposes a change to (or an event in) a process. Meta KIPs are like Standard Track KIPs but apply to areas other than the Kaia protocol itself. They may propose an implementation, but not to Kaia's codebase; they often require community consensus; unlike Informational KIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Kaia development. Any Meta KIP is also considered a Process KIP. - An **Informational KIP** describes a Kaia design issue, or provides general guidelines or information to the Kaia community, but does not propose a new feature. Informational KIPs do not necessarily represent Kaia community consensus or a recommendation, so users and implementers are free to ignore Informational KIPs or follow their advice. It is highly recommended that a single KIP contains a single key proposal or new idea. The more focused the KIP, the more successful it tends to be. A change to one client doesn't require a KIP; a change that affects multiple clients, or defines a standard for multiple apps to use, does. A KIP must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly. ### Special requirements for Core KIPs If a **Core** KIP mentions or proposes changes to the KLVM (Kaia Virtual Machine, forked from Byzantium EVM), it should refer to the instructions by their mnemonics and define the opcodes of those mnemonics at least once. A preferred way is the following: ``` REVERT (0xfe) ``` ## KIP Work Flow ### Shepherding a KIP Parties involved in the process are you, the champion or *KIP author*, the [*KIP editors*](#kip-editors), and the Kaia core developers. Before you begin writing a formal KIP, you should vet your idea. Ask the Kaia community first if an idea is original to avoid wasting time on something that will be be rejected based on prior research. It is thus recommended to open a discussion thread on [the Issues section of this repository](https://github.com/kaiachain/KIPs/issues). In addition to making sure your idea is original, it will be your role as the author to make your idea clear to reviewers and interested parties, as well as inviting editors, developers and community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your KIP is commensurate with both the work involved in implementing it and how many parties will have to conform to it. For example, the work required for implementing a Core KIP will be much greater than for others and the KIP will need sufficient interest from the Kaia client teams. Negative community feedback will be taken into consideration and may prevent your KIP from moving past the Draft stage. ### Core KIPs For Core KIPs, given that they require client implementations to be considered **Final** (see "KIPs Process" below), you will need to either provide an implementation for clients or convince clients to implement your KIP. In short, your role as the champion is to write the KIP using the style and format described below, shepherd the discussions in the appropriate forums, and build community consensus around the idea. ### KIP Process Following is the process that a successful KIP will move along: ``` [ IDEA ] -> [ DRAFT ] -> [ LAST CALL ] -> [ ACCEPTED ] -> [ FINAL ] ``` Each status change is requested by the KIP author and reviewed by the KIP editors. Use a pull request to update the status. Please include a link to where people should continue discussing your KIP. The KIP editors will process these requests as per the conditions below. * **Idea** -- Once the champion has asked the Kaia community in [Dev Forum - TBD](https://devforum.kaia.io/c/english/kip/55) whether an idea has any chance of support, they will write a draft KIP as a [pull request](https://github.com/kaiachain/KIPs/pulls). Consider including an implementation if this will aid people in studying the KIP. * :arrow_right: Draft -- If agreeable, a KIP editor will assign the KIP a number (generally the issue or PR number related to the KIP) and merge your pull request. The KIP editor will not unreasonably deny a KIP. * :x: Draft -- Reasons for denying draft status include being too unfocused, too broad, duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility. * **Draft** -- Once the first draft has been merged, you may submit follow-up pull requests with further changes to your draft until such point as you believe the KIP to be mature and ready to proceed to the next status. A KIP in draft status must be implemented to be considered for promotion to the next status. * :arrow_right: Last Call -- If agreeable, the KIP editor will assign Last Call status and set a review end date (`review-period-end`), normally 14 days later. * :x: Last Call -- A request for Last Call status will be denied if material changes are still expected to be made to the draft. We hope that KIPs only enter Last Call once. * **Last Call** -- This KIP will listed prominently as a pinned issue. * :x: -- A Last Call which results in material changes or substantial unaddressed technical complaints will cause the KIP to revert to Draft. * :arrow_right: Accepted -- A successful Last Call without material changes or unaddressed technical complaints will become Accepted. * **Accepted** -- This status signals that material changes are unlikely and Kaia client developers should consider this KIP for inclusion. Their process for deciding whether to encode it into their clients as part of a hard fork is not part of the KIP process. * :arrow_right: Draft -- The KIP can be decided to move it back to the Draft status at the discretion. E.g. a major, but correctable, flaw was found in the KIP. * :arrow_right: Rejected -- The KIP can be decided to be marked as this KIP as Rejected at their discretion. E.g. a major, but uncorrectable, flaw was found in the KIP. * :arrow_right: Final -- Standard Track Core KIPs must be implemented in any of Kaia clients before it can be considered Final. When the implementation is complete and adopted by the community, the status will be changed to “Final”. * **Final** -- This KIP represents the current state-of-the-art. A Final KIP should only be updated to correct errata. Other exceptional statuses include: * **Active** -- Some Informational and Process KIPs may also have a status of “Active” if they are never meant to be completed. E.g. KIP 1 (this KIP). * **Abandoned** -- This KIP is no longer pursued by the original authors or it may not be a (technically) preferred option anymore. * :arrow_right: Draft -- Authors or new champions wishing to pursue this KIP can ask for changing it to Draft status. * **Rejected** -- A KIP that is fundamentally broken or a Core KIP that was rejected by the Core Devs and will not be implemented. A KIP cannot move on from this state. * **Superseded** -- A KIP which was previously Final but is no longer considered state-of-the-art. Another KIP will be in Final status and reference the Superseded KIP. A KIP cannot move on from this state. ## What belongs in a successful KIP? Each KIP should have the following parts: - Preamble - RFC 822 style headers containing metadata about the KIP, including the KIP number, a short descriptive title (limited to a maximum of 44 characters), and the author details. See [below](#kip-header-preamble) for details. - Abstract - A short (~200 word) description of the technical issue being addressed. - Motivation (*optional) - The motivation is critical for KIPs that want to change the Kaia protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the KIP solves. KIP submissions without sufficient motivation may be rejected outright. - Specification - The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Kaia platforms. - Rationale - The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion. - Backwards Compatibility - All KIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The KIP must explain how the author proposes to deal with these incompatibilities. KIP submissions without a sufficient backwards compatibility treatise may be rejected outright. - Test Cases - Test cases for an implementation are mandatory for KIPs that are affecting consensus changes. Other KIPs can choose to include links to test cases if applicable. - Implementations - The implementations must be completed before any KIP is given status “Final”, but it need not be completed before the KIP is merged as draft. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of API details. - Copyright Waiver - All KIPs must be in the public domain. See the bottom of this KIP for an example copyright waiver. ## KIP Formats and Templates KIPs should be written in [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Image files should be included in a subdirectory of the `assets` folder for that KIP as follows: `assets/kip-N` (where **N** is to be replaced with the KIP number). When linking to an image in the KIP, use relative links such as `../assets/kip-1/image.png`. ## KIP Header Preamble Each KIP must begin with an [RFC 822](https://www.ietf.org/rfc/rfc822.txt) style header preamble, preceded and followed by three hyphens (`---`). This header is also termed ["front matter" by Jekyll](https://jekyllrb.com/docs/front-matter/). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required. ` kip:` *KIP number* (this is determined by the KIP editor) ` title:` *KIP title* ` author:` *a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s). Details are below.* ` * discussions-to:` *a url pointing to the official discussion thread* ` status:` *Draft | Last Call | Accepted | Final | Active | Abandoned | Rejected | Superseded* ` * review-period-end:` *date review period ends* ` type:` *Standards Track | Informational | Meta* ` * category:` *Core | Networking | Storage | Interface | KCT | SDK | Application* (Standards Track KIPs only) ` created:` *date created on* ` * updated:` *comma separated list of dates* ` * requires:` *KIP number(s)* ` * replaces:` *KIP number(s)* ` * superseded-by:` *KIP number(s)* ` * resolution:` *a url pointing to the resolution of this KIP* Headers that permit lists must separate elements with commas. Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd). #### `author` header The `author` header optionally lists the names, email addresses or usernames of the authors/owners of the KIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be: > Random J. User <address@dom.ain> or > Random J. User (@username) if the email address or GitHub username is included, and > Random J. User if the email address is not given. #### `resolution` header The `resolution` header is required for Standards Track KIPs only. It contains a URL that should point to an email message or other web resource where the pronouncement about the KIP is made. #### `discussions-to` header While a KIP is a draft, a `discussions-to` header will indicate the mailing list or URL where the KIP is being discussed. As mentioned above, examples for places to discuss your KIP include an issue in this repo or in a fork of this repo. No `discussions-to` header is necessary if the KIP is being discussed privately with the author. As a single exception, `discussions-to` cannot point to GitHub pull requests. #### `type` header The `type` header specifies the type of KIP: Standards Track, Meta, or Informational. If the track is Standards Track, please include the subcategory (core, networking, storage, interface, token, SDK or application). #### `category` header The `category` header specifies the KIP's category. This is required for standards-track KIPs only. #### `created` header The `created` header records the date that the KIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14. #### `updated` header The `updated` header records the date(s) when the KIP was updated with "substantial" changes. This header is only valid for KIPs of Draft and Active status. #### `requires` header KIPs may have a `requires` header, indicating the KIP numbers that this KIP depends on. #### `superseded-by` and `replaces` headers KIPs may also have a `superseded-by` header indicating that a KIP has been rendered obsolete by a later document; the value is the number of the KIP that replaces the current document. The newer KIP must have a `replaces` header containing the number of the KIP that it rendered obsolete. ## Auxiliary Files KIPs may include auxiliary files such as diagrams. Such files must be named KIP-XXXX-Y.ext, where “XXXX” is the KIP number, “Y” is a serial number (starting at 1), and “ext” is replaced by the actual file extension (e.g. “png”). ## Transferring KIP Ownership It occasionally becomes necessary to transfer ownership of KIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred KIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the KIP process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the KIP. We try to build consensus around a KIP, but if that's not possible, you can always submit a competing KIP. If you are interested in assuming ownership of a KIP, send a message asking to take over, addressed to both the original author and the KIP editor. If the original author doesn't respond to email in a timely manner, the KIP editor will make a unilateral decision (it's not like such decisions can't be reversed :)). ## KIP Editors The current KIP editors are ` * Kyungup Kim (@KimKyungup)` ` * Junghyun Colin Kim (@kjhman21)` ` * Sangmin Seo (@smseo)` ## KIP Editor Responsibilities For each new KIP that comes in, an editor does the following: - Read the KIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to final status. - The title should accurately describe the content. - Check the KIP for language (spelling, grammar, sentence structure, etc.), markup (Github flavored Markdown), code style If the KIP isn't ready, the editor will send it back to the author for revision, with specific instructions. Once the KIP is ready for the repository, the KIP editor will: - Assign a KIP number (generally the PR number or, if preferred by the author, the Issue # if there was discussion in the Issues section of this repository about this KIP) - Merge the corresponding pull request - Send a message back to the KIP author with the next step. Many KIPs are written and maintained by developers with write access to the Kaia codebase. The KIP editors monitor KIP changes, and correct any structure, grammar, spelling, or markup mistakes we see. The editors don't pass judgment on KIPs. We merely do the administrative & editorial part. ## History This document was derived heavily from [Ethereum's EIP-1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md) written by Martin Becze, Hudson Jameson, et al. [Ethereum's EIP-1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md) was derived heavily from [Bitcoin's BIP-0001](https://github.com/bitcoin/bips) written by Amir Taaki which in turn was derived from [Python's PEP-0001](https://www.python.org/dev/peps/). In many places text was simply copied and modified. The authors of the documents are not responsible for its use in the Kaia Improvement Proposal, and should not be bothered with technical questions specific to Kaia or the KIP. Please direct all comments to the KIP editors. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Klaytn Keystore Format v4

Fri, 03 Jan 2020 00:00:00 +0000

Fungible Token Standard

Thu, 20 Feb 2020 00:00:00 +0000

Interface Query Standard

Thu, 27 Feb 2020 00:00:00 +0000

## Simple Summary This KIP defines a method to query whether a contract implements a certain interface or not. ## Abstract This proposal defines: 1. [How interface identifiers are defined](#how-interface-identifiers-are-defined) 2. [How a contract publishes the interfaces it implements](#how-a-contract-publishes-the-interfaces-it-implements) 3. [How to query if a contract implements KIP-13](#how-to-query-if-a-contract-implements-kip-13) 4. [How to query if a contract implements any given interface](#how-to-query-if-a-contract-implements-any-given-interface) ## Motivation Since there is no clear way to find what functions are implemented in a contract, this KIP proposes a standard method to define and query interfaces in a contract. For example, if we define an interface identifier of [KIP-7](https://kips.klaytn.com/KIPs/kip-7), we can easily determine a contract implements [KIP-7](https://kips.klaytn.com/KIPs/kip-7) or not. ## Specification This document derived heavily from Ethereum's [ERC-165](https://eips.ethereum.org/EIPS/eip-165) written by Christian Reitwießner, Nick Johnson, Fabian Vogelsteller, Jordi Baylina, Konrad Feldmeier, and William Entriken. ### How Interface Identifiers are Defined An *interface identifier* is a combination of function selectors of a contract. A function selector is four bytes of keccak256 hash of the signature of a function (e.g., `bytes4(keccak256('supportsInterface(bytes4)'))`). The signature is defined as the canonical expression of the basic prototype without parameter names and the return type. We define the interface identifier as the XOR of all function selectors in the interface. This code example below shows how to calculate an interface identifier: ```solidity pragma solidity ^0.4.24; interface Solidity101 { function hello() external pure; function world(int) external pure; } contract Selector { function calculateSelector() public pure returns (bytes4) { Solidity101 i; return i.hello.selector ^ i.world.selector; } } ``` Note: interfaces do not permit optional functions, therefore, the interface identifier will not include them. ### How a Contract Publishes the Interfaces it Implements A contract that is compliant with KIP-13 shall implement the following interface (referred as `InterfaceIdentifier.sol`): ```solidity pragma solidity ^0.4.24; interface InterfaceIdentifier { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as defined in KIP-13. /// @dev Interface identifier is defined in KIP-13. This function /// uses less than 30,000 gas. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise. function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` The interface identifier for this interface is `0x01ffc9a7`. You can calculate this by running `bytes4(keccak256('supportsInterface(bytes4)'));` or using the `Selector` contract above. The implementing contract will have a `supportsInterface` function, and it returns: - `true` when `interfaceID` is `0x01ffc9a7` (`supportsInterface` itself) - `false` when `interfaceID` is `0xffffffff` - `true` for `interfaceID` this contract implements - `false` for any other `interfaceID` This function must return a bool and use at most 30,000 gas. Implementation note: there are several logical ways to implement this function. Please see the example implementations and the discussion on gas usage. ### How to Query if a Contract Implements KIP-13 1. The source contract makes a `STATICCALL` to the destination address with input data: `0x01ffc9a701ffc9a700000000000000000000000000000000000000000000000000000000` and gas 30,000. This corresponds to `contract.supportsInterface(0x01ffc9a7)`. 2. If the call fails or return false, the destination contract does not implement KIP-13. 3. If the call returns true, a second call is made with input data `0x01ffc9a7ffffffff00000000000000000000000000000000000000000000000000000000`. This corresponds to `contract.supportsInterface(0xffffffff)`. 4. If the second call fails or returns true, the destination contract does not implement KIP-13. 5. Otherwise it implements KIP-13. ### How to Query if a Contract Implements any Given Interface 1. If you are not sure if the contract implements KIP-13, use the above procedure to confirm. 2. If it does not implement KIP-13, then you will have to see what methods it uses in other way. 3. If it implements KIP-13 then just call `supportsInterface(interfaceID)` to determine if it implements an interface you can use. ## Rationale We tried to keep this specification as simple as possible. This implementation is also compatible with the current Solidity version. ## Backwards Compatibility The mechanism described above (with `0xffffffff`) should work with most of the contracts previous to this standard to determine that they do not implement KIP-13. ## Test Cases Following is a contract that detects which interfaces other contracts implement. From @fulldecent and @jbaylina. ```solidity pragma solidity ^0.4.24; contract supportsInterfaceQuery { bytes4 constant InvalidID = 0xffffffff; bytes4 constant supportsInterfaceID = 0x01ffc9a7; function doesContractImplementInterface(address _contract, bytes4 _interfaceId) external view returns (bool) { uint256 success; uint256 result; (success, result) = noThrowCall(_contract, supportsInterfaceID); if ((success==0)||(result==0)) { return false; } (success, result) = noThrowCall(_contract, InvalidID); if ((success==0)||(result!=0)) { return false; } (success, result) = noThrowCall(_contract, _interfaceId); if ((success==1)&&(result==1)) { return true; } return false; } function noThrowCall(address _contract, bytes4 _interfaceId) constant internal returns (uint256 success, uint256 result) { bytes4 id = supportsInterfaceID; assembly { let x := mload(0x40) // Find empty storage location using "free memory pointer" mstore(x, id) // Place signature at beginning of empty storage mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature success := staticcall( 30000, // 30k gas _contract, // To addr x, // Inputs are stored at location x 0x24, // Inputs are 36 bytes long x, // Store output over input (saves space) 0x20) // Outputs are 32 bytes long result := mload(x) // Load the result } } } ``` ## Implementation This approach uses a `view` function implementation of `InterfaceIdentifier`. The execution cost is 586 gas for any input. But contract initialization requires storing each interface (`SSTORE` is 20,000 gas). The `MappingImplementation` contract is generic and reusable. ```solidity pragma solidity ^0.4.24; import "./InterfaceIdentifier.sol"; contract MappingImplementation is InterfaceIdentifier { /// @dev You must not set element 0xffffffff to true mapping(bytes4 => bool) internal supportedInterfaces; function MappingImplementation() internal { supportedInterfaces[this.supportsInterface.selector] = true; } function supportsInterface(bytes4 interfaceID) external view returns (bool) { return supportedInterfaces[interfaceID]; } } interface Simpson { function is2D() external returns (bool); function skinColor() external returns (string); } contract Lisa is MappingImplementation, Simpson { function Lisa() public { supportedInterfaces[this.is2D.selector ^ this.skinColor.selector] = true; } function is2D() external returns (bool){} function skinColor() external returns (string){} } ``` Following is a `pure` function implementation of `InterfaceIdentifier`. The worst-case execution cost is 236 gas, but increases linearly with a higher number of supported interfaces. ```solidity pragma solidity ^0.4.24; import "./InterfaceIdentifier.sol"; interface Simpson { function is2D() external returns (bool); function skinColor() external returns (string); } contract Homer is InterfaceIdentifer, Simpson { function supportsInterface(bytes4 interfaceID) external view returns (bool) { return interfaceID == this.supportsInterface.selector || // InterfaceIdentifier interfaceID == this.is2D.selector ^ this.skinColor.selector; // Simpson } function is2D() external returns (bool){} function skinColor() external returns (string){} } ``` With three or more supported interfaces (including KIP-13 itself as a required supported interface), the mapping approach (in every case) costs less gas than the pure approach (at worst case). ## References - https://eips.ethereum.org/EIPS/eip-165 - https://solidity.readthedocs.io/en/develop/abi-spec.html#function-selector ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Non-fungible Token Standard

Wed, 04 Mar 2020 00:00:00 +0000

Klaytn SDK Common Architecture

Thu, 02 Jul 2020 00:00:00 +0000

Token Standard

Wed, 19 Aug 2020 00:00:00 +0000

Dynamic Gas Fee Pricing Mechanism

Thu, 14 Apr 2022 00:00:00 +0000

Implementing the on-chain governance voting method

Mon, 19 Sep 2022 00:00:00 +0000

## Simple Summary Introducing a new governance voting method based on the staking amount and implementation of the Klaytn Square, a governance portal ## Abstract Klaytn introduces a stake-based governance model that provides voting power to governance participants. Currently, one vote per Governance Council(GC) member was cast. The new method will introduce the voting right that will be exercised based on the staking amount with the maximum cap to prevent an entity from making an arbitrary decision. The voting agenda is determined through discussion on the Klaytn Governance Forum, and the topic will be presented and voted on at the newly launched Governance Portal, Klaytn Square. This voting mechanism aims to provide responsibility and obligation of voting to Governance Councils. ## Motivation The new on-chain voting mechanism discloses GC’s opinion transparently through the portal, allowing anyone to view the result. The governance agenda discussed in Klaytn Governance Forum will be voted on the governance portal, Klaytn Square. Since the voting power is calculated based on the staking amount, this voting process provides more power to GC members who share the same interest as Klaytn by staking and locking up more KLAYs. ## Specification Klaytn Governance Forum is to freely propose and discuss Klaytn governance items. Once Klaytn Square, the governance portal, opens, the on-chain voting will be executed based on the discussion held in this forum. Klaytn Square includes the following functions: - Ability to vote on a governance agenda and view the voting process - Information about Governance Councils: description, contract address, notice, staking status, staking and reward history, etc. - View the history of governance agenda and Governance Councils ![voting process diagram](/assets/kip-81/voting_process_diagram.png) The foundation will provide 7 days of preparation period for voting, providing a time for GC to adjust the staking amount. With the start of the voting, the foundation will announce the list of GC members and their voting power. GC will have 7 days of the voting period. The Klaytn governance voting system is designed based on the following fundamental premises. - Klaytn’s major decision-making process should reflect the opinions of as many participants as possible from the ecosystem. - Participants will be more likely to make a decision that is beneficial to the Klaytn ecosystem if they hold more KLAY. This is based on the premise that the growth of Klaytn’s ecosystem is correlated to the rise in the value of KLAY. - The governance system should be able to manage the situations in which a particular entity makes an arbitrary decision. This is because the entity may weaken the sustainability of the entire network. - The act of voting and the gain of voting power is different. Recognizing a tendency that the member with more KLAY makes a decision that benefits the Klaytn ecosystem in the long run, we are granting a higher voting power to members with more KLAY. Yet, to prevent a particular subject from making an arbitrary decision, we are placing a cap on the voting power one can receive at the maximum. Therefore, a GC member will receive 1 vote per a certain amount of staked KLAY (initial configuration: 5 million KLAY). The maximum number of votes a member can own is one less than the total number of GC members. In other words, [Maximum Voting Power = Total number of GC members - 1]. For example, if there are 35 GC members, one can own a maximum of 34 voting power. This cap structure prevents potential monopolies. ### Smart Contracts Overview The Klaytn on-chain governance voting will be conducted on smart contracts. Several contracts and accounts interact together in the process. The below diagram shows the relationship between contracts and accounts. Find an example implementation [here](https://github.com/klaytn/governance-contracts-audit). - Contracts - **AddressBook**: an existing contract that stores the list of GC nodes, their staking contracts, and their reward recipient addresses. - **CnStakingV2**: an updated version of the existing CnStakingContract. GCs stake their KLAYs to earn rights to validate blocks and cast on-chain votes. - **StakingTracker**: a new contract that tracks voting-related data from AddressBook and CnStakingV2 contracts. - **Voting**: a new contract that processes the on-chain voting. It stores governance proposals, counts votes, and sends approved transactions. - Accounts - **AddressBook admins**: a set of accounts controlled by the Foundation which can manage the list of GCs in the AddressBook. AddressBook admins are managed in the AddressBook contract. - **CnStaking admins**: a set of accounts controlled by each GC that can manage the staked KLAYs and its voter account. CnStaking admins are managed in the respective CnStakingV2 contracts. Note that every CnStakingV2 contract has a different set of admins. - **Voter account**: an account controlled by each GC member that can cast on-chain votes. But this account cannot withdraw KLAYs from CnStakingV2 contracts. A Voter account is appointed at CnStakingV2 contracts of the respective GC member. - **Secretariat account**: an account controlled by the Foundation which can propose and execute on-chain governance proposals. The secretariat account is managed in the Voting contract. ![contracts and accounts](/assets/kip-81/smart_contract_relation.png) ### AdressBook In Cypress mainnet and Baobab testnet, an [AddressBook contract](https://github.com/klaytn/klaytn/blob/v1.9.1/contracts/reward/contract/AddressBook.sol) is deployed at address `0x0000000000000000000000000000000000000400`. For the purpose of Voting, the following function of the AddressBook is used. ```solidity interface IAddressBook { /// @dev Returns all addresses in the AddressBook. /// /// Each GC's addresses are stored in the same index of the three arrays. /// i.e. GC[i] is described in (nodeIds[i], stakingContracts[i], rewardAddresses[i]) /// However, a GC may operate multiple staking contracts. In this case, /// the GC occupies multiple indices with the same reward address. /// /// @return nodeIds GC consensus node address list /// @return stakingContracts GC staking contract address list /// @return rewardAddresses GC reward recipient address list /// @return pocAddress PoC(KGF) recipient address /// @return kirAddress KIR recepient address function getAllAddressInfo() external view returns( address[] memory nodeIds, address[] memory stakingContracts, address[] memory rewardAddresses, address pocAddress, address kirAddress); } ``` ### CnStakingV2 CnStakingV2 is an upgraded version of [CnStakingContract](https://github.com/klaytn/klaytn/blob/v1.9.1/contracts/cnstaking/CnStakingContract.sol). The CnStakingContract has been serving the purpose of locking GC stakes. V2 will add two new features related to StakingTracker, which will be described later. - It holds a new unique identifier "GC ID" which is a nonzero integer assigned to each GC member. If a GC member owns multiple CnStakingV2 contracts, the contracts must contain the same GC ID value. - Whenever its KLAY balance changes, V2 notifies the StakingTracker. - V2 stores a voter account address, and notifies the StakingTracker whenever it changes. The voter account can be changed by its admins. To support the new features, the following functions are added. The functions `setStakingTracker` and `setGCId` is only callable before contract [initialization](https://github.com/klaytn/klaytn/blob/v1.9.1/contracts/cnstaking/CnStakingContract.sol#L237). Functions `updateStakingTracker` and `updateVoterAddress` are invoked upon approval of CnStaking admins using the existing [CnStaking multisig facility](https://github.com/klaytn/klaytn/blob/v1.9.1/contracts/cnstaking/CnStakingContract.sol#L597). ```solidity abstract contract CnStakingV2 { event UpdateStakingTracker(address stakingTracker); event UpdateVoterAddress(address voterAddress); event UpdateGCId(uint256 gcId); function stakingTracker() external view returns(address); function voterAddress() external view returns(address); function gcId() external view returns(uint256); /// @dev Set the initial stakingTracker address /// Emits an UpdateStakingTracker event. function setStakingTracker(address _tracker) external beforeInit; /// @dev Set the gcId /// The gcId never changes once initialized. /// Emits an UpdateGCId event. function setGCId(uint256 _gcId) external beforeInit; /// @dev Update the StakingTracker address this contract reports to /// Emits an UpdateStakingTracker event. function submitUpdateStakingTracker(address _tracker) external; function updateStakingTracker(address _tracker) external onlyMultisigTx; /// @dev Update the voter address of this GC /// Emits an UpdateVoterAddress event. function submitUpdateVoterAddress(address _addr) external; function updateVoterAddress(address _addr) external onlyMultisigTx; } ``` #### Notifying changes to StakingTracker To notify balance and voter account changes to the StakingTracker contract, the CnStakingV2 contract shall call the StakingTracker whenever after every change. For example, ```solidity abstract contract CnStakingV2 { function depositLockupStakingAndInit() payable beforeInit() { // ... stakingTracker.refreshStake(address(this)); } function stakeKlay() payable { // ... stakingTracker.refreshStake(address(this)); } function withdrawLockupStaking(address _to, uint256 _value) { // ... _to.transfer(_value); stakingTracker.refreshStake(address(this)); } function withdrawApprovedStaking(uint256 _approvedWithdrawalId) { // ... _to.transfer(_value); stakingTracker.refreshStake(address(this)); } function updateVoterAddress(address _addr) { // ... voterAddress = _addr; stakingTracker.refreshVoter(address(this)); } } interface IStakingTracker { /// @dev Re-evaluate Tracker contents related to the staking contract /// @param staking The CnStaking contract address function refreshStake(address staking) external; /// @dev Update a GC's voter address from the given address /// @param staking The CnStaking contract address function refreshVoter(address staking) external; } ``` #### Version identifier To distinguish the CnStakingContract and CnStakingV2 contracts, V2 will have VERSION value 2. ```solidity abstract contract CnStakingV2 { uint256 constant public VERSION = 2; } ``` #### Example implementation See [here](https://github.com/klaytn/governance-contracts-audit/blob/main/contracts/CnStakingV2.sol) for an example implementation. ### StakingTracker StakingTracker collects voting-related data of each GC member. - Staking amounts and voting powers \ Stored separately in `Tracker` structs. Each `Tracker` struct can be updated between `trackStart` and `trackEnd` blocks, but becomes immutable afterward, essentially freezing the voting powers. A `Tracker` struct is first created in `createTracker()`, and updated by `refreshStake()`. - Each GC’s voter accounts \ Stored in global mappings, and can be updated at any time. Voter account mappings are updated by `refreshVoter()`. #### Contract interface ```solidity abstract contract StakingTracker { struct Tracker { // Tracked block range. // Balance changes are only updated if trackStart <= block.number < trackEnd. uint256 trackStart; uint256 trackEnd; // Determined at createTracker() and does not change. uint256[] gcIds; mapping(uint256 => bool) gcExists; mapping(address => uint256) stakingToGCId; // Balances and voting powers. // First collected at createTracker() and updated at refreshStake() until trackEnd. mapping(address => uint256) stakingBalances; // staking address balances mapping(uint256 => uint256) gcBalances; // consolidated GC balances mapping(uint256 => uint256) gcVotes; // GC voting powers uint256 totalVotes; uint256 numEligible; } // Tracker objects. Added by createTracker(). mapping(uint256 => Tracker) private trackers; // trackerId => Tracker uint256[] private allTrackerIds; // 1-to-1 mapping between nodeId and voter account. // Updated by refreshVoter(). mapping(uint256 => address) public gcIdToVoter; mapping(address => uint256) public voterToGCId; // Minimum staking amount to have 1 vote function MIN_STAKE() external view returns(uint256); /// @dev Creates a new Tracker and populate initial values from AddressBook function createTracker(uint256 trackStart, uint256 trackEnd) external returns(uint256 trackerId); /// @dev Re-evaluate Tracker contents related to the staking contract /// Anyone can call this function, but `staking` must be a staking contract /// registered to the AddressBook. function refreshStake(address staking) external; /// @dev Re-evaluate voter account mapping related to the staking contract /// Anyone can call this function, but `staking` must be a staking contract /// registered to the AddressBook. /// Note that two different nodes cannot appoint the same voter address. function refreshVoter(address staking) external; /// @dev Return integer fields of a tracker function getTrackerSummary(uint256 trackerId) external view returns( uint256 trackStart, uint256 trackEnd, uint256 numGCs, uint256 totalVotes, uint256 numEligible) /// @dev Return balances and votes of all GC members stored in a tracker function getAllTrackedGCs(uint256 trackerId) external view returns( uint256[] memory gcIds, uint256[] memory gcBalances, uint256[] memory gcVotes) /// @dev Return the balance and votes of a specified GC member function getTrackedGC(uint256 trackerId, uint256 gcId) external view returns( uint256 gcBalance, uint256 gcVotes) } ``` #### Usage A voting contract can utilize StakingTracker as follows. 1. When a governance proposal is submitted, the voting contract calls `createTracker()` to finalize the eligible GC members list and evaluate voting powers. 2. Before `trackEnd` block, GC members stake or unstake their KLAYs from their CnStakingV2 contracts. The CnStakingV2 contracts will then call `refreshStake()` to notify the balance change. 3. GC members may change their voter account in their CnStakingV2 contracts. The CnStakingV2 contracts will then call `refreshVoter()` to notify voter account change. 4. After `trackEnd` block, the voting powers are frozen. The voting contract uses StakingTracker getters to process votes cast by voter accounts. #### Example implementation See [here](https://github.com/klaytn/governance-contracts-audit/blob/main/contracts/StakingTracker.sol) for an example implementation. ### Voting The Voting contract operates the on-chain governance votes. The Voting contract stores governance proposals, counts casted votes, and sends on-chain transactions. Its design is influenced by [Compound Finance](https://docs.compound.finance/v2/governance/) and [OpenZeppelin](https://docs.openzeppelin.com/contracts/4.x/api/governance). A proposal contains textual descriptions and optionally on-chain transactions. The transactions are executed on behalf of the voting contract if the proposal receives enough votes. While GCs hold their voting rights from staked KLAYs, a special secretariat account manages the overall on-chain governance process. Governance proposals can be submitted by the secretariat account, or any GC if the secretariat account is not set. The secretariat account can be updated by on-chain governance. #### Voting steps overview Under the default timing settings, a typical governance proposal is handled as follows. 1. When a governance proposal is submitted, it enters a 7-day preparation period where GCs can adjust their voting powers by staking or unstaking KLAYs. The list of voters (i.e., GCs) is finalized at the moment of proposal submission. However, voting powers are finalized at the end of the preparation period. 2. A 7-day voting period immediately follows after the preparation period. 3. If there are enough Yes votes, the transactions can be queued within 14 days after voting ends. 4. The transaction is delayed by 2 days to be executable. This delay gives the ecosystem enough time to adjust to the change and perform a final review of transactions. 5. After the delay, the transaction can be executed within 14 days. The proposer of a proposal can cancel it at any time prior to execution. If a passed transaction is not queued or executed within the timeout, the proposal automatically expires. ![voting steps](/assets/kip-81/voting_steps.png) #### Access control Voting contract has two category of users, secretary and voters. - The secretary is a single account stored in the `secretary` variable. This account is intended to be controlled by the Klaytn Foundation. It will serve the GC by assisting administrative works such as submitting and executing proposals. - The voters are identified by their GC ID. The list of voters differs per proposal, depending on the list of GC members registered in AddressBook and their staking amounts at the time of proposal submission. In its default setting, only the secretary can propose and execute proposals. Later the voters may be allowed to propose and execute proposals by changing the following access rule. | Name | Meaning | Default Value | | --- | --- | --- | | `secretaryPropose` | True if the secretary can propose() | true | | `voterPropose` | True if any eligible voter at the time of the submission can propose() a proposal | false | | `secretaryExecute` | True if the secretary can queue() and execute() | true | | `voterExecute` | True if any eligible voter of a given proposal can queue() and execute() the proposal | false | #### Timing rule The proposal timeline is dictated by several timing values below. The settings are expressed in block numbers. The number of days in the below table is calculated based on 1 block/sec assumption. To support flexible operation, Voting contract allows each proposal to have different `votingDelay` and `votingPeriod` within respective min and max values. However, `queueTimeout`, `execDelay` and `execTimeout` are should not be configurable. | Name | Meaning | Default Value | Configurability | |-------------------|--------------------------------------------------------------|-------------------|------------------------| | `minVotingDelay` | Minimum `votingDelay` | 86400 (1 day) | via `updateTimingRule` | | `maxVotingDelay` | Maximum `votingDelay` | 2419200 (28 days) | via `updateTimingRule` | | `minVotingPeriod` | Minimum `votingPeriod` | 86400 (1 day) | via `updateTimingRule` | | `maxVotingPeriod` | Maximum `votingPeriod` | 2419200 (28 days) | via `updateTimingRule` | | `votingDelay` | Delay from proposal submission to voting start | | Specify per proposal | | `votingPeriod` | Duration of the voting | | Specify per proposal | | `queueTimeout` | Grace period to queue() passed proposals | 1209600 (14 days) | Cannot modify | | `execDelay` | A minimum delay before a queued transaction can be executed | 172800 (2 days) | Cannot modify | | `execTimeout` | Grace period to execute() queued proposals since `execDelay` | 1209600 (14 days) | Cannot modify | #### Quorum A proposal passes when it satisfies a combination of the following conditions. - `CountQuorum` = At least 1/3 of all eligible voters cast votes - `PowerQuorum` = At least 1/3 of all eligible voting powers cast votes - `MajorityYes` = Yes votes are more than half of total cast votes (i.e. `Yes > No + Abstain`) - `PassCondition = (CountQuorum or PowerQuorum) and MajorityYes` #### Contract interface ```solidity interface Voting { enum ProposalState { Pending, Active, Canceled, Failed, Passed, Queued, Expired, Executed } enum VoteChoice { No, Yes, Abstain } struct Receipt { bool hasVoted; uint8 choice; uint256 votes; } // events /// @dev Emitted when a proposal is created /// @param signatures Array of empty strings; for compatibility with OpenZeppelin event ProposalCreated( uint256 proposalId, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 voteStart, uint256 voteEnd, string description); /// @dev Emitted when a proposal is canceled event ProposalCanceled(uint256 proposalId); /// @dev Emitted when a proposal is queued /// @param eta The block number where transaction becomes executable. event ProposalQueued(uint256 proposalId, uint256 eta); /// @dev Emitted when a proposal is executed event ProposalExecuted(uint256 proposalId); /// @dev Emitted when a vote is cast /// @param reason An empty string; for compatibility with OpenZeppelin event VoteCast(address indexed voter, uint256 proposalId, uint8 choice, uint256 votes, string reason); /// @dev Emitted when the StakingTracker is changed event UpdateStakingTracker(address oldAddr, address newAddr); /// @dev Emitted when the secretary is changed event UpdateSecretary(address oldAddr, address newAddr); /// @dev Emitted when the AccessRule is changed event UpdateAccessRule( bool secretaryPropose, bool voterPropose, bool secretaryExecute, bool voterExecute); /// @dev Emitted when the TimingRule is changed event UpdateTimingRule( uint256 minVotingDelay, uint256 maxVotingDelay, uint256 minVotingPeriod, uint256 maxVotingPeriod); // mutator functions /// @dev Create a Proposal /// @param description Proposal text /// @param targets List of transaction target addresses /// @param values List of KLAY values to send along with transactions /// @param calldatas List of transaction calldatas /// @param votingDelay Delay from proposal submission to voting start in block numbers /// @param votingPeriod Duration of the voting in block numbers function propose( string memory description, address[] memory targets, uint256[] memory values, bytes[] memory calldatas, uint256 votingDelay, uint256 votingPeriod ) external returns (uint256 proposalId); /// @dev Cancel a proposal /// The proposal must be in Pending state /// Only the proposer of the proposal can cancel the proposal. function cancel(uint256 proposalId) external; /// @dev Cast a vote to a proposal /// The proposal must be in Active state /// A node can only vote once for a proposal /// choice must be one of VoteChoice. function castVote(uint256 proposalId, uint8 choice) external; /// @dev Queue a passed proposal /// The proposal must be in Passed state /// Current block must be before `queueDeadline` of this proposal /// If secretary is null, any GC with at least 1 vote can queue. /// Otherwise only secretary can queue. function queue(uint256 proposalId) external; /// @dev Execute a queued proposal /// The proposal must be in Queued state /// Current block must be after `eta` and before `execDeadline` of this proposal /// If secretary is null, any GC with at least 1 vote can execute. /// Otherwise only secretary can execute. function execute(uint256 proposalId) external payable; /// @dev Update the StakingTracker address /// Should not be called if there is an active proposal function updateStakingTracker(address newAddr) external; /// @dev Update the secretary account function updateSecretary(address newAddr) external; /// @dev Update the access rule function updateAccessRule( bool secretaryPropose, bool voterPropose, bool secretaryExecute, bool voterExecute) external; /// @dev Update the timing rule function updateTimingRule( uint256 minVotingDelay, uint256 maxVotingDelay, uint256 minVotingPeriod, uint256 maxVotingPeriod) external; // getter functions function stakingTracker() external view returns(address); function secretary() external view returns(address); function accessRule() external view returns( bool secretaryPropose, bool voterPropose, bool secretaryExecute, bool voterExecute); function timingRule() external view returns( uint256 minVotingDelay, uint256 maxVotingDelay, uint256 minVotingPeriod, uint256 maxVotingPeriod); function queueTimeout() external view returns(uint256); function execDelay() external view returns(uint256); function execTimeout() external view returns(uint256); /// @dev The id of the last created proposal /// Retrurns 0 if there is no proposal. function lastProposalId() external view returns(uint256); /// @dev State of a proposal function state(uint256 proposalId) external view returns(ProposalState); /// @dev Check if a proposal is passed /// Note that its return value represents the current voting status, /// and is subject to change until the voting ends. function checkQuorum(uint256 proposalId) external view returns(bool); /// @dev Resolve the voter account into its gcId and voting powers /// Returns the currently assigned gcId. Returns the voting powers /// effective at the given proposal. Returns zero gcId and 0 votes /// if the voter account is not assigned to any eligible GC. /// /// @param proposalId The proposal id /// @return gcId The gcId assigned to this voter account /// @return votes The amount of voting powers the voter account represents function getVotes(uint256 proposalId, address voter) external view returns(uint256, uint256); /// @dev General contents of a proposal function getProposalContent(uint256 proposalId) external view returns( uint256 id, address proposer, string memory description ); /// @dev Transactions in a proposal /// @return signatures Array of empty strings; for compatibility with OpenZeppelin function function getActions(uint256 proposalId) external view returns( address[] memory targets, uint256[] memory values, string[] memory signatures, bytes[] memory calldatas ); /// @dev Timing and state related properties of a proposal function getProposalSchedule(uint256 proposalId) external view returns( uint256 voteStart, // propose()d block + votingDelay uint256 voteEnd, // voteStart + votingPeriod uint256 queueDeadline, // voteEnd + queueTimeout uint256 eta, // queue()d block + execDelay uint256 execDeadline, // queue()d block + execDelay + execTimeout bool canceled, // true if successfully cancel()ed bool queued, // true if successfully queue()d bool executed // true if successfully execute()d ); /// @dev Vote counting related properties of a proposal function getProposalTally(uint256 proposalId) external view returns( uint256 totalYes, uint256 totalNo, uint256 totalAbstain, uint256 quorumCount, // required number of voters uint256 quorumPower, // required number of voting powers uint256[] memory voters, // list of gcIds who voted ) /// @dev Individual vote receipt function getReceipt(uint256 proposalId, uint256 gcId) external view returns(Receipt memory); } ``` #### Fetching votes from StakingTracker Calculating votes requires information from StakingTracker contract. The Voting contract shall utilize the getters to find the voting powers of each voter as well as quorum conditions. Below is an example implementation of `castVote()` and `checkQuorum()` functions. ```solidity abstract contract Voting { struct Proposal { uint256 trackerId; // StakingTracker trackerId created in propose() uint256 totalYes; uint256 totalNo; uint256 totalAbstain; uint256[] voters; // List of gcIds mapping(uint256 => Receipt) receipts; } mapping(uint256 => Proposal) proposals; IStakingTracker stakingTracker; function castVote(uint256 proposalId, uint8 choice) external { Proposal storage p = proposals[proposalId]; (uint256 gcId, uint256 votes) = getVotes(proposalId, msg.sender); require(gcId != 0, "Not a registered voter"); require(votes > 0, "Not eligible to vote"); require(choice == uint8(VoteChoice.Yes) || choice == uint8(VoteChoice.No) || choice == uint8(VoteChoice.Abstain), "Not a valid choice"); require(!p.receipts[gcId].hasVoted, "Already voted"); p.receipts[gcId].hasVoted = true; p.receipts[gcId].choice = choice; p.receipts[gcId].votes = votes; if (choice == VoteChoice.Yes) { p.totalYes += votes; } if (choice == VoteChoice.No) { p.totalNo += votes; } if (choice == VoteChoice.Abstain) { p.totalAbstain += votes; } p.voters.push(gcId); } function getVotes(uint256 proposalId, address voter) public view returns( uint256 gcId, uint256 votes) { Proposal storage p = proposals[proposalId]; gcId = IStakingTracker(p.stakingTracker).voterToGCId(voter); ( , votes) = IStakingTracker(p.stakingTracker).getTrackedGC(p.trackerId, gcId); } function checkQuorum(uint256 proposalId) external view returns(bool) { Proposal storage p = proposals[proposalId]; (uint256 quorumCount, uint256 quorumPower) = getQuorum(proposalId); uint256 totalVotes = p.totalYes + p.totalNo + p.totalAbstain; uint256 quorumYes = p.totalNo + p.totalAbstain + 1; // more than half of all votes bool countPass = (p.voters.length >= quorumCount); bool powerPass = (totalVotes >= quorumPower); bool approval = (p.totalYes >= quorumYes); return ((countPass || powerPass) && approval); } /// @dev Calculate count and power quorums for a proposal function getQuorum(uint256 proposalId) private view returns( uint256 quorumCount, uint256 quorumPower) { Proposal storage p = proposals[proposalId]; if (p.quorumCount != 0) { // return cached numbers return (p.quorumCount, p.quorumPower); } ( , , , uint256 totalVotes, uint256 numEligible) = IStakingTracker(p.stakingTracker).getTrackerSummary(p.trackerId); quorumCount = (numEligible + 2) / 3; // more than or equal to 1/3 of all GC members quorumPower = (totalVotes + 2) / 3; // more than or equal to 1/3 of all voting powers return (quorumCount, quorumPower); } } ``` #### Determining state The state of a proposal can be determined from stored variables, vote counts, and current block number. Below is an example implementation of `state()` function. ```solidity abstract contract Voting { struct Proposal { uint256 voteStart; // propose()d block + votingDelay uint256 voteEnd; // voteStart + votingPeriod uint256 queueDeadline; // voteEnd + queueTimeout uint256 eta; // queue()d block + execDelay uint256 execDeadline; // queue()d block + execDelay + execTimeout bool canceled; // true if successfully cancel()ed bool queued; // true if successfully queue()d bool executed; // true if successfully execute()d } mapping(uint256 => Proposal) proposals; function state(uint256 proposalId) external view returns (ProposalState) { Proposal storage p = proposals[proposalId]; if (p.executed) { return ProposalState.Executed; } else if (p.canceled) { return ProposalState.Canceled; } else if (block.number < p.voteStart) { return ProposalState.Pending; } else if (block.number <= p.voteEnd) { return ProposalState.Active; } else if (!checkQuorum(proposalId)) { return ProposalState.Failed; } if (!p.queued) { // A proposal without an action does not expire if (block.number <= p.queueDeadline || p.targets.length == 0) { return ProposalState.Passed; } else { return ProposalState.Expired; } } else { if (block.number <= p.execDeadline) { return ProposalState.Queued; } else { return ProposalState.Expired; } } } } ``` #### Executing transactions The transactions in a passed proposal are executed in the order they appear in the `propose()` function arguments. Each transaction is sent to `targets[i]`, carrying `values[i]` of KLAYs, with `calldatas[i]` as input data. Below is an example of `execute()` function. ```solidity abstract contract Voting { struct Proposal { address[] targets; uint256[] values; bytes[] calldatas; } mapping(uint256 => Proposal) proposals; function execute(uint256 proposalId) external payable { Proposal storage p = proposals[proposalId]; for (uint256 i = 0; i < p.targets.length; i++) { (bool success, bytes memory result) = p.targets[i].call{value: p.values[i]}(p.calldatas[i]); require(success, "Transaction failed"); } } } ``` #### Example implementation See [here](https://github.com/klaytn/governance-contracts-audit/blob/main/contracts/Voting.sol) for an example implementation. ## Rationale #### CnStakingV2 and StakingTracker instead of standard ERC20Votes It is common for DAOs to manage their governance tokens in an [ERC20Votes](https://docs.openzeppelin.com/contracts/4.x/api/token/erc20#ERC20Votes) contract. However new contracts CnStakingV2 and StakingTracker were used to manage staked KLAYs. Using the new contracts provides better compatibility with ecosystem Dapps like public staking services. It also does not break the existing block validator selection algorithm that depends on AddressBook. #### StakingTracker refreshStake and refreshVoting has no access control It is a remnant of a previous design. Those functions were originally intended to allow optionally or gradually migrate from CnStakingContract to CnStakingV2 contracts. Now that old CnStakingContract are excluded from the voting power calculation, such a feature is unnecessary but the refreshStake and refreshVoter functions retain its shape. #### Separate voter account In a security standpoint, it is safer to have separate accounts for different roles. Existing CnStakingV2 admins take a financial role - withdrawing staked KLAYs - and the voter account take a voting role only. #### Proposals have expired state Proposal transactions expire if they are not queued or executed within the deadline. This guarantees the timeliness of the transactions. If a proposal was left unexecuted for a long time, the proposal might be irrelevant anymore and require a fresh proposal. ## Expected Effect The proposed GC Voting method is expected to produce the following changes: - All members in the Klaytn ecosystem grow together with credibility - Providing obligation and authority to GC motivates active participation in governance voting activities and the KLAY staking - Anyone can easily view the proposals and voting status through the governance portal. It encourages holders to participate and give responsibility and authority to GCs. - The Klaytn network can take a step closer to transparency and decentralized networks. ## Backward Compatibility - GCs should deploy new CnStakingV2 contracts and move their staked KLAYs. Existing CnStakingContract (i.e. V1) balances are excluded from voting power calculation. - However, block validator selection is not affected by the change, so GCs can still participate in consensus before migrating to CnStakingV2. ## Reference n/a ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

A new GC reward structure due to abolition of the Gini coefficient

Wed, 21 Sep 2022 00:00:00 +0000

## Simple Summary A renewal of the Governance Council(GC) reward structure due to abolition of the Gini coefficient. ## Abstract In addition to traditional enterprises, Klaytn is expanding the Governance Council (GC) by bringing DAOs in response to the growth of nontraditional entities. Such a change in the GC ecosystem will restructure the entire Klaytn governance structure. Abolishing the current block proposal selection method based on the Gini coefficient and staking quantity, the new reward program alleviates the problem of providing insufficient compensation for the network contribution and block verification due to lack of staking. The instability of certain nodes with high staking amounts can result in poor network stability as a whole. The renewed structure provides 20% of GC rewards to block proposers and the rest to the stakers. This form is to reward the participants for providing network stability with node operation and financial contribution. ## Motivation Klaytn has been compensating GC with block proposal rewards based on the quantity of staking and the Gini coefficient. This included rewards incurred by minting and gas fee generated by transactions. As mentioned in the [Klaytn 2.0 Lightpaper](https://klaytn.foundation/wp-content/themes/klaytn/download/lightpaper.pdf), Klaytn is abolishing the Gini coefficient since this measure demotivates members from staking. Discontinuation of the Gini coefficient increases the risk to network stability due to the expanding reliance on certain nodes. This change ultimately calls for the revision of block proposer selection and reward structure. In an effort to enhance individual voting power and promote ultimate decentralization, we aim to accomplish the following changes: - Ameliorate the risk that block creation depends on larger staker nodes - Associate GC reward with the growth of the Klaytn ecosystem ## Specification Block generation is rewarded for the node operations that are serving as public goods in the Klaytn network. CNs and PNs are in charge of block proposal and propagation while ENs are in charge of blockchain data inquiry based on an individual's needs. The infrastructure cost remains similar, enabling some fixed benefits. Therefore, fixed compensation will be equivalent to the sum of the transaction fee and an additional block compensation, which can be both inflationary and deflationary. The block proposal method will be based on equal selection regardless of the staking amount. The current model provides a block generation reward based on staking amount and the Gini-coefficient. Until now, the Gini coefficient was utilized to alleviate the chance of an entity with more staking amount being selected as a block proposer. As this model provided a fairly equal chance to every participant, each node was promised a certain amount of rewards. In the new method, the reward for node operation is required since the staking amount is not considered in the block proposer selection. Therefore, a certain percentage of the total reward amount will be placed as a node operation reward. Node operators will also be compensated with the staking for enhancing network stability from an economic standpoint. The opportunity cost incurred from staking is rewarded based on inflation. In this system, inflation provides a tax-like common effect. Public users can also participate and receive rewards through the GC-run public staking program. As of September 21st, 2022, of the 300 million KLAY that is minted annually, only 100 million KLAY goes to GC. The renewal separates GC reward into two components: block proposer reward and staking reward. The block proposer reward is compensating for node operation by providing 20% of the GC reward and 100% of gas fee resources from transactions. The staking reward is from 80% of the GC reward and is distributed based on GC staking amounts. The relative ratio of 20% and 80% is a tentative value to be used in the Cypress mainnet. However, this ratio is defined as a governance paramter, so GC members can change the ratio through the governance process. ![gc reward allocation](/assets/kip-82/gc_reward_allocation.png) After the Magma hard fork, Klaytn has been burning the first half of the gas fee based on [the KIP-71 proposal](https://kips.klaytn.foundation/KIPs/kip-71) while the second half is distributed. The second half is distributed into GC reward, KGF and KIR. In addition to changing the reward structure, this renewal will include burning the gas fee up to a threshold which is the size of block proposer reward. If the gas fee exceeds the threshold, remaining amount is rewarded to the block proposer. The KGF and KIR portion will be excluded from the gas fee. ### Klaytn node update The Klaytn node will be updated according to the new reward policy. The CN reward is further split into proposer reward and staking reward. The staking reward is distributed among CNs proportionally to their staking amounts minus the minimum staking amount. A new governance parameter is introduced to tune the new reward distribution algorithm. The initial value below will be used in the Cypress mainnet when KIP-82 is first applied. The parameter can be updated using the existing governance mechanism. | Name | Type | Meaning | Initial Value | |---------------------|--------|---------------------------------------------------------|---------------| | `reward.kip82ratio` | string | The relative ratio between proposer and staking rewards | "20/80" | During integer arithmetics, minuscule remaining amounts may be emitted as by-products. The proposer gets the remainder from the staking share disribution, and KGF gets the the remainder from the distribution among proposer, stakers, KIR, KGF. Below pseudocode illustrates the new reward distribution algorithm. Note: `//` is round down integer division. ```python from collections import defaultdict MAGMA_BLOCK_NUMBER = 99841497 KORE_BLOCK_NUMBER = 120000000 # TBD # Block header. Only relevant fields are shown here. class Header: Number: int = 0 # Block number GasUsed: int = 0 # Total gas spent in the block BaseFee: int = 0 # Base fee per gas at the block RewardBase: string = "" # Reward recipient address of the block proposer # Network configurations related to reward distribution. # Corresponds to Klaytn's reward.rewardConfig struct. class RewardConfig: # "istanbul.policy" parameter RoundRobin = 0 Sticky = 1 WeightedRandom = 2 ProposerPolicy: int = WeightedRandom UnitPrice: int = 25000000000 # "governance.unitprice" parameter (in peb) MintingAmount: int = 9600000000000000000 # "reward.mintingamount" parameter (in peb) MinimumStake: int = 5000000 # "reward.minimumstake" parameter (in KLAY) DeferredTxFee: bool = True # "reward.deferredtxfee" parameter # "reward.ratio" parameter (e.g. "50/40/10") CnRatio: int = 50 KgfRatio: int = 40 KirRatio: int = 10 TotalRatio: int = CnRatio + KgfRatio + KirRatio # "reward.kip82ratio" parameter (e.g. "20/80") (new) CnProposerRatio: int = 20 CnStakingRatio: int = 80 CnTotalRatio: int = CnProposerRatio + CnStakingRatio # CN staking status and KGF/KIR addresses. # Corresponds to Klaytn's reward.StakingInfo struct. # Can be obtained from reward.GetStakingInfo(blockNum) function. class StakingInfo: KIRAddr: string = "" KGFAddr: string = "" Nodes: List[ConsolidatedNode] = [] # Staking information merged under the same CN. # Sometimes a node would register multiple NodeAddrs # in which each entry has a different StakingAddr and the same RewardAddr. # We treat those entries with common RewardAddr as one node. # Corresponds to Klaytn's reward.ConsolidatedNode struct. class ConsolidatedNode: NodeAddrs: List[string] = [] StakingAddrs: List[string] = [] RewardAddr: string = "" # The common reward address of the CN StakingAmount: int = 0 # Total staking amount across StakingAddrs (in KLAY) # Reward distribution details. class RewardSpec: Minted: int = 0 # The amount newly minted TotalFee: int = 0 # Total tx fee spent BurntFee: int = 0 # The amount burnt Proposer: int = 0 # The amount allocated to the block proposer Stakers: int = 0 # Total amount allocated to stakers Kgf: int = 0 # The amount allocated to KGF Kir: int = 0 # The amount allocated to KIR Rewards: Dict[string, int] = {} # Mapping from reward recipient to amounts # Perform post-transaction state modifications such as block rewards. # Corresponds to Klaytn's consensus/istanbul/backend.Finalize() # # - state is the StateDB to apply the rewards. # - header is a Header instance. # - config is a RewardConfig instance. def finalize_block(state, header, config): if config.ProposerPolicy in [RoundRobin, Sticky]: spec = calc_deferred_reward_simple(header, config) else: spec = calc_deferred_reward(header, config) for addr, amount in spec.Rewards: state.AddBalance(addr, amount) header.Root = state.Root() def calc_deferred_reward_simple(header, config): minted = config.MintingAmount total_fee = get_total_fee(header) if header.Number >= KORE_BLOCK_NUMBER and not config.DeferredTxFee: total_fee = 0 reward_fee = total_fee burnt_fee = 0 if header.Number >= MAGMA_BLOCK_NUMBER: burn_amount = get_burn_amount_magma(reward_fee) reward_fee -= burn_amount burnt_fee += burn_amount proposer = minted + reward_fee spec = RewardSpec() spec.Minted = minted spec.TotalFee = total_fee spec.BurntFee = burnt_fee spec.Proposer = proposer spec.Rewards = {header.RewardBase: proposer} return spec # Calculates the deferred rewards, which are determined at the end of block processing. # Used in reward distribution. # Returns a RewardSpec. def calc_deferred_reward(header, config): staking_info = GetStakingInfo(header.Number) minted = config.MintingAmount total_fee, reward_fee, burnt_fee = calc_deferred_fee(header, config) proposer, stakers, kgf, kir, split_rem = calc_split(header, config, minted, reward_fee) shares, share_rem = calc_shares(config, staking_info, stakers) # Remainder from (CN, KGF, KIR) split goes to KGF kgf += split_rem # Remainder from staker shares goes to Proposer proposer += share_rem # If KGF or KIR address is not set, proposer gets the portion. if staking_info.KGFAddr is None: proposer += kgf kgf = 0 if staking_info.KIRAddr is None: proposer += kir kir = 0 spec = RewardSpec() spec.Minted = minted spec.TotalFee = total_fee spec.BurntFee = burnt_fee spec.Proposer = proposer spec.Stakers = stakers spec.Kgf = kgf spec.Kir = kir spec.Rewards = defaultdict(int) spec.Rewards[header.RewardBase] += proposer if staking_info.KGFAddr is not None: spec.Rewards[staking_info.KGFAddr] += kgf if staking_info.KIRAddr is not None: spec.Rewards[staking_info.KIRAddr] += kir for reward_addr, reward_amount in shares: spec.Rewards[reward_addr] += reward_amount return spec # Returns (total_fee, reward_fee, burnt_fee) def calc_deferred_fee(header, config): # If not DeferredTxFee, fees are already added to the proposer during TX execution. # Therefore, there are no fees to distribute here at the end of block processing. # However, the fees must be compensated to calculate actual rewards paid. if not config.DeferredTxFee: return (0, 0, 0) # Start with the total block gas fee total_fee = get_total_fee(header) reward_fee = total_fee burnt_fee = 0 # Since Magma, burn half of gas if header.number >= MAGMA_BLOCK_NUMBER: burn_amount = get_burn_amount_magma(reward_fee) reward_fee -= burn_amount burnt_fee += burn_amount # If KIP-82 is enabled, burn fees up to proposer's minted reward if header.number >= KORE_BLOCK_NUMBER: burn_amount = get_burn_amount_kip82(config, reward_fee) reward_fee -= burn_amount burnt_fee += burn_amount return (total_fee, reward_fee, burnt_fee) def get_total_fee(header): if header.number >= MAGMA_BLOCK_NUMBER: return header.GasUsed * header.BaseFee else: return header.GasUsed * config.UnitPrice def get_burn_amount_magma(fee): return fee / 2 def get_burn_amount_kip82(config, fee): cn, _, _ = split_by_ratio(config, config.MintingAmount) proposer, _ = split_by_kip82_ratio(config, cn) if fee >= proposer: return proposer else: return fee # Returns (proposer, stakers, kgf, kir, remaining) amounts # The sum of output must be equal to (minted + reward_fee). def calc_split(header, config, minted, reward_fee): total_resource = minted + reward_fee if header.number >= KORE_BLOCK_NUMBER: cn, kgf, kir = split_by_ratio(config, minted) proposer, stakers = split_by_kip82_ratio(config, cn) proposer += reward_fee remaining = total_resource - kgf - kir - proposer - stakers return (proposer, stakers, kgf, kir, remaining) else: cn, kgf, kir = split_by_ratio(config, minted + reward_fee) remaining = total_resource - kgf - kir - cn return (cn, 0, kgf, kir, remaining) # Split by `ratio`. Ignore remaining amounts. def split_by_ratio(config, source): cn = source * config.CnRatio // config.TotalRatio kgf = source * config.KgfRatio // config.TotalRatio kir = source * config.KirRatio // config.TotalRatio return (cn, kgf, kir) # Split by `kip82ratio`. Ignore remaining amounts. def split_by_kip82_ratio(config, source): proposer = source * config.CnProposerRatio // config.CnTotalRatio stakers = source * config.CnStakingRatio // config.CnTotalRatio return (proposer, stakers) # Distribute stake_reward among staked CNs # Returns a mapping from each reward address to their reward shares, # and the remaining amount. def calc_shares(config, staking_info, stake_reward): min_stake = config.MinimumStake total_stakes = 0 for node in staking_info.Nodes: if node.StakingAmount > min_stake: total_stakes += (node.StakingAmount - min_stake) shares = {} remaining = stake_reward for node in staking_info.Nodes: if node.StakingAmount > min_stake: effective_stake = node.StakingAmount - min_stake reward_amount = stake_reward * effective_stake // total_stakes remaining -= reward_amount shares[node.RewardAddr] = reward_amount return (shares, remaining) ``` The updated algorithm increases the balance of every GC member's reward account at every block. The performance impact should be reasonable since the number of GC members is significantly smaller than Klaytn's transaction processing capability. ### Reward JSON-RPC API A new JSON-RPC method should be added to provide historic reward distribution details. - Name: `klay_getRewards` - Description: Returns allocation details of reward distribution at the specified block. If the parameter is not set, returns a breakdown of reward distribution at the latest block. - Parameters 1. `QUANTITY | TAG` - (optional) integer or hexadecimal block number, or the string "earlist" or "latest". - Returns - `DATA` - `minted`: The amount minted - `totalFee`: Total tx fee spent - `burntFee`: The amount burnt - `proposer`: The amount for the block proposer - `stakers`: Total amount for stakers - `kgf`: The amount for KGF - `kir`: The amount for KIR - `rewards`: A mapping from reward recipient addresses to reward amounts - Example ``` // Request curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"klay_getRewards", "params":["0x64fe7e0"],"id":1}' https://api.baobab.klaytn.net:8651 // Response { "jsonrpc":"2.0", "id":1, "result":{ "minted": "6400000000000000000", "totalFee": "1075975000000000", "burntFee": "537987500000000", "proposer": "3200268993750000000", "stakers": "0", "kgf": "2560215195000000000", "kir": "640053798750000000" "rewards": { "0xa86fd667c6a340c53cc5d796ba84dbe1f29cb2f7": "3200268993750000000", "0x2bcf9d3e4a846015e7e3152a614c684de16f37c6": "2560215195000000000", "0x716f89d9bc333286c79db4ebb05516897c8d208a": "640053798750000000" } } } ``` ## Expected Effect The proposed GC reward mechanism is expected to produce the following changes: - GC members increase individual staking amount. - KLAY holders receive profit based on the staking amount of KLAY. - Total Value Locked (TVL) of Klaytn increases. - The total circulation reduces. ## Backward Compatibility Klaytn nodes must be upgraded before `KORE_BLOCK_NUMBER` to correctly produce or verify blocks. ## Reference n/a ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

NFT Avatar in Multi-Metaverse

Tue, 01 Nov 2022 00:00:00 +0000

Signed Data Standard

Tue, 10 Jan 2023 00:00:00 +0000

## Simple Summary This is to standardize message signing methods different from those of Ethereum. ## Abstract This standard proposes a specification about how to handle signed data in Klaytn. ## Motivation Several multisignature wallet implementations have been created which accepts `presigned` transactions. A `presigned` transaction is a chunk of binary `signed_data`, along with signature (`r`, `s` and `v`). The interpretation of the `signed_data` has not been specified in Klaytn and Ethereum solved this by [EIP-191](https://eips.ethereum.org/EIPS/eip-191) standard. Additionally, the signatures are different when using Metamask and Kaikas because they have the different preamble. ## Specification This document is heavily derived from [EIP-191](https://eips.ethereum.org/EIPS/eip-191) written by Martin Holst Swende and Nick Johnson. We propose the following format for `signed_data`: ``` 0x19 <1 byte version> ``` The initial `0x19` byte is intended to ensure that the `signed_data` is not valid RLP. > For a single byte whose value is in the [0x00, 0x7f] range, that byte is its own RLP encoding. That means that any `signed_data` cannot be one RLP-structure, but a 1-byte `RLP` payload followed by something else. Thus, any `signed_data` can never be an Klaytn transaction. The following format is prepended before hashing in personal_sign: ``` "\x19Klaytn Signed Message:\n" + len(message) ``` Using `0x19` thus makes it possible to extend the scheme by defining a version `0x4b` (`K`) to handle these kinds of signatures. ### Registry of version bytes | Version byte | KIP | Description | ------------ | -------------- | ----------- | `0x4b` | [97][kip-97] | `personal_sign` messages #### Version `0x4b` (K) ``` 0x19 <0x4b (K)> ``` The version `0x4b` (K) has `` for the version-specific data. The data to sign can be any arbitrary data. > NB: The `K` in `Klaytn Signed Message` refers to the version byte 0x4b. The character `K` is `0x4b` in hexadecimal which makes the remainder, `laytn Signed Message:\n + len(message)`, the version-specific data. [kip-97]: /KIPs/kip-97 ### Specification of the caver.js API ```JavaScript caver.klay.accounts.sign('Some data', '0x{private key}'); ``` ### Returns ```shell { message: 'Some data', messageHash: '0x8ed2036502ed7f485b81feaec1c581d236a8b711e55a24077724879c8a263c2a', v: '0x1b', r: '0x4a57bcff1637346a4323a67acd7a478514d9f00576f42942d50a5ca0e4b0342b', s: '0x5914e19a8ebc10ce1450b00a3b9c1bf0ce01909bca3ffdead1aa3a791a97b5ac', signature: '0x4a57bcff1637346a4323a67acd7a478514d9f00576f42942d50a5ca0e4b0342b5914e19a8ebc10ce1450b00a3b9c1bf0ce01909bca3ffdead1aa3a791a97b5ac1b' } ``` ## Backwards Compatibility - [caver-js](https://docs.klaytn.foundation/content/dapp/sdk/caver-js/v1.4.1/api-references/caver.klay.accounts#sign) already sign in this format. - [caver-java](https://javadoc.io/doc/com.klaytn.caver/core/1.10.0/com/klaytn/caver/wallet/keyring/PrivateKey.html) already sign in this format. ## Reference [EIP-191](https://eips.ethereum.org/EIPS/eip-191) ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Treasury Fund Rebalancing

Fri, 24 Feb 2023 00:00:00 +0000

BLS public key registry

Mon, 22 May 2023 00:00:00 +0000

Supplant DIFFICULTY opcode with RANDOM

Wed, 31 May 2023 00:00:00 +0000

## Simple Summary Introduce on-chain randomness and expose it in the EVM by supplanting DIFFICULTY opcode semantics ## Abstract This standard outlines an approach for generating an on-chain random value based on digital signature. Specifically, it introduces new fields, namely `randomReveal` and `mixHash`, in the block header; `randomReveal` is a verifiable random number, and `mixHash` is a derivation from a mixture of `randomReveals` and additional information. They serve as an unpredictable, verifiable, and dependable source of on-chain randomness. In addition, these fields can be fetched from the EVM via `RANDOM (0x44)` opcode. ## Motivation An unpredictable, verifiable, and dependable on-chain randomness can be utilized in various use-cases including the protocol and applications. - Unpredictability indicates that the random should be as difficult to predict as possible. - Verifiability ensures that the random is authentic and cannot be manipulated or forged. - Dependability implies that the random is generated without trusting any external sources of randomness, such as oracles. An example of such use-cases is the block proposer selection. An exemplary requirement can be that the next block's proposer remains undisclosed until the latest block has been finalized, or that the proposer cannot tamper with deciding the next block's proposer. In this proposal, new header fields `randomReveal` and `mixHash` are introduced. `randomReveal` is the signature of the proposer, and `randomReveal`s are mixed to compute `mixHash`, which users can use for a part of the random source. `mixHash` is unpredictable, verifiable, and dependable: - (Unpredictability) the signature is random and so is `mixHash`. - (Verifiability) the signature can be verified with the public key of the proposer, and `mixHash` is computed in a deterministic manner. - (Dependability) `mixHash` only relies on the validators. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The terms hash_to_point (hereinafter referred to as hash), public key, proof-of-possession (hereinafter referred to as pop) are from the ciphersuite [BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP\_](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#section-4.2.3). ### Parameters | Constant | Value | | ------------ | ----- | | `FORK_BLOCK` | TBD | ### Block Structure Beginning with `FORK_BLOCK`, client software must set the fields in a block header: - `randomReveal`: 96 bytes. It must be specified in the 15th field (0-indexed) of a block header. - `mixHash`: 32 bytes. It must be specified in the 16th field (0-indexed) of a block header. ### Block Processing #### Block Proposal Beginning with `FORK_BLOCK`, the proposer must fill the new fields in the block proposal: - `randomReveal`: The proposer must sign the hash of the proposing block number. - `mixHash`: The proposer must XOR the keccak256 hash of `randomReveal` and the previous block's `mixHash`. If the previous block's `mixHash` is null (e.g., previous block is before `FORK_BLOCK`), then use 32 bytes of zero instead. ```python class Header: parentHash: hash rewardbase: address root: hash txHash: hash receiptHash: hash bloom: bloom blockScore: int number: int gasUsed: uint64 time: int timeFoS: uint8 extra: bytes governance: bytes vote: bytes baseFee: int randomReveal: bytes # new mixHash: bytes # new header.randomReveal = sign(privateKey, header.number) header.mixHash = xor(prevHeader.mixHash, keccak256(randomReveal)) ``` #### Validation Beginning with `FORK_BLOCK`, validators must validate the new fields: - `randomReveal` - The validators must fetch the public key and the pop of the proposer by `getInfo(cnNodeId)` of the BLS registry standardized by [KIP-113](https://github.com/klaytn/kips/blob/main/KIPs/kip-113.md#validation). - The validators must verify the validity of the proposer public key using pop as mentioned in [here](https://github.com/klaytn/kips/blob/main/KIPs/kip-113.md#validation). - The validators must verify if `randomReveal` is signed by the proposer public key. - `mixHash`: The validators must verify the validity of the proposed `mixHash` by calculating `mixHash` using the aforementioned `mixHash` algorithm. ### Pseudocode See the following pseudocode that describes the block processing in python: ```python DEFAULT_MIXHASH = b"\x00" * 32 def fill_kip114_header(newHeader, prevHeader, privateKey): newHeader.randomReveal = calc_random_reveal(privateKey, newHeader.number) if newHeader.number == FORK_BLOCK: prevMixHash = DEFAULT_MIXHASH else: prevMixHash = prevHeader.mixHash newHeader.mixHash = calc_mix_hash(prevMixHash, newHeader.randomReveal) def calc_random_reveal(privateKey, headerNumber): return sign(privateKey, headerNumber) def calc_mix_hash(prevMixHash, randomReveal): return xor(prevMixHash, keccak256(randomReveal)) def verify_kip114_header(newHeader, prevHeader): # Getting PoP information from the smart contract registry defined in KIP-113. [proposerPubkey, proposerPop] = get_proposer_pubkey_pop() # pop verify if not pop_verify(proposerPubkey, proposerPop): return False # signature verify if not verify(proposerPubkey, newHeader.number, newHeader.randomReveal): return False # mixHash verify if newHeader.number == FORK_BLOCK: prevMixHash = DEFAULT_MIXHASH else: prevMixHash = prevHeader.mixHash return newHeader.mixHash == calc_mix_hash(prevMixHash, newHeader.randomReveal): ``` ### EVM Beginning with `FORK_BLOCK`, the `RANDOM (0x44)` instruction must return the value of `mixHash` of the current block it is executing in. Note: The gas cost of the `RANDOM (0x44)` opcode remains unchanged. ### Genesis Block If `FORK_BLOCK` is zero, the genesis block must have `randomReveal` and `mixHash` fields. ## Rationale ### Names of the header fields The naming is highly inspired by [EIP-4339](https://eips.ethereum.org/EIPS/eip-4399). We use `randomReveal` instead of RANDAO reveal because the randoms are generated in a different manner. ### Block size increment due to new fields in the header The size increment cost of RLP-encoded header is around 131 bytes per block, which is approximately 3.8GB per year. It is a negligible cost compared to its benefit. ### BLS-based random over EC-based random We chose BLS-based verifiable random over EC-based because: - A BLS library written in Golang is easy to find as in [link](https://github.com/klaytn/klaytn/issues/1823), whereas it is not the case for EC-based as in [link](https://www.ietf.org/archive/id/draft-irtf-cfrg-vrf-15.html#section-6). - There is a potential consensus change based on BLS signature. Therefore, this proposal gently introduces BLS signature to the Klaytn protocol as well as adding on-chain randomness. ## Backwards Compatibility Blocks before `FORK_BLOCK` will remain the same. ## Security Considerations ### Biasability BLS signature as well as the signing message (i.e., proposing block number) is deterministic. Thus, the proposer has no influence over the computation of `mixHash`. In addition, the biasability of `mixHash` mainly depends on that of the hash of `randomReveal`. To the best of our knowledge, keccak256 is not a biased hash function. Therefore, `mixHash`, which is the XOR of the output of keccak256 and the previous `mixHash`, is unbiased. ### Predictability A list of inputs influencing future randomness consists of but is not limited to the following items: - **Number of colluding validators.** When colluding validators become proposers of consecutive blocks, they collectively share their `randomReveal`s in advance to predict the value of `mixHash`. - **Proposer selection policy.** This contributes to how likely the colluding validators become proposers of consecutive blocks. Define `f(x, N, C)`: - `N`: the number of validators - `C`: the number of colluding validators (N > C) - `x`: the number of blocks from the latest block - `f`: the probability of predicting the value of `mixHash` `x` blocks in advance. In other words, the probability of colluding validators becoming proposers for `x` consecutive blocks. Under random proposer selection policy, the proposer is randomly selected after each block, thus `f(x, N, C) = (C/N)^x`. ### Tips for application developers The following tips attempt to reduce predictability and biasability of randomness outputs returned by `RANDOM (0x44)`: - Make your applications rely on the future randomness with a reasonably high lookahead. Given that IBFT permits one third of the validators to be malicious, developers are advised to give a distance of 200 blocks between bidding and rolling the dice to be "95 nines" safe. ## Implementation A simulation in Python: ```python from blspy import PrivateKey, G1Element, G2Element, PopSchemeMPL # blspy from Crypto.Hash import keccak # pycryptodome FORK_BLOCK = 100 # TBD DEFAULT_MIXHASH = b"\x00" * 32 validatorNum: int = 3 proposerBLSPrivKeys: list[PrivateKey] = [ PrivateKey.from_bytes((i + 1).to_bytes(32, byteorder="big")) for i in range(validatorNum) ] # b"\x00..\x01", b"\x00..\x02", ... proposerBLSPublicKeys: list[G1Element] = [i.get_g1() for i in proposerBLSPrivKeys] proposerAddrs: list[str] = [ str(i + 1).zfill(40) for i in range(validatorNum) ] # "0x00..1, 0x00..2, ..." # Block header. Only relevant fields are shown here. class Header: number: int = 0 # Block number randomReveal: bytes mixHash: bytes proposer: str def __init__(self, number: int, randomReveal: bytes = b"", mixHash: bytes = b""): self.number = number self.randomReveal = randomReveal self.mixHash = mixHash self.proposer = proposerAddrs[number % validatorNum] def __repr__(self): return "number: {}\n\nrandomReveal ({} bytes): {}\n\nmixHash ({} bytes): {}".format( self.number, len(self.randomReveal), self.randomReveal, len(self.mixHash), self.mixHash, ) class BlsPublicKeyInfo: publicKey: bytes pop: bytes def __init__(self, publicKey, pop): self.publicKey = publicKey self.pop = pop # A BLSRegistry that supports the interface IKIP-113 (https://github.com/klaytn/kips/blob/main/KIPs/kip-113.md) class BLSRegistry: mapping = {} def __init__(self): for i, proposerAddr in enumerate(proposerAddrs): pop = bytes(PopSchemeMPL.pop_prove(proposerBLSPrivKeys[i])) self.mapping[proposerAddr] = BlsPublicKeyInfo( bytes(proposerBLSPublicKeys[i]), pop ) def getInfo(self, addr: str) -> BlsPublicKeyInfo: return self.mapping[addr] def is_kip114_fork_enabled(num) -> bool: return FORK_BLOCK <= num # dummy function for fetching the proposer secret key # in implementation, this should be fetched from a file def get_proposer_private_key(num) -> PrivateKey: proposerIdx = num % validatorNum return proposerBLSPrivKeys[proposerIdx] def fill_kip114_header(newHeader, prevHeader, privateKey): newHeader.randomReveal = calc_random_reveal(privateKey, newHeader.number) if newHeader.number == FORK_BLOCK: prevMixHash = DEFAULT_MIXHASH else: prevMixHash = prevHeader.mixHash newHeader.mixHash = calc_mix_hash(prevMixHash, newHeader.randomReveal) def calc_random_reveal(sk, num) -> bytes: msg = block_num_to_bytes(num) return bytes(PopSchemeMPL.sign(sk, msg)) def calc_mix_hash(prevMixHash, randomReveal) -> bytes: return xor(prevMixHash, keccak256(randomReveal)) def gen_next_header(prevHeader) -> Header: nextBlockNum = prevHeader.number + 1 newHeader = Header(nextBlockNum) if is_kip114_fork_enabled(nextBlockNum): privateKey = get_proposer_private_key(nextBlockNum) fill_kip114_header(newHeader, prevHeader, privateKey) return newHeader def keccak256(msg) -> bytes: keccak256 = keccak.new(digest_bits=256) keccak256.update(msg) return keccak256.digest() def block_num_to_bytes(num) -> bytes: return num.to_bytes(32, byteorder="big") def xor(a: bytes, b: bytes) -> bytes: return bytes(x ^ y for x, y in zip(a, b)) def verify_kip114_header(header, prevHeader) -> bool: if not is_kip114_fork_enabled(header.number): return True # pop verify blsPublicKeyInfo = BLSRegistry().getInfo(header.proposer) publicKey = G1Element.from_bytes(blsPublicKeyInfo.publicKey) pop = G2Element.from_bytes(blsPublicKeyInfo.pop) if not PopSchemeMPL.pop_verify(publicKey, pop): return False # signature verify msg = block_num_to_bytes(header.number) sig = G2Element.from_bytes(header.randomReveal) if not PopSchemeMPL.verify(publicKey, msg, sig): return False # mixHash verify if header.number == FORK_BLOCK: # prevHeader mixHash does not exist, so fill with default prevMixHash = DEFAULT_MIXHASH else: prevMixHash = prevHeader.mixHash return header.mixHash == calc_mix_hash(prevMixHash, header.randomReveal) def main(): header = Header(FORK_BLOCK - 2) prevHeader = header N = 10 # print header numbers in [FORK_BLOCK - 1, FORK_BLOCK + N] for _ in range(N + 2): header = gen_next_header(header) print(header) verified = verify_kip114_header(header, prevHeader) assert verified print("verified:", verified) print("=" * 80) prevHeader = header main() ``` ## Test Cases ``` Proposer secret key: 0x6c605527c8e4f31c959478801d51384d690a22dfc6438604646f7709032c893a Previous MixHash: 0x8019df1a2a9f833dc7f400a15b33e54a5c80295165c5953dc23891aab9203810 Block number: 31337 Expected Msg: 0x0000000000000000000000000000000000000000000000000000000000007a69 Expected RandomReveal: 0xadfe25ced45819332cbf088f01cdd2807686dd6309b11d7440237dd623624f401d4753747f5fb92374235e997edcd18318bae2806a1675b1e685e792abd1fbdf5c50ec1e148cc7fe861984d8bc3204c1b2136725b Expected MixHash: 0x8772d58248bdf34e81ecbf36f28299cfa758b61ccf3f64e1dc0646687a55892f ``` Testing the Python simulation above: ``` sk = PrivateKey.from_bytes(unhexlify("6c605527c8e4f31c959478801d51384d690a22dfc6438604646f7709032c893a")) prevMix = unhexlify("8019df1a2a9f833dc7f400a15b33e54a5c80295165c5953dc23891aab9203810") num = 31337 msg = block_num_to_bytes(num) reveal = calc_random_reveal(sk, num) mix = calc_mix_hash(prevMix, reveal) assert hexlify(msg) == b"0000000000000000000000000000000000000000000000000000000000007a69" assert hexlify(reveal) == b"adfe25ced45819332cbf088f01cdd2807686dd6309b11d7440237dd623624f401d4753747f5fb92374235e997edcd18318bae2806a1675b1e685e792abd1fbdf5c50ec1e148cc7fe861984d8bc3204c1b2136725b assert hexlify(mix) == b"8772d58248bdf34e81ecbf36f28299cfa758b61ccf3f64e1dc0646687a55892f" ``` ## References - [consensus-specs/beacon-chain.md at dev · ethereum/consensus-specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#randao) - [EIP-4399: Supplant DIFFICULTY opcode with PREVRANDAO](https://eips.ethereum.org/EIPS/eip-4399) ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Unpredictable Proposer Selection

Thu, 15 Jun 2023 00:00:00 +0000

Unified System Contract Management Process

Wed, 20 Sep 2023 00:00:00 +0000

## Simple Summary A unified deployment and management process for system contracts. ## Abstract This standard defines a unified deployment and management process for system contracts. To effectively manage system contracts, it also introduces a Registry contract that manages all system contracts. ## Motivation Currently, Klaytn has multiple [system contracts](#definitions), but they are deployed and managed without any defined standards. For example, the `AddressBook` contract was deployed by a bytecode injection at the genesis block with a reserved address. In contrast, an EOA deployed `TreasuryRebalance`, and its address is set in the chain config. As more system contracts will be deployed in the future, it’s essential to have a standard way to deploy and manage system contracts. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. If a system contract implements a proxy pattern for upgradeability, it must follow the separation of data and logic contracts as defined in this standard. This method, often called the proxy pattern, allows the change of the logic contract while keeping the data, which can greatly reduce the cost of contract updates. Upgrading a logic contract will not affect the Registry since the Registry only holds the address of the proxy(data) contract. Delegating ownership of a proxy contract to a governance contract can solve the centralized and potential private key loss issues. For system contracts that implement the proxy pattern, they must be developed and validated based on the [`UUPS`](https://eips.ethereum.org/EIPS/eip-1822) proxy pattern rather than the `Transparent` pattern. ### Definitions - System contract: A contract that is read by the Klaytn core protocol or directly affect the protocol. The currently deployed system contracts are as follows: [**AddressBook**](https://github.com/klaytn/klaytn/blob/dev/contracts/contracts/system_contracts/consensus/AddressBook.sol), [**GovParam**](https://github.com/klaytn/klaytn/blob/dev/contracts/contracts/system_contracts/gov/GovParam.sol), **Voting**([KIP-81](https://github.com/klaytn/kips/blob/main/KIPs/kip-81.md)), **TreasuryRebalance**([KIP-103](https://github.com/klaytn/kips/blob/main/KIPs/kip-103.md)) - System contract upgrade: The process of updating an existing logic contract while maintaining a proxy contract. The upgraded logic contract must be compatible with the previous interface and its storage layout. - System contract replacement: The deployment of a new system contract that is then registered to the Registry using the same name as its predecessor. The new contract effectively deprecates the previous system contract. ### Smart Contracts Overview The proposed smart contract will be implemented in Solidity and compatible with the Ethereum Virtual Machine (EVM). The smart contract will have the following features: 1. Registry - Register a new system contract with an activation block. - Return the state of the system contracts. 2. Proxy - Delegate a call to logic contract. - Upgrade a logic contract. #### 1. Registry The registry must have data for system contracts at a specific block. It will be done by state injection, which injects data into the Registry directly using the `state.SetState`. A reference implementation is introduced in [Implementation](#implementation). Note that it only records system contracts developed based on KIP-149. #### Interface of Registry ```solidity pragma solidity ^0.8.0; abstract contract IRegistry { /* ========== VARIABLES ========== */ /// The following variables are baked in the interface because their storage layout matters in protocol consensus /// when inject initial states (system contracts, owner) of the Registry. /// @dev Mapping of system contracts mapping(string => Record[]) public records; /// @dev Array of system contract names string[] public names; /// @dev Owner of contract address internal _owner; /* ========== TYPES ========== */ /// @dev Struct of system contracts struct Record { address addr; uint256 activation; } /* ========== EVENTS ========== */ /// @dev Emitted when the contract owner is updated by `transferOwnership`. event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); /// @dev Emitted when a new system contract is registered. event Registered(string name, address indexed addr, uint256 indexed activation); /* ========== MUTATORS ========== */ /// @dev Registers a new system contract. function register(string memory name, address addr, uint256 activation) external virtual; /// @dev Transfers ownership to newOwner. function transferOwnership(address newOwner) external virtual; /* ========== GETTERS ========== */ /// @dev Returns an address for active system contracts registered as name if exists. /// It returns a zero address when there's no active system contract with name. function getActiveAddr(string memory name) external virtual view returns (address); /// @dev Returns all system contracts registered as name. function getAllRecords(string memory name) external virtual view returns (Record[] memory); /// @dev Returns all names of registered system contracts. function getAllNames() external virtual view returns (string[] memory); /// @dev Returns owner of contract. function owner() external virtual view returns (address); } ``` #### Methods ```solidity function register(string memory name, address addr, uint256 activation) ``` Registers a new system contract. It will be activated at `activation`. It overwrites the predecessor if a predecessor system contract exists and is not yet active. Passing `addr == address(0)` is an implicit deprecation for the `name`, meaning the `name` will no longer be used. The function validates the following requirements: - The function caller MUST be an owner address. - The function MUST revert if a `name` is an empty string. - The function MUST revert if `activation < block.number`. The function emits a `Registered` event. ```solidity function getActiveAddr(string memory name) view returns (address) ``` Returns the address of the active system contract with the `name`. It returns a zero address if there’s no registered system contract with the `name` or the `name` has been deprecated by registering a zero address. #### 2. Proxy The implementation of the proxy contract will come from [OZ's UUPS implementation](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.9.3/contracts/proxy/ERC1967/ERC1967Proxy.sol), which follows [EIP-1967](https://eips.ethereum.org/EIPS/eip-1967) and [EIP-1822](https://eips.ethereum.org/EIPS/eip-1822). ### System Contracts Life Cycle The Registry contract manages system contracts based on the current block number. Its state will be managed implicitly, which means there’s no explicit state variable(e.g., enum State). It has three implicit states and cannot be reversed to the previous state: - Registered: It has been registered but has not been activated yet. - Active: The registered address isn't a zero address and current block number exceeds its activation. Also, no active successor system contract exists. - Deprecated: It's registered with a zero address or there’s an active successor system contract. ![](/assets/kip-149/LifeCycle.png) #### Upgrade System Contracts When upgrading a system contract, its logic contract will be changed by governance proposal. The Registry will not be updated since it only manages the address of the proxy contract. ![](/assets/kip-149/UpgradeProcess.png) #### Replace System Contracts If current system contract updates can’t be done by upgrading the logic contract (e.g., not compatible storage layout or immutable contract), it must be replaced with the newly deployed system contract. The predecessor doesn’t need to be explicitly deprecated since a new system contract will implicitly replace and deprecate it. The replacement process is the same as the initial registration for the system contract except for having a predecessor. ![](/assets/kip-149/ReplacementProcess.png) ### Core Logic Overview After a target block number, a Klaytn node should read all the active addresses of system contracts through the Registry. A Klaytn node deploys the Registry at the configured block number at the reserved address by bytecode injection. Note that the Registry will be replaced by bytecode injection if necessary since it's deployed by bytecode injection. #### Chain Configuration In the Chain Config, the following fields are newly introduced. All node operators in a network must update `genesis.json` configuration with the same value. The configuration values for Baobab and Cypress networks are hard-coded on the client source code. - `RegistryAddress`: the reserved address for the Registry contract, which is `0x0000000000000000000000000000000000000401`. - `Kip149CompatibleBlock`: the target block number that the Registry will be deployed. - `RegistryInit`: the initial data config for the Registry. Tye type of this field is defined as `RegistryConfig` as shown below. It is used when injecting the initial state after deploying the Registry contract. ```go // In klaytn/params/config.go type RegistryConfig struct { Records map[string]common.Address // Map for system contracts Owner common.Address // Address for initial owner of Registry } var ChainConfig = &ChainConfig{ ... Kip149CompatibleBlock: TBD, // RegistryInit will be used when injecting initial state for the Registry // Note that the registry only records the system contracts based on the KIP-149, which is currently only KIP-113 // The activation block deployed by state injection will be 0 RegistryInit: &RegistryConfig{ Records: map[string]common.Address{ "KIP113": Kip113Address, }, Owner: OwnerAddress, }, } ``` #### Execution The Registry deployment is executed at the `engine.Finalize` function, which means the end of the block generation. It reads the reserved address and runtime bytecode and deploys the Registry by the bytecode injection. Also, it injects the initial state provided by `RegistryConfig` for the Registry here. When `kip149CompatibleBlock == 0`, the Registry will be allocated at the genesis block. ```go if chain.Config().IsKIP149ForkBlock(header.Number) { // Inject the bytecode and states for the Registry err := registry.InstallRegistry(state, chain.Config().RegistryInit) if err != nil { logger.Error("failed to set the registry contract code", "err", err) } else { logger.Info("successfully set the registry contract code", "block", header.Number.Uint64()) } } ``` #### Resolver A Klaytn node will have a resolver to read the active addresses of system contracts from the Registry. But the system contracts deployed by state injection (e.g., `KIP113`) will be directly read from `chain.Config().RegistryInit` at the `Kip149CompatibleBlock` since the Registry will be deployed in the `engine.Finalize` function, which is the last part of the block generation. In other words, the resolver will be used starting in the `Kip149CompatibleBlock + 1`. ```go // Note that it will be activated in the next of KIP-149 fork block func ReadActiveAddressFromRegistry(backend bind.ContractCaller, name string, num *big.Int) (common.Address, error) { code, err := backend.CodeAt(context.Background(), RegistryAddr, num) if err != nil { return common.Address{}, err } if code == nil { return common.Address{}, ErrRegistryNotInstalled } caller, err := contracts.NewRegistryCaller(RegistryAddr, backend) if err != nil { return common.Address{}, err } opts := &bind.CallOpts{BlockNumber: num} return caller.GetActiveAddr(opts, name) } ``` #### JSON-RPC APIs The following JSON-RPC methods for the Klaytn node should be added to provide the records of registered system contracts. 1. `klay_getActiveAddressFromRegistry` - Parameters: - `name`: the name of the system contract in string. - `number`: (optional) integer or hexadecimal block number, or the string "pending" or "latest". - Description: Returns the active address of the system contract registered as `name` if exists. - Return: The address of the active system contract. - Example ```json // Request curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"klay_getActiveAddressFromRegistry", "params":["KIP113", "latest"],"id":1}' http://localhost:8551 // Response { "jsonrpc":"2.0", "id":1, "result": "0x0000000000000000000000000000000000000402" } // Request - no active system contract curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"klay_getActiveAddressFromRegistry", "params":["KIP114", "latest"],"id":1}' http://localhost:8551 // Response { "jsonrpc":"2.0", "id":1, "error":{ "code":-32000, "message":"no active address for KIP114" } } ``` 2. `klay_getAllRecordsFromRegistry` - Parameters: - `name`: the name of the system contract in string. - `number`: (optional) integer or hexadecimal block number, or the string "pending" or "latest". - Description: Returns all records of the system contract registered as `name` if it has been registered. - Returns: - `Record[]`: An array of the records of the system contract. - `Record`: A struct of the record with the following fields. - `addr`: The address of the system contract. - `activation`: The block number when the system contract is activated. - Example ``` // Request curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"klay_getAllRecordsFromRegistry", "params":["KIP113", "latest"],"id":1}' http://localhost:8551 // Response { "jsonrpc":"2.0", "id":1, "result":[ { "addr":"0x0000000000000000000000000000000000000402", "activation":0 } ] } // request - no records curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"klay_getAllRecordsFromRegistry", "params":["KIP114", "latest"],"id":1}' http://localhost:8551 // Response { "jsonrpc":"2.0", "id":1, "error":{ "code":-32000, "message":"KIP114 has not been registered" } } ``` ## Rationale ### Bytecode Injection for Registry Deployment In the future, all system contracts will be registered in the Registry, and a Klaytn node will read the active addresses of system contracts from the Registry. Not only for a Klaytn node but also for other ecosystem participants who will use the registry to read the system contracts they need, meaning the registry should be registered at an easily accessible reserved address. ### Delegating Ownership of Registry and System Contracts to Governance The Registry holds all system contracts for Klaytn, affecting the protocol directly. This means its registration and deprecation process must be very careful and not centralized. The same goes for the system contract. As mentioned in [specification](#specification), making the EOA the owner of system contracts can cause centralization and potential private key loss issues. By delegating ownership of the Registry and system contracts to Governance, all registry and system contract changes will only be applied after full discussion and consensus of the GCs and Validators. Validators have the right to accept or reject the proposal depending on whether or not the hard fork proceeds. ### State Injection for System Contracts The Registry must hold data for system contracts at a specific block. To handle this, there are three main approaches: 1. Send multiple register transactions after deploying the Registry. 2. Use a fallback logic in the getter to return the state of system contracts. 3. Use state injection, which injects state for system contracts by the `state.SetState`. The first approach seems straightforward. However, the Registry will be set in the `engine.Finalize`, which is the last part of the block generation. It means the transaction cannot be processed in the same block and must be entered in the first order of the next block. This requires additional implementation and can't be applied when `KIP149CompatibleBlock == 0`. In the second approach, the Registry contract should have different codes by the network, requiring direct code modification in the getter(e.g., add/remove hard-coded system contracts and modify if-else statements). It can cause potential security vulnerabilities and increase costs for getter calls permanently. On the other hand, the last approach is much safer because it's more structured and doesn't require modifying any code. It can also set the necessary configuration without working with the additional contract's constructor. Note that the state injection for system contracts will follow the [solidity layout rule](https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html). ### Separate Data and Logic Contract This proxy pattern simplifies the process of system contract update because the existing data can be used even if the logic contract is changed. The main issue of the proxy pattern is the centralization and potential private key loss. But delegating ownership to upgrade a logic contract to Governance can solve those problems. Choosing `UUPS` as the proxy pattern is because it's lighter and more secure than `Transparent` proxy pattern. For example, `Transparent` requires additional logic to prevent `proxy selector clashing`. However, with `UUPS`, the proxy functionality is managed in a logic contract, eliminating the need for additional work. For more details, please refer to [OZ's article](https://docs.openzeppelin.com/contracts/4.x/api/proxy#transparent-vs-uups) ## Backward Compatibility ### Deployed System Contracts The existing system contracts will not be registered in the Registry, since they are not developed based on KIP-149. They will be used in a Klaytn node same way as before. ## Implementation - A reference implementation for the Registry contract: [Implementation](https://github.com/klaytn/klaytn/blob/dev/contracts/contracts/system_contracts/kip149/Registry.sol) - A reference implementation for core logic: [Implementation](https://github.com/klaytn/klaytn/blob/dev/blockchain/system/registry.go) ## References - Binance Smart Chain: https://github.com/bnb-chain/bsc/tree/master/core/systemcontracts - Celo: https://docs.celo.org/community/release-process/smart-contracts ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

An Update of Treasury Fund Rebalancing

Mon, 22 Apr 2024 00:00:00 +0000

## Simple Summary An update of treasury fund rebalancing. ## Abstract The treasury fund rebalancing is updated, resulting in updates to the treasury rebalance contract v2 and the related core logic. ## Motivation According to KIP-103, the treasury rebalancing refers to the act of burning existing fund balances and minting new funds. This event happens at a reserved time, such as a hard fork block number. Through the TreasuryRebalance contract, the disclosure of the treasury fund activities can be conducted transparently and verifiably. However, there are a few shortcomings of KIP-103; (1) it only permits the decrease in the total balance of the funds, (2) its rebalance blocknumber or memo is immutable. Once these values are set, they cannot be changed, even if they are incorrectly set. To address those above, this proposal made some improvements. First of all, this proposal expands to the general cases so that we don't have to consider whether the final result is burn or mint. The other improvement is about making rebalanceBlocknumber in the RebalanceContract editable. The rebalanceBlocknumber should be matched with the related hardfork block number. ## Specification Before proceeding, this proposal will first organize and clarify the terminology. Here, the previous/new fund addresses are referred to as `Zeroed`, `Allocated` unlike in KIP-103. `Retired`, `Newbie` were ambiguous and did not clearly indicate that the previous fund balance is zeroed and the new fund balance is allocated, which degraded the readability. ### To consider both total burn/total mint cases In KIP-103, rebalancing is limited to cases where the total balance decreases. This proposal aims to generalize the process by removing the requirement that the total balance of `Zeroeds` should exceed the total minting amount of `Allocateds`. Consequently, the checking code is eliminated from the contract and core code. In the `TreasuryRebalanceV2` contract, the `finalizeApproval` method has been revised as follows. Initially, this `require` statement, `require(getTreasuryAmount() < sumOfZeroedBalance())`, was present. However, it has been removed to accommodate all cases. ```solidity /** * @dev finalizeApproval sets the status to Approved, * After this stage, approvals will be restricted. */ function finalizeApproval() public onlyOwner onlyAtStatus(Status.Registered) { checkZeroedsApproved(); status = Status.Approved; emit StatusChanged(status); } ``` The next validation has also been removed from the core logic. It previously ensured that the total balance of `Zeroeds` was greater than the total balance of `Allocateds`. However, it has been removed to support all cases. * totalZeroedAmount >= totalAllocatedAmount ### To enable editing of RebalanceBlocknumber defined in treasury rebalance contract Within the treasury rebalance contract, there exists a storage value named `RebalanceBlocknumber`, which ideally should correspond to the associated hard fork block number. Despite being able to update the hard fork block number, the `RebalanceBlocknumber` field was immutable. To align the behavior of this field with that of the hard fork block number, this proposal advocates for making the `RebalanceBlocknumber` field editable. The next method is added to the TreasuryRebalanceV2 contract. ```solidity /** * @dev updates rebalance block number * @param _rebalanceBlockNumber is the updated target block number of the execution the rebalance in Core */ function updateRebalanceBlocknumber( uint256 _rebalanceBlockNumber ) public onlyOwner { require(block.number < rebalanceBlockNumber, "current block shouldn't be past the currently set block number"); require(block.number < _rebalanceBlockNumber, "rebalance blockNumber should be greater than current block"); rebalanceBlockNumber = _rebalanceBlockNumber; } ``` ### To enable editing of Memo defined in treasury rebalance contract The execution result of treasury fund rebalancing V2 is printed as an INFO-level log on each node. This log is added as a memo to the contract, making it permanently viewable. However, once finalized, any modifications to the memo value were restricted even if set incorrectly. This proposal aims to seperate the memo setting process from the contract finalization, allowing the memo value to be set repeatedly. The `setPendingMemo` is added and `finalizeContract` of the TreasuryRebalanceV2 contract is revised as follows. ```solidity string public pendingMemo; // temporary storage for memo string public memo; // result of the treasury fund rebalance /** * @dev sets the pendingMemo of the Contract. Once finalized, the memo cannot be modified. * @param _memo is the result of the rebalance after executing successfully in the core. */ function setPendingMemo(string memory _memo) external onlyOwner onlyAtStatus(Status.Approved) { pendingMemo = _memo; } /** * @dev sets the status of the contract to Finalize. Once finalized the storage data * of the contract cannot be modified. Also it sets the memo with pendingMemo value. * It will be used for public disclosure. * Can only be called by the current owner at Approved state after the execution of rebalance in the core */ function finalizeContract() external onlyOwner onlyAtStatus(Status.Approved) { require(block.number > rebalanceBlockNumber, "Contract can only finalize after executing rebalancing"); require(bytes(pendingMemo).length > 0, "no pending memo, cannot finalize without memo"); memo = pendingMemo; status = Status.Finalized; emit Finalized(memo, status); } ``` ### Result In the Kip-103 memo format, the `zeroed` item showed the balance of the zereods before rebalancing, while the `allocated` item showed the balance of the allocateds after rebalancing. It was insufficient for interpreting the rebalancing results. Therefore, this proposal changes the format to display balances both before and after rebalancing. The newly proposed memo format is shown below with balance/amount in kei (peb of Klaytn). **Format** ``` { "before": { "zeroed": { "0xZeroedAddress1": [balance of zeroedAddress1 before rebalance], "0xZeroedAddress2": [balance of zeroedAddress2 before rebalance], ...}, "allocated": { "0xAllocatedAddress1": [balance of AllocatedAddress1 before rebalance], "0xAllocatedAddress2": [balance of AllocatedAddress1 before rebalance], ...} }, "after": { zeroed": { "0xZeroedAddress1": [balance of zeroedAddress1 after rebalance], "0xZeroedAddress2": [balance of zeroedAddress2 after rebalance], ...}, "allocated": { "0xAllocatedAddress1": [balance of AllocatedAddress1 after rebalance], "0xAllocatedAddress2": [balance of AllocatedAddress1 after rebalance], ...} }, "burnt": [burnt amount], "success": [true/false] } ``` ## Rationale While executing the core logic of the KIP-103 treasury rebalance, the unintended increase in the nonce of the '0x0' address occured. In KIP-160, this issue can be resolved by replacing the usage of `kip103ContractBackend` with `BlockchainContractBackend`. For your reference, `ContractBackend` facilitates the interaction between the core and contracts. The following pseudocode illustrates how to define a contract callers for each rebalancing. ```golang RebalanceTreasury() { if current block number is equal to KIP-160 hard fork block number { // Define the caller for the NewTreasuryRebalanceV2 contract caller, err = rebalance.NewTreasuryRebalanceV2Caller(chain.Config().Kip160ContractAddress, backends.NewBlockchainContractBackend(chain, nil, nil)) } if current block number is equal to KIP-103 hard fork block number { // Define the caller for the NewTreasuryRebalance contract caller, err = rebalance.NewTreasuryRebalanceCaller(chain.Config().Kip103ContractAddress, &Kip103ContractCaller{state: state, chain: chain, header: header}, } if err != nil { stop } } ``` ## Test cases TBD ## Reference TBD

Priority Fee Mechanism

Wed, 20 Mar 2024 00:00:00 +0000

# Simple summary Priority fee mechanism for transaction type 2 (EthereumDynamicFee) in terms of transaction ordering. # Abstract Activate the priority fee mechanism as defined in the EIP-1559. The maxPriorityFeePerGas field of transaction type 2 is no longer a placeholder, now it represents the priority fee the sender is willing to pay. The transactions are ordered by descending effective gas price, which is usually in the descending priority fee order. Under congested network, high priority transactions can be included to block by declaring high priority fee. # Motivation In Klaytn, the KIP-71 dynamic base fee mechanism and the FCFS (first come first serve) policy had been introduced to alleviate the network stability and usability issue caused by transaction bursts. However, if there are enough transactions that are willing to pay the upper bound base fee (e.g. 750 ston) then the network traffic will stay contested. Under such a condition, senders may experience transaction delay even if they pay the highest fee and send the transactions as soon as possible. Raising the base fee upper bound is undesirable solution because the users no longer be able to predict or budget their gas fee spendings. Instead, this proposal adds a reliable method for urgent transactions to be included in blocks. # Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC-2119](https://www.ietf.org/rfc/rfc2119.txt). ## Block processing ### Configuration The KIP-162 shall be activated since the `DRAGON_FORK_BLOCK_NUMBER`. | config | value | |-|-| | `MAGMA_FORK_BLOCK_NUMBER` | 98347376 (testnet), 99841497 (mainnet) | | `DRAGON_FORK_BLOCK_NUMBER` | TBD | ### Effective gas price and effective priority fee per gas The effective gas price and effective priorirty fee per gas of a transaction at given block are calculated as follows. The effective gas price is the actual price of gas fee paid by the sender. The calculation differs by whether the transaction type is 2 (EIP-1559 EthereumDynamicFee) or not. ```py def EffectiveGasPrice(header: Header, tx: Transaction): if header.number >= DRAGON_FORK_BLOCK_NUMBER: # Transaction type 2 has {maxFeePerGas, maxPriorityFeePerGas} fields # Other transactions only have {gasPrice} field if tx.type == 2: maxFeePerGas = tx.maxFeePerGas maxPriorityFeePerGas = tx.maxPriorityFeePerGas else: # makes EffectiveGasPrice() = tx.gasPrice maxFeePerGas = tx.gasPrice maxPriorityFeePerGas = tx.gasPrice return min(header.baseFeePerGas + maxPriorityFeePerGas, maxFeePerGas) elif header.number >= MAGMA_FORK_BLOCK_NUMBER: return header.baseFeePerGas else: # Note: before Magma hardfork, transactions must satisfy # tx.gasPrice == config.UnitPrice or tx.maxFeePerGas == config.UnitPrice. # Therefore EffectiveGasPrice is essentially config.UnitPrice. if tx.type == 2: return tx.maxFeePerGas else: return tx.gasPrice def EffectivePriorityFeePerGas(header: Header, tx: Transaction): if header.number >= DRAGON_FORK_BLOCK_NUMBER: effectiveGasPrice = EffectiveGasPrice(header, tx) return effectiveGasPrice - header.baseFeePerGas else: return 0 ``` ### KIP-82 reward scheme The [KIP-82](https://github.com/klaytn/kips/blob/main/KIPs/kip-82.md) reward scheme is slightly modified. The `get_total_fee` now accounts for effective gas price. Otherwise remains the same. ```py def get_total_fee(header: Header, txs: list[Transaction], receipts: list[Receipt]): # Note: EffectiveGasPrice handles hardfork totalFee = 0 for i in range(len(txs)): totalFee += EffectiveGasPrice(header, txs[i]) * receipts[i].gasUsed return totalFee ``` ### EVM GASPRICE opcode The `GASPRICE` (0x3a) opcode returns the effective gas price of the currently executing transaction. ## Transaction pool ### Transaction ordering Block transaction ordering depends on client implementation as the ordering is not checked by block validators. However, under the KIP-82 reward scheme, a proposer should prioritize high priority fee transactions for the maximum proposer reward. Block proposers are recommended to order transactions with descending effective gas price, and the same effective gas price are sorted by transaction arrival time. This discourages the transaction spamming where a sender sends many transactions hoping that at least one is included in the block. Instead, the sender would pay a higher priority fee to ensure the transaction be included in the block. ### Txpool management A transaction pool should not accept underpriced transactions. A transaction is underpriced if its `tx.gasPrice` or `tx.maxFeePerGas` field is lower than the baseFeePerGas of the pending block. ## JSON-RPC API ### `eth_gasPrice` and `klay_gasPrice` Returns suggested value for `gasPrice` or `maxFeePerGas` fields of a transaction. - Parameters: none - Result: Recommended gas price in peb. The result depends on the client implementation. - Example ```sh curl $RPC_URL -X POST -H 'Content-Type: application/json' --data ' {"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}' {"jsonrpc":"2.0","id":1,"result":"0xba43b7400"} ``` ### `eth_maxPriorityFeePerGas` and `klay_maxPriorityFeePerGas` Returns suggested value for `gasPrice` or `maxFeePerGas` fields of a transaction. - Parameters: none - Result: Recommended priority fee per gas in peb. The result depends on the client implementation. - Example ```sh curl $RPC_URL -X POST -H 'Content-Type: application/json' --data ' {"jsonrpc":"2.0","id":1,"method":"eth_maxPriorityFeePerGas","params":[]}' {"jsonrpc":"2.0","id":1,"result":"0x3b9aca00"} ``` ### `eth_feeHistory` and `klay_feeHistory` Returns historical gas information for a range of blocks. - Parameters - `blockCount` - Number of blocks in the requested range. - `newestBlock` - Highest block of the requested range. Can be a number or "latest". - `rewardPercentiles` - (optional) A monotonically increasing list of percentile (between 0 and 100) values. For each block in the requested range, the transactions will be sorted in ascending order by effective tip per gas and sampled at the specified percentiles. - Result - `oldestBlock` - Lowest number block of returned range. - `baseFeePerGas` - An array of block base fee per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block. Zeroes are returned for pre-Magma blocks. - `gasUsedRatio` - An array of block gas used ratios. Measures the network congestion level. These are calculated as the ratio of block gas used and [KIP-71 MAX_BLOCK_GAS_USED_FOR_BASE_FEE](https://github.com/klaytn/kips/blob/main/KIPs/kip-71.md). If the ratio is above 1, then 1 is returned. - `reward` - (optional) A 2D array of effective priority fees per gas. `reward[n][i]` is the `rewardPercentiles[i]`-th percentile effective priority fees per gas among the transactions in the block `oldestBlock + n`. Only returned if `rewardPercentiles` is specified. - Example ```sh curl $RPC_URL -X POST -H 'Content-Type: application/json' --data ' {"jsonrpc":"2.0","id":1,"method":"eth_feeHistory","params":[ 4, "latest", [50.0, 90.0, 95.0] ]}' { "id": "1", "jsonrpc": "2.0", "result": { "oldestBlock": "0x8e0a025", "baseFeePerGas": ["0x5d21dba00", "0x5d21dba00", "0x5d21dba00", "0x61c9f3680"], "gasUsedRatio": [0.023, 0.31, 1.0, 0.88], "reward": [ ["0x3b9aca00", "0x3b9aca00", "0x9502f900"], ["0x3b9aca00", "0x3b9aca00", "0x9502f900"], ["0x3b9aca00", "0x9502f900", "0x2e90edd00"], ["0x3b9aca00", "0x9502f900", "0x30e4f9b40"], ] } } ``` # Rationale ## A KIP-71 parameter is used in place of block gas limit The Ethereum's `eth_feeHistory` calculates gasUsedRatio as `block.gasUsed/blockGasLimit`. But Klaytn does not have hard limit of block gas. Instead, Klaytn's MAX_BLOCK_GAS_USED_FOR_BASE_FEE is analogous to Ethereum's block gas limit. In Ethereum, block gas limit is 30,000,000 and the base fee starts to rise when the block gas used exceeds 15,000,000 (`block.gasLimit / ELASTICITY_MULTIPLIER`). Similartly, the Klaytn's initial KIP-71 parameters stipulates that the block gas used is only accounted until 60,000,000 for the purpose of base fee calculation (`MAX_BLOCK_GAS_USED_FOR_BASE_FEE`), and the base fee starts to rise when the block gas used exceeds 30,000,000 (`GAS_TARGET`). # Backward compatibility ## Continued use of other transaction types Legacy (type 0) transactions, EIP-2930 AccessList (type 1) transactions, and Klaytn transaction types (types 8+) will work and be included in blocks. Those transactions have `gasPrice` field but no `maxFeePerGas` nor `maxPriorityFeePerGas` fields. For those transaction types, their effective gas price is considered to equal to the `gasPrice`. The senders pay the full price as declared in the `gasPrice`. This policy is identical to [EIP-1559](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md) and the same as pre-1559 auction market. In this manner, those transaction types pay a nonzero priority fee. | baseFeePerGas | transaction | effectiveGasPrice | effectivePriorityFeePerGas | |-|-|-|-| | 25 | {type: 0, gasPrice: 26} | 26 | 1 | | 25 | {type: 2, maxFeePerGas: 51, maxPriorityFeePerGas: 1} | 26 | 1 | ## EVM opcodes The `GASPRICE` (0x3a) opcode is backwards compatible because it had been correctly returning the effective gas price before `DRAGON_FORK_BLOCK_NUMBER`. The `BASEFEE` (0x48) opcode remains the same; returns the base fee per gas of the currently executing block. # References - https://github.com/klaytn/kips/blob/main/KIPs/kip-71.md - https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md - https://github.com/ethereum/execution-apis/blob/main/src/eth/fee_market.yaml

CnStakingV3 with public delegation

Tue, 30 Apr 2024 00:00:00 +0000

KIP Process Upgrade

Tue, 03 Dec 2024 00:00:00 +0000

## What is a KIP? KIP stands for Kaia Improvement Proposal. A KIP is a design document providing information to the Kaia community, or describing a new feature for Kaia or its processes or environment. The KIP should provide a concise technical specification of the feature and a rationale for the feature. The KIP author is responsible for building consensus within the community via discussion on the developer forum and documenting dissenting opinions. ## KIP Rationale We intend KIPs to be the primary mechanisms for proposing new standards and features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Kaia protocol and ecosystem. Because the KIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. For Kaia’s builders and contributors, KIPs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the KIPs that they have implemented. This will give KIP users a convenient way to know the current status of a given implementation and its constituent libraries. ## KIP Types There are in total four types of KIP: - A **Core KIP** describes any change that affects Kaia protocol implementations, such as a change to the network protocol, an improvement in block or transaction validity rules, an improvement in storage-layer mechanism, an improvement in interface around client API/RPC specifications and standards, and also certain language-level standards like method names and contract ABIs, any change in Kaia’s tokenomics-related settings and financial parameters, or any change in GC block reward mechanism, etc. Core KIP would be seen requiring a consensus fork as well as changes that are not necessarily consensus critical but may be relevant to any core-related development. Core KIPs consist of two parts, a design document and implementation. - An **Ecosystem KIP** describes any change falling under the broad category of ecosystem features, tools or environment used in Kaia development, such as a change on application layer related to proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Kaia, or a change in SDK layer related to application-level standards and conventions, such as name registries, URI schemes, library/package formats, and wallet formats, or an introduction of new ecosystem tool that could be integrated to the Kaia chain with implementation know-hows, or an introduction of contract standards that would introduce ecosystem features, etc. - A **Tokenization KIP** describes any change or introduction related to Kaia compatible tokens, such as an introduction of purpose-driven fungible token or non-fungible token and its minting policies in general. - A **Meta KIP** describes a process surrounding Kaia or proposes a change to (or an event in) a process. Meta KIPs apply to areas other than the KIPs listed above. Examples include procedures, guidelines, and changes to the decision-making process. Any Meta KIP is also considered a Process KIP. It is highly recommended that a single KIP contains a single key proposal or new idea. The more focused the KIP, the more successful it tends to be. A change to one client doesn’t require a KIP; a change that affects multiple clients, or defines a standard for multiple apps to use, does. A KIP must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly. ### Special requirements for Core KIPs If a **Core KIP** mentions or proposes changes to the KLVM (Kaia Virtual Machine, forked from Byzantium EVM), it should refer to the instructions by their mnemonics and define the opcodes of those mnemonics at least once. A preferred way is the following: ``` REVERT (0xfe) ``` ## KIP Work Flow ### Shepherding a KIP Parties involved in the process are you, the champion or *KIP author*, the [*KIP reviewers*](#kip-reviewers), and the Kaia dev team. Before you begin writing a formal KIP, you should vet your idea. Ask the Kaia community first if an idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread on [the Issues section of this repository](https://github.com/kaiachain/KIPs/issues) or directly over to [Kaia Dev Forum](https://devforum.kaia.io/c/english/kip/55). In addition to making sure your idea is original, it will be your role as the author to make your idea clear to reviewers and interested parties, as well as inviting reviewers, developers, and the community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your KIP is commensurate with both the work involved in implementing it and how many parties will have to conform to it. For example, the work required for implementing a Core KIP will be much greater than for others and the KIP will need sufficient interest from the Kaia client teams. Negative community feedback will be taken into consideration and may prevent your KIP from moving past the Draft stage. ### Core KIPs For Core KIPs, given that they require client implementations to be considered **Final** (see “KIPs Process” below), you will need to either provide an implementation for clients or convince clients to implement your KIP. In short, your role as the champion is to write the KIP using the style and format described below, shepherd the discussions in the appropriate forums, and build community consensus around the idea. ### KIP Process Following is the process that a successful KIP will move along: ``` [ IDEA ] -> [ DRAFT ] -> [ REVIEW ] -> [ LAST CALL ] -> [ ACCEPTED ] -> [ FINAL ] ``` Each status change is requested by the KIP author and reviewed by the KIP reviewers. Use a pull request to update the status. Please include a link to where people should continue discussing your KIP. The KIP reviewers will process these requests as per the conditions below. * **Idea** -- Once the champion has asked the Kaia community in [Dev Forum](https://devforum.kaia.io/c/english/kip/55) whether an idea has any chance of support, they will write a draft KIP as a [pull request](https://github.com/kaiachain/KIPs/pulls). Consider including an implementation if this will aid people in studying the KIP. * :arrow_right: Draft – If agreeable, a KIP reviewer will assign the KIP a number (generally the issue or PR number related to the KIP) and merge your pull request. The KIP reviewer will not unreasonably deny a KIP. * :x: Draft -- Reasons for denying draft status include being too unfocused, too broad, duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility. * **Draft** -- Once the first draft has been merged, you may submit follow-up pull requests with further changes to your draft until such point as you believe the KIP to be mature and ready to proceed to the next status. A KIP in draft status must be implemented to be considered for promotion to the next status. * :arrow_right: Review – If agreeable, the KIP reviewer will assign the Review status and officially take the proposal under review. * :x: An unsuccessful review would result in material changes or substantial unaddressed technical complaints will cause the KIP to revert to Draft, all would be based on the peer review feedback by KIP Reviewers. * **Review** -- A KIP Author marks a KIP as ready for and requesting Peer Review by Reviewers. * :arrow_right: Last Call – If agreeable, the KIP reviewer will assign the Last Call status and set a review end date (`review-period-end`), normally 14 days later. * :x: -- A request for Last Call status will be denied if material changes are still expected to be made to the draft. We expect that KIPs only enter Last Call once. * **Last Call** -- This KIP will be listed prominently as a pinned issue. * :arrow_right: Accepted – A successful Last Call without material changes or unaddressed technical complaints will become Accepted. * :x: -- A Last Call which results in material changes or substantial unaddressed technical complaints will cause the KIP to revert to Draft, all would be based on the peer review feedback by KIP Reviewers. * **Accepted** -- This status signals that material changes are unlikely and the Kaia dev team should consider this KIP for inclusion. Their process for deciding whether to encode it into their core protocol as part of a hard fork or include the new ecosystem integration/feature is not part of the KIP process. * :arrow_right: Draft – The KIP can be decided to move it back to the Draft status at the discretion. E.g. a major, but correctable, flaw was found in the KIP by the reviewer committee. * :arrow_right: Rejected – The KIP can be decided to be marked as this KIP as Rejected at their discretion. E.g. a major, but uncorrectable, flaw was found in the KIP. * :arrow_right: Final – Standard Track Core KIPs must be implemented in any of Kaia clients before it can be considered Final. When the implementation is complete and adopted by the community, the status will be changed to "Final". * **Final** -- This KIP represents the current state-of-the-art. A Final KIP should only be updated to correct errata. Other exceptional statuses include: * **Active** -- Some Informational and Process KIPs may also have a status of “Active” if they are never meant to be completed. E.g. KIP-201 (this KIP). * **Abandoned** -- This KIP is no longer pursued by the original authors or it may not be a (technically) preferred option anymore. * :arrow_right: Draft – Authors or new champions wishing to pursue this KIP can ask for changing it to Draft status. * **Rejected** -- A KIP that is fundamentally broken or a Core KIP that was rejected by the Core Devs and will not be implemented. A KIP cannot move on from this state. * **Superseded** -- A KIP which was previously Final but is no longer considered state-of-the-art. Another KIP will be in Final status and reference the Superseded KIP. A KIP cannot move on from this state. ## What belongs in a successful KIP? Each KIP should include the following parts: - Preamble - RFC 822 style headers containing metadata about the KIP, including the KIP number, a short descriptive title (limited to a maximum of 44 characters), and the author details. See [below](#kip-header-preamble) for details. - Abstract - A short (~200 word) description of the technical issue being addressed. - Motivation: Why is this KIP necessary? - The motivation is critical for KIPs that want to change the Kaia protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the KIP solves. KIP submissions without sufficient motivation will be rejected outright. - Specification - The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Kaia platforms. - Rationale: How does this KIP achieve its goals? - The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion. - Backwards Compatibility (if applicable) - All KIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The KIP must explain how the author proposes to deal with these incompatibilities. KIP submissions without a sufficient backwards compatibility treatise may be rejected outright. - Test Cases (if applicable) - Test cases for an implementation are mandatory for KIPs that are affecting consensus changes. Other KIPs can choose to include links to test cases if applicable. - Implementations - The implementations must be completed before any KIP is given status “Final”, but it need not be completed before the KIP is merged as draft. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of API details. - Optional Sections (if applicable) - May appear in any order, or with custom titles, at author and reviewer discretion: - Versioning: if Versioning is not addressed in Specification - Appendices - References - Copyright Waiver - All KIPs must be in the public domain. See the bottom of this KIP for an example copyright waiver. ## KIP Formats and Templates KIPs should be written in [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Image files should be included in a subdirectory of the `assets` folder for that KIP as follows: `assets/kip-N` (where **N** is to be replaced with the KIP number). When linking to an image in the KIP, use relative links such as `../assets/kip-201/image.png`. ## KIP Header Preamble Each KIP must begin with an [RFC 822](https://www.ietf.org/rfc/rfc822.txt) style header preamble, preceded and followed by three hyphens (`---`). This header is also termed ["front matter" by Jekyll](https://jekyllrb.com/docs/front-matter/). The headers must appear in the following order. Headers marked with “*” are optional and are described below. All other headers are required. ` kip:` *KIP number* (this is determined by the KIP editor) ` title:` *KIP title* ` author:` *a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s). Details are below.* ` * discussions-to:` *an url pointing to the official discussion thread* ` status:` *Draft | Review | Last Call | Accepted | Final | Active | Abandoned | Rejected | Superseded* ` * review-period-end:` *date review period ends* ` type:` *Core | Ecosystem | Tokenization | Meta* ` created:` *date created on* ` * updated:` *comma separated list of dates* ` * requires:` *KIP number(s)* ` * replaces:` *KIP number(s)* ` * superseded-by:` *KIP number(s)* ` * resolution:` *an url pointing to the resolution of this KIP* Headers that permit lists must separate elements with commas. Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd). #### `author` header The `author` header optionally lists the names, email addresses or usernames of the authors/owners of the KIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be: > Kaia A. User <address@kaia.io> or > Kaia A. User (@username) if the email address or GitHub username is included, and > Kaia A. User if the email address is not given. #### `resolution` header The `resolution` header is required for Standards Track KIPs only. It contains a URL that should point to an email message or other web resource where the pronouncement about the KIP is made. #### `discussions-to` header While a KIP is a draft, a `discussions-to` header will indicate the mailing list or URL where the KIP is being discussed. As mentioned above, examples for places to discuss your KIP include an issue in this repo or in a fork of this repo. No `discussions-to` header is necessary if the KIP is being discussed privately with the author. As a single exception, `discussions-to` cannot point to GitHub pull requests. #### `type` header The `type` header specifies the type of KIP: Core, Ecosystem, Tokenization and Meta. #### `created` header The `created` header records the date that the KIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2024-12-3. #### `updated` header The `updated` header records the date(s) when the KIP was updated with "substantial" changes. This header is only valid for KIPs of Draft and Active status. #### `requires` header KIPs may have a `requires` header, indicating the KIP numbers that this KIP depends on. #### `superseded-by` and `replaces` headers KIPs may also have a `superseded-by` header indicating that a KIP has been rendered obsolete by a later document; the value is the number of the KIP that replaces the current document. The newer KIP must have a `replaces` header containing the number of the KIP that it rendered obsolete. ## Linking to other KIPs References to other KIPs should follow the format `KIP-N` where **N** is the KIP number you are referring to. Each KIP that is referenced in an KIP MUST be accompanied by a relative markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in this GitHub repository, forks of this repository, the main KIPs site, mirrors of the main KIP site, etc. For example, you would link to this KIP as `./kip-201.md`. ## Auxiliary Files KIPs may include auxiliary files such as diagrams. Such files must be named KIP-XXXX-Y.ext, where “XXXX” is the KIP number, “Y” is a serial number (starting at 1), and “ext” is replaced by the actual file extension (e.g. “png”). ## Transferring KIP Ownership It occasionally becomes necessary to transfer ownership of KIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred KIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the KIP process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the KIP. We try to build consensus around a KIP, but if that's not possible, you can always submit a competing KIP. If you are interested in assuming ownership of a KIP, send a message asking to take over, addressed to both the original author and the KIP reviewer. If the original author doesn’t respond to email in a timely manner, the KIP reviewer will make a unilateral decision (it’s not like such decisions can’t be reversed :)). ## KIP Roles To encourage greater community participation with an effective KIP process framework as the foundation of open-source contribution to Kaia chain and ecosystem, we propose to have the following role structure: - KIP Reviewer - KIP Author - Dev Team ### KIP Reviewers The current KIP reviewers are: ` * Aidan Kwon (@aidan-kwon)` ` * Ollie Jeong (@blukat29)` ` * Iron Cho (@ironcho)` ` * Jack Jin (@kjeom)` ` * Ashwani Modi (@modiashwani)` ` * Scott Lee (@scott-klaytn)` ` * Neo Yiu (@neoofkaia)` ## KIP Reviewer Responsibilities For each new KIP that comes in, a reviewer does the following: - Read the KIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to final status. - The title should accurately describe the content. - Check the KIP for language (spelling, grammar, sentence structure, etc.), markup (Github flavored Markdown), code style If the KIP isn't ready, the reviewer will send it back to the author for revision, with specific instructions. Once the KIP is ready for the repository, the KIP reviewer will: - Assign a KIP number (generally add “200” to the respective pull request number) - Merge the corresponding pull request - Send a message back to the KIP author with the next step Many KIPs are written and maintained by developers with write access to the Kaia codebase. The KIP reviewers monitor KIP changes, and correct any structure, grammar, spelling, or markup mistakes identified. ## KIP Author KIP author is any community member of Kaia blockchain who can present a proposal and start the KIP process. ## KIP Author Responsibilities For each of the new KIPs that comes in, an author does the following: - Articulating the proposed changes clearly and concisely starting from discussion threads on Kaia Dev Forum - Explaining the expected effects of the proposed changes - Encouraging community participation and engaging in discussions around the proposal - Actively seeking feedback from other community members - Checking alignment with the community and the strategic focuses of Kaia ecosystem And any author of KIP is expected to: - Draft, edit and refine the KIP using the provided template - Follow the instructions provided in the GitHub/KIPs documentation - Collect and incorporate feedback from the community and reviewers - Document alternative opinions, the options considered and other discussed topics - Champion the KIP through each stage of the KIP process - Coordinate with Kaia’s Dev Team for a smooth KIP implementation, being included in protocol and ecosystem level ## Dev Team Dev Team refers to the Kaia’s core development team, ecosystem development team, contributors and any other active participants that are making updates, parameter changes, and upgrades to the Kaia protocol itself. ## Dev Team Responsibilities For each of the new KIPs that comes in, the dev team does the following: - Reviewing KIP’s implementation plan - Executing the implementation plan of approved KIPs And any author of KIP is expected to: - Assess the feasibility of the KIP’s implementation plan and provide feedback to the KIP Author - Ensure correct execution of the implementation plan in a timely manner - Communicate and explain any delays and other important decisions about the implementation with the KIP Author and community ## KIP Numbers When referring to KIP with any other category, it must be written in the hyphenated form `KIP-X` where **X** is that KIP’s assigned number. A default KIP number would be starting with adding “200” to the respective pull request number. ## History This document was derived heavily from [Ethereum's EIP-1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md) written by Martin Becze, Hudson Jameson, et al, as the first version, later specified with the Kaia’s KIP framework and process for Kaia blockchain and ecosystem exclusively. [Ethereum's EIP-1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md) was derived heavily from [Bitcoin's BIP-0001](https://github.com/bitcoin/bips) written by Amir Taaki which in turn was derived from [Python's PEP-0001](https://www.python.org/dev/peps/). In many places text was simply copied and modified. The authors of the documents are not responsible for its use in the Kaia Improvement Proposal, and should not be bothered with technical questions specific to Kaia or the KIP. Please direct all comments to the KIP reviewers. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Reduce calldata gas cost and introduce floor data gas

Fri, 18 Oct 2024 00:00:00 +0000

Consensus liquidity for Kaia

Thu, 07 Nov 2024 00:00:00 +0000

# Table of contents - [Simple Summary](#simple-summary) - [Abstract](#abstract) - [Motivation](#motivation) - [Specification](#specification) - [Terminology](#terminology) - [Overview](#overview) - [Configuration](#configuration) - [CLRegistry](#clregistry) - [StakingTrackerV2](#stakingtrackerv2) - [CLDEX](#cldex) - [Consensus](#consensus) - [On-chain Governance](#on-chain-governance) - [JSON-RPC API](#json-rpc-api) - [Rationale](#rationale) - [Backward Compatibility](#backward-compatibility) - [Copyright](#copyright) ## Simple Summary Introduce a consensus liquidity mechanism for Kaia. The staked KAIA through the consensus liquidity will contribute to the consensus and [on-chain governance](https://kips.kaia.io/KIPs/kip-81) of Kaia. ## Abstract This KIP introduces a consensus liquidity mechanism where KAIA and CL Token holders can participate in Kaia network through liquidity provision. Users stake KAIA tokens in the native decentralized exchange (CLDEX), simultaneously providing market liquidity and securing the network. Stakers earn both swap fees and block rewards, creating an efficient capital utilization. The eligibility of GC remains unaffected by consensus liquidity, which means it still requires maintaining 5M KAIA staked solely through `CnStaking` contract, as is currently the case. ## Motivation The current staking model often leads to capital inefficiency, where staked tokens remain idle. This KIP addresses this limitation by introducing consensus liquidity, which serves multiple purposes: 1. **New Utility**: Staked KAIA simultaneously secure the network and provide DEX liquidity, increasing the token utility. 2. **Enhanced Network Security**: By tying liquidity provision to consensus, we can expect more KAIA staked for the network, which enhances the network security. 3. **Sustainable Tokenomics**: The dual reward structure (swap fees + block rewards) creates a new utility and burn mechanism, building a sustainable tokenomics for Kaia and CL Token. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. ### Terminology | Term | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | CnStaking | The existing staking contract for Kaia. Usually referred as `CnStakingV2` or `CnStakingV3` | | Consensus Liquidity (CL) | A mechanism where KAIA and CL Token holders can participate in Kaia network through liquidity provision. | | CLDEX | A decentralized exchange (DEX) on Kaia that allows users to trade KAIA and CL Token. | | CL Token | A token pair with KAIA. | | LP Token | A token representing the liquidity provider's share in the CLDEX. | ### Overview There'll be modified and new smart contracts to be developed. ![CL Overview](/assets/kip-226/KIP-226-1.png) - `CLRegistry`: A new registry for CLDEX. Manage the information of CLDEXs for `StakingTrackerV2` and Kaia core. - `CLDEX`: A new smart contract for CLDEX. It consists of router, factory, and pool. - `StakingTrackerV2`: A modified [staking tracker](https://kips.kaia.io/KIPs/kip-81) to track the staked KAIA in CLDEX for the governance. The existing `StakingTracker` contract will be deprecated. The detailed information of each smart contract is described in the following sections. ### Configuration The KIP-226 shall be used since processing `PRAGUE_FORK_BLOCK_NUMBER` block. Please note that the staking information at previous block will be used to process current block since the Kaia hardfork. | config | value | | -------------------------- | ----- | | `PRAGUE_FORK_BLOCK_NUMBER` | TBD | ### CLRegistry The `CLRegistry` contract must implement the `ICLRegistry` interface: ```solidity interface ICLRegistry { struct CLInfo { /// @dev The node ID of the validator address nodeId; /// @dev The governance committee ID of the validator uint256 gcId; /// @dev The address of the CLDEX pool address clPool; } /// @dev Returns the CL information of all registered validators /// @return The CL information of all registered validators function getAllCLs() external view returns (address[] memory nodeIds, uint256[] memory gcIds, address[] memory clPools); } ``` The `CLRegistry` will be registered in [KIP-149](https://kips.kaia.io/KIPs/kip-149) system registry with activation of `PRAGUE_FORK_BLOCK_NUMBER - 1`. ### StakingTrackerV2 The all external functions of `StakingTrackerV2` contract must have same selector and semantics as the existing `StakingTracker` contract to be compatible with the existing contracts. The additional tracking processes of `StakingTrackerV2` are as follows: 1. Creating a new tracker: When creating a new tracker, the `StakingTrackerV2` contract must call `CLRegistry.getAllCLs()` to populate the CL information. 2. Updating the tracker: When the staked KAIA in `CLPool` changes, the `StakingTrackerV2` contract must update the staked KAIA for the corresponding validator. The `StakingTrackerV2` will be registered in [KIP-149](https://kips.kaia.io/KIPs/kip-149) system registry with activation of `PRAGUE_FORK_BLOCK_NUMBER`. #### Voting Power Eligibility The validator is eligible for voting power if the staked KAIA in `CnStaking` is greater than or equal to 5M. For example: - Validator A: CnStaking (6M) + CLPool (5M) = 11M total stake, 2 voting power - Validator B: CnStaking (4M) + CLPool (10M) = 14M total stake, 0 voting power ### CLDEX The CLDEX is a decentralized exchange on Kaia for consensus liquidity based on UniswapV2's CPMM model and implementation. The liquidity providers (LPs) deposit KAIA and CL Token in the CLDEX and earn swap fees and block rewards. It consists of router, factory, and pool contracts. ![CLDEX Overview](/assets/kip-226/KIP-226-2.png) #### Staking Requirements - All LP tokens in CLDEX MUST be subject to a minimum staking period of 7 days from the moment of provision, without exception. This differs from the traditional CnStaking withdrawal process as: - The 7-day period begins automatically upon LP token creation - No separate withdrawal request is required - Additional staking or partial withdrawal is allowed but it'll reset the 7-day period - The transfer of LP Token leads to resettlement of the 7-day period of the sender It makes the calculation of the staked KAIA in CLDEX more easier since the all KAIA in CLDEX can be considered as staked. #### Pair Creation and Management 1. CL Token pairs MUST be approved through governance before being listed on CLDEX 2. No duplicate pair is allowed on CLDEX. Only one pair per CL Token is allowed. 3. Only designated owner addresses SHALL have the authority to create new pairs 4. During the initial stability period: - Liquidity provision SHALL be restricted to designated addresses - After stability is confirmed, liquidity provision SHALL be opened to all participants - Swap SHALL be available to all participants since the beginning #### Block Rewards The CLDEX will receive block rewards from the Kaia core for contributing to the consensus. Note that the block rewards will be directly injected into the CLPair (CLPool) contract, similar to the [Public Delegation](https://kips.kaia.io/KIPs/kip-163) contract. 1. Block rewards for CLDEX SHALL be distributed based on: - The proportional LP Token of each staker - Rewards SHALL be distributed per second to eligible stakers - No lockup period for rewards #### StakingTrackerV2 Interaction As `CnStaking` notifies its staked KAIA changes to `StakingTracker`, the CLDEX must notify to `StakingTrackerV2` whenever the staked KAIA in CLDEX changes. For example, based on UniswapV2's implementation, the target functions must call `stakingTrackerV2.refreshStake(address(this))`. - `CLDEX.mint`: Used when providing liquidity - `CLDEX.burn`: Used when removing liquidity - `CLDEX.swap`: Used when swapping tokens #### Commission CLDEX commissions are derived from two sources: 1. Swap fees from CLPool 2. Block rewards from CLPool **Swap Fee Commission**: - Commissions can be collected from swap fees - Burn ratios can be configurable by token type (e.g., KAIA: 10%, CL Token: 5%) **Block Reward Commission**: - Commissions can be collected from block rewards For both commission types, the following parameters are configurable: - Commission receiver addresses - Split ratios for each receiver address - Burn ratios ### Consensus Since the `PRAGUE_FORK_BLOCK_NUMBER`, staked KAIA will be tracked through two mechanisms: 1. **CnStaking** - Existing staking mechanism through the `CnStaking` contract 2. **Consensus Liquidity** - New staking mechanism through CLDEX liquidity provision Similar to voting power requirements, validators must maintain at least 5M KAIA staked in CnStaking to be eligible to propose blocks. The total effective staked amount for staking rewards distribution is calculated as: ``` totalEffectiveStakedKAIA = staked KAIA in CnStaking + staked KAIA in CLDEX ``` #### Block Rewards Distribution The total block reward for each validator will be calculated based on [KIP-82](https://kips.kaia.io/KIPs/kip-82), while the split ratio between `CnStaking` and `CLDEX` will be proportional to their respective staked KAIA amounts. ### On-chain Governance The on-chain governance will be maintained except using `StakingTrackerV2` instead of `StakingTracker`. #### StakingTracker Replacement Process 1. Deploy the new `StakingTrackerV2` contract 2. Propose a `StakingTracker` replacement on Voting 3. After the proposal is approved, the new `StakingTrackerV2` contract will be set for Voting 4. Replace all `StakingTracker` contracts of `CnStaking` with `StakingTrackerV2` ## JSON-RPC API ### `kaia_getStakingInfo` The new field `clStakingInfo` will be added to the response of `kaia_getStakingInfo` since the `PRAGUE_FORK_BLOCK_NUMBER` to provide the CLStaking information if exists. - Example ```json // Request curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0", "method":"kaia_getStakingInfo", "params":["latest"],"id":1}' http://localhost:8551 // Response { "jsonrpc":"2.0", "id":1, "result": { KIRAddr: "0x6c38302e00dbac91712d93ab94b4a827698be6f1", PoCAddr: "0xc8757a6b5b427ddcd5781c9faa5e41318d32336a", blockNum: 109, clStakingInfos: [{ clNodeId: "0x4e37f45ab0385782afbbc713f4b0d5f936ba2201", clPoolAddr: "0x07987c97befca39f6fcf884271cc65f85d8d1a5b", clStakingAmount: 5000000 }, { clNodeId: "0x681f56e59003172201d155ca8a5dbe0ad0993641", clPoolAddr: "0xe1f42e74dbf400affd54553a7c258b88ab3e2a8f", clStakingAmount: 10000000 }], councilNodeAddrs: ["0x4e37f45ab0385782afbbc713f4b0d5f936ba2201", "0x681f56e59003172201d155ca8a5dbe0ad0993641", "0x7fcd59726eb6560f385c195ff33db9385aadf644", "0x15245589f68c14690cbcc3131256aeb594a006f7"], councilRewardAddrs: ["0x1ffdee22fa4df55d66dea1d9435343be2c0d3b12", "0xf411483d602620203bbfc9ba87e38bcfb6430b90", "0x2836a57c4fc95537ba2c3b1587d2a7d195a278e6", "0x6b4679e1a0aa81ffcab3e0b70044b3c0928b7f44"], councilStakingAddrs: ["0xcf24c0f2e12c534046f32d1bd072e9eabbe1012d", "0xd08ace335231e523c5cf7c0b1078a7365f3a606d", "0x2c701c0bf6792a4643dc095547494357b92b5d72", "0x4539ccc933283507d11aff505ea3fb47fad1d282"], councilStakingAmounts: [5000000, 10000000, 15000000, 20000000], gini: 0.13, kcfAddr: "0x6c38302e00dbac91712d93ab94b4a827698be6f1", kefAddr: "0x6c38302e00dbac91712d93ab94b4a827698be6f1", kffAddr: "0xc8757a6b5b427ddcd5781c9faa5e41318d32336a", kifAddr: "0xc8757a6b5b427ddcd5781c9faa5e41318d32336a", useGini: false } } ``` ## Rationale ### Set activation to `PRAGUE_FORK_BLOCK_NUMBER - 1` for `CLRegistry` The Kaia's using previous block's staking information to process current block since the Kaia hardfork. It makes the `CLRegistry` at `PRAGUE_FORK_BLOCK_NUMBER - 1` to be required to track the staked KAIA in CLDEX at `PRAGUE_FORK_BLOCK_NUMBER` if exists. Please note that the `StakingTrackerV2` will also populate the staked KAIA in CLDEX at `PRAGUE_FORK_BLOCK_NUMBER - 1` if transaction creating a new tracker is executed at exact `PRAGUE_FORK_BLOCK_NUMBER - 1` block, which is not feasible. ### Separate Reward Address The validator only has one reward address even if it has multiple `CnStaking` contracts. But this KIP will break that invariant by separating the reward address for `CnStaking` and `CLDEX`. It's natural to separate the reward address since consensus liquidity is a new staking mechanism and has different form and reward profile. ### Minimum Staking Period The decision not to implement a 7-day waiting period after unstaking request (like in CnStaking) was made for several reasons. From a consensus perspective, since Kaia's validators will be selected as proposer randomly based on [KIP-146](https://kips.kaia.io/KIPs/kip-146), requiring 5M in CnStaking provides sufficient protection against consensus instability. From a governance perspective, while it's important to prevent sudden voting power shifts in response to specific proposals, this can be adequately addressed through the minimum staking period alone. Additionally, LP assets receive comparatively lower block rewards relative to their invested assets compared to CnStaking, and are subject to impermanent loss risks. Therefore, to promote CL adoption through the ecosystem, the requirements were made more lenient to allow users to utilize CL more easily. ### 5M KAIA in CnStaking to be validator As mentioned in the [Minimum Staking Period](#minimum-staking-period), the 5M KAIA in CnStaking is to prevent the consensus instability. It'll act as a safety margin for network stability. Even if the validator is not malicious, the staked KAIA in CLDEX can be extremely volatile due to the external market conditions. It's not reasonable to rely solely on the volatile staked KAIA. ## Backward Compatibility ### StakingTrackerV2 The `StakingTrackerV2` contract will support same functions as the existing `StakingTracker` contract to be compatible with the existing contracts. ## References - [Enrinshed Liquidity](https://docs.initia.xyz/about/enshrined-liquidity-and-staking) - [Proof of Liquidity](https://docs.berachain.com/learn/what-is-proof-of-liquidity) ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

Candidate and Validator Evaluation

Tue, 07 Jan 2025 00:00:00 +0000

## Simple Summary This proposal presents VRank, a framework for quantitatively assessing the performance and stability of candidates and validators in the Kaia Chain network. ## Abstract As Kaia Chain transitions to a permissionless network structure, it is critical to hold validators more accountable. They play an important role in ensuring that the network runs smoothly, securely, and without problems. This KIP introduces VRank, a Validator Reputation Evaluation Framework that quantitatively assesses the performance and stability of both candidates and validators. VRank aims to ensure that nodes involved in the consensus mechanism are trustworthy and capable of meeting the security requirements of the permissionless Kaia Chain network. ## Introduction It is planned for the Kaia Chain network to change from a Permissioned network to a Permissionless network. In a permissionless network, anyone can become a validator without being approved first. This makes the network more decentralized, safe, and open to everyone. This change fits with Kaia Chain's goal of making the blockchain ecosystem more open and strong. Please refer to [KGP-4: Permissionless Kaia Chain](https://govforum.kaia.io/t/kgp-4-permissionless-klaytn/135) for more thorough details for switching to a permissionless network. ## Motivation In decentralized networks employing blockchain technology, the reliability and performance of validator nodes are crucial for maintaining network stability, security, and efficiency. Validator nodes propose and validate new blocks, ensuring ledger integrity and establishing trust among participants through consistent operation. However, not all validator nodes operate at optimal efficiency. Certain individuals may experience frequent failures or delays, while others may exhibit malicious behavior, either deliberately or due to external pressures. These problems may lead to delays in the network, a chance of forks, and higher susceptibility to attacks, such as double-spending and censorship. The current systems for evaluating validator performance may ineffectively penalize persistent underperformance or malicious behavior, and they fail to consistently encourage optimal performance incentives. A thorough evaluation system is essential to precisely evaluate the reliability of validator nodes, discourage inadequate performance, and improve the overall integrity of the network. This proposal introduces an innovative evaluation framework for candidates and validators, highlighting measurable performance metrics. Our objective is to create a more resilient and fair framework for assessing node performance by defining metrics such as the Proposal Failure Score (PFS) and Candidate Failure Score (CFS). This framework aims to identify underperforming or malicious nodes, which helps preserve high standards among validators. The framework promotes consistent uptime and reliability. Validators have an incentive to maintain the stability and responsiveness of their nodes, thereby maintaining the performance of the network. ## Specification ### Parameters | Constant | Value/Definition | | :-------------------------- | :---------------------------------------------------------------------- | | `FORK_BLOCK` | TBD | | `CANDIDATE_MSG_TIMEOUT` | Protocol parameter (milliseconds). Default = 500ms. | | `EPOCH_LENGTH` | 86,400 blocks (approximately 1 day, assuming 1-second block time) | | `MAX_BYZANTINE_NODES` (`F`) | Calculated as `F = (n - 1) // 3`, where `n` is the number of validators | | `PFS_THRESHOLD` | 2 (max proposal failures per epoch) | | `CFS_THRESHOLD` | 300 (max candidate failures per epoch) | ### Data Structures and Protocol Primitives #### Block Header Extension (VRank) Starting from `FORK_BLOCK`, the block header includes a new field `VRank`. The `VRank` field contains `RLPEncode(cfReport)` or `nil` if `cfReport` is empty. ```go type Header struct { ParentHash common.Hash // ... existing fields ... Extra []byte Governance []byte Vote []byte BaseFee *big.Int RandomReveal []byte MixHash []byte VRank []byte // New field } ``` #### Reports (pfReport, cfReport) Both `pfReport` and `cfReport` are per-block data structures. A node's presence in either report is undesirable: it indicates a failure, and the node may be penalized in future epoch evaluations. **pfReport** (Proposal Failure Report): Extractable from `header.Extra`. Contains the list of proposers who induced round-change during the consensus of the block. Format: `pfReport(N) -> [proposerAddrRound0, proposerAddrRound1, ...]` with at most one entry per validator (`validator(N)`). **cfReport** (Candidate Failure Report): Encoded in `header.VRank` at block `N` for target block `N-1`. Contains the list of candidates (nodes in `CandTesting`) that failed to send a valid `VRankCandidate` message on-time for block `N-1`. If `N % k*EPOCH_LENGTH == 0` (epoch start), `cfReport(N)` MUST be empty. Format: `cfReport(N) -> [candidateAddr1, candidateAddr2, ...]` with at most one entry per candidate of previous block (`candidate(N-1)`). #### VRankPreprepare `VRankPreprepare` is a message type sent by the proposer of block `N` to all candidates under `CandTesting` after having sent Istanbul Preprepare messages to consensus participants. It triggers candidates to respond with `VRankCandidate`. The timeout for candidate response is `CANDIDATE_MSG_TIMEOUT` (default 500ms). ```go type VRankPreprepare struct { Block *types.Block View *istanbul.View } ``` #### VRankCandidate `VRankCandidate` is a message type sent by each candidate (node in `CandTesting`) to all validators under `ValActive` upon receiving `VRankPreprepare`. A candidate must send `VRankCandidate` within `CANDIDATE_MSG_TIMEOUT` of the counterparty's `preprepared_time` to be counted as on-time. **Signature scheme**: The `signature` MUST be produced with the candidate's validator signing key over `keccak256("VRANK_CANDIDATE_V1" || chain_id || block_number || round || block_hash)`, with an unambiguous canonical encoding of each field. ```go type VRankCandidate struct { BlockNumber uint64 Round uint8 BlockHash common.Hash Sig []byte } ``` ### Consensus Protocol Integration VRank runs in parallel with consensus. Per block, reports (`pfReport` and `cfReport`) are produced during consensus and committed in the next block header. #### Proposer of block N 1. After having sent Istanbul Preprepare messages to consensus participants, the proposer MUST send `VRankPreprepare` to all candidates in `CandTesting`. 2. The round information is recorded in `header.Extra` as part of the existing consensus. If the proposer fails to propose and a round change occurs, the failed proposer's address is recorded in `pfReport(N)`. #### Validators during consensus for block N 1. When block `N` enters the `preprepared` pBFT state, each validator MUST record `preprepared_time`. 2. Each validator MUST collect `VRankCandidate` messages from candidates in `CandTesting` and record each message's arrival time. 3. If a validator receives more than one `VRankCandidate` from the same candidate for the same view (block number `N` and round `R`), only the first valid message MUST be accepted; subsequent messages MUST be ignored. 4. A candidate is counted as on-time if the message is valid and either (a) it arrives before `preprepared_time`, or (b) `arrival_time - preprepared_time ≤ CANDIDATE_MSG_TIMEOUT`. Otherwise, it will be recorded in `cfReport(N+1)`. #### Candidates (nodes in CandTesting) 1. Upon receiving `VRankPreprepare` for block `N`, each candidate MUST broadcast `VRankCandidate` to all validators in `ValActive`. 2. To be counted as on-time, the `VRankCandidate` MUST arrive at each validator within `CANDIDATE_MSG_TIMEOUT` of that validator's `preprepared_time` for block `N`. #### Proposer of block N+1 1. When proposing block `N+1`, the proposer MUST build `header.VRank` from `cfReport(N)`. 2. `cfReport(N+1)` MUST include each candidate (in `CandTesting` at block `N`) who either (a) did not send a valid `VRankCandidate` for block `N` on-time, or (b) sent an invalid message. 3. The proposer MUST encode `cfReport` in `header.VRank` as `RLPEncode(cfReport)` or `nil` if empty. 4. Candidates in `cfReport` are counted as failures for CFS aggregation. #### Block Validation After `FORK_BLOCK`, validators MUST validate the newly added `VRank` field in the block header. The values of the subfields (`cfReport`) are used to evaluate node performance using the components of the VRank framework. Given a header with number `N`: - `header.VRank` MUST be `nil` or `RLPEncode(cfReport(N))`. - `cfReport(N)` MUST contain at most one entry per candidate ID. Each entry must be a candidate address from `candidates(N-1)`. ### Failure Scores (PFS, CFS) Each score is per epoch, computed from `pfReport` and `cfReport` in epoch blocks. Higher values indicate worse performance; zero indicates no failures. **Proposal Failure Score (PFS)**: For a given block number `N`, PFS MUST be computed from `pfReport(b)` for blocks `x ∈ [epochStart(N), N]`. For each validator, count how many times the validator appears across all `pfReport`s in the epoch (each round change adds one entry). PFS maps each validator address to its total proposal failure count. Format: `pfs(N) -> map[proposerAddr]score` **Candidate Failure Score (CFS)**: For a given block number `N`, CFS MUST be computed from `cfReport(b)` for blocks `b ∈ [epochStart(N), N]` (note that `cfReport(epochStart(N))` is empty). For each candidate `C` and reporter (proposer of block `N`): if `C` is in `cfReport(N)`, that counts as 1 failure. For each candidate, sum failures per reporter over the epoch, discard the highest `F` reporter totals (Byzantine filtering), and sum the remainder to obtain CFS. Format: `cfs(N) -> map[candidateAddr]score` **Example: Byzantine filtering in CFS** _Example 1: Short epoch_ ``` epoch = 5 len(validator) = 4 len(candidates) = 3 F = 1 proposer(5)=P1, cfReport(5)=[] proposer(6)=P2, cfReport(6)=[] proposer(7)=P3, cfReport(7)=[C1,C2,C3] proposer(8)=P4, cfReport(8)=[C1,C2] proposer(9)=P4, cfReport(9)=[C1,C2] ``` Aggregated `cfReport(N)` where N ∈ \[5, 9\]:

Candidate \ Reporter	raw data (cfReport)				summary (CFS)
Candidate \ Reporter	P1	P2	P3	P4	Total	Filtered	Byzantine filtering
C1	0	0	1	2	3	1	P4 is not counted
C2	0	0	1	2	3	1	P4 is not counted
C3	0	0	1	0	1	0	P3 is not counted

_Example 2: Byzantine behavior_ Consider a network with 10 validators (proposers P1–P10) and 5 candidates (C1–C5). The table shows how many times each candidate appears in `cfReport(N)` when each proposer produced a report (i.e., failures reported per candidate per reporter). P8, P9, and P10 report abnormally high counts for C1–C3, suggesting Byzantine behavior. With `F = 3`, we discard the highest 3 reporter totals per candidate and sum the remainder to obtain the filtered CFS.

Candidate \ Reporter	raw data (cfReport)										summary (CFS)
Candidate \ Reporter	P1	P2	P3	P4	P5	P6	P7	P8	P9	P10	Total	Filtered	Byzantine filtering
C1	14	12	15	34	12	32	20	8640	8637	8634	26050	139	exclude reports from P8,P9,P10
C2	48	10	59	33	49	49	41	8640	8637	8634	26200	289	exclude reports from P8,P9,P10
C3	48	22	40	41	44	27	61	8640	8637	8634	26194	283	exclude reports from P8,P9,P10
C4	50	29	45	30	23	2	42	56	56	64	397	221	exclude reports from P8,P9,P10
C5	71	34	62	5	11	20	18	30	19	13	283	116	exclude reports from P1,P2,P3

_Note: Each `cfReport(N)` is in the header of block `N` and reports on target block `N - 1`._ ### Score thresholds A node must meet the following stability requirements to participate in consensus: - **Block proposal participation**: At most `PFS_THRESHOLD` proposal failures per epoch. - **Downtime**: Less than 0.5% downtime per epoch (fewer than 432 blocks missed). Violations: - a validator exceeding `PFS_THRESHOLD` in an epoch is classified as not qualified. - a candidate exceeding `CFS_THRESHOLD` in an epoch is classified as not qualified. The handling of not-qualified nodes is specified in [KIP-286](https://kips.kaia.io/KIPs/kip-286). ## Rationale ### Choice of CFS_THRESHOLD Historical data from vrank logs indicates that most healthy nodes pass the evaluation with CFS well below 300 per epoch. The threshold of 300 is therefore set to distinguish underperforming or unstable candidates while allowing normal nodes to qualify for validator promotion. ### Importance of Mitigating Malicious Behavior **Byzantine Nodes** In a permissionless environment, some validators may act maliciously, attempting to disrupt the network or unfairly penalize honest nodes. It is assumed that up to one-third of the validators may behave maliciously. **Filtering Mechanisms** To mitigate the impact of malicious validators, the highest `F` failure reports are excluded in CFS calculations. This ensures that the actions of a few Byzantine nodes do not distort the evaluation of honest candidates. **Robust Scoring Algorithms** VRank's design ensures that honest nodes are not unfairly penalized due to the actions of Byzantine nodes. ### Importance of the 500ms Deadline **Ensuring Consensus Responsiveness** The **500ms** deadline for `CANDIDATE_MSG_TIMEOUT` ensures that candidates respond promptly, supporting the network's goal of generating blocks every second. **Regional Centralization** Candidate-to-validator latency depends on distance: candidates near the validator cluster (where most validators are located) observe shorter latency; those farther away observe longer latency. A short timeout would favor candidates collocated with the validator majority and effectively exclude those at greater distance, reinforcing regional concentration. This carries significant risks: (a) a regional network outage could affect a large fraction of the validator set, and (b) operators outside the cluster face a higher barrier to participation. A longer timeout (e.g., 500ms) allows candidates farther from the cluster to participate, improving decentralization and resilience. **Block Time Impact** A longer timeout does not necessarily slow block production. Block progression is driven by the proposer's Istanbul Preprepare being sent and committed on time; `VRankCandidate` is an auxiliary evaluation message collected in parallel. The 500ms window accounts for global network latency variations without unfairly penalizing distant candidates, while the primary consensus path remains unaffected. **Design Choice** Given that regional centralization poses a greater risk than the marginal impact of a 500ms evaluation window, the design favors a longer timeout to support geographic diversity. ### The omission of signatures in cfReport If we required valid `VRankCandidate` messages (with signatures) to be included in `cfReport`, then each entry would need a verifiable signature. However, the proposer has the authority to include any candidate in `cfReport` regardless. A malicious proposer could intentionally omit a candidate's valid signature and claim that the candidate did not send any message—thereby falsely penalizing an honest candidate (a **false positive**). Including signatures would block false negatives (a proposer could not falsely claim a candidate failed when they actually sent a valid message). However, if the proposer is an accomplice of the candidate, they could collude to omit the candidate from `cfReport` even when the candidate failed—bypassing the signature check. Given that signatures cannot fully prevent manipulation in either direction, and that signatures add significant size to the report, we decided to simplify: `cfReport` is a list of candidate addresses only (no signatures). The Byzantine filtering in CFS (excluding the highest `F` reporter totals) mitigates the impact of malicious proposers. ### The exclusion of pfReport from header.VRank `pfReport` is extracted from `header.Extra` rather than stored in `header.VRank`. Round-change information is recorded during consensus, before the block is finalized. If `pfReport` were written into `header.VRank` upon each round change, the header would need to be updated mid-consensus. Supporting such updates would require substantial changes to the current implementation. The `Extra` field is already populated during consensus with round-change data, so `pfReport` is derived from there instead. ### Empty `CfReport(k*EPOCH_LENGTH)` The validator set changes every `EPOCH_LENGTH`, so there may be new validators at block `k*EPOCH_LENGTH` that were not validators at block `k*EPOCH_LENGTH - 1`. Those new validators did not participate in consensus for block `k*EPOCH_LENGTH - 1` and therefore could not have collected `VRankCandidate` messages. The proposer of block `k*EPOCH_LENGTH` may be such a new validator, so they cannot produce a valid `cfReport(k*EPOCH_LENGTH)`. Hence the `vrank` field in the header at `k*EPOCH_LENGTH` MUST be `nil`. ## Backward Compatibility The introduction of VRank does not affect existing nodes before `FORK_BLOCK`. Nodes operating prior to `FORK_BLOCK` will continue to function as before. After `FORK_BLOCK`, the new `vrank` field and associated validation processes come into effect. ## Security Considerations ### Handling Byzantine Nodes **Assumption of One-Third Malicious Validators** We accept the standard Byzantine fault tolerance assumption that up to one-third of validators may behave maliciously. Kaia Chain relies on the assumption that less than one-third of participants are malicious to ensure safety and liveness. VRank's scoring mechanism is designed with this threshold in mind, allowing the network to function correctly even in the presence of some malicious actors. **Limitations and Contingencies** If the number of malicious validators exceeds one-third, the network's ability to reach consensus and maintain integrity may be compromised. **Justification for the Assumption** While it's challenging to prevent all malicious activity, assuming that up to one-third of validators could be compromised provides a practical balance between security and network performance. ## Implementation TBD ## Appendix: Node Models The following node models were considered when designing VRank and defining a stable node. They describe the philosophy behind the scoring thresholds and help clarify the types of behavior VRank aims to distinguish. VRank categorizes nodes into four models to evaluate their performance and stability: | Node | Performance | Impact | | :-------------------------------------------------- | :------------ | :-------------------------------------------------------------- | | **Uptime \> 99.5%, No network issues** | **Excellent** | **Contribute to network stability** | | **Uptime about 99.5% temporally unstable** | **Good** | **May delay block time** | | **Uptime \< 99.5%** | **Not good** | **May fail to propose a block** | | **Halts continuously regardless uptime** | **Bad** | **May affect consensus if consists of nodes experiencing this** | | **Uptime \> 99.5%, try to destabilize the network** | **N/A** | **Threat network integrity** | 1. **Node A: Stable Node** **Characteristics**: Capable of performing validation duties with optimal performance and stability. **Impact on Network**: Contributes positively to network stability and performance. 2. **Node B: Temporarily Unstable Node** **Characteristics**: Experiences brief, frequent network disruptions that last a few seconds. **Impact on Network**: May delay block creation if selected as a proposer but does not cause a round change. 3. **Node C: Intermittently Stopping Node** **Characteristics**: Experiences longer network disruptions (tens of seconds). **Impact on Network**: May fail to propose a block when selected as a proposer, resulting in round changes and significant delays. 4. **Node M: Malicious Node** **Characteristics**: Intentionally attempts to destabilize the network through malicious actions. **Impact on Network**: Threatens network security and integrity. VRank aims to mitigate the influence of such nodes. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).