ethereum.base_types

  1"""
  2Integer and array types which are used by—but not unique to—Ethereum.
  3
  4[`Uint`] represents non-negative integers of arbitrary size, while subclasses
  5of [`FixedUint`] (like [`U256`] or [`U32`]) represent non-negative integers of
  6particular sizes.
  7
  8Similarly, [`Bytes`] represents arbitrarily long byte sequences, while
  9subclasses of [`FixedBytes`] (like [`Bytes0`] or [`Bytes64`]) represent
 10sequences containing an exact number of bytes.
 11
 12[`Uint`]: ref:ethereum.base_types.Uint
 13[`FixedUint`]: ref:ethereum.base_types.FixedUint
 14[`U32`]: ref:ethereum.base_types.U32
 15[`U256`]: ref:ethereum.base_types.U256
 16[`Bytes`]: ref:ethereum.base_types.Bytes
 17[`FixedBytes`]: ref:ethereum.base_types.FixedBytes
 18[`Bytes0`]: ref:ethereum.base_types.Bytes0
 19[`Bytes64`]: ref:ethereum.base_types.Bytes64
 20"""
 21
 22from dataclasses import is_dataclass, replace
 23from typing import (
 24    Any,
 25    Callable,
 26    ClassVar,
 27    Optional,
 28    Protocol,
 29    Tuple,
 30    Type,
 31    TypeVar,
 32    runtime_checkable,
 33)
 34
 35
 36@runtime_checkable
 37class SlottedFreezable(Protocol):
 38    """
 39    A [`Protocol`] implemented by data classes annotated with
 40    [`@slotted_freezable`].
 41
 42    [`@slotted_freezable`]: ref:ethereum.base_types.slotted_freezable
 43    [`Protocol`]: https://docs.python.org/library/typing.html#typing.Protocol
 44    """
 45
 46    _frozen: bool
 47
 48
 49U255_CEIL_VALUE = 2**255
 50"""
 51Smallest value that requires 256 bits to represent. Mostly used in signed
 52arithmetic operations, like [`sdiv`].
 53
 54[`sdiv`]: ref:ethereum.frontier.vm.instructions.arithmetic.sdiv
 55"""
 56
 57U256_CEIL_VALUE = 2**256
 58"""
 59Smallest value that requires 257 bits to represent. Used when converting a
 60[`U256`] in two's complement format to a regular `int` in [`U256.to_signed`].
 61
 62[`U256`]: ref:ethereum.base_types.U256
 63[`U256.to_signed`]: ref:ethereum.base_types.U256.to_signed
 64"""
 65
 66
 67class Uint(int):
 68    """
 69    Unsigned integer of arbitrary size.
 70    """
 71
 72    __slots__ = ()
 73
 74    @classmethod
 75    def from_be_bytes(cls: Type, buffer: "Bytes") -> "Uint":
 76        """
 77        Converts a sequence of bytes into an arbitrarily sized unsigned integer
 78        from its big endian representation.
 79        """
 80        return cls(int.from_bytes(buffer, "big"))
 81
 82    @classmethod
 83    def from_le_bytes(cls: Type, buffer: "Bytes") -> "Uint":
 84        """
 85        Converts a sequence of bytes into an arbitrarily sized unsigned integer
 86        from its little endian representation.
 87        """
 88        return cls(int.from_bytes(buffer, "little"))
 89
 90    def __init__(self, value: int) -> None:
 91        if not isinstance(value, int):
 92            raise TypeError()
 93
 94        if value < 0:
 95            raise ValueError()
 96
 97    def __radd__(self, left: int) -> "Uint":
 98        return self.__add__(left)
 99
