Skip to main content
Version: 11.x

Class: CairoByteArray

Defined in: src/utils/cairoDataTypes/byteArray.ts:82

A Cairo core::byte_array::ByteArray : an arbitrary sequence of bytes, cut into words of 31.

A ByteArray is not Cairo's string type. It carries bytes, and text is only one of the things those bytes can mean — which is why the constructor reads a string the way calldata does, and why text has a door of its own, CairoByteArray.fromText.

'0x' holds no byte at all, and is the same ByteArray 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 four characters, read four ways
new CairoByteArray('Hello').toHexString(); //      "0x48656c6c6f"  text, nothing else fits
new CairoByteArray('12345').toHexString(); //      "0x3039"        the number 12345
new CairoByteArray('0x4142').toHexString(); //     "0x4142"        the bytes 0x41 0x42
CairoByteArray.fromText('12345').toHexString(); // "0x3132333435"  the text '12345'

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

Constructors​

Constructor​

new CairoByteArray(data, pendingWord, pendingWordLen): CairoByteArray

Defined in: src/utils/cairoDataTypes/byteArray.ts:144

Build from components that are already typed, the form an api response arrives in.

Parameters​

data​

CairoBytes31[]

the complete 31-byte words

pendingWord​

CairoFelt252

the bytes left after the last complete word

pendingWordLen​

CairoUint32

how many bytes pendingWord holds

Returns​

CairoByteArray

Example​

const pending = new CairoFelt252('0x48656c6c6f');
const result = new CairoByteArray([], pending, new CairoUint32(5)).decodeUtf8();
// result = "Hello"

Constructor​

new CairoByteArray(data): CairoByteArray

Defined in: src/utils/cairoDataTypes/byteArray.ts:164

Build from a single value, cut into words of 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 CairoByteArray.fromText when the argument is text.

A value that is already a ByteArray — an instance, or the object returned by byteArrayFromString — is adopted as it stands, its words never cut again.

Parameters​

data​

unknown

the value to carry

Returns​

CairoByteArray

Example​

const result = new CairoByteArray('Hello').toApiRequest();
// result = ["0", "310939249775", "5"]
const components = { data: [], pending_word: '0x41', pending_word_len: 1 };
const result2 = new CairoByteArray(components).decodeUtf8();
// result2 = "A"

Properties​

abiSelector​

static abiSelector: "core::byte_array::ByteArray"

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

The abi type this class serializes.

Example​

const result = CairoByteArray.abiSelector;
// result = "core::byte_array::ByteArray"

data​

data: CairoBytes31[] = []

Defined in: src/utils/cairoDataTypes/byteArray.ts:93

The complete words, 31 bytes each.

Bytes that do not fill a whole word are not here, but in CairoByteArray.pending_word.

Example​

const result = CairoByteArray.fromText('ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567').data.length;
// result = 1     (33 bytes : one full word of 31, and 2 bytes left pending)

pending_word​

pending_word: CairoFelt252

Defined in: src/utils/cairoDataTypes/byteArray.ts:107

The bytes left over after the last complete word, held as a felt252.

Its value alone does not say how many bytes it holds — a leading zero byte is invisible in a number — which is what CairoByteArray.pending_word_len is for.

Example​

const text = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567';
const result = CairoByteArray.fromText(text).pending_word.toHexString();
// result = "0x3637"     (the two characters '67' left after the first word)

pending_word_len​

pending_word_len: CairoUint32

Defined in: src/utils/cairoDataTypes/byteArray.ts:120

How many bytes CairoByteArray.pending_word holds, from 0 to 30.

The contract reads this length, so the same pending word under two lengths is two different values : 0x41 on one byte is A, on two bytes it is a NUL followed by A.

Example​

const result = new CairoByteArray('0x0041').pending_word_len.toBigInt();
// result = 2n    (where new CairoByteArray('0x41') gives 1n, for the same pending word)

Methods​

__processData()​

static __processData(inData): object

Defined in: src/utils/cairoDataTypes/byteArray.ts:206

Turn any accepted input into the three components of a ByteArray.

Shared by both constructor paths. An input that is already a ByteArray is adopted rather than cut again, so a pending word declared longer than its content keeps that declared length.

Parameters​

inData​

unknown

the value to convert

Returns​

object

the data, pending_word and pending_word_len components

data​

data: CairoBytes31[]

pending_word​

pending_word: CairoFelt252

pending_word_len​

pending_word_len: CairoUint32

Example​

const result = CairoByteArray.__processData('Hello').pending_word_len.toBigInt();
// result = 5n

fromText()​

static fromText(text): CairoByteArray

Defined in: src/utils/cairoDataTypes/byteArray.ts:302

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

The constructor reads a string the way calldata does — '0x1a' as two hexadecimal bytes, '12345' as a decimal number — because a ByteArray is a byte sequence, not Cairo's string type, and spelling those bytes in hexadecimal is a legitimate way to fill one. 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

Returns​

CairoByteArray

the UTF-8 bytes of the text, cut into 31-byte words

Example​

const result = CairoByteArray.fromText('12345').toHexString();
// result = "0x3132333435"     (the text, where the constructor would read the number 0x3039)
const result2 = CairoByteArray.fromText('0x4142').toHexString();
// result2 = "0x307834313432"  (six characters, where the constructor would read the bytes "AB")

validate()​

static validate(data): void

Defined in: src/utils/cairoDataTypes/byteArray.ts:511

Throw unless the value is of a kind this class can carry.

Called by the constructor, and called directly by the calldata validator before a contract call — so a value refused here never reaches serialization. It weighs the kind of the value, not its contents : a ByteArray object holding unusable components passes here and fails later, when those components are adopted.

