#3961 - added an example of abi encoding of a function with two-dimensional dynamic arrays

1 files changed, 68 insertions, 0 deletions

diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst
index 8591a07f..b9bdc439 100644
--- a/docs/abi-spec.rst
+++ b/docs/abi-spec.rst
@@ -278,6 +278,74 @@ 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:
+
+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:
+
+ - ``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:
+
+ - ``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:
+
+ - ``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)
+
+Finally we encode the embeded strings of the second root array:
+
+ - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of characters in word ``"one"``)
+ - ``0x6f6e650000000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``"one"``)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of characters in word ``"two"``)
+ - ``0x74776f0000000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``"two"``)
+ - ``0x0000000000000000000000000000000000000000000000000000000000000005`` (number of characters in word ``"three"``)
+ - ``0x7468726565000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``"three"``)
+
+Thus the overall encoding becomes:
+
+::
+
+	0x2289b18c
+	  0000000000000000000000000000000000000000000000000000000000000040
+	  0000000000000000000000000000000000000000000000000000000000000140
+	  0000000000000000000000000000000000000000000000000000000000000002
+	  0000000000000000000000000000000000000000000000000000000000000040
+	  00000000000000000000000000000000000000000000000000000000000000a0
+	  0000000000000000000000000000000000000000000000000000000000000002
+	  0000000000000000000000000000000000000000000000000000000000000001
+	  0000000000000000000000000000000000000000000000000000000000000002
+	  0000000000000000000000000000000000000000000000000000000000000001
+	  0000000000000000000000000000000000000000000000000000000000000003
+	  0000000000000000000000000000000000000000000000000000000000000003
+	  0000000000000000000000000000000000000000000000000000000000000060
+	  00000000000000000000000000000000000000000000000000000000000000a0
+	  00000000000000000000000000000000000000000000000000000000000000e0
+	  0000000000000000000000000000000000000000000000000000000000000003
+	  6f6e650000000000000000000000000000000000000000000000000000000000
+	  0000000000000000000000000000000000000000000000000000000000000003
+	  74776f0000000000000000000000000000000000000000000000000000000000
+	  0000000000000000000000000000000000000000000000000000000000000005
+	  7468726565000000000000000000000000000000000000000000000000000000
+
 Events
 ======