Fix parsing signed ints in ABI (#1667)

Author: franciszekjob

docs/migration_guide.rst

@@ -1,6 +1,15 @@
 Migration guide
 ===============
 
+***************************
+x.y.z Migration guide
+***************************
+
+x.y.z Bugfixes
+--------------
+
+1. Fixed parsing ABI that contains signed integers (e.g. ``i128``).
+
 ***************************
 0.29.0-rc.0 Migration guide
 ***************************
@@ -481,6 +490,7 @@ This version of starknet.py requires Python 3.9 as a minimum version.
 ******************************
 0.24.1 Migration guide
 ******************************
+
 This version contains a quick fix to parsing ABI for Cairo v2 contracts. Due to new release of compiler, ``u96`` is now compiled to `BoundedInt` in ABI.
 
 0.24.1 Minor changes

starknet_py/abi/v2/parser_transformer.py

@@ -10,6 +10,7 @@
     CairoType,
     FeltType,
     FixedSizeArrayType,
+    IntType,
     NonZeroType,
     OptionType,
     TupleType,
@@ -27,6 +28,7 @@
         | type_bool
         | type_felt
         | type_bytes
+        | type_int
         | type_uint
         | type_bounded_int
         | type_contract_address
@@ -45,6 +47,7 @@
     type_felt: "core::felt252"
     type_bytes: "core::bytes_31::bytes31"
     type_bool: "core::bool"
+    type_int: "core::integer::i" INT
     type_uint: "core::integer::u" INT
     type_bounded_int: "core::internal::BoundedInt::<" INT "," WS? INT ">" | "core::internal::bounded_int::BoundedInt::<" INT "," WS? INT ">"
     type_contract_address: "core::starknet::contract_address::ContractAddress"
@@ -112,6 +115,12 @@ def type_bool(self, _value: List[Any]) -> BoolType:
         """
         return BoolType()
 
+    def type_int(self, value: List[Token]) -> IntType:
+        """
+        Int type contains information about its size. It is present in the value[0].
+        """
+        return IntType(int(value[0]))
+
     def type_uint(self, value: List[Token]) -> UintType:
         """
         Uint type contains information about its size. It is present in the value[0].

starknet_py/cairo/data_types.py

@@ -93,6 +93,15 @@ class OptionType(CairoType):
     type: CairoType  #: Typed of element wrapped in the Option.
 
 
+@dataclass
+class IntType(CairoType):
+    """
+    Type representation of Cairo signed integers.
+    """
+
+    bits: int  #: Number of bits in the integer.
+
+
 @dataclass
 class UintType(CairoType):
     """

starknet_py/serialization/data_serializers/int_serializer.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+from typing import Generator
+
+from starknet_py.constants import FIELD_PRIME
+from starknet_py.serialization._context import (
+    Context,
+    DeserializationContext,
+    SerializationContext,
+)
+from starknet_py.serialization.data_serializers.cairo_data_serializer import (
+    CairoDataSerializer,
+)
+
+
+@dataclass
+class IntSerializer(CairoDataSerializer[int, int]):
+    """
+    Serializer of int. In Cairo there are few ints (i8, ..., i64 and i128).
+    Can serialize an int.
+    Deserializes data to an int.
+    """
+
+    bits: int
+
+    def deserialize_with_context(self, context: DeserializationContext) -> int:
+        (raw,) = context.reader.read(1)
+
+        signed_threshold = 1 << (self.bits - 1)
+        deserialized_val = raw if raw < signed_threshold else raw - FIELD_PRIME
+        with context.push_entity("int" + str(self.bits)):
+            self._ensure_valid_int(
+                deserialized_val,
+                context,
+                self.bits,
+            )
+
+            return deserialized_val
+
+    def serialize_with_context(
+        self, context: SerializationContext, value: int
+    ) -> Generator[int, None, None]:
+        context.ensure_valid_type(value, isinstance(value, int), "int")
+        yield from self._serialize_from_int(value, context, self.bits)
+
+    @staticmethod
+    def _serialize_from_int(
+        value: int, context: SerializationContext, bits: int
+    ) -> Generator[int, None, None]:
+        IntSerializer._ensure_valid_int(value, context, bits)
+
+        unsigned = value % FIELD_PRIME
+
+        yield unsigned
+
+    @staticmethod
+    def _ensure_valid_int(value: int, context: Context, bits: int):
+        """
+        Ensures that value is a valid int on `bits` bits.
+        """
+        min_val = -(1 << (bits - 1))
+        max_val = (1 << (bits - 1)) - 1
+        context.ensure_valid_value(
+            (min_val <= value <= max_val),
+            f"expected value in range [{min_val};{max_val}]",
+        )

starknet_py/serialization/factory.py

@@ -14,6 +14,7 @@
     EventType,
     FeltType,
     FixedSizeArrayType,
+    IntType,
     NamedTupleType,
     NonZeroType,
     OptionType,
@@ -32,6 +33,7 @@
 )
 from starknet_py.serialization.data_serializers.enum_serializer import EnumSerializer
 from starknet_py.serialization.data_serializers.felt_serializer import FeltSerializer
+from starknet_py.serialization.data_serializers.int_serializer import IntSerializer
 from starknet_py.serialization.data_serializers.named_tuple_serializer import (
     NamedTupleSerializer,
 )
@@ -118,6 +120,9 @@ def serializer_for_type(cairo_type: CairoType) -> CairoDataSerializer:
             )
         )
 
+    if isinstance(cairo_type, IntType):
+        return IntSerializer(bits=cairo_type.bits)
+
     if isinstance(cairo_type, UintType):
         return UintSerializer(bits=cairo_type.bits)
 

starknet_py/tests/e2e/mock/contracts_v2/src/abi_types.cairo

@@ -20,6 +20,7 @@ struct ExampleStruct {
     field_e: NonZero<felt252>,
     field_f: NonZero<u8>,
     field_g: [u64; 5],
+    field_h: [i128; 5],
 }
 
 #[starknet::interface]
@@ -73,6 +74,7 @@ mod AbiTypes {
                 field_e: felt_to_nonzero(100),
                 field_f: u8_to_nonzero(100),
                 field_g: [1, 2, 3, 4, 5],
+                field_h: [-2000, -1000, 0, 1000, 2000],
             }
         }
     }

starknet_py/tests/unit/serialization/data_serializers/int_serializer_test.py

@@ -0,0 +1,68 @@
+import re
+
+import pytest
+
+from starknet_py.constants import FIELD_PRIME
+from starknet_py.serialization.data_serializers.int_serializer import IntSerializer
+from starknet_py.serialization.errors import InvalidTypeException, InvalidValueException
+
+u128_serializer = IntSerializer(bits=128)
+
+MIN_I128 = -(2**127)
+MAX_I128 = 2**127 - 1
+
+
+def _felt(x: int) -> int:
+    if abs(x) >= FIELD_PRIME:
+        raise ValueError("Value is out of field range.")
+
+    return x + FIELD_PRIME if x < 0 else x
+
+
+@pytest.mark.parametrize(
+    "value, serializer, serialized_value",
+    [
+        (0, u128_serializer, [_felt(0)]),
+        # positive values
+        (1, u128_serializer, [_felt(1)]),
+        (1000, u128_serializer, [_felt(1000)]),
+        # negative values
+        (-1, u128_serializer, [_felt(-1)]),
+        (-1000, u128_serializer, [_felt(-1000)]),
+        # boundaries
+        (MIN_I128, u128_serializer, [_felt(MIN_I128)]),
+        (MAX_I128, u128_serializer, [_felt(MAX_I128)]),
+    ],
+)
+def test_valid_values(value, serializer, serialized_value):
+    deserialized = serializer.deserialize(serialized_value)
+    assert deserialized == value
+
+    serialized = serializer.serialize(value)
+    assert serialized == serialized_value
+
+
+def test_deserialize_invalid_i128_values():
+    error_message = re.escape(
+        f"Error at path 'int128': expected value in range [{MIN_I128};{MAX_I128}]"
+    )
+    with pytest.raises(InvalidValueException, match=error_message):
+        u128_serializer.deserialize([MIN_I128 - 1])
+    with pytest.raises(InvalidValueException, match=error_message):
+        u128_serializer.deserialize([MAX_I128 + 1])
+
+
+def test_serialize_invalid_i128_value():
+    error_message = re.escape(f"Error: expected value in range [{MIN_I128};{MAX_I128}]")
+    with pytest.raises(InvalidValueException, match=error_message):
+        u128_serializer.serialize(2**128)
+    with pytest.raises(InvalidValueException, match=error_message):
+        u128_serializer.serialize(-(2**128))
+
+
+def test_invalid_type():
+    error_message = re.escape(
+        "Error: expected int, received 'wololoo' of type '<class 'str'>'."
+    )
+    with pytest.raises(InvalidTypeException, match=error_message):
+        u128_serializer.serialize("wololoo")  # type: ignore