llms.txt
Skip to main content

Ability: Key

In the Move Basics chapter, we covered two of the four abilities - Drop and Copy. They affect the behavior of a value within a scope, and are not related to storage. Now it is time to cover the key ability - the ability that allows a struct to become a unit of storage.

Historically, the key ability was created to mark a type as a key in global storage. A type with the key ability could be stored at the top level and could be owned by an account or address. With the introduction of the Object Model, the key ability became the defining ability for objects.

Throughout the book, we refer to any struct with the key ability as an object.

Object Definition​

A struct with the key ability is an object, and can be used in storage functions. Two layers of rules apply to its definition:

  • The Move language requires every field of a key struct to have the store ability - we explore store on the next page;
  • The Sui Verifier additionally requires the first field of the struct to be named id and to have the type UID.
/// An object: a struct with the `key` ability and an `id: UID` field.
public struct User has key {
    id: UID, // required by the Sui Verifier, always the first field
    name: String, // all other fields must have `store`
}

/// Creates a new `User` object. The fresh `UID` is derived from the
/// transaction context `ctx`.
public fun new(name: String, ctx: &mut TxContext): User {
    User {
        id: object::new(ctx),
        name,
    }
}

The new function creates the object. A fresh UID can only be produced by object::new, which takes a mutable reference to the transaction context - so every newly created object gets an identifier that has never existed on the network before. We look closer at the UID type and its guarantees in the UID and ID section.

Relation to copy and drop​

UID is a type that has neither drop nor copy. Since every object is required to have a UID field, and a struct can only have an ability its fields support, this means that objects can never have drop or copy. Every object is non-discardable and non-copyable by construction - which is exactly what the asset properties demand.

This property can be leveraged in ability constraints: requiring drop or copy automatically excludes objects, and conversely, requiring key excludes types with drop or copy.

Types with the key Ability​

Due to the UID requirement, none of the native types in Move can have the key ability, nor can any of the types in the Standard Library. The key ability is present only in some Sui Framework types and in custom types.

Summary​

  • The key ability defines an object.
  • The Sui Verifier requires the first field of an object to be id of type UID.
  • The Move language requires all fields of a key struct to have store.
  • Objects can never have drop or copy.

Next Steps​

The key ability defines objects and forces all fields to have store. In the next section, we look at the store ability itself - and at the second, less obvious role it plays for objects.

Further Reading​

llms.txt