starknet 11.0.0-beta.4 → 11.0.0-beta.6

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [11.0.0-beta.6](https://github.com/starknet-io/starknet.js/compare/v11.0.0-beta.5...v11.0.0-beta.6) (2026-08-25)
+
+### Bug Fixes
+
+- **calldata:** text reaches a ByteArray, whatever it spells ([509c9f8](https://github.com/starknet-io/starknet.js/commit/509c9f80f02ef1f5751bcdbd45a8612c2479f6f8))
+
+# [11.0.0-beta.5](https://github.com/starknet-io/starknet.js/compare/v11.0.0-beta.4...v11.0.0-beta.5) (2026-08-24)
+
+### Bug Fixes
+
+- **calldata:** long string chunks stay text, at any ABI depth ([06638d9](https://github.com/starknet-io/starknet.js/commit/06638d9b7317caf3e20087c9f92a05a499157213))
+
 # [11.0.0-beta.4](https://github.com/starknet-io/starknet.js/compare/v11.0.0-beta.3...v11.0.0-beta.4) (2026-08-21)
 
 ### Bug Fixes

package/dist/index.d.ts

@@ -10351,11 +10351,82 @@ declare class CairoFixedArray {
     static isTypeFixedArray(type: string): boolean;
 }
 
+/**
+ * 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.
+ * @example
+ * ```typescript
+ * // the same five characters, read two ways
+ * new CairoBytes31('12345').toHexString(); //      "0x3039"        the number 12345
+ * CairoBytes31.fromText('12345').toHexString(); // "0x3132333435"  the text '12345'
+ * ```
+ */
 declare class CairoBytes31 {
+    /**
+     * How many bytes a bytes31 holds, which is also the width of a `ByteArray` word.
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.MAX_BYTE_SIZE;
+     * // result = 31
+     * ```
+     */
     static MAX_BYTE_SIZE: 31;
+    /**
+     * 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
+     * ```typescript
+     * const result = new CairoBytes31('0x41').data.length;
+     * // result = 31    (the byte 0x41 sits last, at index 30)
+     * ```
+     */
     data: Uint8Array;
+    /**
+     * The abi type this class serializes.
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.abiSelector;
+     * // result = "core::bytes_31::bytes31"
+     * ```
+     */
     static abiSelector: "core::bytes_31::bytes31";
+    /**
+     * 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 {@link 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.
+     * @param {string | Uint8Array | Buffer | CairoBytes31} data the value to carry, 31 bytes at most
+     * @throws {Error} when the value needs more than 31 bytes
+     * @example
+     * ```typescript
+     * const result = new CairoBytes31('Hello').toApiRequest();
+     * // result = ["310939249775"]
+     * ```
+     */
     constructor(data: string | Uint8Array | Buffer | unknown);
+    /**
+     * 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.
+     * @param {Uint8Array | string | Buffer | CairoBytes31} data the value to convert
+     * @returns {Uint8Array} the bytes, of whatever length the input implied
+     * @throws {Error} when the input is of a type this class does not read
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.__processData('0x4142').length;
+     * // result = 2     (where CairoBytes31.__processData('Hello').length is 5)
+     * ```
+     */
     static __processData(data: Uint8Array | string | Buffer | unknown): Uint8Array;
     /**
      * Build from text, with no interpretation of what the text looks like.
@@ -10372,19 +10443,116 @@ declare class CairoBytes31 {
      * ```
      */
     static fromText(text: string): CairoBytes31;
+    /**
+     * Serialize to the single felt a contract call carries.
+     * @returns {string[]} one decimal-string felt, flagged as compiled
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.fromText('Hello').toApiRequest();
+     * // result = ["310939249775"]
+     * ```
+     */
     toApiRequest(): string[];
+    /**
+     * 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
+     * ```typescript
+     * const result = CairoBytes31.fromText('Hello').toBigInt();
+     * // result = 310939249775n
+     * ```
+     */
     toBigInt(): bigint;
+    /**
+     * 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
+     * ```typescript
+     * 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)
+     * ```
+     */
     decodeUtf8(): string;
     /**
-     * @param padded flag for including leading zeros
+     * 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.
+     * @param {'padded'} [padded] write the 31 bytes in full, leading zeros included
+     * @returns {string} the bytes as a 0x-prefixed hex string
+     * @example
+     * ```typescript
+     * const result = new CairoBytes31('Hello').toHexString();
+     * // result = "0x48656c6c6f"
+     * const result2 = new CairoBytes31('Hello').toHexString('padded');
+     * // result2 = "0x000000000000000000000000000000000000000000000000000048656c6c6f"
+     * ```
      */
     toHexString(padded?: 'padded'): string;
+    /**
+     * 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.
+     * @param {Uint8Array | string | Buffer | CairoBytes31} data the value to check
+     * @throws {Error} when the value needs more than 31 bytes, or is of an unread type
+     * @example
+     * ```typescript
+     * CairoBytes31.validate('Hello'); // passes
+     * CairoBytes31.validate('x'.repeat(32));
+     * // throws Error("Data is too long: 32 bytes (max 31 bytes)")
+     * ```
+     */
     static validate(data: Uint8Array | string | Buffer | unknown): void;
-    static is(data: Uint8Array | string | Buffer): boolean;
     /**
-     * Check if provided abi type is this data type
+     * Can this value be carried by a CairoBytes31?
+     *
+     * The non-throwing form of {@link CairoBytes31.validate}, so a value of an unread type answers
+     * false here just as an over-long one does.
+     * @param {Uint8Array | string | Buffer | CairoBytes31} data the value to test
+     * @returns {boolean} true when the value fits in a bytes31
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.is('Hello');
+     * // result = true
+     * const result2 = CairoBytes31.is('x'.repeat(32));
+     * // result2 = false
+     * ```
+     */
+    static is(data: Uint8Array | string | Buffer | unknown): boolean;
+    /**
+     * Is this abi type the one this class serializes?
+     * @param {string} abiType the abi type to test
+     * @returns {boolean} true for `core::bytes_31::bytes31`
+     * @example
+     * ```typescript
+     * const result = CairoBytes31.isAbiType('core::bytes_31::bytes31');
+     * // result = true
+     * ```
      */
     static isAbiType(abiType: string): boolean;
+    /**
+     * Read one bytes31 off a contract response, advancing the iterator past it.
+     *
+     * One felt is consumed, so successive calls read successive return values.
+     * @param {Iterator<string>} responseIterator the response felts, positioned on this bytes31
+     * @returns {CairoBytes31} the bytes31 that was read
+     * @example
+     * ```typescript
+     * const response = ['310939249775'];
+     * const result = CairoBytes31.factoryFromApiResponse(response.values()).decodeUtf8();
+     * // result = "Hello"
+     * ```
+     */
     static factoryFromApiResponse(responseIterator: Iterator<string>): CairoBytes31;
 }
 
@@ -10431,34 +10599,201 @@ declare class CairoUint32 {
     static factoryFromApiResponse(responseIterator: Iterator<string>): CairoUint32;
 }
 
+/**
+ * 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, {@link CairoByteArray.fromText}.
+ * @example
+ * ```typescript
+ * // 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'
+ * ```
+ */
 declare class CairoByteArray {
     /**
-     * entire dataset
+     * The complete words, 31 bytes each.
+     *
+     * Bytes that do not fill a whole word are not here, but in {@link CairoByteArray.pending_word}.
+     * @example
+     * ```typescript
+     * const result = CairoByteArray.fromText('ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567').data.length;
+     * // result = 1     (33 bytes : one full word of 31, and 2 bytes left pending)
+     * ```
      */
     data: CairoBytes31[];
     /**
-     * cairo specific implementation helper
+     * 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 {@link CairoByteArray.pending_word_len} is for.
+     * @example
+     * ```typescript
+     * const text = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567';
+     * const result = CairoByteArray.fromText(text).pending_word.toHexString();
+     * // result = "0x3637"     (the two characters '67' left after the first word)
+     * ```
      */
     pending_word: CairoFelt252;
     /**
-     * cairo specific implementation helper
+     * How many bytes {@link 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
+     * ```typescript
+     * const result = new CairoByteArray('0x0041').pending_word_len.toBigInt();
+     * // result = 2n    (where new CairoByteArray('0x41') gives 1n, for the same pending word)
+     * ```
      */
     pending_word_len: CairoUint32;
+    /**
+     * The abi type this class serializes.
+     * @example
+     * ```typescript
+     * const result = CairoByteArray.abiSelector;
+     * // result = "core::byte_array::ByteArray"
+     * ```
+     */
     static abiSelector: "core::byte_array::ByteArray";
     /**
-     * byteArray from typed components
+     * Build from components that are already typed, the form an api response arrives in.
+     * @param {CairoBytes31[]} data the complete 31-byte words
+     * @param {CairoFelt252} pendingWord the bytes left after the last complete word
+     * @param {CairoUint32} pendingWordLen how many bytes `pendingWord` holds
+     * @example
+     * ```typescript
+     * const pending = new CairoFelt252('0x48656c6c6f');
+     * const result = new CairoByteArray([], pending, new CairoUint32(5)).decodeUtf8();
+     * // result = "Hello"
+     * ```
      */
     constructor(data: CairoBytes31[], pendingWord: CairoFelt252, pendingWordLen: CairoUint32);
-    constructor(data: BigNumberish | Buffer | Uint8Array | unknown);
-    static __processData(inData: BigNumberish | Buffer | Uint8Array | unknown): {
+    /**
+     * 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 {@link 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.
+     * @param {BigNumberish | Buffer | Uint8Array | ByteArray} data the value to carry
+     * @example
+     * ```typescript
+     * 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"
+     * ```
+     */
+    constructor(data: BigNumberish | Buffer | Uint8Array | ByteArray | unknown);
+    /**
+     * 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.
+     * @param {BigNumberish | Buffer | Uint8Array | ByteArray} inData the value to convert
+     * @returns {object} the `data`, `pending_word` and `pending_word_len` components
+     * @example
+     * ```typescript
+     * const result = CairoByteArray.__processData('Hello').pending_word_len.toBigInt();
+     * // result = 5n
+     * ```
+     */
+    static __processData(inData: BigNumberish | Buffer | Uint8Array | ByteArray | unknown): {
         data: CairoBytes31[];
         pending_word: CairoFelt252;
         pending_word_len: CairoUint32;
     };
+    /**
+     * 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.
+     * @param {string} text the text to encode
+     * @returns {CairoByteArray} the UTF-8 bytes of the text, cut into 31-byte words
+     * @example
+     * ```typescript
+     * 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")
+     * ```
+     */
+    static fromText(text: string): CairoByteArray;
+    /**
+     * 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
+     * ```typescript
+     * const result = CairoByteArray.fromText('Hello').toApiRequest();
+     * // result = ["0", "310939249775", "5"]
+     * ```
+     */
     toApiRequest(): string[];
+    /**
+     * 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
+     * ```typescript
+     * 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)
+     * ```
+     */
     decodeUtf8(): string;
+    /**
+     * 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
+     * {@link CairoByteArray.toHexString} when the byte count matters.
+     * @returns {bigint} the bytes as a number, 0n when there are none
+     * @example
+     * ```typescript
+     * 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)
+     * ```
+     */
     toBigInt(): bigint;
+    /**
+     * 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
+     * ```typescript
+     * const result = new CairoByteArray('0x0041').toHexString();
+     * // result = "0x0041"    (where toBigInt() gives 65n, having dropped the first byte)
+     * ```
+     */
     toHexString(): string;
+    /**
+     * The whole byte sequence as a Buffer, leading zero bytes included.
+     * @returns {Buffer} a copy of the bytes, empty when there are none
+     * @example
+     * ```typescript
+     * const result = CairoByteArray.fromText('Hello').toBuffer().toString('hex');
+     * // result = "48656c6c6f"
+     * ```
+     */
     toBuffer(): any;
     /**
      * Compute the Pedersen hash of this ByteArray, following OpenZeppelin's `hash_byte_array` algorithm.
@@ -10477,26 +10812,96 @@ declare class CairoByteArray {
      */
     hash(): string;
     /**
-     * returns an array of all the data chunks and the pending word
-     * when concatenated, represents the original bytes sequence
+     * 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[]} one buffer per word, in order
+     * @example
+     * ```typescript
+     * const text = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567';
+     * const result = CairoByteArray.fromText(text).toElements().map((word) => word.length);
+     * // result = [31, 2]
+     * ```
      */
     toElements(): Uint8Array[];
     /**
-     * Private helper to check if the CairoByteArray is properly initialized
+     * Throw unless the three components are present.
+     *
+     * They are declared with a definite assignment assertion, so TypeScript does not catch an
+     * instance whose components were never filled, or one overwritten after construction. Every
+     * method that reads them calls this first.
+     * @throws {Error} when any of the three components is missing
+     * @example
+     * ```typescript
+     * const byteArray = new CairoByteArray('test');
+     * (byteArray as any).data = undefined;
+     * byteArray.toApiRequest();
+     * // throws Error("CairoByteArray is not properly initialized")
+     * ```
      */
     private assertInitialized;
-    static validate(data: Uint8Array | Buffer | BigNumberish | unknown): void;
     /**
-     * Check if the provided data is a valid CairoByteArray
+     * 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.
+     * @param {Uint8Array | Buffer | BigNumberish | ByteArray} data the value to check
+     * @throws {Error} when the value is of a kind this class does not carry
+     * @example
+     * ```typescript
+     * 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")
+     * ```
+     */
+    static validate(data: Uint8Array | Buffer | BigNumberish | ByteArray | unknown): void;
+    /**
+     * Can this value be carried by a CairoByteArray?
      *
-     * @param data - The data to check
-     * @returns True if the data is a valid CairoByteArray, false otherwise
+     * The non-throwing form of {@link CairoByteArray.validate}, with the same reach : it answers on
+     * the kind of the value, not on the usability of its contents.
+     * @param {any} data the value to test
+     * @returns {boolean} true when the value is of a kind this class can carry
+     * @example
+     * ```typescript
+     * 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)
+     * ```
      */
     static is(data: any): boolean;
     /**
-     * Check if provided abi type is this data type
+     * Is this abi type the one this class serializes?
+     * @param {string} abiType the abi type to test
+     * @returns {boolean} true for `core::byte_array::ByteArray`
+     * @example
+     * ```typescript
+     * const result = CairoByteArray.isAbiType('core::byte_array::ByteArray');
+     * // result = true
+     * ```
      */
     static isAbiType(abiType: string): boolean;
+    /**
+     * 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.
+     * @param {Iterator<string>} responseIterator the response felts, positioned on this ByteArray
+     * @returns {CairoByteArray} the ByteArray that was read
+     * @example
+     * ```typescript
+     * const response = ['0', '310939249775', '5'];
+     * const result = CairoByteArray.factoryFromApiResponse(response.values()).decodeUtf8();
+     * // result = "Hello"
+     * ```
+     */
     static factoryFromApiResponse(responseIterator: Iterator<string>): CairoByteArray;
 }