#3961 - rewritten encoding example in a logical order instead of a sequential order

1 files changed, 44 insertions, 44 deletions

diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst
index b9bdc439..751d7713 100644
--- a/docs/abi-spec.rst
+++ b/docs/abi-spec.rst
@@ -278,40 +278,26 @@ All together, the encoding is (newline after function selector and each 32-bytes
       000000000000000000000000000000000000000000000000000000000000000d
       48656c6c6f2c20776f726c642100000000000000000000000000000000000000
 
-Applying the same principle to encode a function with a signature ``g(uint[][],string[])`` with values ``([[1, 2], [3]], ["one", "two", "three"])`` would be as follows:
+Lets apply the same principle to encode a function with a signature ``g(uint[][],string[])`` with values ``([[1, 2], [3]], ["one", "two", "three"])`` but start from the most atomic parts of the encoding:
 
-First we encode the offsets of the root dynamic arrays:
-
- - ``0x0000000000000000000000000000000000000000000000000000000000000040`` (64 bytes offset to the start of the content of the first root dynamic array ``[[1, 2], [3]]``)
- - ``0x0000000000000000000000000000000000000000000000000000000000000140`` (320 bytes offset to the start of the content of the second root dynamic array ``["one", "two", "three"]``)
-
-Then we encode the length and data of the first root array which is simultaneously an encoding of offsets of dynamic arrays it holds:
-
- - ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements in the first root array, 2; the elements themselves are ``[1, 2]``  and ``[3]``)
- - ``0x0000000000000000000000000000000000000000000000000000000000000040`` (64 bytes offset to the start of the content of the first embeded dynamic array ``[1, 2]``)
- - ``0x00000000000000000000000000000000000000000000000000000000000000a0`` (160 bytes offset to the start of the content of the second embeded argument ``[3]``)
-
-Note that offsets of dynamic arguments ``[1, 2]``  and ``[3]`` are computed only with respect to the start of the data block of the first root array ``[[1, 2], [3]]``. Thus it doesn't matter where those arguments are located in the overall encoding.
-
-Then we encode the length and data of the first embeded dynamic array of the first root array:
+First we encode the length and data of the first embeded dynamic array ``[1, 2]`` of the first root array ``[[1, 2], [3]]``:
 
  - ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements in the first array, 2; the elements themselves are ``1``  and ``2``)
  - ``0x0000000000000000000000000000000000000000000000000000000000000001`` (first element)
  - ``0x0000000000000000000000000000000000000000000000000000000000000002`` (second element)
 
-Then we encode the length and data of the second embeded dynamic array of the first root array:
+Then we encode the length and data of the second embeded dynamic array ``[3]`` of the first root array ``[[1, 2], [3]]``:
 
  - ``0x0000000000000000000000000000000000000000000000000000000000000001`` (number of elements in the second array, 1; the element is ``3``)
  - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (first element)
 
-Then we encode the length and data of the second root array which is simultaneously an encoding of offsets of strings it holds:
+Since ``[1, 2]`` and ``[3]`` are dynamic arrays we need to find offsets of their content from the data part of the encoding of the first root array ``[[1, 2], [3]]`` and prepend their count which is not considered for offsets:
 
- - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of strings in the second root array, 3; the strings themselves are ``"one"``, ``"two"`` and ``"three"``)
- - ``0x0000000000000000000000000000000000000000000000000000000000000060`` (96 bytes offset to the content of the first string)
- - ``0x00000000000000000000000000000000000000000000000000000000000000a0`` (160 bytes offset to the content of the second string)
- - ``0x00000000000000000000000000000000000000000000000000000000000000e0`` (224 bytes offset to the content of the thrird string)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements in the first root array, 2; the elements themselves are ``[1, 2]``  and ``[3]``)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000040`` (64 bytes offset to the start of the content of the first embeded dynamic array ``[1, 2]``)
+ - ``0x00000000000000000000000000000000000000000000000000000000000000a0`` (160 bytes offset to the start of the content of the second embeded argument ``[3]``)
 
-Finally we encode the embeded strings of the second root array:
+Then we encode the embeded strings of the second root array:
 
  - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of characters in word ``"one"``)
  - ``0x6f6e650000000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``"one"``)
@@ -320,31 +306,45 @@ Finally we encode the embeded strings of the second root array:
  - ``0x0000000000000000000000000000000000000000000000000000000000000005`` (number of characters in word ``"three"``)
  - ``0x7468726565000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``"three"``)
 
