_

MystenLabs · Mar 31, 2024 · 99224e7 · 99224e7
1 parent 434cdfd
commit 99224e7
Show file tree

Hide file tree

Showing 21 changed files with 234 additions and 186 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -71,14 +71,14 @@ comparison to docs.sui.io
     <!-- TODO:  -->
     <!-- - [Send a Transaction]() -->
 - [Concepts](./concepts/README.md)
-  - [What is a Package](./concepts/packages.md)
+  - [Package](./concepts/packages.md)
   - [Manifest](./concepts/manifest.md)
-  - [Addresses](./concepts/address.md)
-  - [Module](./concepts/modules.md)
-  - [Interacting with a Package](./concepts/user-interaction.md)
+  - [Address](./concepts/address.md)
   - [Account](./concepts/what-is-an-account.md)
   - [Transaction](./concepts/what-is-a-transaction.md)
-  - [Fast Path](./concepts/fast-path.md)
+<!-- - [Interacting with a Package](./concepts/user-interaction.md) -->
+<!-- - [Fast Path](./concepts/fast-path.md) -->
+<!-- - [Module](./concepts/modules.md) -->
 - [Syntax Basics](./basic-syntax/README.md)
   - [Module](./basic-syntax/module.md)
   - [Comments](./basic-syntax/comments.md)
@@ -112,7 +112,7 @@ comparison to docs.sui.io
   - [Fast Path & Consensus](./object/fast-path-and-consensus.md)
 - [Using Objects](./storage/README.md)
   - [Ability: Key](./storage/key-ability.md)
-  - [UID and ID]() <!-- (./object/what-is-an-object.md) -->
+  - [UID and ID](./storage/uid-and-id.md)
   - [Transfer Restrictions]() <!-- (./object/transfer-restrictions.md) -->
   - [Ability: Store]() <!-- ./object/store-ability.md) -->
   - [Shared State]() <!-- (./object/shared-state.md) -->
@@ -127,7 +127,6 @@ comparison to docs.sui.io
   - [Dynamic Fields](./programmability/dynamic-fields.md)
   - [Dynamic Object Fields](./programmability/dynamic-object-fields.md)
   - [Dynamic Collections](./programmability/dynamic-collections.md)
-  - [Package Upgrades]()<!-- (./programmability/package-upgrades.md) -->
   - [Pattern: Witness]() <!-- ./programmability/witness-pattern.md) <!-- Block: from Witness to Display -->
   - [One Time Witness](./programmability/one-time-witness.md)
   - [Publisher Authority](./programmability/publisher.md)
@@ -138,18 +137,19 @@ comparison to docs.sui.io
   - [Pattern: Request]() <!-- - [Witness and Abstract Implementation](./programmability/witness-and-abstract-implementation.md) -->
   - [Pattern: Hot Potato]()
   - [Pattern: Object Capability]()
+  - [Package Upgrades]()<!-- (./programmability/package-upgrades.md) -->
   - [Transaction Blocks]()<!-- (./programmability/transaction-blocks.md) -->
   - [Authorization Patterns]()<!-- (./programmability/authorization-patterns.md) -->
   - [Cryptography and Hashing]()<!-- (./programmability/cryptography-and-hashing.md) -->
   - [Randomness]()<!-- (./programmability/randomness.md) -->
-  - [BCS](./programmability/bcs.md)
-- [Patterns (?)]()
+  - [BCS]() <!-- (./programmability/bcs.md) -->
+  <!-- - [Patterns (?)]()
   - [Getters and Setters]()
   - [Abstract Class]()
   - [Hot Potato]()
   - [Request]()
   - [Object Capability]()
-  - [Witness Registry]()
+  - [Witness Registry]() -->
 - [Standards]()
   - [Balance]()
   - [Coin]()
@@ -165,7 +165,7 @@ comparison to docs.sui.io
   - [Testing]()<!-- (./guides/testing.md) -->
   - [Debugging]()<!-- (./guides/debugging.md) -->
   - [Coding Conventions]()
-- [Appendix]()
+# Appendix
   - [A - Glossary](./appendix/glossary.md)
   - [B - Publications](./appendix/publications.md)
   - [C - Contributing](./appendix/contributing.md)

