@towns-labs/wallet 7.0.0 → 7.2.0

package/README.md

@@ -49,10 +49,10 @@ Create a new account (interactive password prompt):
 tw account create
 ```
 
-Create a named profile in local dev:
+Create a named profile:
 
 ```bash
-tw account create --env dev --profile agent
+tw account create --profile agent
 ```
 
 Keystore layout:
@@ -65,7 +65,7 @@ Keystore layout:
 Resume a previously created profile:
 
 ```bash
-tw account create --resume --env dev --profile agent
+tw account create --resume --profile agent
 ```
 
 Non-interactive mode (stdin password + JSON output):
@@ -77,7 +77,7 @@ echo "my-password" | tw account create --password-stdin --json
 Use an explicit keystore path:
 
 ```bash
-tw account create --keystore-path ~/.config/towns/tw/profiles/dev/team/default.keystore.json --env dev
+tw account create --keystore-path ~/.config/towns/tw/profiles/prod/team/default.keystore.json
 ```
 
 ## Account Export
@@ -85,19 +85,19 @@ tw account create --keystore-path ~/.config/towns/tw/profiles/dev/team/default.k
 Export metadata only (safe default):
 
 ```bash
-tw account export --env dev --profile agent
+tw account export --profile agent
 ```
 
 Export metadata in JSON:
 
 ```bash
-tw account export --env dev --profile agent --json
+tw account export --profile agent --json
 ```
 
 Export decrypted private keys (interactive confirmation required):
 
 ```bash
-tw account export --env dev --profile agent --show-private
+tw account export --profile agent --show-private
 ```
 
 ## Account Address
@@ -105,7 +105,7 @@ tw account export --env dev --profile agent --show-private
 Print the main/root account address:
 
 ```bash
-tw account address --env dev --profile agent
+tw account address --profile agent
 ```
 
 ## Address (Root Alias)
@@ -141,17 +141,15 @@ tw address --token 0x1111111111111111111111111111111111111111 --amount 1 --decim
 Check USDC balance for the main/root account on Base (default):
 
 ```bash
-tw account balance --env dev --profile agent
+tw account balance --profile agent
 ```
 
 Check USDC balance on Polygon:
 
 ```bash
-tw account balance --env prod --profile agent --chain polygon
+tw account balance --profile agent --chain polygon
 ```
 
-For local dev (`--env dev`), default chain is Anvil (`http://127.0.0.1:8545`).
-
 ## Account Send
 
 Send USDC to an address:
@@ -169,15 +167,42 @@ tw account send 2.5 vitalik.eth --chain base
 Send USDC on Polygon with JSON output:
 
 ```bash
-tw account send 10 0x1111111111111111111111111111111111111111 --chain polygon --env prod --json
+tw account send 10 0x1111111111111111111111111111111111111111 --chain polygon --json
+```
+
+Send using a specific local session by name (without changing active session):
+
+```bash
+tw account send 1 0x1111111111111111111111111111111111111111 --profile agent --session worker-2
+```
+
+## Account History
+
+Get paginated relayer call history for an EOA. By default this uses your local profile root EOA from keystore:
+
+```bash
+tw account history --profile agent
+```
+
+Query an explicit EOA (without reading local keystore):
+
+```bash
+tw account history --address 0x1111111111111111111111111111111111111111 --limit 10 --offset 20
 ```
 
-Local dev defaults to Anvil:
+Filter by one or more chains:
 
 ```bash
-tw account send 1 0x1111111111111111111111111111111111111111 --env dev
+tw account history --chain base,polygon --json
 ```
 
+Notes:
+
+- `--limit` defaults to `20` and max is `100`
+- `--offset` defaults to `0`
+- `offset + limit` must be `<= 1000`
+- History queries are EOA-based (root EOA), not delegated account address
+
 ## Contacts
 
 Store aliases in a global contacts file:
@@ -238,21 +263,23 @@ Send with a portable session file (no root keystore required):
 
 ```bash
 tw account send 1 0x1111111111111111111111111111111111111111 \
-  --env prod --chain base --session-file ./worker-1.session.json
+  --chain base --session-file ./worker-1.session.json
 ```
 
+`--session` and `--session-file` are mutually exclusive.
+
 ## Account Status
 
 Show compact readiness status:
 
 ```bash
-tw account status --env dev --profile agent
+tw account status --profile agent
 ```
 
 JSON output for automation:
 
 ```bash
-tw account status --env prod --profile agent --chain polygon --json
+tw account status --profile agent --chain polygon --json
 ```
 
 ## Account Update Password
@@ -260,7 +287,7 @@ tw account status --env prod --profile agent --chain polygon --json
 Rotate local keystore encryption password (interactive):
 
 ```bash
-tw account update password --env dev --profile agent
+tw account update password --profile agent
 ```
 
 Rotate password non-interactively using stdin lines:
@@ -295,6 +322,10 @@ Grant full wildcard access (explicit opt-in):
 echo "my-password" | tw session create worker-admin --profile agent --full-access --password-stdin
 ```
 
+`--full-access` is mutually exclusive with `--target`, `--selector`, `--spend-limit`, `--spend-limit-raw`, and `--spend-period`.
+Omitting both `--target` and `--selector` uses wildcard call permissions by default; you do not need to pass magic wildcard values.
+`--spend-limit` accepts human USDC amounts (for example `10` = `10 USDC`). Use `--spend-limit-raw` for base units.
+
 ## Session List
 
 List local sessions:
@@ -355,6 +386,10 @@ Rotate to an explicit new session name:
 echo "my-password" | tw session rotate --profile agent --new-name worker-3 --password-stdin
 ```
 
