Skip to main content
Version: 11.x

Class: CairoUint128

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

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

The value is kept as a bigint, so the shape of the input does not survive — 129445976596022050476432668810952994672, '129445976596022050476432668810952994672' and '0x6162636465666768696a6b6c6d6e6f70' give the same u128. A string that reads as text rather than as a number is taken for its UTF-8 bytes, which is why 'abcdefghijklmnop' is 129445976596022050476432668810952994672 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 CairoUint128(129445976596022050476432668810952994672).toBigInt(); //     129445976596022050476432668810952994672n
new CairoUint128('129445976596022050476432668810952994672').toBigInt(); //   129445976596022050476432668810952994672n
new CairoUint128('0x6162636465666768696a6b6c6d6e6f70').toBigInt(); // 129445976596022050476432668810952994672n
new CairoUint128('abcdefghijklmnop').toBigInt(); //    129445976596022050476432668810952994672n     the UTF-8 bytes of the text

Constructors​

Constructor​

new CairoUint128(data): CairoUint128

Defined in: src/utils/cairoDataTypes/uint128.ts:65

Build from a number, a string or a boolean, refusing anything out of the u128 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 16 ASCII characters : one more already makes a number past 340282366920938463463374607431768211455.

Parameters​

data​

unknown

the value to carry, within [0, 340282366920938463463374607431768211455]

Returns​

CairoUint128

Throws​

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

Example​

const result = new CairoUint128('abcdefghijklmnop').toApiRequest();
// result = ["129445976596022050476432668810952994672"]

Properties​

abiSelector​

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

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

The abi type this class serializes.

Example​

const result = CairoUint128.abiSelector;
// result = "core::integer::u128"

data​

data: bigint

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

The value, always as a bigint.

Example​

const result = new CairoUint128('0x6162636465666768696a6b6c6d6e6f70').data;
// result = 129445976596022050476432668810952994672n

Methods​

__processData()​

static __processData(data): bigint

Defined in: src/utils/cairoDataTypes/uint128.ts:85

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 u128 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 = CairoUint128.__processData('abcdefghijklmnop');
// result = 129445976596022050476432668810952994672n
const result2 = CairoUint128.__processData('abcdefghijklmnopq');
// result2 = 33138170008581644921966763215603966636145n     (past the u128 range, and returned all the same)

validate()​

static validate(data): void

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

Throw unless the value can be carried by a u128.

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, 340282366920938463463374607431768211455]. A text string reaches that last check as the number its bytes spell, so 'abcdefghijklmnopq' 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​

CairoUint128.validate(5000000000); // passes
CairoUint128.validate(340282366920938463463374607431768211456);
// throws Error("Value is out of u128 range [0, 340282366920938463463374607431768211455]")

is()​

static is(data): boolean

Defined in: src/utils/cairoDataTypes/uint128.ts:196

Can this value be carried by a u128?

The non-throwing form of CairoUint128.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 u128

Example​

const result = CairoUint128.is('abcdefghijklmnop');
// result = true     (129445976596022050476432668810952994672, the UTF-8 bytes of the text)
const result2 = CairoUint128.is('abcdefghijklmnopq');
// result2 = false   (33138170008581644921966763215603966636145, past the u128 range)

isAbiType()​

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/uint128.ts:217

Is this abi type the one this class serializes?

Parameters​

abiType​

string

the abi type to test

Returns​

boolean

true for core::integer::u128

Example​

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

factoryFromApiResponse()​

static factoryFromApiResponse(responseIterator): CairoUint128

Defined in: src/utils/cairoDataTypes/uint128.ts:235

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

Returns​

CairoUint128

the u128 that was read

Example​

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

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/uint128.ts:102

Serialize to the single felt a contract call carries.

Returns​

string[]

one decimal-string felt, flagged as compiled

Example​

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

toBigInt()​

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/uint128.ts:115

The value as a number.

Returns​

bigint

the number this u128 holds

Example​

const result = new CairoUint128(340282366920938463463374607431768211455).toBigInt();
// result = 340282366920938463463374607431768211455n

decodeUtf8()​

decodeUtf8(): string

Defined in: src/utils/cairoDataTypes/uint128.ts:131

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 CairoUint128('abcdefghijklmnop').decodeUtf8();
// result = "abcdefghijklmnop"

toHexString()​

toHexString(): string

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

The value in hexadecimal, without padding.

Returns​

string

the number as a 0x-prefixed hex string

Example​

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