From 6c61ae6f620df93e51fa7858e196fcd2c03b31b2 Mon Sep 17 00:00:00 2001 From: Janito Vaqueiro Ferreira Filho Date: Mon, 6 May 2024 17:49:53 -0300 Subject: [PATCH] Small tweaks to the documentation (#100) * Add target to "Getting Started" build command Ensure that the Wasm target is specified, because now there is no Cargo-specific configuration file. * Rephrase "Wasm/JS" goal Make it clearer that it's about running on the browser instead of supporting Javascript in applications. * Change adjective to adverb Tweak the phrasing to try to make it more fluid. * Add link to WebAssembly website Make it easier to reach for readers on that page. * Remove unnecessary verbs Doesn't add much to the phrase. * Remove early reference to views No need to mention it yet. * Reword expression to better define earlier Make it explicit that the message was created by an earlier block. * Replace "in chain" for "on chain" Seems like a more common expression. * Add a sentence to describe what a state is Now that there isn't a `State` trait, it's best to at least mention why there's a separate type for persisted data. * Don't link to source code from `main` Use the specific commit the documentation was tested with instead. --- src/core_concepts/applications.md | 17 +++++++---------- src/core_concepts/overview.md | 4 ++-- src/getting_started/hello_linera.md | 5 +---- src/sdk/contract.md | 3 ++- src/sdk/state.md | 3 ++- 5 files changed, 14 insertions(+), 18 deletions(-) diff --git a/src/core_concepts/applications.md b/src/core_concepts/applications.md index 153c2af9..2687ac46 100644 --- a/src/core_concepts/applications.md +++ b/src/core_concepts/applications.md @@ -3,9 +3,9 @@ The programming model of Linera is designed so that developers can take advantage of microchains to scale their applications. -Linera uses the WebAssembly Virtual Machine (Wasm) to execute user applications. -Currently, the [Linera SDK](../sdk.md) is focused on the -[Rust](https://www.rust-lang.org/) programming language. +Linera uses the [WebAssembly (Wasm)](https://webassembly.org) Virtual Machine to +execute user applications. Currently, the [Linera SDK](../sdk.md) is focused on +the [Rust](https://www.rust-lang.org/) programming language. Linera applications are structured using the familiar notion of **Rust crate**: the external interfaces of an application (including initialization parameters, @@ -28,8 +28,8 @@ flexible: 3. A user can create a new application instance, by providing the bytecode identifier and initialization arguments. This process returns an application identifier which can be used to reference and interact with the application. -4. The same bytecode identifier can be used as many times is needed by as many - users are needed to create distinct applications. +4. The same bytecode identifier can be used as many times needed by as many + users needed to create distinct applications. Importantly, the application deployment lifecycle is abstracted from the user, and an application can be published with a single command: @@ -54,9 +54,6 @@ The **service** is non-metered and read-only. It is used primarily to query the state of an application and populate the presentation layer (think front-end) with the data required for a user interface. -Finally, the application's state is shared by the contract and service in the -form of a [View](./../advanced_topics/views.md), but more on that later. - ## Operations and Messages > For this section we'll be using a simplified version of the example @@ -96,7 +93,7 @@ can be sent from one chain to another, always within the same application. Block proposers also actively include messages in their block proposal, but unlike with operations, they are only allowed to include them in the right order (possibly skipping some), and only if they were actually created by another -chain (or the same chain, earlier). +chain (or by a previous block of the same chain). In our "fungible token" application, a message to credit an account would look like this: @@ -124,7 +121,7 @@ authentication as the received message. In other words, the block signer can have its authority propagated across chains through series of messages. This allows applications to safely store user state -in chains that the user may not have the authority to produce blocks. The +on chains that the user may not have the authority to produce blocks. The application may also allow only the authorized user to change that state, and not even the chain owner is able to override that. diff --git a/src/core_concepts/overview.md b/src/core_concepts/overview.md index f6904577..ce7e0bbd 100644 --- a/src/core_concepts/overview.md +++ b/src/core_concepts/overview.md @@ -184,7 +184,7 @@ as follows. - [x] Support for read-only GraphQL services in Wasm - [x] Support for mocked system APIs - [x] Improve host/guest stub generation to make mocks easier -- [ ] Support for Wasm/JS +- [ ] Support for running Wasm applications in the browser ### Storage @@ -212,7 +212,7 @@ as follows. - [x] Observability - [x] Kubernetes support in CI - [x] Deployment using a cloud provider -- [ ] Horizontal scalable frontend (aka. proxy) +- [ ] Horizontally scalable frontend (aka. proxy) - [ ] Dynamic shard assignment - [ ] Cloud integration to demonstrate elastic scaling diff --git a/src/getting_started/hello_linera.md b/src/getting_started/hello_linera.md index 6ccc14df..0001f882 100644 --- a/src/getting_started/hello_linera.md +++ b/src/getting_started/hello_linera.md @@ -89,12 +89,9 @@ execute bytecode. Let's build the `counter` application from the `examples/` subdirectory: ```bash -cd examples/counter && cargo build --release +cd examples/counter && cargo build --release --target wasm32-unknown-unknown ``` -> Note: This will automatically build Wasm, not native code, thanks to the -> configuration file `examples/.cargo/config.toml`. - ## Publishing your Application You can publish the bytecode and create an application using it on your local diff --git a/src/sdk/contract.md b/src/sdk/contract.md index 7b3cad95..ac8ef6f0 100644 --- a/src/sdk/contract.md +++ b/src/sdk/contract.md @@ -51,7 +51,8 @@ pub trait Contract: WithContractAbi + ContractAbi + Send + Sized { ``` The full trait definition can be found -[here](https://github.com/linera-io/linera-protocol/blob/main/linera-sdk/src/lib.rs). +[here](https://github.com/linera-io/linera-protocol/blob/{{#include +../../.git/modules/linera-protocol/HEAD}}/linera-sdk/src/lib.rs). There's quite a bit going on here, so let's break it down and take one method at a time. diff --git a/src/sdk/state.md b/src/sdk/state.md index dfae1224..9555671e 100644 --- a/src/sdk/state.md +++ b/src/sdk/state.md @@ -1,7 +1,8 @@ # Creating the Application State The `struct` which defines your application's state can be found in -`src/state.rs`. +`src/state.rs`. An application state is the data that is persisted on storage +between transactions. To represent our counter, we're going to need a single `u64`. To persist the counter we'll be using Linera's [view](../advanced_topics/views.md) paradigm.