100    def __add__(self, right: int) -> "Uint":
101        if not isinstance(right, int):
102            return NotImplemented
103
104        if right < 0:
105            raise ValueError()
106
107        return int.__new__(self.__class__, int.__add__(self, right))
108
109    def __iadd__(self, right: int) -> "Uint":
110        return self.__add__(right)
111
112    def __sub__(self, right: int) -> "Uint":
113        if not isinstance(right, int):
114            return NotImplemented
115
116        if right < 0 or self < right:
117            raise ValueError()
118
119        return int.__new__(self.__class__, int.__sub__(self, right))
120
121    def __rsub__(self, left: int) -> "Uint":
122        if not isinstance(left, int):
123            return NotImplemented
124
125        if left < 0 or self > left:
126            raise ValueError()
127
128        return int.__new__(self.__class__, int.__rsub__(self, left))
129
130    def __isub__(self, right: int) -> "Uint":
131        return self.__sub__(right)
132
133    def __mul__(self, right: int) -> "Uint":
134        if not isinstance(right, int):
135            return NotImplemented
136
137        if right < 0:
138            raise ValueError()
139
140        return int.__new__(self.__class__, int.__mul__(self, right))
141
142    def __rmul__(self, left: int) -> "Uint":
143        return self.__mul__(left)
144
145    def __imul__(self, right: int) -> "Uint":
146        return self.__mul__(right)
147
148    # Explicitly don't override __truediv__, __rtruediv__, and __itruediv__
149    # since they return floats anyway.
150
151    def __floordiv__(self, right: int) -> "Uint":
152        if not isinstance(right, int):
153            return NotImplemented
154
155        if right < 0:
156            raise ValueError()
157
158        return int.__new__(self.__class__, int.__floordiv__(self, right))
159
160    def __rfloordiv__(self, left: int) -> "Uint":
161        if not isinstance(left, int):
162            return NotImplemented
163
164        if left < 0:
165            raise ValueError()
166
167        return int.__new__(self.__class__, int.__rfloordiv__(self, left))
168
169    def __ifloordiv__(self, right: int) -> "Uint":
170        return self.__floordiv__(right)
171
172    def __mod__(self, right: int) -> "Uint":
173        if not isinstance(right, int):
174            return NotImplemented
175
176        if right < 0:
177            raise ValueError()
178
179        return int.__new__(self.__class__, int.__mod__(self, right))
180
181    def __rmod__(self, left: int) -> "Uint":
182        if not isinstance(left, int):
183            return NotImplemented
184
185        if left < 0:
186            raise ValueError()
187
188        return int.__new__(self.__class__, int.__rmod__(self, left))
189
190    def __imod__(self, right: int) -> "Uint":
191        return self.__mod__(right)
192
193    def __divmod__(self, right: int) -> Tuple["Uint", "Uint"]:
194        if not isinstance(right, int):
195            return NotImplemented
196
197        if right < 0:
198            raise ValueError()
199
200        result = int.__divmod__(self, right)
201        return (
202            int.__new__(self.__class__, result[0]),
203            int.__new__(self.__class__, result[1]),
204        )
205
206    def __rdivmod__(self, left: int) -> Tuple["Uint", "Uint"]:
207        if not isinstance(left, int):
208            return NotImplemented
209
210        if left < 0:
211            raise ValueError()
212
213        result = int.__rdivmod__(self, left)
214        return (
215            int.__new__(self.__class__, result[0]),
216            int.__new__(self.__class__, result[1]),
217        )
218
219    def __pow__(  # type: ignore[override]
220        self, right: int, modulo: Optional[int] = None
221    ) -> "Uint":
222        if modulo is not None:
223            if not isinstance(modulo, int):
224                return NotImplemented
225
226            if modulo < 0:
227                raise ValueError()
228
229        if not isinstance(right, int):
230            return NotImplemented
231
232        if right < 0:
233            raise ValueError()
234
235        return int.__new__(self.__class__, int.__pow__(self, right, modulo))
236
237    def __rpow__(  # type: ignore[misc]
238        self, left: int, modulo: Optional[int] = None
239    ) -> "Uint":
240        if modulo is not None:
241            if not isinstance(modulo, int):
242                return NotImplemented
243
244            if modulo < 0:
245                raise ValueError()
246
247        if not isinstance(left, int):
248            return NotImplemented
249
250        if left < 0:
251            raise ValueError()
252
253        return int.__new__(self.__class__, int.__rpow__(self, left, modulo))
254
255    def __ipow__(  # type: ignore[override]
256        self, right: int, modulo: Optional[int] = None
257    ) -> "Uint":
258        return self.__pow__(right, modulo)
259
260    def __xor__(self, right: int) -> "Uint":
261        if not isinstance(right, int):
262            return NotImplemented
263
264        if right < 0:
265            raise ValueError()
266
267        return int.__new__(self.__class__, int.__xor__(self, right))
268
269    def __rxor__(self, left: int) -> "Uint":
270        if not isinstance(left, int):
271            return NotImplemented
272
273        if left < 0:
274            raise ValueError()
275
276        return int.__new__(self.__class__, int.__rxor__(self, left))
277
278    def __ixor__(self, right: int) -> "Uint":
279        return self.__xor__(right)
280
281    # TODO: Implement and, or, neg, pos, abs, invert, ...
282
283    def to_be_bytes32(self) -> "Bytes32":
284        """
285        Converts this arbitrarily sized unsigned integer into its big endian
286        representation with exactly 32 bytes.
287        """
288        return Bytes32(self.to_bytes(32, "big"))
289
290    def to_be_bytes(self) -> "Bytes":
291        """
292        Converts this arbitrarily sized unsigned integer into its big endian
293        representation, without padding.
294        """
295        bit_length = self.bit_length()
296        byte_length = (bit_length + 7) // 8
297        return self.to_bytes(byte_length, "big")
298
299    def to_le_bytes(self, number_bytes: Optional[int] = None) -> "Bytes":
300        """
301        Converts this arbitrarily sized unsigned integer into its little endian
302        representation, without padding.
303        """
304        if number_bytes is None:
305            bit_length = self.bit_length()
306            number_bytes = (bit_length + 7) // 8
307        return self.to_bytes(number_bytes, "little")
308
309
310T = TypeVar("T", bound="FixedUint")
311
312
313class FixedUint(int):
314    """
315    Superclass for fixed size unsigned integers. Not intended to be used
316    directly, but rather to be subclassed.
317    """
318
319    MAX_VALUE: ClassVar["FixedUint"]
320    """
321    Largest value that can be represented by this integer type.
322    """
323
324    __slots__ = ()
325
326    def __init__(self: T, value: int) -> None:
327        if not isinstance(value, int):
328            raise TypeError()
329
330        if value < 0 or value > self.MAX_VALUE:
331            raise ValueError()
332
333    def __radd__(self: T, left: int) -> T:
334        return self.__add__(left)
335
336    def __add__(self: T, right: int) -> T:
337        if not isinstance(right, int):
338            return NotImplemented
339
340        result = int.__add__(self, right)
341
342        if right < 0 or result > self.MAX_VALUE:
343            raise ValueError()
344
345        return int.__new__(self.__class__, result)
346
347    def wrapping_add(self: T, right: int) -> T:
348        """
349        Return a new instance containing `self + right (mod N)`.
350
351        Passing a `right` value greater than [`MAX_VALUE`] or less than zero
352        will raise a `ValueError`, even if the result would fit in this integer
353        type.
354
355        [`MAX_VALUE`]: ref:ethereum.base_types.FixedUint.MAX_VALUE
356        """
357        if not isinstance(right, int):
358            return NotImplemented
359
360        if right < 0 or right > self.MAX_VALUE:
361            raise ValueError()
362
363        # This is a fast way of ensuring that the result is < (2 ** 256)
364        return int.__new__(
365            self.__class__, int.__add__(self, right) & self.MAX_VALUE
366        )
367
368    def __iadd__(self: T, right: int) -> T:
369        return self.__add__(right)
370
371    def __sub__(self: T, right: int) -> T:
372        if not isinstance(right, int):
373            return NotImplemented
374
375        if right < 0 or right > self.MAX_VALUE or self < right:
376            raise ValueError()
377
378        return int.__new__(self.__class__, int.__sub__(self, right))
379
380    def wrapping_sub(self: T, right: int) -> T:
381        """
382        Return a new instance containing `self - right (mod N)`.
383
384        Passing a `right` value greater than [`MAX_VALUE`] or less than zero
385        will raise a `ValueError`, even if the result would fit in this integer
386        type.
387
388        [`MAX_VALUE`]: ref:ethereum.base_types.FixedUint.MAX_VALUE
389        """
390        if not isinstance(right, int):
391            return NotImplemented
392
393        if right < 0 or right > self.MAX_VALUE:
394            raise ValueError()
395
396        # This is a fast way of ensuring that the result is < (2 ** 256)
397        return int.__new__(
398            self.__class__, int.__sub__(self, right) & self.MAX_VALUE
399        )
400
401    def __rsub__(self: T, left: int) -> T:
402        if not isinstance(left, int):
403            return NotImplemented
404
405        if left < 0 or left > self.MAX_VALUE or self > left:
406            raise ValueError()
407
408        return int.__new__(self.__class__, int.__rsub__(self, left))
409
410    def __isub__(self: T, right: int) -> T:
411        return self.__sub__(right)
412
413    def __mul__(self: T, right: int) -> T:
414        if not isinstance(right, int):
415            return NotImplemented
416
417        result = int.__mul__(self, right)
418
419        if right < 0 or result > self.MAX_VALUE:
420            raise ValueError()
421
422        return int.__new__(self.__class__, result)
423
424    def wrapping_mul(self: T, right: int) -> T:
425        """
426        Return a new instance containing `self * right (mod N)`.
427
428        Passing a `right` value greater than [`MAX_VALUE`] or less than zero
429        will raise a `ValueError`, even if the result would fit in this integer
430        type.
431
432        [`MAX_VALUE`]: ref:ethereum.base_types.FixedUint.MAX_VALUE
433        """
434        if not isinstance(right, int):
435            return NotImplemented
436
437        if right < 0 or right > self.MAX_VALUE:
438            raise ValueError()
439
440        # This is a fast way of ensuring that the result is < (2 ** 256)
441        return int.__new__(
442            self.__class__, int.__mul__(self, right) & self.MAX_VALUE
443        )
444
445    def __rmul__(self: T, left: int) -> T:
446        return self.__mul__(left)
447
448    def __imul__(self: T, right: int) -> T:
449        return self.__mul__(right)
450
451    # Explicitly don't override __truediv__, __rtruediv__, and __itruediv__
452    # since they return floats anyway.
453
454    def __floordiv__(self: T, right: int) -> T:
455        if not isinstance(right, int):
456            return NotImplemented
457
458        if right < 0 or right > self.MAX_VALUE:
459            raise ValueError()
460
461        return int.__new__(self.__class__, int.__floordiv__(self, right))
462
463    def __rfloordiv__(self: T, left: int) -> T:
464        if not isinstance(left, int):
465            return NotImplemented
466
467        if left < 0 or left > self.MAX_VALUE:
468            raise ValueError()
469
470        return int.__new__(self.__class__, int.__rfloordiv__(self, left))
471
472    def __ifloordiv__(self: T, right: int) -> T:
473        return self.__floordiv__(right)
474
475    def __mod__(self: T, right: int) -> T:
476        if not isinstance(right, int):
477            return NotImplemented
478
479        if right < 0 or right > self.MAX_VALUE:
480            raise ValueError()
481
482        return int.__new__(self.__class__, int.__mod__(self, right))
483
484    def __rmod__(self: T, left: int) -> T:
485        if not isinstance(left, int):
486            return NotImplemented
487
488        if left < 0 or left > self.MAX_VALUE:
489            raise ValueError()
490
491        return int.__new__(self.__class__, int.__rmod__(self, left))
492
493    def __imod__(self: T, right: int) -> T:
494        return self.__mod__(right)
495
496    def __divmod__(self: T, right: int) -> Tuple[T, T]:
497        if not isinstance(right, int):
498            return NotImplemented
499
500        if right < 0 or right > self.MAX_VALUE:
501            raise ValueError()
502
503        result = super(FixedUint, self).__divmod__(right)
504        return (
505            int.__new__(self.__class__, result[0]),
506            int.__new__(self.__class__, result[1]),
507        )
508
509    def __rdivmod__(self: T, left: int) -> Tuple[T, T]:
510        if not isinstance(left, int):
511            return NotImplemented
512
513        if left < 0 or left > self.MAX_VALUE:
514            raise ValueError()
515
516        result = super(FixedUint, self).__rdivmod__(left)
517        return (
518            int.__new__(self.__class__, result[0]),
519            int.__new__(self.__class__, result[1]),
520        )
521
522    def __pow__(  # type: ignore[override]
523        self: T, right: int, modulo: Optional[int] = None
524    ) -> T:
525        if modulo is not None:
526            if not isinstance(modulo, int):
527                return NotImplemented
528
529            if modulo < 0 or modulo > self.MAX_VALUE:
530                raise ValueError()
531
532        if not isinstance(right, int):
533            return NotImplemented
534
535        result = int.__pow__(self, right, modulo)
536
537        if right < 0 or right > self.MAX_VALUE or result > self.MAX_VALUE:
538            raise ValueError()
539
540        return int.__new__(self.__class__, result)
541
542    def wrapping_pow(self: T, right: int, modulo: Optional[int] = None) -> T:
543        """
544        Return a new instance containing `self ** right (mod modulo)`.
545
546        If omitted, `modulo` defaults to `Uint(self.MAX_VALUE) + 1`.
547
548        Passing a `right` or `modulo` value greater than [`MAX_VALUE`] or
549        less than zero will raise a `ValueError`, even if the result would fit
550        in this integer type.
551
552        [`MAX_VALUE`]: ref:ethereum.base_types.FixedUint.MAX_VALUE
553        """
554        if modulo is not None:
555            if not isinstance(modulo, int):
556                return NotImplemented
557
558            if modulo < 0 or modulo > self.MAX_VALUE:
559                raise ValueError()
560
561        if not isinstance(right, int):
562            return NotImplemented
563
564        if right < 0 or right > self.MAX_VALUE:
565            raise ValueError()
566
567        # This is a fast way of ensuring that the result is < (2 ** 256)
568        return int.__new__(
569            self.__class__, int.__pow__(self, right, modulo) & self.MAX_VALUE
570        )
571
572    def __rpow__(  # type: ignore[misc]
573        self: T, left: int, modulo: Optional[int] = None
574    ) -> T:
575        if modulo is not None:
576            if not isinstance(modulo, int):
577                return NotImplemented
578
579            if modulo < 0 or modulo > self.MAX_VALUE:
580                raise ValueError()
581
582        if not isinstance(left, int):
583            return NotImplemented
584
585        if left < 0 or left > self.MAX_VALUE:
586            raise ValueError()
587
588        return int.__new__(self.__class__, int.__rpow__(self, left, modulo))
589
590    def __ipow__(  # type: ignore[override]
591        self: T, right: int, modulo: Optional[int] = None
592    ) -> T:
593        return self.__pow__(right, modulo)
594
595    def __and__(self: T, right: int) -> T:
596        if not isinstance(right, int):
597            return NotImplemented
598
599        if right < 0 or right > self.MAX_VALUE:
600            raise ValueError()
601
602        return int.__new__(self.__class__, int.__and__(self, right))
603
604    def __or__(self: T, right: int) -> T:
605        if not isinstance(right, int):
606            return NotImplemented
607
608        if right < 0 or right > self.MAX_VALUE:
609            raise ValueError()
610
611        return int.__new__(self.__class__, int.__or__(self, right))
612
613    def __xor__(self: T, right: int) -> T:
614        if not isinstance(right, int):
615            return NotImplemented
616
617        if right < 0 or right > self.MAX_VALUE:
618            raise ValueError()
619
620        return int.__new__(self.__class__, int.__xor__(self, right))
621
622    def __rxor__(self: T, left: int) -> T:
623        if not isinstance(left, int):
624            return NotImplemented
625
626        if left < 0 or left > self.MAX_VALUE:
627            raise ValueError()
628
629        return int.__new__(self.__class__, int.__rxor__(self, left))
630
631    def __ixor__(self: T, right: int) -> T:
632        return self.__xor__(right)
633
634    def __invert__(self: T) -> T:
635        return int.__new__(
636            self.__class__, int.__invert__(self) & self.MAX_VALUE
637        )
638
639    def __rshift__(self: T, shift_by: int) -> T:
640        if not isinstance(shift_by, int):
641            return NotImplemented
642        return int.__new__(self.__class__, int.__rshift__(self, shift_by))
643
644    def to_be_bytes(self) -> "Bytes":
645        """
646        Converts this unsigned integer into its big endian representation,
647        omitting leading zero bytes.
648        """
649        bit_length = self.bit_length()
650        byte_length = (bit_length + 7) // 8
651        return self.to_bytes(byte_length, "big")
652
653    # TODO: Implement neg, pos, abs ...
654
655
656class U256(FixedUint):
657    """
658    Unsigned integer, which can represent `0` to `2 ** 256 - 1`, inclusive.
659    """
660
661    MAX_VALUE: ClassVar["U256"]
662    """
663    Largest value that can be represented by this integer type.
664    """
665
666    __slots__ = ()
667
668    @classmethod
669    def from_be_bytes(cls: Type, buffer: "Bytes") -> "U256":
670        """
671        Converts a sequence of bytes into a fixed sized unsigned integer
672        from its big endian representation.
673        """
674        if len(buffer) > 32:
675            raise ValueError()
676
677        return cls(int.from_bytes(buffer, "big"))
678
679    @classmethod
680    def from_signed(cls: Type, value: int) -> "U256":
681        """
682        Creates an unsigned integer representing `value` using two's
683        complement.
684        """
685        if value >= 0:
686            return cls(value)
687
688        return cls(value & cls.MAX_VALUE)
689
690    def to_be_bytes32(self) -> "Bytes32":
691        """
692        Converts this 256-bit unsigned integer into its big endian
693        representation with exactly 32 bytes.
694        """
695        return Bytes32(self.to_bytes(32, "big"))
696
697    def to_signed(self) -> int:
698        """
699        Decodes a signed integer from its two's complement representation.
700        """
701        if self.bit_length() < 256:
702            # This means that the sign bit is 0
703            return int(self)
704
705        # -1 * (2's complement of U256 value)
706        return int(self) - U256_CEIL_VALUE
707
708
709U256.MAX_VALUE = int.__new__(U256, (2**256) - 1)
710
711
712class U32(FixedUint):
713    """
714    Unsigned positive integer, which can represent `0` to `2 ** 32 - 1`,
715    inclusive.
716    """
717
718    MAX_VALUE: ClassVar["U32"]
719    """
720    Largest value that can be represented by this integer type.
721    """
722
723    __slots__ = ()
724
725    @classmethod
726    def from_le_bytes(cls: Type, buffer: "Bytes") -> "U32":
727        """
728        Converts a sequence of bytes into an arbitrarily sized unsigned integer
729        from its little endian representation.
730        """
731        if len(buffer) > 4:
732            raise ValueError()
733
734        return cls(int.from_bytes(buffer, "little"))
735
736    def to_le_bytes4(self) -> "Bytes4":
737        """
738        Converts this fixed sized unsigned integer into its little endian
739        representation, with exactly 4 bytes.
740        """
741        return Bytes4(self.to_bytes(4, "little"))
742
743    def to_le_bytes(self) -> "Bytes":
744        """
745        Converts this fixed sized unsigned integer into its little endian
746        representation, in the fewest bytes possible.
747        """
748        bit_length = self.bit_length()
749        byte_length = (bit_length + 7) // 8
750        return self.to_bytes(byte_length, "little")
751
752
753U32.MAX_VALUE = int.__new__(U32, (2**32) - 1)
754
755
756class U64(FixedUint):
757    """
758    Unsigned positive integer, which can represent `0` to `2 ** 64 - 1`,
759    inclusive.
760    """
761
762    MAX_VALUE: ClassVar["U64"]
763    """
764    Largest value that can be represented by this integer type.
765    """
766
767    __slots__ = ()
768
769    @classmethod
770    def from_le_bytes(cls: Type, buffer: "Bytes") -> "U64":
771        """
772        Converts a sequence of bytes into an arbitrarily sized unsigned integer
773        from its little endian representation.
774        """
775        if len(buffer) > 8:
776            raise ValueError()
777
778        return cls(int.from_bytes(buffer, "little"))
779
780    def to_le_bytes8(self) -> "Bytes8":
781        """
782        Converts this fixed sized unsigned integer into its little endian
783        representation, with exactly 8 bytes.
784        """
785        return Bytes8(self.to_bytes(8, "little"))
786
787    def to_le_bytes(self) -> "Bytes":
788        """
789        Converts this fixed sized unsigned integer into its little endian
790        representation, in the fewest bytes possible.
791        """
792        bit_length = self.bit_length()
793        byte_length = (bit_length + 7) // 8
794        return self.to_bytes(byte_length, "little")
795
796    @classmethod
797    def from_be_bytes(cls: Type, buffer: "Bytes") -> "U64":
798        """
799        Converts a sequence of bytes into an unsigned 64 bit integer from its
800        big endian representation.
801        """
802        if len(buffer) > 8:
803            raise ValueError()
804
805        return cls(int.from_bytes(buffer, "big"))
806
807
808U64.MAX_VALUE = int.__new__(U64, (2**64) - 1)
809
810
811B = TypeVar("B", bound="FixedBytes")
812
813
814class FixedBytes(bytes):
815    """
816    Superclass for fixed sized byte arrays. Not intended to be used directly,
817    but should be subclassed.
818    """
819
820    LENGTH: int
821    """
822    Number of bytes in each instance of this class.
823    """
824
825    __slots__ = ()
826
827    def __new__(cls: Type[B], *args: Any, **kwargs: Any) -> B:
828        """
829        Create a new instance, ensuring the result has the correct length.
830        """
831        result = super(FixedBytes, cls).__new__(cls, *args, **kwargs)
832        if len(result) != cls.LENGTH:
833            raise ValueError(
834                f"expected {cls.LENGTH} bytes but got {len(result)}"
835            )
836        return result
837
838
839class Bytes0(FixedBytes):
840    """
841    Byte array of exactly zero elements.
842    """
843
844    LENGTH = 0
845    """
846    Number of bytes in each instance of this class.
847    """
848
849
850class Bytes4(FixedBytes):
851    """
852    Byte array of exactly four elements.
853    """
854
855    LENGTH = 4
856    """
857    Number of bytes in each instance of this class.
858    """
859
860
861class Bytes8(FixedBytes):
862    """
863    Byte array of exactly eight elements.
864    """
865
866    LENGTH = 8
867    """
868    Number of bytes in each instance of this class.
869    """
870
871
872class Bytes20(FixedBytes):
873    """
874    Byte array of exactly 20 elements.
875    """
876
877    LENGTH = 20
878    """
879    Number of bytes in each instance of this class.
880    """
881
882
883class Bytes32(FixedBytes):
884    """
885    Byte array of exactly 32 elements.
886    """
887
888    LENGTH = 32
889    """
890    Number of bytes in each instance of this class.
891    """
892
893
894class Bytes64(FixedBytes):
895    """
896    Byte array of exactly 64 elements.
897    """
898
899    LENGTH = 64
900    """
901    Number of bytes in each instance of this class.
902    """
903
904
905class Bytes256(FixedBytes):
906    """
907    Byte array of exactly 256 elements.
908    """
909
910    LENGTH = 256
911    """
912    Number of bytes in each instance of this class.
913    """
914
915
916Bytes = bytes
917"""
918Sequence of bytes (octets) of arbitrary length.
919"""
920
921
922def _setattr_function(self: Any, attr: str, value: Any) -> None:
923    if getattr(self, "_frozen", None):
924        raise Exception("Mutating frozen dataclasses is not allowed.")
925    else:
926        object.__setattr__(self, attr, value)
927
928
929def _delattr_function(self: Any, attr: str) -> None:
930    if self._frozen:
931        raise Exception("Mutating frozen dataclasses is not allowed.")
932    else:
933        object.__delattr__(self, attr)
934
935
936def _make_init_function(f: Callable) -> Callable:
937    def init_function(self: Any, *args: Any, **kwargs: Any) -> None:
938        will_be_frozen = kwargs.pop("_frozen", True)
939        object.__setattr__(self, "_frozen", False)
940        f(self, *args, **kwargs)
941        self._frozen = will_be_frozen
942
943    return init_function
944
945
946def slotted_freezable(cls: Any) -> Any:
947    """
948    Monkey patches a dataclass so it can be frozen by setting `_frozen` to
949    `True` and uses `__slots__` for efficiency.
950
951    Instances will be created frozen by default unless you pass `_frozen=False`
952    to `__init__`.
953    """
954    cls.__slots__ = ("_frozen",) + tuple(cls.__annotations__)
955    cls.__init__ = _make_init_function(cls.__init__)
956    cls.__setattr__ = _setattr_function
957    cls.__delattr__ = _delattr_function
958    return type(cls)(cls.__name__, cls.__bases__, dict(cls.__dict__))
959
960
961S = TypeVar("S")
962
963
964def modify(obj: S, f: Callable[[S], None]) -> S:
965    """
966    Create a copy of `obj` (which must be [`@slotted_freezable`]), and modify
967    it by applying `f`. The returned copy will be frozen.
968
969    [`@slotted_freezable`]: ref:ethereum.base_types.slotted_freezable
970    """
971    assert is_dataclass(obj)
972    assert isinstance(obj, SlottedFreezable)
973    new_obj = replace(obj, _frozen=False)
974    f(new_obj)
975    new_obj._frozen = True
976    return new_obj