Crate serlp

A (de)serializer for RLP encoding in ETH

Not Supported Types

• bool
• float numbers
• maps
• enum (only deserialize)

We do not support enum when deserializing because we lost some information (i.e. variant //! index) about the original value when serializing.

We have to choose this approach because there is no enums in Golang while ETH is written in go. Treating enums as a transparent layer can make our furture implementation compatiable with ETH.

Design principle

Accroding to the ETH Yellow Paper, all supported data structure can be represented with either recursive list of byte arrays or byte arrays . So we can transform all Rust’s compound types, for example, tuple, struct and list, into lists. And then encode them as exactly described in the paper

For example, the structure in test::test_embeded_struct, can be internally treated as the following form:

[
    "This is a tooooooooooooo loooooooooooooooooooong tag", 
    [
        114514, 
        [191, -9810], 
        [
            [[], [[]], [[], [[]]]]
        ]
    ], 
    "哼.啊啊啊啊啊啊啊啊啊啊啊啊啊啊啊啊啊啊"
]

ZST serialization

In Rust, we can represent ‘empty’ in many ways, for example:

[], (), "", b"", struct Empty, Variant::Empty, None, PhantomData<T>

In out implementation:

1. [] and () are considered empty list, thus should be serialized into 0xc0
2. All other ZSTs are considered empty, thus should be serialized into 0x80

To better understand ZSTs’ behavior when serializing, try this code:

#[test]
fn test_compound_zst() {
    #[derive(Serialize, Debug, PartialEq, Eq)]
    struct ZST;
 
    #[derive(Serialize, Debug, PartialEq, Eq)]
    enum Simple {
        Empty(ZST),
        #[allow(dead_code)]
        Int((u32, u64))
    }
 
    #[derive(Serialize, Debug, PartialEq, Eq)]
    struct ContainZST(Simple);
 
    #[derive(Serialize, Debug, PartialEq, Eq)]
    struct StructZST {
        zst: Simple
    }
 
    let zst = Simple::Empty(ZST);
    let zst_res = to_bytes(&zst).unwrap();
    assert_eq!(zst_res, [0x80]);
 
    let with_zst = ContainZST(Simple::Empty(ZST));
    let with_zst_res = to_bytes(&with_zst).unwrap();
    // the container is transparent because its a newtype
    assert_eq!(with_zst_res, [0x80]);
     
    let with_zst = StructZST { zst: Simple::Empty(ZST) };
    let with_zst_res = to_bytes(&with_zst).unwrap();
    // the container is a list, to this is equivlent to [""]
    assert_eq!(with_zst_res, [0xc1, 0x80]);
    }

RLP Proxy

We have a RlpProxy struct that implemented Deserialize trait, which just stores the original rlp encoded data after deserialization (no matter what type it is). You can gain more control over the deserialization process with it. Check out de::RlpProxy to find more about it.

(de)serializers for frequently used types

We provide two (de)serializers for frequently used types in blockchain.

• biguint for num_bigint::BigUint
• byte_array for [u8; N]

Put #[serde(with = "biguint")] or #[serde(with = "byte_array")] before your struct field to use them.

Modules

de

A recursive deserializer, theoritically this is more efficient than the tree based one, because all data are decoded only when needed and accessed only once.

error

rlp

ser

types