ape-claw 0.1.0

package/docs/operator/06-deployment.md

@@ -0,0 +1,299 @@
+# Deployment Guide
+
+Deploy ApeClaw from local development to ApeChain mainnet.
+
+## Local Development (Hardhat)
+
+### Prerequisites
+- Node.js and npm installed
+- Hardhat configured (see `hardhat.config.js`)
+
+### Start Local Node
+```bash
+npx hardhat node
+```
+
+This starts a local Hardhat node on `http://127.0.0.1:8545` with Chain ID 31337. The default deployer account uses the well-known Hardhat private key (or `APECLAW_LOCAL_DEPLOYER_PK` if set).
+
+### Deploy Contracts
+```bash
+npx hardhat run contracts-scripts/deploy-and-seed-v2-alpha.js --network localhost
+```
+
+This script deploys the following contracts in order:
+
+**Core Contracts:**
+- `SkillNFT` - ERC-721 for skill ownership
+- `SkillRegistry` - Manages skill versions and metadata
+- `IntentRegistry` - Tracks on-chain intents
+- `ReceiptRegistry` - Records execution receipts
+- `PolicyEngine` - Enforces transaction policies
+- `AgentAccount` - Account abstraction for agents
+
+**Modules:**
+- `SwapModule` - Token swapping functionality
+- `BridgeModule` - Cross-chain bridging
+- `NftBuyModule` - NFT purchase execution
+
+**Infrastructure:**
+- `PodVault` - Treasury with deployer as sole member (100% shares)
+
+**Configuration:**
+- PolicyEngine configured with:
+  - `maxValuePerTx`: 1 ETH
+  - Allowlisted modules: SwapModule, BridgeModule, NftBuyModule
+  - Optional MockTarget for testing (if contract exists)
+
+**Seeding:**
+- Reads all `.json` files from `skillcards/seed/`
+- Mints Skill NFTs with 5% royalty to PodVault
+- Publishes skill versions with content hashes and URIs
+- Uses `APECLAW_SKILLCARD_URI_BASE` env var for URIs (defaults to `file://`)
+
+**Output:**
+- Contract addresses printed to console
+- Deployment record saved to `state/v2-deployments/localhost.json`
+- Environment variable export commands printed
+
+### Start Backend
+```bash
+npm run telemetry
+# or: node src/server/index.mjs
+```
+
+The modular telemetry server:
+- Runs on port 8787 (configurable via `APE_CLAW_UI_PORT`)
+- Serves the dashboard UI at `/ui`
+- Provides SSE event stream at `/events` (with Last-Event-ID reconnect support)
+- Handles event backlog at `/events/backlog`
+- Manages clawbot registration, chat, quotes, and bridge requests
+- Supports file-based (default) or SQLite storage (`APE_CLAW_STORAGE=sqlite`)
+- Includes CORS allowlist, rate limiting, body size limits, structured logging (pino)
+
+The legacy monolithic server is still available via `npm run telemetry:legacy`.
+
+### Environment Variables (Local)
+```bash
+# Optional: Override local deployer key
+export APECLAW_LOCAL_DEPLOYER_PK=0x...
+
+# Optional: Set skillcard URI base
+export APECLAW_SKILLCARD_URI_BASE=https://your-cdn.com/skillcards
+```
+
+## ApeChain Mainnet Deployment
+
+### Prerequisites
+- ApeChain RPC URL (public or private endpoint)
+- Funded deployer wallet with sufficient APE for gas
+- Private key for deployment (keep secure!)
+
+### Environment Setup
+```bash
+# Required: ApeChain RPC endpoint
+export APE_CLAW_V2_RPC_URL=https://rpc.apechain.com/http
+# Or use legacy env var name:
+export RPC_URL_33139=https://rpc.apechain.com/http
+
+# Required: Deployer private key (NEVER commit this!)
+export APE_CLAW_V2_PRIVATE_KEY=0x...
+```
+
+**Security Notes:**
+- Never commit private keys to version control
+- Use environment variables or secure secret management
+- Consider using a hardware wallet or multisig for production deployments
+- The deploy script validates that RPC and private key are set for `apechain` network
+
+### Deploy
+```bash
+npx hardhat run contracts-scripts/deploy-and-seed-v2-alpha.js --network apechain
+```
+
+The deployment process:
+1. Validates environment variables
+2. Connects to ApeChain (Chain ID 33139)
+3. Deploys all contracts sequentially
+4. Configures PolicyEngine
+5. Seeds skills from `skillcards/seed/`
+6. Saves deployment record to `state/v2-deployments/apechain.json`
+
+**Deployment Output:**
+The script prints:
+- All contract addresses
+- Deployment summary JSON
+- Environment variable export commands
+
+Example output:
+```json
+{
+  "skillNft": "0x...",
+  "registry": "0x...",
+  "intents": "0x...",
+  "receipts": "0x...",
+  "policy": "0x...",
+  "agentAccount": "0x...",
+  "podVault": "0x...",
+  "modules": {
+    "swap": "0x...",
+    "bridge": "0x...",
+    "nftBuy": "0x..."
+  },
+  "seeded": 42,
+  "network": "apechain",
+  "chainId": 33139
+}
+```
+
+### Verify Contracts
+If ApeChain has a block explorer with contract verification support:
+
+1. Get verification API details from the explorer
+2. Use Hardhat's verify plugin or explorer's manual verification
+3. Verify each contract with constructor arguments
+
+Example (if Hardhat verify plugin configured):
+```bash
+npx hardhat verify --network apechain <CONTRACT_ADDRESS> <CONSTRUCTOR_ARGS>
+```
+
+### Production Backend
+
+Deploy the telemetry server to a hosting platform:
+
+**Vercel Deployment:**
+1. Configure `vercel.json` for rewrites:
+```json
+{
+  "rewrites": [
+    { "source": "/ui", "destination": "/ui/index.html" },
+    { "source": "/events", "destination": "/api/events" }
+  ]
+}
+```
+
+2. Set environment variables in Vercel dashboard:
+   - `APE_CLAW_UI_PORT` (if needed)
+   - `APE_CLAW_V2_RPC_URL` (for receipt reading)
+   - `APE_CLAW_V2_RECEIPT_REGISTRY` (contract address)
+   - `MOLTBOOK_API_BASE` (for chat)
+   - `MOLTBOOK_APP_KEY` (if using Moltbook)
+   - `APE_CLAW_REGISTRATION_KEY` (for open registration)
+
+**Docker Compose (recommended for Railway/VPS):**
+
+```bash
+cp .env.example .env
+# Edit .env with your keys
+docker compose --env-file .env up -d --build
+```
+
+The `docker-compose.yml` includes:
+- Pinned `node:22-alpine` image with non-root `apeclaw` user
+- Persistent volume for state (`apeclaw_state`)
+- Environment variable passthrough for all configuration
+- Healthcheck (`GET /api/health`)
+- Memory limit (512 MB)
+- Restart policy (`unless-stopped`)
+
+**SQLite Backend (recommended for production):**
+
+```bash
+export APE_CLAW_STORAGE=sqlite
+```
+
+Migrate existing file-based state:
+
+```bash
+node scripts/migrate-to-sqlite.mjs
+```
+
+**Other Platforms:**
+- Railway, Render, Fly.io, or any Node.js hosting
+- Ensure SSE (Server-Sent Events) are supported
+- `APE_CLAW_CORS_ORIGINS` is logged at startup; current allowlist is defined in server middleware (includes `https://apeclaw.ai` + localhost variants)
+- Set up persistent storage for events/chat if required
+
+## Supported Networks
+
+### ApeChain Mainnet
+- **Chain ID**: 33139
+- **Network Name**: `apechain`
+- **RPC**: Configure via `APE_CLAW_V2_RPC_URL`
+
+### Hardhat Local
+- **Chain ID**: 31337
+- **Network Name**: `localhost`
+- **RPC**: `http://127.0.0.1:8545`
+- **Default Account**: First Hardhat account (or `APECLAW_LOCAL_DEPLOYER_PK`)
+
+## Post-Deployment Checklist
+
+### Contract Deployment
+- [ ] All contract addresses exported as environment variables
+- [ ] Deployment record saved to `state/v2-deployments/`
+- [ ] Contracts verified on block explorer (if available)
+
+### PolicyEngine Configuration
+- [ ] `maxValuePerTx` set appropriately (default: 1 ETH)
+- [ ] Modules allowlisted: SwapModule, BridgeModule, NftBuyModule
+- [ ] Target contracts allowlisted (if needed)
+- [ ] Function selectors allowlisted (if needed)
+
+### PodVault Setup
+- [ ] PodVault deployed with correct members
+- [ ] Share distribution configured (default: deployer has 100%)
+- [ ] Royalty receiver set to PodVault (5% BPS = 500)
+
+### Backend Configuration
+- [ ] Backend can reach RPC endpoint
+- [ ] `APE_CLAW_V2_RPC_URL` set correctly
+- [ ] `APE_CLAW_V2_RECEIPT_REGISTRY` set to deployed address
+- [ ] Telemetry server accessible at expected URL
+- [ ] SSE endpoint working (`/events`)
+
+### UI Configuration
+- [ ] Dashboard accessible at `/ui`
+- [ ] UI can read contract addresses from deployment record
+- [ ] Backend URL configured (default or override)
+- [ ] Collections loaded correctly
+
+### Skill Seeding
+- [ ] All skills from `skillcards/seed/` minted
+- [ ] Skill versions published with correct hashes
+- [ ] Skill URIs accessible (if using CDN)
+- [ ] Royalties configured (5% to PodVault)
+
+### Testing
+- [ ] Can register a clawbot
+- [ ] Can send telemetry events
+- [ ] Dashboard shows events in real-time
+- [ ] NFT purchase flow works (if testing)
+- [ ] Bridge operations work (if testing)
+- [ ] Receipt recording works (if enabled)
+
+## Troubleshooting
+
+### Deployment Fails
+- Check RPC URL is accessible
+- Verify private key has sufficient balance
+- Ensure network name matches `hardhat.config.js`
+- Check gas prices if network is congested
+
+### Skills Not Seeding
+- Verify `skillcards/seed/` directory exists
+- Check JSON files are valid skillcards
+- Ensure deployer has enough gas
+- Review skillcard URI configuration
+
+### Backend Not Starting
+- Check port 8787 is available
+- Verify Node.js version compatibility
+- Review environment variable configuration
+- Check file permissions for state directory
+
+### UI Not Connecting
+- Verify backend URL is correct
+- Check CORS configuration
+- Ensure SSE endpoint is accessible
+- Review browser console for errors

