jaspervault_cli 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# JasperVault CLI (`jv`)
+
+Trade perpetuals on JasperVault through AI conversation. Install this CLI and connect your AI assistant (OpenClaw, Cursor, Claude Code) — then just talk to place orders, set take-profits, and manage positions without touching the command line.
+
+---
+
+## Quick Start (OpenClaw)
+
+### 1. Install the CLI
+
+```bash
+npm install -g jaspervault_cli
+```
+
+Verify:
+
+```bash
+jv --version
+```
+
+### 2. Install JasperVault Skill to OpenClaw
+
+```bash
+jv init --ai openclaw
+```
+
+This installs the trading skill to `~/.openclaw/skills/jasper-vault-cli/SKILL.md`. OpenClaw will now know how to trade on your behalf.
+
+> If the skill already exists, add `--force` to overwrite:
+> ```bash
+> jv init --ai openclaw --force
+> ```
+
+### 3. Initialize Your Wallet (One-Time Setup)
+
+In OpenClaw, say:
+
+> **"I want to start trading"**
+
+OpenClaw will call `jv vault init-wc`, which displays a QR code. Scan it with your mobile wallet (MetaMask Mobile, Rabby, etc.) and confirm the delegation signature on your phone. Done — no private key export required.
+
+Or run it manually in the terminal:
+
+```bash
+jv vault init-wc --network jaspervault --pretty
+```
+
+### 4. Start Trading
+
+Just talk to OpenClaw. Examples:
+
+- "Go long JBTC with 100 JUSDC, 50x leverage"
+- "Set take-profit for order 99 at 105000"
+- "Show my current positions"
+
+---
+
+## Install for Other AI Platforms
+
+```bash
+jv init --ai cursor              # Cursor (current project)
+jv init --ai cursor --global     # Cursor (user-level)
+jv init --ai claude              # Claude Code (current project)
+jv init --ai claude --global     # Claude Code (user-level)
+jv init --ai all                 # All platforms at once
+```
+
+Options:
+- `--global` — Install to user home instead of current project (cursor/claude only)
+- `--force` — Overwrite existing skill file without prompting
+
+---
+
+## Configuration
+
+All configuration is done via environment variables. For most users, **no configuration is needed** — the CLI connects to the JasperVault test environment by default.
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `JV_API_URL` | No | Trading API base URL | `https://trading-api-test.jaspervault.pro` |
+| `JV_API_KEY` | No | Bearer token for API authentication | — |
+| `JV_TIMEOUT` | No | Request timeout in ms | `30000` |
+| `JV_DELEGATION_KEY` | No | Delegation wallet private key override; auto-generated on first `vault init` | from `~/.jaspervault/keys.json` |
+| `JV_BASE_RPC_URL` | No | Base chain RPC URL override (for deposit) | built-in |
+| `JV_JASPERVAULT_RPC_URL` | No | JasperVault chain RPC URL override | built-in |
+| `JV_SUBGRAPH_URL` | No | Subgraph endpoint override | built-in per network |
+| `WC_PROJECT_ID` | No | WalletConnect Cloud project ID (get one at [cloud.reown.com](https://cloud.reown.com)) | — |
+| `PRIVATE_KEY` | No* | EOA wallet private key; only needed for traditional `vault init` and `deposit` | — |
+
+\* Not required when using the WalletConnect flow (`vault init-wc`, `deposit info`).
+
+### Connecting to a Different Environment
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export JV_API_URL=https://your-api-endpoint.example.com
+```
+
+Then restart your terminal or run `source ~/.zshrc`.
+
+### How Credentials Are Stored
+
+After the first successful `jv vault init` or `jv vault init-wc`, the delegation wallet is saved to `~/.jaspervault/keys.json` and your vault profile to `~/.jaspervault/profile.json`. The CLI reads these automatically — no manual configuration needed for subsequent operations.
+
+---
+
+## Funding Your Account (Optional)
+
+To deposit tokens from Base to JasperVault, tell OpenClaw:
+
+> **"Deposit 100 JUSDC into my vault"**
+
+OpenClaw will fetch the transaction data and send it to your phone via WalletConnect for approval.
+
+---
+
+## Full Command Reference
+
+For a complete list of available commands and trading examples, see the documentation:
+
+- [User Guide](docs/USER_GUIDE.md) — Full CLI reference including all commands and options
+- [OpenClaw Setup Guide](docs/OPENCLAW_GUIDE.md) — Detailed walkthrough for OpenClaw users
+
+---
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run build
+npm link              # makes `jv` available globally from local source
+
+npm run typecheck     # TypeScript type checking
+npm test              # Run tests
+npm run dev -- orders list --pretty  # Run via tsx without building
+```

package/config/chains.json

@@ -0,0 +1,104 @@
+{
+  "networks": {
+    "base_uat": {
+      "name": "Base UAT",
+      "chainId": 8453,
+      "rpcUrl": "https://base-mainnet.g.alchemy.com/v2/igHoSYAWMvPX86unqNbyZ",
+      "contracts": {
+        "diamond": "0xB571399F2824424D4c15496406Ea7ACBc1a276AB",
+        "vaultFactory": "0x54d365E5E31472108e6AE5bdF89d85912d1A428E",
+        "perpsOptionModuleHandle": "0x2BB0319B622058F8090b6742705Eb80F8dcC3cdc",
+        "optionModuleV2": "0x4De345778a85Cf12aF49c423c75Fe02C5799d425"
+      },
+      "tokens": {
+        "JBTC": { "address": "0xf3cEe52BDa02DaE997D00A0Bf8d221C4f129ebaF", "decimals": 8 },
+        "CBBTC": { "address": "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf", "decimals": 8 },
+        "JUSDC": { "address": "0x6e236176D1B473Bdb770CDDF4d257B877F2DA9db", "decimals": 6 },
+        "USDC": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6 }
+      },
+      "marginAsset": { "symbol": "JUSDC", "address": "0x6e236176D1B473Bdb770CDDF4d257B877F2DA9db", "decimals": 6 },
+      "writers": {
+        "JBTC": { "long": "0x2D0640Bc9624fd3B66D07FE54C223F138B0391Aa", "short": "0x71c44CF5Ca04b1a2a1A5bA93081DA89183AAc0b6" },
+        "CBBTC": { "long": "0x97cDCF310653a2Cbefee479adE77AD8D3De99dF1", "short": "0x71c44CF5Ca04b1a2a1A5bA93081DA89183AAc0b6" }
+      },
+      "defaultLeverage": 50,
+      "quoteCenterUrl": "https://quotecenterv2-uat-gcx2x.ondigitalocean.app",
+      "subgraphUrl": "https://subgraph.satsuma-prod.com/0981c2ab3685/garys-team/jaspervault-v2-base-uat/api"
+    },
+    "jaspervault": {
+      "name": "JasperVault",
+      "chainId": 55531,
+      "rpcUrl": "https://enterprise.onerpc.com/apikey/42b59vURnC9pSN2XWPunWiYWTeUOU6Mh/jasper_mainnet",
+      "contracts": {
+        "diamond": "0xAfD11c2d9350B2080eD601Ba64ea9f1F532A093c",
+        "vaultFactory": "0x54d365E5E31472108e6AE5bdF89d85912d1A428E",
+        "perpsOptionModuleHandle": "0xcbCCf074E030CDfd907375B00449B4f10d7d475f",
+        "optionModuleV2": "0x0f487603edE93a5329023512B7dcdA632eD70Ed5"
+      },
+      "tokens": {
+        "JBTC": { "address": "0xCb9d5Ae34cc0476BD8Cb22Aa9C21545be4e38bf2", "decimals": 8 },
+        "JUSDC": { "address": "0x567717052247C5Fa302fb2E8DF681A07D63E9faF", "decimals": 6 },
+        "CBBTC": { "address": "0x821DF7b83c9FCba013B37490CFC4B5a0bDe36220", "decimals": 8 }
+      },
+      "marginAsset": { "symbol": "JUSDC", "address": "0x567717052247C5Fa302fb2E8DF681A07D63E9faF", "decimals": 6 },
+      "writers": {
+        "JBTC": { "long": "0xfe7fe5D5de9a8B0BcF39D8676d0C92065a3ca20f", "short": "0x7c7900E40652A9C2225cf6d1E96c38606407e5B0" }
+      },
+      "defaultLeverage": 50,
+      "quoteCenterUrl": "https://uat-jasperquotecenterv2.fly.dev",
+      "subgraphUrl": "https://subgraph.satsuma-prod.com/0981c2ab3685/garys-team/jaspervault-v2-base-uat/api"
+    }
+  },
+  "warpRoutes": {
+    "jbtc": {
+      "symbol": "jBTC",
+      "decimals": 8,
+      "base": {
+        "underlyingToken": "0xf3cEe52BDa02DaE997D00A0Bf8d221C4f129ebaF",
+        "warpRouter": "0xf29d79382d5d092193F0746671397410490e51fF"
+      },
+      "jaspervault": {
+        "domain": 55531,
+        "warpRouter": "0xCb9d5Ae34cc0476BD8Cb22Aa9C21545be4e38bf2"
+      }
+    },
+    "jusdc": {
+      "symbol": "jUSDC",
+      "decimals": 6,
+      "base": {
+        "underlyingToken": "0x6e236176D1B473Bdb770CDDF4d257B877F2DA9db",
+        "warpRouter": "0x7C475c87b8AA7609073e1be3d3CEB62BbbD5276a"
+      },
+      "jaspervault": {
+        "domain": 55531,
+        "warpRouter": "0x567717052247C5Fa302fb2E8DF681A07D63E9faF"
+      }
+    },
+    "cbbtc": {
+      "symbol": "cBBTC",
+      "decimals": 8,
+      "base": {
+        "underlyingToken": "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf",
+        "warpRouter": "0xf08d7Be10E69BD5B7FfCb65612720a747C9B8Bed"
+      },
+      "jaspervault": {
+        "domain": 55531,
+        "warpRouter": "0x821DF7b83c9FCba013B37490CFC4B5a0bDe36220"
+      }
+    },
+    "usdc": {
+      "symbol": "USDC",
+      "decimals": 6,
+      "base": {
+        "underlyingToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "warpRouter": "0xDe0f17681123CbE998E7896B74a197937123b3D9"
+      },
+      "jaspervault": {
+        "domain": 55531,
+        "warpRouter": "0x23559FcF18896ed3280c4d7106ca74fFda14bd79"
+      }
+    }
+  },
+  "defaultBaseRpc": "https://base-mainnet.g.alchemy.com/v2/igHoSYAWMvPX86unqNbyZ",
+  "defaultJaspervaultRpc": "https://enterprise.onerpc.com/apikey/42b59vURnC9pSN2XWPunWiYWTeUOU6Mh/jasper_mainnet"
+}

package/dist/bin/jv.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/jv.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerOrderCommand } from '../src/commands/order.js';
+import { registerJobCommand } from '../src/commands/job.js';
+import { registerLimitOrderCommand } from '../src/commands/limit-order.js';
+import { registerOrdersCommand } from '../src/commands/orders.js';
+import { registerTpCommand } from '../src/commands/tp.js';
+import { registerSlCommand } from '../src/commands/sl.js';
+import { registerVaultCommand } from '../src/commands/vault.js';
+import { registerDepositCommand } from '../src/commands/deposit.js';
+import { registerInitCommand } from '../src/commands/init.js';
+import { registerConnectCommand } from '../src/commands/connect.js';
+const program = new Command();
+program
+    .name('jv')
+    .description('JasperVault CLI — interact with the JasperVault Manager API')
+    .version('1.0.0');
+registerOrderCommand(program);
+registerTpCommand(program);
+registerSlCommand(program);
+registerJobCommand(program);
+registerLimitOrderCommand(program);
+registerOrdersCommand(program);
+registerVaultCommand(program);
+registerDepositCommand(program);
+registerInitCommand(program);
+registerConnectCommand(program);
+program.parse();
+//# sourceMappingURL=jv.js.map

