Update Java SDK README

Author: mikera

convex-java/README.md

@@ -1,52 +1,97 @@
-# convex-java
-Java client library for Convex
+# Convex Java SDK
 
-## About
+[![Maven Central](https://img.shields.io/maven-central/v/world.convex/convex-java.svg?label=Maven%20Central)](https://search.maven.org/search?q=world.convex)
+[![javadoc](https://javadoc.io/badge2/world.convex/convex-java/javadoc.svg)](https://javadoc.io/doc/world.convex/convex-java)
 
-Convex is an open, decentralised technology for the Internet of Value. Java is one of the world's leading programming languages, especially in the realm of business and finance.
+The official Java SDK for building applications on the [Convex](https://convex.world) network.
 
-`convex-java` provides everything Java developers need to access Convex and utilise all of its capabilities from their own applications.
+## Installation
 
-## Usage
+### Maven
 
-You will need a connection to a peer on the Convex Network. Peers are servers which participate in the maintaining consensus on the Convex Network, by executing the CPoS consensus algorithm and validating transactions. It is easiest if you simply use the free public peer available at `https://convex.world`.
+```xml
+<dependency>
+    <groupId>world.convex</groupId>
+    <artifactId>convex-java</artifactId>
+    <version>0.8.2</version>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+implementation 'world.convex:convex-java:0.8.2'
+```
+
+## Quick Start
+
+### Connect to the Network
 
 ```java
+import convex.java.Convex;
+
+// Connect to the public test network
 Convex convex = Convex.connect("https://convex.world");
 ```
 
-To utilise the network, you will need an account with available funds. On the Test Network, you can obtain one by requesting a new account with free balance (up to 10,000,000 Convex copper coins). This should be enough for most simple testing.
+### Create an Account
 
 ```java
-convex.useNewAccount(10000000);
+// Request a new account with test funds (up to 10,000,000 copper coins)
+convex.useNewAccount(10_000_000);
+
+// Access your key pair (required for signing transactions)
+AKeyPair keyPair = convex.getKeyPair();
 ```
 
-`convex-java` will automatically generate a new cryptographic key pair to secure your new account. Having a valid key pair for the account is the *only way* to successfully submit transactions for that Account on the Convex Network. If you want to access the key pair, you can use:
+### Execute Queries
+
+Queries are read-only operations that don't modify state:
 
 ```java
-convex.getKeyPair()
+// Query the current balance
+ACell result = convex.query("*balance*");
 ```
 
+### Submit Transactions
 
+Transactions modify on-chain state and require a funded account:
 
+```java
+// Transfer funds to another account
+ACell result = convex.transact("(transfer #42 1000000)");
 
+// Deploy a smart contract
+ACell result = convex.transact("(deploy '(do (defn greet [name] (str \"Hello, \" name))))");
+```
 
-## Installation and Configuration
+## Key Concepts
 
-You can clone this repository and run `mvn install` to get a working local version. This is recommended for developers who wish to use early snapshot versions or contribute to `convex-java` as an open source project.
+| Concept | Description |
+|---------|-------------|
+| **Account** | Self-sovereign identity on Convex, identified by address (e.g., `#42`) |
+| **Key Pair** | Ed25519 cryptographic keys for signing transactions |
+| **Query** | Read-only operation, free to execute |
+| **Transaction** | State-changing operation, consumes juice (gas) |
+| **Convex Lisp** | On-chain programming language for smart contracts |
 
-`convex-java` is also available as a Maven dependency.
+## Building from Source
 
+```bash
+git clone https://github.com/Convex-Dev/convex.git
+cd convex
+mvn install -pl convex-java -am
 ```
-<dependency>
-	<groupId>world.convex</groupId>
-	<artifactId>convex-java</artifactId>
-	<version>0.0.1</version>
-</dependency>
-```
+
+## Resources
+
+- [Convex Documentation](https://docs.convex.world)
+- [Javadoc API Reference](https://javadoc.io/doc/world.convex/convex-java)
+- [GitHub Repository](https://github.com/Convex-Dev/convex)
+- [Discord Community](https://discord.com/invite/xfYGq4CT7v)
 
 ## License
 
-Copyright 2021-203 The Convex Foundation and Contributors
+Copyright 2021-2025 The Convex Foundation and Contributors
 
-Code in convex-java is provided under the Convex Public License
+Code in convex-java is provided under the [Convex Public License](../LICENSE.md).