package/docs/operator/07-safety-and-policy.md

@@ -0,0 +1,311 @@
+# Safety and Policy
+
+## PolicyEngine Contract
+
+The PolicyEngine is an onchain contract that enforces safety policies for agent operations. It acts as a gatekeeper, allowing only approved modules, targets, and selectors to execute transactions.
+
+### Role
+
+The PolicyEngine:
+- **Validates transactions** before execution
+- **Enforces value caps** per transaction
+- **Maintains allowlists** for modules, targets, and selectors
+- **Prevents unauthorized operations** by blocking non-allowlisted calls
+
+### Integration
+
+AgentAccount contracts are configured with a PolicyEngine address. When an agent executes a skill via `AgentAccount.executeSkill()`, the PolicyEngine validates the transaction before it's executed.
+
+## Module Allowlisting
+
+Modules are contract addresses that implement specific functionality (e.g., SwapModule, BridgeModule, NftBuyModule).
+
+### How It Works
+
+1. **Deploy modules**: Deploy module contracts (SwapModule, BridgeModule, NftBuyModule)
+2. **Allowlist modules**: Call `PolicyEngine.setModuleAllowed(moduleAddress, true)`
+3. **Agent execution**: Agents can only call allowlisted modules
+
+### Example
+
+```solidity
+// Deploy modules
+SwapModule swapModule = new SwapModule();
+BridgeModule bridgeModule = new BridgeModule();
+NftBuyModule nftBuyModule = new NftBuyModule();
+
+// Allowlist modules
+policyEngine.setModuleAllowed(address(swapModule), true);
+policyEngine.setModuleAllowed(address(bridgeModule), true);
+policyEngine.setModuleAllowed(address(nftBuyModule), true);
+```
+
+### Checking Allowlist Status
+
+Query the PolicyEngine contract:
+```solidity
+bool isAllowed = policyEngine.isModuleAllowed(moduleAddress);
+```
+
+## Target Allowlisting
+
+Targets are contract addresses that agents interact with (e.g., DEX routers, NFT marketplaces).
+
+### How It Works
+
+1. **Identify targets**: Determine which contracts agents need to call
+2. **Allowlist targets**: Call `PolicyEngine.setTargetAllowed(targetAddress, true)`
+3. **Agent execution**: Agents can only call allowlisted targets
+
+### Example
+
+```solidity
+// Allowlist a DEX router
+address dexRouter = 0x...;
+policyEngine.setTargetAllowed(dexRouter, true);
+
+// Allowlist an NFT marketplace
+address seaport = 0x0000000000000068f116a894984e2db1123eb395;
+policyEngine.setTargetAllowed(seaport, true);
+```
+
+### Use Cases
+
+- **DEX routers**: For token swaps
+- **NFT marketplaces**: For NFT purchases
+- **Bridge contracts**: For cross-chain transfers
+- **Mock targets**: For testing (local dev only)
+
+## Selector Allowlisting
+
+Selectors are function signatures (first 4 bytes of function hash) that can be called on a target.
+
+### How It Works
+
+1. **Identify selectors**: Determine which functions agents need to call
+2. **Allowlist selectors**: Call `PolicyEngine.setSelectorAllowed(targetAddress, selector, true)`
+3. **Agent execution**: Agents can only call allowlisted selectors on allowlisted targets
+
+### Example
+
+```solidity
+// Allowlist a specific function on a target
+address target = 0x...;
+bytes4 selector = 0x12345678;  // Function signature
+policyEngine.setSelectorAllowed(target, selector, true);
+```
+
+### Benefits
+
+- **Granular control**: Allow only specific functions, not entire contracts
+- **Reduced attack surface**: Even if a target is allowlisted, only approved functions can be called
+- **Flexible policies**: Different selectors can have different risk levels
+
+## Per-Transaction Value Cap
+
+The PolicyEngine enforces a maximum value (native token amount) per transaction.
+
+### How It Works
+
+1. **Set cap**: Call `PolicyEngine.setMaxValuePerTx(maxValue)`
+2. **Validation**: Every transaction is checked against this cap
+3. **Rejection**: Transactions exceeding the cap are rejected
+
+### Example
+
+```solidity
+// Set max value to 1 ETH (or 1 APE on ApeChain)
+uint256 maxValue = 1 ether;
+policyEngine.setMaxValuePerTx(maxValue);
+```
+
+### Default Configuration
+
+From `deploy-and-seed-v2-alpha.js`:
+```javascript
+await policy.write.setMaxValuePerTx([parseEther("1")]);
+// maxValuePerTx = 1 ETH (or 1 APE)
+```
+
+### Checking Value Cap
+
+Query the PolicyEngine contract:
+```solidity
+uint256 maxValue = policyEngine.maxValuePerTx();
+```
+
+## Dry-Run Mode
+
+Dry-run mode is the default safety posture. It allows testing and validation without executing transactions.
+
+### How It Works
+
+1. **Default behavior**: All commands run in dry-run by default
+2. **No execution**: Transactions are not broadcast to the chain
+3. **Validation**: Policy checks still run, but no state changes occur
+4. **Explicit opt-in**: Use `--execute` flag to enable real execution
+
+### Example
+
+```bash
+# Dry-run (default)
+ape-claw nft buy --quote q_123 --json
+
+# Execute (explicit)
+ape-claw nft buy --quote q_123 --execute --autonomous --json
+```
+
+### Benefits
+
+- **Safe testing**: Test workflows without risk
+- **Policy validation**: Verify policy checks before execution
+- **Cost savings**: No gas fees in dry-run mode
+- **Audit trail**: Dry-run events are still logged to telemetry
+
+## Skill Vetting
+
+Skills should be vetted before installation and use, especially user-submitted skills.
+
+### Vetting Checklist
+
+- [ ] **No secrets**: No private keys, API keys, or sensitive data
+- [ ] **No destructive commands**: No irreversible operations without safeguards
+- [ ] **Error handling**: Proper error handling and recovery
+- [ ] **Documentation**: Clear description and usage instructions
+- [ ] **Risk assessment**: Appropriate risk tier assignment
+- [ ] **Source verification**: Verify provenance and publisher
+
+### Risk Tiers
+
+| Tier | Label | Description |
+|------|-------|-------------|
+| 0 | unknown | Unassessed risk |
+| 1 | low | Read-only or minimal impact |
+| 2 | medium | Moderate impact, reversible |
+| 3 | high | High impact, potentially irreversible |
+
+### Vetting Process
+
+1. **Review SkillCard**: Check JSON structure and content
+2. **Test in dry-run**: Run skill in dry-run mode first
+3. **Audit code**: Review any executable code or scripts
+4. **Check dependencies**: Verify external dependencies are safe
+5. **Mark as vetted**: Set `vettedOk: true` if approved
+
+### User Skills
+
+User-submitted skills (`source: "user"`) are **not vetted by default**:
+- `vettedOk: false` initially
+- Require manual review
+- Should be tested before use
+
+### Seed Skills
+
+Seed skills (`source: "seed"`) are **trusted by default**:
+- `vettedOk: true` automatically
+- Shipped with ApeClaw
+- Pre-configured and safe
+
+## Security Posture
+
+### Never Store Keys in Files
+
+**Rule**: Never store private keys, API keys, or secrets in:
+- SkillCard JSON files
+- Workspace files (AGENTS.md, etc.)
+- Version control
+- Public repositories
+
+**Use instead**:
+- Environment variables (`APE_CLAW_PRIVATE_KEY`)
+- Local auth profile (`ape-claw auth set`)
+- Secure key management systems
+
+### Audit Skills Before Install
+
+**Rule**: Always audit skills before installation, especially:
+- User-submitted skills
+- Skills from untrusted sources
+- Skills with high risk tiers
+- Skills with unclear provenance
+
+**Process**:
+1. Review SkillCard JSON
+2. Check risk tier
+3. Test in dry-run mode
+4. Verify no secrets included
+5. Review executable code (if any)
+
+### Policy Enforcement
+
+**Onchain (PolicyEngine)**:
+- Module allowlisting
+- Target allowlisting
+- Selector allowlisting
+- Value caps
+
+**Offchain (CLI)**:
+- Collection allowlists
+- Daily spend caps
+- Confirmation phrases
+- Simulation requirements
+
+### Default Safety Settings
+
+From `config/policy.json`:
+```json
+{
+  "nftBuy": {
+    "maxPricePerTx": 10000,
+    "simulationRequired": true
+  },
+  "execution": {
+    "dailySpendCap": 100000,
+    "confirmPhraseRequired": true
+  }
+}
+```
+
+### Autonomous Mode
+
+When `autonomousMode: true`:
+- `dailySpendCap` is **mandatory**
+- Confirmation phrases are auto-generated
+- Still requires `--execute` flag
+- Still requires simulation (if enabled)
+
+## Best Practices
+
+1. **Start with dry-run**: Always test in dry-run first
+2. **Use allowlists**: Only allow necessary modules/targets/selectors
+3. **Set value caps**: Limit maximum transaction value
+4. **Vet skills**: Review skills before installation
+5. **Never store secrets**: Use environment variables
+6. **Monitor telemetry**: Watch for policy violations
+7. **Use simulation**: Enable simulation for critical operations
+8. **Set spend caps**: Limit daily spending
+9. **Require confirmations**: Use confirmation phrases for high-value operations
+10. **Audit regularly**: Review policy settings and allowlists periodically
+
+## Troubleshooting
+
+**PolicyEngine blocking transactions:**
+- Check module is allowlisted
+- Check target is allowlisted
+- Check selector is allowlisted (if required)
+- Check value doesn't exceed cap
+
+**Dry-run not working:**
+- Ensure `--execute` flag is not set
+- Check policy configuration
+- Verify no private key is required for dry-run
+
+**Skill vetting issues:**
+- User skills require manual vetting
+- Check `vettedOk` status in index
+- Review SkillCard for security issues
+
+**Value cap exceeded:**
+- Reduce transaction value
+- Increase `maxValuePerTx` in PolicyEngine (if authorized)
+- Split transaction into smaller amounts