diff --git a/AGENTS.md b/AGENTS.md index 8841715..25476f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,13 @@ ``` packages/ - cli-sdk/ → @walletconnect/cli-sdk (wallet connection + signing for CLI apps) - staking-cli/ → @walletconnect/staking-cli (WCT staking CLI, depends on cli-sdk) + cli-sdk/ → @walletconnect/cli-sdk (wallet connection, signing, and cross-chain swidge for CLI apps) + companion-wallet/ → @walletconnect/companion-wallet (self-custody wallet with auto-bridging via LI.FI) + staking-cli/ → @walletconnect/staking-cli (WCT staking CLI, depends on cli-sdk) + pay-cli/ → @walletconnect/pay-cli (WalletConnect Pay CLI, experimental) ``` -Both packages are ESM (`"type": "module"`), built with **tsup**, tested with **vitest**, linted with **ESLint v9** (flat config at root `eslint.config.mjs`). +All packages are ESM (`"type": "module"`), built with **tsup**, tested with **vitest**, linted with **ESLint v9** (flat config at root `eslint.config.mjs`). **Turborepo** orchestrates build/test/lint. Build order: `cli-sdk` first (staking-cli depends on it). @@ -70,7 +72,7 @@ Both packages always version together (fixed group). A changeset touching either Tests live in `packages/*/test/`. Both packages use vitest with `--reporter=verbose`. -- **cli-sdk**: 41 tests (client, helpers, session, terminal-ui, browser-ui) +- **cli-sdk**: 58 tests (client, helpers, session, terminal-ui, browser-ui, swidge) - **staking-cli**: 20 tests (contracts, format utilities) Mocks for WalletConnect SignClient are in `packages/cli-sdk/test/mocks/sign-client.ts`. diff --git a/README.md b/README.md index 6510c18..114befc 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# WalletConnect Agent SDK +# 🔗 WalletConnect Agent SDK > **Beta (v0.1.x)** — This project is under active development. APIs and CLI interfaces may change between releases. Not yet recommended for production use. -Monorepo for WalletConnect agent tooling — CLI tools and libraries for wallet connection, message signing, and WCT staking from the terminal. +Monorepo for WalletConnect agent tooling — CLI tools and libraries for wallet connection, message signing, cross-chain bridging, and WCT staking from the terminal. -### Agent Skills +### 🤖 Agent Skills Install the accompanying Claude Code / agent skills: @@ -12,15 +12,15 @@ Install the accompanying Claude Code / agent skills: npx skills add WalletConnect/agent-sdk ``` -## Packages +## 📦 Packages | Package | Binary | Description | |---------|--------|-------------| -| [`@walletconnect/cli-sdk`](packages/cli-sdk/) | `walletconnect` | Wallet connection and signing for terminal applications | -| [`@walletconnect/staking-cli`](packages/staking-cli/) | `walletconnect-staking` | WCT staking on Optimism (stake, unstake, claim rewards) | -| [`@walletconnect/pay-cli`](packages/pay-cli/) | `walletconnect-pay` | **Experimental** — WalletConnect Pay payments from the terminal | +| [`@walletconnect/cli-sdk`](packages/cli-sdk/) | `walletconnect` | 🔑 Wallet connection, signing, and cross-chain swidge for terminal apps | +| [`@walletconnect/staking-cli`](packages/staking-cli/) | `walletconnect-staking` | 📈 WCT staking on Optimism (stake, unstake, claim rewards) | +| [`@walletconnect/pay-cli`](packages/pay-cli/) | `walletconnect-pay` | 💳 **Experimental** — WalletConnect Pay payments from the terminal | -## Quick Start +## 🚀 Quick Start ### Install globally @@ -42,27 +42,33 @@ Or set the environment variable: export WALLETCONNECT_PROJECT_ID= ``` -## `walletconnect` CLI +## 🔑 `walletconnect` CLI -Connect a wallet, sign messages, and manage sessions. +Connect a wallet, sign messages, send transactions, and bridge tokens across chains. ``` Usage: walletconnect [options] Commands: - connect Connect to a wallet via QR code - whoami Show current session info - sign Sign a message with the connected wallet - disconnect Disconnect the current session - config set Set a config value (e.g. project-id) - config get Get a config value + connect Connect to a wallet via QR code + whoami Show current session info + sign Sign a message with the connected wallet + sign-typed-data Sign EIP-712 typed data (JSON string) + send-transaction Send a transaction (EVM or Solana) + swidge Bridge/swap tokens across chains via LI.FI + disconnect Disconnect the current session + config set Set a config value (e.g. project-id) + config get Get a config value Options: --browser Use browser UI instead of terminal QR code + --json Output as JSON (for whoami) + --chain Specify chain (e.g. evm, solana, eip155:10) for connect + --version Show version number --help Show this help message ``` -### Examples +### 💬 Examples ```bash # Connect a wallet (shows QR code in terminal) @@ -77,11 +83,52 @@ walletconnect sign "Hello from the terminal" # Check connected wallet walletconnect whoami +# Send a transaction on Optimism +walletconnect send-transaction '{"to":"0x...","value":"0x0","chainId":"eip155:10"}' + # Disconnect walletconnect disconnect ``` -## `walletconnect-staking` CLI +## 🔀 Swidge (Cross-Chain Bridge/Swap) + +Bridge or swap tokens across EVM chains, powered by [LI.FI](https://li.fi). The connected wallet approves and executes each transaction. + +``` +Swidge options: + --from-chain Source chain (e.g. eip155:8453) + --to-chain Destination chain (e.g. eip155:10) + --from-token Source token symbol (e.g. ETH, USDC) + --to-token Destination token symbol (e.g. ETH, WCT) + --amount Amount to bridge (human-readable) +``` + +### 🌉 Swidge examples + +```bash +# Bridge 5 WCT from Optimism to Ethereum mainnet +walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 \ + --from-token WCT --to-token WCT --amount 5 + +# Swap USDC on Base to ETH on Optimism +walletconnect swidge --from-chain eip155:8453 --to-chain eip155:10 \ + --from-token USDC --to-token ETH --amount 10 + +# Bridge ETH from Ethereum to Base +walletconnect swidge --from-chain eip155:1 --to-chain eip155:8453 \ + --amount 0.01 +``` + +### ⚡ Auto-bridge in `send-transaction` + +When sending a transaction, the CLI automatically checks if the connected wallet has sufficient ETH on the target chain. If funds are insufficient: + +- **Interactive (TTY)**: Prompts you to bridge from another chain +- **Pipe/agent mode**: Auto-bridges from the chain with the most funds + +This means agents can seamlessly execute transactions across chains without worrying about which chain has funds. + +## 📈 `walletconnect-staking` CLI Stake WCT tokens on Optimism, check staking positions, and claim rewards. @@ -101,7 +148,7 @@ Options: --help Show this help message ``` -### Examples +### 💰 Examples ```bash # Stake 1000 WCT for 52 weeks @@ -120,9 +167,9 @@ walletconnect-staking claim walletconnect-staking unstake ``` -## `walletconnect-pay` CLI (Experimental) +## 💳 `walletconnect-pay` CLI (Experimental) -> **Experimental** — This package is under active development. APIs, commands, and behavior may change significantly between releases. Not recommended for production use. +> **⚠️ Experimental** — This package is under active development. APIs, commands, and behavior may change significantly between releases. Create and complete WalletConnect Pay payments from the terminal. Supports proxy mode (no API keys needed) and direct API mode. @@ -140,7 +187,7 @@ Options: --help Show this help message ``` -### Authentication +### 🔐 Authentication By default, the CLI proxies through the WalletConnect Pay frontend — no API keys needed. For direct API access, set environment variables: @@ -153,13 +200,14 @@ export WC_PAY_PARTNER_API_KEY= export WC_PAY_MERCHANT_ID= ``` -### Travel Rule compliance +### 🛂 Travel Rule compliance Some payments require Information Capture data. Provide via CLI flags or environment variables: ```bash # Via CLI flags -walletconnect-pay checkout --name "John Doe" --dob "1990-01-15" --pob-country "US" --pob-address "New York, NY" +walletconnect-pay checkout --name "John Doe" --dob "1990-01-15" \ + --pob-country "US" --pob-address "New York, NY" # Or via environment variables export WC_PAY_NAME="John Doe" @@ -168,7 +216,7 @@ export WC_PAY_POB_COUNTRY="US" export WC_PAY_POB_ADDRESS="New York, NY" ``` -### Examples +### 💳 Examples ```bash # Check a payment's status @@ -181,7 +229,7 @@ walletconnect-pay create 1000 --staging walletconnect-pay checkout pay_abc123 --staging ``` -## Programmatic Usage +## 🧑‍💻 Programmatic Usage ### `@walletconnect/cli-sdk` @@ -250,9 +298,9 @@ const proxyClient = createFrontendPayClient({ const payment = await client.getPayment("pay_abc123"); ``` -> **Experimental** — The `@walletconnect/pay-cli` programmatic API is not yet stable. +> **⚠️ Experimental** — The `@walletconnect/pay-cli` programmatic API is not yet stable. -## Development +## 🛠️ Development ```bash npm install @@ -261,7 +309,7 @@ npm run test # Run all tests npm run lint # Lint all packages ``` -### Contributing +### 📝 Contributing Every PR that changes package behavior must include a **changeset**: @@ -271,6 +319,6 @@ npm run changeset # Interactive — select packages, bump type, description This creates a `.changeset/.md` file. Commit it with your PR. On merge, the [changesets action](https://github.com/changesets/changesets/tree/main/packages/action) opens a version PR, and merging that publishes to npm. -## License +## 📄 License [WalletConnect Community License](LICENSE.md) diff --git a/packages/cli-sdk/README.md b/packages/cli-sdk/README.md index 9fb812e..798b89f 100644 --- a/packages/cli-sdk/README.md +++ b/packages/cli-sdk/README.md @@ -1,6 +1,6 @@ -# @walletconnect/cli-sdk +# 🔑 @walletconnect/cli-sdk -Wallet connection and transaction signing for CLI applications, powered by the WalletConnect protocol. +Wallet connection, transaction signing, and cross-chain bridging for CLI applications, powered by the WalletConnect protocol and [LI.FI](https://li.fi). ## Quick Start @@ -129,3 +129,21 @@ Returns the raw session object. ### `wc.destroy(): Promise` Cleans up all resources (browser server, listeners, client references). + +## 🔀 Swidge (Cross-Chain Bridge/Swap) + +The `walletconnect` CLI includes a `swidge` command for bridging and swapping tokens across EVM chains via [LI.FI](https://li.fi). Zero additional dependencies — all external calls use `fetch()`. + +```bash +# Bridge WCT from Optimism to Ethereum mainnet +walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 \ + --from-token WCT --to-token WCT --amount 5 + +# Swap USDC on Base to ETH on Optimism +walletconnect swidge --from-chain eip155:8453 --to-chain eip155:10 \ + --from-token USDC --to-token ETH --amount 10 +``` + +### Auto-bridge in `send-transaction` + +When sending a transaction, the CLI checks if the wallet has sufficient ETH. If not, it automatically bridges from another chain (prompts in TTY, auto-bridges in pipe mode). diff --git a/skills/walletconnect-staking/SKILL.md b/skills/walletconnect-staking/SKILL.md index 14f4cb4..421159d 100644 --- a/skills/walletconnect-staking/SKILL.md +++ b/skills/walletconnect-staking/SKILL.md @@ -21,6 +21,7 @@ Operate the `walletconnect-staking` CLI to stake/unstake WCT tokens, claim staki ## When not to use - User wants basic wallet connection without staking (use `walletconnect` skill) +- User wants to bridge or swap tokens across chains (use `walletconnect` skill — the `swidge` command) - User is working on the staking-cli source code (just edit normally) - User wants to interact with WCT on a chain other than Optimism diff --git a/skills/walletconnect/SKILL.md b/skills/walletconnect/SKILL.md index 2a58c37..44c36b6 100644 --- a/skills/walletconnect/SKILL.md +++ b/skills/walletconnect/SKILL.md @@ -1,31 +1,34 @@ --- name: walletconnect -description: Manages the walletconnect CLI for wallet connection, session management, and message signing. Use when the user wants to connect a wallet, check session status, sign messages, or disconnect. +description: Manages the walletconnect CLI for wallet connection, session management, message signing, transaction sending, and cross-chain bridging (swidge). Use when the user wants to connect a wallet, check session status, sign messages, send transactions, bridge tokens across chains, or disconnect. --- # WalletConnect CLI ## Goal -Operate the `walletconnect` CLI binary to connect wallets via QR code, inspect sessions, sign messages, and disconnect. +Operate the `walletconnect` CLI binary to connect wallets via QR code, inspect sessions, sign messages, send transactions, bridge/swap tokens across chains (swidge), and disconnect. ## When to use - User asks to connect a wallet or scan a QR code - User asks to check which wallet is connected (`whoami`) - User asks to sign a message with their wallet +- User asks to sign EIP-712 typed data +- User asks to send a transaction with their wallet +- User asks to bridge or swap tokens across chains - User asks to disconnect their wallet session - User mentions `walletconnect` CLI in context of wallet operations ## When not to use - User wants to stake, unstake, or claim WCT rewards (use `walletconnect-staking` skill) +- User wants to create or checkout WalletConnect Pay payments (use `walletconnect-pay` skill) - User is working on the SDK source code itself (just edit normally) -- User wants to interact with a dApp or smart contract beyond signing ## Prerequisites -- Project ID must be configured (see below) for `connect` and `sign` commands +- Project ID must be configured (see below) for `connect`, `sign`, `send-transaction`, and `swidge` commands - Binary is at `packages/cli-sdk/dist/cli.js` (or globally linked as `walletconnect`) - Build first if needed: `npm run build -w @walletconnect/cli-sdk` @@ -53,12 +56,31 @@ walletconnect connect # Connect via browser UI instead of terminal QR walletconnect connect --browser +# Connect with specific chain +walletconnect connect --chain eip155:10 + # Check current session walletconnect whoami +walletconnect whoami --json # Sign a message walletconnect sign "Hello, World!" +# Sign EIP-712 typed data +walletconnect sign-typed-data '{"types":...}' + +# Send a transaction (EVM) +walletconnect send-transaction '{"to":"0x...","value":"0x...","data":"0x..."}' + +# Send a transaction on a specific chain +walletconnect send-transaction '{"to":"0x...","value":"0x...","chainId":"eip155:10"}' + +# Send a Solana transaction +walletconnect send-transaction '{"transaction":"base64...","chainId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"}' + +# Bridge/swap tokens across chains (swidge) +walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5 + # Disconnect walletconnect disconnect @@ -67,21 +89,57 @@ walletconnect config set project-id walletconnect config get project-id ``` +## Swidge (cross-chain bridge/swap) + +The `swidge` command bridges or swaps tokens across chains via [LI.FI](https://li.fi). It uses the connected wallet to approve and execute the bridge transaction. + +### Required flags +- `--from-chain ` — Source chain (CAIP-2, e.g. `eip155:8453`) +- `--to-chain ` — Destination chain (CAIP-2, e.g. `eip155:10`) +- `--amount ` — Amount to bridge (human-readable, e.g. `5`, `0.1`) + +### Optional flags +- `--from-token ` — Source token symbol (default: `ETH`) +- `--to-token ` — Destination token symbol (default: `ETH`) + +### Auto-bridge in send-transaction + +When using `send-transaction`, the CLI automatically checks if the connected wallet has sufficient ETH on the target chain. If insufficient, it: +- In TTY mode: prompts the user to bridge from another chain +- In pipe/agent mode: auto-bridges from the chain with the most funds + +### Swidge examples + +```bash +# Bridge 5 WCT from Optimism to Ethereum mainnet +walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5 + +# Swap USDC on Base to ETH on Optimism +walletconnect swidge --from-chain eip155:8453 --to-chain eip155:10 --from-token USDC --to-token ETH --amount 10 + +# Bridge ETH from Ethereum to Base +walletconnect swidge --from-chain eip155:1 --to-chain eip155:8453 --amount 0.01 +``` + ## Default workflow 1. Check project ID is configured: `walletconnect config get project-id` 2. Check if a session exists: `walletconnect whoami` 3. If not connected, connect: `walletconnect connect` -4. Perform the requested operation (sign, check status, etc.) +4. Perform the requested operation (sign, send-transaction, swidge, etc.) 5. If done, optionally disconnect: `walletconnect disconnect` ## Important notes - The `connect` and `sign` commands require a project ID — set it with `walletconnect config set project-id ` if not configured - Sessions persist across invocations in `~/.walletconnect-cli/` -- `sign` auto-connects if no session exists +- `sign`, `send-transaction`, and `swidge` auto-connect if no session exists - The `--browser` flag opens a local web page with the QR code instead of rendering in terminal -- Always use a 60s+ timeout for commands that require wallet interaction (QR scan, signing) +- Always use a 60s+ timeout for commands that require wallet interaction (QR scan, signing, bridging) +- `connect` defaults to all EVM chains when no `--chain` flag is specified +- `swidge` requires token approval for ERC-20 tokens (handled automatically — user confirms in wallet) +- Cross-chain bridges typically take 1-5 minutes for funds to arrive on the destination chain +- `send-transaction` output goes to stdout as JSON; status/progress goes to stderr ## Validation checklist @@ -89,6 +147,7 @@ walletconnect config get project-id - [ ] Binary is built and linked (`walletconnect --help` works) - [ ] Command output is shown to the user - [ ] Timeouts are sufficient for wallet interaction (60s+) +- [ ] For swidge: `--from-chain`, `--to-chain`, and `--amount` are all provided ## Examples @@ -104,3 +163,17 @@ User: "Sign the message 'verify-ownership' with my wallet" Action: Run `walletconnect sign "verify-ownership"` Note: Inform user to confirm in their wallet app ``` + +### Send a transaction +``` +User: "Send 0.01 ETH to 0xABC... on Optimism" +Action: Run `walletconnect send-transaction '{"to":"0xABC...","value":"0x2386F26FC10000","chainId":"eip155:10"}'` +Note: Inform user to confirm in their wallet app. Auto-bridges ETH if insufficient. +``` + +### Bridge tokens +``` +User: "Bridge 5 WCT from Optimism to mainnet" +Action: Run `walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5` +Note: May send 2 transactions (approve + bridge). Inform user to confirm each. Funds arrive in 1-5 min. +```