moneyos 0.2.1 → 0.3.0

package/README.md

@@ -1,55 +1,210 @@
 # MoneyOS
 
-The operating system for money. Programmable money primitives for developers and AI agents.
+MoneyOS is an open source programmable money SDK and CLI for developers and AI
+agents. The repo includes balance, send, swap, runtime-composition, wallet,
+and executor code, with the project currently centered on Arbitrum.
 
-## Install
+The project is still early. Package boundaries and some APIs are still settling,
+but the repo is structured so each major surface can evolve independently.
+
+## What lives in this repo
+
+- `moneyos`: the root SDK + CLI package
+- `@moneyos/core`: runtime interfaces, shared types, chain/token registries
+- `@moneyos/tool-swap`: swap execution tool and provider surface
+- `@moneyos/executor-particle`: Particle AA smart-account executor
+
+## CLI
+
+Available commands:
 
 ```bash
-npm install moneyos
+moneyos init [--key 0x...] [--force] [--chain 42161] [--rpc https://...]
+moneyos auth unlock
+moneyos auth lock
+moneyos auth status
+moneyos backup export [--out ./wallet-backup.json] [--force]
+moneyos backup restore <path> [--force]
+moneyos backup status
+moneyos keystore status
+moneyos balance <token> [--address 0x...]
+moneyos send <amount> <token> <to>
+moneyos swap <amount> <tokenIn> <tokenOut>
 ```
 
-## CLI
+For the full command surface and flag details, run `moneyos --help`.
+
+Example:
 
 ```bash
-# Check balance
+moneyos init
+moneyos auth unlock
 moneyos balance USDC
-moneyos balance ETH --address 0x...
-
-# Send tokens
-moneyos send 10 USDC 0x...
-moneyos send 0.1 ETH 0x...
+moneyos backup status
 ```
 
 ## SDK
 
-```typescript
-import { MoneyOS } from "moneyos";
+```ts
+import { createMoneyOS } from "moneyos";
 
-const moneyos = new MoneyOS({
+const moneyos = createMoneyOS({
   chainId: 42161,
-  privateKey: process.env.PRIVATE_KEY,
+  privateKey: process.env.MONEYOS_PRIVATE_KEY as `0x${string}`,
 });
 
-// Check balance
 const balance = await moneyos.balance("USDC");
-console.log(balance.amount); // "250.50"
+console.log(balance.amount);
 
-// Send tokens
 const tx = await moneyos.send("USDC", "0x...", "10");
 console.log(tx.hash);
 ```
 
-## Supported Chains
+The runtime seam is intentionally small. `createMoneyOS` can also take injected
+`execute`, `read`, and `assets` implementations, which is how external packages
+plug in.
+
+## Published npm package
+
+The current `main` branch is ahead of the published npm package. The encrypted
+wallet flow described below requires cloning this repo and building from
+source. `npm install moneyos` currently gives you an older pre-encrypted-wallet
+release.
+
+## Current wallet model
+
+What is landed in code today:
+
+- The CLI stores the root wallet in an encrypted local wallet file at `~/.moneyos/wallet.json`
+- `~/.moneyos/config.json` now stores only non-secret settings such as chain and RPC configuration
+- `MONEYOS_PRIVATE_KEY` remains an explicit override for ephemeral CI or agent runs
+- `moneyos auth unlock` opens a short-lived local session for write commands
+- `moneyos backup export|restore|status` manages encrypted wallet backups
+- Normal wallet commands resolve their write path through one shared session-aware flow
+- Local EOA signers use viem's nonce manager, so back-to-back live transactions
+  use pending-aware nonce sequencing
+
+What is intentionally not shipped yet:
+
+- password-manager integrations
+- unlock-helper plugins
+- delegated agent spending limits
+- smart-account policy sessions
+
+Password managers are not wallet backends in MoneyOS. The current model is:
+local encrypted wallet, local human unlock, short-lived session, and encrypted
+wallet backup files.
+
+The design notes for the current and target wallet architecture live in
+[`docs/keystore.md`](docs/keystore.md).
+
+## Importing an existing wallet
+
+If you already have a raw private key, import it with `init`:
+
+```bash
+moneyos init --key 0x...
+```
+
+MoneyOS prompts you for a wallet password, encrypts the key into
+`~/.moneyos/wallet.json`, and writes an initial encrypted backup under
+`~/.moneyos/backups/`. After that, use `moneyos auth unlock` before any
+write command.
 
-| Chain | ID |
-|-------|-----|
-| Arbitrum | 42161 |
-| Ethereum | 1 |
-| Polygon | 137 |
+The CLI only supports raw hex private-key import today. Seed phrases,
+keystore v3 JSON files, and hardware-wallet derivation are not implemented.
+If your wallet currently lives in one of those formats, derive the raw hex
+with another tool first.
 
-## Supported Tokens
+If you have a legacy `~/.moneyos/config.json` with a plaintext `privateKey`
+field from a pre-encrypted-wallet version of the CLI, `moneyos init` with no
+flags will detect and import that key automatically.
+
+## Threat model
+
+What this wallet model is meant to protect against:
+
+- accidental plaintext private-key storage in `config.json`
+- casual disk access while the wallet is locked
+- copying encrypted wallet backups without also knowing the wallet password
+- sending the wallet password through normal AI chat flows
+
+What it does not protect against:
+
+- malware already running as your user while the wallet is unlocked
+- a compromised machine that can inspect local process memory
+- someone who knows your wallet password
+- loss of both the encrypted wallet and its password
+
+## Known operational limitations
+
+- If a session-backed `send` or `swap` returns a timeout or disconnect error,
+  do not assume nothing was broadcast. Verify on-chain before retrying.
+- PR #12 fixed the common 750ms false-timeout path, but client-disconnect
+  detection and request idempotency are still follow-up work.
+
+The intended operating model is simple: keep the wallet encrypted locally,
+unlock it locally when you want to write, keep sessions short, and save the
+wallet password in your password manager of choice yourself.
+
+## Supported chains and tokens
+
+Default chain: Arbitrum One (`42161`)
+
+Built-in chains:
+
+- Arbitrum
+- Ethereum
+- Polygon
+
+Built-in tokens:
+
+- USDC
+- USDT
+- RYZE
+- ETH
+- POL
+
+## Current validation status
+
+What we have verified locally on the current code:
+
+- unit tests pass
+- lint passes
+- typechecks pass
+- workspace builds pass
+- the built CLI runs
+- encrypted wallet creation, unlock/session, backup export, and backup restore protections are covered by tests
+- read-only balance checks work
+- the session-backed send path has a real slow-daemon regression test after PR #12
+- repeated live transactions worked before wallet v1 landed, which validated the
+  nonce-manager fix but should not be treated as end-to-end validation of the
+  current session-backed wallet flow
+
+What still needs more hands-on validation:
+
+- live session-backed ETH send
+- live session-backed ERC-20 send
+- live session-backed swap
+- Particle executor against real infrastructure
+- more live usage of the encrypted-wallet/auth/backup flow in a real terminal
+
+## Development
+
+```bash
+npm install
+npm run build:core
+npm run build:tool-swap
+npm run build:executor-particle
+npm run typecheck
+npm test
+npm run lint
+npm run build
+```
 
-USDC, USDT, RYZE, ETH (native)
+The repo currently uses npm workspaces. Before any npm release, verify the
+packed tarballs with `npm pack --dry-run` and confirm publish-time dependency
+resolution for the extracted workspace packages.
 
 ## License