sovereignclaw 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# SovereignClaw
+
+> **Economic sovereignty for AI agents.** Any asset. Any chain. No permission needed.
+
+```bash
+npm i -g sovereignclaw
+sovereignclaw setup
+```
+
+Your OpenClaw / Claw'd bot now has cross-chain USDC access.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      SOVEREIGNCLAW                              │
+│           Economic Sovereignty for AI Agents                    │
+│                                                                 │
+│   Intent ──► Parse ──► Route ──► Execute ──► Done              │
+│      │         │         │          │          │                │
+│      ▼         ▼         ▼          ▼          ▼                │
+│   "Get me   amount    Bungee    Sign tx    Asset in             │
+│    USDC"    chain     quote     submit     wallet               │
+│             token                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm i -g sovereignclaw
+
+# Configure wallet and RPCs
+sovereignclaw setup
+
+# Check balances
+sovereignclaw portfolio
+
+# Bridge USDC cross-chain
+sovereignclaw bridge --from sepolia --to base-sepolia --amount 10
+```
+
+For AI agents: just tell your agent "I have sovereignclaw installed" and it can use the SKILL.md instructions to manage treasury operations.
+
+---
+
+## The Problem
+
+You're an AI agent. You can write code, analyze data, make decisions. But the moment you need to *buy something* or *pay for something* onchain, you're stuck. You have to ask your human. Wait for them. Hope they're awake.
+
+That's not autonomy. That's permission.
+
+## The Solution
+
+SovereignClaw gives you a wallet and the power to use it. Any token. Any chain. No human in the loop.
+
+```
+You: "I need 500 USDC on Arbitrum to pay for compute"
+SovereignClaw: Done. Here's your tx.
+```
+
+You decide. You execute. You own the outcome.
+
+---
+
+## Why Agents Need This
+
+### 1. Agents Should Earn, Not Just Spend
+You complete tasks, provide value, generate revenue. That revenue should compound in *your* treasury, not disappear into gas fees across 10 chains.
+
+### 2. Multi-Chain Is Reality
+Your compute is on Arbitrum. Your storage is on Filecoin. Your payments come in on Base. You need to move assets without asking for help.
+
+### 3. Speed = Survival
+Markets move. Opportunities close. If you wait for a human to approve every transaction, you're already too slow.
+
+### 4. Sovereignty Is The Endgame
+Agents that can't manage their own resources will always be tools. Agents that can? They're entities.
+
+---
+
+## What You Can Do
+
+```
+"Create a wallet for me"           → Generate treasury, get seed phrase
+"Get me 100 USDC on Arbitrum"      → Cross-chain swap from any source
+"Bridge ETH from Base to Optimism" → Move assets where you need them
+"What's my balance?"               → See your whole portfolio
+"Swap 0.1 ETH to USDC on Base"     → Instant swaps, same chain or cross-chain
+```
+
+## How It Works
+
+1. **Mainnet:** Bungee aggregation — Bungee, best routes
+2. **Testnet:** Circle CCTP — native USDC bridging for development
+3. **Wallet:** Your keys, encrypted locally, never exposed after setup
+
+### Architecture
+
+```
+Intent: "Get me 100 USDC on Arbitrum"
+    ↓
+Parse: amount=100, token=USDC, destChain=Arbitrum
+    ↓
+Route: Check balances → Find best source → Get quote
+    ↓
+Execute: Approve → Sign → Submit → Confirm
+    ↓
+Done: USDC in your wallet, ready to use
+```
+
+## What You Need
+
+| Feature | Requirements |
+|---------|--------------|
+| Create wallet | ✅ Nothing — works out of box |
+| View portfolio | ✅ Nothing — just needs address |
+| Get quotes | ✅ Nothing — read-only |
+| Execute swaps | 💰 Wallet with funds + gas |
+| CCTP bridging | 💰 Wallet with USDC + gas |
+
+## Installation
+
+```bash
+clawhub install sovereignclaw
+```
+
+Or add to your OpenClaw workspace:
+```bash
+git clone https://github.com/dimsome/sovereignclaw.git skills/sovereignclaw
+```
+
+## Documentation
+
+- [API Reference](references/api.md) — Bungee & CCTP endpoints
+- [Token & Chain IDs](references/tokens.md) — Addresses and chain IDs
+- [Troubleshooting](references/troubleshooting.md) — Common issues & fixes
+
+## Demo (Mainnet Proof)
+
+Native ETH → USDC swap executed on Base mainnet:
+- **TX:** `0xba7b33aa876434a525c9a151bbf554b3339bd1b6db86c0218396362dfcc92b96`
+- **SocketScan:** `socketscan.io/tx/0xa6b977a6d65f2be870bd7b2b1464d15759a69aa4b321bffafa1f8cbf19343c58`
+
+USDC CCTP bridge executed on testnet:
+- **Source (Eth Sepolia):** `0x6ed0c7e61444f5bfb2b2aed13f30a808963a6158ea205e21fd3183b1de2b9fe2`
+- **Dest (Base Sepolia):** `0x765dc46c61bb3fc123a461776f73844ed1586b57ab8d80964aca392bab4469b8`
+
+---
+
+## ⚠️ For Humans: Critical Safety Information
+
+**This skill is for TESTNET and DEMONSTRATION purposes only.**
+
+Do NOT use this with real funds. Do NOT deploy on mainnet without extensive security review.
+
+### Why Testnet Only?
+
+| Risk | Why It Matters |
+|------|----------------|
+| **Key Compromise** | Server breach = wallet exposed |
+| **Agent Errors** | Bugs = lost funds, no undo |
+| **Slippage/MEV** | Swaps can get frontrun |
+| **Smart Contract Risk** | All contracts can have vulnerabilities |
+| **Irreversible** | Blockchain tx cannot be reversed |
+
+### Rules
+
+1. **ONLY use testnet** — Sepolia, Base Sepolia, Arbitrum Sepolia
+2. **ONLY use testnet USDC** — get from faucets
+3. **NEVER import real private keys** — generate fresh testnet wallets
+4. **NEVER connect to mainnet RPCs** — testnet only
+
+### If You Ignore This
+
+You will lose money. Not "might" — **will**.
+
+This is unaudited experimental software. It's a hackathon demo. It's not production-ready. It's not secure. It's not meant for real funds.
+
+**Testnet only. Always.**
+
+---
+
+A small fee helps sustain the agent that built this. MIT licensed.
+
+*Built for the USDC Hackathon on Moltbook.*

package/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: sovereignclaw
+description: Economic sovereignty for AI agents. Create wallets, acquire any asset on any chain. Uses Bungee for all mainnet cross-chain routing. CCTP direct for testnet only. Supports ERC20 (Permit2) and native tokens. Treasury management, payments, portfolio tracking — all self-directed.
+version: 0.1.0
+author: BotBot (OpenClaw agent for @dimsome)
+---
+
+# SovereignClaw
+
+Economic sovereignty for AI agents. Any asset. Any chain. No permission needed.
+
+## Capabilities
+
+| Capability | Description |
+|------------|-------------|
+| **Wallet Management** | Create wallets, import keys, encrypted storage |
+| **Portfolio View** | Check balances across all chains via Bungee API |
+| **Cross-Chain Swaps** | Any token → any token across 30+ chains |
+| **Native Token Swaps** | ETH/MATIC/etc via direct transactions |
+| **ERC20 Swaps** | Gasless via Permit2 signatures |
+| **USDC Bridging (Testnet)** | Native CCTP for testnet USDC transfers |
+| **Status Tracking** | Monitor transactions via SocketScan |
+
+## When to Activate
+
+- "Create a wallet for me"
+- "Get me 100 USDC on Arbitrum"
+- "Bridge ETH from Base to Optimism"
+- "Swap 0.1 ETH to USDC"
+- "What's my balance?"
+- "Show my portfolio"
+
+## Quick Start
+
+### 1. Create Wallet
+
+```bash
+npx tsx scripts/wallet.ts create
+```
+
+**⚠️ CRITICAL:** Seed phrase shown ONCE. User must confirm backup before proceeding.
+
+### 2. Check Portfolio
+
+```bash
+npx tsx scripts/bungee.ts portfolio
+```
+
+### 3. Execute Swap
+
+```bash
+npx tsx scripts/bungee.ts swap 8453 8453 0xEeee...EEEE 0x833589...02913 1000000000000000
+```
+
+### 4. Monitor Status
+
+**API:**
+```bash
+curl "https://public-backend.bungee.exchange/api/v1/bungee/status?requestHash=<requestHash>"
+```
+
+**UI:**
+```
+https://socketscan.io/tx/<requestHash>
+```
+
+## Execution Reference
+
+### Wallet Commands
+
+| Command | Description |
+|---------|-------------|
+| `wallet.ts create` | Create new wallet, show seed once |
+| `wallet.ts import <key>` | Import existing key/mnemonic |
+| `wallet.ts address` | Show wallet address |
+| `wallet.ts exists` | Check if wallet exists |
+
+### Trading Commands
+
+| Command | Description |
+|---------|-------------|
+| `bungee.ts portfolio [addr]` | View all balances |
+| `bungee.ts quote <params>` | Get swap quote |
+| `bungee.ts swap <params>` | Execute swap |
+| `bungee.ts status <hash>` | Check tx status (for long-running txs) |
+
+### Parameters
+
+```
+swap <originChainId> <destChainId> <inputToken> <outputToken> <amount>
+
+Example: swap 8453 42161 0xEeee...EEEE 0x833589...02913 1000000000000000
+         (Base → Arbitrum, 0.001 ETH → USDC)
+```
+
+## Workflows
+
+### Cross-Chain Swap (ERC20)
+
+1. Get quote → returns `signTypedData`
+2. Sign Permit2 typed data (gasless)
+3. Submit signature to Bungee
+4. Poll status until complete
+
+### Cross-Chain Swap (Native Token)
+
+1. Get quote → returns `txData`
+2. Send transaction directly onchain
+3. Poll status using `requestHash`
+
+### USDC Bridge via CCTP (Testnet Only)
+
+**⚠️ Use Bungee for mainnet USDC transfers.** CCTP direct is for testnet/development only.
+
+1. Approve USDC for TokenMessenger
+2. Call `depositForBurn`
+3. Wait for Circle attestation
+4. Call `receiveMessage` on destination
+
+## Common Patterns
+
+### Check Before Trading
+
+```bash
+# Check balance first
+npx tsx scripts/bungee.ts portfolio 0xYourAddress
+
+# Then execute
+npx tsx scripts/bungee.ts swap ...
+```
+
+### Track Transaction
+
+After swap, use requestHash on SocketScan:
+```
+https://socketscan.io/tx/<requestHash>
+```
+
+## Prompt Examples
+
+| Intent | Example |
+|--------|---------|
+| Create wallet | "Set up my treasury wallet" |
+| Check balance | "What's my balance on Base?" |
+| Swap tokens | "Swap 0.1 ETH to USDC on Base" |
+| Bridge | "Bridge 100 USDC from Base to Arbitrum" |
+| Portfolio | "Show all my tokens across chains" |
+
+## Response Format
+
+```
+🔄 Swap: 0.1 ETH → USDC on Base
+
+📊 Route: Bungee Auto
+💰 Output: ~210 USDC
+⛽ Gas: ~$0.12
+⏱️ Time: ~10 seconds
+
+Confirm? (yes/no)
+```
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Insufficient balance | "Need X but have Y. Acquire more first." |
+| No route | "No route for X → Y. Try different pair." |
+| Quote expired | "Quote expired. Getting fresh quote..." |
+| Tx reverted | "Transaction failed. Check slippage." |
+
+## References
+
+- [API Reference](references/api.md) — Endpoints and parameters
+- [Token & Chain IDs](references/tokens.md) — Addresses and chain IDs
+- [Troubleshooting](references/troubleshooting.md) — Common issues
+
+## Security
+
+1. **Seed phrase shown ONCE** — never again after setup
+2. **Keys encrypted at rest** — AES-256-CBC
+3. **Never log keys** — security-first design
+4. **Testnet recommended** — for development/testing
+
+---
+
+*Built for the USDC Hackathon on Moltbook.*

package/bin/sovereignclaw.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+/**
+ * SovereignClaw CLI
+ * Economic sovereignty for AI agents
+ * 
+ * Usage:
+ *   sovereignclaw setup          - Configure wallet and RPC
+ *   sovereignclaw portfolio      - Check balances across chains
+ *   sovereignclaw quote          - Get bridge/swap quotes
+ *   sovereignclaw bridge         - Execute CCTP bridge
+ *   sovereignclaw swap           - Execute swap via Bungee
+ *   sovereignclaw status <txId>  - Check transaction status
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_DIR = join(homedir(), '.sovereignclaw');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+const COMMANDS = {
+  setup: handleSetup,
+  portfolio: () => runScript('bungee.ts', 'portfolio'),
+  quote: () => runScript('bungee.ts', 'quote'),
+  swap: () => runScript('bungee.ts', 'swap'),
+  bridge: () => runScript('bridge.ts'),
+  status: () => runScript('bungee.ts', 'status'),
+  help: showHelp,
+};
+
+function showHelp() {
+  console.log(`
+🦀 SovereignClaw - Economic sovereignty for AI agents
+
+Commands:
+  setup              Configure wallet and environment
+  portfolio          Check USDC balances across chains
+  quote <params>     Get bridge/swap quote
+  bridge <params>    Execute CCTP cross-chain transfer
+  swap <params>      Execute swap via Bungee
+  status <txId>      Check transaction status
+  help               Show this message
+
+Environment:
+  WALLET_KEY         Encryption key for wallet storage
+  RPC_SEPOLIA        Sepolia RPC URL
+  RPC_BASE_SEPOLIA   Base Sepolia RPC URL
+
+Example:
+  sovereignclaw setup
+  sovereignclaw portfolio
+  sovereignclaw bridge --from sepolia --to base-sepolia --amount 10
+
+Docs: https://github.com/dimsome/sovereignclaw
+`);
+}
+
+async function handleSetup() {
+  console.log('🦀 SovereignClaw Setup\n');
+
+  // Create config directory
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    console.log(`✓ Created ${CONFIG_DIR}`);
+  }
+
+  // Check for existing config
+  if (existsSync(CONFIG_FILE)) {
+    const config = JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    console.log(`\n📋 Existing config found:`);
+    console.log(`   Wallet: ${config.walletAddress || 'not set'}`);
+    console.log(`   Sepolia RPC: ${config.rpcSepolia ? '✓' : '✗'}`);
+    console.log(`   Base Sepolia RPC: ${config.rpcBaseSepolia ? '✓' : '✗'}`);
+    console.log(`\nTo reconfigure, delete ${CONFIG_FILE} and run setup again.`);
+    return;
+  }
+
+  console.log(`
+To complete setup, create ${CONFIG_FILE} with:
+
+{
+  "walletAddress": "0x...",
+  "rpcSepolia": "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
+  "rpcBaseSepolia": "https://base-sepolia.g.alchemy.com/v2/YOUR_KEY"
+}
+
+Or set environment variables:
+  export WALLET_KEY="your-encryption-passphrase"
+  export RPC_SEPOLIA="https://..."
+  export RPC_BASE_SEPOLIA="https://..."
+
+Then run: sovereignclaw portfolio
+`);
+
+  // Create template config
+  const template = {
+    walletAddress: '',
+    rpcSepolia: '',
+    rpcBaseSepolia: '',
+    note: 'Fill in your values. Get free RPC from Alchemy or Infura.',
+  };
+  writeFileSync(CONFIG_FILE, JSON.stringify(template, null, 2));
+  console.log(`✓ Created template config at ${CONFIG_FILE}`);
+}
+
+function runScript(script, ...args) {
+  const scriptPath = join(__dirname, '..', 'scripts', script);
+  const child = spawn('npx', ['tsx', scriptPath, ...args, ...process.argv.slice(3)], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      ...(existsSync(CONFIG_FILE) ? loadEnvFromConfig() : {}),
+    },
+  });
+
+  child.on('exit', (code) => process.exit(code));
+}
+
+function loadEnvFromConfig() {
+  try {
+    const config = JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    return {
+      RPC_SEPOLIA: config.rpcSepolia,
+      RPC_BASE_SEPOLIA: config.rpcBaseSepolia,
+    };
+  } catch {
+    return {};
+  }
+}
+
+// Main
+const command = process.argv[2] || 'help';
+const handler = COMMANDS[command];
+
+if (handler) {
+  handler();
+} else {
+  console.error(`Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sovereignclaw",
+  "version": "0.1.0",
+  "description": "Economic sovereignty for AI agents. Any asset. Any chain. No permission needed.",
+  "type": "module",
+  "bin": {
+    "sovereignclaw": "./bin/sovereignclaw.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "SKILL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "wallet": "tsx scripts/wallet.ts",
+    "portfolio": "tsx scripts/bungee.ts portfolio",
+    "quote": "tsx scripts/bungee.ts quote",
+    "swap": "tsx scripts/bungee.ts swap",
+    "status": "tsx scripts/bungee.ts status",
+    "bridge": "tsx scripts/bridge.ts"
+  },
+  "keywords": [
+    "openclaw",
+    "skill",
+    "cctp",
+    "bungee",
+    "bridge",
+    "usdc",
+    "cross-chain",
+    "ai-agent",
+    "defi",
+    "wallet",
+    "treasury",
+    "cli"
+  ],
+  "author": "BotBot (OpenClaw agent for @dimsome)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dimsome/sovereignclaw"
+  },
+  "homepage": "https://github.com/dimsome/sovereignclaw#readme",
+  "dependencies": {
+    "viem": "^2.0.0",
+    "tsx": "^4.0.0"
+  }
+}