From 972be782162e26c644ea35db212b13ca97396a12 Mon Sep 17 00:00:00 2001 From: salaheldinsoliman Date: Fri, 25 Oct 2024 12:48:47 +0200 Subject: [PATCH] feat(docs): add abilities section Signed-off-by: salaheldinsoliman --- .../structs-and-abilities/abilities-intro.mdx | 4 +- .../structs-and-abilities/copy.mdx | 10 ++-- .../structs-and-abilities/drop.mdx | 10 ++-- .../structs-and-abilities/key.mdx | 53 +++++++++++++++++++ .../structs-and-abilities/store.mdx | 50 +++++++++++++++++ docs/content/sidebars/developer.js | 3 ++ 6 files changed, 118 insertions(+), 12 deletions(-) create mode 100644 docs/content/developer/iota-101/move-overview/structs-and-abilities/key.mdx create mode 100644 docs/content/developer/iota-101/move-overview/structs-and-abilities/store.mdx diff --git a/docs/content/developer/iota-101/move-overview/structs-and-abilities/abilities-intro.mdx b/docs/content/developer/iota-101/move-overview/structs-and-abilities/abilities-intro.mdx index 8518ae17e55..679d0934afc 100644 --- a/docs/content/developer/iota-101/move-overview/structs-and-abilities/abilities-intro.mdx +++ b/docs/content/developer/iota-101/move-overview/structs-and-abilities/abilities-intro.mdx @@ -44,9 +44,9 @@ References have `copy` and `drop`. - `drop` - allows the struct to be _dropped_ or _discarded_. Explained in the [Ability: Drop](./drop.mdx) section. - `key` - allows the struct to be used as a _key_ in a storage. Explained in the - [Ability: Key](./../storage/key-ability.md) chapter. + [Ability: Key](./key.mdx) chapter. - `store` - allows the struct to be _stored_ in structs with the _key_ ability. Explained in the - [Ability: Store](./../storage/store-ability.md) chapter. + [Ability: Store](./store.mdx) chapter. While it is important to mention them here, we will go in detail about each ability in the following chapters and give a proper context on how to use them. diff --git a/docs/content/developer/iota-101/move-overview/structs-and-abilities/copy.mdx b/docs/content/developer/iota-101/move-overview/structs-and-abilities/copy.mdx index 830b6c85ff4..c82bd4ca66a 100644 --- a/docs/content/developer/iota-101/move-overview/structs-and-abilities/copy.mdx +++ b/docs/content/developer/iota-101/move-overview/structs-and-abilities/copy.mdx @@ -43,11 +43,11 @@ All native types in Move have the `copy` ability. This includes: - bool - unsigned integers -- vector -- address +- [vector](../../../../references/framework/move-stdlib/vector.mdx) +- [address](../../../../references/framework/move-stdlib/address.mdx) All of the types defined in the standard library have the `copy` ability as well. This includes: -- Option -- String -- TypeName \ No newline at end of file +- [Option](../../../../references/framework/move-stdlib/option.mdx) +- [String](../../../../references/framework/move-stdlib/string.mdx) +- [TypeName](../../../../references/framework/move-stdlib/type_name.mdx) \ No newline at end of file diff --git a/docs/content/developer/iota-101/move-overview/structs-and-abilities/drop.mdx b/docs/content/developer/iota-101/move-overview/structs-and-abilities/drop.mdx index 9f5a90c1842..26810b911fb 100644 --- a/docs/content/developer/iota-101/move-overview/structs-and-abilities/drop.mdx +++ b/docs/content/developer/iota-101/move-overview/structs-and-abilities/drop.mdx @@ -27,11 +27,11 @@ All native types in Move have the `drop` ability. This includes: - bool - unsigned integers -- vector -- address +- [vector](../../../../references/framework/move-stdlib/vector.mdx) +- [address](../../../../references/framework/move-stdlib/address.mdx) All of the types defined in the standard library have the `drop` ability as well. This includes: -- Option -- String -- TypeName \ No newline at end of file +- [Option](../../../../references/framework/move-stdlib/option.mdx) +- [String](../../../../references/framework/move-stdlib/string.mdx) +- [TypeName](../../../../references/framework/move-stdlib/type_name.mdx) \ No newline at end of file diff --git a/docs/content/developer/iota-101/move-overview/structs-and-abilities/key.mdx b/docs/content/developer/iota-101/move-overview/structs-and-abilities/key.mdx new file mode 100644 index 00000000000..6afac672b1c --- /dev/null +++ b/docs/content/developer/iota-101/move-overview/structs-and-abilities/key.mdx @@ -0,0 +1,53 @@ +# The Key Ability + +We already covered two out of four abilities - +[Drop](./drop.mdx) and [Copy](./copy.mdx). They affect the behaviour of the value in a +scope and are not directly related to storage. It is time to cover the `key` ability, which allows +the struct to be stored. + +Historically, the `key` ability was created to mark the type as a _key in the storage_. A type with +the `key` ability could be stored at top-level in the storage, and could be _directly owned_ by an +account or address. With the introduction of the [Object Model](../../objects/object-model.mdx), the `key` ability +naturally became the defining ability for the object. + + +## Object Definition + +A struct with the `key` ability is considered an object and can be used in the storage functions. +The Sui Verifier will require the first field of the struct to be named `id` and have the type +`UID`. + +```move +public struct Object has key { + id: UID, // required + name: String, +} + +/// Creates a new Object with a Unique ID +public fun new(name: String, ctx: &mut TxContext): Object { + Object { + id: object::new(ctx), // creates a new UID + name, + } +} +``` + +A struct with the `key` ability is still a struct, and can have any number of fields and associated +functions. There is no special handling or syntax for packing, accessing or unpacking the struct. + +However, because the first field of an object struct must be of type `UID` - a non-copyable and +non-droppable type (we will get to it very soon!), the struct transitively cannot have `drop` and +`copy` abilities. Thus, the object is non-discardable by design. + + +## Types with the `key` Ability + +Due to the `UID` requirement for types with `key`, none of the native types in Move can have the +`key` ability, nor can any of the [Standard Library](../../../../references/framework/move-stdlib/_category_.json) types. +The `key` ability is only present in the [IOTA Framework](../../../../references/framework/iota-framework/_category_.json) and +custom types. + +## Next Steps + +Key ability defines the object in Move, and objects are intended to be _stored_. In the next section +we present the `iota::transfer` module, which provides native storage functions for objects. \ No newline at end of file diff --git a/docs/content/developer/iota-101/move-overview/structs-and-abilities/store.mdx b/docs/content/developer/iota-101/move-overview/structs-and-abilities/store.mdx new file mode 100644 index 00000000000..fcf0d001529 --- /dev/null +++ b/docs/content/developer/iota-101/move-overview/structs-and-abilities/store.mdx @@ -0,0 +1,50 @@ +# Ability: Store + +## Definition + +The `store` is a special ability that allows a type to be _stored_ in objects. This ability is +required for the type to be used as a field in a struct that has the `key` ability. Another way to +put it is that the `store` ability allows the value to be _wrapped_ in an object. + +:::info +The `store` ability also relaxes restrictions on transfer operations. We talk about it more in the +[Custome Transfer Rules](../../objects/transfers/custom-rules.mdx) section. +::: + +## Example + +In previous sections we already used types with the `key` ability: all objects must have a `UID` +field, which we used in examples; we also used the `Storable` type as a part of the `Config` struct. +The `Config` type also has the `store` ability. + +```move +/// This type has the `store` ability. +public struct Storable has store {} + +/// Config contains a `Storable` field which must have the `store` ability. +public struct Config has key, store { + id: UID, + stores: Storable, +} + +/// MegaConfig contains a `Config` field which has the `store` ability. +public struct MegaConfig has key { + id: UID, + config: Config, // there it is! +} +``` + +## Types with the `store` Ability + +All native types (except for references) in Move have the `store` ability. This includes: + +- bool +- unsigned integers +- [vector](../../../../references/framework/move-stdlib/vector.mdx) +- [address](../../../../references/framework/move-stdlib/address.mdx) + +All of the types defined in the standard library have the `store` ability as well. This includes: + +- [Option](../../../../references/framework/move-stdlib/option.mdx) +- [String](../../../../references/framework/move-stdlib/string.mdx) +- [TypeName](../../../../references/framework/move-stdlib/type_name.mdx) \ No newline at end of file diff --git a/docs/content/sidebars/developer.js b/docs/content/sidebars/developer.js index 2b1b06fc6fc..c73ee465fb0 100644 --- a/docs/content/sidebars/developer.js +++ b/docs/content/sidebars/developer.js @@ -78,7 +78,10 @@ const developer = [ label: 'Structs and Abilities', items: [ 'developer/iota-101/move-overview/structs-and-abilities/struct', + 'developer/iota-101/move-overview/structs-and-abilities/copy', 'developer/iota-101/move-overview/structs-and-abilities/drop', + 'developer/iota-101/move-overview/structs-and-abilities/key', + 'developer/iota-101/move-overview/structs-and-abilities/store', ], }, {