@solana/codecs-data-structures 8.3.0 → 8.4.0-canary-20260918134912

package/dist/types/array.d.ts

@@ -1,5 +1,71 @@
-import { Codec, Decoder, Encoder, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder, VariableSizeCodec, VariableSizeDecoder, VariableSizeEncoder } from '@solana/codecs-core';
+import { Codec, Decoder, Encoder, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder, ReadonlyUint8Array, VariableSizeCodec, VariableSizeDecoder, VariableSizeEncoder } from '@solana/codecs-core';
 import { NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
+/**
+ * Defines whether the sentinel of a {@link ArrayLikeCodecSentinelSize} strategy is written when
+ * encoding and required when decoding.
+ *
+ * This mirrors the `sentinelCountStrategy` enumeration of Codama's `sentinelCountNode`.
+ *
+ * - `"required"` — The sentinel is written after the last item and must be present when decoding.
+ *   Reaching the end of the byte array without it is an error. This is the default.
+ * - `"optional"` — The sentinel is written after the last item; when decoding, it is consumed if
+ *   present but the collection may also end at the end of the byte array. Use this to tolerate
+ *   tightly sized or legacy data that lacks the sentinel.
+ * - `"omitted"` — The sentinel is never written; when decoding, it is consumed if present and the
+ *   collection also ends at the end of the byte array. Only meaningful when the collection is
+ *   followed by unused space or the end of the byte array.
+ *
+ * Under `"optional"` and `"omitted"`, the sentinel must be no wider than the smallest possible item
+ * (see the constraints on {@link ArrayLikeCodecSentinelSize}).
+ *
+ * @see {@link ArrayLikeCodecSentinelSize}
+ */
+export type SentinelCountStrategy = 'omitted' | 'optional' | 'required';
+/**
+ * A size strategy for array-like codecs where the collection ends when the bytes at the next item
+ * position match a constant `sentinel`, compared at item boundaries only.
+ *
+ * Unlike {@link addCodecSentinel}, the sentinel is never searched for within an item's bytes, so its
+ * bytes may occur _inside_ an item without terminating the collection. This mirrors Codama's
+ * `sentinelCountNode`.
+ *
+ * @remarks
+ * Because the sentinel is only compared at the start of the next item slot, two invariants must hold
+ * for the collection to round-trip correctly. The codec does **not** enforce them — like Codama's
+ * `sentinelCountNode`, it is the caller's (or IDL author's) responsibility to guarantee them:
+ *
+ * 1. **No item may _begin_ with the sentinel's bytes.** A valid item that starts with the sentinel
+ *    is indistinguishable from the terminator, so decoding would stop early at that item. The
+ *    sentinel may still appear _inside_ an item, just never at its start. For instance, a single
+ *    `0xff` byte is a poor sentinel for a list of public keys: roughly one key in 256 starts with
+ *    `0xff`, so such a key would prematurely terminate the list. A sentinel as wide as an item — for
+ *    instance the all-zero (default) public key — avoids this, since only that exact key can ever
+ *    match the terminator.
+ * 2. **Under `"optional"` and `"omitted"`, the sentinel must be no wider than the smallest possible
+ *    item.** Otherwise a trailing region shorter than the sentinel but large enough to hold a valid
+ *    item would be skipped: decoding stops as soon as fewer bytes than the sentinel remain, so that
+ *    final item would never be read. This cannot arise under `"required"` because a terminator is
+ *    always written.
+ *
+ * @see {@link SentinelCountStrategy}
+ */
+export type ArrayLikeCodecSentinelSize = {
+    /** Internal discriminator identifying this object as a sentinel size strategy. */
+    readonly __kind: 'sentinel';
+    /**
+     * The fixed-size constant compared against the bytes at each item position.
+     *
+     * No valid item may begin with these bytes, and under the `"optional"` / `"omitted"` strategies
+     * this must be no wider than the smallest possible item. See the remarks above.
+     */
+    readonly sentinel: ReadonlyUint8Array;
+    /**
+     * Whether the sentinel is written when encoding and required when decoding.
+     *
+     * @defaultValue `"required"`
+     */
+    readonly strategy?: SentinelCountStrategy;
+};
 /**
  * Defines the possible size strategies for array-like codecs (`array`, `map`, and `set`).
  *
@@ -7,10 +73,12 @@ import { NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-number
  * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} to store a size prefix.
  * - A fixed `number` of items, enforcing an exact length.
  * - The string `"remainder"`, which infers the number of items by consuming the rest of the available bytes.
+ * - An {@link ArrayLikeCodecSentinelSize} object, which ends the collection when the bytes at the next
+ *   item position match a constant sentinel.
  *
  * @typeParam TPrefix - A number codec, decoder, or encoder used for size prefixing.
  */
-export type ArrayLikeCodecSize<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = TPrefix | number | 'remainder';
+export type ArrayLikeCodecSize<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = ArrayLikeCodecSentinelSize | TPrefix | number | 'remainder';
 /**
  * Defines the configuration options for array codecs.
  *
@@ -40,6 +108,8 @@ export type ArrayCodecConfig<TPrefix extends NumberCodec | NumberDecoder | Numbe
      * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} stores a size prefix before encoding the array.
      * - A `number` enforces a fixed number of elements.
      * - `"remainder"` uses all remaining bytes to infer the array length (only for fixed-size items).
+     * - An {@link ArrayLikeCodecSentinelSize} object ends the array when the bytes at the next item
+     *   position match a constant sentinel.
      *
      * @defaultValue A `u32` size prefix.
      */
@@ -170,6 +240,18 @@ export declare function getArrayDecoder<TTo>(item: Decoder<TTo>, config?: ArrayC
  * ```
  *
  * @example
+ * Using a sentinel to mark the end of the array. Note that no valid item may begin with the
+ * sentinel's bytes, or decoding would stop early — see {@link ArrayLikeCodecSentinelSize} for the
+ * full constraints.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec(), { size: { __kind: 'sentinel', sentinel: new Uint8Array([0]) } });
+ * codec.encode([1, 2, 3]);
+ * // 0x01020300
+ * //   |      └-- The sentinel that marks the end of the array.
+ * //   └-- 3 items of 1 byte each.
+ * ```
+ *
+ * @example
  * Requiring the size prefix to be present when decoding.
  * ```ts
  * getArrayCodec(getU8Codec()).decode(new Uint8Array([]));
@@ -184,6 +266,8 @@ export declare function getArrayDecoder<TTo>(item: Decoder<TTo>, config?: ArrayC
  * - A `Codec<number>` (e.g. `getU16Codec()`) stores a size prefix before the array.
  * - A `number` enforces a fixed number of elements.
  * - `"remainder"` uses all remaining bytes to infer the array length.
+ * - A sentinel object (see {@link ArrayLikeCodecSentinelSize}) ends the array when the bytes at the
+ *   next item position match a constant sentinel.
  *
  * When the size is stored as a prefix, decoding an exhausted byte array yields an empty array,
  * which allows arrays to be appended to existing data layouts without breaking older data.

package/dist/types/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/array.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,EAIL,OAAO,EACP,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAGhB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAgC,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAKjH;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,CAAC,OAAO,SAAS,WAAW,GAAG,aAAa,GAAG,aAAa,IACpF,OAAO,GACP,MAAM,GACN,WAAW,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,WAAW,GAAG,aAAa,GAAG,aAAa,IAAI;IACxF;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EACjC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EACpB,MAAM,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GACtD,gBAAgB,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;AAChC,wBAAgB,eAAe,CAAC,KAAK,EACjC,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC7B,MAAM,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3D,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC;AAC7B,wBAAgB,eAAe,CAAC,KAAK,EACjC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,GACzC,mBAAmB,CAAC,KAAK,EAAE,CAAC,CAAC;AAkChC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAC/B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAClB,MAAM,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GACtD,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAC9B,wBAAgB,eAAe,CAAC,GAAG,EAC/B,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3D,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC;AAC3B,wBAAgB,eAAe,CAAC,GAAG,EAC/B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAClB,MAAM,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,GACzC,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC;AAoC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,KAAK,EAC1D,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,EACvB,MAAM,EAAE,gBAAgB,CAAC,WAAW,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GACpD,cAAc,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACrC,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,KAAK,EAC1D,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,EAChC,MAAM,EAAE,gBAAgB,CAAC,WAAW,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GACzD,cAAc,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AAClC,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,KAAK,EAC1D,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,EACvB,MAAM,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,GACvC,iBAAiB,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/array.ts"],"names":[],"mappings":"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"}

package/dist/types/map.d.ts

@@ -10,6 +10,7 @@ import { ArrayLikeCodecSize } from './array';
  * - A fixed number of entries.
  * - `'remainder'`, which infers the number of entries based on the remaining bytes.
  *   This option is only available for fixed-size keys and values.
+ * - An {@link ArrayLikeCodecSentinelSize} object, which ends the map when the bytes at the next entry position match a constant sentinel.
  *
  * @typeParam TPrefix - A number codec, encoder, or decoder used for the size prefix.
  */

package/dist/types/map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/map.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/map.ts"],"names":[],"mappings":"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"}

package/dist/types/set.d.ts

@@ -10,6 +10,7 @@ import { ArrayLikeCodecSize } from './array';
  * - A {@link NumberCodec}, {@link NumberEncoder}, or {@link NumberDecoder} to store the size as a prefix.
  * - A fixed number of items, enforcing a strict length.
  * - The string `'remainder'` to infer the set size from the remaining bytes (only for fixed-size items).
+ * - An {@link ArrayLikeCodecSentinelSize} object to end the set when the bytes at the next item position match a constant sentinel.
  *
  * @typeParam TPrefix - The type used for encoding the size of the set.
  */

package/dist/types/set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/set.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/set.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/codecs-data-structures",
-  "version": "8.3.0",
+  "version": "8.4.0-canary-20260918134912",
   "description": "Codecs for various data structures",
   "homepage": "https://www.solanakit.com/api#solanacodecs-data-structures",
   "exports": {
@@ -56,9 +56,9 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/codecs-core": "8.3.0",
-    "@solana/codecs-numbers": "8.3.0",
-    "@solana/errors": "8.3.0"
+    "@solana/codecs-core": "8.4.0-canary-20260918134912",
+    "@solana/codecs-numbers": "8.4.0-canary-20260918134912",
+    "@solana/errors": "8.4.0-canary-20260918134912"
   },
   "peerDependencies": {
     "typescript": ">=5.4.0"

package/src/array.ts

@@ -1,6 +1,7 @@
 import {
     Codec,
     combineCodec,
+    containsBytes,
     createDecoder,
     createEncoder,
     Decoder,
@@ -15,10 +16,83 @@ import {
     VariableSizeEncoder,
 } from '@solana/codecs-core';
 import { getU32Decoder, getU32Encoder, NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
+import {
+    SOLANA_ERROR__CODECS__SENTINEL_MISSING_AT_END_OF_BYTES,
+    SOLANA_ERROR__CODECS__SENTINEL_MUST_NOT_BE_EMPTY,
+    SolanaError,
+} from '@solana/errors';
 
 import { assertValidNumberOfItemsForCodec } from './assertions';
 import { getFixedSize, getMaxSize } from './utils';
 
+/**
+ * Defines whether the sentinel of a {@link ArrayLikeCodecSentinelSize} strategy is written when
+ * encoding and required when decoding.
+ *
+ * This mirrors the `sentinelCountStrategy` enumeration of Codama's `sentinelCountNode`.
+ *
+ * - `"required"` — The sentinel is written after the last item and must be present when decoding.
+ *   Reaching the end of the byte array without it is an error. This is the default.
+ * - `"optional"` — The sentinel is written after the last item; when decoding, it is consumed if
+ *   present but the collection may also end at the end of the byte array. Use this to tolerate
+ *   tightly sized or legacy data that lacks the sentinel.
+ * - `"omitted"` — The sentinel is never written; when decoding, it is consumed if present and the
+ *   collection also ends at the end of the byte array. Only meaningful when the collection is
+ *   followed by unused space or the end of the byte array.
+ *
+ * Under `"optional"` and `"omitted"`, the sentinel must be no wider than the smallest possible item
+ * (see the constraints on {@link ArrayLikeCodecSentinelSize}).
+ *
+ * @see {@link ArrayLikeCodecSentinelSize}
+ */
+export type SentinelCountStrategy = 'omitted' | 'optional' | 'required';
+
+/**
+ * A size strategy for array-like codecs where the collection ends when the bytes at the next item
+ * position match a constant `sentinel`, compared at item boundaries only.
+ *
+ * Unlike {@link addCodecSentinel}, the sentinel is never searched for within an item's bytes, so its
+ * bytes may occur _inside_ an item without terminating the collection. This mirrors Codama's
+ * `sentinelCountNode`.
+ *
+ * @remarks
+ * Because the sentinel is only compared at the start of the next item slot, two invariants must hold
+ * for the collection to round-trip correctly. The codec does **not** enforce them — like Codama's
+ * `sentinelCountNode`, it is the caller's (or IDL author's) responsibility to guarantee them:
+ *
+ * 1. **No item may _begin_ with the sentinel's bytes.** A valid item that starts with the sentinel
+ *    is indistinguishable from the terminator, so decoding would stop early at that item. The
+ *    sentinel may still appear _inside_ an item, just never at its start. For instance, a single
+ *    `0xff` byte is a poor sentinel for a list of public keys: roughly one key in 256 starts with
+ *    `0xff`, so such a key would prematurely terminate the list. A sentinel as wide as an item — for
+ *    instance the all-zero (default) public key — avoids this, since only that exact key can ever
+ *    match the terminator.
+ * 2. **Under `"optional"` and `"omitted"`, the sentinel must be no wider than the smallest possible
+ *    item.** Otherwise a trailing region shorter than the sentinel but large enough to hold a valid
+ *    item would be skipped: decoding stops as soon as fewer bytes than the sentinel remain, so that
+ *    final item would never be read. This cannot arise under `"required"` because a terminator is
+ *    always written.
+ *
+ * @see {@link SentinelCountStrategy}
+ */
+export type ArrayLikeCodecSentinelSize = {
+    /** Internal discriminator identifying this object as a sentinel size strategy. */
+    readonly __kind: 'sentinel';
+    /**
+     * The fixed-size constant compared against the bytes at each item position.
+     *
+     * No valid item may begin with these bytes, and under the `"optional"` / `"omitted"` strategies
+     * this must be no wider than the smallest possible item. See the remarks above.
+     */
+    readonly sentinel: ReadonlyUint8Array;
+    /**
+     * Whether the sentinel is written when encoding and required when decoding.
+     *
+     * @defaultValue `"required"`
+     */
+    readonly strategy?: SentinelCountStrategy;
+};
+
 /**
  * Defines the possible size strategies for array-like codecs (`array`, `map`, and `set`).
  *
@@ -26,10 +100,13 @@ import { getFixedSize, getMaxSize } from './utils';
  * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} to store a size prefix.
  * - A fixed `number` of items, enforcing an exact length.
  * - The string `"remainder"`, which infers the number of items by consuming the rest of the available bytes.
+ * - An {@link ArrayLikeCodecSentinelSize} object, which ends the collection when the bytes at the next
+ *   item position match a constant sentinel.
  *
  * @typeParam TPrefix - A number codec, decoder, or encoder used for size prefixing.
  */
 export type ArrayLikeCodecSize<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> =
+    | ArrayLikeCodecSentinelSize
     | TPrefix
     | number
     | 'remainder';
@@ -63,6 +140,8 @@ export type ArrayCodecConfig<TPrefix extends NumberCodec | NumberDecoder | Numbe
      * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} stores a size prefix before encoding the array.
      * - A `number` enforces a fixed number of elements.
      * - `"remainder"` uses all remaining bytes to infer the array length (only for fixed-size items).
+     * - An {@link ArrayLikeCodecSentinelSize} object ends the array when the bytes at the next item
+     *   position match a constant sentinel.
      *
      * @defaultValue A `u32` size prefix.
      */
@@ -113,6 +192,7 @@ export function getArrayEncoder<TFrom>(
     config: ArrayCodecConfig<NumberEncoder> = {},
 ): Encoder<TFrom[]> {
     const size = config.size ?? getU32Encoder();
+    assertValidSize(size);
     const fixedSize = computeArrayLikeCodecSize(size, getFixedSize(item));
     const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? undefined;
 
@@ -121,8 +201,13 @@ export function getArrayEncoder<TFrom>(
             ? { fixedSize }
             : {
                   getSizeFromValue: (array: TFrom[]) => {
-                      const prefixSize = typeof size === 'object' ? getEncodedSize(array.length, size) : 0;
-                      return prefixSize + [...array].reduce((all, value) => all + getEncodedSize(value, item), 0);
+                      const prefixSize = isPrefixSize(size) ? getEncodedSize(array.length, size) : 0;
+                      const suffixSize = isSentinelSize(size) && size.strategy !== 'omitted' ? size.sentinel.length : 0;
+                      return (
+                          prefixSize +
+                          suffixSize +
+                          [...array].reduce((all, value) => all + getEncodedSize(value, item), 0)
+                      );
                   },
                   maxSize,
               }),
@@ -130,12 +215,16 @@ export function getArrayEncoder<TFrom>(
             if (typeof size === 'number') {
                 assertValidNumberOfItemsForCodec(config.description ?? 'array', size, array.length);
             }
-            if (typeof size === 'object') {
+            if (isPrefixSize(size)) {
                 offset = size.write(array.length, bytes, offset);
             }
             array.forEach(value => {
                 offset = item.write(value, bytes, offset);
             });
+            if (isSentinelSize(size) && size.strategy !== 'omitted') {
+                bytes.set(size.sentinel, offset);
+                offset += size.sentinel.length;
+            }
             return offset;
         },
     });
@@ -183,6 +272,7 @@ export function getArrayDecoder<TTo>(
 ): VariableSizeDecoder<TTo[]>;
 export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfig<NumberDecoder> = {}): Decoder<TTo[]> {
     const size = config.size ?? getU32Decoder();
+    assertValidSize(size);
     const itemSize = getFixedSize(item);
     const fixedSize = computeArrayLikeCodecSize(size, itemSize);
     const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? undefined;
@@ -191,7 +281,7 @@ export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfi
         ...(fixedSize !== null ? { fixedSize } : { maxSize }),
         read: (bytes: ReadonlyUint8Array | Uint8Array, offset) => {
             const array: TTo[] = [];
-            if (typeof size === 'object' && !config.requireSizePrefix && offset >= bytes.length) {
+            if (isPrefixSize(size) && !config.requireSizePrefix && offset >= bytes.length) {
                 return [array, offset];
             }
 
@@ -204,6 +294,32 @@ export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfi
                 return [array, offset];
             }
 
+            if (isSentinelSize(size)) {
+                const { sentinel, strategy = 'required' } = size;
+                while (true) {
+                    if (offset + sentinel.length > bytes.length) {
+                        // Not enough bytes remain to hold the sentinel.
+                        if (strategy === 'required') {
+                            throw new SolanaError(SOLANA_ERROR__CODECS__SENTINEL_MISSING_AT_END_OF_BYTES, {
+                                codecDescription: config.description ?? 'array',
+                                hexSentinel: hexBytes(sentinel),
+                                sentinel,
+                            });
+                        }
+                        break;
+                    }
+                    if (containsBytes(bytes, sentinel, offset)) {
+                        // The sentinel is present; consume it and stop.
+                        offset += sentinel.length;
+                        break;
+                    }
+                    const [value, newOffset] = item.read(bytes, offset);
+                    offset = newOffset;
+                    array.push(value);
+                }
+                return [array, offset];
+            }
+
             const [resolvedSize, newOffset] = typeof size === 'number' ? [size, offset] : size.read(bytes, offset);
             offset = newOffset;
             for (let i = 0; i < resolvedSize; i += 1) {
@@ -272,6 +388,18 @@ export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfi
  * ```
  *
  * @example
+ * Using a sentinel to mark the end of the array. Note that no valid item may begin with the
+ * sentinel's bytes, or decoding would stop early — see {@link ArrayLikeCodecSentinelSize} for the
+ * full constraints.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec(), { size: { __kind: 'sentinel', sentinel: new Uint8Array([0]) } });
+ * codec.encode([1, 2, 3]);
+ * // 0x01020300
+ * //   |      └-- The sentinel that marks the end of the array.
+ * //   └-- 3 items of 1 byte each.
+ * ```
+ *
+ * @example
  * Requiring the size prefix to be present when decoding.
  * ```ts
  * getArrayCodec(getU8Codec()).decode(new Uint8Array([]));
@@ -286,6 +414,8 @@ export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfi
  * - A `Codec<number>` (e.g. `getU16Codec()`) stores a size prefix before the array.
  * - A `number` enforces a fixed number of elements.
  * - `"remainder"` uses all remaining bytes to infer the array length.
+ * - A sentinel object (see {@link ArrayLikeCodecSentinelSize}) ends the array when the bytes at the
+ *   next item position match a constant sentinel.
  *
  * When the size is stored as a prefix, decoding an exhausted byte array yields an empty array,
  * which allows arrays to be appended to existing data layouts without breaking older data.
@@ -325,3 +455,24 @@ function computeArrayLikeCodecSize(size: number | object | 'remainder', itemSize
     if (size === 0) return 0;
     return itemSize === null ? null : itemSize * size;
 }
+
+/** Narrows an array-like size to a numeric prefix codec, decoder, or encoder. */
+function isPrefixSize(size: unknown): size is NumberCodec | NumberDecoder | NumberEncoder {
+    return typeof size === 'object' && size !== null && !isSentinelSize(size);
+}
+
+/** Narrows an array-like size to an {@link ArrayLikeCodecSentinelSize} object. */
+function isSentinelSize(size: unknown): size is ArrayLikeCodecSentinelSize {
+    return typeof size === 'object' && size !== null && '__kind' in size && size.__kind === 'sentinel';
+}
+
+/** Throws if an array-like size strategy is misconfigured (e.g. a sentinel that can never be matched). */
+function assertValidSize(size: number | object | 'remainder'): void {
+    if (isSentinelSize(size) && size.sentinel.length === 0) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__SENTINEL_MUST_NOT_BE_EMPTY);
+    }
+}
+
+function hexBytes(bytes: ReadonlyUint8Array): string {
+    return bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '');
+}

package/src/map.ts

@@ -26,6 +26,7 @@ import { getTupleDecoder, getTupleEncoder } from './tuple';
  * - A fixed number of entries.
  * - `'remainder'`, which infers the number of entries based on the remaining bytes.
  *   This option is only available for fixed-size keys and values.
+ * - An {@link ArrayLikeCodecSentinelSize} object, which ends the map when the bytes at the next entry position match a constant sentinel.
  *
  * @typeParam TPrefix - A number codec, encoder, or decoder used for the size prefix.
  */

package/src/set.ts

@@ -25,6 +25,7 @@ import { ArrayLikeCodecSize, getArrayDecoder, getArrayEncoder } from './array';
  * - A {@link NumberCodec}, {@link NumberEncoder}, or {@link NumberDecoder} to store the size as a prefix.
  * - A fixed number of items, enforcing a strict length.
  * - The string `'remainder'` to infer the set size from the remaining bytes (only for fixed-size items).
+ * - An {@link ArrayLikeCodecSentinelSize} object to end the set when the bytes at the next item position match a constant sentinel.
  *
  * @typeParam TPrefix - The type used for encoding the size of the set.
  */