Linera-documents translage v3

docs/_sidebar.md

@@ -1,41 +1,55 @@
-The Linera Manual
-- [The Linera Manual](en_US/introduction.md)
-- [**1.** Developers](en_US/developers.md)
-  -  [**1.1.** Getting Started](en_US/developers/getting_started.md)
-      - [**1.1.1.** Installation](en_US/developers/getting_started/installation.md)
-      - [**1.1.2.** Hello, Linera](en_US/developers/getting_started/hello_linera.md)
-  - [**1.2.** The Linera Protocol](en_US/developers/core_concepts.md)
-      - [**1.2.1.** Overview](en_US/developers/core_concepts/overview.md)
-      - [**1.2.2.** Microchains](en_US/developers/core_concepts/microchains.md)
-      - [**1.2.3.** Wallets](en_US/developers/core_concepts/wallets.md)
-      - [**1.2.4.** Node Service](en_US/developers/core_concepts/node_service.md)
-      - [**1.2.5.** Applications](en_US/developers/core_concepts/applications.md)
-  - [**1.3.** Writing Linera Applications](en_US/developers/sdk.md)
-      - [**1.3.1.** Creating a Project](en_US/developers/sdk/creating_a_project.md)
-      - [**1.3.2.** Creating the Application State](en_US/developers/sdk/state.md)
-      - [**1.3.3.** Defining the ABI](en_US/developers/sdk/abi.md)
-      - [**1.3.4.** Writing the Contract Binary](en_US/developers/sdk/contract.md)
-      - [**1.3.5.** Writing the Service Binary](en_US/developers/sdk/service.md)
-      - [**1.3.6.** Deploying the Application](en_US/developers/sdk/deploy.md)
-      - [**1.3.7.** Cross-Chain Messages](en_US/developers/sdk/messages.md)
-      - [**1.3.8.** Calling other Applications](en_US/developers/sdk/composition.md)
-      - [**1.3.9.** Printing Logs from an Application](en_US/developers/sdk/logging.md)
-      - [**1.3.10.** Writing Tests](en_US/developers/sdk/testing.md)
-   - [**1.4.** Advanced Topics](en_US/developers/advanced_topics.md)
-      - [**1.4.1.** Views](en_US/developers/advanced_topics/views.md)
-      - [**1.4.2.** Persistent Storage](en_US/developers/advanced_topics/persistent_storage.md)
-      - [**1.4.3.** Contract Finalization](en_US/developers/advanced_topics/contract_finalize.md)
-      - [**1.4.4.** Validators](en_US/developers/advanced_topics/validators.md)
-      - [**1.4.5.** Creating New Blocks](en_US/developers/advanced_topics/block_creation.md)
-      - [**1.4.6.** Applications that Handle Assets](en_US/developers/advanced_topics/assets.md)
-   - [**1.5.** Experimental](en_US/developers/experimental.md)
-      - [**1.5.1.** Machine Learning](en_US/developers/experimental/ml.md)
--  [**2.** Node Operators](en_US/operators.md)
-   - [**2.1.** Devnets](en_US/operators/devnets.md)
-      - [**2.1.1.** Docker Compose](en_US/operators/devnets/compose.md)
-      - [**2.1.2.** kind](en_US/operators/devnets/kind.md)
-   - [**2.2.** Testnets](en_US/operators/testnets.md)
-      - [**2.2.1.** Joining a Testnet](en_US/operators/testnets/joining.md)
--  [**3.** Appendix](en_US/appendix.md)
-    - [**3.1.** Glossary](en_US/appendix/glossary.md)
-    - [**3.2.** Videos](en_US/appendix/videos.md)
+[Welcome](en_US/introduction.md)
+---
+ The Linera Protocol
+- [Overview](./en_US/protocol/overview.md)
+- [Use cases](./en_US/protocol/use_cases.md)
+- [Roadmap](./en_US/protocol/roadmap.md)
+---
+Developers
+- [Getting Started](./en_US/developers/getting_started.md)
+  - [Installation](./en_US/developers/getting_started/installation.md)
+  - [Hello, Linera](./en_US/developers/getting_started/hello_linera.md)
+- [Core Concepts](./en_US/developers/core_concepts.md)
+  - [Microchains](./en_US/developers/core_concepts/microchains.md)
+  - [Wallets](./en_US/developers/core_concepts/wallets.md)
+  - [Node Service](./en_US/developers/core_concepts/node_service.md)
+  - [Applications](./en_US/developers/core_concepts/applications.md)
+- [Writing Backends](./en_US/developers/backend.md)
+  - [Creating a Project](./en_US/developers/backend/creating_a_project.md)
+  - [Creating the Application State](./en_US/developers/backend/state.md)
+  - [Defining the ABI](./en_US/developers/backend/abi.md)
+  - [Writing the Contract Binary](./en_US/developers/backend/contract.md)
+  - [Writing the Service Binary](./en_US/developers/backend/service.md)
+  - [Deploying the Application](./en_US/developers/backend/deploy.md)
+  - [Cross-Chain Messages](./en_US/developers/backend/messages.md)
+  - [Calling other Applications](./en_US/developers/backend/composition.md)
+  - [Using Data Blobs](./en_US/developers/backend/blobs.md)
+  - [Printing Logs from an Application](./en_US/developers/backend/logging.md)
+  - [Writing Tests](./en_US/developers/backend/testing.md)
+- [Writing Frontends](./en_US/developers/frontend.md)
+  - [Overview](./en_US/developers/frontend/overview.md)
+  - [Setup](./en_US/developers/frontend/setup.md)
+  - [Interactivity](./en_US/developers/frontend/interactivity.md)
+- [Advanced Topics](./en_US/developers/advanced_topics.md)
+  - [Contract Finalization](./en_US/developers/advanced_topics/contract_finalize.md)
+  - [Validators](./en_US/developers/advanced_topics/validators.md)
+  - [Creating New Blocks](./en_US/developers/advanced_topics/block_creation.md)
+  - [Applications that Handle Assets](./en_US/developers/advanced_topics/assets.md)
+- [Experimental](./en_US/developers/experimental.md)
+  - [Machine Learning](./en_US/developers/experimental/ml.md)
+---
+Node Operators
+- [Devnets](./en_US/operators/devnets.md)
+  - [Docker Compose](./en_US/operators/devnets/compose.md)
+  - [kind](./en_US/operators/devnets/kind.md)
+- [Testnets](./en_US/operators/testnets.md)
+  - [Requirements](./en_US/operators/testnets/requirements.md)
+  - [One-Click Deploy](./en_US/operators/testnets/one-click.md)
+  - [Manual Installation](./en_US/operators/testnets/manual-installation.md)
+  - [Verifying your Installation](./en_US/operators/testnets/verify-installation.md)
+  - [Monitoring and Logging](./en_US/operators/testnets/monitoring-logging.md)
+  - [Debugging](./en_US/operators/testnets/debugging.md)
+---
+- [Glossary](./en_US/appendix/glossary.md)
+- [Videos](./en_US/appendix/videos.md)
+---

