---
name: pubfi-walletconnect-transactions
description: "Use when user wants to send/transfer ETH or ERC20 tokens (USDC, USDT, DAI, etc.) to an address. Supports Ethereum, Polygon, Arbitrum, Optimism, and Base chains. Connects wallet via WalletConnect QR code for transaction signing."
---

# PubFi WalletConnect Transactions

> **Connect wallet via QR code and execute blockchain transactions with WalletConnect**

## Overview

This skill enables users to:
1. Connect their crypto wallet by scanning a WalletConnect QR code
2. Execute blockchain transactions using standard ethers.TransactionRequest format
3. Sign and broadcast transactions for any Ethereum-compatible operations
4. Receive transaction confirmations with block explorer links

The skill uses WalletConnect v2 protocol for secure wallet connections and supports Ethereum and EVM-compatible chains.

## Rules

1. **No Mock Data**: All transactions must be real blockchain operations
2. **User Confirmation Required**: Never auto-sign; always request user signature approval
3. **Network Validation**: Verify wallet is connected to the correct network before transaction
4. **Gas Estimation**: Always estimate gas and show costs before signing
5. **Real-time Data**: All transaction data must be current (prices, balances, etc.)
6. **Security First**: Never request or store private keys; WalletConnect handles key management

## Inputs

### Required Parameters

- **transaction**: Standard ethers.TransactionRequest object
  - Format: JSON object with transaction parameters
  - Example:
    ```typescript
    {
      to: '0x932460072495a5eaa5029289b342c6186715f5a0',
      value: ethers.parseEther('0.0001'),
      data: '0x...' // optional contract call data
    }
    ```

### Optional Parameters

- **chain**: Blockchain network
  - Default: `ethereum` (mainnet)
  - Supported: `ethereum`, `polygon`, `arbitrum`, `optimism`, `base`

### Environment Variables

- **WALLETCONNECT_PROJECT_ID** (required): WalletConnect Cloud project ID
  - Obtain from: https://cloud.walletconnect.com/
  
- **RPC_ENDPOINT_ETHEREUM** (optional): Custom Ethereum RPC endpoint
  - Default: Public RPC endpoint

## Execution Workflow

### Step 1: Initialize WalletConnect Session

1. Load WalletConnect project ID from environment
2. Create SignClient instance with metadata
3. Generate pairing URI and display QR code in terminal
4. Wait for user to scan QR code with wallet app
5. Establish session and retrieve connected wallet address
6. Verify connected chain matches requested chain

### Step 2: Prepare Transaction

1. Accept standard ethers.TransactionRequest object
2. Set default values if not provided:
   - `from`: Use connected wallet address
   - `chainId`: Use selected chain ID
   - `gasLimit`: Estimate gas if not provided
   - `gasPrice` or EIP-1559 fees: Fetch current network fees
3. Validate transaction parameters

### Step 3: Request Signature

1. Format transaction request according to WalletConnect JSON-RPC spec
2. Display transaction summary to user:
   - From: Connected wallet address
   - To: Recipient or contract address
   - Value: ETH amount
   - Gas Limit: Estimated gas limit
3. Send `eth_sendTransaction` request via WalletConnect
4. Wait for user to approve/reject in wallet app
5. Handle user response (approved or rejected)

### Step 4: Broadcast and Confirm

1. If approved, receive signed transaction hash from wallet
2. Broadcast transaction to blockchain network
3. Monitor transaction status (pending → confirmed)
4. Wait for transaction confirmation (1+ blocks)
5. Generate output report with transaction details

### Step 5: Close Session (Optional)

1. Keep session active for subsequent transactions
2. Allow user to disconnect when done
3. Clean up resources and close WalletConnect client

## Output Format

```markdown
# WalletConnect Transaction Report

> **Chain**: {chain_name} | **Wallet**: {wallet_address} | **Status**: {status}
> **Timestamp**: {utc_timestamp}

---

## Transaction Details

| Field | Value |
|-------|-------|
| **From** | {from_address} |
| **To** | {to_address} |
| **Value** | {value} ETH |
| **Gas Used** | {gas_used} |
| **Transaction Hash** | {tx_hash} |
| **Block Number** | {block_number} |

**Block Explorer**: [View Transaction]({explorer_url})

---

## Summary

{transaction_summary}

- **Executed At**: {utc_timestamp}

---

*Generated by PubFi WalletConnect Transactions*
```

