[book] massive rewrite

book/404.md

@@ -1,3 +1,8 @@
+---
+description: "Page not found."
+unlisted: true
+---
+
 # Page not Found
 
 You're looking for a page that doesn't exist, or has been moved. Please check the URL and try again.

book/appendix/acknowledgements.md

@@ -8,3 +8,18 @@ description: "Acknowledgements for The Move Book: credits to The Rust Book, cont
 personally grateful to the authors of the book, Steve Klabnik and Carol Nichols, for their work, as
 I have learned a lot from it. This book is a small tribute to their work and an attempt to bring a
 similar learning experience to the Move community.
+
+## The Move Community
+
+Just as important is the Move community, which has shaped this book from its very first edition -
+written back when the language had no official documentation. Readers who asked questions, pointed
+out confusing passages, reported mistakes, and opened issues and pull requests made the book what
+it is today. The full list of contributors is available on
+[GitHub](https://github.com/MystenLabs/move-book/graphs/contributors), and the
+[Contributing](./contributing) appendix describes how to join them.
+
+The Move language itself is the work of a large community of researchers and engineers - from the
+original Move team, who designed the language and wrote the first reference materials, to the
+contributors evolving it today across many companies and projects. The
+[Move Reference](/reference), published alongside this book, builds directly on the Move Language
+Reference written by the Move contributors.

book/appendix/reserved-addresses.md

@@ -11,6 +11,10 @@ between environments and are used for specific native operations.
 - `0x2` - address of the [Sui Framework](./../programmability/sui-framework.md) (alias `sui`)
 - `0x5` - address of the `SuiSystem` object
 - `0x6` - address of the system [`Clock` object](./../programmability/epoch-and-time.md)
-- `0x8` - address of the system `Random` object
-- `0xc` - address of the system `CoinRegistry` object
+- `0x8` - address of the system [`Random` object](./../programmability/randomness.md)
+- `0xc` - address of the system
+  [`CoinRegistry` object](./../programmability/balance-and-coin.md#currency-and-the-coin-registry)
+- `0xd` - address of the system `DisplayRegistry` object (see
+  [Object Display](./../programmability/display.md))
 - `0x403` - address of the `DenyList` system object
+- `0xacc` - address of the system `AccumulatorRoot` object

book/before-we-begin/install-move-registry-cli.md

@@ -44,3 +44,8 @@ cargo install --locked --git https://github.com/mystenlabs/mvr --branch release
 
 For troubleshooting the installation process, please refer to the
 [Install MVR](https://docs.suins.io/move-registry/tooling/mvr-cli#installation) Guide.
+
+## Using MVR
+
+To learn how to find packages in the registry and use them as dependencies in your projects, see
+the [Using Move Registry](./../guides/using-move-registry) guide.

book/concepts/address.md

@@ -4,34 +4,9 @@ description: "Learn about addresses in Sui — 32-byte unique identifiers used t
 
 # Address
 
-<!--
-
-Chapter: Concepts
-Goal: explain locations and addresses
-Notes:
-    - don't talk about the type
-    - packages, accounts and objects are identified by addresses
-    - addresses are 32 bytes long
-    - addresses are unique
-    - represented as hex strings (64 characters) prefixed with 0x
-    - addresses are case insensitive
-
-Links:
-    - address type
-
-
-- mention what an address is, because it identifies a package
-    - address is used for packages, objects, and accounts
-    - address is a 32-byte value
-    - address is written in hexadecimal notation
-    - don't describe the type yet
-    - focus on the concept of address on blockchain and on Sui in particular
-
- -->
-
-Address is a unique identifier of a location on the blockchain. It is used to identify
+An address is a unique identifier of a location on the blockchain. It is used to identify
 [packages](./packages), [accounts](./what-is-an-account), and [objects](./../object/object-model).
-Address has a fixed size of 32 bytes and is usually represented as a hexadecimal string prefixed
+An address has a fixed size of 32 bytes and is usually represented as a hexadecimal string prefixed
 with `0x`. Addresses are case insensitive.
 
 ```move
@@ -43,7 +18,7 @@ with `0x`.
 
 Sui also has reserved addresses that are used to identify standard packages and objects. Reserved
 addresses are typically simple values that are easy to remember and type. For example, the address
-of the Standard Library is `0x1`. Addresses, shorter than 32 bytes, are padded with zeros to the
+of the Standard Library is `0x1`. Addresses shorter than 32 bytes are padded with zeros to the
 left.
 
 ```move
@@ -52,11 +27,12 @@ left.
 
 Here are some examples of reserved addresses:
 
-- `0x1` - address of the Sui Standard Library (alias `std`)
+- `0x1` - address of the Move Standard Library (alias `std`)
 - `0x2` - address of the Sui Framework (alias `sui`)
 - `0x6` - address of the system `Clock` object
 
-> You can find all reserved addresses in the [Appendix B](../appendix/reserved-addresses).
+> You can find all reserved addresses in
+> [Appendix B: Reserved Addresses](../appendix/reserved-addresses).
 
 ## Further Reading
 

book/concepts/index.md

@@ -4,8 +4,8 @@ description: "Core Sui and Move concepts: packages, accounts, transactions, addr
 
 # Concepts
 
-In this chapter you will learn about the basic concepts of Sui and Move. You will learn what is a
-package, how to interact with it, what is an account and a transaction, and how data is stored on
-Sui. While this chapter is not a complete reference, and you should refer to the
-[Sui Documentation](https://docs.sui.io) for that, it will give you a good understanding of the
-basic concepts required to write Move programs on Sui.
+In this chapter you will learn about the basic concepts of Sui and Move: what a package is and how
+to interact with it, what an account and a transaction are, and how data is stored on Sui. While
+this chapter is not a complete reference - refer to the [Sui Documentation](https://docs.sui.io)
+for that - it will give you a good understanding of the concepts required to write Move programs
+on Sui.

book/concepts/manifest.md

@@ -1,3 +1,7 @@
+---
+description: "The Move.toml package manifest: package metadata, dependencies, named addresses, and dependency overrides explained."
+---
+
 # Package Manifest
 
 The `Move.toml` is a manifest file that describes the [package](./packages) and its dependencies. It
@@ -22,9 +26,9 @@ published on chain, but they are used in tooling and release management; they al
 edition for the compiler.
 
 - `name` - the name of the package when it is imported;
-- `edition` - the edition of the Move language; currently, the only valid value is `2024`.
-
-<!-- published-at -->
+- `edition` - the edition of the Move language; currently, the only valid value is `2024`;
+- `published-at` - the address the package was published at; set after publishing, it lets
+  dependent packages and tooling resolve the on-chain address of this package.
 
 ### Dependencies
 
@@ -41,14 +45,26 @@ example = { git = "https://github.com/example/example.git", subdir = "path/to/pa
 my_package = { local = "../my-package" }
 ```
 
-Packages also import addresses from other packages. For example, the Sui dependency adds the `std`
-and `sui` addresses to the project. These addresses can be used in the code as aliases for the
-addresses.
+Packages also import named addresses from their dependencies. For example, the Sui dependency adds
+the `std` and `sui` addresses to the project, usable in the code in place of the full `0x1` and
+`0x2` addresses.
 
 Starting with version 1.45 of the Sui CLI, the Sui system packages (`std`, `sui`, `system`,
 `bridge`, and `deepbook`) are automatically added as dependencies if none of them are explicitly
 listed.
 
+### Addresses
+
+The `[addresses]` section declares _named addresses_: aliases that can be used in the code in place
+of full addresses. The package's own name is conventionally declared here with the value `0x0`,
+which is the placeholder used until the package is published:
+
+```toml
+[addresses]
+my_project = "0x0"
+alice = "0xA11CE"
+```
+
 ### Resolving Version Conflicts with Override
 
 Sometimes dependencies have conflicting versions of the same package. For example, if you have two

book/concepts/packages.md

@@ -4,22 +4,6 @@ description: "Understand Move packages — the unit of code organization contain
 
 # Package
 
-<!--
-
-    - packages and how they're stored
-        - overview of packages and their contents (use a diagram)
-        - how a package is created, and what it consists of
-        - what is the package manifest
-        - describe how "name" field is used
-        - mention the "edition" field
-        - what are the folders in a package and what are they for
-        - how packages are imported (give Sui as an example)
-        - what are addresses, and how they identify packages
-        - how packages are published
-        - leave a note that packages are also *upgradable*
-
--->
-
 Move is a language for writing smart contracts - programs that are stored and run on the blockchain.
 A single program is organized into a package. A package is published on the blockchain and is
 identified by an [address](./address). A published package can be interacted with by sending
@@ -29,7 +13,7 @@ other packages.
 > To create a new package, use the `sui move new` command. To learn more about the command, run
 > `sui move new --help`.
 
-Package consists of modules - separate scopes that contain functions, types, and other items.
+A package consists of modules - separate scopes that contain functions, types, and other items.
 
 ```
 package 0x...
@@ -45,7 +29,7 @@ package 0x...
 
 Locally, a package is a directory with a `Move.toml` file and a `sources` directory. The `Move.toml`
 file - called the "package manifest" - contains metadata about the package, and the `sources`
-directory contains the source code for the modules. Package usually looks like this:
+directory contains the source code for the modules. A package usually looks like this:
 
 ```
 sources/
@@ -65,9 +49,9 @@ used for code examples, and is also not published on-chain.
 
 ## Published Package
 
-During development, package doesn't have an address and it needs to be set to `0x0`. Once a package
-is published, it gets a single unique [address](./address) on the blockchain containing its modules'
-bytecode. A published package becomes _immutable_ and can be interacted with by sending
+During development, a package doesn't have an address yet, and `0x0` is used in its place. Once a
+package is published, it gets a single unique [address](./address) on the blockchain containing its
+modules' bytecode. A published package becomes _immutable_ and can be interacted with by sending
 transactions.
 
 ```
@@ -76,7 +60,14 @@ transactions.
     another_module: <bytecode>
 ```
 
-## Links
+While the published bytecode can never be changed, a package can be _upgraded_: an upgrade
+publishes a new version of the package at a new address, leaving the old version intact. We touch
+on the implications throughout the book: the
+[Package Upgrades](./../programmability/package-upgrades) section explains the mechanics, and the
+[Upgradeability Practices](./../guides/upgradeability-practices) guide covers how to design for
+upgrades.
+
+## Further Reading
 
 - [Package Manifest](./manifest)
 - [Address](./address)

book/concepts/what-is-a-transaction.md

@@ -4,21 +4,9 @@ description: "Learn how Sui transactions work: structure, commands, gas payments
 
 # Transaction
 
-Transaction is a fundamental concept in the blockchain world. It is a way to interact with a
-blockchain. Transactions are used to change the state of the blockchain, and they are the only way
-to do so. In Move, transactions are used to call functions in a package, deploy new packages, and
-upgrade existing ones.
-
-<!--
-
-- how user interacts with a program
-    - mention public functions
-    - give a concept of an entry / public function without getting into details
-    - mention that functions are called in transactions
-    - mention that transactions are sent by accounts
-    - every transaction specifies object it operates on
-
- -->
+A transaction is the fundamental way to interact with a blockchain. Transactions are used to
+change the state of the blockchain, and they are the only way to do so. On Sui, a transaction can
+call functions in published packages, deploy new packages, and upgrade existing ones.
 
 ## Transaction Structure
 
@@ -31,11 +19,11 @@ Transactions consist of:
 - 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;
+- a gas price and budget - the cost of the transaction.
 
 ## Inputs
 
-Transaction inputs are the arguments for the transaction and are split between 2 types:
+Transaction inputs are the arguments for the transaction, and come in two types:
 
 - Pure arguments: These are mostly [primitive types](../move-basics/primitive-types) with some extra
   additions. A pure argument can be:
@@ -47,7 +35,7 @@ Transaction inputs are the arguments for the transaction and are split between 2
   - [`std::ascii::String`](../move-basics/string#ascii-strings), ASCII strings.
   - [`vector<T>`](../move-basics/vector), where `T` is a pure type.
   - [`std::option::Option<T>`](../move-basics/option), where `T` is a pure type.
-  - [`std::object::ID`](../storage/uid-and-id), typically points to an object. See also
+  - [`sui::object::ID`](../storage/uid-and-id), typically points to an object. See also
   [What is an Object](../object/object-model).
 - Object arguments: These are objects or references of objects that the transaction will access. An
   object argument needs to be either a shared object, a frozen object, or an object that the
@@ -61,6 +49,12 @@ publishing a package) or a call to a function in an already published package. T
 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.
 
+Any [`public`](../move-basics/visibility#public-visibility) function can be called as a command:
+making a function `public` is all it takes for users to call it in a transaction, and it is the
+default way to expose functionality in Move. (There is also the
+[`entry`](../move-basics/visibility#entry-modifier) modifier, which creates functions callable
+_only_ as transaction commands - a deliberately restricted option, covered later in the book.)
+
 Schematically, a transaction looks like this (in pseudo-code):
 
 ```
@@ -81,10 +75,6 @@ In this example, the transaction consists of three commands:
    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
@@ -104,4 +94,10 @@ The result of the executed transaction consists of different parts:
 - Events - the custom [events](./../programmability/events) 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;
+  transaction.
+
+## Further Reading
+
+- [Transactions](https://docs.sui.io/concepts/transactions) in the Sui Documentation.
+- [Programmable Transaction Blocks](https://docs.sui.io/concepts/transactions/prog-txn-blocks) in
+  the Sui Documentation.

book/concepts/what-is-an-account.md

@@ -4,31 +4,19 @@ description: "Understand Sui accounts: how they are generated from private keys,
 
 # Account
 
-<!--
-
-- user is an account
-    - account is identified by an address
-    - account is generated from a private key
-    - account can own objects
-    - account can send transactions
-    - every transaction has a sender
-    - sender is identified by an address
-    - sui cryptographic agility
-    - sui account types
-    - supported curves: ed25519, secp256k1, zklogin
-
- -->
-
 An account is a way to identify a user. An account is generated from a private key, and is
 identified by an address. An account can own objects, and can send transactions. Every transaction
 has a sender, and the sender is identified by an [address](./address).
 
-Sui supports multiple cryptographic algorithms for account generation. The two supported curves are
-ed25519, secp256k1, and there is also a special way of generating an account - zklogin. The
-cryptographic agility - the unique feature of Sui - allows for flexibility in the account
-generation.
+An account does not need to be created or registered anywhere: it exists as soon as a keypair is
+generated, and any valid address can receive objects without prior setup. There is no on-chain
+record of "all accounts" - an address with no objects and no transaction history is
+indistinguishable from one that was never used.
 
-<!-- The cryptographic agility allows for flexibility in the account generation -->
+Sui supports multiple signature schemes for accounts: ed25519, ECDSA (over the secp256k1 and
+secp256r1 curves), multisig - an account controlled by a combination of keys - and zkLogin, which
+derives an account from a Web2 login. This _cryptographic agility_ gives Sui unusual flexibility in
+how accounts are created and controlled.
 
 ## Further Reading