Merge pull request #46 from Convex-Dev/develop

General doc updates

Author: mikera

docs/cad/000_principles/README.md

@@ -1,25 +1,27 @@
 # CAD000: Design Principles
 
-This document details general design and engineering principles deployed in the implementation and documentation of Convex.
+We are building a platform for global decentralised computation and data, based on lattice technology and as a shared public utility network. As such, we are developing a set of open standards based on sound principles and values that will serve the long term vision.
+
+This document details general design and engineering principles deployed in the implementation and documentation of Convex. All CADs should refer to and align with these principles.
 
 ## Technical Principles
 
 ### Values are Immutable
 
-We adopt immutability as a standard principle for all values in Convex. Immutability is important for several reasons:
+We adopt immutability for all values in Convex. Immutability is important for several reasons:
 
 - Enables hash codes to be used for value identity (value IDs) - essential for content-addressable storage
-- Enables structural sharing in persistent data structures
+- Enables structural sharing in persistent data structures, especially when shared on the lattice
 - Easier to reason about immutable values, especially with pure functions
 - Better suited for concurrency
 
-Mutability in implementations is permitted (e.g. a mutable cached value for performance reasons), however such mutability should not be externally visible (e.g. should not affect the Encoding of Values). 
+Mutability may occur as an implementation detail (e.g. a mutable cached value for performance reasons), however such mutability should not be externally visible (e.g. should not affect the encoding of values or CVM behaviour). 
 
-An important presentation on the topic: https://www.infoq.com/presentations/Value-Values/
+A useful presentation on the topic: https://www.infoq.com/presentations/Value-Values/
 
 ### Bounded Resources
 
-We are building a system for distibuted computation and data in the context of a global internet where many parties with access to the Convex network may be untrusted.
+We are building a system for distributed computation and data in the context of a global internet where many parties with access to the Convex network may be untrusted.
 
 It is therefore necessary to place a bound on the size of resources used. This is essential to ensure that the CVM does not ever attempt to process data of unbounded size, which could allow DoS attacks by adversaries constructing arbitrarily sized input.
 
