README tidying

mikera · mikera · commit 9dde0637d51d · 2026-01-23T19:15:11.000Z
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -46,12 +46,15 @@ Examples:
 ### Test Structure
 Tests follow JUnit 6 conventions with `src/test/java` mirroring `src/main/java` structure.
 
+### Language
+Concise language, British English spelling
+
 ## Key Technologies
 
 - **Netty** - Async networking
 - **JUnit 6** - Testing
 - **SLF4J** - Logging
-- **Ed25519** - Cryptographic signatures
+- **Ed25519** - Cryptographic signatures (Bouncy Castle Library)
 - **ANTLR4** - Parser generation (requires IDE source path configuration)
 
 ## Running Convex
@@ -63,7 +66,7 @@ Execution is typically using CLI commands on convex.jar uberjar (all dependencie
 java -jar convex.jar desktop   # Launch GUI
 ```
 
-Typically should set up small convenience wrapper script to run `java -jar ...` and allow comamnds like:
+Typically should set up small convenience wrapper script to run `java -jar ...` and allow commands like:
 ```bash
 convex key generate
 ```
@@ -82,10 +85,6 @@ See BUILD.md for complete release workflow.
 - ANTLR4 generated sources may need manual IDE source path configuration
 - Add `target/generated-sources/antlr4` as source directory if needed
 
-## Contributing
-
-See README.md for contribution guidelines and license terms.
-
 ## Key Principles
 
 - **Immutable Data** - Use immutable lattice data structures (ACell hierarchy)
diff --git a/convex-benchmarks/README.md b/convex-benchmarks/README.md
@@ -1,47 +1,68 @@
 # Convex Benchmarks
 
-## Benchmarking
+[![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-benchmarks.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex)
 
-Convex includes a wide set of benchmarks, which are used to evaluate performance enhancements. These are mostly implemented with the JMH framework, and reside in the `convex.benchmarks` package.
+Performance benchmarking suite for [Convex](https://convex.world) using the JMH (Java Microbenchmark Harness) framework.
 
-## Preparing to run benchmarks
+## Available Benchmarks
 
-To run benchmarks, it is best to build the full `convex-benchmarks` jar with dependencies which includes all benchmarks, tests and dependencies. This can be done with the following commend:
+| Benchmark | Description |
+|-----------|-------------|
+| `CVMBenchmark` | Convex Virtual Machine execution performance |
+| `EtchBenchmark` | Etch database read/write throughput |
+| `HashBenchmark` | Cryptographic hashing operations |
+| `SignatureBenchmark` | Ed25519 signature generation and verification |
+| `DataStructureBenchmark` | Immutable data structure operations |
 
-`mvn clean install`
+## Running Benchmarks
 
-## Directly running benchmarks
+### Build
 
-After building the testing `.jar`, you can launch benchmarks as main classes in the `convex.benchmarks` package, e.g.
-
-```
-java -cp target/convex-benchmarks-jar-with-dependencies.jar convex.benchmarks.EtchBenchmark
+```bash
+cd convex
+mvn clean install -pl convex-benchmarks -am
 ```
 
-## Running with Java Flight Recorder
+### Execute
 
-If you want to analyse profiling results for the benchmarks, you can run using JFR to produce a profiling output file `flight.jfr`
+Run a specific benchmark:
 
+```bash
+java -cp convex-benchmarks/target/convex-benchmarks-jar-with-dependencies.jar \
+  convex.benchmarks.EtchBenchmark
 ```
-java -cp target/convex-benchmarks-jar-with-dependencies.jar -XX:+FlightRecorder -XX:StartFlightRecording=duration=200s,filename=flight.jfr convex.benchmarks.CVMBenchmark
-```
 
-The resulting `flight.jfr` can the be opened in tools such as JDK Mission Control which enables detailed analysis and visualisation of profiling results. This is a useful approach that the Convex team use to identify performance bottlenecks.
+### With Profiling (Java Flight Recorder)
+
+Generate profiling data for analysis:
 
-## Benchmark results
+```bash
+java -cp convex-benchmarks/target/convex-benchmarks-jar-with-dependencies.jar \
+  -XX:+FlightRecorder \
+  -XX:StartFlightRecording=duration=200s,filename=flight.jfr \
+  convex.benchmarks.CVMBenchmark
+```
+
+Open `flight.jfr` in JDK Mission Control for detailed analysis.
 
-After running benchmarks, you should see results similar to this:
+## Example Results
 
 ```
 Benchmark                      Mode  Cnt        Score        Error  Units
 EtchBenchmark.readDataRandom  thrpt    5  4848620.857 ± 110622.054  ops/s
 EtchBenchmark.writeData       thrpt    5   728486.145 ± 168739.491  ops/s
 ```
 
-For example, this can be interpreted as an indication that the Etch database layer is handling approximately 4.8 million reads and 729k million atomic writes per second in the testing environment. Usual benchmarking caveats apply and results may vary considerably based on your system setup (available RAM, disk performance etc.) - it is advisable to examine the benchmark source to determine precisely which operations are being performed.
+This indicates ~4.8 million reads/sec and ~728k writes/sec for the Etch database layer. Results vary based on hardware (RAM, disk speed, CPU).
+
+## Documentation
+
+- [Convex Documentation](https://docs.convex.world)
+- [JMH Documentation](https://openjdk.org/projects/code-tools/jmh/)
+- [JDK Mission Control](https://www.oracle.com/java/technologies/jdk-mission-control.html)
 
-## Copyright
+## License
 
-Code in `convex-benchmarks` provided under the Convex Public License
+Copyright 2020-2025 The Convex Foundation and Contributors
 
-Copyright 2020-2023 Convex Foundation and Contributors
+Code in convex-benchmarks is provided under the [Convex Public License](../LICENSE.md).
diff --git a/convex-cli/README.md b/convex-cli/README.md
@@ -1,6 +1,8 @@
 # Convex CLI
 
-Command-line interface for the Convex decentralized network. Query state, execute transactions, manage keys, run local test networks, and operate production peers.
+[![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-cli.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex)
+
+Command-line interface for the [Convex](https://convex.world) decentralised network. Query state, execute transactions, manage keys, run local test networks, and operate production peers.
 
 ## Quick Start
 
diff --git a/convex-core/README.md b/convex-core/README.md
@@ -1,30 +1,75 @@
 # Convex Core
 
+[![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-core.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex)
 [![javadoc](https://javadoc.io/badge2/world.convex/convex-core/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-core)
 
-## Overview
+The foundational library for the [Convex](https://convex.world) decentralized network, providing the virtual machine, consensus algorithm, and core data structures.
 
-Convex Core is the fundamental code base for Convex
+## Features
 
-It includes:
- - Implementations of all Convex decentralised data structures
- - Implementation of the Convex Virtual Machine (CVM)
- - Convergent Proof of Stake consensus algorithm
- - The Etch database and storage system
- - Common utility functions (including cryptography support)
+- **Convex Virtual Machine (CVM)** - Lambda calculus-based execution environment for smart contracts
+- **Convergent Proof of Stake (CPoS)** - Energy-efficient consensus algorithm
+- **Immutable Data Structures** - Lattice-based structures optimized for decentralized systems
+- **Etch Database** - High-performance persistent storage layer
+- **Cryptography** - Ed25519 signatures and secure hashing utilities
 
-Convex Core is designed as a library to support applications in the Convex ecosystem. It can be used directly and embedded in JVM applications that wish to work with Convex data structures directly.
+## Installation
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>world.convex</groupId>
+    <artifactId>convex-core</artifactId>
+    <version>0.8.2</version>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+implementation 'world.convex:convex-core:0.8.2'
+```
+
+## Usage
+
+Use `convex-core` directly when you need to work with Convex data structures locally without network connectivity:
+
+```java
+import convex.core.data.*;
+import convex.core.lang.*;
+
+// Work with immutable data structures
+AVector<CVMLong> vec = Vectors.of(1L, 2L, 3L);
+AMap<Keyword, ACell> map = Maps.of(Keyword.create("name"), Strings.create("Alice"));
+
+// Execute CVM code locally
+Context ctx = Context.create(state, address);
+ctx = ctx.eval(Reader.read("(+ 1 2 3)"));
+ACell result = ctx.getResult();  // Returns 6
+```
 
 ## Documentation
 
-- JavaDocs (available in this repository or [from javado.io](https://javadoc.io/doc/world.convex/convex-core))
+- [Javadoc API Reference](https://javadoc.io/doc/world.convex/convex-core)
 - [Java Examples](https://github.com/Convex-Dev/convex/tree/develop/convex-core/src/test/java/examples)
 - [Convex Lisp Examples](https://github.com/Convex-Dev/convex/tree/develop/convex-core/src/test/resources/examples)
+- [Convex Documentation](https://docs.convex.world)
+
+## Building from Source
+
+```bash
+git clone https://github.com/Convex-Dev/convex.git
+cd convex
+mvn install -pl convex-core -am
+```
+
+**Note:** ANTLR4 generates parser code during the build. If your IDE shows errors, add `target/generated-sources/antlr4` as a source directory.
 
-## License and Contributing
+## License
 
-Convex Core is distributed under the Convex Public License
+Copyright 2018-2025 The Convex Foundation and Contributors
 
-Contributors are encouraged to sign the Convex Contribtor's Agreement, which may make contributors eligible for awards of Convex Coins.
+Code in convex-core is provided under the [Convex Public License](../LICENSE.md).
 
-Copyright 2018-2024 Convex Foundation and Contributors
+Contributors are encouraged to sign the Convex Contributor's Agreement, which may make contributors eligible for awards of Convex Coins.
diff --git a/convex-gui/README.md b/convex-gui/README.md
@@ -1,58 +1,57 @@
-# Convex Desktop GUI
+# Convex Desktop
 
-Convex Desktop is a full featured desktop application for working with Convex. It is intended for developers who wish to build solutions on Convex as well as power users who wish to work directly with assets and smart contracts on the Convex Network.
+[![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-gui.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex)
 
-Key features:
-- Execute transactions on Convex networks
-- Secure key generation and wallet management
-- Run a local network of Convex Peers
-- Visualisation of CPoS consensus and network messaging
-- Simulations and stress test code
+A full-featured desktop application for developers and power users working with the [Convex](https://convex.world) decentralized network.
 
 ![Screenshot](docs/images/convex-desktop.png)
 
-```
-Unleash the power of the Convex decentralized network directly from your desktop. The Convex GUI 
-application puts the control center for Web3 innovation at your fingertips. Designed for power users 
-and developers, this intuitive interface empowers you to seamlessly interact with Convex, build 
-next-generation dApps, and navigate the future of a democratized internet – all within a familiar
-and efficient desktop environment. Take command of your decentralized experience. 
- 
-Download the Convex GUI today.
-
-- Google Gemini
-```
+## Features
 
-## Usage
+- **Transaction Execution** - Submit transactions and queries to Convex networks
+- **Wallet Management** - Secure key generation and account management
+- **Local Network** - Run a local Convex peer cluster for development
+- **Network Visualization** - Real-time view of CPoS consensus and messaging
+- **Testing Tools** - Simulations and stress testing capabilities
 
-### Building
+## Quick Start
 
-You will need a recent version of Java (21+) and Maven (3.7+) installed
+### Download
 
-You can then build the latest version of Convex Desktop as follows:
+Download `convex.jar` from the [releases page](https://github.com/Convex-Dev/convex/releases).
 
-- Download the convex repository via git `https://github.com/Convex-Dev/convex.git` or using the zip download `https://github.com/Convex-Dev/convex/archive/refs/heads/develop.zip`
-- Run `mvn install` in the root directory (this will build all Convex modules)
-- The Convex `.jar` file should be created at `convex-integration/target/convex.jar` 
+### Run
+
+```bash
+java -jar convex.jar desktop
+```
 
-### Running Convex Desktop
+On Windows, you can also double-click `convex.jar` if Java is properly configured.
 
-If Java is properly installed on your machine, you should be able to run the `convex.jar` file directly as a Java application (double click on Windows).
+## Building from Source
 
-Alternatively, from the command line you can run the desktop with a Java command such as:
+**Requirements:** Java 21+, Maven 3.7+
 
 ```bash
-java -jar convex.jar desktop
+git clone https://github.com/Convex-Dev/convex.git
+cd convex
+mvn install
+java -jar convex-integration/target/convex.jar desktop
 ```
 
-This launches the Convex Desktop application main screen.
+## Documentation
+
+- [Convex Documentation](https://docs.convex.world)
+- [CLI Reference](../convex-cli/README.md)
+- [GitHub Repository](https://github.com/Convex-Dev/convex)
 
 ## License
 
-Copyright 2019-2024 The Convex Foundation and Contributors
+Copyright 2019-2025 The Convex Foundation and Contributors
 
-Code in convex-gui is provided under the [Convex Public License](../LICENSE.md). Alternate licenses can be granted for developers in the Convex ecosystem who have specific requirements - contact @mikera to discuss
+Code in convex-gui is provided under the [Convex Public License](../LICENSE.md).
 
-Feather Icons (https://github.com/feathericons/feather) used under MIT license 
+### Third-Party Licenses
 
-Material UI Swing (https://github.com/vincenzopalazzo/material-ui-swing) used under MIT license.
+- [Feather Icons](https://github.com/feathericons/feather) - MIT License
+- [Material UI Swing](https://github.com/vincenzopalazzo/material-ui-swing) - MIT License
diff --git a/convex-integration/README.md b/convex-integration/README.md
@@ -1,15 +1,52 @@
 # Convex Integration
 
-This module is used for contructing primary Convex artifacts and integration testing.
+Build assembly and integration testing module for [Convex](https://convex.world).
 
-## `convex.jar` construction
+## Purpose
 
-The `convex-integration` module builds `convex.jar` as a fat jar with dependencies for convenient distribution and usage (e.g. at the CLI)
+This module produces the `convex.jar` distribution artifact - a self-contained executable JAR with all dependencies included for easy distribution and command-line usage.
+
+## Build Output
+
+After building, `convex.jar` is located at:
+
+```
+convex-integration/target/convex.jar
+```
+
+## Building
+
+```bash
+cd convex
+mvn clean install
+```
+
+The JAR is created during the standard Maven build process.
+
+## Running
+
+```bash
+# Launch desktop GUI
+java -jar convex-integration/target/convex.jar desktop
+
+# Use CLI commands
+java -jar convex-integration/target/convex.jar --help
+java -jar convex-integration/target/convex.jar local start
+java -jar convex-integration/target/convex.jar key generate
+```
+
+See the [CLI documentation](../convex-cli/README.md) for full command reference.
 
 ## Integration Tests
 
-To run live integration tests do:
+Run live integration tests against a running network:
 
 ```bash
 mvn verify -Pintegration-tests
-```
+```
+
+## License
+
+Copyright 2020-2025 The Convex Foundation and Contributors
+
+Code in convex-integration is provided under the [Convex Public License](../LICENSE.md).
diff --git a/convex-peer/README.md b/convex-peer/README.md
diff --git a/convex-restapi/README.md b/convex-restapi/README.md