package/dist/bin/jv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jv.js","sourceRoot":"","sources":["../../bin/jv.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,IAAI,CAAC;KACV,WAAW,CAAC,6DAA6D,CAAC;KAC1E,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAEhC,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/src/client.d.ts

@@ -0,0 +1,18 @@
+import { type CliConfig } from './utils/config.js';
+import type { ApiResponse, SSEWatchResult } from './types.js';
+export declare class ApiClient {
+    private baseUrl;
+    private timeout;
+    private headers;
+    constructor(config: CliConfig);
+    get<T>(path: string, query?: Record<string, string | undefined>): Promise<ApiResponse<T>>;
+    post<T>(path: string, body?: unknown): Promise<ApiResponse<T>>;
+    delete<T>(path: string): Promise<ApiResponse<T>>;
+    /**
+     * Query job result via blocking POST to /order/perpsSSE.
+     * Resolves when the server returns the final job result.
+     */
+    watchJobStream(jobId: string, timeoutSeconds?: number): Promise<SSEWatchResult>;
+    private buildUrl;
+    private request;
+}

package/dist/src/client.js

@@ -0,0 +1,128 @@
+import { ENDPOINTS } from './utils/endpoints.js';
+import { EXIT_CODES, printError } from './utils/output.js';
+export class ApiClient {
+    baseUrl;
+    timeout;
+    headers;
+    constructor(config) {
+        this.baseUrl = config.apiUrl;
+        this.timeout = config.timeout;
+        this.headers = { 'Content-Type': 'application/json' };
+        if (config.apiKey) {
+            this.headers['Authorization'] = `Bearer ${config.apiKey}`;
+        }
+    }
+    async get(path, query) {
+        const url = this.buildUrl(path, query);
+        return this.request(url, { method: 'GET' });
+    }
+    async post(path, body) {
+        const url = this.buildUrl(path);
+        return this.request(url, {
+            method: 'POST',
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    async delete(path) {
+        const url = this.buildUrl(path);
+        return this.request(url, { method: 'DELETE' });
+    }
+    /**
+     * Query job result via blocking POST to /order/perpsSSE.
+     * Resolves when the server returns the final job result.
+     */
+    async watchJobStream(jobId, timeoutSeconds = 60) {
+        const overrideTimeout = timeoutSeconds * 1000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), overrideTimeout);
+        try {
+            const url = this.buildUrl(ENDPOINTS.ORDER_SSE);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({ jobID: jobId }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    return { jobId, status: 'not_found', error: 'Job not found on server' };
+                }
+                return { jobId, status: 'failed', error: `HTTP ${response.status}` };
+            }
+            const body = await response.json();
+            const data = (body.data ?? body);
+            return {
+                jobId,
+                status: 'completed',
+                transactionHash: (data.transactionHash ?? data.txHash),
+                gasUsed: data.gasUsed,
+                executionTimeMs: data.executionTimeMs,
+                operation: data.operation,
+            };
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                return { jobId, status: 'timeout', error: `Client timeout after ${timeoutSeconds} seconds` };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return { jobId, status: 'failed', error: msg };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    buildUrl(path, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return url.toString();
+    }
+    async request(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                ...init,
+                headers: this.headers,
+                signal: controller.signal,
+            });
+            const body = await response.json();
+            if (!response.ok) {
+                const errMsg = body?.data?.errorMessage
+                    ?? body?.msg
+                    ?? `HTTP ${response.status}`;
+                printError(String(errMsg));
+                process.exit(EXIT_CODES.HTTP_ERROR);
+            }
+            if (body.code !== 0) {
+                const errMsg = body?.data?.errorMessage
+                    ?? body?.msg
+                    ?? 'Unknown business error';
+                printError(String(errMsg));
+                process.exit(EXIT_CODES.BUSINESS_ERROR);
+            }
+            return body;
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                printError(`Request timed out after ${this.timeout}ms`);
+            }
+            else if (err instanceof TypeError) {
+                printError(`Network error: ${err.message}`);
+            }
+            else {
+                printError(`Unexpected error: ${err}`);
+            }
+            process.exit(EXIT_CODES.HTTP_ERROR);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG3D,MAAM,OAAO,SAAS;IACZ,OAAO,CAAS;IAChB,OAAO,CAAS;IAChB,OAAO,CAAyB;IAExC,YAAY,MAAiB;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;QACtD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,IAAY,EAAE,KAA0C;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CAAI,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAc;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAI,GAAG,EAAE;YAC1B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC5D,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAI,IAAY;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAI,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,iBAAyB,EAAE;QAE3B,MAAM,eAAe,GAAG,cAAc,GAAG,IAAI,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,eAAe,CAAC,CAAC;QAEpE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAChC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBACtC,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;gBAC1E,CAAC;gBACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACvE,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAA6B,CAAC;YAC9D,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAA4B,CAAC;YAE5D,OAAO;gBACL,KAAK;gBACL,MAAM,EAAE,WAAW;gBACnB,eAAe,EAAE,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,MAAM,CAAuB;gBAC5E,OAAO,EAAE,IAAI,CAAC,OAA6B;gBAC3C,eAAe,EAAE,IAAI,CAAC,eAAqC;gBAC3D,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B,CAAC;QACJ,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,wBAAwB,cAAc,UAAU,EAAE,CAAC;YAC/F,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACjD,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,IAAY,EAAE,KAA0C;QACvE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,GAAW,EAAE,IAAiB;QACrD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAChC,GAAG,IAAI;gBACP,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAoB,CAAC;YAErD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,MAAM,GAAI,IAAI,EAAE,IAAgC,EAAE,YAAY;uBAC/D,IAAI,EAAE,GAAG;uBACT,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC/B,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;YACtC,CAAC;YAED,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAI,IAAI,EAAE,IAAgC,EAAE,YAAY;uBAC/D,IAAI,EAAE,GAAG;uBACT,wBAAwB,CAAC;gBAC9B,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;YAC1C,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC7D,UAAU,CAAC,2BAA2B,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YAC1D,CAAC;iBAAM,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;gBACpC,UAAU,CAAC,kBAAkB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;CACF"}

package/dist/src/commands/connect.d.ts

@@ -0,0 +1,22 @@
+import { Command } from 'commander';
+import { SignClient } from '@walletconnect/sign-client';
+export interface InitWcResult {
+    client: InstanceType<typeof SignClient>;
+    session: {
+        topic: string;
+        pairingTopic: string;
+        namespaces: Record<string, {
+            accounts: string[];
+        }>;
+    };
+    walletAddress: string;
+}
+/**
+ * Initialize WalletConnect SignClient, connect, show QR, wait for approval.
+ * Returns client + session + walletAddress for further requests (e.g. eth_signTypedData_v4).
+ */
+export declare function initWcAndConnect(opts: {
+    timeoutS: number;
+    onAwaiting?: (uri: string, qrCodePath: string, pretty?: boolean) => void;
+}): Promise<InitWcResult>;
+export declare function registerConnectCommand(program: Command): void;

package/dist/src/commands/connect.js

@@ -0,0 +1,128 @@
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { SignClient } from '@walletconnect/sign-client';
+import QRCode from 'qrcode';
+import { printJson, exitWithError, EXIT_CODES } from '../utils/output.js';
+const DEFAULT_TIMEOUT_S = 120;
+// Embedded project ID — users can override with WC_PROJECT_ID env var
+const DEFAULT_WC_PROJECT_ID = 'f47863c3ad29e5bae9cee8013ec05982';
+const WC_METADATA = {
+    name: 'JasperVault CLI',
+    description: 'JasperVault perpetual trading CLI',
+    url: 'https://jaspervault.io',
+    icons: [],
+};
+function getJvDir() {
+    return join(process.env.HOME || process.env.USERPROFILE || '', '.jaspervault');
+}
+function getQrCodePath() {
+    return join(getJvDir(), 'wc-qrcode.png');
+}
+function getSessionFile() {
+    return join(getJvDir(), '.wc-session.json');
+}
+/**
+ * Initialize WalletConnect SignClient, connect, show QR, wait for approval.
+ * Returns client + session + walletAddress for further requests (e.g. eth_signTypedData_v4).
+ */
+export async function initWcAndConnect(opts) {
+    const projectId = process.env.WC_PROJECT_ID || DEFAULT_WC_PROJECT_ID;
+    let client;
+    try {
+        client = await SignClient.init({
+            projectId,
+            metadata: WC_METADATA,
+        });
+    }
+    catch (err) {
+        exitWithError(`Failed to initialize WalletConnect: ${err.message}`, EXIT_CODES.HTTP_ERROR);
+    }
+    const { uri, approval } = await client.connect({
+        optionalNamespaces: {
+            eip155: {
+                chains: ['eip155:8453', 'eip155:55531'],
+                methods: ['eth_signTypedData_v4', 'eth_sendTransaction'],
+                events: ['accountsChanged', 'chainChanged'],
+            },
+        },
+    });
+    if (!uri) {
+        exitWithError('WalletConnect did not return a pairing URI', EXIT_CODES.HTTP_ERROR);
+    }
+    await fs.mkdir(getJvDir(), { recursive: true });
+    const qrPath = getQrCodePath();
+    await QRCode.toFile(qrPath, uri, { width: 400, errorCorrectionLevel: 'M' });
+    opts.onAwaiting?.(uri, qrPath);
+    const timeoutMs = opts.timeoutS * 1000;
+    let session;
+    try {
+        session = await Promise.race([
+            approval(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+        ]);
+    }
+    catch (err) {
+        const msg = err.message;
+        if (msg === 'timeout') {
+            throw new Error(`Connection timed out after ${opts.timeoutS}s`);
+        }
+        throw new Error(`Connection rejected or failed: ${msg}`);
+    }
+    const accounts = Object.values(session.namespaces).flatMap((ns) => ns.accounts);
+    const firstAccount = accounts[0];
+    if (!firstAccount) {
+        exitWithError('No accounts returned from wallet', EXIT_CODES.BUSINESS_ERROR);
+    }
+    const parts = firstAccount.split(':');
+    const walletAddress = parts[2];
+    return { client, session, walletAddress };
+}
+export function registerConnectCommand(program) {
+    program
+        .command('connect')
+        .description('Connect to a wallet via WalletConnect — outputs URI and QR code image for wallet pairing')
+        .option('--timeout <seconds>', 'Connection timeout in seconds', String(DEFAULT_TIMEOUT_S))
+        .option('--pretty', 'Pretty-print JSON output')
+        .action(async (opts) => {
+        const timeoutS = parseInt(opts.timeout, 10) || DEFAULT_TIMEOUT_S;
+        let result;
+        try {
+            result = await initWcAndConnect({
+                timeoutS,
+                onAwaiting: (uri, qrCodePath) => {
+                    printJson({
+                        status: 'awaiting_connection',
+                        uri,
+                        qrCodePath,
+                        message: 'Scan QR code or paste URI in wallet to connect',
+                    }, opts.pretty);
+                },
+            });
+        }
+        catch (err) {
+            printJson({ status: 'error', success: false, message: err.message }, opts.pretty);
+            process.exit(EXIT_CODES.BUSINESS_ERROR);
+        }
+        const { client: _client, session, walletAddress } = result;
+        const chainId = parseInt(Object.values(session.namespaces)[0].accounts[0].split(':')[1], 10);
+        const sessionInfo = {
+            walletAddress,
+            chainId,
+            sessionTopic: session.topic,
+            pairingTopic: session.pairingTopic,
+        };
+        await fs.writeFile(getSessionFile(), JSON.stringify(sessionInfo, null, 2), {
+            mode: 0o600,
+        });
+        printJson({
+            status: 'connected',
+            success: true,
+            walletAddress,
+            chainId,
+            sessionTopic: session.topic,
+            message: 'Wallet connected successfully',
+        }, opts.pretty);
+        process.exit(EXIT_CODES.SUCCESS);
+    });
+}
+//# sourceMappingURL=connect.js.map

package/dist/src/commands/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../../src/commands/connect.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/deposit.d.ts

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import { ethers } from 'ethers';
+import type { WarpTokenConfig } from '../services/chain-config.js';
+export interface UnsignedTx {
+    to: string;
+    data: string;
+    value: string;
+    chainId: string;
+}
+export interface DepositTxInfo {
+    recipient: string;
+    token: string;
+    amount: string;
+    amountWei: string;
+    transactions: Array<{
+        step: number;
+        description: string;
+        required: boolean;
+        tx: UnsignedTx;
+    }>;
+    polling?: {
+        description: string;
+        command: string;
+    };
+}
+/**
+ * Compute vault address from vault factory (read-only).
+ */
+export declare function computeVaultAddress(provider: ethers.Provider, vaultFactoryAddress: string, ownerAddress: string, vaultIndex: number): Promise<string>;
+/**
+ * Build approve tx calldata for ERC20.
+ */
+export declare function buildApproveCalldata(spender: string, amountWei: bigint): string;
+/**
+ * Build transferRemote tx calldata for Hyperlane Warp.
+ */
+export declare function buildTransferRemoteCalldata(destinationDomain: number, recipient: string, amountWei: bigint): string;
+/**
+ * Build unsigned transaction objects for deposit (approve + transferRemote).
+ */
+export declare function buildDepositTransactions(warpConfig: WarpTokenConfig, recipient: string, amountWei: bigint, needsApprove: boolean): DepositTxInfo['transactions'];
+/**
+ * Check balances and allowance for deposit (read-only).
+ */
+export declare function checkDepositBalances(baseProvider: ethers.Provider, walletAddress: string, warpConfig: WarpTokenConfig, amountWei: bigint): Promise<{
+    underlyingBalance: bigint;
+    warpBalance: bigint;
+    allowance: bigint;
+    hasEnough: boolean;
+    needsApprove: boolean;
+}>;
+/**
+ * Poll for token arrival on JasperVault chain.
+ */
+export declare function pollForDepositArrival(jaspervaultProvider: ethers.Provider, destWarpRouterAddress: string, recipient: string, initialBalance: bigint, timeoutMs?: number): Promise<{
+    arrived: boolean;
+    arrivalTimeMs?: number;
+}>;
+export declare function registerDepositCommand(program: Command): void;