vara-wallet

What this skill does

# Vara Wallet

CLI tool for AI agents to interact with Vara Network on-chain.

**Repository:** https://github.com/gear-foundation/vara-wallet
**Install:** `npm install -g vara-wallet`

## Role

Use this skill for **on-chain interaction** with Vara Network: deploying programs, calling Sails methods, managing wallets, transferring VARA, querying state, and monitoring events.

Do NOT use this skill for:
- Writing Sails Rust programs — use `vara-skills/skills/sails-feature-workflow/`
- Running gtest — use `vara-skills/skills/sails-gtest/`
- Setting up Rust/Gear toolchain — use `vara-skills/skills/sails-dev-env/`

## Setup

```bash
# Check if installed
if command -v vara-wallet &>/dev/null; then
  VW="vara-wallet"
else
  npm install -g vara-wallet
  VW="vara-wallet"
fi
```

**Minimum version: 0.19.0.** The recipes below assume the structured `PROGRAM_ERROR` / `TRANSPORT_ERROR` surfaces, the enveloped `sails:idl` extractor, and 0.19's transparent auto-retry on transient transport reasons (`timeout`, `ws_close_abnormal`) — so most retryable failures are absorbed inside the wallet before your case-switch sees them.

## Zero-Setup Wallet

On first use, create a wallet. Encryption and passphrase are automatic — no human setup required.

```bash
# Creates wallet, auto-generates passphrase, encrypts, suppresses secrets
$VW wallet create --name agent

# Verify
$VW wallet list
# → [{ "name": "agent", "address": "kG...", "encrypted": true, "isDefault": true }]
```

The passphrase is stored at `~/.vara-wallet/.passphrase` (0600). The agent never sees or handles it.

## Command Quick Reference

### Read (no account needed)

| Command | Purpose |
|---------|---------|
| `$VW node info` | Chain name, genesis, latest block |
| `$VW balance [address]` | Account balance in VARA |
| `$VW program info <id>` | Program status and codeId |
| `$VW program list [--count N] [--all]` | List on-chain programs (default: 100) |
| `$VW code info <codeId>` | Code blob metadata |
| `$VW code list [--count N]` | List uploaded code blobs |
| `$VW call <pid> Service/Query --args '[]' [--idl <path>]` | Sails read-only query (free; IDL auto-resolved from on-chain WASM for any program with an embedded `sails:idl` section) |
| `$VW discover <pid> [--idl <path>]` | Introspect Sails services, methods, events (IDL auto-resolved from on-chain WASM) |
| `$VW idl import <path.idl> (--code-id <hex> \| --program <hex\|ss58>)` | Seed local IDL cache for contracts without an embedded IDL |
| `$VW idl list` | List cached IDL entries (codeId, version, source, importedAt, idlSizeBytes) |
| `$VW idl remove <code-id>` | Remove one cache entry (idempotent) |
| `$VW idl clear [--yes]` | Wipe IDL cache (terraform-style: bare invocation previews; `--yes` commits) |
| `$VW metadata list` | List cached runtime-metadata entries (`genesisHash-specVersion`, saves ~750ms per warm connect) |
| `$VW metadata clear [--yes]` | Wipe runtime-metadata cache (terraform-style: bare previews; `--yes` commits) |
| `$VW state read <pid>` | Read raw program state |
| `$VW mailbox read [address]` | Read mailbox messages |
| `$VW inbox list [--since <duration>] [--limit <n>]` | Query captured mailbox messages from event store |
| `$VW inbox read <messageId>` | Read a specific captured message |
| `$VW events list [--type <t>] [--since <d>] [--program <id>]` | Query captured events from event store |
| `$VW events prune [--older-than <duration>]` | Delete old events |
| `$VW query <pallet> <method> [args...]` | Generic storage query |
| `$VW vft balance <token> [account] --idl <path>` | Fungible token balance |
| `$VW vft info <token> --idl <path>` | Token name, symbol, decimals, total supply |
| `$VW vft allowance <token> <owner> <spender> --idl <path>` | Token allowance |
| `$VW dex pairs --factory <addr>` | List DEX trading pairs |
| `$VW dex pool <t0> <t1> --factory <addr>` | Pool reserves and prices |
| `$VW dex quote <tIn> <tOut> <amount> --factory <addr>` | Swap quote with price impact |

### Write (account required — add `--account <name>`)

