diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst index 8591a07f6..b9bdc4394 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 ======