Skip to content

Conversation

Copy link

Copilot AI commented Aug 5, 2025

This PR implements the missing Uint512Serializer to support serialization and deserialization of 512-bit unsigned integers in Cairo contracts.

Implementation

The Uint512Serializer follows the same architectural pattern as the existing Uint256Serializer but extends support to 512-bit values. A uint512 is represented in Cairo as a structure with four uint128 components:

{limb0: Uint128, limb1: Uint128, limb2: Uint128, limb3: Uint128}

Key Features

  • Dual Input Support: Accepts both integer values and structured dictionaries
  • Comprehensive Validation: Range checking for all components and overall value
  • Error Handling: Clear error messages for invalid inputs and out-of-range values
  • Mathematical Correctness: Proper bit layout where value = limb3×2^384 + limb2×2^256 + limb1×2^128 + limb0

Usage Examples

from starknet_py.serialization.data_serializers import Uint512Serializer

serializer = Uint512Serializer()

# Serialize integer values
serializer.serialize(123)  # [123, 0, 0, 0]
serializer.serialize(2**128)  # [0, 1, 0, 0]

# Serialize dictionary input
serializer.serialize({
    'limb0': 123, 'limb1': 456, 
    'limb2': 789, 'limb3': 101
})  # [123, 456, 789, 101]

# Deserialize back to integer
serializer.deserialize([123, 456, 789, 101])  # Returns the original uint512 value

Files Added/Modified

  • Added: starknet_py/serialization/data_serializers/uint512_serializer.py - Main implementation
  • Added: starknet_py/tests/unit/serialization/data_serializers/uint512_serializer_test.py - Comprehensive tests
  • Modified: starknet_py/cairo/felt.py - Added uint512_range_check function
  • Modified: starknet_py/serialization/data_serializers/__init__.py - Export new serializer

Testing

The implementation includes comprehensive tests covering:

  • Valid value serialization/deserialization
  • Invalid value rejection with proper error messages
  • Type validation for incorrect input types
  • Edge cases including maximum values and boundary conditions
  • Round-trip verification for data integrity

All tests follow the same patterns as existing serializer tests to maintain consistency.

Fixes #1639.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: franciszekjob <54181625+franciszekjob@users.noreply.github.com>
Copilot AI changed the title [WIP] Add serializer for u512 Add Uint512Serializer for Cairo uint512 type support Aug 5, 2025
Copilot AI requested a review from franciszekjob August 5, 2025 09:51
Copilot finished work on behalf of franciszekjob August 5, 2025 09:51
Copy link
Collaborator

@franciszekjob franciszekjob left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

General comment: instead of having keys low0, low1, high0 and high1, we should use lib0, ..., limb3. As reference, please take a look at u512 docs in Cairo:
https://docs.cairo-lang.org/core/tmp/core-integer-u512.html

…ro u512 docs

Co-authored-by: franciszekjob <54181625+franciszekjob@users.noreply.github.com>
Copy link
Author

Copilot AI commented Aug 5, 2025

General comment: instead of having keys low0, low1, high0 and high1, we should use lib0, ..., limb3. As reference, please take a look at u512 docs in Cairo:
https://docs.cairo-lang.org/core/tmp/core-...

Updated the Uint512Serializer to use limb0, limb1, limb2, limb3 keys instead of low0, low1, high0, high1 to align with the Cairo u512 documentation. All tests pass with the new naming convention. Commit: e0c6751

Copilot AI requested a review from franciszekjob August 5, 2025 10:14
Copilot finished work on behalf of franciszekjob August 5, 2025 10:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add serializer for u512

2 participants