docs(rfc): non-evm chain memo design standard #2963
Conversation
ws4charlie
requested review from
brewmaster012,
kingpinXD,
lumtis,
skosito,
swift1337 and
fbac
as code owners
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 Walkthrough📝 Walkthrough📝 Walkthrough📝 Walkthrough📝 WalkthroughWalkthroughThe changes encompass a comprehensive update to the changelog and the introduction of a proposed standard memo format for non-EVM chains. Key features include support for stateful precompiled contracts, enhancements to staking and bank precompiled contracts, and the integration of multiple Bitcoin chains. Additionally, the documentation outlines a structured memo format aimed at improving cross-chain transaction interoperability, detailing its structure, operation codes, and encoding specifications. Changes
Possibly related PRs
Suggested labels
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (7)
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md (7)
1-7: Utilize Markdown syntax for document titleThe document title is currently formatted using HTML. For consistency with Markdown conventions, consider replacing the HTML syntax with Markdown equivalent.
Replace the HTML-formatted title with the following Markdown syntax:
-<h1 style="text-align: center;">A proposed standard memo format for non-EVM chains</h1> +# A proposed standard memo format for non-EVM chainsThe goal section effectively outlines the purpose of the standard memo format, providing clear context for the document.
9-34: Specify language for code blocksThe content in this section effectively describes the events to be mimicked for non-EVM chains. However, the code blocks lack language specification.
Enhance the code block formatting by specifying the language. For example:
-``` +```solidity event Deposited( address indexed sender, address indexed receiver, uint256 amount, address asset, bytes payload, RevertOptions revertOptions );Apply this change to both code blocks in this section.
🧰 Tools
🪛 Markdownlint
29-29: Column: 1
Hard tabs(MD010, no-hard-tabs)
30-30: Column: 1
Hard tabs(MD010, no-hard-tabs)
31-31: Column: 1
Hard tabs(MD010, no-hard-tabs)
32-32: Column: 1
Hard tabs(MD010, no-hard-tabs)
18-18: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
38-40: Add alt text to the memo diagramThe memo diagram is a crucial visual aid for understanding the memo structure. However, it lacks alt text, which is important for accessibility and SEO.
Enhance the image by adding descriptive alt text:
-<br><br> +<br><br>🧰 Tools
🪛 Markdownlint
40-40: null
Images should have alternate text (alt text)(MD045, no-alt-text)
43-58: Improve table formatting in memo structure sectionThe memo structure section provides a clear and informative breakdown of the 9 sections in the standard non-EVM memo. The table effectively summarizes the key details of each section.
To enhance the table's readability and adhere to Markdown best practices, consider the following formatting improvements:
- Add leading and trailing pipes to each row.
- Ensure consistent column alignment.
Apply these changes to the table:
-| | Section 0 | Section 1 | Section 2 | Section 3 | Section 4 | Section 5 | Section 6 | Section 7 | Section 8 | -|-----------------|------------|-------------|-------------|----------------|--------------|--------------|---------------|-------------|-------------| -| **Name** | Header | Receiver | Payload | RevertAddress | CallOnRevert | AbortAddress | RevertMessage | reserved | reserved | -| **Size (byte)** | 3 | 20 | variable | variable | 1 | 20 | variable | -- | -- | -| **Type** | [3]byte | ZEVM address| bytes | non-EVM address| bool | ZEVM address | bytes | -- | -- | -| **Optional** | No | No | Yes | Yes | Yes | Yes | Yes | -- | -- | +| Section | Section 0 | Section 1 | Section 2 | Section 3 | Section 4 | Section 5 | Section 6 | Section 7 | Section 8 | +|-----------------|------------|-------------|-------------|----------------|--------------|--------------|---------------|-------------|-------------| +| **Name** | Header | Receiver | Payload | RevertAddress | CallOnRevert | AbortAddress | RevertMessage | reserved | reserved | +| **Size (byte)** | 3 | 20 | variable | variable | 1 | 20 | variable | -- | -- | +| **Type** | [3]byte | ZEVM address| bytes | non-EVM address| bool | ZEVM address | bytes | -- | -- | +| **Optional** | No | No | Yes | Yes | Yes | Yes | Yes | -- | -- |🧰 Tools
🪛 Markdownlint
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: 10; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
61-104: Enhance table formatting in the header sectionThe header section provides a comprehensive breakdown of the 3-byte header structure, offering detailed information about each byte's purpose and encoding.
To improve readability and consistency, apply the following formatting changes to the tables:
- Add leading and trailing pipes to each row.
- Ensure consistent column alignment.
- Use a consistent style for empty cells (e.g.,
--or leave blank).Apply these changes to the tables in this section. For example:
-| | bit 5 ~ 7 | bit 3 ~ 4 | bit 0 ~ 2 | -|-----------------|---------------------------------|--------------------------------|----------------------------------------------------------| -| **Name** | version # | encoding flag | operation code | -| | | | No for non-contract chains; Ignored for contract chains | -| **Optional** | No (0b000 for now) | No (0b00 or 0b01 or 0b10) | The operation code is already differentiated by method names in contract based chains | +| Field | bit 5 ~ 7 | bit 3 ~ 4 | bit 0 ~ 2 | +|-----------------|---------------------------------|--------------------------------|----------------------------------------------------------| +| **Name** | version # | encoding flag | operation code | +| **Description** | -- | -- | No for non-contract chains; Ignored for contract chains | +| **Optional** | No (0b000 for now) | No (0b00 or 0b01 or 0b10) | The operation code is already differentiated by method names in contract-based chains |Apply similar formatting improvements to the other tables in this section.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~65-~65: Loose punctuation mark.
Context: ...ut breaking compatibility. ###byte-0: Memo Identifier The ASCII code0x5A...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~67-~67: Possible missing article found.
Context: ...mo Identifier The ASCII code0x5Aof letter'Z'is used as the identifier of the ...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...os beginning with0x5A. ###byte-1: Control Byte | | bit 5...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~76-~76: This expression is usually spelled with a hyphen.
Context: ...ready differentiated by method names in contract based chains | ###byte-2: Data Flags | ...(BASED_HYPHEN)
[uncategorized] ~79-~79: Loose punctuation mark.
Context: ...n contract based chains | ###byte-2: Data Flags | | bit 7 ...(UNLIKELY_OPENING_PUNCTUATION)
[locale-violation] ~99-~99: The phrase ‘in future’ is British English. Did you mean: “in the future”?
Context: ...flag seems good enough and won’t change in future. | 0b00 | 0b01 | 0...(IN_FUTURE)
🪛 Markdownlint
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
107-118: Refine table formatting in the types sectionThe types section effectively defines the types used for decoding/encoding memo fields, providing clear descriptions for each type.
To enhance readability and consistency, apply the following formatting changes to the table:
- Add leading and trailing pipes to each row.
- Ensure consistent column alignment.
Apply these changes to the table:
-| Field | Size (byte) | Description | -|-----------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------| -| **ZEVM address** | fixed, 20 | The raw bytes representation of a ZEVM address. ZEVM address is the same as standard Ethereum address. | -| **non-EVM address** | variable | The raw bytes representation of a non-EVM external chain address. Different addresses have different lengths, e.g., Bitcoin vs Solana; Bitcoin Segwit vs Legacy. | -| **bytes** | variable | The raw bytes of arbitrary data. | +| Field | Size (byte) | Description | +|-----------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------| +| **ZEVM address** | fixed, 20 | The raw bytes representation of a ZEVM address. ZEVM address is the same as standard Ethereum address. | +| **non-EVM address** | variable | The raw bytes representation of a non-EVM external chain address. Different addresses have different lengths, e.g., Bitcoin vs Solana; Bitcoin Segwit vs Legacy. | +| **bytes** | variable | The raw bytes of arbitrary data. |🧰 Tools
🪛 Markdownlint
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
121-131: Enhance table formatting in the byte layout sectionThe byte layout section effectively describes the two methods for encoding memo fields into raw bytes, providing clear details for each format.
To improve readability and consistency, apply the following formatting changes to the table:
- Add leading and trailing pipes to each row.
- Ensure consistent column alignment.
Apply these changes to the table:
-| Decoding flag | Format | Layout | Description | Rule | -|---------------|-------------------|-----------------------------------------|-----------------------------------------------|----------------------------------------------------------| -| 0b00 | ABI encoded | ABI encoded types | Types are packed/unpacked with ABI standard | [ABI Spec](https://docs.soliditylang.org/en/develop/abi-spec.html) | -| 0b01 | lite-data short | [1-byte length] + [data] | Carry up to 255 bytes of data. | A valid length must > 0 and match data length. | -| 0b10 | lite-data long | [2-byte length, little-endian] + [data] | Carry up to 65535 bytes (64KB) of data. | A valid length must > 0 and match data length. | +| Decoding flag | Format | Layout | Description | Rule | +|---------------|-------------------|-----------------------------------------|-----------------------------------------------|----------------------------------------------------------| +| 0b00 | ABI encoded | ABI encoded types | Types are packed/unpacked with ABI standard | [ABI Spec](https://docs.soliditylang.org/en/develop/abi-spec.html) | +| 0b01 | lite-data short | [1-byte length] + [data] | Carry up to 255 bytes of data. | A valid length must > 0 and match data length. | +| 0b10 | lite-data long | [2-byte length, little-endian] + [data] | Carry up to 65535 bytes (64KB) of data. | A valid length must > 0 and match data length. |
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
⛔ Files ignored due to path filters (1)
docs/design-proposals/non_evm_inbound_memo/layout.pngis excluded by!**/*.png
📒 Files selected for processing (2)
- changelog.md (1 hunks)
- docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md (1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
[uncategorized] ~65-~65: Loose punctuation mark.
Context: ...ut breaking compatibility. ###byte-0: Memo Identifier The ASCII code0x5A...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~67-~67: Possible missing article found.
Context: ...mo Identifier The ASCII code0x5Aof letter'Z'is used as the identifier of the ...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...os beginning with0x5A. ###byte-1: Control Byte | | bit 5...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~76-~76: This expression is usually spelled with a hyphen.
Context: ...ready differentiated by method names in contract based chains | ###byte-2: Data Flags | ...(BASED_HYPHEN)
[uncategorized] ~79-~79: Loose punctuation mark.
Context: ...n contract based chains | ###byte-2: Data Flags | | bit 7 ...(UNLIKELY_OPENING_PUNCTUATION)
[locale-violation] ~99-~99: The phrase ‘in future’ is British English. Did you mean: “in the future”?
Context: ...flag seems good enough and won’t change in future. | 0b00 | 0b01 | 0...(IN_FUTURE)
🪛 Markdownlint
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
29-29: Column: 1
Hard tabs(MD010, no-hard-tabs)
30-30: Column: 1
Hard tabs(MD010, no-hard-tabs)
31-31: Column: 1
Hard tabs(MD010, no-hard-tabs)
32-32: Column: 1
Hard tabs(MD010, no-hard-tabs)
18-18: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
40-40: null
Images should have alternate text (alt text)(MD045, no-alt-text)
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: 10; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
104-104: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
118-118: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
🔇 Additional comments (3)
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md (1)
1-131: Comprehensive and well-structured design proposalThis document presents a thorough and well-organized design proposal for a standard memo format for non-EVM chains. The content effectively covers all aspects of the proposed format, including:
- Clear explanation of the goal and context
- Detailed breakdown of the memo structure
- Comprehensive description of the header and its components
- Clear definition of types and encoding methods
The proposed standard memo format appears to be well-thought-out and designed to ensure consistency across different blockchain environments. This standardization is crucial for improving interoperability and developer experience in cross-chain transactions.
While minor formatting issues were identified throughout the document, addressing these will further enhance its readability and professional presentation. These improvements primarily involve consistent table formatting and proper use of Markdown syntax.
Overall, this design proposal provides a solid foundation for implementing a standardized memo format that will significantly contribute to the efficiency and reliability of cross-chain transactions in the ZetaChain ecosystem.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~65-~65: Loose punctuation mark.
Context: ...ut breaking compatibility. ###byte-0: Memo Identifier The ASCII code0x5A...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~67-~67: Possible missing article found.
Context: ...mo Identifier The ASCII code0x5Aof letter'Z'is used as the identifier of the ...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...os beginning with0x5A. ###byte-1: Control Byte | | bit 5...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~76-~76: This expression is usually spelled with a hyphen.
Context: ...ready differentiated by method names in contract based chains | ###byte-2: Data Flags | ...(BASED_HYPHEN)
[uncategorized] ~79-~79: Loose punctuation mark.
Context: ...n contract based chains | ###byte-2: Data Flags | | bit 7 ...(UNLIKELY_OPENING_PUNCTUATION)
[locale-violation] ~99-~99: The phrase ‘in future’ is British English. Did you mean: “in the future”?
Context: ...flag seems good enough and won’t change in future. | 0b00 | 0b01 | 0...(IN_FUTURE)
🪛 Markdownlint
29-29: Column: 1
Hard tabs(MD010, no-hard-tabs)
30-30: Column: 1
Hard tabs(MD010, no-hard-tabs)
31-31: Column: 1
Hard tabs(MD010, no-hard-tabs)
32-32: Column: 1
Hard tabs(MD010, no-hard-tabs)
18-18: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
40-40: null
Images should have alternate text (alt text)(MD045, no-alt-text)
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
104-104: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style(MD055, table-pipe-style)
118-118: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style(MD055, table-pipe-style)
58-58: Expected: 10; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
104-104: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
118-118: Expected: 3; Actual: 1; Too few cells, row will be missing data
Table column count(MD056, table-column-count)
changelog.md (2)
51-54: Approved: Critical fixes and improvements.The changelog for version v12.2.4 includes several important fixes that enhance the stability and security of the system. Key improvements include:
- Additional checks for external chain height verification.
- Adjustment of gas prices to buffer EIP1559 increases.
- Authorization changes for WhitelistERC20.
- Improvements to Bitcoin-related operations.
These changes address critical issues and should improve the overall reliability of the system.
56-57: Noted: Testing infrastructure improvement.The removal of the standalone network and the adoption of a require testing package for the entire node folder is a positive change. This modification should lead to more consistent and reliable tests across the project, potentially improving the overall quality of the codebase.
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
lumtis
changed the title
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
docs/design-proposals/non_evm_inbound_memo/2024_10_02_standard_memo_format.md
Outdated
Show resolved
Hide resolved
|
Converting to draft as we should not merge it for now |
|
Added a few commit to make it same organization as the other docs |
lumtis
changed the title
|
Why does this doc have an index of |
…m; add example code
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## develop #2963 +/- ##
========================================
Coverage 65.77% 65.77%
========================================
Files 398 398
Lines 22421 22421
========================================
Hits 14747 14747
Misses 6900 6900
Partials 774 774 |
| # A proposed standard memo format for non-EVM chains | ||
| <br> | ||
|
|
||
| ## The goal |
There was a problem hiding this comment.
Unrelated to this PR specifically, but I think it's useful to have a "Status: {proposed, declined, implemented}" on the RFCs.
In this case it's "proposed". In the PR actually implementing/completing the feature, you would set it to "implemented" and add a small description of any changes needed during the implementation.
Even declined RFCs should still be committed to the repo for historical reference.
There was a problem hiding this comment.
@gartnera Good idea. Do you think adding a Proposal status section at the beginning looking good? like below
Description
upload the doc Standard-non-EVM-Inbound-Memo
How Has This Been Tested?
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Refactor