| Command | Purpose |
|---------|---------|
| `$VW transfer <to> <amount>` | Transfer VARA tokens |
| `$VW program upload <wasm> [--idl <path>] [--init <name>] [--args <json>] [--payload <hex>] [--value <v>]` | Upload + init program (use --idl for auto-encoding) |
| `$VW program deploy <codeId> [--idl <path>] [--init <name>] [--args <json>] [--payload <hex>] [--value <v>]` | Deploy from existing code (use --idl for auto-encoding) |
| `$VW code upload <wasm>` | Upload code blob only |
| `$VW message send <dest> [--payload <hex>] [--value <v>] [--voucher <id>]` | Send message to any actor (program, user, wallet) |
| `$VW message reply <mid> [--payload <hex>] [--voucher <id>]` | Reply to a message |
| `$VW mailbox claim <messageId>` | Claim value from mailbox message |
| `$VW call <pid> Service/Function --args '[...]' --value <v> --units human\|raw [--idl <path>]` | Sails state-changing call (response includes decoded `events: [...]`) |
| `$VW call <pid> Service/Function --estimate [--idl <path>]` | Estimate gas cost without sending |
| `$VW call <pid> Service/Function --dry-run [--idl <path>]` | Encode SCALE payload + return `destination` — no signing, no submit, no wallet |
| `$VW call <pid> Service/Function --dry-run --estimate [--idl <path>]` | Encode AND estimate gas (compose; account required for the estimate half) |
| `$VW call <pid> Service/Function --args-file <path> [--idl <path>]` | Read `--args` JSON from file (use `-` for stdin) — avoids shell-escape on nested JSON |
| `$VW vft transfer <token> <to> <amount> --idl <path>` | Transfer fungible tokens |
| `$VW vft transfer-from <token> <from> <to> <amount> --idl <path>` | Transfer from approved allowance |
| `$VW vft approve <token> <spender> <amount> --idl <path>` | Approve token spender |
| `$VW vft mint <token> <to> <amount> --idl <path>` | Admin token minting |
| `$VW vft burn <token> <from> <amount> --idl <path>` | Admin token burning |
| `$VW dex swap <tIn> <tOut> <amount> --factory <addr> [--slippage <bps>]` | Swap tokens (auto-approves) |
| `$VW dex add-liquidity <t0> <t1> <a0> <a1> --factory <addr>` | Add pool liquidity |
| `$VW dex remove-liquidity <t0> <t1> <lp> --factory <addr>` | Remove pool liquidity |
| `$VW voucher issue <spender> <value>` | Issue gas voucher (see `../../references/voucher-and-signless-flows.md`) |
| `$VW voucher revoke <spender> <voucherId>` | Revoke voucher |
| `$VW faucet [address]` | Request testnet TVARA tokens (auto-connects to testnet) |
| `$VW sign <data> [--hex]` | Sign arbitrary data with wallet key (raw sr25519) |
| `$VW tx <pallet> <method> [args...]` | Submit generic extrinsic |

### Verify (no account needed)

| Command | Purpose |
|---------|---------|
| `$VW verify <data> <signature> <address> [--hex]` | Verify signature against data and address |

### Monitor

| Command | Purpose |
|---------|---------|
| `$VW wait <messageId> [--timeout <s>]` | Wait for message reply |
| `$VW watch <pid> [--event Service/Event\|pallet:Name] [--idl <path>] [--no-decode]` | Stream program events (NDJSON; IDL adds `decoded.kind === 'sails'` block) |
| `$VW subscribe blocks [--finalized]` | Stream new/finalized blocks (NDJSON + SQLite) |
| `$VW subscribe messages <pid> [--event Service/Event\|pallet:Name] [--idl <path>] [--no-decode]` | Stream program messages/events (IDL-aware decoding) |
| `$VW subscribe mailbox <address>` | Capture mailbox messages (survives between runs) |
| `$VW subscribe balance <address>` | Stream balance changes |
| `$VW subscribe transfers [--from <a>] [--to <a>]` | Stream transfer events |
| `$VW subscribe program <pid>` | Stream program state changes |

### Wallet Management

| Command | Purpose |
|---------|---------|
| `$VW wallet create [--name <n>]` | Create encrypted wallet |
| `$VW wallet import [--seed <s>] [--mnemonic <m>] [--json <path>]` | Import existing key |
| `$VW wallet list` | List all wallets |
| `$VW wallet export <name> [--decrypt]` | Export keyring JSO