-Thus the overall encoding becomes:
+In parallel to the first root array, since strings are dynamic elements we need to find their offsets and prepend their count:
+
+ - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of strings in the second root array, 3; the strings themselves are ``"one"``, ``"two"`` and ``"three"``)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000060`` (96 bytes offset to the content of the first string)
+ - ``0x00000000000000000000000000000000000000000000000000000000000000a0`` (160 bytes offset to the content of the second string)
+ - ``0x00000000000000000000000000000000000000000000000000000000000000e0`` (224 bytes offset to the content of the thrird string)
+
+Note that encodings of the embeded elements of the root arrays are not dependent on each other and would have the same encodings for a fuction with a signature ``g(string[],uint[][])``.
+
+Finally we can count the offsets to the content of the root dynamic arrays ``[[1, 2], [3]]`` and ``["one", "two", "three"]``:
+
+ - ``0x0000000000000000000000000000000000000000000000000000000000000040`` (64 bytes offset to the start of the content of the first root dynamic array ``[[1, 2], [3]]``)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000140`` (320 bytes offset to the start of the content of the second root dynamic array ``["one", "two", "three"]``)
+
+Now we can assemble parts in the correct order ending up with: 
 
 ::
 
-	0x2289b18c
-	  0000000000000000000000000000000000000000000000000000000000000040
-	  0000000000000000000000000000000000000000000000000000000000000140
-	  0000000000000000000000000000000000000000000000000000000000000002
-	  0000000000000000000000000000000000000000000000000000000000000040
-	  00000000000000000000000000000000000000000000000000000000000000a0
-	  0000000000000000000000000000000000000000000000000000000000000002
-	  0000000000000000000000000000000000000000000000000000000000000001
-	  0000000000000000000000000000000000000000000000000000000000000002
-	  0000000000000000000000000000000000000000000000000000000000000001
-	  0000000000000000000000000000000000000000000000000000000000000003
-	  0000000000000000000000000000000000000000000000000000000000000003
-	  0000000000000000000000000000000000000000000000000000000000000060
-	  00000000000000000000000000000000000000000000000000000000000000a0
-	  00000000000000000000000000000000000000000000000000000000000000e0
-	  0000000000000000000000000000000000000000000000000000000000000003
-	  6f6e650000000000000000000000000000000000000000000000000000000000
-	  0000000000000000000000000000000000000000000000000000000000000003
-	  74776f0000000000000000000000000000000000000000000000000000000000
-	  0000000000000000000000000000000000000000000000000000000000000005
-	  7468726565000000000000000000000000000000000000000000000000000000
+	0x2289b18c                                                         - function signature
+	  0000000000000000000000000000000000000000000000000000000000000040 - offset of [[1, 2], [3]]
+	  0000000000000000000000000000000000000000000000000000000000000140 - offset of ["one", "two", "three"]
+	  0000000000000000000000000000000000000000000000000000000000000002 - count for [[1, 2], [3]]
+	  0000000000000000000000000000000000000000000000000000000000000040 - offset of [1, 2]
+	  00000000000000000000000000000000000000000000000000000000000000a0 - offset of [3]
+	  0000000000000000000000000000000000000000000000000000000000000002 - count for [1, 2]
+	  0000000000000000000000000000000000000000000000000000000000000001 - encoding of 1
+	  0000000000000000000000000000000000000000000000000000000000000002 - encoding of 2
+	  0000000000000000000000000000000000000000000000000000000000000001 - count for [3]
+	  0000000000000000000000000000000000000000000000000000000000000003 - encoding of 3
+	  0000000000000000000000000000000000000000000000000000000000000003 - count for ["one", "two", "three"]
+	  0000000000000000000000000000000000000000000000000000000000000060 - offset for "one"
+	  00000000000000000000000000000000000000000000000000000000000000a0 - offset for "two"
+	  00000000000000000000000000000000000000000000000000000000000000e0 - offset for "three"
+	  0000000000000000000000000000000000000000000000000000000000000003 - count for "one"
+	  6f6e650000000000000000000000000000000000000000000000000000000000 - encoding of "one"
+	  0000000000000000000000000000000000000000000000000000000000000003 - count for "two"
+	  74776f0000000000000000000000000000000000000000000000000000000000 - encoding of "two"
+	  0000000000000000000000000000000000000000000000000000000000000005 - count for "three"
+	  7468726565000000000000000000000000000000000000000000000000000000 - encoding of "three"
 
 Events
 ======