Class: CairoUint96

Defined in: src/utils/cairoDataTypes/uint96.ts:30

A Cairo core::integer::u96 : a whole number in [0, 79228162514264337593543950335], carried in one felt252.

The value is kept as a bigint, so the shape of the input does not survive — 30138990049255557934854335340, '30138990049255557934854335340' and '0x6162636465666768696a6b6c' give the same u96. A string that reads as text rather than as a number is taken for its UTF-8 bytes, which is why 'abcdefghijkl' is 30138990049255557934854335340 and not a rejected input.

An already built instance is not an accepted input : handed back to the constructor it is seen as an object and refused. Inside the library it is unwrapCairoScalar that reduces an instance to its number before an abi slot receives it.

Example

// the same value, reached four ways
new CairoUint96(30138990049255557934854335340).toBigInt(); //     30138990049255557934854335340n
new CairoUint96('30138990049255557934854335340').toBigInt(); //   30138990049255557934854335340n
new CairoUint96('0x6162636465666768696a6b6c').toBigInt(); // 30138990049255557934854335340n
new CairoUint96('abcdefghijkl').toBigInt(); //    30138990049255557934854335340n     the UTF-8 bytes of the text

Constructors

Constructor

new CairoUint96(data): CairoUint96

Defined in: src/utils/cairoDataTypes/uint96.ts:80

Build from a number, a string or a boolean, refusing anything out of the u96 range.

A string is read as a number when it spells one — decimal or hexadecimal — and as UTF-8 text otherwise. Text therefore only fits here up to 12 ASCII characters : one more already makes a number past 79228162514264337593543950335.

Parameters

data

unknown

the value to carry, within [0, 79228162514264337593543950335]

Returns

CairoUint96

Throws

when the value is null, undefined, an object, a decimal number, '0x', or out of range

Example

const result = new CairoUint96('abcdefghijkl').toApiRequest();
// result = ["30138990049255557934854335340"]

Properties

abiSelector

static abiSelector: string = 'core::integer::u96'

Defined in: src/utils/cairoDataTypes/uint96.ts:49

The abi type this class serializes.

Example

const result = CairoUint96.abiSelector;
// result = "core::integer::u96"

---

abiSelectorBoundedInt

static abiSelectorBoundedInt: string = 'core::internal::bounded_int::BoundedInt::<0, 79228162514264337593543950335>'

Defined in: src/utils/cairoDataTypes/uint96.ts:63

The name a compiled abi actually gives this type.

Cairo has no u96 of its own : it is a bounded integer, and the compiler writes it out as its bounds. So CairoUint96.abiSelector above is the name one would expect and never meets, while this is the one a contract emits — both are recognized, here and in the parsing strategy.

Example

const result = CairoUint96.abiSelectorBoundedInt;
// result = "core::internal::bounded_int::BoundedInt::<0, 79228162514264337593543950335>"

---

data

data: bigint

Defined in: src/utils/cairoDataTypes/uint96.ts:39

The value, always as a bigint.

Example

const result = new CairoUint96('0x6162636465666768696a6b6c').data;
// result = 30138990049255557934854335340n

Methods

__processData()

static __processData(data): bigint

Defined in: src/utils/cairoDataTypes/uint96.ts:100

Turn an accepted input into its number, before the range is checked.

Nothing here refuses a value : validate is what reads this number and decides. So an input far outside the u96 range comes back untouched rather than raising.

Parameters

data

unknown

the value to convert

Returns

bigint

the number the input spells, of whatever size

Example

const result = CairoUint96.__processData('abcdefghijkl');
// result = 30138990049255557934854335340n
const result2 = CairoUint96.__processData('abcdefghijklm');
// result2 = 7715581452609422831322709847149n     (past the u96 range, and returned all the same)

---

validate()

static validate(data): void

Defined in: src/utils/cairoDataTypes/uint96.ts:180

Throw unless the value can be carried by a u96.

Five things are refused, each with its own message : a null or undefined value, an object or an array, a number with a decimal part, '0x', and a value outside [0, 79228162514264337593543950335]. A text string reaches that last check as the number its bytes spell, so 'abcdefghijklm' is refused for being out of range.

Parameters

data

unknown

the value to check

Returns

void

Throws

when the value is null, undefined, an object, a decimal number, '0x', or out of range

Example

CairoUint96.validate(5000000000); // passes
CairoUint96.validate(79228162514264337593543950336);
// throws Error("Value is out of u96 range [0, 79228162514264337593543950335]")

---

is()

static is(data): boolean

Defined in: src/utils/cairoDataTypes/uint96.ts:211

Can this value be carried by a u96?

The non-throwing form of CairoUint96.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 u96

Example

const result = CairoUint96.is('abcdefghijkl');
// result = true     (30138990049255557934854335340, the UTF-8 bytes of the text)
const result2 = CairoUint96.is('abcdefghijklm');
// result2 = false   (7715581452609422831322709847149, past the u96 range)

---

isAbiType()

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/uint96.ts:239

Is this abi type the one this class serializes?

Both names answer true : the one a reader would write, and the bounded-integer form a compiled abi actually carries. Only the second is ever met in the wild.

Parameters

abiType

string

the abi type to test

Returns

boolean

true for core::integer::u96 and for its bounded-integer name

Example

const result = CairoUint96.isAbiType('core::integer::u96');
// result = true
const result2 = CairoUint96.isAbiType(
  'core::internal::bounded_int::BoundedInt::<0, 79228162514264337593543950335>'
);
// result2 = true     the name a contract emits
const result3 = CairoUint96.isAbiType('core::felt252');
// result3 = false

---

factoryFromApiResponse()

static factoryFromApiResponse(responseIterator): CairoUint96

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

Read one u96 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 u96

Returns

CairoUint96

the u96 that was read

Example

const response = ['0x12a05f200'];
const result = CairoUint96.factoryFromApiResponse(response.values()).toBigInt();
// result = 5000000000n

---

toApiRequest()

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/uint96.ts:117

Serialize to the single felt a contract call carries.

Returns

string[]

one decimal-string felt, flagged as compiled

Example

const result = new CairoUint96(5000000000).toApiRequest();
// result = ["5000000000"]

---

toBigInt()

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/uint96.ts:130

The value as a number.

Returns

bigint

the number this u96 holds

Example

const result = new CairoUint96(79228162514264337593543950335).toBigInt();
// result = 79228162514264337593543950335n

---

decodeUtf8()

decodeUtf8(): string

Defined in: src/utils/cairoDataTypes/uint96.ts:146

Read the value back as the UTF-8 text its bytes spell.

Only a value that was text to begin with comes back as readable text. Any other number is decoded all the same, and what it gives is whatever its bytes happen to mean.

Returns

string

the bytes decoded as UTF-8

Example

const result = new CairoUint96('abcdefghijkl').decodeUtf8();
// result = "abcdefghijkl"

---

toHexString()

toHexString(): string

Defined in: src/utils/cairoDataTypes/uint96.ts:161

The value in hexadecimal, without padding.

Returns

string

the number as a 0x-prefixed hex string

Example

const result = new CairoUint96(5000000000).toHexString();
// result = "0x12a05f200"
const result2 = new CairoUint96(0).toHexString();
// result2 = "0x0"     (one digit, not "0x00")