Data serialization# serializes python values to Cairo values and deserializes Cairo values to python values.


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




0, 1, 1213124124

Provided int must be in range [0;P) - P being the Prime used in cairo-vm.


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))


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


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





named tuple



dict with keys matching struct





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:

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

func transferFrom{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_ptr}(
    sender: felt, recipient: felt, amount: felt
) -> (success: felt) {
    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

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(["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()