humanfx-wallet-cli 0.1.0

package/dist/args.js

@@ -0,0 +1,27 @@
+/** Minimal `--flag value` / `--flag` (boolean) parser — no external dep needed for this CLI's
+ * small, fixed set of flags. */
+export function parseFlags(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const name = arg.slice(2);
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[name] = next;
+            i += 1;
+        }
+        else {
+            flags[name] = true;
+        }
+    }
+    return flags;
+}
+export function requireFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== 'string' || !value) {
+        throw new Error(`Missing required --${name} <value> argument.`);
+    }
+    return value;
+}

package/dist/bin.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { runGenerate } from './commands/generate.js';
+import { runImport } from './commands/import.js';
+import { runAddress } from './commands/address.js';
+import { runBalance } from './commands/balance.js';
+import { runSend } from './commands/send.js';
+import { runCall } from './commands/call.js';
+const USAGE = `hfx-wallet — local-custody HumanFX agentic wallet CLI
+
+The private key never leaves this machine and is never printed by any command — only addresses,
+balances, and tx hashes are. Register the resulting address with backend-core separately (via the
+register_agentic_wallet MCP tool), this CLI has no HumanFX credential of its own.
+
+Usage:
+  hfx-wallet generate [--force]
+  hfx-wallet import --from <file> [--force]        (file must contain the raw private key)
+  hfx-wallet address
+  hfx-wallet balance [--address <0x..>] [--token <0x..>]
+  hfx-wallet send --to <0x..> --amount <decimal> [--token <0x..>]
+  hfx-wallet call --calls <file.json>               ([{target, data, value?}, ...])
+`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case 'generate':
+            runGenerate(rest);
+            return;
+        case 'import':
+            runImport(rest);
+            return;
+        case 'address':
+            runAddress();
+            return;
+        case 'balance':
+            await runBalance(rest);
+            return;
+        case 'send':
+            await runSend(rest);
+            return;
+        case 'call':
+            await runCall(rest);
+            return;
+        default:
+            console.error(USAGE);
+            process.exit(command ? 1 : 0);
+    }
+}
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/dist/chain-client.js

@@ -0,0 +1,8 @@
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { config } from './config.js';
+export function getPublicClient() {
+    return createPublicClient({ transport: http(config.evmRpcUrl) });
+}
+export function getWalletClient(account) {
+    return createWalletClient({ account, transport: http(config.evmRpcUrl) });
+}

package/dist/commands/address.js

@@ -0,0 +1,5 @@
+import { loadKeystore } from '../keystore.js';
+export function runAddress() {
+    const { address } = loadKeystore();
+    console.log(address);
+}

package/dist/commands/balance.js

@@ -0,0 +1,50 @@
+import { formatUnits } from 'viem';
+import { getPublicClient } from '../chain-client.js';
+import { keystoreExists, loadKeystore } from '../keystore.js';
+import { parseFlags } from '../args.js';
+const ERC20_ABI = [
+    {
+        type: 'function',
+        name: 'balanceOf',
+        stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ type: 'uint256' }],
+    },
+    {
+        type: 'function',
+        name: 'decimals',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ type: 'uint8' }],
+    },
+    {
+        type: 'function',
+        name: 'symbol',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ type: 'string' }],
+    },
+];
+export async function runBalance(args) {
+    const flags = parseFlags(args);
+    const address = (typeof flags.address === 'string' ? flags.address : loadKeystoreAddressOrThrow());
+    const client = getPublicClient();
+    if (typeof flags.token === 'string') {
+        const token = flags.token;
+        const [raw, decimals, symbol] = await Promise.all([
+            client.readContract({ address: token, abi: ERC20_ABI, functionName: 'balanceOf', args: [address] }),
+            client.readContract({ address: token, abi: ERC20_ABI, functionName: 'decimals' }),
+            client.readContract({ address: token, abi: ERC20_ABI, functionName: 'symbol' }).catch(() => ''),
+        ]);
+        console.log(`${formatUnits(raw, decimals)} ${symbol}`.trim());
+        return;
+    }
+    const raw = await client.getBalance({ address });
+    console.log(`${formatUnits(raw, 18)} (native)`);
+}
+function loadKeystoreAddressOrThrow() {
+    if (!keystoreExists()) {
+        throw new Error('No --address given and no local wallet found — pass --address <0x...> explicitly.');
+    }
+    return loadKeystore().address;
+}

