VX SDK — ドキュメント

概要 (Overview)

VX SDK (@nk4dev/vx / vx3) は、 Web3 アプリケーション（dApps）の開発を加速するための TypeScript 製 CLI ツール兼 SDK です。スマートコントラクト統合・ウォレット管理・マルチチェーン RPC 接続・暗号通貨決済 API を提供します。

🔗 RPC 接続

Ethereum 互換チェーンへの HTTP/WS RPC 接続を設定ファイルで管理

💸 決済 API

ETH 送金・ React/Vue 向け Payment コンポーネントを内蔵

⛏️ Hardhat 統合

1 コマンドで Hardhat 開発環境をスキャフォールディング

📦 IPFS

CLI から直接 IPFS コンテンツを取得

GitHub (vx) · GitHub (vx3 parent) · npm: @nk4dev/vx

インストール

npm、pnpm、yarn、または Bun のいずれかでインストールできます。

npm

npm install -g @nk4dev/vx

pnpm

pnpm add -g @nk4dev/vx

Bun

bun add -g @nk4dev/vx

ローカルプロジェクト依存として追加

npm install @nk4dev/vx

インストール後、バージョンを確認：

vx3 --version

クイックスタート

1. 新規プロジェクトを作成：

vx3 create my-dapp

2. ディレクトリに移動し、Hardhat をセットアップ（任意）：

cd my-dapp
vx3 setup hardhat

3. SDK をプログラムから使用：

import vx from '@nk4dev/vx';

const blockNumber = await vx.getBlockNumber('https://eth.llamarpc.com');
console.log('Block:', blockNumber);

vx.config.json

プロジェクトルートに vx.config.json を配置することで、RPC エンドポイントや IPFS 設定を管理します。配列形式で複数エンドポイントを定義できます。

[
  {
    "host": "127.0.0.1",
    "port": 8545,
    "protocol": "http",
    "type": "rpc"
  },
  {
    "host": "eth.llamarpc.com",
    "port": 443,
    "protocol": "https",
    "type": "rpc"
  }
]

フィールド	型	説明
`host`	string	RPC ホスト名または IP アドレス
`port`	number	ポート番号
`protocol`	string	`http` \| `https` \| `ws` \| `wss`
`type`	string	`rpc` \| `ipfs`

CLI リファレンス

vx3 create <name>

テンプレートから新しい VX プロジェクトを作成します。name を省略するとインタラクティブモードに入ります。

vx3 create my-dapp
# または対話モード
vx3 create

エイリアス: vx3 init

vx3 setup hardhat

Hardhat 開発環境を現在のプロジェクトにスキャフォールディングします（hardhat.config.ts、サンプルコントラクト、デプロイスクリプト等）。

vx3 setup hardhat

vx3 rpc

RPC 設定の管理を行うサブコマンド群です。

vx3 rpc list                        # 設定一覧を表示
vx3 rpc create                      # 新しい設定を作成
vx3 rpc add                         # エンドポイントを追加
vx3 rpc save --host <h> --port <p> --protocol <p>
vx3 rpc load                        # 設定を読み込み
vx3 rpc help                        # ヘルプを表示

vx3 gas

RPC エンドポイントから現在のガス代を取得して表示します。

# vx.config.json の最初のエントリを使用
vx3 gas

# RPC を直接指定
vx3 gas --rpc https://eth.llamarpc.com

# 設定ファイルのパスを指定
vx3 gas --path ./vx.config.json

出力: baseFeePerGas、maxPriorityFeePerGas、maxFeePerGas、gasPrice (legacy) を gwei 単位で表示

vx3 pay <to> <amount>

指定アドレスへ ETH を送金します。秘密鍵は環境変数 PRIVATE_KEY から読み込まれます。

# 基本的な使用法 (vx.config.json から RPC 取得)
vx3 pay 0xRecipientAddress 0.01

# RPC と秘密鍵を直接指定
vx3 pay 0xRecipient 0.01 --rpc https://eth.llamarpc.com --key 0xYourPrivateKey

# ショートフラグ
vx3 pay 0xRecipient 0.05 -r http://localhost:8545 -k 0xPrivateKey

⚠️ セキュリティ: 秘密鍵は --key フラグではなく PRIVATE_KEY 環境変数または .env ファイルで管理することを強く推奨します。

vx3 ipfs fetch <cid>

IPFS CID を指定してコンテンツを取得します。カスタムゲートウェイ URL も指定可能です。

# デフォルトゲートウェイを使用
vx3 ipfs fetch QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

# カスタムゲートウェイを指定
vx3 ipfs fetch <cid> https://cloudflare-ipfs.com/ipfs/

vx3 serve

ローカル開発サーバーを起動します。

vx3 serve

vx3 info / --version

SDK バージョンやプロジェクト情報を確認します。

vx3 --version   # ローカルバージョン
vx3 -v
vx3 info        # リモート API からバージョン情報を取得

SDK API リファレンス

@nk4dev/vx をインポートしてプログラムから利用できます。ESM / CJS 両方に対応しています。

// ESM default import
import vx from '@nk4dev/vx';

