@lifi/cli 0.1.1-alpha.1 → 0.1.1

package/README.md

@@ -108,6 +108,32 @@ lifi auth test                 # Validate key against the API
 lifi health                    # Check API connectivity and latency
 ```
 
+### Balances & Allowances
+
+Read on-chain balances and ERC-20 allowances directly via JSON-RPC (no signing).
+
+```bash
+# Native (gas) balance — EVM or Solana
+lifi balance native --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+lifi balance native --chain solana   --address 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
+
+# ERC-20 / SPL token balance
+lifi balance token --chain ethereum \
+  --token  0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# ERC-20 allowance (EVM only)
+lifi balance allowance --chain ethereum \
+  --token   0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --owner   0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --spender 0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE
+
+# Override the public RPC when needed
+lifi balance native --chain arbitrum --address 0x... --rpc https://arb1.example/v1
+```
+
+RPC URLs are pulled from the LI.FI chain catalog by default and tried in order on transient failures.
+
 ## Output Modes
 
 | Mode | Trigger | Behaviour |

package/dist/lifi.js

@@ -3,6 +3,8 @@ import { Command, Option } from "commander";
 import Table from "cli-table3";
 import axios from "axios";
 import ora from "ora";
+import { createPublicClient, erc20Abi, http, isAddress } from "viem";
+import { Connection, PublicKey } from "@solana/web3.js";
 import { input } from "@inquirer/prompts";
 //#region src/core/constants.ts
 const API_BASE_URL = "https://li.quest/v1";
@@ -159,6 +161,312 @@ function registerAuthCommand(program) {
 	});
 }
 //#endregion
+//#region src/core/chain-resolver.ts
+let chainsCache = null;
+let inflight = null;
+async function fetchChains() {
+	if (chainsCache) return chainsCache;
+	if (inflight) return inflight;
+	inflight = api.get("/chains?chainTypes=EVM,SVM").then(({ data }) => {
+		chainsCache = data.chains;
+		inflight = null;
+		return chainsCache;
+	});
+	try {
+		return await inflight;
+	} catch (err) {
+		inflight = null;
+		throw err;
+	}
+}
+async function resolveChain(chainArg) {
+	if (!chainArg) throw new CliError("Chain is required", ExitCode.InvalidArgs);
+	const chains = await fetchChains();
+	const isNumeric = /^\d+$/.test(chainArg);
+	const needle = chainArg.toLowerCase();
+	const match = isNumeric ? chains.find((c) => c.id === Number(chainArg)) : chains.find((c) => c.name.toLowerCase() === needle || c.key.toLowerCase() === needle || c.metamask?.chainName?.toLowerCase() === needle);
+	if (!match) throw new CliError(`Chain "${chainArg}" not found`, ExitCode.InvalidArgs, "Run: lifi chains  to see all available chains");
+	return match;
+}
+function resolveRpcUrls(chain, override) {
+	if (override) return [override];
+	const urls = chain.metamask?.rpcUrls ?? [];
+	if (urls.length === 0) throw new CliError(`No RPC URL available for chain "${chain.name}" (id ${chain.id})`, ExitCode.InvalidArgs, "Supply one with --rpc <url>");
+	return urls;
+}
+//#endregion
+//#region src/core/rpc-client.ts
+function getStatus(e) {
+	if (typeof e.status === "number") return e.status;
+	if (typeof e.cause?.status === "number") return e.cause.status;
+}
+function getMessage(e) {
+	return e.shortMessage || e.message || e.details || "RPC error";
+}
+function isTransientRpcError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	const status = getStatus(e);
+	if (status === 429 || typeof status === "number" && status >= 500) return true;
+	const code = e.code ?? e.cause?.code;
+	if (code === "ECONNREFUSED" || code === "ECONNRESET" || code === "ETIMEDOUT" || code === "EAI_AGAIN") return true;
+	if (code === -32005) return true;
+	const msg = `${getMessage(e)} ${e.cause?.message ?? ""}`.toLowerCase();
+	if (msg.includes("rate limit") || msg.includes("too many requests")) return true;
+	if (msg.includes("timeout") || msg.includes("timed out")) return true;
+	if (msg.includes("fetch failed") || msg.includes("network")) return true;
+	return false;
+}
+function mapRpcError(err, rpcUrls) {
+	if (err instanceof CliError) return err;
+	if (!err || typeof err !== "object") return new CliError(String(err ?? "Unknown RPC error"), ExitCode.NetworkError);
+	const e = err;
+	const raw = getMessage(e);
+	const revertMatch = raw.match(/execution reverted(?:: (.+))?/i);
+	if (revertMatch) {
+		const reason = revertMatch[1]?.trim();
+		return new CliError(reason ? `Execution reverted: ${reason}` : "Execution reverted", ExitCode.ApiError, "The contract rejected the call. Check that the address is an ERC-20 and the chain is correct.");
+	}
+	if (getStatus(e) === 429 || /rate limit|too many requests/i.test(raw)) return new CliError("RPC rate limited", ExitCode.NetworkError, "Retry shortly or pass --rpc <url> to use a private RPC.");
+	if (/timeout|timed out/i.test(raw)) return new CliError("RPC timed out", ExitCode.NetworkError, `Tried: ${rpcUrls.join(", ")}. Pass --rpc <url> to override.`);
+	return new CliError(raw, ExitCode.NetworkError, `RPC URLs tried: ${rpcUrls.join(", ")}`);
+}
+function makeClient(rpcUrl) {
+	return createPublicClient({ transport: http(rpcUrl, {
+		timeout: 15e3,
+		retryCount: 0
+	}) });
+}
+async function withFallback(rpcUrls, op) {
+	let lastErr;
+	for (const url of rpcUrls) try {
+		return await op(makeClient(url));
+	} catch (err) {
+		lastErr = err;
+		if (!isTransientRpcError(err)) break;
+	}
+	throw mapRpcError(lastErr, rpcUrls);
+}
+function createEvmClient(rpcUrls) {
+	if (rpcUrls.length === 0) throw new CliError("No RPC URLs provided", ExitCode.InvalidArgs);
+	return {
+		rpcUrls,
+		getNativeBalance: (address) => withFallback(rpcUrls, (c) => c.getBalance({ address })),
+		getErc20Balance: (token, wallet) => withFallback(rpcUrls, (c) => c.readContract({
+			address: token,
+			abi: erc20Abi,
+			functionName: "balanceOf",
+			args: [wallet]
+		})),
+		getErc20Allowance: (token, owner, spender) => withFallback(rpcUrls, (c) => c.readContract({
+			address: token,
+			abi: erc20Abi,
+			functionName: "allowance",
+			args: [owner, spender]
+		})),
+		getErc20Metadata: async (token) => {
+			const [symbolRes, decimalsRes] = await Promise.allSettled([withFallback(rpcUrls, (c) => c.readContract({
+				address: token,
+				abi: erc20Abi,
+				functionName: "symbol"
+			})), withFallback(rpcUrls, (c) => c.readContract({
+				address: token,
+				abi: erc20Abi,
+				functionName: "decimals"
+			}))]);
+			return {
+				symbol: symbolRes.status === "fulfilled" ? symbolRes.value : "?",
+				decimals: decimalsRes.status === "fulfilled" ? Number(decimalsRes.value) : 0
+			};
+		}
+	};
+}
+async function withSolanaFallback(rpcUrls, op) {
+	let lastErr;
+	for (const url of rpcUrls) try {
+		return await op(new Connection(url, "confirmed"));
+	} catch (err) {
+		lastErr = err;
+		if (!isTransientRpcError(err)) break;
+	}
+	throw mapRpcError(lastErr, rpcUrls);
+}
+function createSolanaClient(rpcUrls) {
+	if (rpcUrls.length === 0) throw new CliError("No RPC URLs provided", ExitCode.InvalidArgs);
+	return {
+		rpcUrls,
+		getNativeBalance: async (owner) => {
+			const lamports = await withSolanaFallback(rpcUrls, (c) => c.getBalance(owner));
+			return BigInt(lamports);
+		},
+		getSplBalance: async (owner, mint) => {
+			const result = await withSolanaFallback(rpcUrls, (c) => c.getParsedTokenAccountsByOwner(owner, { mint }));
+			let total = 0n;
+			let decimals = 0;
+			for (const { account } of result.value) {
+				const info = account.data.parsed?.info?.tokenAmount;
+				if (info?.amount) total += BigInt(info.amount);
+				if (typeof info?.decimals === "number") decimals = info.decimals;
+			}
+			return {
+				amount: total,
+				decimals
+			};
+		}
+	};
+}
+function parseSolanaAddress(label, value) {
+	try {
+		return new PublicKey(value);
+	} catch {
+		throw new CliError(`Invalid ${label} address: ${value}`, ExitCode.InvalidArgs);
+	}
+}
+//#endregion
+//#region src/commands/balance.ts
+function assertEvm(chain, operation) {
+	if (chain.chainType !== "EVM") throw new CliError(`${operation} is only supported on EVM chains (got ${chain.chainType} chain "${chain.name}").`, ExitCode.InvalidArgs);
+}
+function assertEvmAddress(label, value) {
+	if (!isAddress(value)) throw new CliError(`Invalid ${label} address: ${value}`, ExitCode.InvalidArgs);
+	return value;
+}
+function registerBalanceCommand(program) {
+	const balance = program.command("balance").description("Read on-chain balances and ERC-20 allowances");
+	balance.command("native").description("Read the native-token balance of an address").requiredOption("--chain <chain>", "Chain id, name, or key (e.g. 1, ethereum, eth)").requiredOption("--address <address>", "Wallet address").option("--rpc <url>", "Override the RPC URL").addHelpText("after", `
+Examples:
+  $ lifi balance native --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+  $ lifi balance native --chain 137 --address 0x... --json
+  $ lifi balance native --chain arbitrum --address 0x... --rpc https://arb1.example/v1`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const chain = await withSpinner("Resolving chain...", () => resolveChain(options.chain));
+			const rpcUrls = resolveRpcUrls(chain, options.rpc);
+			let result;
+			if (chain.chainType === "EVM") {
+				const address = assertEvmAddress("wallet", options.address);
+				const client = createEvmClient(rpcUrls);
+				result = {
+					address,
+					balance: (await withSpinner(`Fetching ${chain.nativeToken.symbol} balance...`, () => client.getNativeBalance(address))).toString(),
+					tokenSymbol: chain.nativeToken.symbol,
+					chainId: chain.id,
+					decimals: chain.nativeToken.decimals
+				};
+			} else if (chain.chainType === "SVM") {
+				const owner = parseSolanaAddress("wallet", options.address);
+				const client = createSolanaClient(rpcUrls);
+				const raw = await withSpinner(`Fetching ${chain.nativeToken.symbol} balance...`, () => client.getNativeBalance(owner));
+				result = {
+					address: options.address,
+					balance: raw.toString(),
+					tokenSymbol: chain.nativeToken.symbol,
+					chainId: chain.id,
+					decimals: chain.nativeToken.decimals
+				};
+			} else throw new CliError(`Unsupported chain type: ${chain.chainType}`, ExitCode.InvalidArgs);
+			if (isJsonMode(opts)) console.log(jsonOutput(result));
+			else console.log(formatTable(["Field", "Value"], [
+				["Chain", `${chain.name} (${chain.id})`],
+				["Address", result.address],
+				["Balance", `${formatAmount(result.balance, result.decimals)} ${result.tokenSymbol}`],
+				["Raw", result.balance]
+			]));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+	balance.command("token").description("Read the ERC-20 balance of a wallet for a specific token").requiredOption("--chain <chain>", "Chain id, name, or key").requiredOption("--token <address>", "ERC-20 contract address").requiredOption("--wallet <address>", "Wallet address").option("--rpc <url>", "Override the RPC URL").addHelpText("after", `
+Examples:
+  $ lifi balance token --chain ethereum \\
+      --token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \\
+      --wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const chain = await withSpinner("Resolving chain...", () => resolveChain(options.chain));
+			const rpcUrls = resolveRpcUrls(chain, options.rpc);
+			let result;
+			if (chain.chainType === "EVM") {
+				const token = assertEvmAddress("token", options.token);
+				const wallet = assertEvmAddress("wallet", options.wallet);
+				const client = createEvmClient(rpcUrls);
+				const [rawBalance, meta] = await withSpinner("Fetching ERC-20 balance...", () => Promise.all([client.getErc20Balance(token, wallet), client.getErc20Metadata(token)]));
+				result = {
+					walletAddress: wallet,
+					tokenAddress: token,
+					balance: rawBalance.toString(),
+					tokenSymbol: meta.symbol,
+					decimals: meta.decimals,
+					chainId: chain.id
+				};
+			} else if (chain.chainType === "SVM") {
+				const mint = parseSolanaAddress("token", options.token);
+				const owner = parseSolanaAddress("wallet", options.wallet);
+				const client = createSolanaClient(rpcUrls);
+				const splResult = await withSpinner("Fetching SPL token balance...", () => client.getSplBalance(owner, mint));
+				result = {
+					walletAddress: options.wallet,
+					tokenAddress: options.token,
+					balance: splResult.amount.toString(),
+					tokenSymbol: "?",
+					decimals: splResult.decimals,
+					chainId: chain.id
+				};
+			} else throw new CliError(`Unsupported chain type: ${chain.chainType}`, ExitCode.InvalidArgs);
+			if (isJsonMode(opts)) console.log(jsonOutput(result));
+			else console.log(formatTable(["Field", "Value"], [
+				["Chain", `${chain.name} (${chain.id})`],
+				["Wallet", result.walletAddress],
+				["Token", `${result.tokenSymbol} (${result.tokenAddress})`],
+				["Balance", `${formatAmount(result.balance, result.decimals)} ${result.tokenSymbol}`],
+				["Raw", result.balance]
+			]));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+	balance.command("allowance").description("Read the ERC-20 allowance an owner has granted to a spender").requiredOption("--chain <chain>", "Chain id, name, or key").requiredOption("--token <address>", "ERC-20 contract address").requiredOption("--owner <address>", "Token owner (wallet) address").requiredOption("--spender <address>", "Spender address (typically the LI.FI Diamond)").option("--rpc <url>", "Override the RPC URL").addHelpText("after", `
+Examples:
+  $ lifi balance allowance --chain ethereum \\
+      --token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \\
+      --owner 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \\
+      --spender 0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE
+
+Note: Allowance is an EVM-only concept. On Solana, programs use token-account
+authority instead of ERC-20-style approvals.`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const token = assertEvmAddress("token", options.token);
+			const owner = assertEvmAddress("owner", options.owner);
+			const spender = assertEvmAddress("spender", options.spender);
+			const chain = await withSpinner("Resolving chain...", () => resolveChain(options.chain));
+			assertEvm(chain, "Allowance");
+			const client = createEvmClient(resolveRpcUrls(chain, options.rpc));
+			const [rawAllowance, meta] = await withSpinner("Fetching allowance...", () => Promise.all([client.getErc20Allowance(token, owner, spender), client.getErc20Metadata(token)]));
+			const result = {
+				tokenAddress: token,
+				ownerAddress: owner,
+				spenderAddress: spender,
+				allowance: rawAllowance.toString(),
+				tokenSymbol: meta.symbol,
+				decimals: meta.decimals,
+				chainId: chain.id
+			};
+			if (isJsonMode(opts)) console.log(jsonOutput(result));
+			else console.log(formatTable(["Field", "Value"], [
+				["Chain", `${chain.name} (${chain.id})`],
+				["Token", `${meta.symbol} (${token})`],
+				["Owner", owner],
+				["Spender", spender],
+				["Allowance", `${formatAmount(result.allowance, result.decimals)} ${result.tokenSymbol}`],
+				["Raw", result.allowance]
+			]));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
 //#region src/commands/chains.ts
 function registerChainsCommand(program) {
 	program.command("chains").description("List all supported blockchain networks").addOption(new Option("--type <type>", "Filter by chain type").choices(["EVM", "SVM"])).addHelpText("after", `
@@ -615,6 +923,7 @@ function createProgram() {
 	registerToolsCommand(program);
 	registerGasCommand(program);
 	registerHealthCommand(program);
+	registerBalanceCommand(program);
 	return program;
 }
 if (process.env["VITEST"] === void 0) createProgram().parseAsync(process.argv).catch(handleError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/cli",
-  "version": "0.1.1-alpha.1",
+  "version": "0.1.1",
   "description": "CLI for the LI.FI cross-chain bridge & DEX aggregation API",
   "homepage": "https://github.com/lifinance/lifi-cli",
   "bugs": {
@@ -41,7 +41,9 @@
     "axios": "^1.7.0",
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
-    "ora": "^8.1.0"
+    "ora": "^8.1.0",
+    "viem": "^2.21.0",
+    "@solana/web3.js": "^1.95.0"
   },
   "lint-staged": {
     "src/**/*.{ts,tsx}": [