From d814a8b20a69870f65187f0837193a54eabf8865 Mon Sep 17 00:00:00 2001
From: Mark Toda <toda.mark@gmail.com>
Date: Wed, 1 Jan 2025 17:58:56 -0500
Subject: [PATCH] feat: update readme

---
 README.md | 222 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 159 insertions(+), 63 deletions(-)

diff --git a/README.md b/README.md
index 1242fe7..fafc416 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,14 @@
 # Chainz
 
-A simple CLI tool for managing chain configurations
+A CLI tool for managing EVM chain configurations
+
+## Features
+
+- Interactive chain discovery and configuration
+- Dynamic RPC health checking and failover
+- Private key management
+- Multiple RPC support per chain
+- Environment variable interpolation
 
 ## Installation
 
@@ -10,89 +18,177 @@ cd chainz
 cargo install --path .
 ```
 
-## Usage
+## Quick Start
 
-### Add a new chain
 ```bash
-> chainz add -h
-chainz-add 0.1.0
-Add a new chain
-
-USAGE:
-    chainz add [OPTIONS] --name <name> --rpc-url <rpc-url> --verification-api-key <verification-api-key>
-
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
-
-OPTIONS:
-    -n, --name <name>
-    -p, --private-key <private-key>
-    -r, --rpc-url <rpc-url>
-    -v, --verification-api-key <verification-api-key>
-
-> chainz add --name mainnet -r https://mainnet.infura.io/v3/{INFURA_KEY} -v {ETHERSCAN_API_KEY}
-mainnet (ChainId: 1)
-Wallet: 0x0000000000000000000000000000000000000000 (Balance: 80072519714480901)
+# Initialize with interactive wizard
+chainz init
+
+# Add a new chain
+chainz add
+
+# List configured chains
+chainz list
+
+# Switch to a chain
+chainz use ethereum
+source .env
 ```
 
-### List chains
-```bash
-> chainz list -h
-chainz-list 0.1.0
-List all chains
+## Usage
 
-USAGE:
-    chainz list
+### Adding Chains
 
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
+Chainz provides an interactive wizard for adding chains:
 
+```bash
+> chainz add
+Chain Selection
+══════════════════════════════════════════════════════
+? Type to search and select a chain
+> ethereum (1)
+  optimism (10)
+  arbitrum (42161)
+  polygon (137)
+  ...
+
+RPC Configuration
+══════════════════════════════════════════════════════
+Testing RPCs...
+✓ https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}
+✓ https://eth.llamarpc.com
+✗ https://mainnet.infura.io/v3/${INFURA_KEY}
+
+Key Configuration
+══════════════════════════════════════════════════════
+? Select a key
+> default (0x123...789)
+  deployer (0xabc...def)
+  Add new key
+
+Chain added: ethereum (ChainId: 1)
+```
+
+### Managing Chains
+
+List configured chains and their status:
 
+```bash
 > chainz list
-optimism (ChainId: 10)
-Wallet: 0x0000000000000000000000000000000000000000 (Balance: 1336192881671202)
+Chain: ethereum
+├─ ID: 1
+├─ Active RPC: https://eth-mainnet.g.alchemy.com/v2/...
+├─ Verification Key: 0xabc...def
+└─ Key Name: default
+
+Chain: optimism
+├─ ID: 10
+├─ Active RPC: https://opt-mainnet.g.alchemy.com/v2/...
+├─ Verification Key: None
+└─ Key Name: deployer
+```
+
+Update chain configuration:
 
-arbitrum (ChainId: 42161)
-Wallet: 0x0000000000000000000000000000000000000000 (Balance: 10959312699843000)
+```bash
+> chainz update
+Testing all RPCs...
+✓ ethereum: 2/3 RPCs working
+✓ optimism: 1/1 RPCs working
+✗ arbitrum: 0/1 RPCs working
+
+? Select chain to update
+? What would you like to update?
+> RPC URL
+  Key
+  Verification API Key
 ```
 
-### Switch to a chain
+### Using Chains
+
+Switch to a chain and set up environment:
+
 ```bash
-> chainz use -h
-chainz-use 0.1.0
-Use a chain by name or chainid. Writes to a local .env which can be sourced
+> chainz use ethereum
+Chain: ethereum
+├─ ID: 1
+├─ RPC: https://rpc.com
+└─ Wallet: 0x123...789
 
-USAGE:
-    chainz use [FLAGS] <name-or-id>
+> source .env
+> echo $FOUNDRY_RPC_URL
+https://rpc.com
+```
 
-FLAGS:
-    -h, --help       Prints help information
-    -p, --print
-    -V, --version    Prints version information
+Execute commands with chain context:
 
-ARGS:
-    <name-or-id>
+```bash
+> chainz exec 1 -- cast block-number
+21532741
 
-> chainz use mainnet && source .env
+> chainz exec ethereum -- cast balance @wallet
+1.5 ETH
 
-> echo $FOUNDRY_RPC_URL
-https://mainnet.infura.io/v3/{INFURA_KEY}
-> echo $FOUNDRY_PRIVATE_KEY
-{PRIVATE_KEY}
-> echo $FOUNDRY_VERIFICATION_API_KEY
-{ETHERSCAN_API_KEY}
+> chainz exec 10 -- forge script Deploy
 ```
 
-### Set global defaults
+### Managing Keys
+
+Add and manage private keys:
+
 ```bash
-> chainz set --default-private-key {key}
-> chainz set --env-prefix FOUNDRY
+> chainz key add deployer
+Enter private key: ****
+Added key 'deployer'
+
+> chainz key list
+Stored keys:
+- default: 0x123...789
+- deployer: 0xabc...def
 ```
 
-### Importing a chainz config
-Configs are stored at $HOME/.chainz.json. If you have a pre-made chainz file, you can import it by simply copying it to this location.
+### Custom Variables
+
+Set and use custom variables:
+
+```bash
+> chainz var set ALCHEMY_KEY abc123
+> chainz var set ETHERSCAN_KEY def456
 
-## TODOs
-- Import config from 1password etc.
+> chainz var list
+ALCHEMY_KEY=abc123
+ETHERSCAN_KEY=def456
+```
+
+## Configuration
+
+### Config File
+
+Configs are stored at `$HOME/.chainz.json`:
+
+```json
+{
+  "chains": [
+    {
+      "name": "ethereum",
+      "chain_id": 1,
+      "rpc_urls": [
+        "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}",
+        "https://eth.llamarpc.com"
+      ],
+      "selected_rpc": "https://eth.llamarpc.com",
+      "verification_api_key": "abc123",
+      "key_name": "default"
+    }
+  ],
+  "variables": {
+    "ALCHEMY_KEY": "def456"
+  },
+  "keys": {
+    "default": {
+      "type": "PrivateKey",
+      "value": "0x123..."
+    }
+  }
+}
+```