ravensafe-cli 1.0.0

package/Docs.md

@@ -0,0 +1,262 @@
+# RavenSafe CLI Technical Docs
+
+This document contains implementation and advanced usage details for RavenSafe CLI. Normal users should start with the guided workflow in [README.md](README.md).
+
+## Project Architecture
+
+- `RavenSafe.js` is the public executable entry point.
+- `cli.js` is a small compatibility shim.
+- `src/RavenSafe.js` wires the guided mode and command-mode actions.
+- `src/interactive/` contains the guided wallet UI and menu flow.
+- `src/ledger/` handles Ledger transport, app checks, public-key requests, and address verification.
+- `src/core/` contains shared scan, address, network, and session-cache helpers.
+- `src/explorer/zelcore.js` adapts Zelcore explorer responses for balances, UTXOs, raw transactions, and broadcast.
+- `src/tx/` contains transaction planning and Ledger signing support.
+- `src/config/index.js` contains public runtime defaults and branding constants.
+- `tools/probe-ledger.js` is a diagnostic public-key export probe.
+
+## Runtime Defaults
+
+Current public defaults live in `src/config/index.js`:
+
+```js
+ravencoin: {
+  explorerBaseUrl: 'https://explorer.rvn.zelcore.io/api',
+  feeRateSatPerByte: 1000,
+  dustSats: 546,
+  defaultChangeIndex: 0,
+  scan: {
+    balanceReceivingMaxIndex: 50,
+    balanceChangeMaxIndex: 20,
+    receiveMaxIndex: 100
+  }
+}
+```
+
+Branding constants also live in `src/config/index.js`, including the RVN donation address and explorer link used by the startup UI and Support / Donate menu.
+
+## Ledger Derivation Paths
+
+RavenSafe CLI uses Ravencoin coin type `175`.
+
+Receiving addresses:
+
+```text
+m/44'/175'/0'/0/index
+```
+
+Change addresses:
+
+```text
+m/44'/175'/0'/1/index
+```
+
+The diagnostic probe reads these paths:
+
+```text
+m/44'/175'/0'/0/0
+m/44'/175'/0'/0/1
+m/44'/175'/0'/0/2
+m/44'/175'/175'/0/0
+```
+
+For each path, the probe prints the derivation path, public key, chain code if returned by the Ledger, Ledger-returned address if available, and locally derived Ravencoin mainnet P2PKH address.
+
+## Explorer Adapter
+
+The explorer backend is isolated in `src/explorer/zelcore.js`.
+
+Expected Zelcore endpoints:
+
+- `GET /addr/{address}/?noTxList=1` for confirmed and unconfirmed balance.
+- `GET /txs?address={address}&pageNum={page}` for transaction pages used to construct UTXOs.
+- `GET /rawtx/{txid}` for previous raw transaction hex required by Ledger signing.
+- `POST https://explorer.rvn.zelcore.io/api/tx/send` for signed raw transaction broadcast with JSON body `{ "rawtx": rawtx }`.
+
+Zelcore `/txs` returns transaction pages, so RavenSafe CLI constructs UTXOs by selecting unspent `vout` entries whose `scriptPubKey.addresses` contains the scanned address. Previous raw transaction hex is fetched from Zelcore `/rawtx/{txid}` and is not reconstructed.
+
+## Guided Transaction Flow
+
+Guided Send RVN:
+
+1. Prompts for destination, amount, and fee choice.
+2. Reuses the current session scan cache when available.
+3. Checks the quick scan range if needed.
+4. Selects suitable confirmed UTXOs.
+5. Shows a human-readable summary with amount, destination, source, estimated fee, and change details.
+6. Requires typing exactly `SIGN`.
+7. Calls Ledger signing only after terminal confirmation.
+8. Requires approval on the Ledger device.
+9. Broadcasts automatically after successful guided signing.
+10. Prints the TXID and explorer link on success.
+
+If signing fails or the Ledger rejects the request, nothing is broadcast.
+
+## Scan Ranges
+
+Guided balance scan presets:
+
+- Quick scan: receiving indexes `0-15`, change indexes `0-5`.
+- Standard scan: receiving indexes `0-40`, change indexes `0-10`.
+- Deep scan: receiving indexes `0-70`, change indexes `0-30`.
+- Custom scan: accepts ranges such as `0-30`, `3-19`, or `100-150`.
+
+Receive RVN searches receiving addresses and checks additional receiving indexes only when needed, up to the configured receive maximum.
+
+## Advanced Commands
+
+Run the command help:
+
+```sh
+node RavenSafe.js --help
+```
+
+### Address Listing
+
+List Ledger-derived receiving addresses:
+
+```sh
+node RavenSafe.js addresses --start 0 --count 10 --app ravencoin
+```
+
+Options:
+
+- `--start <number>` defaults to `0`.
+- `--count <number>` defaults to `10` and must be between `1` and `100`.
+- `--app <context>` defaults to `ravencoin`; supported contexts are `current`, `ravencoin`, and `bitcoin`.
+
+The command prints index, derivation path, locally derived RVN address, Ledger-returned address, and match status.
+
+### Balance Scan
+
+Scan receiving addresses:
+
+```sh
+node RavenSafe.js scan --chain receiving --start 0 --count 10 --app ravencoin
+```
+
+Scan both receiving and change chains:
+
+```sh
+node RavenSafe.js scan --chain both --start 0 --count 3 --app ravencoin
+```
+
+Options:
+
+- `--start <number>` defaults to `0`.
+- `--count <number>` defaults to `10` and must be between `1` and `200`.
+- `--chain <receiving|change|both>` defaults to `receiving`.
+- `--app <context>` defaults to `ravencoin`.
+
+The scan command reads public keys from the Ledger, derives RVN addresses locally, checks Ledger-returned address matches, fetches public balance and UTXO data, and prints totals. It does not sign, send, build transactions, or broadcast.
+
+### Dry-Run Send Planner
+
+Prepare a transaction plan from one Ledger-derived source address:
+
+```sh
+node RavenSafe.js send --from-chain receiving --from-index 0 --to <RVN_ADDRESS> --amount 1
+```
+
+Options:
+
+- `--from-chain <receiving|change>` defaults to `receiving`.
+- `--from-index <number>` is required.
+- `--to <RVN_ADDRESS>` is required and must be a Ravencoin mainnet P2PKH or P2SH address.
+- `--amount <RVN_AMOUNT>` is required and must be greater than `0`.
+- `--fee-rate <sat_per_byte>` defaults to `config.ravencoin.feeRateSatPerByte`.
+- `--change-chain <receiving|change>` defaults to `change`.
+- `--change-index <number>` defaults to `config.ravencoin.defaultChangeIndex`.
+- `--app <context>` defaults to `ravencoin`.
+- `--dry-run` is enabled by default.
+- `--sign` asks for `SIGN` confirmation and calls Ledger signing after review.
+
+Without `--sign`, the command prints a dry-run plan and does not sign or broadcast.
+
+With `--sign`, the command signs only after exact terminal confirmation and Ledger approval. Command-mode signing prints the signed raw transaction and locally derived txid, but does not broadcast.
+
+### Manual Broadcast
+
+Broadcast raw signed transaction hex directly:
+
+```sh
+node RavenSafe.js broadcast --rawtx <SIGNED_RAW_TX_HEX>
+```
+
+Or read raw hex from a local file:
+
+```sh
+node RavenSafe.js broadcast --file signed-tx.hex
+```
+
+Rules:
+
+- Exactly one of `--rawtx` or `--file` is required.
+- The raw transaction must be non-empty even-length hex.
+- The CLI decodes the transaction locally and prints txid, estimated bytes, input count, and output count.
+- The CLI prints an irreversible-broadcast warning.
+- Broadcasting only happens after typing exactly `BROADCAST`.
+- If confirmation is not exact, nothing is broadcast.
+
+### Ledger Probe
+
+Run the diagnostic probe:
+
+```sh
+node tools/probe-ledger.js --app ravencoin
+```
+
+The probe reads public information only. It does not sign, send, or broadcast.
+
+## Security Model
+
+- The Ledger is the only signer.
+- Recovery phrases and private keys are never requested.
+- Addresses are derived locally from Ledger-returned public keys.
+- Ledger-returned addresses are compared with locally derived RVN addresses.
+- Balance and UTXO discovery use public explorer data.
+- Signing requires explicit terminal confirmation and device approval.
+- Guided-mode broadcast only follows successful guided signing.
+- Command-mode broadcast requires exact `BROADCAST` confirmation.
+
+## Troubleshooting
+
+Ledger cannot be found:
+
+- Confirm the Ledger is connected over USB.
+- Unlock the Ledger.
+- Close Ledger Live and other wallet software.
+- Open the Ravencoin app on the Ledger.
+
+Ledger app mismatch:
+
+- Open the Ravencoin app and retry.
+- Use `--app ravencoin` for normal RVN operations.
+- Use `--app current` only for diagnostics.
+
+Explorer errors:
+
+- Check internet connectivity.
+- Retry later if the public explorer is unavailable.
+- Confirm the endpoint in `src/config/index.js`.
+
+Insufficient funds:
+
+- Run guided balance scan first.
+- Try a broader scan range.
+- Check whether funds are on a change address.
+- Test with a smaller amount.
+
+Signing rejected:
+
+- Review the Ledger screen carefully.
+- Rejecting on the device is safe; nothing is broadcast.
+- Restart guided mode and retry only if the transaction details are correct.
+
+## Developer Notes
+
+- Keep guided mode as the primary user path.
+- Keep advanced command behavior conservative.
+- Do not couple informational screens to Ledger, scan, signing, send, or broadcast paths.
+- Keep public defaults and branding constants centralized in `src/config/index.js`.
+- Use safe checks for docs-only changes; do not run Ledger, scan, sign, or broadcast flows unless intentionally testing those paths.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Web3Dev-ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# RavenSafe CLI
+
+![RavenSafe CLI brand identity](assets/ravensafe-cli-brand.png)
+
+RavenSafe CLI is a guided Ravencoin wallet helper for Ledger devices. It helps you scan balances, receive RVN, send RVN, sign on the Ledger, and broadcast through a focused terminal workflow without exposing your recovery phrase.
+
+## Why This Exists
+
+RavenSafe CLI was built after practical issues sending RVN with Electrum-RVN while using a Ledger device. Electrum-RVN is an important community project, but its GitHub repository is now archived and read-only, so some users may need a simpler working path for Ledger-based RVN operations.
+
+This project is not a replacement for every wallet use case. It is a focused Ledger/RVN helper for users who want a guided flow for scanning, receiving, sending, signing, and broadcasting RVN.
+
+Reference: <https://github.com/Electrum-RVN-SIG/electrum-ravencoin/>
+
+## Core Safety Promise
+
+- RavenSafe CLI never asks for your Ledger recovery phrase.
+- RavenSafe CLI never imports private keys.
+- The Ledger remains the signer.
+- Sending requires explicit confirmation in the terminal and approval on the Ledger.
+- Always verify the destination address and amount on the Ledger screen.
+- Use at your own risk.
+- Test with a small amount first.
+
+## Features
+
+- Guided wallet menu for normal use.
+- Balance scanning for Ledger-derived RVN addresses.
+- Receive-address discovery using receiving addresses only.
+- Optional on-device verification for receive addresses.
+- Guided RVN sending with a clear summary before signing.
+- Automatic broadcast after a successful guided send.
+- Help and safety notes inside the CLI.
+- Informational Support / Donate screen.
+
+## Requirements
+
+- Node.js
+- A Ledger device with the Ravencoin app installed
+- USB access to the Ledger
+- Internet access for public Ravencoin explorer lookups and broadcasts
+
+Before using guided mode:
+
+1. Close Ledger Live.
+2. Connect and unlock the Ledger.
+3. Open the Ravencoin app on the Ledger.
+
+## Quick Start
+
+Run without installing:
+
+```sh
+npx ravensafe-cli
+```
+
+Or install globally:
+
+```sh
+npm install -g ravensafe-cli
+```
+
+Then start the guided CLI:
+
+```sh
+ravensafe
+```
+
+The package also exposes the `ravensafe-cli` command:
+
+```sh
+ravensafe-cli
+```
+
+For local development from a cloned repository:
+
+```sh
+npm install
+npm start
+```
+
+You can also run the local entry point directly:
+
+```sh
+node RavenSafe.js
+```
+
+## Guided Usage
+
+The normal workflow starts with:
+
+```sh
+ravensafe
+```
+
+The guided menu provides:
+
+```text
+1. Scan wallet balances
+2. Send RVN
+3. Receive RVN
+4. Help / safety notes
+5. Support / Donate
+6. Exit
+```
+
+### 1. Scan Wallet Balances
+
+Checks Ledger-derived receiving and change addresses, reads public blockchain data, and shows balances and UTXO counts. This does not sign, send, or broadcast anything.
+
+### 2. Send RVN
+
+Guides you through destination, amount, fee choice, transaction review, Ledger signing, and broadcast. Nothing is signed until you type `SIGN`, and the Ledger must still approve the transaction.
+
+### 3. Receive RVN
+
+Finds an unused receiving address and displays it. You can optionally verify the address on the Ledger screen.
+
+### 4. Help / Safety Notes
+
+Shows reminders for safe Ledger use, including keeping the Ravencoin app open and verifying transaction details before approval.
+
+### 5. Support / Donate
+
+Shows the RVN donation address and explorer link. This option is informational only and does not trigger Ledger access, scanning, signing, sending, or broadcasting.
+
+## Safety Notes
+
+- Never type your recovery phrase into any computer, website, terminal, wallet, or support chat.
+- Confirm the Ledger screen matches the amount and destination you intended.
+- Start with a small test send before moving larger balances.
+- Treat broadcast as final once confirmed by the network.
+- Keep Ledger Live and other wallet apps closed while RavenSafe CLI is using the Ledger.
+
+## Limitations
+
+- RavenSafe CLI is intentionally focused on Ledger-backed RVN wallet operations.
+- It expects standard Ledger-derived Ravencoin addresses.
+- It depends on the configured public explorer being reachable.
+- It is a command-line tool, not a full graphical wallet.
+- It does not manage recovery phrases, private keys, staking, assets, or exchange features.
+
+## Support / Donate
+
+RVN donations are optional:
+
+```text
+RYW4QozWJtmSipDAzXVJk2nyxRbY1fppbv
+```
+
+Explorer:
+
+```text
+https://explorer.rvn.zelcore.io/address/RYW4QozWJtmSipDAzXVJk2nyxRbY1fppbv
+```
+
+## Advanced Commands
+
+Guided mode is the recommended path:
+
+```sh
+ravensafe
+```
+
+Advanced commands still exist for users who need command-mode address listing, scanning, dry-run send planning, signing, manual broadcast, or Ledger probing:
+
+```sh
+ravensafe --help
+```
+
+For technical details, command examples, derivation paths, explorer endpoints, transaction flow, and troubleshooting, see [Docs.md](Docs.md).

