@mingderwang/wallet 0.1.0 → 0.1.2

package/dist/index.js

@@ -79,6 +79,10 @@ function randomBytesHex(len = 32) {
 }
 
 // src/index.ts
+function processEnvPassword() {
+  const v = process.env.WALLET_PASSWORD ?? process.env.XSIFT_WALLET_PASSWORD;
+  return v && v.length > 0 ? v : undefined;
+}
 var NETWORKS = {
   ethereumMainnet: { networkId: "ethereum-mainnet", chainId: 1 },
   ethereumSepolia: { networkId: "ethereum-sepolia", chainId: 11155111 },
@@ -162,6 +166,7 @@ export {
   rpcUrl,
   readKeystore,
   randomBytesHex,
+  processEnvPassword,
   loadWallet,
   importWallet,
   getBalances,

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@mingderwang/wallet",
-  "version": "0.1.0",
-  "description": "Encrypted Ethereum keystore (scrypt + AES-256-GCM) and wallet signing helpers.",
+  "version": "0.1.2",
+  "description": "Ethereum wallet + encrypted keystore helpers (scrypt + AES-256-GCM) built on ethers v6. Ships a `wallet` CLI.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "wallet": "./dist/cli.js"
+  },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
-  "files": ["dist", "README.md"],
+  "files": ["dist", "src", "README.md"],
   "engines": {
     "node": ">=18.0.0"
   },

package/src/cli.ts

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Wallet } from 'ethers';
+import {
+  createWallet as generateWallet,
+  importWallet,
+  loadWallet,
+  encryptPrivateKey,
+  saveKeystore,
+  readKeystore,
+  deleteFile,
+  getBalances,
+  formatAmount,
+  USDC,
+  processEnvPassword,
+  type EncryptedKeystore,
+} from './index';
+
+const VERSION = '0.1.2';
+
+const C = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  gray: (s: string) => `\x1b[90m${s}\x1b[0m`,
+};
+
+const hasEnvPassword = () => typeof processEnvPassword() === 'string';
+
+function prompt(question: string): Promise<string> {
+  process.stderr.write(question);
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    stdin.resume();
+    stdin.once('data', (buf: Buffer) => {
+      stdin.pause();
+      const v = buf.toString().replace(/\r?\n$/, '');
+      process.stderr.write('');
+      resolve(v);
+    });
+  });
+}
+
+function promptHidden(question: string): Promise<string> {
+  if (hasEnvPassword()) {
+    process.stderr.write(`${question}[using WALLET_PASSWORD env]\n`);
+    return Promise.resolve(processEnvPassword() as string);
+  }
+  process.stderr.write(question);
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const wasRaw = !!stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    let input = '';
+    const onData = (buf: Buffer) => {
+      const code = buf[0];
+      if (code === 3) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.stderr.write('\n');
+        process.exit(130);
+      }
+      if (code === 13 || code === 10) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.stderr.write('\n');
+        resolve(input);
+        return;
+      }
+      if (code === 127 || code === 8) {
+        input = input.slice(0, -1);
+        return;
+      }
+      input += buf.toString('utf8');
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function defaultPath(): string {
+  return process.env.WALLET_PATH ?? join(homedir(), '.wallet', 'wallet.json');
+}
+
+function walletPath(opts: Record<string, string>): string {
+  return opts.path ?? defaultPath();
+}
+
+function printCreated(wallet: Wallet, path: string): void {
+  console.log('');
+  console.log(`  ${C.bold('Wallet created')}`);
+  console.log('  ' + '─'.repeat(46));
+  console.log(`  ${C.green('Address')}   ${wallet.address}`);
+  console.log(`  ${C.gray('Keystore')}  ${path}`);
+  console.log('');
+  console.log(`  ${C.yellow('Keep the password safe — it signs payments.')}`);
+  console.log(`  ${C.yellow('Back up the keystore file; losing both loses the funds.')}`);
+}
+
+async function readPasswordTwice(action: string): Promise<string> {
+  for (;;) {
+    const p1 = await promptHidden(`New keystore password (${action}): `);
+    if (p1.length < 8) {
+      console.log(C.yellow('Password must be at least 8 characters.'));
+      continue;
+    }
+    const p2 = await promptHidden('Confirm password: ');
+    if (p1 !== p2) {
+      console.log(C.red('Passwords do not match. Try again.'));
+      continue;
+    }
+    return p1;
+  }
+}
+
+async function loadUnlocked(path: string, action: string): Promise<{ wallet: Wallet; keystore: EncryptedKeystore }> {
+  if (!existsSync(path)) {
+    console.log(C.red('No wallet found at ' + path) + ' — run ' + C.bold('wallet create') + ' first.');
+    process.exit(2);
+  }
+  const keystore = readKeystore(path);
+  for (let attempt = 1; ; attempt++) {
+    const password = await promptHidden(`Keystore password (${action}): `);
+    try {
+      const wallet = loadWallet(keystore, password);
+      return { wallet, keystore };
+    } catch {
+      if (attempt >= 3) {
+        console.log(C.red('Incorrect password. Exiting.'));
+        process.exit(1);
+      }
+      console.log(C.red('Incorrect password, try again.'));
+    }
+  }
+}
+
+function guardNoWallet(path: string): void {
+  if (existsSync(path)) {
+    console.log(C.yellow(`A wallet already exists at ${path}`) + ` — delete it with \`wallet delete --path ${path}\` first.`);
+    process.exit(1);
+  }
+}
+
+// ---------- commands ----------
+
+async function cmdCreate(opts: Record<string, string>): Promise<void> {
+  const path = walletPath(opts);
+  guardNoWallet(path);
+  const password = await readPasswordTwice('create');
+  const { wallet } = generateWallet();
+  saveKeystore(encryptPrivateKey(wallet.privateKey, password, wallet.address), path);
+  if (opts.json) {
+    console.log(JSON.stringify({ address: wallet.address, path }, null, 2));
+    return;
+  }
+  printCreated(wallet, path);
+}
+
+async function cmdImport(opts: Record<string, string>): Promise<void> {
+  const path = walletPath(opts);
+  guardNoWallet(path);
+  const secret = opts.secret ?? (await prompt('Enter mnemonic phrase (or 0x private key): ')).trim();
+  let wallet: Wallet;
+  try {
+    ({ wallet } = importWallet(secret));
+  } catch {
+    console.log(C.red('Invalid mnemonic or private key.'));
+    process.exit(1);
+  }
+  const password = await readPasswordTwice('import');
+  saveKeystore(encryptPrivateKey(wallet.privateKey, password, wallet.address), path);
+  if (opts.json) {
+    console.log(JSON.stringify({ address: wallet.address, path }, null, 2));
+    return;
+  }
+  printCreated(wallet, path);
+}
+
+async function cmdAddress(opts: Record<string, string>): Promise<void> {
+  const { wallet } = await loadUnlocked(walletPath(opts), 'unlock');
+  console.log(wallet.address);
+}
+
+async function cmdBalance(opts: Record<string, string>): Promise<void> {
+  const { wallet } = await loadUnlocked(walletPath(opts), 'balance');
+  const network = opts.network ?? 'ethereum-sepolia';
+  try {
+    const { eth, usdc } = await getBalances(wallet, network);
+    const usdcInfo = USDC[network];
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            network,
+            address: wallet.address,
+            eth,
+            usdc: usdcInfo
+              ? { raw: usdc, formatted: formatAmount(usdc, usdcInfo.decimals), symbol: usdcInfo.symbol }
+              : null,
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    console.log('');
+    console.log(`  ${C.bold('Wallet')}   ${wallet.address}`);
+    console.log(`  ${C.bold('Network')}  ${network}`);
+    console.log('  ' + '─'.repeat(46));
+    console.log(`  ${C.cyan('ETH')}     ${(Number(eth) / 1e18).toFixed(6)}`);
+    if (usdcInfo) console.log(`  ${C.cyan(usdcInfo.symbol)}  ${formatAmount(usdc, usdcInfo.decimals)}`);
+  } catch (e) {
+    console.log(C.red(`Failed to query ${network}: ${e instanceof Error ? e.message : e}`));
+    process.exit(1);
+  }
+}
+
+async function cmdExport(opts: Record<string, string>): Promise<void> {
+  const { wallet } = await loadUnlocked(walletPath(opts), 'export');
+  console.log('\n' + C.yellow('Anyone with this private key controls the wallet.'));
+  console.log(`  Private key: ${C.bold(wallet.privateKey)}`);
+  console.log(`  Mnemonic   : ${wallet.mnemonic?.phrase ?? C.gray('(imported as private key only)')}`);
+}
+
+async function cmdDelete(opts: Record<string, string>): Promise<void> {
+  const path = walletPath(opts);
+  if (!existsSync(path)) {
+    console.log(C.red('No wallet found at ' + path));
+    process.exit(1);
+  }
+  const answer = (await prompt(`Delete ${path}? Type ${C.bold('yes')} to confirm: `)).trim();
+  if (answer !== 'yes') {
+    console.log(C.gray('Aborted.'));
+    return;
+  }
+  deleteFile(path);
+  console.log(C.green('Wallet deleted.'));
+}
+
+// ---------- help ----------
+
+const HELP = `wallet v${VERSION}
+
+Manage an encrypted Ethereum keystore (scrypt + AES-256-GCM) at ~/.wallet/wallet.json.
+
+Usage:
+  wallet create [--path <file>] [--json]
+  wallet import <mnemonic | private key> [--path <file>] [--json]
+  wallet address [--path <file>]
+  wallet balance [--path <file>] [--network <ethereum-sepolia|ethereum-mainnet|base-sepolia|base>]
+  wallet export [--path <file>]
+  wallet delete [--path <file>]
+
+Options:
+  --path <file>     Keystore file (default ~/.wallet/wallet.json)
+  --network <id>    Network for balance lookups (default ethereum-sepolia)
+  --json             Machine-readable output
+
+Password:
+  Prompts interactively, or set WALLET_PASSWORD in the environment for scripting.`;
+
+function printHelp(): void {
+  console.log(HELP);
+}
+
+// ---------- entry ----------
+
+interface Parsed {
+  cmd: string;
+  positional: string[];
+  opts: Record<string, string>;
+}
+
+function parseArgs(args: string[]): Parsed {
+  const cmd = args.find((a) => !a.startsWith('--')) ?? 'help';
+  const positional: string[] = [];
+  const opts: Record<string, string> = {};
+  for (const a of args) {
+    if (a === cmd) continue;
+    if (a === '--json') {
+      opts.json = '1';
+      continue;
+    }
+    if (a === '--network' || a === '--path') {
+      const next = args[args.indexOf(a) + 1];
+      if (!next || next.startsWith('--')) {
+        console.log(C.red(`Missing value for ${a}`));
+        process.exit(1);
+      }
+      opts[a.slice(2)] = next;
+      continue;
+    }
+    if (!a.startsWith('--')) positional.push(a);
+  }
+  return { cmd, positional, opts };
+}
+
+async function main(): Promise<void> {
+  const { cmd, positional, opts } = parseArgs(process.argv.slice(2));
+  switch (cmd) {
+    case 'create': return cmdCreate(opts);
+    case 'import': return cmdImport({ ...opts, secret: positional[0] ?? opts.secret });
+    case 'address': return cmdAddress(opts);
+    case 'balance': return cmdBalance(opts);
+    case 'export': return cmdExport(opts);
+    case 'delete': return cmdDelete(opts);
+    case 'help':
+    case '-h':
+    case '--help':
+      return printHelp();
+    case '-v':
+    case '--version':
+      return console.log(VERSION);
+    default:
+      console.log(C.red(`Unknown command: ${cmd}`) + '\n');
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,110 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Wallet, HDNodeWallet } from 'ethers';
+import {
+  encryptPrivateKey,
+  decryptPrivateKey,
+  verifyPassword,
+  randomBytesHex,
+  type EncryptedKeystore,
+} from './keystore';
+
+export { encryptPrivateKey, decryptPrivateKey, verifyPassword, randomBytesHex };
+export type { EncryptedKeystore };
+
+export function processEnvPassword(): string | undefined {
+  const v = process.env.WALLET_PASSWORD ?? process.env.XSIFT_WALLET_PASSWORD;
+  return v && v.length > 0 ? v : undefined;
+}
+
+export const NETWORKS = {
+  ethereumMainnet: { networkId: 'ethereum-mainnet', chainId: 1 },
+  ethereumSepolia: { networkId: 'ethereum-sepolia', chainId: 11155111 },
+  base: { networkId: 'base', chainId: 8453 },
+  baseSepolia: { networkId: 'base-sepolia', chainId: 84532 },
+} as const;
+
+export const USDC: Record<string, { address: string; decimals: number; symbol: string }> = {
+  'ethereum-sepolia': { address: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', decimals: 6, symbol: 'USDC' },
+  'ethereum-mainnet': { address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', decimals: 6, symbol: 'USDC' },
+  'base-sepolia': { address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', decimals: 6, symbol: 'USDC' },
+  base: { address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6, symbol: 'USDC' },
+};
+
+export function rpcUrl(networkId: string): string {
+  const fromEnv = process.env.X402_RPC_URL;
+  if (fromEnv) return fromEnv;
+  switch (networkId) {
+    case 'ethereum-sepolia':
+      return 'https://ethereum-sepolia-rpc.publicnode.com';
+    case 'ethereum-mainnet':
+      return 'https://eth.llamarpc.com';
+    case 'base-sepolia':
+      return 'https://base-sepolia-rpc.publicnode.com';
+    case 'base':
+      return 'https://mainnet.base.org';
+    default:
+      throw new Error(`No default RPC for ${networkId}`);
+  }
+}
+
+export type SigningWallet = Wallet | HDNodeWallet;
+
+export function createWallet(): { wallet: HDNodeWallet; privateKey: string; address: string } {
+  const wallet = Wallet.createRandom();
+  return { wallet, privateKey: wallet.privateKey, address: wallet.address };
+}
+
+export function importWallet(secret: string): { wallet: SigningWallet; privateKey: string; address: string } {
+  const wallet: SigningWallet = /^[a-f0-9]{64}$/i.test(secret.replace(/^0x/, ''))
+    ? new Wallet(secret)
+    : Wallet.fromPhrase(secret);
+  return { wallet, privateKey: wallet.privateKey, address: wallet.address };
+}
+
+export function loadWallet(keystore: EncryptedKeystore, password: string): Wallet {
+  const privateKey = decryptPrivateKey(keystore, password);
+  const wallet = new Wallet(privateKey);
+  if (wallet.address.toLowerCase() !== keystore.address.toLowerCase()) {
+    throw new Error('Keystore address does not match its private key.');
+  }
+  return wallet;
+}
+
+export function saveKeystore(keystore: EncryptedKeystore, path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(keystore, null, 2), { mode: 0o600 });
+}
+
+export function readKeystore(path: string): EncryptedKeystore {
+  return JSON.parse(readFileSync(path, 'utf8')) as EncryptedKeystore;
+}
+
+export function deleteFile(path: string): void {
+  rmSync(path, { force: true });
+}
+
+export async function getBalances(walletOrAddress: string | Wallet, networkId: string): Promise<{ eth: string; usdc: string }> {
+  const { JsonRpcProvider, Contract } = await import('ethers');
+  const provider = new JsonRpcProvider(rpcUrl(networkId));
+  const address = typeof walletOrAddress === 'string' ? walletOrAddress : walletOrAddress.address;
+  const usdc = USDC[networkId];
+  const eth = await provider.getBalance(address);
+  let usdcBalance = 0n;
+  if (usdc) {
+    const contract = new Contract(usdc.address, ERC20_ABI, provider);
+    const balanceOf = (contract as unknown as { balanceOf: (a: string) => Promise<bigint> }).balanceOf;
+    usdcBalance = await balanceOf(address);
+  }
+  return { eth: eth.toString(), usdc: usdcBalance.toString() };
+}
+
+export function formatAmount(amountWei: bigint | string | number, decimals: number): string {
+  return (Number(amountWei) / 10 ** decimals).toFixed(decimals);
+}
+
+const ERC20_ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)',
+  'function nonces(address) view returns (uint256)',
+] as const;

package/src/keystore.ts

@@ -0,0 +1,101 @@
+import { randomBytes, randomUUID, scryptSync, createCipheriv, createDecipheriv } from 'node:crypto';
+
+export interface EncryptedKeystore {
+  version: 1;
+  id: string;
+  type: 'scrypt-aes-256-gcm';
+  params: {
+    n: number;
+    r: number;
+    p: number;
+    dkLen: number;
+    salt: string; // hex
+    iv: string; // hex
+    tag: string; // hex
+  };
+  ciphertext: string; // hex
+  address: string;
+}
+
+const PARAMS = { n: 2 ** 15, r: 8, p: 1, dkLen: 32 };
+
+// Coerce the (pre-generics) Buffer type into the stricter Uint8Array<ArrayBufferLike>
+// the current node crypto typings demand. Runtime-identical to the input buffer.
+function bytes(b: Buffer): Uint8Array<ArrayBufferLike> {
+  return b as unknown as Uint8Array<ArrayBufferLike>;
+}
+
+function deriveKey(password: string, salt: Buffer): Buffer {
+  return scryptSync(password, bytes(salt), PARAMS.dkLen, {
+    N: PARAMS.n,
+    r: PARAMS.r,
+    p: PARAMS.p,
+    maxmem: 128 * PARAMS.n * PARAMS.r * 2,
+  });
+}
+
+function hexString(buf: Buffer): string {
+  return buf.toString('hex');
+}
+
+export function encryptPrivateKey(privateKey: string, password: string, address: string): EncryptedKeystore {
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const key = deriveKey(password, salt);
+  const cipher = createCipheriv('aes-256-gcm', bytes(key), bytes(iv));
+  const data = Buffer.from(privateKey.replace(/^0x/, ''), 'hex');
+  const ciphertext = Buffer.concat([cipher.update(bytes(data)), cipher.final()] as unknown as Uint8Array<ArrayBufferLike>[]);
+  const tag = cipher.getAuthTag();
+  return {
+    version: 1,
+    id: randomUUID(),
+    type: 'scrypt-aes-256-gcm',
+    params: {
+      n: PARAMS.n,
+      r: PARAMS.r,
+      p: PARAMS.p,
+      dkLen: PARAMS.dkLen,
+      salt: hexString(salt),
+      iv: hexString(iv),
+      tag: hexString(tag),
+    },
+    ciphertext: hexString(ciphertext),
+    address,
+  };
+}
+
+export function decryptPrivateKey(keystore: EncryptedKeystore, password: string): string {
+  if (keystore.version !== 1 || keystore.type !== 'scrypt-aes-256-gcm') {
+    throw new Error('Unsupported keystore format');
+  }
+  const salt = Buffer.from(keystore.params.salt, 'hex');
+  const iv = Buffer.from(keystore.params.iv, 'hex');
+  const tag = Buffer.from(keystore.params.tag, 'hex');
+  const key = deriveKey(password, salt);
+  const decipher = createDecipheriv('aes-256-gcm', bytes(key), bytes(iv));
+  decipher.setAuthTag(bytes(tag));
+  try {
+    const data = Buffer.from(keystore.ciphertext, 'hex');
+    const plain = Buffer.concat([decipher.update(bytes(data)), decipher.final()] as unknown as Uint8Array<ArrayBufferLike>[]);
+    return '0x' + plain.toString('hex');
+  } catch {
+    throw new Error('Incorrect password or corrupted keystore.');
+  }
+}
+
+export function verifyPassword(keystore: EncryptedKeystore, password: string): boolean {
+  try {
+    decryptPrivateKey(keystore, password);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function bytesToHex(b: Uint8Array): string {
+  return '0x' + Buffer.from(b).toString('hex');
+}
+
+export function randomBytesHex(len = 32): string {
+  return '0x' + randomBytes(len).toString('hex');
+}