diff --git a/book/src/basic-syntax/module.md b/book/src/basic-syntax/module.md
@@ -24,18 +24,17 @@ Usually, a single file in the `sources/` folder contains a single module. The fi
 {{#include ../../../packages/samples/sources/basic-syntax/module.move:module}}
 ```
 
-Structs, functions and constants, imports and friend declarations are all part of the module:
+Structs, functions, constants and imports all part of the module:
 
 - [Structs](./struct.md)
 - [Functions](./function.md)
 - [Constants](./constants.md)
 - [Imports](./importing-modules.md)
-- [Friend declarations]() <!-- TODO -->
-- [Method Aliases](./struct-methods.md)
+- [Struct Methods](./struct-methods.md)
 
 ## Address / Named address
 
-Module address can be specified as both: an address _literal_ (does not require the `@` prefix) or a named address specified in the [Package Manifest](../concepts/package-manifest.md). In the example below, both are identical because there's a `book = "0x0"` record in the `[addresses]` section of the `Move.toml`.
+Module address can be specified as both: an address _literal_ (does not require the `@` prefix) or a named address specified in the [Package Manifest](../concepts/manifest.md). In the example below, both are identical because there's a `book = "0x0"` record in the `[addresses]` section of the `Move.toml`.
 
 ```Move
 {{#include ../../../packages/samples/sources/basic-syntax/module.move:address_literal}}
@@ -56,18 +55,3 @@ Module members are declared inside the module body. To illustrate that, let's de
 ```Move
 {{#include ../../../packages/samples/sources/basic-syntax/module.move:members}}
 ```
-
-## Address block
-
-Before the introduction of the `address::module_name` syntax, modules were organized into `address {}` blocks. This way of code organization is still available today, but is not used widely. Modern practices imply having a single module per file, so the `address {}` block is rather a redundant construct.
-
-> Module addresses can be omitted if modules are organized into `address {}` blocks.
-
-```Move
-{{#include ../../../packages/samples/sources/basic-syntax/module.move:address_block}}
-```
-
-The modules defined in this code sample will be accessible as:
-
-- `book::another_module`
-- `book::yet_another_module`
diff --git a/book/src/before-we-begin/move-2024.md b/book/src/before-we-begin/move-2024.md
@@ -1,5 +1,5 @@
 # Move 2024
 
-Move 2024 is the new version of the Move language that is maintained by Mysten Labs. All of the examples in this book are written in Move 2024. If you're used to the pre-2024 version of Move, please, refer to the [Move 2024 Migration Guide](./../guides/2024-migration-guide.md) to learn about the differences between the two versions.
+Move 2024 is the new edition of the Move language maintained by Mysten Labs. All of the examples in this book are written in Move 2024. If you're used to the pre-2024 version of Move, please, refer to the [Move 2024 Migration Guide](./../guides/2024-migration-guide.md) to learn about the changes and improvements in the new edition.
 
 <!-- Notes ? -->
diff --git a/book/src/concepts/address.md b/book/src/concepts/address.md
@@ -1,4 +1,4 @@
-# Addresses
+# Address
 
 <!--
 

diff --git a/book/src/concepts/packages.md b/book/src/concepts/packages.md
@@ -1,4 +1,4 @@
-# Packages
+# Package
 
 <!--
 

diff --git a/book/src/concepts/what-is-a-transaction.md b/book/src/concepts/what-is-a-transaction.md
@@ -17,12 +17,38 @@ Transaction is a fundamental concept in the blockchain world. It is a way to int
 
 Transactions consist of:
 
-- a sender - the account that _signs_ the transaction;
+- a sender - the [account](./what-is-an-account.md) that _signs_ the transaction;
 - a list (or a chain) of commands - the operations to be executed;
 - command inputs - the arguments for the commands: either `pure` - simple values like numbers or strings, or `object` - objects that the transaction will access;
 - a gas object - the `Coin` object used to pay for the transaction;
 - gas price and budget - the cost of the transaction;
 
+## Commands
+
+Sui transactions may consist of multiple commands. Each command is a single built-in command (like publishing a package) or a call to a function in an already published package. The commands are executed in the order they are listed in the transaction, and they can use the results of the previous commands, forming a chain. Transaction either succeeds or fails as a whole.
+
+Schematically, a transaction looks like this (in pseudo-code):
+
+```
+Inputs:
+- sender = 0xa11ce
+
+Commands:
+- payment = SplitCoins(Gas, [ 1000 ])
+- item = MoveCall(0xAAA::market::purchase, [ payment ])
+- TransferObjects(item, sender)
+```
+
+In this example, the transaction consists of three commands:
+
+1. `SplitCoins` - a built-in command that splits a new coin from the passed object, in this case, the `Gas` object;
+2. `MoveCall` - a command that calls a function `purchase` in a package `0xAAA`, module `market` with the given arguments - the `payment` object;
+3. `TransferObjects` - a built-in command that transfers the object to the recipient.
+
+<!--
+> There are multiple different implementations of transaction building, for example
+-->
+
 ## Transaction Effects
 
 Transaction effects are the changes that a transaction makes to the blockchain state. More specifically, a transaction can change the state in the following ways:
@@ -33,8 +59,9 @@ Transaction effects are the changes that a transaction makes to the blockchain s
 
 The result of the executed transaction consists of different parts:
 
+- Tx Digest - the hash of the transaction which is used to identify the transaction;
 - Transaction Data - the inputs, commands and gas object used in the transaction;
 - Transaction Effects - the status and the "effects" of the transaction, more specifically: the status of the transaction, updates to objects and their new versions, the gas object used, the gas cost of the transaction, and the events emitted by the transaction;
-- Events - the custom events emitted by the transaction;
+- Events - the custom [events](./../programmability/events.md) emitted by the transaction;
 - Object Changes - the changes made to the objects, including the *change of ownership*;
 - Balance Changes - the changes made to the aggregate balances of the account involved in the transaction;
diff --git a/book/src/programmability/collections.md b/book/src/programmability/collections.md
@@ -1,17 +1,13 @@
 # Collections
 
-Collection types are a fundamental part of any programming language. They are used to store a collection of data, such as a list of items. The `vector` type has already been covered in the [vector section](./../basic-syntax/vector.md), and in this chapter we will cover the collection types offered by the [Sui Framework](./sui-framework.md).
-
-- [vector](#vector)
-- [VecSet](#VecSet)
-- [VecMap](#VecMap)
+Collection types are a fundamental part of any programming language. They are used to store a collection of data, such as a list of items. The `vector` type has already been covered in the [vector section](./../basic-syntax/vector.md), and in this chapter we will cover the vector-based collection types offered by the [Sui Framework](./sui-framework.md).
 
 ## Vector
 
 While we have previously covered the `vector` type in the [vector section](./../basic-syntax/vector.md), it is worth going over it again in a new context. This time we will cover the usage of the `vector` type in objects and how it can be used in an application.
 
 ```move
-// >insert collection vector code here<
+{{#include ../../../packages/samples/sources/programmability/collections.move:vector}}
 ```
 
 ## VecSet
@@ -22,6 +18,8 @@ While we have previously covered the `vector` type in the [vector section](./../
 {{#include ../../../packages/samples/sources/programmability/collections.move:vec_set}}
 ```
 
+VecSet will fail on attempt to insert a an item that already exists in the set.
+
 ## VecMap
 
 `VecMap` is a collection type that stores a map of key-value pairs. It is similar to a `VecSet`, but it allows you to associate a value with each item in the set. This makes it useful for storing a collection of key-value pairs, such as a list of addresses and their balances, or a list of user IDs and their associated data.
@@ -31,3 +29,18 @@ Keys in a `VecMap` are unique, and each key can only be associated with a single
 ```move
 {{#include ../../../packages/samples/sources/programmability/collections.move:vec_map}}
 ```
+
+## Limitations
+
+Standard collection types are a great way to store typed data with guaranteed safety and consistency. However, they are limited by the type of data they can store - the type system won't allow you to store a wrong type in a collection; and they're limited in size - by the object size limit. They will work for relatively small-sized sets and lists, but for larger collections you may need to use a different approach.
+
+## Summary
+
+- Vector is a native type that allows storing a list of items.
+- VecSet is built on top of vector and allows storing sets of unique items.
+- VecMap is used to store key-value pairs in a map-like structure.
+- Vector-based collections are strictly typed and limited by the object size limit and are best suited for small-sized sets and lists.
+
+## Next Steps
+
+In the next section we will cover [Dynamic Fields](./dynamic-fields.md) - an important primitive that allows for [Dynamic Collections](./dynamic-collections.md) - a way to store large collections of data in a more flexible, yet more expensive way.
diff --git a/book/src/programmability/sui-framework.md b/book/src/programmability/sui-framework.md
@@ -2,6 +2,10 @@
 
 Sui Framework is a default dependency set in the [Package Manifest](./../concepts/manifest.md). It depends on the [Standard Library](./../basic-syntax/standard-library.md) and provides Sui-specific features, including the interaction with the storage, and Sui-specific native types and modules.
 
+_For convenience, we grouped the modules in the Sui Framework into multiple categories. But they're still part of the same framework._
+
+## Core
+
 <!-- Custom CSS addition in the theme/custom.css  -->
 <div class="modules-table">
 
@@ -14,11 +18,25 @@ Sui Framework is a default dependency set in the [Package Manifest](./../concept
 | sui::clock                | Defines the `Clock` type and its methods                                    | [Epoch and Time](./epoch-and-time.md)                                  |
 | sui::dynamic_field        | Implements methods to add, use and remove dynamic fields                    | [Dynamic Fields](./dynamic-fields.md)                                  |
 | sui::dynamic_object_field | Implements methods to add, use and remove dynamic object fields             | [Dynamic Object Fields](./dynamic-object-fields.md)                    |
-| sui::vec_map              | Implements a map with vector keys                                           | [Collections](./collections.md)                                        |
-| sui::vec_set              | Implements a set type                                                       | [Collections](./collections.md)                                        |
 | sui::event                | Allows emitting events for off-chain listeners                              | [Events](./events.md)                                                  |
 | sui::package              | Defines the `Publisher` type and package upgrade methods                    | [Publisher](./publisher.md), [Package Upgrades](./package-upgrades.md) |
-| -                         | -                                                                           | -                                                                      |
+| sui::display              | Implements the `Display` object and ways to create and update it            | [Display](./display.md)                                                |
+
+</div>
+
+## Collections
+
+<div class="modules-table">
+
+| Module            | Description                                                       | Chapter                                         |
+| ----------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
+| sui::vec_set      | Implements a set type                                             | [Collections](./collections.md)                 |
+| sui::vec_map      | Implements a map with vector keys                                 | [Collections](./collections.md)                 |
+| sui::table        | Implements the `Table` type and methods to interact with it       | [Dynamic Collections](./dynamic-collections.md) |
+| sui::linked_table | Implements the `LinkedTable` type and methods to interact with it | [Dynamic Collections](./dynamic-collections.md) |
+| sui::bag          | Implements the `Bag` type and methods to interact with it         | [Dynamic Collections](./dynamic-collections.md) |
+| sui::object_table | Implements the `ObjectTable` type and methods to interact with it | [Dynamic Collections](./dynamic-collections.md) |
+| sui::object_bag   | Implements the `ObjectBag` type and methods to interact with it   | [Dynamic Collections](./dynamic-collections.md) |
 
 </div>
 
@@ -53,45 +71,38 @@ The source code of the Sui Framework is available in the [Sui repository](https:
 
 Modules:
 
-+ sui::address
-- sui::authenticator
-- sui::bag
-- sui::balance
-- sui::bcs
-- sui::borrow
-+ sui::clock
+Coins:
+- sui::pay
+- sui::sui
 - sui::coin
+- sui::token
+- sui::balance
 - sui::deny_list
+
+Commerce:
+- sui::kiosk
 - sui::display
-- sui::dynamic_field
-- sui::dynamic_object_field
-- sui::event
+- sui::kiosk_extension
+- sui::transfer_policy
+
+
+- sui::bcs
 - sui::hex
-- sui::linked_table
 - sui::math
-- sui::object_bag
-- sui::object_table
-- sui::object
-- sui::package
-- sui::pay
+- sui::types
+- sui::borrow
+
+
+- sui::authenticator
+
 - sui::priority_queue
-- sui::prover
-- sui::random
-- sui::sui
 - sui::table_vec
-- sui::table
-- sui::token
-- sui::transfer
-- sui::tx_context
-- sui::types
+
 - sui::url
-- sui::vec_map
-- sui::vec_set
 - sui::versioned
 
-- sui::kiosk
-- sui::kiosk_extension
-- sui::transfer_policy
+- sui::prover
+- sui::random
 
 - sui::bls12381
 - sui::ecdsa_k1

diff --git a/book/src/programmability/transaction-blocks.md b/book/src/programmability/transaction-blocks.md
diff --git a/book/src/programmability/witness-and-abstract-implementation.md b/book/src/programmability/witness-and-abstract-implementation.md
diff --git a/book/src/storage/README.md b/book/src/storage/README.md
@@ -1 +1,4 @@
 # Using Objects
+
+In the [Object Model](./../object) chapter we briefly explained the evolution of the Move language from an account-based model to an object-based model. In this chapter, we will dive deeper into the object model and explore how to use objects in your Sui applications. If you haven't read the [Object Model](./../object) chapter yet, we recommend you do so before continuing with this chapter.
+