docs/en_US/README.md

@@ -1,4 +1,4 @@
-![The Linera banner](../README.assets/Linera-Header_1920x284px.svg)
+![The Linera banner](./images/linera_banner_db73e9b.svg)
 
 # Linera Developer Reference
 
@@ -39,4 +39,4 @@
 - Linera Commuity [https://t.me/linera_official](https://t.me/linera_official)
 - Medium [https://medium.com/@linera](https://medium.com/@linera)
 - Discord [https://discord.com/invite/linera](https://discord.com/invite/linera)
-- LinkedIn [https://www.linkedin.com/company/linera-io](https://www.linkedin.com/company/linera-io)
+- LinkedIn [https://www.linkedin.com/company/linera-io](https://www.linkedin.com/company/linera-io)

docs/en_US/SUMMARY.md

@@ -0,0 +1,88 @@
+# Summary
+
+---
+
+[Welcome](introduction.md)
+
+---
+
+# The Linera Protocol
+
+- [Overview](protocol/overview.md)
+
+- [Use cases](protocol/use_cases.md)
+
+- [Roadmap](protocol/roadmap.md)
+
+---
+
+# Developers
+
+- [Getting Started](developers/getting_started.md)
+
+  - [Installation](developers/getting_started/installation.md)
+  - [Hello, Linera](developers/getting_started/hello_linera.md)
+
+- [Core Concepts](developers/core_concepts.md)
+
+  - [Microchains](developers/core_concepts/microchains.md)
+  - [Wallets](developers/core_concepts/wallets.md)
+  - [Node Service](developers/core_concepts/node_service.md)
+  - [Applications](developers/core_concepts/applications.md)
+
+- [Writing Backends](developers/backend.md)
+
+  - [Creating a Project](developers/backend/creating_a_project.md)
+  - [Creating the Application State](developers/backend/state.md)
+  - [Defining the ABI](developers/backend/abi.md)
+  - [Writing the Contract Binary](developers/backend/contract.md)
+  - [Writing the Service Binary](developers/backend/service.md)
+  - [Deploying the Application](developers/backend/deploy.md)
+  - [Cross-Chain Messages](developers/backend/messages.md)
+  - [Calling other Applications](developers/backend/composition.md)
+  - [Using Data Blobs](developers/backend/blobs.md)
+  - [Printing Logs from an Application](developers/backend/logging.md)
+  - [Writing Tests](developers/backend/testing.md)
+
+- [Writing Frontends](developers/frontend.md)
+
+  - [Overview](developers/frontend/overview.md)
+  - [Setup](developers/frontend/setup.md)
+  - [Interactivity](developers/frontend/interactivity.md)
+
+- [Advanced Topics](developers/advanced_topics.md)
+
+  - [Contract Finalization](developers/advanced_topics/contract_finalize.md)
+  - [Validators](developers/advanced_topics/validators.md)
+  - [Creating New Blocks](developers/advanced_topics/block_creation.md)
+  - [Applications that Handle Assets](developers/advanced_topics/assets.md)
+
+- [Experimental](developers/experimental.md)
+
+  - [Machine Learning](developers/experimental/ml.md)
+
+---
+
+# Node Operators
+
+- [Devnets](operators/devnets.md)
+
+  - [Docker Compose](operators/devnets/compose.md)
+  - [kind](operators/devnets/kind.md)
+
+- [Testnets](operators/testnets.md)
+
+  - [Requirements](operators/testnets/requirements.md)
+  - [One-Click Deploy](operators/testnets/one-click.md)
+  - [Manual Installation](operators/testnets/manual-installation.md)
+  - [Verifying your Installation](operators/testnets/verify-installation.md)
+  - [Monitoring and Logging](operators/testnets/monitoring-logging.md)
+  - [Debugging](operators/testnets/debugging.md)
+
+---
+
+- [Glossary](appendix/glossary.md)
+
+- [Videos](appendix/videos.md)
+
+---

docs/en_US/appendix/glossary.md

@@ -36,7 +36,7 @@
 - **Committee**: The set of all validators for a particular _epoch_, together
   with their voting weights.
 
-- **Chain Owner**: The owner of a _user chain_ or _permissioned chain_. This is
+- **Chain Owner**: The owner of a _user chain_ or _multi-user chain_. This is
   represented as the alphanumeric identifier derived from the hash of the
   owner's public key.
 
@@ -86,15 +86,15 @@
   another. Users typically use operations to start interacting with an
   application on their own chain.
 
-- **Permissioned Chain**: A microchain which is owned by more than one user.
-  Users take turns proposing blocks and the likelihood of selection is
-  proportional to their _weight_.
+- **Multi-user Chain**: A microchain which is owned by more than one user. Users
+  take turns proposing blocks and the likelihood of selection is proportional to
+  their _weight_.
 
 - **Project**: The collection of files and dependencies which are built into the
   bytecode which is instantiated as an application on the Linera Network.
 
 - **Public Chain**: A microchain with full BFT consensus with a strict set of
-  permissions relied on for the operation of the network,
+  permissions relied on for the operation of the network.
 
 - **Quorum**: A set of validators representing > ⅔ of the total stake. A quorum
   is required to create a certificate.

docs/en_US/appendix/videos.md

@@ -1,7 +1,7 @@
 # Videos
 
 We're constantly improving the SDK and creating new material. Below are some of
-our recent tutorial and presentation videos:
+our recent tutorials and presentations videos:
 
 ### [Rust on Linera: Spring 2024 Hackathon Kick-Off](https://www.youtube.com/watch?v=gVOHsS7d5qI)
 
@@ -34,6 +34,6 @@ empowerment in the new web ecosystem from Consensus 2024.
 
 For the latest videos and highlights, check out our
 [YouTube channel](https://www.youtube.com/@linera_io) and
-[Twitter Media](https://twitter.com/linera_io).
+[X (formerly Twitter) Media](https://x.com/linera_io).
 
 _Happy viewing!_

docs/en_US/developers/advanced_topics/assets.md

@@ -16,24 +16,23 @@ Such an application should have a designated operation or message that causes it
 to close the chain: when that operation is executed, it should send back all
 remaining assets, and call the runtime's `close_chain` method.
 
-Once the chain is closed, owners can still create blocks rejecting messages.
+Once the chain is closed, owners can still create blocks to reject messages.
 That way, even assets that are in flight can be returned.
 
 The
 [`matching-engine` example application](https://github.com/linera-io/linera-protocol/tree/main/examples/matching-engine)
 does this:
 
-```rust
+```rust,ignore
     async fn execute_operation(&mut self, operation: Operation) -> Self::Response {
         match operation {
             // ...
             Operation::CloseChain => {
-                for order_id in self.state.orders.indices().await? {
+                for order_id in self.state.orders.indices().await.unwrap() {
                     match self.modify_order(order_id, ModifyAmount::All).await {
-                        Ok(transfer) => self.send_to(transfer),
+                        Some(transfer) => self.send_to(transfer),
                         // Orders with amount zero may have been cleared in an earlier iteration.
-                        Err(MatchingEngineError::OrderNotPresent) => continue,
-                        Err(error) => return Err(error),
+                        None => continue,
                     }
                 }
                 self.runtime

docs/en_US/developers/advanced_topics/block_creation.md

@@ -9,7 +9,7 @@ several types of chains, depending on how new blocks are produced.
 - The simplest and lowest-latency type of chain is called _single-owner_ chain.
 
 - Other types of Linera chains not currently supported in the SDK include
-  _permissioned chains_ and _public chains_ (see the
+  _multi-user chains_ and _public chains_ (see the
   [whitepaper](https://linera.io/whitepaper) for more context).
 
 > For most types of chains (all but _public chains_), Linera validators do not
@@ -54,9 +54,9 @@ that they never propose multiple blocks at the same height. Otherwise, the chain
 may be stuck: once each of the two conflicting blocks has been signed by enough
 validators, it becomes impossible to collect a quorum of votes for either block.
 
-In the future, we anticipate that most users will use _permissioned chains_ even
-if they are the only owners of their chains. Permissioned chains have two
+In the future, we anticipate that most users will use _multi-user chains_ even
+if they are the only owners of their chains. Multi-user chains have two
 confirmation steps instead of one, but it is not possible to accidentally make a
-chain unextendable. They also allow users to delegate certain admistrative tasks
-to third-parties, notably to help with epoch changes (i.e. when the validators
-change if reconfigured).
+chain unextendable. They also allow users to delegate certain administrative
+tasks to third-parties, notably to help with epoch changes (i.e. when the
+validators change if reconfigured).

docs/en_US/developers/advanced_topics/contract_finalize.md

@@ -18,20 +18,53 @@ As an example, a contract that executes a cross-application call with
 `Operation::StartSession` may require the same caller to perform another
 cross-application call with `Operation::EndSession` before the transaction ends.
 
-```rust
+```rust,edition2021
+# extern crate serde;
+# extern crate linera_sdk;
+# use serde::{Deserialize, Serialize};
+# use linera_sdk::linera_base_types::*;
+# use linera_sdk::*;
+# use linera_sdk::abi::*;
+# use std::collections::HashSet;
+# use linera_sdk::views::{linera_views, RegisterView, RootView, ViewStorageContext};
+# use crate::linera_sdk::views::View as _;
+# use linera_sdk::linera_base_types::ApplicationId;
+
+#[derive(RootView)]
+#[view(context = "ViewStorageContext")]
+pub struct MyState {
+    pub value: RegisterView<u64>,
+    // ...
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+pub enum Operation { StartSession, EndSession }
+
+pub struct MyAbi;
+
+impl ContractAbi for MyAbi {
+    type Operation = Operation;
+    type Response = ();
+}
+
 pub struct MyContract {
-    state: MyState;
-    runtime: ContractRuntime<Self>;
-    active_sessions: HashSet<ApplicationId>;
+    state: MyState,
+    runtime: ContractRuntime<Self>,
+    active_sessions: HashSet<ApplicationId>,
+}
+
+impl WithContractAbi for MyContract {
+    type Abi = MyAbi;
 }
 
 impl Contract for MyContract {
     type Message = ();
     type InstantiationArgument = ();
     type Parameters = ();
+    type EventValue = ();
 
     async fn load(runtime: ContractRuntime<Self>) -> Self {
-        let state = MyState::load(ViewStorageContext::from(runtime.key_value_store()))
+        let state = MyState::load(runtime.root_view_storage_context())
             .await
             .expect("Failed to load state");
 
@@ -45,7 +78,7 @@ impl Contract for MyContract {
     async fn instantiate(&mut self, (): Self::InstantiationArgument) {}
 
     async fn execute_operation(&mut self, operation: Self::Operation) -> Self::Response {
-        let caller = self.runtime
+        let caller_id = self.runtime
             .authenticated_caller_id()
             .expect("Missing caller ID");
 
@@ -65,11 +98,11 @@ impl Contract for MyContract {
         }
     }
 
-    async fn execute_message(&mut self, message: Self::Message) -> Result<(), Self::Error> {
+    async fn execute_message(&mut self, message: Self::Message) {
         unreachable!("This example doesn't support messages");
     }
 
-    async fn store(&mut self) {
+    async fn store(mut self) {
         assert!(
             self.active_sessions.is_empty(),
             "Some sessions have not ended"