Merge pull request #42 from Convex-Dev/develop

Update

Author: mikera

docs/cad/029_fungible/README.md

@@ -11,13 +11,13 @@ Typical use cases for fungible tokens might include:
 - Quantities of some resource in a game or metaverse
 - Reputation points
 
-Note: This CAD represents the Convex replacement for ERC20 / ERC777 on Ethereum
+This CAD represents the Convex replacement for ERC20 / ERC777 on Ethereum
 
 ## Specification
 
 ### CAD19 Compliance
 
-A fungible token MUST meet all the specifications for a compatible CAD19 asset, in addition to the requirements specified here.
+A fungible token MUST meet all the specifications for a compatible CAD19 asset, as well as the mandatory requirements specified in this CAD.
 
 ### Balances
 

docs/overview/concepts.md

@@ -15,6 +15,6 @@ Convex is governed by the non-profit Convex Foundation. The Foundation performs
 
 - 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, inlciding management of the release curve
+- 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/convex-whitepaper.md

@@ -505,7 +505,7 @@ In this simple case, the new Consensus is confirmed within just three rounds of
 
 In more complex cases:
 
-* Multiple Peers may propose Blocks at the same time. In this case, stake-weighted voting would be used to resolve conflicts and determine which Blocks are included first. It may take an additional round or two to resolve such conflicts into a stable Ordering. Overall, this is more efficient since multiple Blocks are being brought into Consensus in a similar toatl number of rounds.
+* Multiple Peers may propose Blocks at the same time. In this case, stake-weighted voting would be used to resolve conflicts and determine which Blocks are included first. It may take an additional round or two to resolve such conflicts into a stable Ordering. Overall, this is more efficient since multiple Blocks are being brought into Consensus in a similar total number of rounds.
 * The network might not reach a quiescent state before further new Blocks are added. This is not an issue: consensus will be confirmed for the initial Block(s) while the new Blocks are still being propagated at earlier stages.
 * Some Peers might misbehave or be temporarily unavailable. Again, this is not a problem as long as a sufficient number of Good Peers are still operating and connected, since the consensus thresholds can still be met. Temporarily disconnected or offline Peers can "catch up" later.
 * The Peer Network may not be fully connected, potentially adding `O(log(number of peers))` additional rounds of propagation assuming that each Peer propagates to a small constant number of other Peers in each time period. In practice, not all these additional rounds may be needed because a smaller number of highly staked and well-connected Peers will be able to confirm consensus without waiting for the rest of the Network.
@@ -1007,7 +1007,7 @@ To solve the state growth problem, Convex implements **Memory Accounting** with
 
 **Note 1**: that in practice, the actual storage size of the CVM state will be significantly smaller than the tracked state size, because the use of immutable persistent data structures allows many equal tree branches to be shared. The effectiveness of this structural sharing needs to be observed over time, but we anticipate perhaps a 2-3x reduction in state size may be possible in the long term.
 
-**Note 2**: Observant system hackers may notice that the memory accounting mechanism means that if Account A causes some memory to be allocated, and Account B causes that same memory to be de-allocated (e.g., through the use of calls to an Actor), then Account B will gain memory from A. We consider this a feature, not a bug: It incentivises participants to clean up state wherever possible and incentivises the writers of Actor code to consider their memory allocations and deallocations carefully.
+**Note 2**: Observant system hackers may notice that the memory accounting mechanism means that if Account A causes some memory to be allocated, and Account B causes that same memory to be de-allocated (e.g., through the use of calls to an Actor), then Account B will gain memory from A. We consider this a feature, not a bug: It incentivises participants to clean up state wherever possible and encourages the writers of actor code to consider their memory allocations and deallocations carefully.
 
 To ensure correct economic behaviour, it is necessary for free memory to have an economic cost. Therefore, Convex provides a **Memory Exchange** though which memory allocations may be traded. This has the following features:
 

docs/overview/faq.md

@@ -11,7 +11,7 @@ Some answers to common questions can be found here.
 
 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.
 
-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 serveral reasons:
+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:
 
 - Compensate 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.
@@ -64,7 +64,7 @@ It is a good idea to **keep data structures as simple as possible**. Ideally, Ac
 
 ## Is Convex a Blockchain?
 
-Think of Convex and the undelying lattice technology as "beyond blockchain".
+Think of Convex and the underlying lattice technology as "beyond blockchain".
 
 Convex shares many common attributes with traditional public blockchains:
 
