Merge pull request #43 from Convex-Dev/develop

Various WIP doc updates

Author: mikera

docs/overview/concepts.md

@@ -4,17 +4,54 @@ authors: [convex]
 tags: [convex]
 ---
 
-## Overview
+# Overview
 
-Convex is a decentralised platform for the Internet of Value, offering flexibility and scalability far beyond the capabilities of traditional blockchains. In particular, it is designed to support high volume, interactive applications used directly by end users such as for mobile apps, payments and gaming.
+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.
+
+## Lattice Technology
+
+Convex is based on **lattice technology**. A lattice is a concept from mathematics: a set where every element can be merged with any other element with a "merge" function that is commutative, idempotent and associative.
+
+A consequence of this is that distributed systems can share their lattice values and the lattice is guaranteed to converge to a single consensus value - this is the key idea behind a CRDT (conflict-free replicated data type). CRDTs are well known as a powerful way to build scalable, fault-tolerant distributed systems (e.g Redis).
+
+Lattice technology builds on the idea of CRDTs in several key ways:
+- Adding cryptographic security to enable secure decentralised operation (digital signatures and cryptographic hashes)
+- Ability to create consensus over an ordering of transactions (essential for transaction security, e.g. the double-spend problem) 
+- Use of powerful immutable persistent data structures as the lattice values. These can be of arbitrary size and contain arbitrary data, but only the differences need to be transmitted and processed - similar to the "git" version control system. 
+- Lattice data structures are also Merkle trees, proving strong integrity guarantees and fast identity checking.
+
+By combining the principles of CRDTs with cryptographic security, transactional ordering and immutable data structures, Convex offers a unique solution for building decentralised systems that can reliably converge to consensus, even in the face of network failures or malicious attacks.
+
+## Convergent Proof of Stake (CPoS)
+
+The consensus algorithm used by Convex to secure on-chain transactions is **Convergent Proof of Stake**, which is described in more detail in the [Convex White Paper](convex-whitepaper.md)
+
+The main properties of CPoS are:
+- Byzantine Fault Tolerance (similar to PBFT)
+- Stake weighted voting by peers (67% required to ensure stable consensus)
+- Leaderless design - peers can submit transaction in parallel
+- Resistance to front-running
+
+In general, users and developers don't need to care about CPoS happening: it is handled by peers participating in the consensus lattice. They just get to enjoy lightning fast, secure transactions.
+
+
+## Comparison with Blockchains
+
+Convex is not a blockchain: Its unique lattice technology maintains consensus via a CRDT, rather tying a block to the previous block. This allows significantly better realtime performance as it is a leaderless system with zero block delay.
+
+However, comparisons are inevitable so it is worth noting that Convex can still do everything possible on a blockchain and more:
+- Create and execute smart contracts (via the CVM)
+- Enforce cryptographic security for digital assets and on-chain data
+- Provide decentralised services such as identity, trust and immutable provenance 
+
+Architecturally, Convex is exceptionally simple and developer-friendly: 
+- A single global consensus state avoids the problems and risks of cross-chain / cross-shard transactions - you get the benefits of high scalability without architectural complexity and operational risks
+- An on-chain compiler makes it simple to submit and execute sophisticated transactions without external tools
+- Transactions are atomic and Turing complete, so you can implement arbitrary logic with the safety of complete automatic rollbacks if anything fails
+- Clients need only a standard Ed25519 key pair to transact (via the REST API or the binary protocol)
 
 
-## Governance
 
-Convex is governed by the non-profit Convex Foundation. The Foundation performs the following activities:
 
-- Ensures good governance of the Convex Network
-- Operates key resources on behalf of the community, including the https://convex.world website and developer resources such as GitHub repositories
-- Acts as this initial issuer of Convex Coins to individuals and organisations, including management of the release curve
-- Provides awards for contributors to Convex (e.g. open source developers)
-- Supports the development of the Convex ecosystem via partnerships, marketing, education and other initiatives

docs/overview/governance.md

@@ -0,0 +1,10 @@
+
+# Governance
+
+Convex is governed by the non-profit Convex Foundation. The Foundation performs the following activities:
+
+- Ensures good governance of the Convex Network
+- Operates key resources on behalf of the community, including the https://convex.world website and developer resources such as GitHub repositories
+- Acts as this initial issuer of Convex Coins to individuals and organisations, including management of the release curve
+- Provides awards for contributors to Convex (e.g. open source developers)
+- Supports the development of the Convex ecosystem via partnerships, marketing, education and other initiatives

