Update README and fix "specifications" -> "specification" (#979)

CODING_GUIDE.md

@@ -72,7 +72,7 @@ Substrate is organized around components that are considered as core components
 
 The blockchain-related logic is plugged on top of these core components and can, however, be changed. One can, for example, remove everything related to the Babe consensus algorithm and replace with by another consensus algorithm.
 
-*smoldot*, on the other hand, is implemented following the current state of the Substrate/Polkadot specifications, and assumes that these specifications will never change. This assumption allows, in turn, for better readability and more flexibility when it comes to the purely engineering aspects of the codebase.
+*smoldot*, on the other hand, is implemented following the current state of the Substrate/Polkadot specification, and assumes that this specification will never change. This assumption allows, in turn, for better readability and more flexibility when it comes to the purely engineering aspects of the codebase.
 
 For example, the code that decodes block headers is written in a way that would be relatively painful (but straight-forward) to modify, if the format of a block header ever changed. However, smoldot simply assumes that the format of block headers will rarely, if ever, change.
 

README.md

@@ -10,8 +10,6 @@ In order to simplify the code, two main design decisions have been made compared
 
 - No pluggable architecture. `smoldot` supports a certain hardcoded list of consensus algorithms, at the moment Babe, Aura, and GrandPa. Support for other algorithms can only be added by modifying the code of smoldot, and it is not possible to plug a custom algorithm from outside.
 
-## How to test
-
 There exists two clients: the full client and the wasm light node.
 
 The main development focus is currently around the wasm light node. Using https://github.com/polkadot-js/api/ and https://github.com/paritytech/substrate-connect/ (which uses smoldot as an implementation detail), one can easily connect to a chain and interact in a fully trust-less way with it, from JavaScript.
@@ -32,10 +30,12 @@ The following list is a best-effort list of packages that must be available on t
 
 Pre-requisite: in order to run the wasm light node, you must have installed [rustup](https://rustup.rs/).
 
-The wasm light node can be tested with `cd bin/wasm-node/javascript` and `npm start`. This will start a WebSocket server capable of answering JSON-RPC requests. You can then navigate to <https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944> in order to interact with the Westend chain.
+The wasm light node can be tested with `cd bin/wasm-node/javascript` and `npm start`. This will compile the smoldot wasm light node and start a WebSocket server capable of answering JSON-RPC requests. You can then navigate to <https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944> in order to interact with the Westend chain.
 
 > Note: The `npm start` command starts a small JavaScript shim, on top of the wasm light node, that hardcodes the chain to Westend and starts the WebSocket server. The wasm light node itself can connect to a variety of different chains (not only Westend) and doesn't start any server.
 
+The Wasm light node is published on NPM: https://www.npmjs.com/package/smoldot
+
 # Objectives
 
 There exists multiple objectives behind this repository:
@@ -50,19 +50,20 @@ As a quick overview, at the time of writing of this README, the following is sup
 
 - Verifying Babe and Aura blocks.
 - "Executing" blocks, by calling `Core_execute_block`.
-- Verifying GrandPa justifications.
+- Verifying GrandPa justifications and GrandPa commit messages.
 - "Optimistic syncing", in other words syncing by assuming that there isn't any fork.
 - Verifying storage trie proofs.
 - The WebSocket JSON-RPC server is in progress, but its design is still changing.
 - An informant.
 - A telemetry client (mostly copy-pasted from Substrate and substrate-telemetry).
 - An unfinished new networking stack.
+- A transaction pool for light clients.
+- A SQLite database for the full client.
 
 The following isn't done yet:
 
 - Authoring blocks isn't supported.
-- There is no transaction pool.
-- Anything related to GrandPa networking messages. Finality can only be determined by asking a full node for a justification.
-- No actual database for the full client.
+- Transaction pool for full nodes is non-functional.
+- GrandPa votes gossiping.
 - The changes trie isn't implemented (it is not enabled on Westend, Kusama and Polkadot at the moment).
 - A Prometheus server. While not difficult to implement, it seems a bit overkill to have one at the moment.

bin/full-node/src/network_service.rs

@@ -56,7 +56,7 @@ pub struct Config {
     pub chains: Vec<ChainConfig>,
 
     /// Key used for the encryption layer.
-    /// This is a Noise static key, according to the Noise specifications.
+    /// This is a Noise static key, according to the Noise specification.
     /// Signed using the actual libp2p key.
     pub noise_key: connection::NoiseKey,
 }

bin/wasm-node/javascript/README.md

@@ -13,7 +13,7 @@ the full nodes of the network.
 ```
 import * as smoldot from 'smoldot';
 
-// Load a string chain specifications.
+// Load a string chain specification.
 const chainSpec = Buffer.from(fs.readFileSync('./westend.json')).toString('utf8');
 
 smoldot

bin/wasm-node/rust/src/ffi/bindings.rs

@@ -226,7 +226,7 @@ pub extern "C" fn init(
 ///
 /// A buffer containing a UTF-8 JSON-RPC request must be passed as parameter. The format of the
 /// JSON-RPC requests is described in
-/// [the standard JSON-RPC 2.0 specifications](https://www.jsonrpc.org/specification). A pub-sub
+/// [the standard JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification). A pub-sub
 /// extension is supported.
 ///
 /// The buffer passed as parameter **must** have been allocated with [`alloc`]. It is freed when

bin/wasm-node/rust/src/json_rpc_service.rs

@@ -171,7 +171,7 @@ pub struct Config {
     /// Service that provides a ready-to-be-called runtime for the current best block.
     pub runtime_service: Arc<runtime_service::RuntimeService>,
 
-    /// Specifications of the chain.
+    /// Specification of the chain.
     pub chain_spec: chain_spec::ChainSpec,
 
     /// Hash of the genesis block of the chain.

bin/wasm-node/rust/src/runtime_service.rs

@@ -67,7 +67,7 @@ pub struct Config<'a> {
     /// Service responsible for synchronizing the chain.
     pub sync_service: Arc<sync_service::SyncService>,
 
-    /// Specifications of the chain.
+    /// Specification of the chain.
     pub chain_spec: &'a chain_spec::ChainSpec,
 
     /// Header of the genesis block of the chain, in SCALE encoding.

src/executor.rs

@@ -122,7 +122,7 @@ impl AsRef<[u8]> for CoreVersion {
     }
 }
 
-/// Runtime specifications, once decoded.
+/// Runtime specification, once decoded.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CoreVersionRef<'a> {
     pub spec_name: &'a str,

src/executor/host.rs

@@ -98,7 +98,7 @@
 //! ## Host functions
 //!
 //! The list of host functions available to the runtime is long and isn't documented here. See
-//! the official specifications for details.
+//! the official specification for details.
 //!
 //! # Usage
 //!
@@ -503,7 +503,7 @@ impl ReadyToRun {
                     // Turn the `i64` into a `u64`, not changing any bit.
                     let ret = u64::from_ne_bytes(ret.to_ne_bytes());
 
-                    // According to the runtime environment specifications, the return value is two
+                    // According to the runtime environment specification, the return value is two
                     // consecutive I32s representing the length and size of the SCALE-encoded
                     // return value.
                     let value_size = u32::try_from(ret >> 32).unwrap();

src/executor/vm.rs

@@ -51,7 +51,7 @@
 //!
 //! # About heap pages
 //!
-//! In the WebAssembly specifications, the memory available in the WebAssembly virtual machine has
+//! In the WebAssembly specification, the memory available in the WebAssembly virtual machine has
 //! an initial size and a maximum size. One of the instructions available in WebAssembly code is
 //! [the `memory.grow` instruction](https://webassembly.github.io/spec/core/bikeshed/#-hrefsyntax-instr-memorymathsfmemorygrow),
 //! which allows increasing the size of the memory.

src/libp2p.rs

@@ -147,7 +147,7 @@ pub struct Config<TPeer> {
     pub known_nodes: Vec<(TPeer, PeerId, Multiaddr)>,
 
     /// Key used for the encryption layer.
-    /// This is a Noise static key, according to the Noise specifications.
+    /// This is a Noise static key, according to the Noise specification.
     /// Signed using the actual libp2p key.
     pub noise_key: connection::NoiseKey,
 

src/libp2p/connection/multistream_select.rs

@@ -178,7 +178,7 @@ where
             config: Some(config),
             // Note that the listener theoretically doesn't necessarily have to immediately send
             // a handshake, and could instead wait for a command from the dialer. In practice,
-            // however, the specifications don't mention anything about this, and some libraries
+            // however, the specification doesn't mention anything about this, and some libraries
             // such as js-libp2p wait for the listener to send a handshake before emitting a
             // command.
             state: InProgressState::SendHandshake {

src/libp2p/connection/noise.rs

@@ -79,7 +79,7 @@ pub const PROTOCOL_NAME: &str = "/noise";
 /// libp2p key. The libp2p key is used only to sign the noise public key, while the ECDH is
 /// performed with the noise key.
 ///
-/// From the point of view of the noise protocol specifications, this [`NoiseKey`] corresponds to
+/// From the point of view of the noise protocol specification, this [`NoiseKey`] corresponds to
 /// the static key. The noise key is typically generated at startup and doesn't have to be
 /// persisted on disk, contrary to the libp2p key which is typically persisted after a restart.
 ///
@@ -457,7 +457,7 @@ pub struct HandshakeInProgress {
     /// Libp2p always uses the XX handshake.
     ///
     /// While the `snow` library ensures that the emitted and received messages respect the
-    /// handshake according to the noise specifications, libp2p extends these noise specifications
+    /// handshake according to the noise specification, libp2p extends this noise specification
     /// with a payload that must be transmitted on the second and third messages of the exchange.
     /// This payload must contain a signature of the noise key made using the libp2p key and can
     /// be found in the `tx_payload` field.

src/libp2p/connection/yamux.rs

@@ -23,7 +23,7 @@
 //! and `goaway` frames, belong to a specific substream. In other words, the data transmitted
 //! over the substreams is interleaved.
 //!
-//! Specifications available at https://github.com/hashicorp/yamux/blob/master/spec.md
+//! Specification available at https://github.com/hashicorp/yamux/blob/master/spec.md
 //!
 //! # Usage
 //!

src/libp2p/discovery.rs

@@ -34,7 +34,7 @@
 //! running the same chain. // TODO: not implemented yet
 //!
 //! The main discovery mechanism is the DHT. In order to bootstrap this mechanism, a list of nodes
-//! known to always be part of the chain is hardcoded in the chain specifications. These nodes are
+//! known to always be part of the chain is hardcoded in the chain specification. These nodes are
 //! called **boostrap nodes**.
 //!
 

src/metadata/events.rs

@@ -19,7 +19,7 @@
 //!
 //! # Overview
 //!
-//! While this behaviour is not part of the specifications and is thus not a strict requirement,
+//! While this behaviour is not part of the specification and is thus not a strict requirement,
 //! Substrate-compatible blockchains built using the Substrate framework provide a storage item
 //! (in other words, an entry in the storage, with a specific key) containing a list of so-called
 //! *events*. This storage item is updated at each block with the events that have happened in

src/network/protocol/identify.rs

@@ -28,7 +28,7 @@
 //! [`IdentifyResponse::observed_addr`]. They are necessary in order for nodes to discover their
 //! public address, and in order to insert peers in the Kademlia k-buckets.
 //!
-//! See also [the official specifications](https://github.com/libp2p/specs/tree/69e57d59dc5d59d3979d79842b577ec2c483f7fa/identify).
+//! See also [the official specification](https://github.com/libp2p/specs/tree/69e57d59dc5d59d3979d79842b577ec2c483f7fa/identify).
 
 use super::schema;
 use crate::libp2p::{peer_id::PublicKey, Multiaddr};

src/network/service.rs

@@ -60,7 +60,7 @@ pub struct Config<TPeer> {
     pub known_nodes: Vec<(TPeer, peer_id::PeerId, multiaddr::Multiaddr)>,
 
     /// Key used for the encryption layer.
-    /// This is a Noise static key, according to the Noise specifications.
+    /// This is a Noise static key, according to the Noise specification.
     /// Signed using the actual libp2p key.
     pub noise_key: connection::NoiseKey,
 
@@ -86,8 +86,8 @@ pub struct Config<TPeer> {
 pub struct ChainConfig {
     /// Identifier of the protocol, used on the wire to determine which chain messages refer to.
     ///
-    /// > **Note**: This value is typically found in the specifications of the chain (the
-    /// >           "chain specs").
+    /// > **Note**: This value is typically found in the specification of the chain (the
+    /// >           "chain spec").
     pub protocol_id: String,
 
     /// List of node identities that are known to belong to this overlay network. The node

src/sync/all_forks/pending_blocks.rs

@@ -129,7 +129,7 @@ pub struct Config {
     /// List of block hashes that are known to be bad and shouldn't be downloaded or verified.
     ///
     /// > **Note**: This list is typically filled with a list of blocks found in the chain
-    /// >           specifications. It is part of the "trusted setup" of the node, in other words
+    /// >           specification. It is part of the "trusted setup" of the node, in other words
     /// >           the information that is passed by the user and blindly assumed to be true.
     // TODO: unused
     pub banned_blocks: Vec<[u8; 64]>,