@xyo-network/wallet-xl1-cli 0.1.4

package/README.md

@@ -0,0 +1,329 @@
+# @xyo-network/wallet-xl1-cli
+
+[![npm][npm-badge]][npm-link]
+[![license][license-badge]][license-link]
+
+> Standalone XL1 wallet CLI for seed phrases, accounts, balances, transfers, payload signing, and wallet-signed JWTs.
+
+## Description
+
+`@xyo-network/wallet-xl1-cli` provides the `xl1-wallet` command. It is a focused XL1 wallet tool that can create or import wallets, derive accounts, manage network and contact metadata, sign transactions and payloads, send XL1, and mint or verify wallet-backed JWTs.
+
+The Aries CLI uses this same package for `aries wallet ...`, so the standalone and nested command surfaces stay aligned.
+
+## Installation
+
+### Prerequisites
+
+- Node.js `>=18.17.1`
+- A package manager such as `npm`, `pnpm`, or `yarn`
+
+### Global Install
+
+```sh
+npm install -g @xyo-network/wallet-xl1-cli
+xl1-wallet --help
+```
+
+### Run From This Repository
+
+```sh
+pnpm xy compile @xyo-network/wallet-xl1-cli
+pnpm xl1-wallet --help
+```
+
+## Quick Start
+
+Create a new wallet, derive an account, check its balance, then dry-run a transfer:
+
+```sh
+xl1-wallet create --label primary
+xl1-wallet account derive 0 --label main
+xl1-wallet balance 0
+xl1-wallet send 0x0000000000000000000000000000000000000000 1 --xl1 --dry-run
+```
+
+Import an existing recovery phrase instead:
+
+```sh
+xl1-wallet import --label primary --phrase "test test test test test test test test test test test junk"
+xl1-wallet use <wallet-id>
+```
+
+Use the same wallet CLI through Aries:
+
+```sh
+aries wallet balance 0
+aries wallet send 0x0000000000000000000000000000000000000000 1.25 --milli --json
+```
+
+## Wallet Storage
+
+Wallet CLI data is stored under `~/.xl1/wallet/cli` by default.
+
+| Variable | Purpose |
+| --- | --- |
+| `XL1_WALLET_HOME` | Overrides the wallet storage directory. |
+| `ARIES_WALLET_HOME` | Legacy fallback storage override. Used only when `XL1_WALLET_HOME` is not set. |
+| `ARIES_WALLET_PASSWORD` | Supplies the wallet password for non-interactive runs and tests. |
+
+Wallet seed phrases are encrypted at rest. Commands that need private key access prompt for the wallet password unless `ARIES_WALLET_PASSWORD` is set.
+
+`unlock` stores a short-lived encrypted session so follow-up commands can run without repeatedly prompting:
+
+```sh
+xl1-wallet unlock --ttl 900
+xl1-wallet lock
+```
+
+## Networks
+
+The CLI ships with XL1 mainnet and XL1 Sequence testnet network definitions.
+
+| ID | Label | RPC URL |
+| --- | --- | --- |
+| `xl1-mainnet` | `XL1 (Mainnet)` | `https://api.chain.xyo.network/rpc` |
+| `xl1-sequence` | `XL1 Sequence (Testnet)` | `https://beta.api.chain.xyo.network/rpc` |
+
+List and switch networks:
+
+```sh
+xl1-wallet network list
+xl1-wallet network use xl1-sequence
+```
+
+Add a local or custom network:
+
+```sh
+xl1-wallet network add local http://127.0.0.1:8080/rpc --label "Local XL1" --chain-id 0x1234
+xl1-wallet network use local
+```
+
+Remove a custom network:
+
+```sh
+xl1-wallet network remove local
+```
+
+## Commands
+
+### Wallets
+
+| Command | Description |
+| --- | --- |
+| `xl1-wallet create` | Create a new wallet. |
+| `xl1-wallet import` | Import a recovery phrase. |
+| `xl1-wallet export` | Print a wallet recovery phrase after password confirmation. |
+| `xl1-wallet list` | List wallets in the current wallet home. |
+| `xl1-wallet use <id>` | Set the active wallet. |
+| `xl1-wallet rename <id> <label>` | Rename a wallet. |
+| `xl1-wallet remove <id>` | Remove a wallet from local storage. |
+| `xl1-wallet reset` | Delete local wallet CLI data after confirmation. |
+| `xl1-wallet unlock` | Cache an encrypted wallet session for a limited time. |
+| `xl1-wallet lock` | Clear the cached wallet session. |
+| `xl1-wallet password change` | Change the active wallet password. |
+
+Examples:
+
+```sh
+xl1-wallet create --label primary
+xl1-wallet import --label recovery --phrase "..."
+xl1-wallet list
+xl1-wallet use <wallet-id>
+xl1-wallet export --id <wallet-id>
+```
+
+### Accounts
+
+| Command | Description |
+| --- | --- |
+| `xl1-wallet account derive <offset>` | Derive and store an account at an offset. |
+| `xl1-wallet account list` | List stored accounts for the active wallet. |
+| `xl1-wallet account show <offset>` | Show a derived account address. |
+| `xl1-wallet account label <offset> <label>` | Label an account. |
+| `xl1-wallet account remove <offset>` | Remove a stored account record. |
+
+Examples:
+
+```sh
+xl1-wallet account derive 0 --label main
+xl1-wallet account show 0
+xl1-wallet account list
+```
+
+### Balances And Transfers
+
+| Command | Description |
+| --- | --- |
+| `xl1-wallet balance [offset]` | Get the XL1 balance for an account offset. |
+| `xl1-wallet send <recipient> <amount>` | Send XL1 from an account in the active wallet to an address. |
+
+Examples:
+
+```sh
+xl1-wallet balance 0
+xl1-wallet send 0x1111111111111111111111111111111111111111 1 --xl1
+xl1-wallet send 0x1111111111111111111111111111111111111111 250 --micro --offset 0
+xl1-wallet send 0x1111111111111111111111111111111111111111 1.5 --milli --dry-run
+xl1-wallet send 0x1111111111111111111111111111111111111111 1000000000000000000 --atto --json
+```
+
+`send` supports `--dry-run`, which signs and validates the transaction plan without submitting it to the network.
+
+Use `--json` when scripting:
+
+```sh
+xl1-wallet send 0x1111111111111111111111111111111111111111 1 --xl1 --json
+```
+
+### Amount Units
+
+Amounts are converted to attoXL1 before signing.
+
+| Flag | Unit | Atto multiplier | Fractional input |
+| --- | --- | ---: | --- |
+| `--xl1` | XL1 | `1000000000000000000` | Yes |
+| `--milli` | milliXL1 | `1000000000000000` | Yes |
+| `--micro` | microXL1 | `1000000000000` | Yes |
+| `--nano` | nanoXL1 | `1000000000` | Yes |
+| `--pico` | picoXL1 | `1000000` | Yes |
+| `--femto` | femtoXL1 | `1000` | Yes |
+| `--atto` | attoXL1 | `1` | No |
+
+If no unit flag is supplied, `send` defaults to `--xl1`.
+
+### Contacts
+
+| Command | Description |
+| --- | --- |
+| `xl1-wallet contact add <address> <label>` | Save a contact. |
+| `xl1-wallet contact list` | List saved contacts. |
+| `xl1-wallet contact rename <address> <label>` | Rename a contact. |
+| `xl1-wallet contact remove <address>` | Remove a contact. |
+
+Examples:
+
+```sh
+xl1-wallet contact add 0x1111111111111111111111111111111111111111 treasury
+xl1-wallet contact list
+```
+
+### Transaction Files And Payloads
+
+Use `sign` to sign a payload JSON file directly:
+
+```sh
+xl1-wallet sign payload.json --output signed-payload.json
+```
+
+Use `tx sign` and `tx broadcast` for XL1 transaction files. This path supports on-chain payloads. Replace the `chain` value with the target XL1 chain id.
+
+```json
+{
+  "chain": "0x1234",
+  "nbf": 0,
+  "exp": 4102444800,
+  "onChainPayloads": [
+    {
+      "schema": "network.xyo.example",
+      "payload": {
+        "message": "hello xl1"
+      }
+    }
+  ]
+}
+```
+
+```sh
+xl1-wallet tx sign unsigned-transaction.json --output signed-transaction.json
+xl1-wallet tx broadcast signed-transaction.json
+```
+
+### JWTs
+
+Create, verify, and decode wallet-signed JWTs:
+
+```sh
+xl1-wallet jwt create --audience https://example.com --claim role=operator
+xl1-wallet jwt verify <token> --audience https://example.com
+xl1-wallet jwt decode <token>
+```
+
+Create a JWT from a payload file:
+
+```sh
+xl1-wallet jwt create \
+  --audience https://example.com \
+  --schema network.xyo.example \
+  --payload-file payload.json \
+  --output token.jwt
+```
+
+### Backup And Reset
+
+Backup exports and imports wallet CLI metadata such as contacts and address books. It does not replace saving wallet recovery phrases.
+
+```sh
+xl1-wallet backup export wallet-metadata.json
+xl1-wallet backup import wallet-metadata.json
+xl1-wallet reset
+```
+
+## Output And Automation
+
+Most commands print readable text by default. Commands intended for automation, such as `send`, also support JSON output:
+
+```sh
+xl1-wallet send 0x1111111111111111111111111111111111111111 1 --xl1 --json
+```
+
+For isolated test runs, set a temporary wallet home:
+
+```sh
+XL1_WALLET_HOME="$(mktemp -d)" ARIES_WALLET_PASSWORD="test-password" xl1-wallet create
+```
+
+## Development
+
+Compile the package:
+
+```sh
+pnpm xy compile @xyo-network/wallet-xl1-cli
+```
+
+Run the wallet CLI test suite:
+
+```sh
+pnpm exec vitest run packages/wallet-cli-lib/src/spec/*.spec.ts --project node
+```
+
+Smoke-test the built bin:
+
+```sh
+node packages/wallet-cli/dist/bin/wallet.mjs --help
+```
+
+## License
+
+LGPL-3.0-only
+
+[license-badge]: https://img.shields.io/npm/l/@xyo-network/wallet-xl1-cli.svg
+[license-link]: ./package.json
+[npm-badge]: https://img.shields.io/npm/v/@xyo-network/wallet-xl1-cli.svg
+[npm-link]: https://www.npmjs.com/package/@xyo-network/wallet-xl1-cli
+
+## Machine-readable output
+
+The read/listing commands accept `--json` to emit structured JSON instead of formatted text:
+
+```sh
+xl1-wallet list --json
+xl1-wallet account list --json
+xl1-wallet account show 0 --json
+xl1-wallet balance --json
+xl1-wallet network list --json
+xl1-wallet contact list --json
+xl1-wallet export --json
+```
+
+In `--json` mode the command prints only JSON to stdout (no decoration), so the output can be piped directly into `jq` or another parser.