Skip to main content
Version: 11.x

Class: CairoTuple

Defined in: src/utils/cairoDataTypes/tuple.ts:34

A Cairo tuple : a fixed sequence of values, each of its own type.

Its abi type is written (type1, type2), and Cairo 0 also allows naming the members, (x: felt, y: felt). On the wire a tuple is just its members one after the other — unlike an array it carries no length, because its shape is entirely in its type.

A tuple holds its members as CairoType instances rather than as raw values, so a tuple of tuples serializes in one pass : each member is asked for its own felts.

Example​

const tuple = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
tuple.toApiRequest(); //                  ["1", "2"]     no length prefix
tuple.decompose(cairoTypeStrategy); //    { '0': 1n, '1': 2n }

Constructors​

Constructor​

new CairoTuple(content, tupleType, parsingStrategy): CairoTuple

Defined in: src/utils/cairoDataTypes/tuple.ts:108

Build a tuple, from values a caller passed or from the felts of a response.

The three inputs a member can take are all accepted : a raw value, which the strategy turns into the type its position declares; an instance already built, which is taken as it stands; and the response iterator, which is read member by member.

A named Cairo 0 tuple also accepts an object keyed by those names, and any tuple accepts one keyed by position — { 0: 1, 1: 2 } says what [1, 2] says.

Parameters​

content​

unknown

the members, as an array, an object, or the response iterator

tupleType​

string

the abi type, (type1, type2)

parsingStrategy​

AllowArray<CairoTypeStrategy>

how to build each member

Returns​

CairoTuple

Throws​

when the type is not a tuple, when the member count does not match, or when a member type no strategy knows is met

Example​

const fromArray = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
fromArray.toApiRequest(); // ["1", "2"]

const fromResponse = new CairoTuple(
  ['0x1', '0x2'].values(),
  '(core::integer::u8, core::integer::u32)',
  cairoTypeStrategy
);
fromResponse.toApiRequest(); // ["1", "2"]

Properties​

dynamicSelector​

static dynamicSelector: "CairoTuple"

Defined in: src/utils/cairoDataTypes/tuple.ts:46

The name this class is registered under in a strategy's dynamicSelectors.

A tuple type is a shape rather than one string, so it cannot be a key of constructors the way core::integer::u8 is : the selector recognizes the shape, and this names what to build.

Example​

const result = CairoTuple.dynamicSelector;
// result = "CairoTuple"

dynamicSelector​

readonly dynamicSelector: "CairoTuple" = CairoTuple.dynamicSelector

Defined in: src/utils/cairoDataTypes/tuple.ts:57

The selector on the instance, which is how a composite holding it knows what built it.

Example​

const tuple = new CairoTuple([1], '(core::integer::u8)', cairoTypeStrategy);
const result = tuple.dynamicSelector;
// result = "CairoTuple"

content​

readonly content: CairoType[]

Defined in: src/utils/cairoDataTypes/tuple.ts:68

The members, each already built as the Cairo type its position declares.

Example​

const tuple = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
const result = tuple.content.length;
// result = 2

tupleType​

readonly tupleType: string

Defined in: src/utils/cairoDataTypes/tuple.ts:79

The abi type this tuple was built for.

Example​

const tuple = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
const result = tuple.tupleType;
// result = "(core::integer::u8, core::integer::u32)"

Methods​

getTupleElementTypes()​

static getTupleElementTypes(tupleType): TupleMember[]

Defined in: src/utils/cairoDataTypes/tuple.ts:257

Split a tuple type into its members.

The reading itself is done by the tuple parser the request and response parsers already share, so both worlds see the same members. Only the empty tuple is handled here : that parser answers [''] for () in the Cairo 0 form, which would stand for one member rather than none.

Parameters​

tupleType​

string

the abi type to split

Returns​

TupleMember[]

the members, named ones as { name, type } A Cairo 1 type is also checked for having survived the split : the members are put back together and compared to what came in. That parser walks the string assuming members are separated by ', ', so a comma without its space makes it eat the next character and hand back a member type that does not exist — silently. Recomposing catches exactly that, and nothing else : a nested Result::<u8,u8> is read by bracket matching rather than by commas, comes back whole, and is left alone.

Cairo 0 has no such check, and needs none : every space is stripped before that type is split, so there is nothing to compare against.

Throws​

when a Cairo 1 tuple type does not survive being split and put back together

Example​

