Sui Dynamic Fields and Object Nesting How to Build Complex Data Structures

02 September 2026

Sui’s object model doesn’t force you to decide everything at compile time. Static struct fields are fixed the moment you write the module. Dynamic fields let you attach data to an object after it exists. That distinction shapes how you build anything beyond a simple token.

Static fields are cheap and predictable. The compiler knows their size, type, and layout. You access them with direct dereference. No extra storage lookups. No runtime type checks. For most cases, that’s enough.

Dynamic fields are different. They are key-value pairs stored in the object’s dynamic field storage, separate from its struct fields. You add them with sui::dynamic_field::add. You read them with sui::dynamic_field::borrow. The key can be any type that implements copy + drop + store. The value can be any type with store. This sounds flexible. It is. But flexibility has a cost.

Every dynamic field adds a storage entry. That entry consumes SUI tokens from the storage fund. If you create unbounded numbers of them, the storage fund drain becomes real. The total storage rent on Sui is paid once at creation, then refunded when the object is deleted. But the refund goes to the original owner, not the current one. For long-lived objects with many dynamic fields, the cost compounds. Mitigation is straightforward: delete dynamic fields when you no longer need them. Batch deletes in Programmable Transaction Blocks to minimize wasted gas. And consider whether a static field or a compact vector would serve the same purpose with less overhead.

Sui provides three collection types built on dynamic fields. Each solves a different problem.

Table is the simplest. All keys share one type. All values share one type. You declare the key and value types at creation. It is homogeneous. Use it for a straightforward map where the shape of the data does not change. A Table has no ordering guarantee. You cannot iterate it from outside the module without explicit permission.

ObjectBag is heterogeneous. Keys can be different types. Values can be different types. An ObjectBag holds any mix of store-able data. This is the tool for complex nesting: a user profile object that holds a mix of badges, scores, and metadata, each with a different shape. The downside is that every value is stored as an object. That means each entry carries its own UID and the overhead of object management. Use it when your data genuinely varies. Avoid it when a simple Table would work.

LinkedTable extends Table with a doubly linked list. You get ordered iteration. You can insert at the front, back, or between existing entries. The ordering is explicit, not hash-dependent. This is useful for leaderboards, message queues, or any structure where insertion order matters. The linked list adds storage overhead for the next and previous pointers. Each insert or remove updates those pointers. That costs more gas than a plain Table insert.

Compare with Aptos’s approach. Aptos does not have dynamic fields on objects. It uses the Table extension, introduced in the Aptos standard library. An Aptos Table lives in global storage, not attached to any single object. You manage it via table::upsert and table::borrow. The key-value types are fixed at creation, like Sui’s Table. But because Aptos tables are not owned by an object, they cannot be nested inside another object in the same way. In Sui, a Table exists as a field of a parent object. You can pass that parent object and access its tables. In Aptos, the table is a separate global resource. You must pass both the table handle and any relevant objects explicitly. The result is that Sui’s model is more natural for aggregating data under a single logical entity. Aptos’s model is simpler from a storage accounting perspective, since tables do not belong to any particular object and their storage cost is paid per entry rather than per parent object.

The tradeoff comes down to ownership. Sui’s dynamic fields let you build deeply nested structures where a single object owns everything. Aptos’s tables force a flatter layout with explicit dependencies. For small, bounded collections, the difference is academic. For games, social apps, or any system that accumulates user-generated data over time, the choice determines whether your storage costs spiral or stay manageable.

If you expect thousands of dynamic field entries per object, plan for deletion. Audit your modules for unbounded growth. And if you need ordering, LinkedTable is the right answer - but only if you actually need to traverse the collection in order. Otherwise, a Table with a separate index is cheaper.

Back to sui & aptos