docs(rfc): non-evm chain memo design standard

docs/rfc/002_standard_memo_format.md

@@ -0,0 +1,220 @@
+# A proposed standard memo format for non-EVM chains
+<br>
+
+## The goal
+
+This doc is aimed to introduce a standard format of ZetaChain inbound `memo` across non-EVM chains. The `memo` in an inbound transaction is to carry both instructions and data, by which the cross-chain transaction to be processed as expected in the `zetacore`. A standard memo format helps to ensure consistent developer experience across EVM and non-EVM chains.
+<br><br>
+
+
+## The EVM gateway inbound events
+
+We want to mimic below `Deposit` and `Called` events in the EVM `gateway` contract for non-EVM chains. Typically, we at least want the following 3 pieces at the time of writing.
+
+- The `receiver` address in ZEVM.
+- The `payload` of the call.
+- The `RevertOptions`.
+
+```
+event Deposited(
+ address indexed sender,
+ address indexed receiver,
+ uint256 amount,
+ address asset,
+ bytes payload,
+ RevertOptions revertOptions
+);
+
+event Called(
+ address indexed sender,
+ address indexed receiver,
+ bytes payload,
+ RevertOptions revertOptions
+);
+```
+<br><br>
+
+
+## 1. The Memo Diagram
+
+![](images/002_layout.png)<br><br>
+
+
+## 2. The memo structure
+
+The raw-byte representation of a standard non-EVM memo contains `9` sections (2 mandatory + 7 optional). 
+
+`Section 0` is the `header`, which controls how the memo should be interpreted.
+
+`Section 1~8` are data sections that carry actual data attached to the memo.
+
+
+| | 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)** | 4 | 20 | variable | variable | 1 | 20 | variable | -- | -- |
+| **Type** | [4]byte | ZEVM address| bytes | non-EVM address| bool | ZEVM address | bytes | -- | -- |
+| **Optional** | No | Yes | Yes | Yes | Yes | Yes | Yes | -- | -- |
+<br><br>
+
+
+## 3. The header
+
+The `4-byte` header is a self-contained declaration of the memo properties and rules. The proposed header structure is designed in a flexible manner. The data fields are all declared as optional. With `reserved` flags, new features and fields can be added in the future without breaking compatibility.
+
+### `byte-0`: Memo Identifier
+
+The ASCII code `0x5A` of letter `'Z'` is used as the identifier of the standard ZetaChain memo format. Once legacy memo is phased out, zetaclient will only accept memos beginning with `0x5A`.
+
+
+### `byte-1`: Control Byte
+
+| | bit 4 ~ 7 | bit 0 ~ 3 |
+|-----------------|------------------------------------------------|--------------------------------------|
+| **Name** | version # | encoding format |
+| **Optional** | No (0b0000 for now) | No (0b0000 or 0b0001 or 0b0010) |
+<br>
+
+
+### `byte-2`: Control Byte
+
+| | bit 4 ~ 7 | bit 0 ~ 3 |
+|-----------------|------------------------------------------------|--------------------------------|
+| **Name** | operation code | control bytes reserved |
+| **Optional** | No (0b0000 or 0001 or 0010 for now) | -- |
+<br>
+
+
+
+### `byte-3`: Data Flags
+
+| | bit 7 | bit 6 | bit 5 | bit 4 | bit 3 | bit 2 | bit 1 | bit 0 |
+|-----------------|---------------|--------------|---------------|-------------------|------------------|-------------------|-----------------|------------------|
+| **Name** | flag reserved | flag reserved| flag reserved | flag CallOnRevert | flag AbortAddress| flag RevertAddress| flag Payload | flag Receiver |
+| **Optional** | -- | -- | -- | -- | Yes | Yes | Yes | Yes |
+<br>
+
+Supported `operation codes` :
+
+The `operation code` is designed for the developers to explicitly specify the intention of an inbound transaction in non-contract chains (e.g. Bitcoin, Doge, …).
+The operation code is not necessary for non-contract chains, because the method name tells the intention of the transaction.
+
+A 4-bit operation code would allow `16` operation codes at maximum.
+
+| 0b0000 | 0b0001 | 0b0010 |
+|-------------|-------------------|-------------|
+| deposit | deposit_and_call | call |
+<br>
+
+
+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.<br>
+Note: the `compact *` encoding is to minimizes length of memo data (compared to ABI) and will be explained in following sections.
+
+| 0b00 00 | 0b000 | 0b0010 |
+|--------------|----------------|--------------|
+| ABI encoded | compact short | compact long |
+<br><br>
+
+
+## 4. The types
+
+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 |
+|-----------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------|
+| **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. |
+<br><br>
+
+
+## 5. Byte layout of variable-length types
+
+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 |
+|---------------|---------------|-----------------------------------------|-----------------------------------------------|----------------------------------------------------------|
+| 0b0000 | ABI encoded | ABI encoded types | Types are packed/unpacked with ABI standard | [ABI Spec](https://docs.soliditylang.org/en/develop/abi-spec.html) |
+| 0b0001 | compact short | [1-byte length] + [data] | Carry up to 255 bytes of data. | A valid length (>= 0) must match data length. |
+| 0b0010 | compact long | [2-byte length, little-endian] + [data] | Carry up to 65535 bytes (64KB) of data. | A valid length (>= 0) must match data length. |
+|
+
+
+## 6. How to pack your inbound memo
+
+### Step-1: prepare your memo header
+
+```go
+func MakeHead() []byte {
+ header := make([]byte, 4)
+ header[0] = 'Z'
+ header[1] = 0<<4 | 0b0010 // version + encoding format (e.g. compact long)
+ header[2] = 0b0001 << 4 // operation code (e.g. DepositAndCall)
+ header[3] = 0b00000111 // receiver, payload and revertAddress are set
+ return header
+}
+```
+
+
+### Step-2: pack your memo data
+
+For use cases that requires compact transaction data, choose encoding format of `compact short` or `compact long`.
+
+```go
+func CompactPack(receiver common.Address, payload []byte, revertAddress string) []byte {
+ data := make([]byte, 0)
+
+ // pack receiver (fixed 20 bytes)
+ data = append(data, receiver.Bytes()...)
+
+ // pack payload (dynamic)
+ // encode length with 1 byte if 'compact short' is your choice
+ lenthPayload := make([]byte, 2)
+ binary.LittleEndian.PutUint16(lenthPayload, uint16(len(payload)))
+
+ data = append(data, lenthPayload...) // write length
+ data = append(data, payload...) // write payload
+
+ // pack revert address (dynamic).
+ // encode length with 1 byte if 'compact short' is your choice
+ lengthRevertAddr := make([]byte, 2)
+ binary.LittleEndian.PutUint16(lengthRevertAddr, uint16(len([]byte(revertAddress))))
+
+ data = append(data, lengthRevertAddr...) // write length
+ data = append(data, []byte(revertAddress)...) // write revert address
+
+ return data
+}
+```
+
+
+Also, ABI encoding format is another option to consider.
+
+```go
+func ABIPack(receiver common.Address, payload []byte, revertAddress string) ([]byte, error) {
+ // define the ABI for encoding the types: address, bytes, string
+ abiString := `[{"type":"function","name":"encode","inputs":[
+ {"type":"address"},
+ {"type":"bytes"},
+ {"type":"string"}],
+ "outputs":[]}]`
+
+ // parse the ABI
+ parsedABI, err := abi.JSON(strings.NewReader(abiString))
+ if err != nil {
+ return nil, err
+ }
+
+ // pack the values using the ABI
+ data, err := parsedABI.Pack("encode", receiver, payload, revertAddress)
+ if err != nil {
+ return nil, err
+ }
+
+ // remove the 4-byte selector
+ return data[4:], nil
+}
+```