@@ -98,6 +98,8 @@ A variant of Lisp was chosen as the initial language for the CVM for a few reaso
 
 Paul Graham's essay [Beating the Averages](http://www.paulgraham.com/avg.html) is an interesting perspective on the advantages of Lisp for building a business. Despite dating from 2001, we feel many of these points still stand today and are very relevant for people wanting to build applications using Convex.
 
+For more information see the tutorial section for [Convex Lisp](/docs/tutorial/convex-lisp/convex-lisp)
+
 
 ## What is Memory Accounting?
 

docs/overview/performance.md

@@ -113,11 +113,11 @@ The CVM is a highly optimised execution engine. Some notable points:
 - CVM code is compiled down to efficient "Ops", where a typical transaction might require 10-50 Ops to be executed. This is effectively the "machine code" of the JVM, and corresponds to operations typical in an implementation of the Lambda Calculus - because of the power of the lambda calculus, we usually require fewer Ops than the equivalent for a stack-based machine
 - We can rely on the JVM JIT to further compile key code paths down to efficient native code
 
-The `OpBenckmark` is a microbenchmark of several different groups of Ops, and demonstrates that up to hundreds of millions of Ops can be executed per second on a single thread:
+The `OpBenchmark` is a microbenchmark of several different groups of Ops, and demonstrates that up to hundreds of millions of Ops can be executed per second on a single thread:
 
 ```
 Benchmark                          Mode  Cnt          Score           Error  Units
-OpBenchmark.constant              thrpt    5  522926192.803 ± 200159991.331  ops/s     (a single Contsant op)
+OpBenchmark.constant              thrpt    5  522926192.803 ± 200159991.331  ops/s     (a single Constant op)
 OpBenchmark.emptyLoop             thrpt    5       2180.943 ±       118.609  ops/s     (a loop executing 1000 times)
 OpBenchmark.simpleSum             thrpt    5    8336440.019 ±    444054.388  ops/s     (a sum involving dynamic lookup, 4 Ops)
 OpBenchmark.simpleSumPrecompiled  thrpt    5   21846062.388 ±   1823368.198  ops/s     (a sum with constants, 4 Ops)

docs/overview/use-cases.md

@@ -6,6 +6,16 @@ tags: [convex, ecosystem, applications]
 
 Convex is a general purpose, programmable decentralised network with global state. As such, there is no inherent limit on the nature of applications that can be built. Here are some of the things that Convex can be used for, and are being actively developed within the Convex community:
 
+## Tokensiation
+
+Convex offers a uniquely powerful system for the development of tokenised assets and applications. Tokens in Convex usually support the [CAD029](cad/029_fungible/README.md) token standard, which offers multiple advantages over the common ERC20 standard.
+
+Tokens can be used for:
+- Payments in the form of stablecoins, flatcoins, nationcoins or other digital currency types
+- Utility tokens for delivery of decentralised services
+- Reward schemes and bonus programmes
+- Governance of decentralised economic systems, e.g. with stake-weighted voting
+
 ## NFTs
 
 Non-fungible tokens (NFTs) are a powerful mechanism for creating unique virtual items that can be owned, collected traded and utilised in virtual environments such as games. Each NFT has a unique on-chain ID and can be individually addressed, transferred and used within smart contracts.

docs/products/convex-cli/convex-cli.png

@@ -0,0 +1,51 @@
+# Convex CLI
+
+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 CLI Screenshot](convex-cli.png)
+
+## Installation
+
+The Convex CLI requires:
+- A recent version of Java (21+, Java 22 recommended)
+- A copy of the `convex.jar` executable jar file
+
+Java is available from multiple providers, we recommend:
+- [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)
+- [Eclipse Temurin JDK](https://adoptium.net/temurin/releases/) 
+
+Snapshots of the `convex.jar` file are currently available here: [Convex Snapshots](https://drive.google.com/drive/folders/1AZdyuZOmC70i_TtuEW3uEKvjYLOqIMiv?usp=sharing)
+
+## Running the CLI
+
+To run the CLI, you simply need to run the following:
+
+```
+java -jar convex.jar <arguments>
+```
+
+It is usually more convenient to have a script, alias or batch file which executes the Java command. This means that you can simply type `convex ....` from any directory to access the CLI. The remainder of this document assumes you are using such a script.
+
+### Windows
+
+For Windows PowerShell, the following should work:
+
+```
+# Windows powershell - convex.ps1
+function convex { 
+  java -jar C:\path\to\convex.jar $args
+}
+```
+
+Put this in your PowerShell profile (typically `Profile.ps1` in `$home/documents/PowerShell`) and the `convex` command should be available in all future PowerShell sessions.
+
+### Linux
+
+Make a small shell script (with `chmod +x`) as follows:
+
+```
+#!/bin/bash
+java -jar /path/to/convex.jar $@
+```
+
+Put this in `/usr/local/bin` and you should be good to go.

docs/products/convex-cli/index.md

@@ -0,0 +1,29 @@
+# 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 Screenshot](convex-desktop.png)
+```
+## Installation
+
+The 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
+
+Java is available from multiple providers, we recommend:
+- [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)
+- [Eclipse Temurin JDK](https://adoptium.net/temurin/releases/) 
+
+Snapshots of the `convex.jar` file are currently available here: [Convex Snapshots](https://drive.google.com/drive/folders/1AZdyuZOmC70i_TtuEW3uEKvjYLOqIMiv?usp=sharing)
+
+## Running Convex Desktop
+
+If Java is correctly configured, you should be able to run Convex Desktop simply by double-clicking on the `convex.jar` file which will run Convex Desktop as an executable. On some systems, you may need to grant permissions to run a downloaded executable file.
+
+Alternatively to run Convex Desktop, you can run the following commend from the command prompt, script or GUI shortcut:
+
+```
+java -jar convex.jar desktop
+```

docs/products/convex-desktop/index.md

@@ -14,11 +14,16 @@ The CVM is designed to be able to support many different languages and paradigms
 - **Immutability**: Lisp's functional programming paradigm promotes immutability, which is essential for ensuring the integrity and consistency of decentralised systems where data must be replicated and distributed across multiple nodes.
 - **Dynamic typing**: Lisp's dynamic typing allows for flexible data structures and easy modifications, crucial for adapting to the constantly evolving nature of decentralised systems. At the same time, Convex Lisp is **strongly typed**, avoiding the issues associated with weak typing.
 - **Code is data**: representing code using its own data structures (also known as "homoiconicity") gives Lisp advanced **metaprogramming** capabilities the creation of domain-specific languages (DSLs) tailored to specific concepts, making it easier to reason about and implement complex economic mechanisms.
-- **Interactive coding**: Lisp pineered the use of the REPL for highly interactive programming. With Convex, we've taken this a step further with a complete on-chain compiler so that everything on the CVM can be done with simple interactive Lisp commands.
+- **Interactive coding**: Lisp pioneered the use of the REPL for highly interactive programming. With Convex, we've taken this a step further with a complete on-chain compiler so that everything on the CVM can be done with simple interactive Lisp commands.
 
-Convex Lisp was heavily inspired by [Clojure](https://clojure.org/), from which it borrows most basic and many core functions, and [Racket Scheme](https://racket-lang.org/) which inspired many of the more advanced metaprograming facilities.
+## Inspirations
+
+Lisp was originally created in the 1950s by John McCarthy and has maintained a deep-rooted appeal among hackers for its unique characteristics.
+
+Convex Lisp was heavily inspired by [Clojure](https://clojure.org/), from which it borrows most basic and many core functions, and [Racket Scheme](https://racket-lang.org/) which inspired many of the more advanced metaprogramming facilities.
 
 ## Interesting technical notes
 
 - Convex Lisp is a **Lisp-1** (i.e. keeps function and data values in the same namespace).This is simpler than a Lisp-2 and seems more appropriate for a functional programming language, where functions are regularly treated as first class values.
-- Convex Lisp is designed for **orthogonal persistence**. Developers don't need to care where data or code is stored: it is loaded and cached on demand. This powerful capability means that the CVM can operate code and data data structures much larger than system RAM without imposing any burden on developers.
+- Convex Lisp is designed for **orthogonal persistence**. Developers don't need to care where data or code is stored: it is loaded and cached on demand. This powerful capability means that the CVM can operate code and data data structures much larger than system RAM without imposing any burden on developers.
+- Convex Lisp data structures (and therefore code) are all represented as **Merkle trees** using strong cryptographic hashes. This has the interesting property of making all code and data **content-addressable** and cryptographically **verifiable**. As well as making Convex Lisp ideally suited for running on the lattice technology used by Convex, this opens interesting possibility for new kinds of systems based on immutable and verifiable distributed code bases.