@@ -29,17 +31,17 @@ Where input to Convex may be effectively unbounded (e.g. the size of data struct
 
 ### Security First
 
-Convex is a system intended to support high value economic transactions. As such, security issues should be automatically regarded as the highest priority. We MUST NOT release core software with known severe security defects.
+Convex supports high value economic transactions. As such, security issues should be automatically regarded as the highest priority. We MUST NOT release core software with known severe security defects that might place digital assets at risk.
 
-We SHOULD use existing, proven algorithms and cryptography wherever practically possible: there is no need to reinvent the wheel in crypto.
+We SHOULD use existing, proven algorithms and cryptography wherever practical: there is no need to "reinvent the wheel" in crypto.
 
 ### Favour Simplicity
 
-Especially in API design, there may be a tendency to want to add new features for user convenience, e.g. additional optional arguments for core functions.
+Especially in API design, there is a tendency to want to add new features for user convenience, e.g. additional optional arguments for core functions.
 
 In such cases we SHOULD strongly resist the temptation to add additional complexity, and prefer the simplest possible implementation, especially within core Convex functionality. It is more important that core functionality is clean, simple and maintainable than superficially easy to use. Users have a powerful language with macro capabilities if they wish to implement more convenient programmatic interfaces appropriate for their own use case or design tastes.
 
-An Excellent talk by Rich Hickey on this topic: https://www.infoq.com/presentations/Simple-Made-Easy-QCon-London-2012/
+An excellent talk by Rich Hickey on this topic: https://www.infoq.com/presentations/Simple-Made-Easy-QCon-London-2012/
 
 ### Design for Composition
 
@@ -78,14 +80,13 @@ Such features MAY make sense in P2P off-chain usage, e.g. the Data Lattice. We e
 
 ### Apply Judgement
 
-Principles are rarely absolute. There are always tradeoffs in engineering decisions that must be considered. Discussion is encouraged to ensure relevant aspects are considered from a number of perspectives.
+Principles are rarely absolute. There are always trade-offs in engineering decisions that must be considered. Discussion is encouraged to ensure relevant aspects are considered from a number of perspectives.
 
 ## CAD Style Conventions
 
-
 Literal code (e.g. Convex Lisp forms) should be quoted in a fixed width font `(like this)`
 
-Type names like Vector or the Java type Object should be capitalised.
+Type names like the Convex Vector or the Java type Object should be capitalised. They SHOULD NOT be quoted as code unless they are intended as a code example.
 
 Where possible, follow RFC style MUST, SHOULD, MAY, SHOULD NOT etc. in formal specifications.
 

docs/cad/011_errors/README.md

@@ -221,12 +221,13 @@ Error sources indicate the region in the network where an error occurred. These
 
 | Source Code  | Location of error                            | Example(s)
 | ------------ | --------------------------------             | -----------
-| `:CLIENT`  | Client library code                         | Failed input validation
-| `:COMM`    | Client-Server communications                | IO failure, connection failure or timeout
-| `:PEER`    | Peer handling of user request                | Rejected for bad signature by peer
-| `:NET`     | Consensus network                            | Transaction failed to get into consensus
-| `:CVM`      | CVM state transition handling               | Invalid sequence number, `:JUICE` error
-| `:CODE`    | CVM code execution                          | `:CAST` error in user code
+| `:CLIENT`    | Client library code                          | Failed input validation
+| `:COMM`      | Client-Server communications                 | IO failure, connection failure, timeout
+| `:SERVER`    | Server handling of request                   | Bad request format, server error, server load
+| `:PEER`      | Peer handling of user request                | Rejected for bad signature by peer
+| `:NET`       | Consensus network                            | Transaction failed to get into consensus
+| `:CVM`       | CVM state transition handling                | Invalid sequence number, `:JUICE` error
+| `:CODE`      | CVM code execution                           | `:CAST` error in user code
 
 Error sources are not formally part of the Convex Network / CVM specification, but are important additional information normally returned alongside transaction results. Be aware that a malicious peer could fabricate the error source, so it may be useful to independently validate results. 
 

docs/intro.md

@@ -4,3 +4,6 @@ sidebar_position: 1
 
 # Convex Intro
 
+Convex is an open platform for building decentralised applications that require a high performance, trusted global state without needing to depend on centralised services.
+
+It delivers the promise of the Internet of Value, offering flexibility and scalability far beyond the capabilities of traditional blockchains. In particular, it is supports high volume, interactive applications used directly by end users such as for mobile apps, payments and gaming.

docs/overview/convex-whitepaper.md

@@ -1,7 +1,8 @@
 ---
-title: White Paper
+title: Convex White Paper
 authors: [convex]
 tags: [convex, technology]
+permalink: white-paper
 ---
 # Convex White Paper
 
@@ -314,7 +315,7 @@ Convex eschews the idea of selecting a leader. We maintain the principle that **
 - Blocks can be **independent of all previous Blocks** - they do not necessarily form a "chain" linked by cryptographic hashes.
 - It is possible for multiple Peers to propose Blocks **concurrently** for inclusion in consensus at the same time. This removes a major bottleneck compared to systems that require on some form of sequential leadership e.g. ??????.
 
-An Ordering includes all Blocks up to the current Consensus Point.  A Peer may propose a novel Block for consensus by appending it to the Ordering plus additional Blocks remaining to be confirmed in consensus. 
+An ordering includes all blocks up to the current consensus point. A peer may propose a novel block for consensus by appending it to the ordering (alongside any other additional blocks still to be confirmed in consensus). 
 
 #### Convergent Consensus
 
@@ -337,9 +338,9 @@ The Ordering of one or more other peers could be removed by from the Belief of a
 
 During the convergence process conflicts in proposed block Orderings from different Peers are resolved by a system of convergent stake-weighted voting. [A diagram would be really helpful here] At each belief merge step, peers compute the total share of stake voting for each proposed block in the next position after the current Consensus Point. Peers have a view of the Orderings proposed by all other Peers. 
 
-Stake-weighted voting is applied iteratively to future proposed blocks, but only counting the votes by peers that have supported the winning ordering up to this point. Supporting a minority block causes peers to be temporarily excluded from the considered vote in following blocks. Peers that vote for orderings inconsistent with the majority cannot influence the ordering of any subsequent blocks.
+Stake-weighted voting is applied iteratively to future proposed blocks, but only counting the votes by peers that have supported the winning ordering up to this point. Supporting a minority block causes peers to be temporarily excluded from the vote on following blocks. Peers that vote for orderings inconsistent with the majority cannot influence the ordering of any subsequent blocks. There is therefore an incentive for peers to adopt an ordering consistent with the majority.
 
-Once the overall winning ordering has been determined, any peer can append any new Blocks it wishes to propose, adopting this ordering as its own proposal. This ordering is signed and incorporated into the pPeer's own belief, which is then propagated onwards to other peers.
+Once the overall winning ordering has been determined, any peer can append any new blocks it wishes to propose, adopting this ordering as its own proposal. This ordering is signed and incorporated into the peer's own belief, which is then propagated onwards to other peers.
 
 As an illustration, consider three Peers that are initially in consensus with respect to an ordering of blocks `XXXX` but peers `A` and `B` propose new blocks `Y` and `Z`:
 
@@ -771,7 +772,7 @@ The CVM therefore constrains **time**, **space** and **depth**.
 
 Convex constrains time by placing a "juice cost" on each CVM operation performed. Any transaction executed has a "juice limit" that places a bound on the total amount of computational work that can be performed within the scope of the transaction.
 
-The originating account for a transaction must reserve juice by paying an amount `[juice limit] x [juice price]` at the start of the transaction. Any unused juice at the end of the transaction is refunded at the same rate. The juice price a dynamically varying price that adjusts with amount of execution performed per unit time by the Convex network as a whole: this is a cryptoeconomic mechanism to disincentivise transactions from being submitted at peak periods, and as a protection from DoS attacks by making it prohibitively expensive to flood the compute capacity of the network for a sustained period of time.
+The originating account for a transaction must reserve juice by paying an amount `[juice limit] x [juice price]` at the start of the transaction. Any unused juice at the end of the transaction is refunded at the same rate. The juice price is a dynamically varying price that adjusts with the amount of load on the Convex network as a whole: this is a cryptoeconomic mechanism to disincentivise transactions from being submitted at peak periods, and as a protection from DoS attacks by making it prohibitively expensive to flood the compute capacity of the network for a sustained period of time.
 
 If the juice limit has been exceeded, the CVM terminates transaction execution with an exception, and rolls back any state changes. No juice is refunded in such a situation - this penalises users who attempt excessive resource consumption either carelessly or maliciously.
 
@@ -1053,15 +1054,15 @@ Memory Consumption is computed at the end of each transaction, and is defined as
 
 `Memory Consumption = [CVM State Size at end of Transaction] - [CVM State Size at start of Transaction]` 
 
-If a transaction has zero Memory Consumption, it will complete normally with no effect from the Memory Accounting subsystem
+If a transaction has zero memory consumption, it will complete normally with no effect from the memory accounting subsystem
 
-If a transaction would complete normally, but has a positive Memory Consumption, the following resolutions are attempted, in this order:
+If a transaction would complete normally, but has a positive memory consumption, the following resolutions are attempted, in this order:
 
-1. If the user has sufficient Allowance, the additional memory requirement will be deducted from the allowance, and the transaction will complete normally
+1. If the user has sufficient allowance, the additional memory requirement will be deducted from the allowance, and the transaction will complete normally
 2. If the transaction execution context has remaining juice, and attempt will be made to automatically purchase sufficient memory from the Memory Exchange. The maximum amount paid will be the current juice price multiplied by the remaining juice for the transaction. If this succeeds, the transaction will complete successfully with the additional memory purchase included in the total juice cost.
 3. The transaction will fail with a MEMORY Error, and any state changes will be rolled back. The User will still be charged the juice cost of the transaction
 
-If a transaction has negative Memory Consumption, the memory allowance of the user will be increased by the absolute size of this value. In effect, this is a refund granted for releasing storage requirements.
+If a transaction has negative memory consumption, the memory allowance of the user will be increased by the absolute size of this value. In effect, this is a refund granted for releasing storage requirements.
 
 
 #### Allowance transfers
@@ -1076,7 +1077,7 @@ It is permissible to make an allowance transfer directly between accounts. This
 
 #### Actor Considerations
 
-All Accounts, including actors, have a memory allowance. However, in most cases actors have no use for a memory allowance: any memory consumed during interaction with an actor will be accounted for via the user account account that originated the transaction.
+All Accounts, including actors, have a memory allowance. However, in most cases actors have no need for a memory allowance: any memory consumed during interaction with an actor will be accounted for via the user account account that originated the transaction.
 
 One exception to this is with scheduled execution, where an actor itself may be the origin for a transaction.
 

docs/overview/faq.md

@@ -6,20 +6,18 @@ tags: [convex]
 
 Some answers to common questions can be found here.
 
-
 ## Is Convex Free?
 
-Yes! Convex is free for anyone to use and build applications upon, and always will be. We are building Convex for everyone to support the Internet of Value.
+Yes! Convex is free for anyone to use, and always will be. We are building Convex as an open public utility network for everyone to support the Internet of Value.
 
-To make use of the resources of the network, small transaction fees are charged using Convex Coins, which is the native utility token of the network. This is important for several reasons:
+When transacting on the network, small fees are charged using Convex Coins, which is the native utility token of the network. This is necessary for several reasons:
 
-- Compensate those who provide important secure infrastructure to the network (i.e. peer operators)
+- Compensate fairly those who provide important secure infrastructure to the network (i.e. peer operators)
 - Prevent denial of service attacks by people flooding the network with wasteful transactions. This makes it very expensive to launch such attacks.
 - Create an economic incentive to use the network as efficiently as possible (both for users and developers of smart contracts)
 
 Our goal is to keep transaction fees small, so that it is never a significant issue for legitimate network users.
 
-
 ## How fast is Convex?
 
 Convex can comfortably process many thousands of complex transactions per second (e.g. transfers and smart contract calls). The CVM itself has been benchmarked at over 1,000,000 TPS on a modern desktop PC. And as we continue making performance improvements it is getting faster by the day.

docs/overview/manifesto.md

@@ -228,7 +228,7 @@ Initially, the governance role will be performed by the Convex Foundation, a non
 In the longer term, we will implement decentralised governance. This will happen once we have sufficient confidence that it is practical to implement, secure against plausible threats and fully serves the interest of Convex users and society as a whole.
 
 Key governance roles include:
-- Authorising official updates to the peer network / protocol
+- Authorising official updates to the peer network or protocol
 - Preventing forks in the global state: the entire point of a global state is to act as a single source of truth. As a public utility that records important economic information on a decentralised basis, the network must avoid forks  since these present a significant risk of confusion and loss to participants in the ecosystem. Forks are not desirable in a system designed to act as a single source of truth for asset ownership, contract state and account balances etc. 
 - Ensuring that issuance of Convex Coins is fair, secure and consistent with out principles of rewarding ecosystem contribution
 

docs/overview/performance.md

@@ -9,6 +9,9 @@ We care primarily about two different measurements of performance:
 
 Convex performance is based around a key idea: We implement consensus using a **CRDT** (conflict-free replicated data type) where the Peers achieve consensus by simply sharing a Belief data structure which is repeatedly merged with other Beliefs to form consensus. CRDTs are guaranteed to eventually converge to a consistent value under reasonable assumptions, which gives the desired properties of safety and liveness to the network. Peers, therefore, have a simple primary task: merge and propagate new beliefs to the network as quickly as possible.
 
+Here are some performance figured validated in the EU's Next Generation Internet (NGI) OntoChain Project. 
+![CompareETH2](https://github.com/user-attachments/assets/0ed23d0b-85dc-4aa6-91f7-8fc6903bcf40)
+
 
 ## Latency
 

docs/products/convex-desktop/index.md

@@ -1,3 +1,10 @@
+---
+title: Convex Desktop
+authors: [convex]
+tags: [convex]
+sidebar_position: 0
+---
+
 # Convex Desktop
 
 Convex Desktop is a GUI tool for interacting with Convex. Designed for developers and power users, it puts all the capabilities of Convex at your fingertips.