Wallet Connect Skill

Status: Pre-release (internal only, not in public registry) Agent quick check: node dist/cli/cli.bundle.mjs version Agent rebuild: npm install && npm run build

Wallet connection and transaction bridge skill for EVM (eip155:1, eip155:56).

Agent Execution Policy

• Execute CLI/setup commands directly as the agent; do not ask the user to run shell commands.
• If dependencies/build/env are missing, fix them automatically in the workspace.
• Before any signing or on-chain write action, explain the action and get user consent.
• Do not output raw JSON/internal payloads to users by default; present concise human-readable summaries.
• Use command snippets in this document as agent-side execution references only.

Project Structure

skills/lista-wallet-connect/
├── SKILL.md
├── package.json
├── tsconfig.json
├── references/
│   └── chains.md
└── src/
    ├── cli/                # args/help/meta/router/env
    ├── commands/           # pair/auth/sign/call/...
    │   └── call/           # parse/simulate/constants
    ├── client.ts
    ├── storage.ts
    ├── helpers.ts
    ├── rpc.ts
    ├── types.ts
    └── cli.ts              # CLI entrypoint

Notes:

• src/cli.ts stays as the entrypoint; argument parsing/help/dispatch are split under src/cli/*.
• Raw call logic is modularized under src/commands/call/* (parse, simulate, constants).

Setup (Agent-Run)

Use prebuilt dist/ by default for faster startup.

cd skills/lista-wallet-connect
# ensure Node.js >= 18 (recommended >= 20)
node -v
node dist/cli/cli.bundle.mjs version

Only run install/build when dist/ is missing or version check fails:

cd skills/lista-wallet-connect
npm install
npm run build
node dist/cli/cli.bundle.mjs version

Set WalletConnect project id:

export WALLETCONNECT_PROJECT_ID=c9e9af475f95d71b87da341e0b1e2237

Default project id is already included in skills/lista-wallet-connect/.env.
You can override it by exporting WALLETCONNECT_PROJECT_ID in your shell.

Runtime Contract

• Agent execution entrypoint: node dist/cli/cli.bundle.mjs <command> ...
• stdout: JSON payloads for automation/agent parsing
• stderr: progress/diagnostic logs
• Wallet-request commands emit one waiting_for_approval event first, then a terminal status (paired/authenticated/signed/sent/rejected/simulation_failed/error).
• Optional debug mode: add --debug-log-file <path> to append structured stdout/stderr logs (jsonl).
• Keep CLI/runtime JSON and debug logs in raw format (for example eip155:1, eip155:56) for stable machine parsing and troubleshooting.
• For user-facing answers, the agent should map chain IDs to names (eip155:1 -> Ethereum, eip155:56 -> BSC) in rendered text/tables.
• Treat raw JSON payloads as internal contract data; only show raw output to users on explicit request.

OpenClaw Streaming Rules (Required)

• Run wallet-request commands (pair, auth, sign, sign-typed-data, call) as long-running streams.
• Do not stop on status: "waiting_for_approval"; this is an interim event only.
• Continue consuming output until a terminal status is received.
• Terminal statuses: paired, authenticated, signed, sent, rejected, simulation_failed, error.
• If no terminal status arrives before process timeout, return timeout as an operational error and prompt retry.
• For pair, always try image delivery first (qrPath attachment, then qrMarkdown if supported).
• Only send uri (wc:) when image rendering/delivery is unsupported or fails.
• Read deliveryPlan in the waiting payload as the source of truth for this fallback order.
• For OpenClaw channels, if openclaw.mediaDirective exists, emit that MEDIA:<path> line as the image-send directive.
• If OpenClaw media send fails, retry with openclaw.fallbackUri (wc: URI) as text.
• When a waiting event contains interactionRequired: true, show a user reminder immediately (once per request) using userReminder text, e.g. "Please approve/reject in your wallet app."

Supported Chains

• eip155:1 (Ethereum)
• eip155:56 (BSC)

Security Rules

1. Never send/sign without explicit user confirmation.
2. Always show chain, destination, calldata/value summary before sending.
3. Use call simulation by default; avoid --no-simulate unless user insists.
4. Do not disclose session topic or pairing URI to third parties.

Command Index

• pair
• status
• auth
• sign
• sign-typed-data
• call
• sessions
• list-sessions
• whoami
• delete-session
• health
• version

Command Details

All command snippets below are for agent execution; do not instruct the user to type them manually.

1) pair

Purpose: Start WalletConnect pairing flow.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs pair --chains eip155:56
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs pair --chains eip155:56,eip155:1
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs pair --chains eip155:56 --open

Behavior:

• First outputs status: "waiting_for_approval" with uri, qrPath, qrMarkdown, deliveryPlan, openclaw, plus guidance fields.
• After user approves, outputs status: "paired" with message, topic, accounts, peerName, pairedAt, and summary.

2) status

Purpose: Check whether a stored session exists.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs status --topic <topic>
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs status --address 0xADDRESS

3) auth

Purpose: Request a consent signature and mark session as authenticated.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs auth --topic <topic>
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs auth --address 0xADDRESS

4) sign

Purpose: Sign an arbitrary message (personal_sign).

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs sign --topic <topic> --message "Hello"
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs sign --address 0xADDRESS --message "Hello" --chain eip155:56

5) sign-typed-data

Purpose: Sign EIP-712 typed data (eth_signTypedData_v4).

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs sign-typed-data --topic <topic> --data '{"domain":...,"types":...,"message":...}'
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs sign-typed-data --address 0xADDRESS --data @/path/to/typed-data.json --chain eip155:1

6) call

Purpose: Send arbitrary contract transaction (eth_sendTransaction) with optional calldata and value.

Key points:

• Simulates via eth_call before sending by default.
• On simulation failure, command returns status: "simulation_failed" and does not send tx.
• Use --no-simulate only when you intentionally want to bypass simulation.
• --value accepts hex wei (0x...) or native decimal string (for example 0.01).

Examples:

# contract call with calldata
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs call --topic <topic> --chain eip155:56 --to 0xCONTRACT --data 0xCALLDATA

# with native value
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs call --topic <topic> --chain eip155:56 --to 0xCONTRACT --data 0xCALLDATA --value 0.01

# custom gas
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs call --topic <topic> --chain eip155:56 --to 0xCONTRACT --data 0xCALLDATA --gas 500000

# force send without simulation (risky)
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs call --topic <topic> --chain eip155:56 --to 0xCONTRACT --data 0xCALLDATA --no-simulate

7) sessions

Purpose: Dump raw saved sessions JSON (internal/debug usage).

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs sessions

8) list-sessions

Purpose: Human-readable session listing.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs list-sessions

9) whoami

Purpose: Show account details for a session, or latest session if omitted.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs whoami --topic <topic>
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs whoami --address 0xADDRESS
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs whoami

10) delete-session

Purpose: Remove a saved session entry.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs delete-session --topic <topic>
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs delete-session --address 0xADDRESS

11) health

Purpose: Ping session(s) for liveness and optionally clean dead sessions.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs health --topic <topic>
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs health --address 0xADDRESS
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs health --all
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs health --all --clean

12) version

Purpose: Print skill version.

node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs version

Common Options

• --address <0x...>: resolve and use latest session matching address
• --topic <topic>: explicit session topic
• --chain <eip155:1|eip155:56>
• --open (pair): force open QR image in system viewer
• --no-simulate (call): bypass simulation

Session Persistence

• WalletConnect storage: ~/.agent-wallet/wc-store/
• Session metadata: ~/.agent-wallet/sessions.json

Quick Onboarding Flow

# 1) pair
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs pair --chains eip155:56,eip155:1 --open

# 2) auth
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs auth --topic <topic>

# 3) verify
node skills/lista-wallet-connect/dist/cli/cli.bundle.mjs whoami --topic <topic>

Integration Notes (with lista-lending)

• lista-lending executes transactions by calling this skill's call command.
• Keep both skills aligned on chain/RPC configuration.
• For debugging transaction flow issues, inspect stderr from both skills.