Serialization

Data serialization

starknet.py serializes python values to Cairo values and deserializes Cairo values to python values.

Attention

Serializing short strings to felts has been deprecated. Please use starknet_py.cairo.felt.encode_shortstring to create numeric value from string before passing value to serializer.

Serialization from python to Cairo

Expected Cairo type	Accepted python types	Example python values	Comment
felt	int	0, 1, 1213124124	Provided int must be in range [0;P) - P being the Prime used in cairo-vm.
tuple	any iterable of matching size	(1, 2, (9, 8)), [1, 2, (9, 8)], (v for v in [1, 2, (9, 8)])	Can nest other types apart from pointers
named tuple	dict or NamedTuple or TupleDataclass	{"a": 1, "b": 2, "c" : (3, 4)}, NamedTuple("name", [("a", int), ("b", int), ("c", tuple)])(1, 2, (3, 4))
struct	dict with keys matching struct	{"key_1": 2, "key_2": (1, 2, 3), "key_3": {"other_struct_key": 13}}	Can nest other types apart from pointers
pointer/array (adds parameter_len parameter to abi)	any iterable	[1, 2, 3], [], ({"low": 1, "high": 1}, {"low": 2, "high": 2})	parameter_len is filled automatically from value
uint256	int or dict with "low" and "high" keys and ints as values	0, 340282366920938463463374607431768211583, {"low": 12, "high": 13}

Deserialization from Cairo to python values

Cairo type	Python type
felt	int
tuple	tuple
named tuple	TupleDataclass
struct	dict with keys matching struct
pointer/array	list
uint256	int

Working with shortstrings

To make working with short strings easier we provide some utility functions to translate between them and felt values. You can read more about how cairo treats shortstrings in the documentation.

Conversion functions and references:

• encode_shortstring

• decode_shortstring

from starknet_py.cairo.felt import decode_shortstring, encode_shortstring

# Convert a string literal to its felt value
encoded = encode_shortstring("myshortstring")
assert encoded == 0x6D7973686F7274737472696E67

# Decode a felt into a string
decoded = decode_shortstring(encoded)
assert decoded == "myshortstring"

Creating serializers from abi

For most use cases using high level Contract is enough - it handles serialization and deserialization for you. If you need more flexibility you can use lower level serialization API, see Serializers for more details.

AbiParser transforms ABI into Abi class that can be used for creating serializers. This way you can easily deserialize events or serialize function’s inputs. Remember to use the proper version of AbiParser which depends on parsed ABI version.

Serializing function inputs and outputs

from starknet_py.abi.v0 import AbiParser

"""
@external
func transferFrom{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_ptr}(
    sender: felt, recipient: felt, amount: felt
) -> (success: felt) {
    alloc_locals;
    local success: felt = 1;
    return (success,);
}
"""

erc20_abi = json.loads(raw_abi_string)
abi = AbiParser(erc20_abi).parse()

from starknet_py.serialization import serializer_for_function

# You can create serializer for function inputs/outputs by passing Abi.Function object to serializer_for_function
function_serializer = serializer_for_function(abi.functions["transferFrom"])

# You can call function serializer like you would a normal function
assert [111, 222, 333] == function_serializer.serialize(
    sender=111, recipient=222, amount=333
)
assert [111, 222, 333] == function_serializer.serialize(111, 222, 333)
assert [111, 222, 333] == function_serializer.serialize(111, 222, amount=333)

# You can use deserialized result from function serializer like a tuple, but it also has named properties
result = function_serializer.deserialize([1])
assert 1 == result[0]
assert 1 == result.success
assert {"success": 1} == result.as_dict()
(success,) = result
assert 1 == success

Serializing events

Events emitted by contracts can also be serialized, having provided the correct ABI

from starknet_py.serialization import serializer_for_event

"""
@event
func Transfer(from_: felt, to: felt, value: Uint256) {
}
"""

# You can create serializer for events by passing Abi.Event object to serializer_for_event
event_serializer = serializer_for_event(abi.events["Transfer"])
assert [1, 2, 3, 4] == event_serializer.serialize(
    {"from_": 1, "to": 2, "value": 3 + 4 * 2**128}
)
assert {
    "from_": 1,
    "to": 2,
    "value": 3 + 4 * 2**128,
} == event_serializer.deserialize([1, 2, 3, 4]).as_dict()