Class: CairoStruct
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:35
A Cairo struct : a fixed set of named members, each of its own type.
Unlike a tuple or an array, a struct has no shape to recognize — its abi type is just the name
the contract gave it, my_contract::Point, which looks like any other type. So there is no
isAbiType here : a struct is found by its exact name among a strategy's constructors, and the
strategy that carries those names is built from the abi that declares them.
On the wire a struct is its members one after another, with nothing in front — its shape is entirely in the abi, exactly as a tuple's is in its type.
Example
const point: AbiStruct = {
type: 'struct',
name: 'test::Point',
members: [
{ name: 'x', type: 'core::integer::u8' },
{ name: 'y', type: 'core::integer::u32' },
],
};
const strategies = [cairoTypeStrategy, structStrategy([point])];
const struct = new CairoStruct({ x: 1, y: 2 }, point, strategies);
struct.toApiRequest(); // ["1", "2"]
struct.decompose(strategies); // { x: 1n, y: 2n }
Constructors
Constructor
new CairoStruct(
content,abiStruct,parsingStrategy):CairoStruct
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:88
Build a struct, from values a caller passed or from the felts of a response.
An object is read by the member names the abi declares, in the abi's order — so the order the caller wrote them in does not matter. An array is taken as already being in that order.
Parameters
content
unknown
the members, as an object, an array, or the response iterator
abiStruct
the abi definition of this struct
parsingStrategy
how to build each member, which must carry this struct's own name for a struct that holds another
Returns
CairoStruct
Throws
when a member is missing, when the count does not match, or when a member type no strategy knows is met
Example
new CairoStruct({ x: 1, y: 2 }, point, strategies).toApiRequest(); // ["1", "2"]
new CairoStruct({ y: 2, x: 1 }, point, strategies).toApiRequest(); // ["1", "2"] abi order
new CairoStruct([1, 2], point, strategies).toApiRequest(); // ["1", "2"]
Properties
dynamicSelector
readonlydynamicSelector:string
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:48
The name this struct is registered under, which is the name the abi gave it.
Every other composite has one selector for the whole class; a struct has one per struct, so this is set from the abi rather than declared on the class.
Example
const struct = new CairoStruct({ x: 1, y: 2 }, point, strategies);
const result = struct.dynamicSelector;
// result = "test::Point"
content
readonlycontent:CairoType[]
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:58
The members, each already built as the type the abi declares for it.
Example
const result = new CairoStruct({ x: 1, y: 2 }, point, strategies).content.length;
// result = 2
abiStruct
readonlyabiStruct:AbiStruct
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:68
The abi definition this struct was built from.
Example
const result = new CairoStruct({ x: 1, y: 2 }, point, strategies).abiStruct.name;
// result = "test::Point"
Methods
getStructMembersTypes()
staticgetStructMembersTypes(abiStruct):string[]
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:195
The types of the members, in the abi's order.
Parameters
abiStruct
the abi definition to read
Returns
string[]
one type per member
Example
const result = CairoStruct.getStructMembersTypes(point);
// result = ["core::integer::u8", "core::integer::u32"]
extractStructMembersNames()
staticextractStructMembersNames(abiStruct):string[]
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:209
The names of the members, in the abi's order.
Parameters
abiStruct
the abi definition to read
Returns
string[]
one name per member
Example
const result = CairoStruct.extractStructMembersNames(point);
// result = ["x", "y"]
validate()
staticvalidate(input,abiStruct?):void
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:229
Throw unless this input can be read as this struct.
Given an abi, the member count is checked too : a struct is a fixed set, so a list of the wrong size is refused rather than padded or cut. Without one, only the shape is checked.
Parameters
input
unknown
the members to check
abiStruct?
the abi definition, when there is one to check against
Returns
void
Throws
when the input is neither an array nor an object, when the abi is not a struct, or when the member count does not match
Example
CairoStruct.validate({ x: 1, y: 2 }, point); // passes
CairoStruct.validate([1], point);
// throws Error("Invalid input: expected 2 members, got 1")
is()
staticis(input,abiStruct?):boolean
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:260
Can this input be read as this struct?
The non-throwing form of CairoStruct.validate.
Parameters
input
unknown
the members to test
abiStruct?
the abi definition, when there is one to check against
Returns
boolean
true when the shape fits
Example
const result = CairoStruct.is({ x: 1, y: 2 }, point);
// result = true
const result2 = CairoStruct.is([1], point);
// result2 = false (one member short)
toApiRequest()
toApiRequest():
string[]
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:281
Serialize to the felts a contract call carries.
The members follow one another with nothing in front, as a tuple's do : what a struct holds is said by the abi, not by the calldata.
Returns
string[]
the members' felts, in the abi's order, flagged as compiled
Example
const result = new CairoStruct({ x: 1, y: 2 }, point, strategies).toApiRequest();
// result = ["1", "2"]
decompose()
decompose(
strategyDecompose):Object
Defined in: src/utils/cairoDataTypes/cairoStruct.ts:299
Read the struct back as the plain object 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.
Parameters
strategyDecompose
how to read each member back
Returns
Object
the members' values, keyed by name
Throws
when no strategy can read a member back
Example
const result = new CairoStruct({ x: 1, y: 2 }, point, strategies).decompose(strategies);
// result = { x: 1n, y: 2n }