Skip to main content
Version: 11.x

Class: CairoFelt252

Defined in: src/utils/cairoDataTypes/felt.ts:32

A Cairo core::felt252 : the basic field element, an integer in [0, P).

P is the prime 2^251 + 17⋅2^192 + 1, so a felt252 is 252 bits — 63 hex symbols, or 31 bytes plus 4 bits. Every operation Cairo performs on a felt252 is computed modulo P.

A string is read the way calldata reads it : '0x3039' as a hexadecimal number, '12345' as a decimal one, anything else as UTF-8 text. Unlike CairoBytes31 and CairoByteArray this class has no door reserved for text, so a string that spells a number is always read as that number.

Example​

// the same five characters, read two ways
new CairoFelt252('12345').toBigInt(); // 12345n         the number 12345
new CairoFelt252('Hello').toBigInt(); // 310939249775n  the text, as UTF-8 bytes

Constructors​

Constructor​

new CairoFelt252(data): CairoFelt252

Defined in: src/utils/cairoDataTypes/felt.ts:71

Build from a number, a string or a boolean, refusing anything outside [0, P).

The bytes are stored without their leading zeros, so '0x0041' and '0x41' give the same felt252. A boolean is carried as 1 or 0.

Parameters​

data​

unknown

the value to carry, within [0, P)

Returns​

CairoFelt252

Throws​

when the value is null, undefined, of an unread type, or outside [0, P)

Example​

const result = new CairoFelt252('Hello').toApiRequest();
// result = ["310939249775"]

Properties​

abiSelector​

static abiSelector: "core::felt252"

Defined in: src/utils/cairoDataTypes/felt.ts:56

The abi type this class serializes.

Example​

const result = CairoFelt252.abiSelector;
// result = "core::felt252"

data​

data: Uint8Array

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

The bytes of the value, big-endian and without leading zeros.

The length is that of the value, not a fixed width : a felt252 holding 0 is one byte, and one holding 'Hello' is five. Nothing here records how wide the input was written.

Example​

const result = new CairoFelt252('Hello').data.length;
// result = 5
const result2 = new CairoFelt252(0).data.length;
// result2 = 1     (the single byte 0x00)

Methods​

__processData()​

static __processData(data): Uint8Array

Defined in: src/utils/cairoDataTypes/felt.ts:94

Turn an accepted input into its bytes, before the constructor strips their leading zeros.

The range is not checked here : validate is what reads these bytes and decides. Only the type is, and an input this class does not read raises rather than coming back.

Parameters​

data​

boolean | BigNumberish

the value to convert

Returns​

Uint8Array

the bytes of the value, of whatever length it implies

Throws​

when the input is neither a string, an integer, a bigint nor a boolean

Example​

const result = CairoFelt252.__processData('Hello').length;
// result = 5
CairoFelt252.__processData(1.5);
// throws Error("1.5 can't be computed by felt()")

assertRange()​

static assertRange(val): void

Defined in: src/utils/cairoDataTypes/felt.ts:183

Throw unless a number falls in the felt252 range [0, P).

This takes the number itself, where CairoFelt252.validate takes whatever a caller hands over. P is excluded : the largest felt252 is P - 1.

Parameters​

val​

bigint

the number to check

Returns​

void

Throws​

when the number is negative or greater than or equal to P

Example​

CairoFelt252.assertRange(0n); // passes
CairoFelt252.assertRange(-1n);
// throws Error("Value -1 is out of felt252 range [0, 3618502788666131213697322783095070105623107215331596699973092056135872020481)")

validate()​

static validate(data): void

Defined in: src/utils/cairoDataTypes/felt.ts:206

Throw unless the value can be carried by a felt252.

Null, undefined, any type this class does not read, and '0x' are refused first, each with its own message, then the value is converted and its range checked. A negative number does not reach that range check : converting it fails earlier, and the message comes from the conversion.

Parameters​

data​

unknown

the value to check

Returns​

void

Throws​

when the value is null, undefined, of an unread type, '0x', or outside [0, P)

Example​

CairoFelt252.validate('Hello'); // passes
CairoFelt252.validate({});
// throws Error("Unsupported data type 'object' for felt252. Expected string, number, bigint, or boolean")
CairoFelt252.validate('0x');
// throws Error("Invalid input: '0x' holds no hexadecimal digit")
CairoFelt252.validate(-1);
// throws Error("Cannot convert negative bigint -1 to Uint8Array")

is()​

static is(data): boolean

Defined in: src/utils/cairoDataTypes/felt.ts:237

Can this value be carried by a felt252?

The non-throwing form of CairoFelt252.validate, so it answers false for every input that one refuses, whatever the reason.

Parameters​

data​

unknown

the value to test

Returns​

boolean

true when the value fits in a felt252

Example​

const result = CairoFelt252.is('Hello');
// result = true
const result2 = CairoFelt252.is(-1);
// result2 = false

isAbiType()​

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/felt.ts:258

Is this abi type the one this class serializes?

Parameters​

abiType​

string

the abi type to test

Returns​

boolean

true for core::felt252

Example​

const result = CairoFelt252.isAbiType('core::felt252');
// result = true
const result2 = CairoFelt252.isAbiType('core::integer::u8');
// result2 = false

factoryFromApiResponse()​

static factoryFromApiResponse(responseIterator): CairoFelt252

Defined in: src/utils/cairoDataTypes/felt.ts:276

Read one felt252 off a contract response, advancing the iterator past it.

The felts a node returns are hex strings, and one is consumed per call, so successive calls read successive return values.

Parameters​

responseIterator​

Iterator<string>

the response felts, positioned on this felt252

Returns​

CairoFelt252

the felt252 that was read

Example​

const response = ['0x48656c6c6f'];
const result = CairoFelt252.factoryFromApiResponse(response.values()).decodeUtf8();
// result = "Hello"

toBigInt()​

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/felt.ts:119

The bytes read as one big-endian number.

Returns​

bigint

the value this felt252 holds

Example​

const result = new CairoFelt252('Hello').toBigInt();
// result = 310939249775n

decodeUtf8()​

decodeUtf8(): string

Defined in: src/utils/cairoDataTypes/felt.ts:137

Read the bytes back as UTF-8 text.

Only a value that was text to begin with comes back as readable text : the bytes of a number are decoded all the same, and what they spell is rarely what was meant.

Returns​

string

the bytes decoded as UTF-8

Example​

const result = new CairoFelt252('Hello').decodeUtf8();
// result = "Hello"
const result2 = new CairoFelt252('12345').decodeUtf8();
// result2 = "09"    (the number 12345 is the two bytes 0x30 0x39)

toHexString()​

toHexString(): string

Defined in: src/utils/cairoDataTypes/felt.ts:152

The value in hexadecimal, without padding.

Returns​

string

the value as a 0x-prefixed hex string

Example​

const result = new CairoFelt252('Hello').toHexString();
// result = "0x48656c6c6f"
const result2 = new CairoFelt252(0).toHexString();
// result2 = "0x0"     (one digit, not "0x00")

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/felt.ts:165

Serialize to the single felt a contract call carries.

Returns​

string[]

one decimal-string felt, flagged as compiled

Example​

const result = new CairoFelt252('Hello').toApiRequest();
// result = ["310939249775"]