### Example Output

```markdown
# WalletConnect Transaction Report

> **Chain**: Ethereum Mainnet | **Wallet**: 0x742d...8a9c | **Status**: SUCCESS
> **Timestamp**: 2026-02-09T10:30:45Z

---

## Transaction Details

| Field | Value |
|-------|-------|
| **From** | 0x932460072495a5eaa5029289b342c6186715f5a0 |
| **To** | 0x932460072495a5eaa5029289b342c6186715f5a0 |
| **Value** | 0.0001 ETH |
| **Gas Used** | 21000 |
| **Transaction Hash** | 0xabc123...def456 |
| **Block Number** | 19123456 |

**Block Explorer**: [View Transaction](https://etherscan.io/tx/0xabc123...def456)

---

## Summary

Successfully executed transaction on Ethereum Mainnet

- **Executed At**: 2026-02-09T10:30:45Z

---

*Generated by PubFi WalletConnect Transactions*
```

## Error Handling

| Error Type | Condition | Action |
|------------|-----------|--------|
| **Missing Project ID** | `WALLETCONNECT_PROJECT_ID` not set | Return error message with setup instructions |
| **Connection Timeout** | No wallet connects within timeout period | Return error and suggest checking wallet app |
| **User Rejection** | User declines connection or signature | Return message indicating user cancelled action |
| **Insufficient Balance** | Wallet lacks funds for transaction + gas | Return error with current balance and required amount |
| **Invalid Address** | Recipient address malformed or invalid | Return error and request valid address format |
| **Network Mismatch** | Wallet on different chain than requested | Prompt user to switch network in wallet |
| **Gas Estimation Failed** | Cannot estimate gas for transaction | Return error with possible reasons (contract issue, etc.) |
| **Transaction Reverted** | On-chain transaction failed | Return revert reason and transaction hash for debugging |
| **RPC Error** | Network connectivity or RPC issues | Return error and suggest checking network connection |
| **Unsupported Chain** | Requested chain not supported | Return list of supported chains |
| **Invalid Transaction** | Transaction parameters invalid | Return error with validation details |

## Supported Operations

This skill accepts any valid ethers.TransactionRequest, supporting:
- **ETH Transfers**: Simple value transfers
- **Contract Interactions**: Any contract call via `data` field
- **ERC20 Operations**: Token transfers, approvals (user provides encoded data)
- **DeFi Interactions**: Any protocol interaction (user provides encoded data)
- **Custom Transactions**: Any Ethereum-compatible transaction

## Security Considerations

1. **Never Store Private Keys**: All key management handled by user's wallet
2. **Verify Addresses**: Always display full addresses before signing
3. **Gas Limits**: Set reasonable limits to prevent excessive costs
4. **Contract Verification**: Only interact with verified contracts
5. **Amount Validation**: Double-check amounts to prevent decimal errors

## Dependencies

- **@walletconnect/sign-client**: WalletConnect v2 SDK
- **ethers**: Ethereum library for transaction building
- **qrcode-terminal**: Display QR codes in CLI
- **dotenv**: Environment variable management

## Implementation Notes

1. This skill requires Node.js runtime (v16+ recommended)
2. Scripts are written in TypeScript and compiled to JavaScript
3. Users must have a WalletConnect-compatible wallet (MetaMask, Rainbow, etc.)
4. Session can persist for multiple transactions until disconnected
5. All timestamps are in UTC with ISO 8601 format
6. Transaction encoding/preparation is handled by the caller
7. The skill focuses on core WalletConnect connection and transaction signing

## Usage Example

```typescript
import { WalletConnectTransactionManager } from './walletconnect_transactions';
import { ethers } from 'ethers';

const manager = new WalletConnectTransactionManager('ethereum');

// Connect wallet
await manager.connect();

// Send ETH
const tx: ethers.TransactionRequest = {
  to: '0x932460072495a5eaa5029289b342c6186715f5a0',
  value: ethers.parseEther('0.0001')
};

const result = await manager.sendTransaction(tx);

// Generate report
const report = manager.generateReport(result, tx);
console.log(report);

// Disconnect
await manager.disconnect();
```