Skip to main content
Version: 11.x

Class: CairoUint256

Defined in: src/utils/cairoDataTypes/uint256.ts:95

A Cairo core::integer::u256 : a whole number from 0 to 2^256 - 1, carried in two felts.

A felt252 is too narrow to hold a u256, so the number is cut into two u128 halves — low for the bottom 128 bits, high for the top — and a contract call carries both, low first. Either half can be given directly, which is how a response from a node is read back.

Example​

const small = new CairoUint256(255);
// small.low = 255n, small.high = 0n
const big = new CairoUint256(2n ** 130n + 5n);
// big.low = 5n, big.high = 4n

Constructors​

Constructor​

new CairoUint256(data): CairoUint256

Defined in: src/utils/cairoDataTypes/uint256.ts:139

Build from one number, cutting it into its two halves (Lib usage).

A Uint256 object is accepted here too : it already carries low and high, and both are checked as u128 rather than the whole being cut again.

Parameters​

data​

unknown

the value to carry, within [0, 2^256 - 1]

Returns​

CairoUint256

Throws​

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

Example​

const result = new CairoUint256(2n ** 130n + 5n).toApiRequest();
// result = ["5", "4"]

Constructor​

new CairoUint256(low, high): CairoUint256

Defined in: src/utils/cairoDataTypes/uint256.ts:151

Build from the two halves as they arrive, already cut (Api response).

Parameters​

low​

BigNumberish

the bottom 128 bits

high​

BigNumberish

the top 128 bits

Returns​

CairoUint256

Throws​

when either half is null, undefined, text, '0x', not a number, a decimal number, or outside the u128 range

Example​

const result = new CairoUint256(5, 4).toBigInt();
// result = 1361129467683753853853498429727072845829n

Properties​

abiSelector​

static abiSelector: "core::integer::u256"

Defined in: src/utils/cairoDataTypes/uint256.ts:124

The abi type this class serializes.

Example​

const result = CairoUint256.abiSelector;
// result = "core::integer::u256"

low​

low: bigint

Defined in: src/utils/cairoDataTypes/uint256.ts:104

The bottom 128 bits of the value.

Example​

const result = new CairoUint256(2n ** 130n + 5n).low;
// result = 5n

high​

high: bigint

Defined in: src/utils/cairoDataTypes/uint256.ts:114

The top 128 bits of the value.

Example​

const result = new CairoUint256(2n ** 130n + 5n).high;
// result = 4n

Methods​

validate()​

static validate(bigNumberish): bigint

Defined in: src/utils/cairoDataTypes/uint256.ts:195

Throw unless a whole value can be represented as a u256, and give back its number.

A string is only accepted while it spells a number, in base 10 or 16 : one that does not is refused as text, and '0x', which holds no digit, is refused too. So is an object, a Uint256 one included : its two halves are checked by CairoUint256.validateProps, which is what the constructor calls for it.

Parameters​

bigNumberish​

unknown

the value to check

Returns​

bigint

the value as a number, once accepted

Throws​

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

Example​

const result = CairoUint256.validate(255);
// result = 255n
CairoUint256.validate(-1);
// throws Error("bigNumberish is smaller than UINT_256_MIN")
CairoUint256.validate('abc');
// throws Error("Invalid input: a u256 cannot be built from text")
CairoUint256.validate(1.5);
// throws Error("Invalid input: decimal numbers are not supported, only integers")

validateProps()​

static validateProps(low, high): object

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

Throw unless both halves are u128, and give them back as numbers.

This is the check for a value that arrives already cut. Each half is bounded on its own : it is the pair that makes a u256, so neither can overflow into the other.

Parameters​

low​

BigNumberish

the bottom 128 bits

high​

BigNumberish

the top 128 bits

Returns​

object

the two halves as numbers

low​

low: bigint = bigIntLow

high​

high: bigint = bigIntHigh

Throws​

when either half is null, undefined, text, '0x', not a number, a decimal number, or outside the u128 range

Example​

const result = CairoUint256.validateProps(5, 4);
// result = { low: 5n, high: 4n }
CairoUint256.validateProps(-1, 4);
// throws Error("low is out of range UINT_256_LOW_MIN - UINT_256_LOW_MAX")
CairoUint256.validateProps(1.5, 4);
// throws Error("low must be an integer")
CairoUint256.validateProps('abc', 4);
// throws Error("low cannot be built from text")

is()​

static is(bigNumberish): boolean

Defined in: src/utils/cairoDataTypes/uint256.ts:277

Can this value be represented as a u256?

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

Parameters​

bigNumberish​

unknown

the value to test

Returns​

boolean

true when the value fits in a u256

Example​

const result = CairoUint256.is(255);
// result = true
const result2 = CairoUint256.is(-1);
// result2 = false

isAbiType()​

static isAbiType(abiType): abiType is "core::integer::u256"

Defined in: src/utils/cairoDataTypes/uint256.ts:298

Is this abi type the one this class serializes?

Parameters​

abiType​

string

the abi type to test

Returns​

abiType is "core::integer::u256"

true for core::integer::u256

Example​

const result = CairoUint256.isAbiType('core::integer::u256');
// result = true
const result2 = CairoUint256.isAbiType('core::integer::u512');
// result2 = false

factoryFromApiResponse()​

static factoryFromApiResponse(responseIterator): CairoUint256

Defined in: src/utils/cairoDataTypes/uint256.ts:315

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

Two felts are consumed, low first, since that is how a u256 travels.

Parameters​

responseIterator​

Iterator<string>

the response felts, positioned on this u256

Returns​

CairoUint256

the u256 that was read

Example​

const response = ['0x5', '0x4'];
const result = CairoUint256.factoryFromApiResponse(response.values()).toBigInt();
// result = 1361129467683753853853498429727072845829n

toBigInt()​

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/uint256.ts:330

The two halves put back together as one number.

Returns​

bigint

the value this u256 holds

Example​

const result = new CairoUint256(5, 4).toBigInt();
// result = 1361129467683753853853498429727072845829n

toUint256HexString()​

toUint256HexString(): object

Defined in: src/utils/cairoDataTypes/uint256.ts:343

The two halves as a Uint256 of hexadecimal strings.

Returns​

object

both halves, 0x-prefixed and unpadded

low​

low: string

high​

high: string

Example​

const result = new CairoUint256(255).toUint256HexString();
// result = { low: "0xff", high: "0x0" }

toUint256DecimalString()​

toUint256DecimalString(): object

Defined in: src/utils/cairoDataTypes/uint256.ts:359

The two halves as a Uint256 of decimal strings.

Returns​

object

both halves, in base 10

low​

low: string

high​

high: string

Example​

const result = new CairoUint256(255).toUint256DecimalString();
// result = { low: "255", high: "0" }

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/uint256.ts:375

Serialize to the two felts a contract call carries.

Returns​

string[]

the two halves as decimal strings, low first, flagged as compiled

Example​

const result = new CairoUint256(255).toApiRequest();
// result = ["255", "0"]