package/dist/commands/call.js

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { privateKeyToAccount } from 'viem/accounts';
+import { getWalletClient } from '../chain-client.js';
+import { loadKeystore } from '../keystore.js';
+import { parseFlags, requireFlag } from '../args.js';
+/** Executes a list of {target, data, value} calls SEQUENTIALLY (a plain EOA can't natively batch,
+ * unlike a smart-contract account) — continues through the whole list even if one fails, so the
+ * caller gets a full per-item report rather than an opaque abort partway through. */
+export async function runCall(args) {
+    const flags = parseFlags(args);
+    const callsPath = requireFlag(flags, 'calls');
+    const calls = JSON.parse(readFileSync(callsPath, 'utf8'));
+    if (!Array.isArray(calls) || calls.length === 0) {
+        throw new Error('--calls file must contain a non-empty JSON array of {target, data, value?}.');
+    }
+    const { private_key } = loadKeystore();
+    const account = privateKeyToAccount(private_key);
+    const wallet = getWalletClient(account);
+    const results = [];
+    for (const call of calls) {
+        try {
+            const tx_hash = await wallet.sendTransaction({
+                chain: null,
+                to: call.target,
+                data: call.data,
+                value: call.value ? BigInt(call.value) : undefined,
+            });
+            results.push({ target: call.target, ok: true, tx_hash });
+        }
+        catch (err) {
+            results.push({ target: call.target, ok: false, error: err.message });
+        }
+    }
+    console.log(JSON.stringify(results, null, 2));
+}

package/dist/commands/generate.js

@@ -0,0 +1,15 @@
+import { generatePrivateKey } from 'viem/accounts';
+import { keystoreExists, saveKeystore } from '../keystore.js';
+import { config } from '../config.js';
+export function runGenerate(args) {
+    if (keystoreExists() && !args.includes('--force')) {
+        throw new Error(`A wallet already exists at ${config.keyDir}. Pass --force to overwrite it (the old key ` +
+            `will be gone — make sure it's backed up or genuinely unneeded first).`);
+    }
+    const privateKey = generatePrivateKey();
+    const { address } = saveKeystore(privateKey);
+    console.log(`Generated new wallet.`);
+    console.log(`address: ${address}`);
+    console.log(`Private key saved to ${config.keyDir}/key.json (0600) — not printed here. Back it up ` +
+        'yourself by reading that file directly outside of any agent conversation, if you want a copy.');
+}

package/dist/commands/import.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { keystoreExists, saveKeystore } from '../keystore.js';
+import { config } from '../config.js';
+import { parseFlags, requireFlag } from '../args.js';
+/** Reads the private key from a FILE PATH, never a direct --key value — a value passed on the
+ * command line lands in shell history and process listings, exactly the exposure this CLI exists
+ * to avoid. The file's contents are read once, copied into the keystore, and never echoed back. */
+export function runImport(args) {
+    const flags = parseFlags(args);
+    if (keystoreExists() && !flags.force) {
+        throw new Error(`A wallet already exists at ${config.keyDir}. Pass --force to overwrite it (the old key ` +
+            `will be gone — make sure it's backed up or genuinely unneeded first).`);
+    }
+    const fromPath = requireFlag(flags, 'from');
+    const raw = readFileSync(fromPath, 'utf8').trim();
+    const privateKey = (raw.startsWith('0x') ? raw : `0x${raw}`);
+    const { address } = saveKeystore(privateKey);
+    console.log(`Imported wallet.`);
+    console.log(`address: ${address}`);
+    console.log(`Private key saved to ${config.keyDir}/key.json (0600) — not printed here.`);
+}

package/dist/commands/send.js