package/RavenSafe.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('./src/RavenSafe');

package/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('./RavenSafe');

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ravensafe-cli",
+  "version": "1.0.0",
+  "description": "Guided Ravencoin Ledger wallet operations from the command line.",
+  "main": "RavenSafe.js",
+  "bin": {
+    "ravensafe": "./RavenSafe.js",
+    "ravensafe-cli": "./RavenSafe.js"
+  },
+  "files": [
+    "RavenSafe.js",
+    "cli.js",
+    "src/",
+    "tools/",
+    "README.md",
+    "Docs.md",
+    "LICENSE",
+    "assets/ravensafe-cli-brand.png"
+  ],
+  "scripts": {
+    "start": "node RavenSafe.js",
+    "check": "node --check RavenSafe.js && node --check cli.js && find src tools -name '*.js' -print0 | xargs -0 -n 1 node --check",
+    "test": "npm run check",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ELHARAKA/RavenSafe-CLI.git"
+  },
+  "keywords": [
+    "ravencoin",
+    "rvn",
+    "ledger",
+    "cli",
+    "wallet",
+    "hardware-wallet"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ELHARAKA/RavenSafe-CLI/issues"
+  },
+  "homepage": "https://github.com/ELHARAKA/RavenSafe-CLI#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ledgerhq/hw-app-btc": "^10.22.1",
+    "@ledgerhq/hw-transport-node-hid": "^6.33.2",
+    "axios": "^1.16.1",
+    "bitcoinjs-lib": "^7.0.1",
+    "commander": "^14.0.3",
+    "tiny-secp256k1": "^2.2.4"
+  }
+}