Parameters​

data​

unknown

the value to check

Returns​

void

Throws​

when the value is of a kind this class does not carry

Example​

CairoByteArray.validate('12345'); //           passes, and will be read as the number 12345
CairoByteArray.validate(new Uint8Array(2)); // passes
CairoByteArray.validate(-1);
// throws Error("Invalid input for CairoByteArray: negative numbers are not supported")

is()​

static is(data): boolean

Defined in: src/utils/cairoDataTypes/byteArray.ts:564

Can this value be carried by a CairoByteArray?

The non-throwing form of CairoByteArray.validate, with the same reach : it answers on the kind of the value, not on the usability of its contents.

Parameters​

data​

any

the value to test

Returns​

boolean

true when the value is of a kind this class can carry

Example​

const result = CairoByteArray.is('12345');
// result = true
const result2 = CairoByteArray.is({ data: 'ABC' });
// result2 = false    (an object, and not the three components of a ByteArray)

isAbiType()​

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/byteArray.ts:583

Is this abi type the one this class serializes?

Parameters​

abiType​

string

the abi type to test

Returns​

boolean

true for core::byte_array::ByteArray

Example​

const result = CairoByteArray.isAbiType('core::byte_array::ByteArray');
// result = true

factoryFromApiResponse()​

static factoryFromApiResponse(responseIterator): CairoByteArray

Defined in: src/utils/cairoDataTypes/byteArray.ts:602

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

The felts are consumed in the order a contract emits them : how many complete words follow, those words, then the pending word and its length. The iterator is left on the next value, so successive calls read successive return values.

Parameters​

responseIterator​

Iterator<string>

the response felts, positioned on this ByteArray

Returns​

CairoByteArray

the ByteArray that was read

Example​

const response = ['0', '310939249775', '5'];
const result = CairoByteArray.factoryFromApiResponse(response.values()).decodeUtf8();
// result = "Hello"

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/byteArray.ts:316

Serialize to the felt sequence a contract call carries : the number of complete words, each of them, then the pending word and its length.

Returns​

string[]

the decimal-string felts, flagged as compiled

Example​

const result = CairoByteArray.fromText('Hello').toApiRequest();
// result = ["0", "310939249775", "5"]

decodeUtf8()​

decodeUtf8(): string

Defined in: src/utils/cairoDataTypes/byteArray.ts:342

Read the bytes back as UTF-8 text.

The words are concatenated before decoding, so a multi-byte character split across two of them survives. Bytes that are not valid UTF-8 come back as replacement characters rather than as an error, so succeeding here does not prove the ByteArray was carrying text.

Returns​

string

the bytes decoded as UTF-8

Example​

const result = CairoByteArray.fromText('héllo').decodeUtf8();
// result = "héllo"    (5 characters, 6 bytes)
const result2 = new CairoByteArray('12345').decodeUtf8();
// result2 = "09"      (the number 12345 is the two bytes 0x30 0x39)

toBigInt()​

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/byteArray.ts:363

The whole byte sequence read as one big-endian number.

A number has no room for a leading zero byte, so that byte is lost here. Use CairoByteArray.toHexString when the byte count matters.

Returns​

bigint

the bytes as a number, 0n when there are none

Example​

const result = CairoByteArray.fromText('Hello').toBigInt();
// result = 310939249775n
const result2 = new CairoByteArray('0x0041').toBigInt();
// result2 = 65n     (two bytes in, one byte out - toHexString keeps both)

toHexString()​

toHexString(): string

Defined in: src/utils/cairoDataTypes/byteArray.ts:393

The whole byte sequence in hexadecimal, leading zero bytes included.

This is the faithful view : two hex digits per byte, whatever their value. An empty ByteArray and one holding a single zero byte both read as a zero here, which is the one case this form does not separate.

Returns​

string

the bytes as a 0x-prefixed hex string, "0x0" when there are none

Example​

const result = new CairoByteArray('0x0041').toHexString();
// result = "0x0041"    (where toBigInt() gives 65n, having dropped the first byte)

toBuffer()​

toBuffer(): any

Defined in: src/utils/cairoDataTypes/byteArray.ts:409

The whole byte sequence as a Buffer, leading zero bytes included.

Returns​

any

a copy of the bytes, empty when there are none

Example​

const result = CairoByteArray.fromText('Hello').toBuffer().toString('hex');
// result = "48656c6c6f"

hash()​

hash(): string

Defined in: src/utils/cairoDataTypes/byteArray.ts:429

Compute the Pedersen hash of this ByteArray, following OpenZeppelin's hash_byte_array algorithm.

Serializes the ByteArray to its felt252 components (data array length, each data chunk, pending_word, pending_word_len), then chains Pedersen hash over all elements starting from 0, and finalizes with the total element count.

Returns​

string

hex-string felt252 Pedersen hash of the ByteArray

Example​

const ba = new CairoByteArray('Hello');
const result = ba.hash();
// result = 0x15d19ad651ffaf8e90a13938db2081fa3ff01de0712e00cbe69891bace66c51

toElements()​

toElements(): Uint8Array<ArrayBufferLike>[]

Defined in: src/utils/cairoDataTypes/byteArray.ts:454

The words as raw byte buffers : every complete word, then the pending one.

Concatenating them gives the original byte sequence back. A complete word is always 31 bytes, while the last buffer holds exactly pending_word_len bytes — zero-padded on the left when the pending word is shorter than its declared length. A pending length of 0 yields no last buffer.

Returns​

Uint8Array<ArrayBufferLike>[]

one buffer per word, in order

Example​

const text = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567';
const result = CairoByteArray.fromText(text).toElements().map((word) => word.length);
// result = [31, 2]