You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/abi-spec.rst
+66-11Lines changed: 66 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -418,10 +418,22 @@ In effect, a log entry using this ABI is described as:
418
418
419
419
- ``address``: the address of the contract (intrinsically provided by Ethereum);
420
420
- ``topics[0]``: ``keccak(EVENT_NAME+"("+EVENT_ARGS.map(canonical_type_of).join(",")+")")`` (``canonical_type_of`` is a function that simply returns the canonical type of a given argument, e.g. for ``uint indexed foo``, it would return ``uint256``). If the event is declared as ``anonymous`` the ``topics[0]`` is not generated;
421
-
- ``topics[n]``: ``EVENT_INDEXED_ARGS[n - 1]`` (``EVENT_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that are indexed);
422
-
- ``data``: ``abi_serialise(EVENT_NON_INDEXED_ARGS)`` (``EVENT_NON_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that are not indexed, ``abi_serialise`` is the ABI serialisation function used for returning a series of typed values from a function, as described above).
423
-
424
-
For all fixed-length Solidity types, the ``EVENT_INDEXED_ARGS`` array contains the 32-byte encoded value directly. However, for *types of dynamic length*, which include ``string``, ``bytes``, and arrays, ``EVENT_INDEXED_ARGS`` will contain the *Keccak hash* of the packed encoded value (see :ref:`abi_packed_mode`), rather than the encoded value directly. This allows applications to efficiently query for values of dynamic-length types (by setting the hash of the encoded value as the topic), but leaves applications unable to decode indexed values they have not queried for. For dynamic-length types, application developers face a trade-off between fast search for predetermined values (if the argument is indexed) and legibility of arbitrary values (which requires that the arguments not be indexed). Developers may overcome this tradeoff and achieve both efficient search and arbitrary legibility by defining events with two arguments — one indexed, one not — intended to hold the same value.
421
+
- ``topics[n]``: ``abi_encode(EVENT_INDEXED_ARGS[n - 1])`` (``EVENT_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that are indexed);
422
+
- ``data``: ABI encoding of ``EVENT_NON_INDEXED_ARGS`` (``EVENT_NON_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that are not indexed, ``abi_encode`` is the ABI encoding function used for returning a series of typed values from a function, as described above).
423
+
424
+
For all types of length at most 32 bytes, the ``EVENT_INDEXED_ARGS`` array contains
425
+
the value directly, padded or sign-extended (for signed integers) to 32 bytes, just as for regular ABI encoding.
426
+
However, for all "complex" types or types of dynamic length, including all arrays, ``string``, ``bytes`` and structs,
427
+
``EVENT_INDEXED_ARGS`` will contain the *Keccak hash* of a special in-place encoded value
428
+
(see :ref:`indexed_event_encoding`), rather than the encoded value directly.
429
+
This allows applications to efficiently query for values of dynamic-length types
430
+
(by setting the hash of the encoded value as the topic), but leaves applications unable
431
+
to decode indexed values they have not queried for. For dynamic-length types,
432
+
application developers face a trade-off between fast search for predetermined values
433
+
(if the argument is indexed) and legibility of arbitrary values (which requires that
434
+
the arguments not be indexed). Developers may overcome this tradeoff and achieve both
435
+
efficient search and arbitrary legibility by defining events with two arguments — one
436
+
indexed, one not — intended to hold the same value.
425
437
426
438
.. _abi_json:
427
439
@@ -608,8 +620,9 @@ Through ``abi.encodePacked()``, Solidity supports a non-standard packed mode whe
608
620
609
621
- types shorter than 32 bytes are neither zero padded nor sign extended and
610
622
- dynamic types are encoded in-place and without the length.
623
+
- array elements are padded, but still encoded in-place
611
624
612
-
This packed mode is mainly used for indexed event parameters.
625
+
Furthermore, structs as well as nested arrays are not supported.
613
626
614
627
As an example, the encoding of ``int16(-1), bytes1(0x42), uint16(0x03), string("Hello, world!")`` results in:
615
628
@@ -622,12 +635,18 @@ As an example, the encoding of ``int16(-1), bytes1(0x42), uint16(0x03), string("
622
635
^^^^^^^^^^^^^^^^^^^^^^^^^^ string("Hello, world!") without a length field
623
636
624
637
More specifically:
625
-
- Each value type takes as many bytes as its range has.
626
-
- The encoding of a struct or fixed-size array is the concatenation of the
627
-
encoding of its members/elements without any separator or padding.
628
-
- Mapping members of structs are ignored as usual.
629
-
- Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded without
630
-
their length field.
638
+
- During the encoding, everything is encoded in-place. This means that there is
639
+
no distinction between head and tail, as in the ABI encoding, and the length
640
+
of an array is not encoded.
641
+
- The direct arguments of ``abi.encodePacked`` are encoded without padding,
642
+
as long as they are not arrays (or ``string`` or ``bytes``).
643
+
- The encoding of an array is the concatenation of the
644
+
encoding of its elements **with** padding.
645
+
- Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded
646
+
without their length field.
647
+
- The encoding of ``string`` or ``bytes`` does not apply padding at the end
648
+
unless it is part of an array or struct (then it is padded to a multiple of
649
+
32 bytes).
631
650
632
651
In general, the encoding is ambiguous as soon as there are two dynamically-sized elements,
633
652
because of the missing length field.
@@ -636,3 +655,39 @@ If padding is needed, explicit type conversions can be used: ``abi.encodePacked(
636
655
637
656
Since packed encoding is not used when calling functions, there is no special support
638
657
for prepending a function selector. Since the encoding is ambiguous, there is no decoding function.
658
+
659
+
.. warning::
660
+
661
+
If you use ``keccak256(abi.encodePacked(a, b))`` and both ``a`` and ``b`` are dynamic types,
662
+
it is easy to craft collisions in the hash value by moving parts of ``a`` into ``b`` and
663
+
vice-versa. More specifically, ``abi.encodePacked("a", "bc") == abi.encodePacked("ab", "c")``.
664
+
If you use ``abi.encodePacked`` for signatures, authentication or data integrity, make
665
+
sure to always use the same types and check that at most one of them is dynamic.
666
+
Unless there is a compelling reason, ``abi.encode`` should be preferred.
667
+
668
+
669
+
.. _indexed_event_encoding:
670
+
671
+
Encoding of Indexed Event Parameters
672
+
====================================
673
+
674
+
Indexed event parameters that are not value types, i.e. arrays and structs are not
675
+
stored directly but instead a keccak256-hash of an encoding is stored. This encoding
676
+
is defined as follows:
677
+
678
+
- the encoding of a ``bytes`` and ``string`` value is just the string contents
679
+
without any padding or length prefix.
680
+
- the encoding of a struct is the concatenation of the encoding of its members,
681
+
always padded to a multiple of 32 bytes (even ``bytes`` and ``string``).
682
+
- the encoding of an array (both dynamically- and statically-sized) is
683
+
the concatenation of the encoding of its elements, always padded to a multiple
684
+
of 32 bytes (even ``bytes`` and ``string``) and without any length prefix
685
+
686
+
In the above, as usual, a negative number is padded by sign extension and not zero padded.
687
+
``bytesNN`` types are padded on the right while ``uintNN`` / ``intNN`` are padded on the left.
688
+
689
+
.. warning::
690
+
691
+
The encoding of a struct is ambiguous if it contains more than one dynamically-sized
692
+
array. Because of that, always re-check the event data and do not rely on the search result
0 commit comments