rippled/include/xrpl/protocol/STArray.h.ai.md

STArray.h — Serialized Array of STObject Instances

STArray is one of the fundamental composite types in the XRPL protocol type system. It represents an ordered, variable-length sequence of STObject instances — the protocol's mechanism for encoding repeated structured sub-fields within transactions and ledger entries. Real-world examples include the Memos field (a list of memo objects attached to a transaction) and SignerEntries (the ordered list of signers in a multisig account). Like every STBase-derived type, STArray participates in both the canonical binary wire format and the JSON representation used by the RPC layer.

Inheritance and Instance Tracking

STArray inherits from both STBase and CountedObject<STArray>. The STBase base class provides the field name (SField) association, the serialization interface (add(), addFieldID()), and the virtual copy()/move() protocol used by detail::STVar. The CountedObject<STArray> mixin increments an atomic counter on every constructor call and decrements on destruction, feeding the diagnostics surface exposed through GetCounts. This imposes no runtime cost on hot paths — the counter is a single atomic increment/decrement per object lifetime.

The storage is a plain std::vector<STObject> aliased as list_type. Because STObject is itself a concrete class (not a pointer type), the vector holds values directly, which means copy and move operations on STArray copy or move all elements. The STBase comment in the base class warns against putting STBase-derived objects in ordinary vectors due to copy-assignment name-erasure semantics; STArray sidesteps this for its elements by storing concrete STObject values rather than base-class references.

Binary Deserialization

The SerialIter-based constructor is the most architecturally significant piece of this class. XRPL's binary format encodes an array as a sentinel-terminated stream: each element begins with its field ID and ends with a per-object terminator (STI_OBJECT, 1), and the entire array ends with an array-level terminator (STI_ARRAY, 1). The constructor loops calling sit.getFieldID(type, field) and breaks when it sees the array terminator. Three classes of ill-formed input are rejected explicitly:

• An STI_ARRAY/1 marker that is not the array-end — caught by the loop's break condition.
• An STI_OBJECT/1 marker appearing at the array element level (an end-of-object sentinel leaked outside its scope) — rejected with "Illegal terminator in array".
• A non-STI_OBJECT field type inside the array — rejected with "Non-object in array", enforcing the invariant that every array element is a typed object, never a scalar.

The depth parameter passed through to v_.emplace_back(sit, fn, depth + 1) is a recursion guard. STObject's own deserialization constructor enforces a maximum depth of 10; since STArray increments the counter before passing it down, a maximally nested structure hits the limit before it can blow the call stack. This is a deliberate defense against crafted payloads.

After constructing each STObject, applyTemplateFromSField(fn) is called immediately. The outer SField associated with each array element (e.g., sfMemo, sfSigner) carries schema information (an SOTemplate), and applying it validates the just-deserialized object against the known field layout for that type. This call can throw, and the comment acknowledges it — a partially constructed array is simply abandoned via the exception unwind.

Binary Serialization

add() mirrors the deserializer precisely: for each element it writes object.addFieldID(s) (the element's own field ID prefix), then object.add(s) (the element body including the inner STI_OBJECT/1 per-object end marker from STObject::add()), then explicitly appends s.addFieldID(STI_OBJECT, 1). The outer STI_ARRAY/1 array-end marker is not written here — that is the enclosing STObject's responsibility. This split keeps each level responsible only for its own content, matching the XRPL convention that a container writes its body but its parent closes the outer scope.

JSON Representation

getJson() produces a JSON array where each element is a JSON object keyed by the inner STObject's field name — for instance [{"Memo": {...}}, {"Memo": {...}}]. The outer key is always present, making the field type unambiguous to JSON consumers. Objects whose getSType() returns STI_NOTPRESENT are silently skipped, which handles optional or absent inner objects without introducing nulls into the output.

Move Semantics

The explicit move constructor and move assignment operator in the .cpp file exist because STBase stores an SField const* that is not moved by default (the default move constructor of STBase would leave the field name in the moved-from state). Both operations explicitly call STBase(other.getFName()) or setFName(other.getFName()) before moving v_, preserving the SField association on the destination. The copy() and move() virtual overrides use STBase::emplace() to placement-construct into a caller-provided fixed-size buffer if the object fits, or heap-allocate otherwise — the mechanism by which detail::STVar implements small-buffer optimization for the XRPL type system.

Design Notes

The sort() method accepts a raw C function pointer bool (*compare)(STObject const&, STObject const&) rather than a std::function or template parameter. This keeps the interface simple for the handful of call sites that need it (primarily sorting SignerEntries by account ID for canonical transaction form), without introducing template instantiation in the header.

isDefault() returns true for an empty array. This matters because the enclosing STObject serializer can skip default-valued fields, so an empty STArray contributes nothing to the binary encoding — consistent with how absent optional array fields are represented in the ledger.