Dynamic Fields and Collections - Encode Club Sui Series #4

In this fourth of six educational videos, you will learn the importance of dynamic fields and collections when programming objects on Sui.

Dynamic Fields and Collections - Encode Club Sui Series #4

In the fourth video of Encode Club’s Sui series, we describe two very useful features, dynamic fields and collections. These features add considerable flexibility to Sui’s object data model.

The Sui Foundation partnered with Encode Club to offer a series of six developer-focused videos. This series will range from the basics of Sui to tutorials about building smart contracts and working with objects in Sui.

Learning Highlights

Although Sui’s object data model is a great strength, manipulating and architecting how those objects fit in a programming framework has its own challenges. Two features, dynamic fields and collections, create much more flexibility when defining objects on Sui.

Review: Object Wrapping

Objects can own other objects in Sui, but an object wrapping another object is a different concept.

struct A has key {
	id: UID,
	b: B

struct B has key, store { id: UID }

In the example above, an object of type B is wrapped into an object of type A. With object wrapping, the wrapped object (in our example, object B), is not stored as a top-level object. As such, it is not accessible via its object ID, and as a result any API interacting with this object (i.e. via a frontend) will not be able to access object B directly.

There are a few shortcomings with this approach:

  • Objects have a finite number of fields. These are the fields in the struct declarations.
  • Objects wrapping other objects can become very large, resulting in higher gas fees. There is also an upper limit on an object’s size.
  • It is impossible to store a collection of heterogeneous objects (objects of varying types) via object wrapping. Because the Move vector type must be instantiated with a single type T, heterogeneous collections are not supported using vectors.

Dynamic Fields

Dynamic fields solve the aforementioned problems. Dynamic fields have arbitrary names, and are added and removed ad hoc. With regards to gas, you only pay for what you access, not what you could access. Dynamic fields also support heterogeneous types, making it possible to store un-like types within a certain object.

Dynamic fields come in two different varieties: fields and object fields. Fields can store any value with store. These Fields are not stand-alone objects, and cannot be accessed through their IDs from an external API. Object fields, on the other hand, must have key,store following their struct declaration. The advantage to the latter is that the objects keep their same object ID, and can still be read from external APIs.

Read the Sui documentation on dynamic fields for a more thorough description.


Dynamic fields introduced a way to extend existing objects, and collections take this a step further. Collections are built on top of dynamic fields, and they enable additional support to count the number of entries they contain, as well as protecting against accidental non-empty deletion.

Collections support both homogeneous and heterogeneous values. The homogeneous collection type is Table. All values stored in Table must be of the same type. The heterogeneous collection type is Bag. Values stored in Bag can be of any type. Similar to dynamic fields and dynamic object fields, table and bag also offer an object-only version: object_table and object_bag. Where all values for table and bag must only have store, all values for object_table and object_bag must have key,store.

Read the Sui documentation on collections for a more thorough description.

Join Us at the Vietnam Builder House

Learn more about Sui and network with its founders and other developers! The Sui Foundation is hosting our next Builder House in Vietnam, from March 18 to 19, 2023. Expect educational presentations, a challenge featuring prizes, and other fun activities.

Register today before we hit capacity!

Watch the Whole Series

  1. What's Sui?
  2. Smart Contracts
  3. Creating Objects and NFTs
  4. Dynamic Fields and Collections
  5. RPG Building Basics
  6. Deploy a Game to the Blockchain