ethereum.utils.safe_arithmetic

 1"""
 2Safe Arithmetic for U256 Integer Type
 3^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 4
 5.. contents:: Table of Contents
 6    :backlinks: none
 7    :local:
 8
 9Introduction
10------------
11
12Safe arithmetic utility functions for U256 integer type.
13"""
14from typing import Optional, Type, Union
15
16from ethereum.base_types import U256, Uint
17
18
19def u256_safe_add(
20    *numbers: Union[U256, Uint],
21    exception_type: Optional[Type[BaseException]] = None
22) -> U256:
23    """
24    Adds together the given sequence of numbers. If the total sum of the
25    numbers exceeds `U256.MAX_VALUE` then an exception is raised.
26    If `exception_type` = None then the exception raised defaults to the one
27    raised by `U256` when `U256.value > U256.MAX_VALUE`
28    else `exception_type` is raised.
29
30    Parameters
31    ----------
32    numbers :
33        The sequence of numbers that need to be added together.
34
35    exception_type:
36        The exception that needs to be raised if the sum of the `numbers`
37        exceeds `U256.MAX_VALUE`.
38
39    Returns
40    -------
41    result : `ethereum.base_types.U256`
42        The sum of the given sequence of numbers if the total is less than
43        `U256.MAX_VALUE` else an exception is raised.
44        If `exception_type` = None then the exception raised defaults to the
45        one raised by `U256` when `U256.value > U256.MAX_VALUE`
46        else `exception_type` is raised.
47    """
48    try:
49        return U256(sum(numbers))
50    except ValueError as e:
51        if exception_type:
52            raise exception_type from e
53        else:
54            raise e
55
56
57def u256_safe_multiply(
58    *numbers: Union[U256, Uint],
59    exception_type: Optional[Type[BaseException]] = None
60) -> U256:
61    """
62    Multiplies together the given sequence of numbers. If the net product of
63    the numbers exceeds `U256.MAX_VALUE` then an exception is raised.
64    If `exception_type` = None then the exception raised defaults to the one
65    raised by `U256` when `U256.value > U256.MAX_VALUE` else
66    `exception_type` is raised.
67
68    Parameters
69    ----------
70    numbers :
71        The sequence of numbers that need to be multiplies together.
72
73    exception_type:
74        The exception that needs to be raised if the sum of the `numbers`
75        exceeds `U256.MAX_VALUE`.
76
77    Returns
78    -------
79    result : `ethereum.base_types.U256`
80        The multiplication product of the given sequence of numbers if the
81        net product  is less than `U256.MAX_VALUE` else an exception is raised.
82        If `exception_type` = None then the exception raised defaults to the
83        one raised by `U256` when `U256.value > U256.MAX_VALUE`
84        else `exception_type` is raised.
85    """
86    result = numbers[0]
87    try:
88        for number in numbers[1:]:
89            result *= number
90        return U256(result)
91    except ValueError as e:
92        if exception_type:
93            raise exception_type from e
94        else:
95            raise e