docs/products/convex-desktop/convex-desktop.png

@@ -1,13 +1,12 @@
 # Convex Desktop
 
-The Convex CLI (Command Line Interface) is a powerful tool for interacting with Convex from the command line on Windows, Linux and MacOS. It's a handy tool for system administrators and peer operators who need to script interactions with the Convex Network.
+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.
 
-```
 ![Convex Desktop Screenshot](convex-desktop.png)
-```
+
 ## Installation
 
-The Convex Desktop requires:
+Convex Desktop requires:
 - A recent version of Java (21+, Java 22 recommended)
 - A GUI based operating system (e.g. Windows, Linux or MacOS)
 - A copy of the `convex.jar` executable jar file

docs/products/convex-desktop/index.md

@@ -0,0 +1,45 @@
+# Peer Container
+
+Convex is packaged in the Peer Container for easy deployment via Docker-based systems
+
+![Docker Peer Container](peer-container.png)
+
+## Installation
+
+To run the peer container locally, you will need to install [Docker](https://www.docker.com/). You can use either the Docker CLI or Docker Desktop.
+
+The Peer Container is packaged as a docker container available on DockerHub
+
+- [Peer Container on DockerHub](https://hub.docker.com/repository/docker/convexlive/convex)
+
+The latest version is general available in docker as `convexlive/convex:latest`
+
+## Running a Peer Container
+
+Running the Peer Container is a one-liner:
+
+```bash
+docker run --name my-peer -d convexlive/convex:latest -p 8080:8080 -p 18888:18888
+```
+
+This will run a default test peer, with ports mapped as follows:
+- `8080` mapped for REST API access
+- `18888` for the Convex peer protocol (other peers and binary clients)
+
+However, to operate a peer effectively some configuration is usually required.
+
+### SSL Certificates
+
+If you want your peer to use HTTPS (highly recommended) you probably want to provide SSL certificates.
+
+### Peer Keys
+
+Each peer require a "peer key", which is an Ed25119 key pair. The public key is used to identify the peer on the network, and the private key is used by the peer to sign its interactions with the lattice / CPoS consensus.
+
+### Controller keys
+
+We recommend that you DO NOT add peer controller keys to a Convex peer container. Reasons for this:
+- Peer controller keys have control over significant economic assets, in particular the peer's stake on the Convex Network
+- If the system running the docker container is compromised, the controller key may be stolen
+
+Instead, is is best to operate the Peer Container with a peer key alone, and use a separate mechanism (e.g. a hardware wallet or air-gapped laptop) for signing transactions that require the controller key.

docs/products/convex-peer/index.md

@@ -70,7 +70,7 @@ Technically, Convex is not a blockchain because Blocks are not required to conta
 
 ## Consensus Algorithm
 
-The Convex Consensus Algorithm is obtains consensus through the use of a convergent Belief Merge Function. This algorithm is called Convergent Proof of Stake (CPoS), and is described in more detail in the [White Paper](convex-whitepaper.md).
+The Convex Consensus Algorithm is obtains consensus through the use of a convergent Belief Merge Function. This algorithm is called Convergent Proof of Stake (CPoS), and is described in more detail in the [White Paper](../overview/convex-whitepaper.md).
 
 ## Consensus Point
 

docs/products/convex-peer/peer-container.png

@@ -10,31 +10,29 @@ type FeatureItem = {
 
 const FeatureList: FeatureItem[] = [
   {
-    title: 'Easy to Use',
+    title: 'Lattice Technology',
     Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
     description: (
       <>
-        Convex is the easiest way to create decentralised applications.
+        The Lattice is the innovation at the heart of Convex - decentralised, infinitely scalable, cryptographically secure. 
       </>
     ),
   },
   {
-    title: 'Focus on What Matters',
+    title: 'Developer Power',
     Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
     description: (
       <>
-        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
-        ahead and move your docs into the <code>docs</code> directory.
+        Convex gives developers superpowers: fully interactive REPL development and the power of "One Line DeFi"
       </>
     ),
   },
   {
-    title: 'Powered by React',
+    title: 'Blazing Performance',
     Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
     description: (
       <>
-        Extend or customize your website layout by reusing React. Docusaurus can
-        be extended while reusing the same header and footer.
+        With zero block delay and near-instant transaction confirmation, you can build the perfect experience for your users. 
       </>
     ),
   },