llms.txt
Skip to main content

Ability: Store

The key ability requires all fields to have store, and that requirement is the best way to understand what store means: it is the ability to be stored - to end up inside an object in the blockchain state. A struct with copy or drop but without store can live only during the transaction that creates it; it can never be persisted.

Definition​

The store ability allows a type to be used as a field of a struct with the key ability - directly, or nested any number of levels deep. Like with other abilities, the rule applies recursively: a struct can only have store if all of its fields have store.

/// Extra metadata with `store`; all of its fields must have `store` as well!
public struct Metadata has store {
    bio: String,
}

/// An object for a single user record.
public struct User has key {
    id: UID,
    name: String, // `String` has `store`
    age: u8, // all integers have `store`
    metadata: Metadata, // another type with the `store` ability
}

Relation to copy and drop​

store is independent of copy and drop: the three non-key abilities can be combined freely, and none of them implies another. A type may be copyable but not storable, storable but neither copyable nor droppable, and so on - each combination is valid and has its uses.

Relation to key​

An object can also have the store ability, and for objects it plays a double role:

  • An object with store can be wrapped: used as a field of another object. An object without store is constrained to always remain at the top level of storage.
  • store acts as a public modifier on the object: it permits calling the public storage functions - public_transfer, public_share_object, and public_freeze_object - from any module. Without store, storage operations on the object are reserved for its defining module, which keeps full control over how the object moves.

The second role is not a language feature but a convention of the Sui Framework, enforced through the internal constraint - the topic of the next section. Whether to give an object store is one of the most consequential design decisions in a Sui application, and we return to it in Storage Functions.

Types with the store Ability​

All native types (except references) in Move have the store ability. This includes:

All of the types defined in the standard library have the store ability as well. This includes:

Summary​

  • store allows a type to be persisted - used as a field of an object, at any nesting depth.
  • For objects, store additionally unlocks wrapping and the public storage functions.
  • store is independent of copy and drop; container types have it conditionally on their contents.

Further Reading​

llms.txt