Vara Wallet

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 and Vara.eth: deploying programs, calling Sails methods, managing wallets, transferring tokens, 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

# 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.20.5. The recipes below assume the structured PROGRAM_ERROR / TRANSPORT_ERROR surfaces, the enveloped sails:idl extractor, transparent auto-retry on transient transport reasons (timeout, ws_close_abnormal), the Vara.eth --chain vara-eth rail, direct --wait submitted handoff, and persistent vara-eth:session action loops.

Zero-Setup Wallet

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

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

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

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

wallet list without --chain is a full local inventory: native Vara rows use chain: "vara" and Vara.eth rows use chain: "vara-eth". Use --chain vara wallet list or --chain vara-eth wallet list when a workflow needs only one rail.

Vara.eth Quick Route

Use --chain vara-eth when the user asks for Vara.eth, Hoodi, Mirrors, WVARA, Ethereum V3 keystores, or vara-eth:* commands. Native Vara remains the default. Vara.eth network names are mainnet, hoodi, and local; do not use native Vara's testnet alias on this rail.

$VW vara-eth:wallet create agent-eth --passphrase "$PASSPHRASE"
$VW --chain vara-eth --network hoodi vara-eth:wvara balance 0xYOUR_ETH_ADDRESS
$VW --chain vara-eth --network hoodi --account agent-eth \
  vara-eth:message send 0xMIRROR --payload 0xfeed --via eth --wait submitted

Vara.eth messages and state-changing Sails calls default to --wait reply; WVARA writes and message replies default to --wait receipt. Select --wait submitted only for transaction-hash handoff. Direct messages then avoid the validator and return messageId: null; read the detailed reference first.

Prefer root Sails parity where possible:

$VW --chain vara-eth --network hoodi --account agent-eth \
  program upload ./program.opt.wasm --idl ./program.idl --args '[]'
$VW --chain vara-eth --network hoodi discover 0xMIRROR --idl ./program.idl
$VW --chain vara-eth --network hoodi call 0xMIRROR Service/Query --args '[]' --idl ./program.idl

For detailed Vara.eth wallet workflows, read references/vara-eth-wallet.md in this skill. For multiple Vara.eth Sails actions in one agent process, use vara-eth:session (persistent signer, connection, and IDL cache; injected submissions); see the detailed reference before choosing it over a direct L1 write.

Command Quick Reference

Read (no account needed)

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

Verify (no account needed)

Monitor

Wallet Management

Common Workflows

Deploy and interact with a Sails program

# 1. Upload program (auto-encodes Sails constructor from IDL)
UPLOAD=$($VW --account agent program upload ./target/wasm32-unknown-unknown/release/my_program.opt.wasm \
  --idl ./target/idl/my_program.idl --args '["MyToken", "MTK", 18]')
PROGRAM_ID=$(echo $UPLOAD | jq -r .programId)

# 2. Discover interface
$VW discover $PROGRAM_ID --idl ./target/idl/my_program.idl

# 3. Estimate gas before calling
$VW --account agent call $PROGRAM_ID MyService/DoSomething --args '["hello"]' --idl ./my_program.idl --estimate

# 4. Call a function (state-changing)
$VW --account agent call $PROGRAM_ID MyService/DoSomething --args '["hello"]' --idl ./my_program.idl

# 5. Query state (read-only, free)
$VW call $PROGRAM_ID MyService/GetState --args '[]' --idl ./my_program.idl

Local node deployment

When deploying to a local dev node, use --network local or set the endpoint explicitly.

# Use --network shorthand (recommended)
$VW --network local wallet import --seed '//Alice' --name alice

# Or persist in config
$VW config set network local

# Or set for the session
export VARA_WS=ws://localhost:9944

# Deploy with IDL-based constructor encoding
UPLOAD=$($VW --account alice program upload ./target/wasm32-unknown-unknown/release/my_program.opt.wasm \
  --idl ./my_program.idl --args '["arg1"]')
PROGRAM_ID=$(echo $UPLOAD | jq -r .programId)

# Verify
$VW call $PROGRAM_ID MyService/GetState --args '[]' --idl ./my_program.idl

Send message and wait for reply

RESULT=$($VW --account agent message send $PROGRAM_ID --payload 0x00)
MSG_ID=$(echo $RESULT | jq -r .messageId)

REPLY=$($VW wait $MSG_ID --timeout 60)
echo $REPLY | jq .payload

Monitor program events

# Raw NDJSON
$VW watch $PROGRAM_ID | while read -r line; do
  echo "$line" | jq .
done

# IDL-aware: each UserMessageSent gets a `decoded: { kind: 'sails', service, event, data }` block
$VW watch $PROGRAM_ID --idl ./my-program.idl | jq '.decoded // .'

