ethnotary 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,66 @@
 # Ethnotary CLI
 
-CLI for managing MultiSig accounts, transactions, and data queries across EVM networks.
+A command-line tool for managing multi-signature wallets across EVM networks. Built for teams, DAOs, and AI agents who need secure, collaborative control over on-chain treasuries.
 
-## Installation
+**Key Use Cases:**
+- **Treasury Management** – Collaboratively manage funds with multi-sig approval workflows
+- **Payment Collection** – Receive and track payments across multiple networks
+- **AI Agent Integration** – Enable AI agents to submit transactions while humans retain approval authority
+- **Cross-Chain Operations** – Deploy and manage the same wallet on Sepolia, and Base-Sepolia, and more networks to come.
+
+With multi-signature approvals, every transaction requires consensus—keeping you in control while enabling automation and collaboration.
+
+## How Multi-Signature Works
+
+A multi-signature (multi-sig) wallet requires multiple approvals before a transaction can execute. You define the number of **owners** and how many **confirmations** are required.
+
+**Common Configurations:**
+
+| Setup | Use Case |
+|-------|----------|
+| **1 of 1** | Single owner, instant execution. Good for personal wallets or AI agents with full autonomy. |
+| **1 of 2** | Either owner can approve. Useful for shared access (e.g., you + your AI agent). |
+| **2 of 2** | Both owners must approve. Maximum security for two-party agreements. |
+| **2 of 3** | Any 2 of 3 owners must approve. Balances security with availability—if one key is lost, funds are still accessible. |
+| **3 of 5** | Majority approval for DAOs or teams. Prevents single points of failure. |
 
