ravensafe-cli 1.0.0

package/src/config/index.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const RVN_DONATION_ADDRESS = 'RYW4QozWJtmSipDAzXVJk2nyxRbY1fppbv';
+
+module.exports = {
+  branding: {
+    donations: {
+      rvn: {
+        address: RVN_DONATION_ADDRESS,
+        explorerUrl: `https://explorer.rvn.zelcore.io/address/${RVN_DONATION_ADDRESS}`,
+      },
+    },
+  },
+  ravencoin: {
+    explorerBaseUrl: 'https://explorer.rvn.zelcore.io/api',
+    feeRateSatPerByte: 1000,
+    dustSats: 546,
+    defaultChangeIndex: 0,
+    scan: {
+      balanceReceivingMaxIndex: 50,
+      balanceChangeMaxIndex: 20,
+      receiveMaxIndex: 100,
+    },
+  },
+};

package/src/core/address.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const bitcoin = require('bitcoinjs-lib');
+const secp256k1 = require('tiny-secp256k1');
+const { ravencoinMainnet } = require('./network');
+
+function normalizePublicKey(publicKeyHex) {
+  if (typeof publicKeyHex !== 'string' || publicKeyHex.trim() === '') {
+    throw new Error('Expected a hex-encoded public key from Ledger');
+  }
+
+  const normalized = publicKeyHex.trim().toLowerCase();
+  if (!/^[0-9a-f]+$/.test(normalized) || normalized.length % 2 !== 0) {
+    throw new Error('Ledger returned a public key that is not valid hex');
+  }
+
+  const publicKey = Buffer.from(normalized, 'hex');
+  if (!secp256k1.isPoint(publicKey)) {
+    throw new Error('Ledger returned an invalid secp256k1 public key');
+  }
+
+  return publicKey;
+}
+
+function compressPublicKey(publicKey) {
+  if (!Buffer.isBuffer(publicKey)) {
+    throw new Error('Expected a public key buffer');
+  }
+
+  if (!secp256k1.isPoint(publicKey)) {
+    throw new Error('Ledger returned an invalid secp256k1 public key');
+  }
+
+  if (publicKey.length === 33 && (publicKey[0] === 0x02 || publicKey[0] === 0x03)) {
+    return publicKey;
+  }
+
+  if (publicKey.length === 65 && publicKey[0] === 0x04) {
+    const x = publicKey.subarray(1, 33);
+    const y = publicKey.subarray(33, 65);
+    const prefix = (y[31] & 1) === 0 ? 0x02 : 0x03;
+
+    return Buffer.concat([Buffer.from([prefix]), x]);
+  }
+
+  throw new Error('Ledger returned a public key with an unsupported encoding');
+}
+
+function deriveRvnP2pkhAddress(publicKeyHex) {
+  const publicKey = compressPublicKey(normalizePublicKey(publicKeyHex));
+  const payment = bitcoin.payments.p2pkh({
+    pubkey: publicKey,
+    network: ravencoinMainnet,
+  });
+
+  if (!payment.address) {
+    throw new Error('Could not derive a Ravencoin P2PKH address');
+  }
+
+  return payment.address;
+}
+
+module.exports = {
+  compressPublicKey,
+  deriveRvnP2pkhAddress,
+  normalizePublicKey,
+};

package/src/core/network.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const ravencoinMainnet = Object.freeze({
+  messagePrefix: '\x16Raven Signed Message:\n',
+  bech32: 'rc',
+  pubKeyHash: 60,
+  scriptHash: 122,
+  wif: 128,
+});
+
+module.exports = {
+  ravencoinMainnet,
+};

package/src/core/scan.js

