Class: CairoBytes31

Defined in: src/utils/cairoDataTypes/bytes31.ts:57

A Cairo core::bytes_31::bytes31 : up to 31 bytes, carried in a single felt252.

The bytes are held right-aligned in a fixed 31-byte buffer, so the length of the input is not recoverable from the value — '0x41' and '0x0041' give the same bytes31. Reach for CairoByteArray when the byte count has to survive.

'0x' holds no byte at all, and is the same bytes31 as the empty string ''. Where a number type refuses '0x', a type made of bytes reads it as empty bytes, which is how an EVM tool writes them.

Example

// the same five characters, read two ways
new CairoBytes31('12345').toHexString(); //      "0x3039"        the number 12345
CairoBytes31.fromText('12345').toHexString(); // "0x3132333435"  the text '12345'

// no byte at all, written two ways
new CairoBytes31('').toApiRequest(); //   ["0"]
new CairoBytes31('0x').toApiRequest(); // ["0"]

Constructors

Constructor

new CairoBytes31(data): CairoBytes31

Defined in: src/utils/cairoDataTypes/bytes31.ts:108

Build from a single value, right-aligned in 31 bytes.

A string is read the way calldata reads it : '0x41' as the byte 0x41, '12345' as the number 12345, anything else as UTF-8 text. A string that spells a number therefore becomes that number, with no error raised — use CairoBytes31.fromText when the argument is text.

A value that is already a CairoBytes31 is adopted as it stands, its bytes copied rather than read a second time.

Parameters

data

unknown

the value to carry, 31 bytes at most

Returns

CairoBytes31

Throws

when the value needs more than 31 bytes

Example

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

Properties

MAX_BYTE_SIZE

static MAX_BYTE_SIZE: 31

Defined in: src/utils/cairoDataTypes/bytes31.ts:66

How many bytes a bytes31 holds, which is also the width of a ByteArray word.

Example

const result = CairoBytes31.MAX_BYTE_SIZE;
// result = 31

---

abiSelector

static abiSelector: "core::bytes_31::bytes31"

Defined in: src/utils/cairoDataTypes/bytes31.ts:89

The abi type this class serializes.

Example

const result = CairoBytes31.abiSelector;
// result = "core::bytes_31::bytes31"

---

data

data: Uint8Array

Defined in: src/utils/cairoDataTypes/bytes31.ts:79

The bytes, always exactly 31 of them.

A shorter input is right-aligned and the leading bytes left at zero, so this buffer does not record how long that input was.

Example

const result = new CairoBytes31('0x41').data.length;
// result = 31    (the byte 0x41 sits last, at index 30)

Methods

__processData()

static __processData(data): Uint8Array

Defined in: src/utils/cairoDataTypes/bytes31.ts:129

Turn any accepted input into its bytes, before they are right-aligned by the constructor.

The returned length is the length of the input, not 31 : validate reads it to decide whether the value fits. An input that is already a CairoBytes31 comes back as a copy of its 31 bytes.

Parameters

data

unknown

the value to convert

Returns

Uint8Array

the bytes, of whatever length the input implied

Throws

when the input is of a type this class does not read

Example

const result = CairoBytes31.__processData('0x4142').length;
// result = 2     (where CairoBytes31.__processData('Hello').length is 5)

---

fromText()

static fromText(text): CairoBytes31

Defined in: src/utils/cairoDataTypes/bytes31.ts:163

Build from text, with no interpretation of what the text looks like.

The constructor reads a string the way calldata does — '0x1a' as a hexadecimal number, '12345' as a decimal one — so a string spelling a number never reaches its UTF-8 branch. Here there is no such ambiguity: the argument is text, and its UTF-8 bytes are the value.

Parameters

text

string

the text to encode, 31 bytes max once UTF-8 encoded

Returns

CairoBytes31

the text as a bytes31

Example

const result = CairoBytes31.fromText('12345').toHexString();
// result = "0x3132333435"     (the text, where the constructor would read the number 0x3039)

---

validate()

static validate(data): void

Defined in: src/utils/cairoDataTypes/bytes31.ts:252

Throw unless the value fits in 31 bytes.

Length is all it weighs. Deciding it means converting the value first, so an input of a type this class does not read raises from __processData instead, with that method's message.

Parameters

data

unknown

the value to check

Returns

void

Throws

when the value needs more than 31 bytes, or is of an unread type

Example

CairoBytes31.validate('Hello'); // passes
CairoBytes31.validate('x'.repeat(32));
// throws Error("Data is too long: 32 bytes (max 31 bytes)")

---

is()

static is(data): boolean

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

Can this value be carried by a CairoBytes31?

The non-throwing form of CairoBytes31.validate, so a value of an unread type answers false here just as an over-long one does.

Parameters

data

unknown

the value to test

Returns

boolean

true when the value fits in a bytes31

Example

const result = CairoBytes31.is('Hello');
// result = true
const result2 = CairoBytes31.is('x'.repeat(32));
// result2 = false

---

isAbiType()

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/bytes31.ts:294

Is this abi type the one this class serializes?

Parameters

abiType

string

the abi type to test

Returns

boolean

true for core::bytes_31::bytes31

Example

const result = CairoBytes31.isAbiType('core::bytes_31::bytes31');
// result = true

---

factoryFromApiResponse()

static factoryFromApiResponse(responseIterator): CairoBytes31

Defined in: src/utils/cairoDataTypes/bytes31.ts:311

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

One felt is consumed, so successive calls read successive return values.

Parameters

responseIterator

Iterator<string>

the response felts, positioned on this bytes31

Returns

CairoBytes31

the bytes31 that was read

Example

const response = ['310939249775'];
const result = CairoBytes31.factoryFromApiResponse(response.values()).decodeUtf8();
// result = "Hello"

---

toApiRequest()

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/bytes31.ts:176

Serialize to the single felt a contract call carries.

Returns

string[]

one decimal-string felt, flagged as compiled

Example

const result = CairoBytes31.fromText('Hello').toApiRequest();
// result = ["310939249775"]

---

toBigInt()

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/bytes31.ts:192

The 31 bytes read as one big-endian number.

The padding zeros weigh nothing, so this is the same number whether the input was '0x41' or '0x0041'.

Returns

bigint

the bytes as a number, 0n when they are all zero

Example

const result = CairoBytes31.fromText('Hello').toBigInt();
// result = 310939249775n

---

decodeUtf8()

decodeUtf8(): string

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

Read the bytes back as UTF-8 text, leading zero bytes dropped.

Those zeros are the padding that fills the buffer, and nothing tells them apart from a zero byte the caller meant to carry — so a text opening on a NUL does not survive the round trip. Reach for CairoByteArray when it has to.

Returns

string

the bytes decoded as UTF-8, without their leading zeros

Example

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

---

toHexString()

toHexString(padded?): string

Defined in: src/utils/cairoDataTypes/bytes31.ts:233

The bytes in hexadecimal.

Bare, the leading zeros are dropped, which is the form a node returns for a felt. Padded, all 31 bytes are written out, which is the form a ByteArray data word takes.

Parameters

padded?

"padded"

write the 31 bytes in full, leading zeros included

Returns

string

the bytes as a 0x-prefixed hex string

Example

const result = new CairoBytes31('Hello').toHexString();
// result = "0x48656c6c6f"
const result2 = new CairoBytes31('Hello').toHexString('padded');
// result2 = "0x000000000000000000000000000000000000000000000000000048656c6c6f"