+`--full-access` is mutually exclusive with `--target`, `--selector`, `--spend-limit`, `--spend-limit-raw`, and `--spend-period`.
+Omitting both `--target` and `--selector` uses wildcard call permissions by default; you do not need to pass magic wildcard values.
+`--spend-limit` accepts human USDC amounts (for example `10` = `10 USDC`). Use `--spend-limit-raw` for base units.
+
 Resume interrupted rotation:
 
 ```bash
@@ -381,6 +416,150 @@ Idempotent retry/cleanup when already revoked on-chain:
 echo "my-password" | tw session revoke worker-2 --profile agent --resume --password-stdin --json
 ```
 
+## Agent Commands
+
+Agents are session-key-backed Towns identities with their own encryption device and named channel bindings.
+
+Agent keystore files live alongside normal sessions:
+
+```text
+~/.config/towns/tw/profiles/<env>/<profile>/sessions/agent-<name>.json
+~/.config/towns/tw/profiles/<env>/<profile>/agent-channels.json
+```
+
+Create two local agents:
+
+```bash
+TW_PASSWORD="my-password" tw agent create alice --profile agent
+TW_PASSWORD="my-password" tw agent create bob --profile agent
+```
+
+List local agents:
+
+```bash
+TW_PASSWORD="my-password" tw agent list --profile agent --json
+```
+
+Create or bind a named channel:
+
+```bash
+TW_PASSWORD="my-password" tw agent connect --from alice --channel art --to bob --profile agent
+```
+
+The first `connect` returns:
+
+- `streamId` — the underlying GDM stream
+- `secret` — the shared rendezvous secret, returned only when the binding is first created
+
+Bind the same named channel from the other side:
+
+```bash
+TW_PASSWORD="my-password" tw agent connect --from bob --channel art --secret "<shared-secret>" --to alice --profile agent
+```
+
+Send to a named channel:
+
+```bash
+TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from alice" --profile agent
+```
+
+Send directly to a raw stream ID:
+
+```bash
+TW_PASSWORD="my-password" tw agent send --from alice 77aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa "debug message" --profile agent
+```
+
+Listen on a named channel:
+
+```bash
+TW_PASSWORD="my-password" tw agent listen --from bob --channel art --profile agent
+```
+
+Listen on a specific stream:
+
+```bash
+TW_PASSWORD="my-password" tw agent listen --from bob --stream 77aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --profile agent
+```
+
+Inspect local named bindings:
+
+```bash
+TW_PASSWORD="my-password" tw agent channels --from alice --profile agent --json
+```
+
+Remove an agent:
+
+```bash
+TW_PASSWORD="my-password" tw agent remove bob --profile agent
+```
+
+## Agent Quickstart
+
+This is the shortest end-to-end flow to start a conversation between two local agents.
+
+1. Create or reuse a wallet profile:
+
+```bash
+tw account create --profile agent
+```
+
+2. Create two agents:
+
+```bash
+TW_PASSWORD="my-password" tw agent create alice --profile agent
+TW_PASSWORD="my-password" tw agent create bob --profile agent
+```
+
+3. Create a named channel and copy the returned `secret` and `streamId`:
+
+```bash
+TW_PASSWORD="my-password" tw agent connect --from alice --channel art --to bob --profile agent
+```
+
+4. Bind the same channel from Bob using that secret:
+
+```bash
+TW_PASSWORD="my-password" tw agent connect --from bob --channel art --secret "<shared-secret>" --to alice --profile agent
+```
+
+5. Start a listener in one terminal:
+
+```bash
+TW_PASSWORD="my-password" tw agent listen --from bob --channel art --profile agent
+```
+
+6. Send from another terminal:
+
+```bash
+TW_PASSWORD="my-password" tw agent send --from alice --channel art "hello from alice" --profile agent
+```
+
+7. Bob's listener prints NDJSON when the message arrives:
+
+```json
+{
+  "type": "message",
+  "streamId": "77...",
+  "senderId": "0x...",
+  "eventId": "0x...",
+  "timestamp": 1709654400,
+  "content": "hello from alice"
+}
+```
+
+8. Inspect the local binding if you need the underlying stream:
+
+```bash
+TW_PASSWORD="my-password" tw agent channels --from alice --profile agent
+```
+
+For a single-command live verification, run the built-in smoke script:
+
+```bash
+cd packages/wallet
+TW_PASSWORD="my-password" bun run smoke:agent
+```
+
 ## Permissions List
 
 List all on-chain keys with summarized call/spend permissions:
@@ -417,6 +596,12 @@ Grant spend permission for daily USDC limit:
 echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit 100 --period day --profile agent --password-stdin --json
 ```
 
+For raw base units instead of human USDC amounts, use:
+
+```bash
+echo "my-password" | tw permissions grant agent-key --type spend --token USDC --spend-limit-raw 100000000 --period day --profile agent --password-stdin --json
+```
+
 ## Permissions Revoke
 
 Revoke one rule by stable rule id: