Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update 0051-ckb2023.md #429

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update 0051-ckb2023.md #429

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions rfcs/0051-ckb2023/0051-ckb2023.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ Created: 2023-04-17

# CKB Consensus Change (Edition CKB2023)

The current edition of CKB consensus rules is CKB2021. CKB2023 refers to the new edition of CKB consensus rules after its second hardfork, The purpose of a hard fork is to upgrade and update the rules encoded in the network. The changes are not backward compatible. This document outlines the changes in this upgrade.
The current edition of CKB consensus rules is CKB2021. CKB2023 refers to the new edition of CKB consensus rules after the network's second hardfork, the purpose of a hard fork is to upgrade and update the rules encoded in the network. The changes are not backward compatible. This document outlines the changes in this upgrade.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CKB2023 refers to the new edition of CKB consensus rules after the network's second hardfork, the purpose of a hard fork is to upgrade and update the rules encoded in the network.

This is a run-on sentence. The spelling of "hard fork" is used inconsistently as one and two words.

Suggestion:

CKB2023 refers to the new edition of CKB consensus rules after the network's second hard fork. The purpose of a hard fork is to upgrade and update the rules encoded in the network.


## What's in CKB2023
CKB2023 will bring significant changes to the consensus rules, these changes include the removal of the reservation rule on version field in the block header, the introduction of a new version of the virtual machine (VM) with new syscalls and standard extensions, and the optimization of performance with new mops. This RFC provides a detailed overview of these changes.
CKB2023 will bring significant changes to CKB's consensus rules: these changes include the removal of the reservation rule on version field in the block header, the introduction of a new version of the virtual machine (VM) with new syscalls and standard extensions, and the optimization of performance with new MOPs. This RFC provides a detailed overview of these changes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CKB2023 will bring significant changes to CKB's consensus rules: these changes include the removal of the reservation rule on version field in the block header, the introduction of a new version of the virtual machine (VM) with new syscalls and standard extensions, and the optimization of performance with new MOPs.

The sentence structure after the colon reads as if it was not intended to be used with a colon.

This RFC provides a detailed overview of these changes.

This is redundant from the intro paragraph.

Suggestion:

CKB2023 will bring significant changes to CKB's consensus rules. These changes include:

  • Removal of the reservation rule on the version field in the block header.
  • Introduction of CKB-VM v2, which includes new syscalls and standard extensions.
  • Introduction of new MOPs to optimize performance.



### CKB VM v2
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be consistent with our spelling of "CKB-VM".

Suggestion:

CKB-VM v2


Since CKB2023, there will be multiple VM versions available. [RFC32] introduces a CKB VM version mechanism. It piggybacks on the `hash_type` field in the Script structure.
Once CKB2023 is activated, there will be multiple VM versions available. [RFC32] introduces a CKB VM version mechanism. It piggybacks on the `hash_type` field in the Script structure.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once CKB2023 is activated, there will be multiple VM versions available. [RFC32] introduces a CKB VM version mechanism. It piggybacks on the hash_type field in the Script structure.

Could be worded better for clarity. Multiple versions of the VM already exist. RFC32 should be linked. Usage of hash_type should be explained better if it is mentioned. We need to be consistent with how CKB-VM is spelled: "CKB VM" vs "CKB-VM".

Note: Our presented naming of linked RFC documents is inconsistent throughout our documents: "RFC32" vs "RFC0032".

Suggestion:

Once CKB2023 is activated, CKB-VM v2 will be available for developers to use with their scripts. This is in addition to CKB-VM v0 and CKB-VM v1 which are already available. RFC0032 describes how the hash_type field of a Script structure is used to select the version of CKB-VM that is used for script execution.


| `hash_type` | JSON representation | matches by | VM version |
| ----------- | ---------- | ---------------- | ---------- |
Expand All @@ -26,37 +26,37 @@ Since CKB2023, there will be multiple VM versions available. [RFC32] introduces
| 4 | "data2" | data hash | 2 |


[RFC0049] introduces what's new in CKB VM v2 and [RFC0050] adds new syscalls for VM v2.
[RFC0049] specifies the changes made in CKB VM v2 and [RFC0050] adds new syscalls for VM v2.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[RFC0049] specifies the changes made in CKB VM v2 and [RFC0050] adds new syscalls for VM v2.

Links should be added for referenced documents.

Suggestion:

RFC0049 specifies the changes made in CKB-VM v2 and RFC0050 adds new syscalls for CKB-VM v2.


CKB VM v2 bring the following features:
CKB VM v2 brings the following features:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CKB VM v2 brings the following features:

We should be consistent with the spelling of "CKB-VM".

Suggestion:

CKB-VM v2 brings the following features:


* New syscalls Spawn, Get Memory Limit, Set Content will be added. The syscall Spawn is the core part of this update. The Spawn and the latter two syscalls: Get Memory Limit and Set Content together, implement a way to call another CKB Script in a CKB Script. Unlike the Exec syscall, Spawn saves the execution context of the current script, like posix_spawn, the parent script blocks until the child script ends.
* [“A” Standard Extension](https://five-embeddev.com/riscv-isa-manual/latest/a.html), strictly speaking “A” Standard Extension in ckb-vm does not bring functional changes, but many existing code will be compiled with Atomic Instructions and need to be patched, while ckb-vm can implement A instructions to eliminate such work. For example, in CKB VM v2, if you write a script with rust, you can now use [log](https://crates.io/crates/log) crate directly.
* Introduce more [macro-op fusion](https://en.wikichip.org/wiki/macro-operation_fusion) to reduce cycles consumption of scripts.
* New syscalls Spawn, Get Memory Limit, Set Content will be added. The syscall Spawn is the core part of this update. Together, the Spawn and the latter two syscalls: Get Memory Limit and Set Content, implement a way to call another CKB Script from within a CKB Script. Unlike the Exec syscall, Spawn saves the execution context of the current script, and, like posix_spawn, the parent script blocks until the child script ends.
Copy link
Contributor

@jordanmack jordanmack Jan 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • New syscalls Spawn, Get Memory Limit, Set Content will be added. The syscall Spawn is the core part of this update. Together, the Spawn and the latter two syscalls: Get Memory Limit and Set Content, implement a way to call another CKB Script from within a CKB Script. Unlike the Exec syscall, Spawn saves the execution context of the current script, and, like posix_spawn, the parent script blocks until the child script ends.

Suggestion:

  • Five new syscalls will be added: Spawn, Set Content, Get Memory Limit, Current Memory, and Load Block Extension. The Spawn and Set Content syscalls are used together to provide a new method for a script to call another script during execution. The Spawn syscall saves the execution context of the currently running script and executes a child script. It blocks until the child script has finished executing, then resumes execution of the parent. This is unlike the currently available Exec syscall, which does not return to the parent and is much more similar to the posix_spawn syscall available in POSIX operating systems.
  • The RISC-V A Standard Extension will be added to provide atomic instructions in CKB-VM v2. These instructions are highly beneficial operations related to concurrency. Their inclusion makes CKB-VM v2 more compatible with existing Rust crates without the need for patching or other workarounds. For example, in CKB-VM v2, you can now use the log crate, which was not possible previously without patching.
  • Additional Macro-Operation Fusion optimizations will be introduced in CKB-VM v2. This will further reduce the cycle consumption of executing scripts, allowing for more complex functionality on the same hardware.

* [“A” Standard Extension](https://five-embeddev.com/riscv-isa-manual/latest/a.html), strictly speaking, introducing the “A” Standard Extension in ckb-vm does not bring functional changes, however, while it was previously for code to be compiled with Atomic Instructions and then patched to run on ckb-vm, ckb-vm v2 implements A instructions to eliminate such work. For example, in CKB VM v2, if you write a script with Rust, you can now use the [log](https://crates.io/crates/log) crate directly.
* Introduces more [macro-op fusion](https://en.wikichip.org/wiki/macro-operation_fusion) to reduce cycles consumption of scripts.


### Remove Block Header Version Reservation Rule

In CKB2021, the version field of the block header is reserved and only allowed to be 0. In the 2023 edition this reservation will be removed to allow for the use of [RFC0043]
In CKB2021, the version field of the block header is reserved and only allowed to be 0. In the 2023 edition this reservation will be removed to allow for the use of [RFC0043 - CKB Soft Fork Activation].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In CKB2021, the version field of the block header is reserved and only allowed to be 0. In the 2023 edition this reservation will be removed to allow for the use of [RFC0043 - CKB Soft Fork Activation].

We should link to documents whenever possible.

Note: We are not consistent in our spelling of "soft fork". Two words seems to be more popular industry wide. RFC0043 is using one word.

Suggestion:

In CKB2021, the version field of the block header is reserved and only allowed to be 0. In the 2023 edition this reservation will be removed to allow for the use of RFC0043 - CKB Soft Fork Activation.


## CKB2023 Timeline

The mainnet upgrade is divided into three phases.

* **Stage 1 - Code Preview**: An RC version of 0.200.0 is ready for preview on June 30 2023 via nervosnetwork/ckb [releases](https://github.com/nervosnetwork/ckb/releases). It will introduce the incompatible changes to help developers to adapt their tools and apps to CKB2023. But this version does not activate the consensus incompatible changes in CKB2023. Developers can test the new rules by running a dev chain locally.
* **Stage 1 - Code Preview**: An RC version of 0.200.0 is ready for preview on June 30 2023 via nervosnetwork/ckb [releases](https://github.com/nervosnetwork/ckb/releases). It introduces the breaking changes to help developers to adapt their tools and apps to CKB2023. But this version does not activate the consensus incompatible changes in CKB2023. Developers can test the new rules by running a dev chain locally.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Stage 1 - Code Preview: An RC version of 0.200.0 is ready for preview on June 30 2023 via nervosnetwork/ckb releases. It introduces the breaking changes to help developers to adapt their tools and apps to CKB2023. But this version does not activate the consensus incompatible changes in CKB2023. Developers can test the new rules by running a dev chain locally.

Suggestion:

  • Stage 1 - Code Preview: An early RC version of v0.200.0 will be released on June 30, 2023 via the CKB Releases page. This version does not activate the CKB2023 consensus changes, but does include all breaking changes to interfaces. This release is intended to aid tooling developers in updating for compatibility using local dev chain without having to wait for the Testnet hard fork.


* **Stage 2 - Testnet Activation**:

* **Stage 3 - Mainnet Activation**:

## Upgrade Strategies

First, the SDK, Tool, and dApps authors must adapt to any 0.200.0 rc version.
First, all SDK, Tool, and dApps authors must adapt to any 0.200.0 rc version.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First, all SDK, Tool, and dApps authors must adapt to any 0.200.0 rc version.

Suggestion:

All developers of SDKs, tooling, and dApps should install a local devnet running RC version v0.200.0. This will allow the software to be updated for compatibility before the testnet and mainnet forks.


There are two strategies for ecosystem developers to upgrade to the CKB2023 consensus. Choose the former one if the developers can pause the app during the fork activation, otherwise, use the latter one.
There are two strategies for ecosystem developers to upgrade to the CKB2023 consensus. Choose the former one if it is possible for a developer to pause the app during the fork activation, otherwise, use the latter one.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are two strategies for ecosystem developers to upgrade to the CKB2023 consensus. Choose the former one if it is possible for a developer to pause the app during the fork activation, otherwise, use the latter one.

Add additional description for clarity.

Suggestion:

There are two general upgrade strategies that are recommended for developers that have live projects running in the ecosystem.

  • If your project can be taken offline for upgrades during the hard fork, this may be a more simple and straightforward way to make updates. Prepare a second version of your project, ensuring it is CKB2023 compatible, well in advance of the hard fork. When the CKB2023 hard fork is near, take your project offline and post a notice to your users that service will be resumed after the hard fork. After the hard fork occurs, perform your updates and do final testing, then put the site back online and resume service for your users.
  • If you have a project that cannot be taken offline, then you will need to use a more advanced feature toggle strategy. Ready and deploy a new version of your project that is compatible with the current version and the CKB2023 version, then use a switch that can enable the compatibility changes as soon as the hard fork is activated. When the chain reaches the CKB2023 activation epoch, automatically enable the changes needed to keep the project running properly.

The CKB2023 activation epoch for the testnet and mainnet can be found using the get_consensus` RPC call on v0.200.0 or higher.


- Release two different versions or use the feature switcher. Manually deploy the newer version or enable the feature CKB2023 after the fork activation.
- Use feature switcher and enable the feature CKB2023 automatically when the chain grows into the activation epoch. The activation epoch is different in the testnet and the mainnet, which is available via the updated `get_consensus` RPC.
- Use feature switcher and enable the feature CKB2023 automatically when the chain reaches the activation epoch. The activation epoch is different in the testnet and the mainnet, which is available via the updated `get_consensus` RPC.

## Appendix

Expand Down