@@ -0,0 +1,218 @@
+'use strict';
+
+const { createExplorer } = require('../explorer/zelcore');
+const {
+  listLedgerAddressRequests,
+  listLedgerAddresses,
+} = require('../ledger');
+
+const SATS_PER_RVN = 100000000n;
+
+function formatRvn(sats) {
+  if (sats === null || sats === undefined) {
+    return 'n/a';
+  }
+
+  const negative = sats < 0n;
+  const absolute = negative ? -sats : sats;
+  const whole = absolute / SATS_PER_RVN;
+  const fraction = (absolute % SATS_PER_RVN).toString().padStart(8, '0');
+  const trimmedFraction = fraction.replace(/0+$/, '');
+  const value = trimmedFraction === '' ? whole.toString() : `${whole}.${trimmedFraction}`;
+
+  return `${negative ? '-' : ''}${value} RVN`;
+}
+
+function sumUtxos(utxos, predicate) {
+  return utxos
+    .filter(predicate)
+    .reduce((total, utxo) => total + utxo.valueSats, 0n);
+}
+
+async function readAddressBalance(explorer, address) {
+  const utxos = await explorer.getUtxos(address);
+  let balance = null;
+  let balanceError = null;
+
+  try {
+    balance = await explorer.getAddressBalance(address);
+  } catch (error) {
+    balanceError = error;
+  }
+
+  const confirmedFromUtxos = sumUtxos(utxos, utxo => utxo.confirmations > 0);
+  const unconfirmedFromUtxos = sumUtxos(utxos, utxo => utxo.confirmations <= 0);
+
+  return {
+    confirmedSats: balance ? balance.confirmedSats : confirmedFromUtxos,
+    unconfirmedSats: balance && balance.unconfirmedSats !== null
+      ? balance.unconfirmedSats
+      : unconfirmedFromUtxos,
+    utxos,
+    utxoCount: utxos.length,
+    txAppearances: balance ? balance.txAppearances : null,
+    unconfirmedTxAppearances: balance ? balance.unconfirmedTxAppearances : null,
+    balanceSource: balance ? 'address' : 'utxos',
+    balanceError,
+  };
+}
+
+async function readAddressUsage(explorer, address) {
+  const balance = await explorer.getAddressBalance(address);
+
+  return {
+    confirmedSats: balance.confirmedSats,
+    unconfirmedSats: balance.unconfirmedSats,
+    utxos: [],
+    utxoCount: 0,
+    txAppearances: balance.txAppearances,
+    unconfirmedTxAppearances: balance.unconfirmedTxAppearances,
+    balanceSource: 'address',
+    balanceError: null,
+  };
+}
+
+function buildScanErrorResult(error) {
+  return {
+    error,
+    expectedContext: null,
+    hidDetected: false,
+    hidDeviceCount: 0,
+    app: null,
+    warnings: [],
+    scanResults: [],
+    receivingConfirmedSats: 0n,
+    changeConfirmedSats: 0n,
+    grandTotalConfirmedSats: 0n,
+    totalUtxoCount: 0,
+    allMatch: false,
+  };
+}
+
+async function resolveExplorer(options) {
+  let explorer;
+  try {
+    explorer = options.explorer || createExplorer();
+  } catch (error) {
+    return {
+      explorer: null,
+      error,
+    };
+  }
+
+  return {
+    explorer,
+    error: null,
+  };
+}
+
+async function scanLedgerResultWithExplorer(ledgerResult, explorer) {
+  const result = {
+    expectedContext: ledgerResult.expectedContext,
+    hidDetected: ledgerResult.hidDetected,
+    hidDeviceCount: ledgerResult.hidDeviceCount,
+    app: ledgerResult.app,
+    warnings: ledgerResult.warnings,
+    scanResults: [],
+    receivingConfirmedSats: 0n,
+    changeConfirmedSats: 0n,
+    grandTotalConfirmedSats: 0n,
+    totalUtxoCount: 0,
+    allMatch: false,
+    error: ledgerResult.error,
+  };
+
+  if (ledgerResult.error) {
+    return result;
+  }
+
+  for (const addressItem of ledgerResult.addressResults) {
+    const scanItem = {
+      chain: addressItem.chain,
+      index: addressItem.index,
+      path: addressItem.path,
+      rvnAddress: addressItem.rvnAddress,
+      ledgerAddress: addressItem.ledgerAddress,
+      matchesLedger: addressItem.matchesLedger,
+      confirmedSats: null,
+      unconfirmedSats: null,
+      utxos: [],
+      utxoCount: 0,
+      txAppearances: null,
+      ok: false,
+      error: null,
+    };
+
+    if (!addressItem.ok) {
+      scanItem.error = addressItem.error;
+      result.scanResults.push(scanItem);
+      continue;
+    }
+
+    if (!addressItem.matchesLedger) {
+      scanItem.error = new Error('Local RVN address does not match Ledger-returned address.');
+      result.scanResults.push(scanItem);
+      continue;
+    }
+
+    try {
+      const balance = await readAddressBalance(explorer, addressItem.rvnAddress);
+      scanItem.confirmedSats = balance.confirmedSats;
+      scanItem.unconfirmedSats = balance.unconfirmedSats;
+      scanItem.utxos = balance.utxos;
+      scanItem.utxoCount = balance.utxoCount;
+      scanItem.txAppearances = balance.txAppearances;
+      scanItem.unconfirmedTxAppearances = balance.unconfirmedTxAppearances;
+      scanItem.balanceSource = balance.balanceSource;
+      scanItem.balanceError = balance.balanceError;
+      scanItem.ok = true;
+    } catch (error) {
+      scanItem.error = error;
+    }
+
+    result.scanResults.push(scanItem);
+  }
+
+  result.receivingConfirmedSats = result.scanResults
+    .filter(item => item.ok && item.chain === 'receiving')
+    .reduce((total, item) => total + item.confirmedSats, 0n);
+  result.changeConfirmedSats = result.scanResults
+    .filter(item => item.ok && item.chain === 'change')
+    .reduce((total, item) => total + item.confirmedSats, 0n);
+  result.grandTotalConfirmedSats = result.receivingConfirmedSats + result.changeConfirmedSats;
+  result.totalUtxoCount = result.scanResults
+    .filter(item => item.ok)
+    .reduce((total, item) => total + item.utxoCount, 0);
+  result.allMatch = result.scanResults.length > 0 &&
+    result.scanResults.every(item => item.ok && item.matchesLedger);
+
+  return result;
+}
+
+async function scanLedgerAddressRequests(options = {}) {
+  const resolved = await resolveExplorer(options);
+  if (resolved.error) {
+    return buildScanErrorResult(resolved.error);
+  }
+
+  const ledgerResult = await listLedgerAddressRequests(options);
+  return scanLedgerResultWithExplorer(ledgerResult, resolved.explorer);
+}
+
+async function scanLedgerAddresses(options = {}) {
+  const resolved = await resolveExplorer(options);
+  if (resolved.error) {
+    return buildScanErrorResult(resolved.error);
+  }
+
+  const ledgerResult = await listLedgerAddresses(options);
+  return scanLedgerResultWithExplorer(ledgerResult, resolved.explorer);
+}
+
+module.exports = {
+  formatRvn,
+  readAddressBalance,
+  readAddressUsage,
+  scanLedgerAddressRequests,
+  scanLedgerAddresses,
+};