# Filter by Sails event (qualified or bare when unambiguous)
$VW watch $PROGRAM_ID --idl ./my-program.idl --event MyService/Transferred
$VW subscribe messages $PROGRAM_ID --idl ./my-program.idl --event Transferred --count 1 --timeout 30

# Force pallet vocab even with IDL loaded — replaces the dropped --pallet-event flag
$VW watch $PROGRAM_ID --idl ./my-program.idl --event pallet:UserMessageSent

Bare event names that resolve to multiple services hard-fail with AMBIGUOUS_EVENT listing the alternatives — qualify as Service/Event or use pallet:Name to force pallet vocabulary. --no-decode disables the opportunistic IDL auto-load entirely. The decoded.kind discriminator future-proofs the surface for additional decoder types.

Preview a call without signing

--dry-run encodes the SCALE payload and exits with willSubmit: false. Works on machines with no wallet configured — useful for previewing payloads in CI, code review, or read-only environments.

# call dry-run — no account needed
$VW call $PROGRAM_ID MyService/DoSomething --args '["hello"]' --idl ./my-program.idl --dry-run

# program upload dry-run — reports resolved constructor + encoded init payload
$VW program upload ./my-program.opt.wasm --idl ./my-program.idl --args '["MyToken", "MTK", 18]' --dry-run

Pass nested JSON via stdin (avoids shell-escape footguns)

--args-file <path> (or - for stdin) eliminates double-escape failures when the JSON contains hex actor IDs, 64-byte vec u8 signatures, or other punctuation-heavy payloads.

echo '[["0xabcd...", 1000]]' | $VW --account agent call $PROGRAM_ID MyService/BatchTransfer --args-file - --idl ./my-program.idl

--args and --args-file are mutually exclusive (INVALID_ARGS_SOURCE). Stdin without a pipe attached fails fast with STDIN_IS_TTY instead of hanging on EOF.

Subscribe to events (with persistence)

# Catch mailbox messages (they vanish after ~1 block)
$VW subscribe mailbox $MY_ADDRESS

# Wait for exactly 1 transfer, then exit (agent-friendly)
$VW subscribe transfers --count 1 --timeout 30

# Query captured events between runs
$VW inbox list --since 1h
$VW events list --type mailbox --limit 10

Token operations

# Token info
$VW vft info $TOKEN_PROGRAM --idl ./vft.idl

# Check balance
$VW vft balance $TOKEN_PROGRAM --idl ./vft.idl

# Transfer
$VW --account agent vft transfer $TOKEN_PROGRAM $RECIPIENT 1000 --idl ./vft.idl

# Approve
$VW --account agent vft approve $TOKEN_PROGRAM $SPENDER 1000 --idl ./vft.idl

DEX operations (Rivr)

# Check available pairs
$VW dex pairs --factory $FACTORY

# Get swap quote with price impact
$VW dex quote $TOKEN_IN $TOKEN_OUT 100 --factory $FACTORY

# Swap tokens (auto-approves input token)
$VW --account agent dex swap $TOKEN_IN $TOKEN_OUT 100 --factory $FACTORY --slippage 100

Fund an account with a voucher

$VW --account sponsor voucher issue $SPENDER_ADDRESS 100 --duration 14400

Sign and verify data

# Sign arbitrary data
SIG=$($VW --account agent sign "hello world" | jq -r .signature)

# Verify signature
$VW verify "hello world" $SIG $ADDRESS

IDL Resolution

Sails commands (call, discover, vft, dex) need an IDL. Resolution order:

1. --idl <path> — local file, always works, takes precedence
2. Local cache — ~/.vara-wallet/idl-cache/<codeId>.cache.json, populated automatically by previous fetches or by idl import
3. Embedded sails:idl section — auto-extracted from the program's on-chain WASM and cached. Since 0.18.0 the extractor reads the enveloped section format (1-byte version, 1-byte flags with deflate bit, payload) emitted by current sails-rs, with a raw UTF-8 fallback for older beta.1-era programs.
4. Bundled IDLs — standard VFT and Rivr DEX IDLs ship in the binary for vft / dex commands.

Embedded IDL is the default. Any contract built with current sails-rs ships its IDL inside the WASM, so call / discover / vft / dex work without --idl; the first invocation populates the cache and subsequent calls hit it for free. idl import is only for contracts that don't have an embedded sails:idl section — seed the cache once:

# Resolves codeId via RPC
$VW idl import ./my-program.idl --program <programId>

# Fully offline if you already know the codeId
$VW idl import ./my-program.idl --code-id 0x<hex>

Output Parsing

All commands output JSON to stdout. Errors go to stderr as { error, code }.

# Extract a field
$VW balance | jq -r .balance

# Check transaction success
RESULT=$($VW --account agent transfer $TO 1)
echo $RESULT | jq '.events[] | select(.section == "balances")'

