VX — Small Web3 CLI SDK

Big picture

• CLI entry: src/cli.ts launches src/command/main.ts.
• RPC management: src/core/rpc/* contains config creation, viewing and loading utilities.
• On-chain helpers: src/core/data/index.ts provides ethers v6 helpers (block, balance, gas).
• Local dev server: src/server/dev.ts serves /api, /api/block and a debug view.
• Project initialization: src/command/pjmake.ts implements project scaffolding.

Features

• Connect to multiple chains
• Create and manage wallets
• Local development chains
• Deploy smart contracts

Library usage (default import)

Use the SDK programmatically via the default export; CLI behavior is unchanged.

TypeScript / ESM

import vx from "@nk4dev/vx";

const rpc = vx.getRpcUrl();
const block = await vx.getBlockNumber(rpc);
const gas = await vx.getGasFees(rpc);

CommonJS

const vx = require("@nk4dev/vx");
vx.getGasFees("http://127.0.0.1:8545").then(console.log);

Named exports remain available:

import { vx as data, instance } from "@nk4dev/vx";
await data.getBalance("http://127.0.0.1:8545", "0x...");

Hardhat setup

Scaffold Hardhat into the current project using a built-in template.

vx3 setup hardhat
# then install dev dependencies
npm install -D hardhat @nomicfoundation/hardhat-toolbox

# try scripts
npm run hh:node
npm run hh:compile
npm run hh:deploy

• Adds scripts: hh, hh:compile, hh:test, hh:node, hh:deploy
• Adds devDependencies: hardhat, @nomicfoundation/hardhat-toolbox
• Copies: hardhat.config.ts, contracts/Sample.sol, scripts/deploy.ts

Example: gas command output

The repository includes a vx3 gas command that prints network gas fee data. Example output:

Connecting to RPC: http://localhost:8545
Gas fee data:
  gasPrice (wei): 20000000000
  gasPrice (gwei): 20
  maxFeePerGas (wei): 2532616788
  maxFeePerGas (gwei): 2.532616788
  maxPriorityFeePerGas (wei): 1000000000
  maxPriorityFeePerGas (gwei): 1
            

Key files

• src/cli.ts — Node CLI entry.
• src/command/main.ts — Command dispatcher; supports subcommands like init, create, serve, rpc, sol.
• src/core/rpc/config.ts — Writes a vx.config.json placeholder for RPC settings.
• src/core/rpc/connect.ts — Tries multiple locations to load vx.config.json and returns the first configuration object (array-aware).
• src/core/data/index.ts — Ethers-based helpers: getBlockNumber, getBalance, getGasFees.
• src/server/dev.ts — Local HTTP server (adjusted to not require vx.config.json at import time).
• src/command/pjmake.ts — Implements npx vx3 init <name> scaffolding and package.json creation.
• hardhat.config.ts, contracts/, scripts/ — Hardhat integration samples (Sample.sol, deploy script).

Common commands (examples)

• npm run build — build TypeScript (rimraf dist && tsc).
• npm run dev — run built CLI (node dist/cli.js).
• vx3 create <name> — create a new project from template (non-interactive).
• vx3 create — interactive prompt to create a new project.
• npx vx3 rpc init — create vx.config.json (RPC template).
• npx vx3 serve --debug — start local dev server with debug view.
• vx3 setup hardhat — scaffold Hardhat into the current project.
• npx vx sol hello — example subcommand that prints "hello world".
• Hardhat: npm run hh:node, npm run hh:compile, npm run hh:deploy.

Build / test / dev workflow

1. Install deps: npm install
2. Build: npm run build
3. Run CLI: npm run dev or npx vx3 <command>
4. Local server: npx vx3 serve --debug
5. Tests: npm test (Jest)

vx.config.json (RPC config)

The template written by src/core/rpc/config.ts is an array. Example:

[
                {
                    "host": "localhost",
                    "port": 8575,
                    "protocol": "http"
                }
            ]

Note: some code previously expected a single-object config while other parts expected an array. The loader is array-aware and returns the first object for compatibility. Consider standardizing the format to simplify code.

Debug page (Tailwind UI)

vx3 serve --debug serves a Tailwind-powered debug dashboard at /debug.

• Shows server host and the latest block number
• Quick links: /api, /api/block
• Usage section with example fetch calls

Notes

• The file src/core/rpc/connect.ts was cleaned up after merge-conflict remnants were found.
• Type-definition conflicts (minimatch / @types/glob) caused build errors previously; the project currently uses skipLibCheck in tsconfig.json to avoid transitive declaration-file conflicts.
• The local server was adjusted to avoid requiring vx.config.json at import time so npx vx3 init doesn't fail when config is missing.
• Default library import is supported (import vx from "@nk4dev/vx") while CLI behavior remains unchanged.
• getGasFees returns a JSON-serializable object; bigint fields are stringified via toJSON to avoid serialization errors.

Examples

Initialize project

npx vx3 init hello-world

Create RPC config

npx vx3 rpc init

Libraries

• express — used for the debug/local server
• ethers.js — RPC and on-chain helpers

Author

Maintainer: nk4dev