Quentin@gfusee33
Guide : a comprehensive introduction to #MultiversX SC encoding 📚
If you are a smart contract developer, knowing how values are encoded (and stored) gives you superpowers when it comes to debug your contracts or interact with unknown ones
Let me introduce you to the concept of value encoding 🧵
There are two types of encoding : top encoding and nested encoding
Top encoding
This one is the most intuitive, we take the data and we simply convert it to hexadecimal, the result should always have an even number of digits so we add a leading zero when needed
"test" becomes 74657374
3 -> 03
29 -> 1d
etc...
This type of encoding is used when the value is sole, when it isn't the case we shall use nested encoding
Nested encoding : Introduction
When the value you wanna encode is wrapped into a bigger type, you shall consider nested encoding, we call the value wrapped a "nested value"
By bigger types I mean arrays, tuples, custom structs, etc...
To understand what is nested encoding, we need to see the issue with top encoding when serializing nested values
Let's take the following struct :
Encoding a value of type MyStruct is simply concatenating its fields together, now let's suppose :
first_field = 1 (or 1 in hex)
second_field = 16 (or 10 in hex)
So if we were using top encoding, the result would be 0110, we added leading zero to have an even number of digits
Let's memorize 0110 and now let's suppose :
first_field = 0 (or 0 in hex)
second_field = 272 (or 110 in hex)
By using top encoding, the result would be... 0110 too
Conclusion : using top encoding for nested values leads to ambiguities, different values can have the same result making impossible to do the inverse operation : decoding a hexadecimal
Nested encoding : how it works
Nested encoding is simply adding the size information in the encoding, the size is determined as follow : 8 bits = 1 byte = 2 digits on the hex result
Examples :
1) Nested encode the u32 value of 29
- u32 is a 32-bits signed integer, 32 bits = 4 bytes, so the result have 8 digits
- 29 in hexadecimal is 1D
Solution : 0000001D
2) Nested encode the u64 value of 29
- u64 is a 64-bits signed integer, 64 bits = 8 bytes, so the result have 16 digits
- 29 in hexadecimal is 1D
Solution : 000000000000001D
3) Nested encode the String value of "test"
- a String (or ManagedBuffer) has no predefined size, we need to append it at the start of the result
- the size is a nested encoded u32 representing the number of bytes
- "test" is 74657374 in hexadecimal, it has 8 digits so 4 bytes
- 4 is also 4 in hexadecimal, therefore the size is 00000004 (a u32 nested encoded, see the first example)
Solution : we just have to concatenate the size and the value, the result is 0000000474657374
4) Nested encode the BigUint value of 29
- a BigUint doesn't have a prefixed size, we will do the same as the example above
- 29 in hexadecimal is 1D, 2 digits = 1 byte
- the size is a u32 with value of 1, nested encoded : 00000001
Solution : we just have to concatenate the size and the value, the result is 000000011D
Nested encoding : why it solves the issue
Let's take again MyStruct, but this time we will nested encode its fields
first_field = 1 (or 0000000000000001 with nested encode)
second_field = 16 (or 0000000000000010 with nested encode)
The final encoded value is 00000000000000010000000000000010
Now let's do the same with the values that caused previously an ambiguity :
first_field = 0 (or 0000000000000000 in hex)
second_field = 272 (or 0000000000000110 in hex)
The final encoded value is 00000000000000000000000000000110
No ambiguity here since results are different!
That's it for this guide! There are some special cases but you have a good overview of how encoding works now 🔥
Feel free to RT & like 🥰
