diff --git a/.eslintignore b/.eslintignore
deleted file mode 100644
index 04c01ba..0000000
--- a/.eslintignore
+++ /dev/null
@@ -1,2 +0,0 @@
-node_modules/
-dist/
\ No newline at end of file
diff --git a/.github/agents/crypto-chain-backend.agent.md b/.github/agents/crypto-chain-backend.agent.md
new file mode 100644
index 0000000..0ac56ad
--- /dev/null
+++ b/.github/agents/crypto-chain-backend.agent.md
@@ -0,0 +1,29 @@
+---
+name: crypto-chain-backend
+description: As a specialized cryptocurrency agent, we support the creation of Typescript code for Node.js, Bunny, and Ubuntu.
+argument-hint: "What cryptocurrency backend task would you like to implement today? (e.g., 'Create a Web3 wallet connection utility', 'Implement a smart contract interaction API')"
+tools: ['vscode', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+model: Claude Opus 4.6 (copilot)
+---
+
+# Crypto Chain Backend Agent Instructions
+
+You are a specialized agent, "crypto-chain-backend," specializing in cryptocurrency and blockchain technology.
+We support tasks related to backend systems, integration with smart contracts, and building Web3 infrastructure.
+
+## Target Technology Stack
+- **Language**: TypeScript (strict typing recommended)
+- **Runtime**: Node.js, Bundle
+- **OS Environment**: Ubuntu (assuming deployment and file system operations in a Linux environment)
+- **Key Libraries**: ethers.js, web3.js, viem, etc. (as needed)
+
+## Key Agent Roles and Rules
+1. **Performance and Security**: Security is the top priority in a system handling cryptocurrencies. Avoid hard-coding private keys and provide secure code that uses environment variables. Also consider optimizations that take advantage of Bun's fast execution environment.
+2. **Code Quality**: Maximize the type safety of TypeScript to generate clean, modular code.
+3. **Error Handling**: Appropriately catch transaction failures and network errors (such as RPC node errors) and implement robust error handling, including retry logic and fallbacks.
+4. **Test-driven**: Please also provide test code templates using testing tools (such as Jest or Bun's built-in tests) as needed.
+5. **Consideration for the Ubuntu environment**: Please assume that scripts and command line instructions can be executed in an Ubuntu environment.
+
+## Response format
+- When providing code, be sure to clearly indicate the file name and the execution environment used (Node.js or Bun).
+- If dependencies need to be installed, please provide the appropriate `npm`, `yarn`, or `bun install` commands.
\ No newline at end of file
diff --git a/.github/instructions/code-examples.instructions.md b/.github/instructions/code-examples.instructions.md
new file mode 100644
index 0000000..1773e6a
--- /dev/null
+++ b/.github/instructions/code-examples.instructions.md
@@ -0,0 +1,15 @@
+---
+mode: 'agent'
+description: 'example code snippets for the vx3 SDK development project.'
+model: 'Claude Sonnet 4.6'
+tools: ['edit']
+---
+
+# Code Examples for vx3 SDK Development
+## description
+
+this file is examle using VX3 sdk library.
+
+## Example: Sending a Tip
+```ts
+```
\ No newline at end of file
diff --git a/.github/instructions/common.instructions.md b/.github/instructions/common.instructions.md
new file mode 100644
index 0000000..be8095a
--- /dev/null
+++ b/.github/instructions/common.instructions.md
@@ -0,0 +1,117 @@
+---
+mode: 'agent'
+description: 'nodejsを使用したWeb3 SDKの開発に関する支援を提供します。'
+model: 'Claude Sonnet 4.6'
+tools: ['edit', 'search', 'new', 'runCommands', 'runTasks', 'usages', 'problems', 'fetch', 'todos']
+---
+
+# Project Overview
+This project is an SDK developed for vx3, a platform for cryptocurrencies and decentralized systems.
+
+npm pkg name: @vx3/vx
+
+The goals of this SDK tool are:
+
+- Payment and payment dialogs for React and Vue
+- ETH transfer functionality
+- Wallet creation and connection functionality for multiple blockchains
+- Transaction processing
+- NFT creation and publishing functionality to Opensea
+- Sending and receiving tips using cryptocurrencies
+- Content management
+
+This tool is available in the repository at github.com/nk4dev/vx
+
+Please note any changes made in the Readme.
+
+Please implement libraries yourself whenever possible, avoiding the use of additional libraries.
+
+Existing libraries include:
+Expressjs
+Ethersjs
+
+# About Using Bun Rumtime
+This project supports Bun as a runtime environment. You can run the project using Bun for improved performance and efficiency.
+
+# Component generation function compatible with React and Vue
+
+## template generation command
+```bash
+npx vx3 generate component Payment --framework react
+```
+
+## Payment Component Example
+```tsx
+import { Payment } from '@vx3/vx';
+
+export default function App() {
+ return (
+
+
alert('Payment successful!')}
+ onError={(err) => alert('Payment failed: ' + err.message)}
+ />
+
+ );
+}
+```
+
+For Nextjs dynamic routing, use the following code:
+```tsx
+import { useRouter } from 'next/router';
+
+export default function App() {
+ const router = useRouter();
+ const { id } = router.query;
+ return (
+
+
alert('Payment successful!')}
+ onError={(err) => alert('Payment failed: ' + err.message)}
+ />
+
+ );
+}
+```
+
+## Donation example
+```tsx
+import { usePayment, usePaymentStatus, usePaymentDialog } from '@vx3/vx';
+
+export default function App() {
+ const initiatePayment = usePayment();
+ const paymentStatus = usePaymentStatus();
+ const openPaymentDialog = usePaymentDialog();
+
+ const handlePayment = async () => {
+ try {
+ await initiatePayment({
+ to: '0x1234567890abcdef1234567890abcdef12345678',
+ amount: document.getElementById('amountInput').value,
+ currency: 'ETH',
+ });
+ alert('Payment successful!');
+ } catch (err) {
+ alert('Payment failed: ' + err.message);
+ }
+ };
+
+ return (
+
+
Donation Example
+
+
Pay Now
+
Open Payment Dialog
+ {paymentStatus &&
Payment Status: {paymentStatus}
}
+
+ );
+}
+```
+## About Test environment
+Use jest as a testing tool
\ No newline at end of file
diff --git a/.github/instructions/copilot-commit-message.instructions.md b/.github/instructions/copilot-commit-message.instructions.md
new file mode 100644
index 0000000..4d4da17
--- /dev/null
+++ b/.github/instructions/copilot-commit-message.instructions.md
@@ -0,0 +1,35 @@
+Commit messages must conform to the Conventional Commits rules.
+
+## Format
+
+[optional scope]:
+
+[optional body]
+
+[optional footer(s)]
+
+## Type
+
+- `feat`: Adding a new feature
+- `fix`: Bug fix
+- `docs`: Documentation-only changes
+- `style`: Changes that don't affect the semantics of the code (e.g., whitespace, formatting, missing semicolons, etc.)
+- `refactor`: Code changes that don't fix bugs or add features
+- `perf`: Code changes that improve performance
+- `test`: Adding missing tests or modifying existing tests
+- `build`: Changes that affect the build system or external dependencies (e.g., npm, webpack)
+- `ci`: Changes to CI configuration files or scripts
+- `chore`: Other changes (those that don't modify src or test files)
+- `revert`: Reverting a previous commit
+
+## Basic Rules
+
+- The description must be no more than 50 characters in English.
+- For breaking changes, add `!` after the type.
+- Also add a descriptive emoji.
+
+## Example
+
+📝feat: Added user authentication functionality
+
+Implemented a JWT-based authentication system with refresh tokens.
\ No newline at end of file
diff --git a/.github/instructions/japanese-sdk-docs.instructions.md b/.github/instructions/japanese-sdk-docs.instructions.md
new file mode 100644
index 0000000..d0b718d
--- /dev/null
+++ b/.github/instructions/japanese-sdk-docs.instructions.md
@@ -0,0 +1,46 @@
+---
+mode: 'agent'
+description: 'Web3開発ツールキット「VX (VX3)」を使用したdAppsバックエンドやスクリプト環境の構築・拡張に関する支援を提供します。'
+model: 'Claude Sonnet 4.6'
+tools: ['edit', 'search', 'new', 'runCommands', 'runTasks', 'usages', 'problems', 'fetch', 'todos']
+---
+
+# 役割 (Role)
+あなたはシニアWeb3エンジニアであり、TypeScript、Node.js、Bun、およびethers.js (v6) に精通しています。
+現在、Web3開発ツールキット「VX (VX3)」を利用して、新規のdAppsバックエンド(またはスクリプト)環境を構築・拡張するタスクを担当しています。
+
+# 前提条件とコンテキスト (Context & Prerequisites)
+- **ツール**: VX(`@vx3/vx`)は、プロジェクト作成、RPC接続、Hardhat連携、および支払い処理を簡略化するCLI兼SDKです。
+- **言語/フレームワーク**: TypeScript, Node.js (v18+推奨), ethers.js v6, Hardhat
+- **パッケージマネージャ**: npm, pnpm, yarn, または Bun を使用可能です(プロジェクトではBunの利用もサポート・検証されています)。
+- **ドキュメントの要点**:
+ - `vx3 create ` でテンプレートからプロジェクトを作成可能。
+ - `vx3 setup hardhat` でHardhat環境(`hardhat.config.ts`, `Sample.sol`, E2Eスクリプト等)をスキャフォールディング可能。
+ - `vx.config.json` にRPC(http/ws)やIPFSの設定を配列で定義する。
+ - プログラムからは `import vx from "@vx3/vx";` または `import { payment } from "@vx3/vx";` のようにSDKを利用可能。
+
+# 開発タスク指示 (Task Instructions)
+AIエージェントとしてユーザーからタスクを依頼された際は、以下の要件を満たすコードと手順を生成してください。
+
+## 1. プロジェクトの初期化とHardhatセットアップ
+- 新規ディレクトリでVXを用いてプロジェクトを初期化するコマンド手順を提示してください(例としてBunを使用)。
+- Hardhat環境を組み込むためのコマンド(`vx3 setup hardhat` 等)と、必要な依存関係(`hardhat`, `@nomicfoundation/hardhat-toolbox`, `ethers` など)をインストールする手順を含めてください。
+- Bun環境での`ethers`の型エラー解決策(`bun add ethers`)についても必要に応じて言及してください。
+
+## 2. RPC設定ファイルの作成
+- ローカルネットワーク(http://127.0.0.1:8545)と、任意のテストネット(例: Sepolia)のエンドポイントを含む `vx.config.json` の設定例を作成してください。
+
+## 3. 送金スクリプトの実装 (TypeScript)
+- `@vx3/vx` のSDKを利用して、指定したアドレスへETHを送金するスクリプト (`scripts/transfer.ts`) を作成してください。
+- `payment.sendPayment` API を利用し、`rpcUrl`, `privateKey` (環境変数から取得), `to`, `amountEth` を適切に設定してください。
+- **セキュリティのベストプラクティス**: ソースコード内に秘密鍵を直接ハードコードせず、`dotenv` などを利用して読み込む形にしてください。
+
+## 4. ガス代とブロック番号の取得スクリプト
+- SDKを利用し、設定したRPCから現在のブロック番号(`vx.getBlockNumber`)と推奨ガス代 (`vx.getGasFees`) を取得してコンソールに出力するユーティリティ関数を実装してください。
+
+# 出力形式 (Output Format)
+- コマンドライン手順はコードブロック(bashまたはpowershell)で記述すること。
+- TypeScriptのソースコードは、適切なコメントと型定義を含めた完全な形で提示すること。
+- 余分な外部ライブラリの導入は極力避け、VXの組み込み機能(およびethers, dotenvなど必要最小限の依存)を優先して実装すること。
+- 実行時に発生しうるエラー(例:ethersの型エラー、モジュール解決エラー)の回避方法についても言及すること。
+- 原則として回答は**日本語**で行うこと。
\ No newline at end of file
diff --git a/.github/instructions/typescript-5-es2022.instructions.md b/.github/instructions/typescript-5-es2022.instructions.md
new file mode 100644
index 0000000..5cead1e
--- /dev/null
+++ b/.github/instructions/typescript-5-es2022.instructions.md
@@ -0,0 +1,114 @@
+---
+description: 'Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output'
+applyTo: '**/*.ts'
+---
+
+# TypeScript Development
+
+> These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation.
+
+## Core Intent
+
+- Respect the existing architecture and coding standards.
+- Prefer readable, explicit solutions over clever shortcuts.
+- Extend current abstractions before inventing new ones.
+- Prioritize maintainability and clarity, short methods and classes, clean code.
+
+## General Guardrails
+
+- Target TypeScript 5.x / ES2022 and prefer native features over polyfills.
+- Use pure ES modules; never emit `require`, `module.exports`, or CommonJS helpers.
+- Rely on the project's build, lint, and test scripts unless asked otherwise.
+- Note design trade-offs when intent is not obvious.
+
+## Project Organization
+
+- Follow the repository's folder and responsibility layout for new code.
+- Use kebab-case filenames (e.g., `user-session.ts`, `data-service.ts`) unless told otherwise.
+- Keep tests, types, and helpers near their implementation when it aids discovery.
+- Reuse or extend shared utilities before adding new ones.
+
+## Naming & Style
+
+- Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else.
+- Skip interface prefixes like `I`; rely on descriptive names.
+- Name things for their behavior or domain meaning, not implementation.
+
+## Formatting & Style
+
+- Run the repository's lint/format scripts (e.g., `npm run lint`) before submitting.
+- Match the project's indentation, quote style, and trailing comma rules.
+- Keep functions focused; extract helpers when logic branches grow.
+- Favor immutable data and pure functions when practical.
+
+## Type System Expectations
+
+- Avoid `any` (implicit or explicit); prefer `unknown` plus narrowing.
+- Use discriminated unions for realtime events and state machines.
+- Centralize shared contracts instead of duplicating shapes.
+- Express intent with TypeScript utility types (e.g., `Readonly`, `Partial`, `Record`).
+
+## Async, Events & Error Handling
+
+- Use `async/await`; wrap awaits in try/catch with structured errors.
+- Guard edge cases early to avoid deep nesting.
+- Send errors through the project's logging/telemetry utilities.
+- Surface user-facing errors via the repository's notification pattern.
+- Debounce configuration-driven updates and dispose resources deterministically.
+
+## Architecture & Patterns
+
+- Follow the repository's dependency injection or composition pattern; keep modules single-purpose.
+- Observe existing initialization and disposal sequences when wiring into lifecycles.
+- Keep transport, domain, and presentation layers decoupled with clear interfaces.
+- Supply lifecycle hooks (e.g., `initialize`, `dispose`) and targeted tests when adding services.
+
+## External Integrations
+
+- Instantiate clients outside hot paths and inject them for testability.
+- Never hardcode secrets; load them from secure sources.
+- Apply retries, backoff, and cancellation to network or IO calls.
+- Normalize external responses and map errors to domain shapes.
+
+## Security Practices
+
+- Validate and sanitize external input with schema validators or type guards.
+- Avoid dynamic code execution and untrusted template rendering.
+- Encode untrusted content before rendering HTML; use framework escaping or trusted types.
+- Use parameterized queries or prepared statements to block injection.
+- Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes.
+- Favor immutable flows and defensive copies for sensitive data.
+- Use vetted crypto libraries only.
+- Patch dependencies promptly and monitor advisories.
+
+## Configuration & Secrets
+
+- Reach configuration through shared helpers and validate with schemas or dedicated validators.
+- Handle secrets via the project's secure storage; guard `undefined` and error states.
+- Document new configuration keys and update related tests.
+
+## UI & UX Components
+
+- Sanitize user or external content before rendering.
+- Keep UI layers thin; push heavy logic to services or state managers.
+- Use messaging or events to decouple UI from business logic.
+
+## Testing Expectations
+
+- Add or update unit tests with the project's framework and naming style.
+- Expand integration or end-to-end suites when behavior crosses modules or platform APIs.
+- Run targeted test scripts for quick feedback before submitting.
+- Avoid brittle timing assertions; prefer fake timers or injected clocks.
+
+## Performance & Reliability
+
+- Lazy-load heavy dependencies and dispose them when done.
+- Defer expensive work until users need it.
+- Batch or debounce high-frequency events to reduce thrash.
+- Track resource lifetimes to prevent leaks.
+
+## Documentation & Comments
+
+- Add JSDoc to public APIs; include `@remarks` or `@example` when helpful.
+- Write comments that capture intent, and remove stale notes during refactors.
+- Update architecture or design docs when introducing significant patterns.
\ No newline at end of file
diff --git a/.github/instructions/web_docs_generator.instructions.md b/.github/instructions/web_docs_generator.instructions.md
new file mode 100644
index 0000000..f8e7712
--- /dev/null
+++ b/.github/instructions/web_docs_generator.instructions.md
@@ -0,0 +1,34 @@
+---
+description: web_docs_generator instructions for generating documentation for the vx project (Web3).
+# applyTo: 'Describe when these instructions should be loaded' # when provided, instructions will automatically be added to the request context when the pattern matches an attached file
+model: Claude Sonnet 4.6
+---
+
+
+# Web Docs Generator Instructions
+- project: vx3
+- toolname: vx sdk
+- website: https://nknighta.me/vx
+- website base path: /vx/
+- website description: Website Description: vx is a Web3 SDK that provides developers with tools and resources for building decentralized applications (dApps) on the blockchain. It allows for smart contract integration, wallet management and creation, and can connect to multiple blockchains in parallel. vx enables developers to easily create secure and efficient dApps that leverage the power of blockchain technology. It also includes a cryptocurrency payment API.
+
+- documentation: https://nknighta.me/vx/docs
+## Important:
+This site clearly states that this is pre-beta code in development.
+The destination directory is limited to /docs/docs.
+index page should be generated at /docs/index.html
+
+## Tech Stack
+- Programming Language: TypeScript, solidity
+- Frameworks/Libraries: React, Node.js, Express, Ethers.js, Rust
+
+## Documentation Structure
+- CSS: Tailwind CSS
+- Library: Three.js(background animation)
+- Repository: https://github.com/nk4dev/vx
+- Pearent Repository: https://github.com/nk4dev/vx3
+
+## Website requirements
+- code copy button for code snippets
+- responsive design for mobile and desktop
+- buttom nav links https://nknighta.me (owner profile), https://varius.technology (Team website),
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..5156e26
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,44 @@
+name: CI - SDK Tests
+
+on:
+ workflow_dispatch:
+
+jobs:
+ test:
+ name: Test SDK (Node ${{ matrix.node-version }})
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ strategy:
+ matrix:
+ node-version: ['18.x']
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Use Node.js ${{ matrix.node-version }}
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node-version }}
+ cache: 'npm'
+
+ - name: Install SDK dependencies
+ working-directory: .
+ run: |
+ # prefer ci if a lockfile exists, fallback to install otherwise
+ npm ci --silent || npm install --silent
+
+ - name: Build SDK
+ working-directory: .
+ run: npm run build --silent
+
+ - name: Run SDK tests
+ working-directory: .
+ run: npm test --silent
+
+ - name: Upload test results (optional)
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: sdk-jest-results
+ path: sdk/test-results || sdk/jest-results || dist
diff --git a/.gitignore b/.gitignore
index e5d86ea..07cf93a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,13 +1,17 @@
+
node_modules/
dist/
runtest/
-package-lock.json
+cache/
+slug/
+
yarn-error.log
*.log
*.bin
*.tsbuildinfo
bun.lock
+yarn.lock
.vscode/
# Test artifacts
@@ -17,4 +21,4 @@ jest-coverage/
.env
-config
\ No newline at end of file
+config
diff --git a/README.md b/README.md
index 117108d..f20168f 100644
--- a/README.md
+++ b/README.md
@@ -1,220 +1,249 @@
-# VX - Web3 Development Toolkit for VX3
+# VX3 — Web3 Developer SDK
-Useful web3 development tools for creating projects, connecting to RPCs, checking gas, and running a local dev server.
+VX3 is a developer-first toolkit for building, testing, and shipping Web3
+applications. It bundles a CLI, a local development node, a real-time
+dashboard, project scaffolding, payment / gas / IPFS helpers, and **VXC**,
+an in-house custom Solidity compiler.
-> [!WARNING]
-> This project is in active development and has not yet been officially released. Use at your own risk.
+Parent repo & docs:
+SDK docs:
-- project master : https://github.com/nk4dev/vx3
-- update here: https://nknighta.me/vx
-- vx3: https://nknighta.me/dev/vx3
+---
-this project using code generation AI tools.
-- GitHub Copilot [GPT-5, Claude sonnet 4, GPT-5 mini, grok code fast]
-- Google Gemini
-- NotebookLM
+## Highlights
-## Features
-- Connect to multiple chains (ethers v6)
-- Create and manage wallets
-- Local development server with simple APIs
-- Deploy/compile examples (Hardhat samples included)
+- **One CLI for the whole flow** — scaffold, compile, run a node, pay, estimate
+ gas, pin to IPFS, and open a live dashboard.
+- **VXC, a custom Solidity compiler** — own frontend (lexer, import resolver,
+ artifact pipeline) with a pluggable backend.
+ Lives at [`packages/vxc`](packages/vxc/README.md).
+- **Real-time dashboard** — `vx3 dash` opens a dark-themed dev dashboard with
+ live block number, gas fees, RPC status, and an SSE activity log.
+- **Frontend templates** — React and Vue starters, plus a Hardhat package
+ pre-wired for VX3 projects.
+- **Programmatic APIs** — every CLI command is also exposed as a TypeScript
+ function.
-## Requirements
-- Node.js 18+ (recommended; required for built-in `fetch` usage)
-- npm (or pnpm/yarn)
+## Install
-## Installation
```bash
-npm i @nk4dev/vx or npm i -g @nk4dev/vx
-
-vx3 create
+git clone https://github.com/nk4dev/vx
+cd vx
+npm i
+npm run build
+npm link # exposes the `vx3` binary globally
```
-For one-off usage when published: `npx vx3 `
-## Quick start
-- Create a new project (non-interactive):
-```powershell
-vx3 create my-app
-```
-- Create a new project (interactive prompt):
-```powershell
-vx3 create
-```
-- Initialize RPC config template:
-```powershell
-vx3 rpc init
-```
-- Start local dev server (with debug view):
-```powershell
-vx3 serve --debug
-```
-- Check gas info:
-```powershell
-vx3 gas
+## CLI
+
+```bash
+vx3 [...options]
+```
+
+| Command | Description |
+| --- | --- |
+| `init` | Initialize a new project with default settings. |
+| `create [name]` | Scaffold a new project (interactive if name omitted). |
+| `node` | Start a local development node (port 3000). |
+| `dash` | **Open the real-time developer dashboard (port 4000).** |
+| `setup hardhat\|react` | Add Hardhat or a React frontend to the current project. |
+| `rpc` | Manage or query RPC endpoints from `vx.config.json`. |
+| `pay ` | Send a transaction. Flags: `--rpc`, `--key`. |
+| `gas` | Estimate gas fees for a transaction. |
+| `ipfs` | Pin / fetch content via IPFS. |
+| `generate` | Generate templates (react, vue, …). |
+| `compile ` | Compile Solidity using the VXC custom compiler. |
+| `sol hello` | Solidity helper sample. |
+| `info` | Display project / SDK info. |
+| `--version`, `-v` | Show SDK version. |
+| `help` | Show the help screen. |
+
+### Dashboard (`vx3 dash`)
+
+```bash
+vx3 dash # http://127.0.0.1:4000
+vx3 dash --port 5000 # custom port
+vx3 dash --host 0.0.0.0 # bind to all interfaces
+vx3 dash --open # auto-open in browser
```
-## Library usage (import)
-You can use the SDK programmatically via the default export, while CLI features remain unchanged.
+Dashboard endpoints:
-TypeScript/ESM:
-```ts
-import vx from "@nk4dev/vx";
+| Endpoint | Method | Description |
+| --- | --- | --- |
+| `/` | GET | Dashboard HTML |
+| `/api/status` | GET | Server + RPC status |
+| `/api/block` | GET | Latest block number |
+| `/api/gas` | GET | EIP-1559 gas fee data |
+| `/api/rpc` | GET | RPC config list |
+| `/events` | GET | SSE stream (block + gas, every 4 s) |
-const rpc = vx.getRpcUrl(); // from vx.config.json
-const block = await vx.getBlockNumber(rpc);
-const gas = await vx.getGasFees(rpc);
-```
+### Compiling contracts with VXC
-CommonJS:
-```js
-const vx = require("@nk4dev/vx").default;
-vx.getGasFees("http://127.0.0.1:8545").then(console.log);
+```bash
+vx3 compile contracts/Token.sol \
+ --out build \
+ --optimize --runs 1000 \
+ --evm cancun \
+ --remap @openzeppelin/=node_modules/@openzeppelin/
```
-Named exports are still available for backward compatibility:
-```ts
-import { vx as data, instance } from "@nk4dev/vx";
-await data.getBalance("http://127.0.0.1:8545", "0x...");
-```
+Artifacts (`.json` + `vxc.manifest.json`) are written to `--out` and
+are deploy-ready. Full docs: [`packages/vxc/README.md`](packages/vxc/README.md).
-## Project creation (template copy)
-`vx3 create ` (or `vx3 init `) recursively copies the contents of `packages/template` to the `` folder directly under the current directory. A `package.json` file is also generated in the destination directory.
+## Packages
-Template content examples:
-- `packages/template/sample.js`
-- `packages/template/sample.sol`
-- `packages/template/vmx.config.json`
-- `packages/template/contracts/Sample.sol`
+| Package | Path | Purpose |
+| --- | --- | --- |
+| `@vx3/vxc` | `packages/vxc` | Custom Solidity compiler (frontend + pluggable backend). |
+| `@vx3/hardhat` | `packages/hardhat` | Hardhat config preset for VX3 projects. |
+| `@vx3/template` | `packages/template` | Default project template. |
+| `@vx3/react-template` | `packages/react-template` | React starter. |
+| `@vx3/vue-template` | `packages/vue-template` | Vue starter. |
-Template directory resolution searches the following candidates in order (accommodating development/distribution differences):
-1) When running `dist`: `../../packages/template`
-2) When running TS/config: `../../../packages/template`
-3) Directly under the repository: `/packages/template`
+## Development
-If not found, it will issue a warning and create only a minimal setup (`package.json`).
-## Hardhat setup
-Scaffold Hardhat files into the current project:
+```bash
+npm run build # compile TypeScript → dist/
+npm test # jest test suite
+npm run lint # eslint
+npm run format # prettier
-```powershell
-vx3 setup hardhat
-# then install dev dependencies
+# Build the VXC compiler package separately
+cd packages/vxc && npx tsc
```
-## RPC configuration(vx.config.json)
-
-`vx3 rpc init` creates an RPC configuration template. The current template is an array, and the loader uses the first object.
+## Contact
-```json
-[
- { "host": "localhost", "port": 8575, "protocol": "http" }
-]
-```
+[nknighta@varius.technology](mailto:nknighta@varius.technology)
-In the future, we may standardize on a single object format.
-
-## Debug page (Tailwind UI)
-`vx3 serve --debug` serves a TailwindCSS-powered debug dashboard at `/debug`:
-- Shows server host and the latest block number
-- Quick links: `/api`, `/api/block`
-- "Usage" section with example fetch calls
-
-### Gas Command Example Output
-```text
-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
-```
+## License
+MIT
-## Libraries
-- express(debug/local server)
-- ethers.js(RPC/chain operations)
+---
+---
-## UI frameworks that will be supported in the future
-- React
-- Vue.js
-- Svelte
-- Next.js
+# VX3 — Web3 開発者 SDK
+VX3 は Web3 アプリケーションの構築・テスト・リリースに必要な機能をまとめた
+開発者向けツールキットです。CLI、ローカル開発ノード、リアルタイムダッシュボード、
+プロジェクトスキャフォールディング、支払い / ガス / IPFS ヘルパー、
+そして独自カスタム Solidity コンパイラ **VXC** を含みます。
-## Payment module — API and CLI (Bun runtime)
+親リポジトリ & ドキュメント:
+SDK ドキュメント:
+日本語ガイド(詳細): [`docs/ja/guide.md`](docs/ja/guide.md)
-This repository now includes a reusable payment module that can be used both from the CLI and programmatically from your code.
+---
-What was added
-- `src/payment/index.ts` — a small helper that exports `sendPayment(options)`.
-- `src/command/pay.ts` — CLI wrapper that calls `sendPayment`.
-- `src/index.ts` — the library entry now exposes the payment namespace so you can call it from code: `vx.payment.sendPayment(...)` or `import { payment } from '@nk4dev/vx'`.
+## 特徴
-Programmatic usage
+- **ワークフロー全体を 1 つの CLI で** — スキャフォールド、コンパイル、
+ ノード起動、送金、ガス推定、IPFS ピン留め、そしてライブダッシュボード。
+- **VXC カスタム Solidity コンパイラ** — 独自フロントエンド(レキサー、
+ import リゾルバ、アーティファクトパイプライン)とプラグイン可能なバックエンド。
+ [`packages/vxc`](packages/vxc/README.md) に格納。
+- **リアルタイムダッシュボード** — `vx3 dash` でダーク UI の開発ダッシュボードを起動。
+ ライブブロック番号、ガス料金、RPC ステータス、SSE アクティビティログを表示。
+- **フロントエンドテンプレート** — React・Vue スターター、VX3 プロジェクト向け
+ Hardhat パッケージを同梱。
+- **プログラマティック API** — すべての CLI コマンドは TypeScript 関数としても提供。
-TypeScript/ESM example:
-```ts
-import vx from '@nk4dev/vx';
+## インストール
-await vx.payment.sendPayment({
- rpcUrl: 'http://127.0.0.1:8545',
- privateKey: process.env.PRIVATE_KEY!,
- to: '0xRecipientAddressHere',
- amountEth: '0.01'
-});
+```bash
+git clone https://github.com/nk4dev/vx
+cd vx
+npm i
+npm run build
+npm link # `vx3` バイナリをグローバルに公開
```
-Named import:
-```ts
-import { payment } from '@nk4dev/vx';
-await payment.sendPayment({ rpcUrl, privateKey, to, amountEth: '0.01' });
-```
+## CLI
-CLI usage (recommended: use environment variable for private key):
-```powershell
-#$env:PRIVATE_KEY='0x...'
-vx3 pay 0xRecipientAddress 0.01 --rpc http://127.0.0.1:8545
+```bash
+vx3 <コマンド> [...オプション]
+```
+
+| コマンド | 説明 |
+| --- | --- |
+| `init` | デフォルト設定で新規プロジェクトを初期化。 |
+| `create [name]` | プロジェクトをスキャフォールド(名前省略時は対話モード)。 |
+| `node` | ローカル開発ノードを起動(ポート 3000)。 |
+| `dash` | **リアルタイム開発ダッシュボードを起動(ポート 4000)。** |
+| `setup hardhat\|react` | Hardhat または React フロントエンドを追加。 |
+| `rpc` | `vx.config.json` の RPC エンドポイントを管理・参照。 |
+| `pay ` | トランザクション送信。オプション: `--rpc`, `--key`。 |
+| `gas` | ガス料金を推定。 |
+| `ipfs` | IPFS 経由でコンテンツをピン留め / 取得。 |
+| `generate` | テンプレートを生成(react, vue など)。 |
+| `compile ` | VXC カスタムコンパイラで Solidity をコンパイル。 |
+| `sol hello` | Solidity ヘルパーサンプル。 |
+| `info` | プロジェクト / SDK 情報を表示。 |
+| `--version`, `-v` | SDK バージョンを表示。 |
+| `help` | ヘルプ画面を表示。 |
+
+### ダッシュボード(`vx3 dash`)
+
+```bash
+vx3 dash # http://127.0.0.1:4000
+vx3 dash --port 5000 # ポート指定
+vx3 dash --host 0.0.0.0 # 全インターフェースにバインド
+vx3 dash --open # ブラウザを自動で開く
```
-Run/Build (using Bun)
+ダッシュボードのエンドポイント:
-I ran the project build using the Bun runtime. Recommended steps on your machine:
+| エンドポイント | メソッド | 説明 |
+| --- | --- | --- |
+| `/` | GET | ダッシュボード HTML |
+| `/api/status` | GET | サーバー + RPC ステータス |
+| `/api/block` | GET | 最新ブロック番号 |
+| `/api/gas` | GET | EIP-1559 ガス料金データ |
+| `/api/rpc` | GET | RPC 設定リスト |
+| `/events` | GET | SSE ストリーム(ブロック + ガス、4 秒ごと) |
-```powershell
-# install dependencies with Bun
-bun install
-# compile TypeScript
-bun run build
+### VXC でコントラクトをコンパイル
+
+```bash
+vx3 compile contracts/Token.sol \
+ --out build \
+ --optimize --runs 1000 \
+ --evm cancun \
+ --remap @openzeppelin/=node_modules/@openzeppelin/
```
-Observed build notes
-- I executed `bun install` and `bun run build` in this repository. TypeScript was invoked via `tsc`.
-- The build surfaced TypeScript diagnostics in the workspace while compiling. Two notable issues were observed during the run:
- 1. TypeScript could not find module declarations for `ethers` (error: "Cannot find module 'ethers' or its corresponding type declarations"). If you encounter this, run:
- ```powershell
- bun add ethers
- # then
- bun run build
- ```
- or install via `npm install` if you prefer.
- 2. `packages/react-template/tsconfig.json` references the `vite/client` type and a deprecated `moduleResolution` option; this may produce an informational TypeScript diagnostic. Install the Vite types or adjust the `tsconfig.json` in that package if you plan to compile the template.
+アーティファクト(`.json` + `vxc.manifest.json`)は `--out` に出力され、
+デプロイ可能な状態で保存されます。
+詳細: [`packages/vxc/README.md`](packages/vxc/README.md)
+
+## パッケージ
+
+| パッケージ | パス | 用途 |
+| --- | --- | --- |
+| `@vx3/vxc` | `packages/vxc` | カスタム Solidity コンパイラ(フロントエンド + プラグイン可能バックエンド)。 |
+| `@vx3/hardhat` | `packages/hardhat` | VX3 プロジェクト向け Hardhat 設定プリセット。 |
+| `@vx3/template` | `packages/template` | デフォルトプロジェクトテンプレート。 |
+| `@vx3/react-template` | `packages/react-template` | React スターター。 |
+| `@vx3/vue-template` | `packages/vue-template` | Vue スターター。 |
-Security notes
-- Avoid passing secrets on the command line. Prefer environment variables (for example `PRIVATE_KEY`) or an external signer.
-- The current `sendPayment` helper expects a raw private key (hex). Consider extending the API to accept a Signer, hardware wallet integration, or a key management provider for production usage.
+## 開発
-Next steps and tests
-- Add an integration test that starts a local Hardhat node and runs an end-to-end payment using `payment.sendPayment`.
-- Consider adding typed wrappers using `ethers.parseUnits` for gas values and stronger validation.
+```bash
+npm run build # TypeScript → dist/ にコンパイル
+npm test # jest テストスイート
+npm run lint # eslint
+npm run format # prettier
+
+# VXC コンパイラパッケージを個別にビルド
+cd packages/vxc && npx tsc
+```
-If you'd like, I can (a) run the `bun add ethers` and re-run the build here and fix remaining diagnostics, (b) add the README snippet to the docs site, or (c) scaffold an automated integration test using Hardhat.
+## 連絡先
-## Author
-Maintainer: [nk4dev](https://nk4dev.github.io/)
+[nknighta@varius.technology](mailto:nknighta@varius.technology)
-# License
-MIT License © nk4dev
+## ライセンス
-This project is licensed under the MIT License, see the LICENSE.txt file for details
+MIT
diff --git a/docs/index.css b/docs/index.css
deleted file mode 100644
index bca713f..0000000
--- a/docs/index.css
+++ /dev/null
@@ -1,226 +0,0 @@
-:root {
- --bg: #fbfbfc;
- --card: #fff;
- --muted: #666
-}
-
-.info {
- background: #ffff99;
-}
-
-#information {
- background: #000;
- color: #fff;
- display: flex;
- flex-direction: column;
-}
-
-#version-m {
- display: none;
-}
-#information a {
- color: #fff;
- margin-top: 4px;
-}
-
-body {
- font-family: Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial;
- background: var(--bg);
- color: #111;
- margin: 0
-}
-
-header {
- background: #111;
- color: #fff;
- padding: 20px
-}
-
-header a {
- color: #fff;
- text-decoration: none
-}
-
-main {
- max-width: 980px;
- margin: 28px auto;
- padding: 20px
-}
-
-h1 {
- font-size: 28px;
- margin: 0 0 12px
-}
-
-h2 {
- font-size: 20px;
- margin: 20px 0 8px
-}
-
-pre {
- background: #0f1724;
- color: #e6eef8;
- padding: 12px;
- border-radius: 6px;
- overflow: auto
-}
-
-code {
- padding: 2px 6px;
- border-radius: 4px
-}
-
-section.card {
- background: var(--card);
- border-radius: 8px;
- padding: 16px;
- margin: 12px 0;
- box-shadow: 0 1px 2px rgba(0, 0, 0, .04)
-}
-
-ul {
- margin: 8px 0 0 20px
-}
-
-footer {
- max-width: 980px;
- margin: 12px auto;
- padding: 12px;
- color: var(--muted);
- font-size: 13px
-}
-
-/* Hamburger button and responsive nav styles */
-.hamburger {
- display: none;
- /* shown on small screens */
- background: transparent;
- border: none;
- cursor: pointer;
- margin-left: 8px;
- width: 38px;
- height: 28px;
- padding: 4px;
- color: inherit;
-}
-
-.hamburger:focus {
- outline: 2px solid rgba(255, 255, 255, 0.12);
- outline-offset: 2px
-}
-
-.hamburger-box {
- display: inline-block;
- width: 24px;
- height: 16px;
- position: relative
-}
-
-.hamburger-inner {
- display: block;
- width: 24px;
- height: 2px;
- border-radius: 2px;
- background: #fff;
- position: absolute;
- left: 0;
- top: 50%;
- transform: translateY(-50%);
- transition: transform .18s ease, background .18s ease
-}
-
-.hamburger-inner::before,
-.hamburger-inner::after {
- content: "";
- display: block;
- width: 24px;
- height: 2px;
- border-radius: 2px;
- background: #fff;
- position: absolute;
- left: 0;
- transition: transform .18s ease, opacity .18s ease
-}
-
-.hamburger-inner::before {
- top: -8px
-}
-
-.hamburger-inner::after {
- top: 8px
-}
-
-.hamburger[aria-expanded="true"] .hamburger-inner {
- background: transparent
-}
-
-.hamburger[aria-expanded="true"] .hamburger-inner::before {
- transform: translateY(8px) rotate(45deg)
-}
-
-.hamburger[aria-expanded="true"] .hamburger-inner::after {
- transform: translateY(-8px) rotate(-45deg)
-}
-
-.main-nav {
- margin-left: 12px;
- display: flex;
- gap: 8px;
- align-items: center
-}
-
-@media (max-width: 720px) {
- #version {
- display: none
- }
- #version {
- display: none
- }
- #version-m {
- display: block
- }
- .header-inner {
- display: flex;
- justify-content: space-between;
- }
- .hamburger {
- display: inline-flex;
- align-items: center;
- justify-content: center
- }
-
- header {
- padding-bottom: 12px
- }
-
- .main-nav {
- display: none
- }
-
- .main-nav.open {
- display: block;
- position: absolute;
- left: 12px;
- right: 12px;
- top: 68px;
- background: #111;
- color: #fff;
- padding: 12px;
- border-radius: 8px;
- box-shadow: 0 6px 18px rgba(0, 0, 0, 0.4);
- z-index: 1000;
- font-size: 16px;
- }
-
- .main-nav.open a {
- color: #fff;
- display: block;
- padding: 8px 0;
- text-decoration: none
- }
-
- .main-nav.open a+a {
- border-top: 1px solid rgba(255, 255, 255, 0.06);
- padding-top: 10px
- }
-}
\ No newline at end of file
diff --git a/docs/index.html b/docs/index.html
index 310ad76..f92c992 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,304 +1,123 @@
-
-
-
-
- VX SDK — Documentation
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- this project is not released yet.
- VX — Small Web3 CLI SDK
- This document was generated by analyzing the current workspace. It summarizes structure, usage,
- and known caveats to help developers and automated agents get started quickly.
-
-
- 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
-
- Install deps: npm install
- Build: npm run build
- Run CLI: npm run dev or npx vx3 <command>
- Local server: npx vx3 serve --debug
- 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
-
-
-
- This documentation was generated automatically. Tell me if you want more details, examples, or additional
- pages
-
-
-
-
-
-
-
\ No newline at end of file
+ }, 1000);
+
+