const result = CairoTuple.getTupleElementTypes('(core::integer::u8, core::integer::u32)');
// result = ["core::integer::u8", "core::integer::u32"]
const result2 = CairoTuple.getTupleElementTypes('(x:felt, y:felt)');
// result2 = [{ name: "x", type: "felt" }, { name: "y", type: "felt" }]
const result3 = CairoTuple.getTupleElementTypes('()');
// result3 = []
CairoTuple.getTupleElementTypes('(core::integer::u8,core::integer::u32)');
// throws Error('"(core::integer::u8,core::integer::u32)" is not a valid Cairo type
//              (its members do not recompose it, usually a missing space after a comma)')

extractTupleMembersNames()​

static extractTupleMembersNames(type): string[]

Defined in: src/utils/cairoDataTypes/tuple.ts:282

The names of the members, or their positions when the tuple does not name them.

Parameters​

type​

string

the abi type to read

Returns​

string[]

one name per member

Example​

const result = CairoTuple.extractTupleMembersNames('(core::integer::u8, core::integer::u32)');
// result = ["0", "1"]
const result2 = CairoTuple.extractTupleMembersNames('(x:felt, y:felt)');
// result2 = ["x", "y"]

validate()​

static validate(input, tupleType): void

Defined in: src/utils/cairoDataTypes/tuple.ts:304

Throw unless this input can be read as a tuple of this type.

Only the shape is checked here — a tuple type, and members given as a list or an object. What each member is worth is the business of the class its position declares, and is checked when that member is built.

Parameters​

input​

unknown

the members to check

tupleType​

string

the abi type they are meant for

Returns​

void

Throws​

when the type is not a tuple, or the input is neither an array nor an object

Example​

CairoTuple.validate([1, 2], '(core::integer::u8, core::integer::u32)'); // passes
CairoTuple.validate([1, 2], 'core::integer::u8');
// throws Error("The type core::integer::u8 is not a Cairo tuple. Expected format: (type1, type2, ...)")

is()​

static is(input, tupleType): boolean

Defined in: src/utils/cairoDataTypes/tuple.ts:330

Can this input be read as a tuple of this type?

The non-throwing form of CairoTuple.validate.

Parameters​

input​

unknown

the members to test

tupleType​

string

the abi type they are meant for

Returns​

boolean

true when the shape fits

Example​

const result = CairoTuple.is([1, 2], '(core::integer::u8, core::integer::u32)');
// result = true
const result2 = CairoTuple.is('nope', '(core::integer::u8, core::integer::u32)');
// result2 = false

isAbiType()​

static isAbiType(type): boolean

Defined in: src/utils/cairoDataTypes/tuple.ts:351

Is this abi type a tuple?

Parameters​

type​

string

the abi type to test

Returns​

boolean

true for (type1, type2), named or not, nested or not

Example​

const result = CairoTuple.isAbiType('(core::integer::u8, core::integer::u32)');
// result = true
const result2 = CairoTuple.isAbiType('core::integer::u32');
// result2 = false

compile()​

static compile(input): Object

Defined in: src/utils/cairoDataTypes/tuple.ts:382

Turn a list into the object CallData.compile reads a tuple from.

Parameters​

input​

any[]

the members, in order

Returns​

Object

the members keyed by position

Example​

const result = CairoTuple.compile([10, 20, 30]);
// result = { '0': 10, '1': 20, '2': 30 }

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/tuple.ts:368

Serialize to the felts a contract call carries.

The members follow one another with nothing in front : a tuple carries no length, since its type already says how many members it has and what each of them is.

Returns​

string[]

the members' felts, in order, flagged as compiled

Example​

const tuple = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
const result = tuple.toApiRequest();
// result = ["1", "2"]

decompose()​

decompose(strategyDecompose): Object

Defined in: src/utils/cairoDataTypes/tuple.ts:405

Read the tuple back as the plain values a caller reads.

Each member is handed to the strategy entry for its type — or for what built it, when that is a composite, which is what its dynamicSelector says. The result is keyed by member name for a Cairo 0 named tuple, and by position otherwise.

Parameters​

strategyDecompose​

AllowArray<CairoTypeStrategy>

how to read each member back

Returns​

Object

the members' values, keyed by name or by position

Throws​

when no strategy can read a member back

Example​

const tuple = new CairoTuple([1, 2], '(core::integer::u8, core::integer::u32)', cairoTypeStrategy);
const result = tuple.decompose(cairoTypeStrategy);
// result = { '0': 1n, '1': 2n }