Class: CairoInt128

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

A Cairo core::integer::i128 : a whole number in [-170141183460469231731687303715884105728, 170141183460469231731687303715884105727], 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 i128. 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.

A minus sign in front of a number is read as a sign, not as text : '-5' is -5, as -5 and -5n are. Only the signed integers read a string this way — for every other type, '-5' is text, encoded or refused as such.

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 CairoInt128(129445976596022050476432668810952994672).toBigInt(); //     129445976596022050476432668810952994672n
new CairoInt128('129445976596022050476432668810952994672').toBigInt(); //   129445976596022050476432668810952994672n
new CairoInt128('0x6162636465666768696a6b6c6d6e6f70').toBigInt(); // 129445976596022050476432668810952994672n
new CairoInt128('abcdefghijklmnop').toBigInt(); //    129445976596022050476432668810952994672n     the UTF-8 bytes of the text

// a negative value, reached three ways
new CairoInt128(-5).toBigInt(); //     -5n
new CairoInt128('-5').toBigInt(); //   -5n
new CairoInt128('-0x5').toBigInt(); // -5n     a sign, not the text "-0x5"

Constructors

Constructor

new CairoInt128(data): CairoInt128

Defined in: src/utils/cairoDataTypes/int128.ts:76

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

A string is read as a number when it spells one — decimal or hexadecimal, with or without a leading minus sign — and as UTF-8 text otherwise. Text therefore only fits here up to 16 ASCII characters : one more already makes a number past 170141183460469231731687303715884105727.

Parameters

data

unknown

the value to carry, within [-170141183460469231731687303715884105728, 170141183460469231731687303715884105727]

Returns

CairoInt128

Throws

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

Example

const result = new CairoInt128('abcdefghijklmnop').toApiRequest();
// result = ["129445976596022050476432668810952994672"]
const result2 = new CairoInt128('-5').toApiRequest();
// result2 = ["3618502788666131213697322783095070105623107215331596699973092056135872020476"]

Properties

abiSelector

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

Defined in: src/utils/cairoDataTypes/int128.ts:58

The abi type this class serializes.

Example

const result = CairoInt128.abiSelector;
// result = "core::integer::i128"

---

data

data: bigint

Defined in: src/utils/cairoDataTypes/int128.ts:48

The value, always as a bigint.

Example

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

Methods

__processData()

static __processData(data): bigint

Defined in: src/utils/cairoDataTypes/int128.ts:101

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 i128 range comes back untouched rather than raising.

A minus sign in front of a number makes it negative rather than text : '-5' and '-0x5' are both -5. This holds for the signed integers only — for any other type, such a string is text.

Parameters

data

unknown

the value to convert

Returns

bigint

the number the input spells, of whatever size

Example

const result = CairoInt128.__processData('abcdefghijklmnop');
// result = 129445976596022050476432668810952994672n
const result2 = CairoInt128.__processData('abcdefghijklmnopq');
// result2 = 33138170008581644921966763215603966636145n     (past the i128 range, and returned all the same)
const result3 = CairoInt128.__processData('-0x5');
// result3 = -5n     (a negative number, not the text "-0x5")

---

validate()

static validate(data): void

Defined in: src/utils/cairoDataTypes/int128.ts:204

Throw unless the value can be carried by an i128.

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 [-170141183460469231731687303715884105728, 170141183460469231731687303715884105727]. 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

CairoInt128.validate(5000000000); // passes
CairoInt128.validate(170141183460469231731687303715884105728);
// throws Error("Value is out of i128 range [-170141183460469231731687303715884105728, 170141183460469231731687303715884105727]")

---

is()

static is(data): boolean

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

Can this value be carried by an i128?

The non-throwing form of CairoInt128.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 an i128

Example

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

---

isAbiType()

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/int128.ts:256

Is this abi type the one this class serializes?

Parameters

abiType

string

the abi type to test

Returns

boolean

true for core::integer::i128

Example

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

---

factoryFromApiResponse()

static factoryFromApiResponse(responseIterator): CairoInt128

Defined in: src/utils/cairoDataTypes/int128.ts:275

Read one i128 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. A felt past half the prime is a negative number written as its field element, and is brought back below zero here.

Parameters

responseIterator

Iterator<string>

the response felts, positioned on this i128

Returns

CairoInt128

the i128 that was read

Example

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

---

toApiRequest()

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/int128.ts:128

Serialize to the single felt a contract call carries.

A negative value goes out as its field element, PRIME + value, which is what Cairo reads back as the negative number.

Returns

string[]

one decimal-string felt, flagged as compiled

Example

const result = new CairoInt128(5000000000).toApiRequest();
// result = ["5000000000"]
const result2 = new CairoInt128(-5000000000).toApiRequest();
// result2 = ["3618502788666131213697322783095070105623107215331596699973092056130872020481"]

---

toBigInt()

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/int128.ts:141

The value as a number.

Returns

bigint

the number this i128 holds, negative included

Example

const result = new CairoInt128(-5000000000).toBigInt();
// result = -5000000000n

---

decodeUtf8()

decodeUtf8(): string

Defined in: src/utils/cairoDataTypes/int128.ts:159

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 — a negative value is first wrapped to its two's complement, which rarely spells valid UTF-8 and so comes back as replacement characters.

Returns

string

the bytes decoded as UTF-8

Example

const result = new CairoInt128('abcdefghijklmnop').decodeUtf8();
// result = "abcdefghijklmnop"

---

toHexString()

toHexString(): string

Defined in: src/utils/cairoDataTypes/int128.ts:179

The value in hexadecimal, without padding.

A negative value has no hexadecimal form of its own here : it is written as its field element, PRIME + value, the positive number Cairo actually carries.

Returns

string

the number as a 0x-prefixed hex string

Example

const result = new CairoInt128(5000000000).toHexString();
// result = "0x12a05f200"
const result2 = new CairoInt128(-5000000000).toHexString();
// result2 = "0x800000000000010fffffffffffffffffffffffffffffffffffffffed5fa0e01"