From c292962e5709dfc4ed0b94e5c6f609c680fff2e7 Mon Sep 17 00:00:00 2001 From: Charlie Chen Date: Thu, 3 Oct 2024 11:42:51 -0500 Subject: [PATCH] better format doc and table; change terminology 'lite-data' to 'compact' --- changelog.md | 4 --- docs/rfc/002_standard_memo_format.md | 44 ++++++++++++++-------------- 2 files changed, 22 insertions(+), 26 deletions(-) diff --git a/changelog.md b/changelog.md index 2b0a06870e..dc83cb839b 100644 --- a/changelog.md +++ b/changelog.md @@ -48,10 +48,6 @@ * [2853](https://github.com/zeta-chain/node/pull/2853) - calling precompile through sc with sc state update * [2925](https://github.com/zeta-chain/node/pull/2925) - add recover to init chainer to diplay informative message when starting a node from block 1 -### Docs - -* [2963](https://github.com/zeta-chain/node/pull/2963) - added doc for design of non-evm chain inbound memo format. - ## v20.0.0 ### Features diff --git a/docs/rfc/002_standard_memo_format.md b/docs/rfc/002_standard_memo_format.md index feb1e4476f..46aba6f78e 100644 --- a/docs/rfc/002_standard_memo_format.md +++ b/docs/rfc/002_standard_memo_format.md @@ -1,4 +1,4 @@ -

A proposed standard memo format for non-EVM chains

+# A proposed standard memo format for non-EVM chains
## The goal @@ -26,10 +26,10 @@ event Deposited( ); event Called( - address indexed sender, - address indexed receiver, - bytes payload, - RevertOptions revertOptions + address indexed sender, + address indexed receiver, + bytes payload, + RevertOptions revertOptions ); ```

@@ -72,8 +72,9 @@ The ASCII code `0x5A` of letter `'Z'` is used as the identifier of the standard | | 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 | +| **Optional** | No (0b000 for now) | No (0b00 or 0b01 or 0b10) | for non-contract chains; Ignored for contract chains. The operation code is already differentiated by method names in contract based | +
+ ### `byte-2`: Data Flags @@ -91,23 +92,23 @@ The `operation code` is designed for the developers to explicitly specify the in | 0b000 | 0b001 | 0b010 | |------------|------------------|------------| | deposit | deposit_and_call | call | -
Supported `encoding flags`: -This flag is to tell `zetaclient` how the memo fields should be decoded. A 2-bit weight flag seems good enough and won’t change in future. +This flag is to tell `zetaclient` how the memo fields should be decoded. A 2-bit weight flag seems good enough and won’t change in future.
+Note: the `compact *` encoding is to minimizes length of memo data (compared to ABI) and will be explained in following sections. -| 0b00 | 0b01 | 0b10 | -|--------------|------------------|------------------| -| ABI encoded | lite-data short | lite-data long | +| 0b00 | 0b01 | 0b10 | +|--------------|----------------|--------------| +| ABI encoded | compact short | compact long |

## 4. The types -To decode/encode the memo fields with the lite-date format, we've defined a few types below. -To decode/encode the memo fields with ABI format, just follow the [ABI Spec](https://docs.soliditylang.org/en/develop/abi-spec.html). +To decode/encode the memo fields with `compact *` format, we've defined a few types below. +To decode/encode the memo fields with `ABI encoded` format, just follow the [ABI Spec](https://docs.soliditylang.org/en/develop/abi-spec.html). | Field | Size (byte) | Description | @@ -120,12 +121,11 @@ To decode/encode the memo fields with ABI format, just follow the [ABI Spec](htt ## 5. Byte layout of variable-length types -There are two ways to encode your the memo fields into raw bytes. The `ABI encoded` and `lite-data` encoded. - -| 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. | - +There are two ways to encode your the memo fields into raw bytes. The `ABI encoded` and `compact *` encoded. +| 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 | compact short | [1-byte length] + [data] | Carry up to 255 bytes of data. | A valid length must > 0 and match data length. | +| 0b10 | compact long | [2-byte length, little-endian] + [data] | Carry up to 65535 bytes (64KB) of data. | A valid length must > 0 and match data length. | +|