Merge pull request #5698 from ethereum/chriseth-patch-2

[DOC] More details about packed encoding.

1 files changed, 14 insertions, 6 deletions

diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst
index 0f4a16b6..3c9dfcf9 100644
--- a/docs/abi-spec.rst
+++ b/docs/abi-spec.rst
@@ -609,7 +609,9 @@ Through ``abi.encodePacked()``, Solidity supports a non-standard packed mode whe
 - types shorter than 32 bytes are neither zero padded nor sign extended and
 - dynamic types are encoded in-place and without the length.
 
-As an example encoding ``int8, bytes1, uint16, string`` with values ``-1, 0x42, 0x2424, "Hello, world!"`` results in:
+This packed mode is mainly used for indexed event parameters.
+
+As an example, the encoding of ``int8(-1), bytes1(0x42), uint16(0x2424), string("Hello, world!")`` results in:
 
 .. code-block:: none
 
@@ -619,12 +621,18 @@ As an example encoding ``int8, bytes1, uint16, string`` with values ``-1, 0x42,
           ^^^^                           uint16(0x2424)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^ string("Hello, world!") without a length field
 
-More specifically, each statically-sized type takes as many bytes as its range has
-and dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded without
-their length field. This means that the encoding is ambiguous as soon as there are two
-dynamically-sized elements.
+More specifically:
+ - Each value type takes as many bytes as its range has.
+ - The encoding of a struct or fixed-size array is the concatenation of the
+   encoding of its members/elements without any separator or padding.
+ - Mapping members of structs are ignored as usual.
+ - Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded without
+   their length field.
+
+In general, the encoding is ambiguous as soon as there are two dynamically-sized elements,
+because of the missing length field.
 
 If padding is needed, explicit type conversions can be used: ``abi.encodePacked(uint16(0x12)) == hex"0012"``.
 
 Since packed encoding is not used when calling functions, there is no special support
-for prepending a function selector.
+for prepending a function selector. Since the encoding is ambiguous, there is no decoding function.