+**Example: AI Agent Integration (1 of 2)**
+```
+Owners: [Your Wallet, AI Agent Wallet]
+Required: 1
+
+→ AI agent can submit AND execute transactions autonomously
+→ You can also execute transactions when needed
+```
+
+**Example: Human Oversight (2 of 2)**
+```
+Owners: [Your Wallet, AI Agent Wallet]
+Required: 2
+
+→ AI agent submits transactions
+→ You review and approve before execution
+→ Nothing happens without your confirmation
+```
+
+## Prerequisites
+
+- **Node.js** (v16 or higher) - [Download](https://nodejs.org/)
+- **npm** (comes with Node.js)
+- **RPC URL** – Connection to your target network (e.g., from [Infura](https://infura.io), [Alchemy](https://alchemy.com), or a public RPC)
+- **ETH for gas** – Enough cryptocurrency on your target network to pay for transaction fees
+
+Verify Node.js installation:
 ```bash
-# Install globally
-npm install -g .
+node --version  # Should show v16.x.x or higher
+npm --version   # Should show 8.x.x or higher
+```
+
+## Installation
 
-# Or use npm link for development
-npm link
+```bash
+# Install globally from npm
+npm install -g ethnotary
 ```
 
 ## Quick Start
@@ -60,6 +111,31 @@ ethnotary wallet import     # Import existing key/mnemonic
 ethnotary wallet show       # Display wallet address
 ```
 
+## Wallet Security
+
+Your private keys **never leave your machine**. Ethnotary stores wallet credentials locally in an encrypted keystore file, protected by a password you choose.
+
+**Wallet Priority:**
+1. `--private-key` flag – Explicit override for single commands
+2. **Encrypted keystore** – Default, password-protected (recommended)
+3. `PRIVATE_KEY` env var – Fallback for scripts/automation
+
+```bash
+# Create a new encrypted wallet (stored locally)
+ethnotary wallet init
+
+# View your wallet address
+ethnotary wallet show
+```
+
+**What stays on your machine:**
+- Private keys (encrypted in keystore)
+- Wallet passwords (never stored, prompted each time)
+- RPC URLs and API keys (in `~/.ethnotary/config.json`)
+
+**What goes on-chain:**
+- Only signed transactions you explicitly submit
+- Your public address (visible in transactions)
 ### Account Management
 
 Account management commands apply changes across ALL networks the contract is deployed on.
@@ -333,33 +409,21 @@ All configuration is stored in `~/.ethnotary/`:
 
 Supported networks (use `--network <name>` or `--chain-id <id>`):
 
-**Mainnets:**
+**Currently Supported:**
+| Network | Name | Chain ID |
+|---------|------|----------|
+| Sepolia | `sepolia` | 11155111 |
+| Base Sepolia | `base-sepolia` | 84532 |
+
+**Coming Soon:**
 | Network | Name | Chain ID |
 |---------|------|----------|
 | Ethereum Mainnet | `ethereum` | 1 |
-| Optimism | `optimism` | 10 |
 | Base | `base` | 8453 |
 | Arbitrum One | `arbitrum` | 42161 |
-| Arbitrum Nova | `arbitrum-nova` | 42170 |
-| zkSync Era | `zksync-era` | 324 |
-| Scroll | `scroll` | 534352 |
-| Polygon zkEVM | `polygon-zkevm` | 1101 |
-| Linea | `linea` | 59144 |
+| Optimism | `optimism` | 10 |
 | Polygon PoS | `polygon` | 137 |
-| Gnosis Chain | `gnosis` | 100 |
-| Avalanche C-Chain | `avalanche` | 43114 |
-| Celo | `celo` | 42220 |
-| Soneium | `soneium` | 1868 |
-
-**Testnets:**
-| Network | Name | Chain ID |
-|---------|------|----------|
-| Sepolia | `sepolia` | 11155111 |
-| Base Sepolia | `base-sepolia` | 84532 |
-| Arbitrum Sepolia | `arbitrum-sepolia` | 421614 |
-| Polygon Mumbai | `polygon-mumbai` | 80001 |
-| Polygon Amoy | `polygon-amoy` | 80002 |
-| Avalanche Fuji | `avalanche-fuji` | 43113 |
+| *...and more* | | |
 
 **Configure RPC URLs:**
 ```bash

package/cli/commands/account/index.js

@@ -168,40 +168,75 @@ account
 
     try {
       const address = resolveAddress(options.address);
-      // Get first network from contract's networks, or use specified network
       const contractNetworks = getContractNetworks(options.address);
-      const networkKey = globalOpts.network || contractNetworks[0] || 'sepolia';
-      const network = await getNetwork(networkKey);
-      const provider = new ethers.JsonRpcProvider(network.rpc);
+      const networksToQuery = contractNetworks.length > 0 ? contractNetworks : ['sepolia'];
 
-      // Check if contract exists
-      const code = await provider.getCode(address);
-      if (code === '0x') {
-        out.error(`No contract found at ${address} on ${network.name}`);
-        return;
-      }
+      out.startSpinner('Fetching account info across all networks...');
 
-      const multisig = new ethers.Contract(address, MULTISIG_ABI, provider);
+      // Fetch balances from all networks in parallel
+      const balancePromises = networksToQuery.map(async (networkKey) => {
+        try {
+          const network = await getNetwork(networkKey);
+          const provider = new ethers.JsonRpcProvider(network.rpc);
+          const balance = await provider.getBalance(address);
+          return { network: networkKey, balance: ethers.formatEther(balance), raw: balance };
+        } catch (e) {
+          return { network: networkKey, balance: 'unavailable', error: e.message };
+        }
+      });
 
-      out.startSpinner('Fetching account info...');
+      // Get account details from first available network
+      let owners = [];
+      let required = 0;
+      let primaryNetwork = null;
 
-      const [owners, required, balance] = await Promise.all([
-        multisig.getOwners(),
-        multisig.required(),
-        provider.getBalance(address)
-      ]);
+      for (const networkKey of networksToQuery) {
+        try {
+          const network = await getNetwork(networkKey);
+          const provider = new ethers.JsonRpcProvider(network.rpc);
+          const code = await provider.getCode(address);
+          if (code !== '0x') {
+            const multisig = new ethers.Contract(address, MULTISIG_ABI, provider);
+            [owners, required] = await Promise.all([
+              multisig.getOwners(),
+              multisig.required()
+            ]);
+            primaryNetwork = networkKey;
+            break;
+          }
+        } catch (e) {
+          continue;
+        }
+      }
+
+      if (!primaryNetwork) {
+        out.failSpinner('Contract not found on any network');
+        return;
+      }
+
+      const balances = await Promise.all(balancePromises);
+      const totalBalance = balances.reduce((sum, b) => {
+        if (b.raw) return sum + b.raw;
+        return sum;
+      }, 0n);
 
       out.succeedSpinner('Account info retrieved');
 
+      // Format balances object
+      const balancesByNetwork = {};
+      for (const b of balances) {
+        balancesByNetwork[b.network] = b.error ? b.balance : `${b.balance} ETH`;
+      }
+
       out.print({
         address,
-        network: networkKey,
-        networks: contractNetworks,
+        networks: networksToQuery,
         owners: owners.map(o => o),
         required: Number(required),
         ownerCount: owners.length,
         confirmationsNeeded: `${required} of ${owners.length}`,
-        balance: ethers.formatEther(balance) + ' ETH'
+        balances: balancesByNetwork,
+        totalBalance: ethers.formatEther(totalBalance) + ' ETH'
       });
 
     } catch (error) {

package/cli/commands/wallet/index.js

@@ -151,26 +151,27 @@ wallet
     const out = createOutput(globalOpts);
 
     try {
-      // Check for private key in options or env
+      // Priority 1: --private-key flag (explicit override)
       if (globalOpts.privateKey) {
         const wallet = new ethers.Wallet(globalOpts.privateKey);
         out.print({ address: wallet.address, source: 'private-key-flag' });
         return;
       }
 
-      if (process.env.PRIVATE_KEY) {
-        const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
-        out.print({ address: wallet.address, source: 'environment' });
-        return;
-      }
-
-      // Check keystore
+      // Priority 2: Keystore (default if exists)
       if (keystoreExists()) {
         const address = getKeystoreAddress();
         out.print({ address: address, source: 'keystore' });
         return;
       }
 
+      // Priority 3: Environment variable (fallback)
+      if (process.env.PRIVATE_KEY) {
+        const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
+        out.print({ address: wallet.address, source: 'environment' });
+        return;
+      }
+
       out.error('No wallet configured. Use --private-key, set PRIVATE_KEY env var, or run "ethnotary wallet init"');
 
     } catch (error) {

package/cli/index.js

@@ -558,18 +558,34 @@ async function checkRpcConfig() {
           const receipt = await tx.wait();
           
           // Get deployed address from event or use predicted
-          let actualAddress = predictedAddress;
+          let actualAddress = null;
           for (const log of receipt.logs) {
             try {
               const parsed = factory.interface.parseLog(log);
               if (parsed && parsed.name === 'NewMSACreated') {
-                actualAddress = parsed.args.msa;
+                // The event has a single indexed address parameter
+                actualAddress = parsed.args.msaAddress || parsed.args[0];
                 break;
               }
-            } catch (e) {}
+            } catch (e) {
+              // Log might be from a different contract, try parsing the topic directly
+              // NewMSACreated(address indexed msaAddress) - topic[1] contains the address
+              if (log.topics && log.topics.length >= 2) {
+                const eventSig = ethers.id('NewMSACreated(address)');
+                if (log.topics[0] === eventSig) {
+                  actualAddress = ethers.getAddress('0x' + log.topics[1].slice(26));
+                  break;
+                }
+              }
+            }
+          }
+          
+          // Fallback to predicted address if event parsing failed
+          if (!actualAddress) {
+            actualAddress = predictedAddress;
           }
 
-          if (!deployedAddress) {
+          if (!deployedAddress && actualAddress) {
             deployedAddress = actualAddress;
           }
 

package/cli/utils/auth.js

@@ -15,12 +15,12 @@ function ensureDir() {
 
 /**
  * Get wallet from various sources (priority order):
- * 1. --private-key flag
- * 2. PRIVATE_KEY env var
- * 3. Encrypted keystore (prompts for password)
+ * 1. --private-key flag (explicit override)
+ * 2. Encrypted keystore (default if exists)
+ * 3. PRIVATE_KEY env var (fallback for scripts/automation)
  */
 async function getWallet(options = {}) {
-  // Priority 1: Direct private key from CLI flag
+  // Priority 1: Direct private key from CLI flag (explicit override)
   if (options.privateKey) {
     try {
       return new ethers.Wallet(options.privateKey);
@@ -29,20 +29,14 @@ async function getWallet(options = {}) {
     }
   }
 
-  // Priority 2: Environment variable
-  if (process.env.PRIVATE_KEY) {
-    try {
-      return new ethers.Wallet(process.env.PRIVATE_KEY);
-    } catch (e) {
-      throw new Error(`Invalid PRIVATE_KEY in environment: ${e.message}`);
-    }
-  }
-
-  // Priority 3: Encrypted keystore
+  // Priority 2: Encrypted keystore (default if exists)
   if (keystoreExists()) {
     if (!options.password) {
-      // In non-interactive mode (--json), we can't prompt
+      // In non-interactive mode (--json), fall back to env var
       if (options.json) {
+        if (process.env.PRIVATE_KEY) {
+          return new ethers.Wallet(process.env.PRIVATE_KEY);
+        }
         throw new Error('No private key provided. Use --private-key or set PRIVATE_KEY env var.');
       }
       // Interactive mode - prompt for password
@@ -58,6 +52,15 @@ async function getWallet(options = {}) {
     return await loadKeystore(options.password);
   }
 
+  // Priority 3: Environment variable (fallback for scripts/automation)
+  if (process.env.PRIVATE_KEY) {
+    try {
+      return new ethers.Wallet(process.env.PRIVATE_KEY);
+    } catch (e) {
+      throw new Error(`Invalid PRIVATE_KEY in environment: ${e.message}`);
+    }
+  }
+
   throw new Error('No wallet configured. Use --private-key, set PRIVATE_KEY env var, or run "ethnotary wallet init"');
 }
 

package/cli/utils/constants.js

@@ -5,7 +5,7 @@
  */
 
 // Default MSA Factory address - same across all EVM networks via CREATE2
-const DEFAULT_MSA_FACTORY = '0x25115564780D3Da99623EaeB9f4eFE88eD801261';
+const DEFAULT_MSA_FACTORY = '0x3DEB514B2ac536b8048f5b37182196cf9d5dDD45';
 
 // Default PIN Verifier (Groth16Verifier) address - same across all EVM networks via CREATE2
 const DEFAULT_PIN_VERIFIER = '0x65ee46C4d21405f4a4C8e9d0F8a3832c1B885ab4';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethnotary",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI for managing MultiSig accounts, transactions, and data queries across EVM networks",
   "main": "cli/index.js",
   "bin": {