// Named imports
import { payment } from '@nk4dev/vx';

// CJS
const vx = require('@nk4dev/vx');

vx.getBlockNumber(provider)

指定した RPC プロバイダーから最新のブロック番号を取得します。

パラメータ	型	説明
`provider`	string	RPC エンドポイント URL

戻り値: Promise<number>

const block = await vx.getBlockNumber('https://eth.llamarpc.com');
console.log('Latest block:', block);

vx.getBalance(provider, address)

指定アドレスの ETH 残高を取得します（ETH 単位の number）。

パラメータ	型	説明
`provider`	string	RPC エンドポイント URL
`address`	string	Ethereum アドレス (0x...)

戻り値: Promise<number> (ETH 単位)

const balance = await vx.getBalance(
  'https://eth.llamarpc.com',
  '0xYourAddress'
);
console.log(`Balance: ${balance} ETH`);

vx.getGasFees(provider)

EIP-1559 対応のガス代情報を取得します。未対応ネットワークではレガシー gasPrice にフォールバックします。

パラメータ	型	説明
`provider`	string	RPC エンドポイント URL

戻り値: Promise<GasFees>

type GasFees = {
  unit: 'gwei' | 'wei';
  gasPriceGwei?: string;
  maxFeePerGasGwei?: string;
  maxPriorityFeePerGasGwei?: string;
  baseFeePerGasGwei?: string;
  raw: {
    gasPrice?: bigint | null;
    maxFeePerGas?: bigint | null;
    maxPriorityFeePerGas?: bigint | null;
    baseFeePerGas?: bigint | null;
  };
};

const fees = await vx.getGasFees('https://eth.llamarpc.com');
console.log('baseFee:', fees.baseFeePerGasGwei, 'gwei');
console.log('maxFee :', fees.maxFeePerGasGwei, 'gwei');

vx.payment.sendPayment(opts)

トランザクションを構築し指定アドレスへ ETH を送金します。確認まで待機して Receipt を返します。

オプション	型	必須	説明
`rpcUrl`	string	✓	RPC エンドポイント URL
`privateKey`	string	✓	送信者の秘密鍵 (hex)
`to`	string	✓	受信者アドレス
`amountEth`	string	✓	送金額 (ETH 単位, 例: "0.01")
`maxFeePerGas`	string	-	最大ガス代 (gwei 文字列)
`maxPriorityFeePerGas`	string	-	優先ガス代 (gwei 文字列)
`gasLimit`	number	-	ガスリミット

戻り値: Promise<{ txHash: string; receipt?: any }>

import vx from '@nk4dev/vx';
import 'dotenv/config';

const result = await vx.payment.sendPayment({
  rpcUrl: 'https://eth.llamarpc.com',
  privateKey: process.env.PRIVATE_KEY!,
  to: '0xRecipientAddress',
  amountEth: '0.01',
});

console.log('TX Hash:', result.txHash);
console.log('Block:', result.receipt?.blockNumber);

vx.getRpcUrl()

vx.config.json を読み込み、最初のエントリから RPC URL 文字列を構築して返します。

戻り値: string

import vx from '@nk4dev/vx';

const url = vx.getRpcUrl();
// => "https://eth.llamarpc.com:443"

React コンポーネント

<Payment />

ワンクリック ETH 決済を実現する React コンポーネントです。

import { Payment } from '@nk4dev/vx';

export default function App() {
  return (
    <Payment
      to="0x1234567890abcdef1234567890abcdef12345678"
      amount="0.01"
      currency="ETH"
      onSuccess={() => alert('Payment successful!')}
      onError={(err) => alert('Failed: ' + err.message)}
    />
  );
}

Props	型	説明
`to`	string	受信者 Ethereum アドレス
`amount`	string	送金額 (ETH 単位)
`currency`	string	通貨 (例: `"ETH"`)
`onSuccess`	() => void	決済成功時コールバック
`onError`	(err: Error) => void	エラー時コールバック

React Hooks

より細かい制御が必要な場合は Hooks を使用します。

import { usePayment, usePaymentStatus, usePaymentDialog } from '@nk4dev/vx';

export default function DonateButton() {
  const initiatePayment = usePayment();

  const handleDonate = async () => {
    try {
      await initiatePayment({
        to: '0xRecipientAddress',
        amount: '0.005',
        currency: 'ETH',
      });
    } catch (err) {
      console.error(err);
    }
  };

  return <button onClick={handleDonate}>Donate ETH</button>;
}

Hardhat 統合

vx3 setup hardhat を実行すると、以下のファイルが自動生成されます：

packages/hardhat/hardhat.config.ts
packages/hardhat/contract/ — サンプルコントラクト
packages/hardhat/scripts/deploy.ts — デプロイスクリプト
packages/hardhat/typechain-types/ — 型定義

Hardhat コマンド

# コンパイル
npm run hh:compile

# ローカルノード起動
npm run hh:node

# デプロイ (localhost)
npm run hh:deploy

# テスト実行
npm run hh:test

Bun 環境での ethers 型エラー対処

bun add ethers

ライセンス

Repository: github.com/nk4dev/vx