package/src/core/session-cache.js

@@ -0,0 +1,158 @@
+'use strict';
+
+function cacheKey(chain, index) {
+  return `${chain}:${index}`;
+}
+
+function cloneUtxos(utxos) {
+  if (!Array.isArray(utxos)) {
+    return [];
+  }
+
+  return utxos.map(utxo => ({
+    ...utxo,
+  }));
+}
+
+function normalizeSats(value) {
+  return typeof value === 'bigint' ? value : 0n;
+}
+
+class SessionAddressCache {
+  constructor() {
+    this.addresses = new Map();
+  }
+
+  get size() {
+    return this.addresses.size;
+  }
+
+  hasAny() {
+    return this.addresses.size > 0;
+  }
+
+  clear() {
+    this.addresses.clear();
+  }
+
+  key(chain, index) {
+    return cacheKey(chain, index);
+  }
+
+  get(chain, index) {
+    return this.addresses.get(this.key(chain, index)) || null;
+  }
+
+  set(item) {
+    const address = item.rvnAddress || item.address;
+    const utxos = cloneUtxos(item.utxos);
+    const entry = {
+      chain: item.chain,
+      index: item.index,
+      path: item.path,
+      address,
+      rvnAddress: address,
+      ledgerAddress: item.ledgerAddress || null,
+      matchesLedger: item.matchesLedger !== false,
+      confirmedSats: normalizeSats(item.confirmedSats),
+      unconfirmedSats: normalizeSats(item.unconfirmedSats),
+      utxos,
+      utxoCount: Number.isSafeInteger(item.utxoCount) ? item.utxoCount : utxos.length,
+      txAppearances: Number.isSafeInteger(item.txAppearances) ? item.txAppearances : null,
+      unconfirmedTxAppearances: Number.isSafeInteger(item.unconfirmedTxAppearances)
+        ? item.unconfirmedTxAppearances
+        : null,
+      balanceSource: item.balanceSource || null,
+      balanceError: item.balanceError || null,
+      ok: item.ok !== false,
+      error: item.error || null,
+      refreshedAt: Date.now(),
+    };
+
+    this.addresses.set(this.key(entry.chain, entry.index), entry);
+    return entry;
+  }
+
+  upsertScanItem(item) {
+    if (!item || !item.ok || !item.matchesLedger || !item.rvnAddress) {
+      return null;
+    }
+
+    return this.set(item);
+  }
+
+  updateBalance(chain, index, balance) {
+    const existing = this.get(chain, index);
+    if (!existing) {
+      throw new Error(`Cannot refresh uncached address ${chain}:${index}.`);
+    }
+
+    return this.set({
+      ...existing,
+      confirmedSats: balance.confirmedSats,
+      unconfirmedSats: balance.unconfirmedSats,
+      utxos: balance.utxos,
+      utxoCount: balance.utxoCount,
+      txAppearances: balance.txAppearances,
+      unconfirmedTxAppearances: balance.unconfirmedTxAppearances,
+      balanceSource: balance.balanceSource,
+      balanceError: balance.balanceError,
+      ok: true,
+      error: null,
+    });
+  }
+
+  updateUsage(chain, index, balance) {
+    const existing = this.get(chain, index);
+    if (!existing) {
+      throw new Error(`Cannot refresh uncached address ${chain}:${index}.`);
+    }
+
+    return this.set({
+      ...existing,
+      confirmedSats: balance.confirmedSats,
+      unconfirmedSats: balance.unconfirmedSats,
+      txAppearances: balance.txAppearances,
+      unconfirmedTxAppearances: balance.unconfirmedTxAppearances,
+      balanceSource: balance.balanceSource,
+      balanceError: balance.balanceError,
+      ok: true,
+      error: null,
+    });
+  }
+
+  values() {
+    return [...this.addresses.values()];
+  }
+
+  toScanItem(entry) {
+    return {
+      chain: entry.chain,
+      index: entry.index,
+      path: entry.path,
+      rvnAddress: entry.address,
+      ledgerAddress: entry.ledgerAddress,
+      matchesLedger: entry.matchesLedger,
+      confirmedSats: entry.confirmedSats,
+      unconfirmedSats: entry.unconfirmedSats,
+      utxos: cloneUtxos(entry.utxos),
+      utxoCount: entry.utxoCount,
+      txAppearances: entry.txAppearances,
+      unconfirmedTxAppearances: entry.unconfirmedTxAppearances,
+      balanceSource: entry.balanceSource,
+      balanceError: entry.balanceError,
+      ok: entry.ok,
+      error: entry.error,
+    };
+  }
+}
+
+function createSessionCache() {
+  return new SessionAddressCache();
+}
+
+module.exports = {
+  SessionAddressCache,
+  cacheKey,
+  createSessionCache,
+};