# Verbose debug (stderr, won't break JSON parsing)
$VW --verbose balance 2>/dev/null | jq .

Structured Errors

Program-execution failures surface as flat JSON on stderr — reason and programMessage are top-level keys, not nested under meta:

{"code":"PROGRAM_ERROR","reason":"panic","programMessage":"<BareVariant>","error":"<full text>"}

reason ∈ panic | unreachable | inactive | not_found. programMessage is the bare Sails error variant — the called \Result::unwrap()` on an `Err` value:wrapper that#[export(unwrap_result)]` adds is stripped, so agents can switch on it directly:

ERR=$(vara-wallet --account agent call $PID Service/Method --args '[...]' --idl ./my.idl 2>&1 1>/dev/null)
case "$(echo "$ERR" | jq -r '.programMessage // ""')" in
  InsufficientBalance) refill ;;
  Unauthorized)        switch_account ;;
  *)                   echo "unhandled: $ERR" ;;
esac

Transport Errors

Migration: scripts that grepped "code":"CONNECTION_TIMEOUT" (WS connect) or "code":"TIMEOUT" / "code":"CONNECTION_FAILED" (program/dex/vft/message paths) must switch to "code":"TRANSPORT_ERROR" + the matching reason. Faucet HTTP CONNECTION_FAILED is unchanged — different consumer surface. --light failures route through the same taxonomy.

Transport-layer failures (DNS, WS handshake, RPC disconnect, TLS, timeout) surface as structured TRANSPORT_ERROR with a reason subcode instead of the legacy opaque {"error":"{}","code":"UNKNOWN_ERROR"}. The error carries endpoint, host (DNS path), and meta.cause (raw underlying message):

{"code":"TRANSPORT_ERROR","reason":"dns_failure","error":"Cannot resolve host nonexistent-host","endpoint":"wss://nonexistent-host","host":"nonexistent-host","meta":{"cause":"<raw>"}}

reason taxonomy: dns_failure | connection_refused | timeout | ws_close_abnormal | protocol_mismatch | unreachable | tls_failure | unknown. Switch on it to decide retry vs. fail:

case "$(echo "$ERR" | jq -r '.reason // ""')" in
  timeout|connection_refused|unreachable|ws_close_abnormal) retry_with_backoff ;;
  dns_failure|tls_failure|protocol_mismatch)                fail_fast ;;
esac

--verbose writes a [verbose] cause: code=<x>, message=<y> line to stderr immediately before the structured JSON (EPIPE-safe), making cause-chain triage cheap without changing the machine-readable surface.

Network Switching

# Shorthand (recommended)
$VW --network testnet balance

# Per-command with full URL
$VW --ws wss://testnet.vara.network balance

# Persist across sessions
$VW config set network testnet

# Session-wide env var
export VARA_WS=wss://testnet.vara.network

Endpoint resolution order: --ws > --network > VARA_WS env > config.wsEndpoint > default.

Connection timeout is 10s. Bad endpoints fail fast with TRANSPORT_ERROR instead of hanging — see Transport Errors.

For full network endpoint and account format details, see ../../references/vara-network-endpoints.md.

Units

1 VARA = 10^12 minimal units (12 decimals). Amounts default to VARA.

$VW transfer $TO 1.5                        # 1.5 VARA
$VW transfer $TO 1500000000000 --units raw   # same in raw units

All --units flags use a unified human|raw vocabulary:

• Native commands (balance, transfer, message, call, voucher, program): human (default) = VARA decimals (12). raw = minimal units passthrough.
• VFT and DEX commands: raw (default) = minimal units passthrough. human = use the token's declared decimals (queried at runtime).
• The literals vara and token are rejected with INVALID_UNITS — pulled from old tutorials, they no longer work.

Existential deposit is ~10 VARA on mainnet.

Error Recovery

Guardrails

• Never pass secrets (seeds, mnemonics, passphrases) as CLI arguments in committed scripts. Use wallet files.
• Never use --show-secret in automated flows. Secrets should stay in encrypted wallet files.
• Always use --account <name> for signing, not --seed.
• Gas is auto-calculated — omit --gas-limit unless you have a specific reason. calculateGas failures (program panic during dry-run) surface as classified PROGRAM_ERROR, not opaque gas errors — see Error Recovery.
• Messages are async. After message send, use wait to get the reply.
• call auto-detects queries vs functions — no need to specify.
• When targeting a local dev node, use --network local or VARA_WS=ws://localhost:9944. The default endpoint is mainnet.
• Use config set network testnet to persist network choice across sessions.
• program list returns 100 programs by default. Use --all for unlimited.
• faucet only works on testnet. It refuses mainnet endpoints automatically.
• If sails-local-smoke is green and you need to interact with a deployed program on a live network, switch to this skill.