@@ -0,0 +1,56 @@
+import { parseUnits } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { getPublicClient, getWalletClient } from '../chain-client.js';
+import { loadKeystore } from '../keystore.js';
+import { parseFlags, requireFlag } from '../args.js';
+const ERC20_TRANSFER_ABI = [
+    {
+        type: 'function',
+        name: 'transfer',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'to', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ type: 'bool' }],
+    },
+    {
+        type: 'function',
+        name: 'decimals',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ type: 'uint8' }],
+    },
+];
+export async function runSend(args) {
+    const flags = parseFlags(args);
+    const to = requireFlag(flags, 'to');
+    const amount = requireFlag(flags, 'amount');
+    const { private_key } = loadKeystore();
+    const account = privateKeyToAccount(private_key);
+    const wallet = getWalletClient(account);
+    const publicClient = getPublicClient();
+    if (typeof flags.token === 'string') {
+        const token = flags.token;
+        const decimals = await publicClient.readContract({
+            address: token,
+            abi: ERC20_TRANSFER_ABI,
+            functionName: 'decimals',
+        });
+        const txHash = await wallet.writeContract({
+            chain: null,
+            address: token,
+            abi: ERC20_TRANSFER_ABI,
+            functionName: 'transfer',
+            args: [to, parseUnits(amount, decimals)],
+        });
+        console.log(txHash);
+        return;
+    }
+    const txHash = await wallet.sendTransaction({
+        chain: null,
+        to,
+        value: parseUnits(amount, 18),
+    });
+    console.log(txHash);
+}

package/dist/config.js

@@ -0,0 +1,10 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const config = {
+    /** Directory holding the local keystore file. Override to run multiple named wallets side by
+     * side, or to point at a different mount in a container. */
+    keyDir: process.env.HFX_WALLET_KEY_DIR ?? join(homedir(), '.humanfx', 'agent-wallet'),
+    /** v1: a single configured chain (worldchain, matching this protocol's own default). */
+    evmRpcUrl: process.env.EVM_RPC_URL ?? 'https://worldchain-mainnet.g.alchemy.com/public',
+};
+export const KEYSTORE_FILENAME = 'key.json';

package/dist/keystore.js

@@ -0,0 +1,30 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { privateKeyToAccount } from 'viem/accounts';
+import { config, KEYSTORE_FILENAME } from './config.js';
+function keystorePath() {
+    return join(config.keyDir, KEYSTORE_FILENAME);
+}
+export function keystoreExists() {
+    return existsSync(keystorePath());
+}
+/** Writes the keystore file with 0600 perms (0700 on its containing dir) — never logs or returns
+ * the private key itself; callers only ever get the address back. */
+export function saveKeystore(privateKey) {
+    const address = privateKeyToAccount(privateKey).address;
+    mkdirSync(config.keyDir, { recursive: true, mode: 0o700 });
+    writeFileSync(keystorePath(), JSON.stringify({ private_key: privateKey, address }, null, 2), {
+        mode: 0o600,
+    });
+    return { address };
+}
+/** Loads the keystore for signing. Never printed to stdout/stderr by any command — only ever held
+ * in memory for the duration of a single command's execution. */
+export function loadKeystore() {
+    if (!keystoreExists()) {
+        throw new Error(`No wallet found at ${keystorePath()}. Run "hfx-wallet generate" (new key) or ` +
+            `"hfx-wallet import --from <file>" (existing key) first.`);
+    }
+    const raw = readFileSync(keystorePath(), 'utf8');
+    return JSON.parse(raw);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "humanfx-wallet-cli",
+  "version": "0.1.0",
+  "description": "Local-custody CLI for a HumanFX agentic wallet: generate/import a key that never leaves this machine, check balance, send tokens, execute arbitrary calldata. The private key never appears in any command's output — only addresses, balances, and tx hashes do.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "hfx-wallet": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin.js",
+    "cli": "tsx src/bin.ts",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "viem": "2.23.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.16",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.56.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.3.3",
+    "vitest": "^2.0.5"
+  }
+}