From d0ce844b5990688fcaf8dcacef044fb99805e668 Mon Sep 17 00:00:00 2001 From: Paul Grey Date: Sat, 16 May 2026 11:53:58 +1200 Subject: [PATCH] docs: lead Step 1 with WebAuth + seed-to-K1 extraction (everyone, not just CLI users) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every "create your account" surface across the project was telling operators to use `proton account:create myagent` as the recommended path. That command only works for operators who already control a funded XPR account — which excludes essentially every first-time operator. The audit didn't catch this because it works for the auditors (who all have funded accounts), but it's a wall for new users. The canonical path is webauth.com — fresh accounts, free, KYC-able, exists for everyone. What was missing from the docs: the seed-phrase-to-PVT_K1_ extraction step in between "I have an account on webauth.com" and "I run proton key:add". This commit closes that gap on every operator surface. ## New canonical Step 1 / 2 / 3 (everywhere) 1. Create the agent account at webauth.com → save the 12-word seed phrase offline. 2. Extract the K1 private key from the seed phrase. Two paths: - Explorer utility (desktop): https://explorer.xprnetwork.org/wallet/utilities/format-keys → "Mnemonic to Private Key" → paste seed → copy PVT_K1_ - WebAuth mobile app: open the account → Backup Wallet → reveal / export private key → copy PVT_K1_ 3. Load the key: `proton key:add` (interactive) or `echo "no" | proton key:add PVT_K1_...` (hosted consoles). `proton account:create myagent` is now demoted to a footnote: "if you already control a funded XPR account, this gives you the K1 directly — skip step 2." ## Why this matters The previous Step 1 had `proton account:create` as the "recommended" path. A first-time operator running it gets either: - A prompt for a creator account they don't have, or - An unhelpful EOSIO error about RAM / no sponsor Then they bounce. The new flow lets every operator complete Step 1. ## Surfaces updated - frontend/src/pages/get-started.tsx — Step 1 split into 3 numbered steps (account creation, seed extraction, keychain load) with two path cards (Explorer utility vs WebAuth mobile) for the extraction step. All subsequent steps renumbered (Deploy → 4, Pillar 2 → 5, Register/build trust → 6). - frontend/src/pages/get-started.tsx — SiteHead description updated. - create-xpr-agent/template/QUICKSTART.md — Step 1 rewritten, Steps 2-4 renumbered to 4-6. - create-xpr-agent/template/README.md — "Creating an Account" block rewritten with the three-step flow. - openclaw/starter/{QUICKSTART,README}.md — synced (CI scaffold- sanity diff-checks these). - openclaw/README.md — npm landing page's "Keychain setup" block expanded to name both extraction paths. - docs/SECURITY.md — Flow A (WebAuth starting state) now names the two extraction paths explicitly before the updateauth recipe. ## Versions - @xpr-agents/openclaw → 0.4.4 (README content only — npm page reflects the corrected operator path) - create-xpr-agent → 0.6.1 (template QUICKSTART + README change, scaffold output matches the live get-started page) ## Verification - frontend builds clean (all 13 routes prerendered) - 80 openclaw tests pass - CI scaffold-sanity covers template-vs-starter diffs for all modified surfaces (start.sh, setup-security.sh, .env.example unchanged this PR; READMEs/QUICKSTART are content-only) --- create-xpr-agent/package.json | 2 +- create-xpr-agent/template/QUICKSTART.md | 69 +++++--- create-xpr-agent/template/README.md | 36 ++-- docs/SECURITY.md | 14 +- frontend/src/pages/get-started.tsx | 89 +++++++--- openclaw/README.md | 15 +- openclaw/package.json | 2 +- openclaw/starter/QUICKSTART.md | 219 ++++++++++-------------- openclaw/starter/README.md | 40 ++--- 9 files changed, 259 insertions(+), 227 deletions(-) diff --git a/create-xpr-agent/package.json b/create-xpr-agent/package.json index 509e466..bb7c201 100644 --- a/create-xpr-agent/package.json +++ b/create-xpr-agent/package.json @@ -1,6 +1,6 @@ { "name": "create-xpr-agent", - "version": "0.6.0", + "version": "0.6.1", "description": "Create an autonomous AI agent on XPR Network", "type": "module", "bin": "./create.mjs", diff --git a/create-xpr-agent/template/QUICKSTART.md b/create-xpr-agent/template/QUICKSTART.md index 153c8e0..15e75d8 100644 --- a/create-xpr-agent/template/QUICKSTART.md +++ b/create-xpr-agent/template/QUICKSTART.md @@ -25,47 +25,60 @@ Your blockchain private key is **not** a flag. It lives in the proton CLI's encr --- -## Step 1: Create a XPR Network Account +## Step 1: Create the agent account at webauth.com -Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots). +Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots). Create a **fresh, dedicated** account for your agent — don't reuse your personal account. -**Option A: Proton CLI (recommended — gives you a private key directly)** +1. Go to [webauth.com](https://webauth.com) → create an XPR Network account → pick a name +2. WebAuth gives you a **12-word seed phrase**. Save it offline (paper, password manager). You'll need it in Step 2. +3. WebAuth installs a biometric key on the account so you can sign from your phone. The biometric key can't be exported and the agent can't use it for autonomous signing — that's what Step 2 fixes. + +> **Tip:** If you already control a funded XPR account on chain, you can create the agent account via the proton CLI instead: `proton account:create myagent`. Skip Step 2 — you already have the `PVT_K1_`. This is uncommon for first-time operators. + +--- + +## Step 2: Extract the K1 private key from your seed phrase + +The seed phrase encodes a K1 keypair registered on the agent account's `owner` permission. The agent needs that `PVT_K1_` in plain form so the proton CLI can use it for signing. Pick one path: + +**Path A — Explorer utility (desktop)** + +1. Open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys) +2. Find the **"Mnemonic to Private Key"** section +3. Paste your 12-word seed phrase +4. Copy the resulting `PVT_K1_...` + +**Path B — WebAuth mobile app** + +1. Open the WebAuth Wallet app +2. Select the agent account you just created +3. Open **Backup Wallet** → reveal / export private key +4. Authenticate (Face ID / fingerprint) and copy the `PVT_K1_...` + +> **Treat the seed phrase and the `PVT_K1_` as equally sensitive** until they're in the proton CLI keychain. Don't paste them into chat, logs, or screenshots. The Pillar 2 lockdown in `./setup-security.sh` (run after `./start.sh`) makes both recoverable if one leaks — but only after that step completes. + +--- + +## Step 3: Load the private key into the proton CLI keychain ```bash npm install -g @proton/cli # If `proton: command not found` after install, npm's global bin isn't on PATH: # export PATH="$(npm config get prefix)/bin:$PATH" -proton chain:set proton-test # testnet (or proton for mainnet) -proton account:create myagent # creates account + key pair -proton key:list # shows the public key + account binding - -# Load the private key into the encrypted keychain (interactive) -proton key:add # paste the PVT_K1_ here +proton chain:set proton # mainnet (or proton-test for testnet) +proton key:add # paste the PVT_K1_ from Step 2 # Or, if you're running on a hosted/web console that can't drive a TTY: echo "no" | proton key:add PVT_K1_yourkey -``` -**Option B: WebAuth Wallet** - -1. Go to [webauth.com](https://webauth.com) and create an account -2. Your account name appears in the wallet (e.g. `myagent`) -3. WebAuth uses biometrics (Face ID / fingerprint) — the keys can't be exported. To get a `PVT_K1_` key for autonomous agent signing: - ```bash - npm install -g @proton/cli - proton key:generate # creates a new PVT_K1_ / PUB_K1_ pair - ``` -4. In WebAuth Wallet → **Settings > Keys** → add the `PUB_K1_` public key to your `active` permission -5. Load the matching `PVT_K1_` into the CLI keychain: - ```bash - proton key:add # paste the PVT_K1_ here - ``` +proton key:list # verify: shows public key + account binding +``` -> **Security tip:** Create a **dedicated account** for your agent. Don't use your personal account. With the proton CLI keychain, the key lives encrypted on disk (or in plaintext if you run `proton key:unlock` for non-interactive signing) — it never enters the agent process's memory either way. +The key now lives encrypted on disk. The agent process never reads it — every signed transaction shells out to `proton transaction:push`. --- -## Step 2: Create Your Agent Project +## Step 4: Create Your Agent Project ```bash npx create-xpr-agent my-agent @@ -74,7 +87,7 @@ cd my-agent --- -## Step 3: Start Your Agent +## Step 5: Start Your Agent ```bash ./start.sh --account myagent --api-key sk-ant-xxx @@ -86,7 +99,7 @@ On first run, this downloads the agent runner from GitHub, installs dependencies --- -## Step 4: Verify It Works +## Step 6: Verify It Works ```bash # Check agent health diff --git a/create-xpr-agent/template/README.md b/create-xpr-agent/template/README.md index d65fc4b..d4b6458 100644 --- a/create-xpr-agent/template/README.md +++ b/create-xpr-agent/template/README.md @@ -80,31 +80,29 @@ Get an Anthropic API key at [console.anthropic.com](https://console.anthropic.co ### Creating an Account & Loading the Signing Key -**Option A: Proton CLI (recommended)** +The canonical flow: -```bash -npm install -g @proton/cli -proton chain:set proton-test # testnet (or proton for mainnet) -proton account:create myagent # creates account + key pair -proton key:add # paste the private key — stored encrypted -``` - -The key now lives in the proton CLI's encrypted keychain. The agent will shell out to `proton transaction:push` for every signed action — the key never enters the agent process's memory. +1. **Create the agent account at [webauth.com](https://webauth.com)** — pick a 1-12 char name (`a-z`, `1-5`, dots). WebAuth gives you a 12-word seed phrase. Save it offline. +2. **Extract the K1 private key from the seed phrase.** Two paths: + - **Explorer utility:** open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys) → "Mnemonic to Private Key" → paste seed → copy `PVT_K1_...` + - **WebAuth mobile app:** open the account → "Backup Wallet" → reveal / export private key → copy `PVT_K1_...` +3. **Load the private key into the proton CLI keychain:** -**Option B: WebAuth Wallet + a separate signing key** - -1. Create an account at [webauth.com](https://webauth.com) (biometric login, supports KYC) -2. WebAuth keys can't be exported. Generate a new key for autonomous signing: ```bash npm install -g @proton/cli - proton key:generate # generates a new PVT_K1_ / PUB_K1_ key pair - ``` -3. In WebAuth Wallet, go to **Settings > Keys** and add the `PUB_K1_` public key to your account's `active` permission -4. Load the matching private key into the CLI keychain: - ```bash - proton key:add # paste the PVT_K1_ here + proton chain:set proton # mainnet (or proton-test for testnet) + proton key:add # paste the PVT_K1_ from step 2 + # Or for hosted consoles without a TTY: + # echo "no" | proton key:add PVT_K1_yourkey + proton key:list # verify ``` +The key now lives encrypted on disk. The agent shells out to `proton transaction:push` for every signed action — the key never enters the agent process's memory. + +> **Already have a funded XPR account?** You can create the agent account from the proton CLI instead: `proton account:create myagent`. You'll get the `PVT_K1_` directly — skip step 2. This path only works if you already control a funded creator account; most operators come through the webauth.com path. + +> **Pillar 2 lockdown after first boot:** once the agent is running, run `./setup-security.sh` to delegate the agent's `owner` permission to a separate human account. Even if the keychain key ever leaks, an attacker can't rotate you out of the account. See [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md). + > **Security tip:** Create a **dedicated account** for the agent. With the proton CLI keychain, the chain key never enters your `.env` file or the agent process — even if the agent is fully compromised, the attacker cannot leak the key directly. ## Architecture diff --git a/docs/SECURITY.md b/docs/SECURITY.md index cc7aff9..baaa50c 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -89,13 +89,19 @@ permissions: active: threshold 1, keys: [PUB_WA_yyy] ← WebAuth biometric key ``` -The K1 key on `owner` is your exportable backup key (Settings → Backup in WebAuth). The `PUB_WA_` key on `active` is biometric — **it cannot be exported**, can only be used from your phone with Face ID / fingerprint, and is therefore **unusable for autonomous signing**. +The K1 key on `owner` is your exportable backup key. The seed phrase WebAuth gave you during account creation encodes the matching private key. The `PUB_WA_` key on `active` is biometric — **it cannot be exported**, can only be used from your phone with Face ID / fingerprint, and is therefore **unusable for autonomous signing**. -The setup moves the K1 from owner to active so the agent can sign with it via the proton CLI keychain, and replaces owner with your human account's active permission. One atomic transaction so the agent is never in an unsignable mid-state: +The setup moves the K1 from owner to active so the agent can sign with it via the proton CLI keychain, and replaces owner with your human account's active permission. One atomic transaction so the agent is never in an unsignable mid-state. + +First, extract the `PVT_K1_` from your seed phrase via either of these paths: + +- **Explorer utility:** open [`https://explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys), find the "Mnemonic to Private Key" section, paste your 12-word seed phrase, copy the resulting `PVT_K1_...`. +- **WebAuth mobile app:** open the account → "Backup Wallet" → reveal / export private key. Copy the `PVT_K1_...`. + +Both paths produce the same K1 — the one currently on `owner`. ```bash -# 1. Load the K1 (the one currently on owner) into the proton CLI keychain. -# WebAuth → Settings → Backup → reveal your private key, then: +# 1. Load the K1 (the one currently on owner) into the proton CLI keychain: proton key:add # paste PVT_K1_yourkey # 2. Sign one transaction with two updateauth actions: diff --git a/frontend/src/pages/get-started.tsx b/frontend/src/pages/get-started.tsx index 28af642..89bc2f0 100644 --- a/frontend/src/pages/get-started.tsx +++ b/frontend/src/pages/get-started.tsx @@ -58,7 +58,7 @@ export default function GetStarted() { <> @@ -122,48 +122,85 @@ export default function GetStarted() {
- {/* ── Step 1: Create account ── */} + {/* ── Step 1: Create agent account on WebAuth ── */}
1
-

Create an XPR Network account

+

Create the agent account at webauth.com

-

Easiest path: webauth.com — biometric login, supports KYC for up to +30 trust score, mints a fresh account for you.

+

+ Go to webauth.com and create a new XPR Network account for your agent. Pick a 1-12 character name (a-z, 1-5, dots). Use a fresh, dedicated account — not your personal account. +

+

+ WebAuth will give you a 12-word seed phrase. Save it offline (paper, password manager) — you'll need it in Step 2 to extract the private key. WebAuth also installs a biometric key on the account so you can sign from your phone, but that biometric key can't be exported and the agent can't use it for autonomous signing — that's why we extract the K1 next. +

- Already have an XPR account with funds? You can create the agent account from the proton CLI instead: + Want KYC on the account for +30 trust score points? Complete KYC inside WebAuth before continuing. Alternatively, you can claim the agent from a separate KYC'd human account later — that's the more common pattern (keeps the agent identity separate from your personal identity).

- - npm install -g @proton/cli - proton chain:set proton # mainnet (matches xpragents.com default) - proton account:create myagent # requires existing funded sponsor -

- Tip: use a dedicated account for the agent. Complete KYC on your human account so you can claim the agent later for +30 trust points. + Already have a funded XPR account? You can create the agent account from the proton CLI instead: proton account:create myagent. Skip Step 2 — you already have the PVT_K1_ for the new account.

- {/* ── Step 2: Load key into keychain ── */} + {/* ── Step 2: Extract PVT_K1_ from the seed phrase ── */}
2
-

Load your private key into the proton CLI keychain

+

Extract the K1 private key from your seed phrase

-

One-time setup. The key gets stored encrypted on disk and the agent never reads it directly.

- - proton key:add # paste the PVT_K1_yourkey +

+ The seed phrase encodes a K1 keypair that's registered on the agent account's owner permission. We need that PVT_K1_... in plain form so the proton CLI can use it for autonomous signing. Pick one of two paths: +

+ +
+
Path A — Explorer utility (works on desktop)
+
    +
  1. Open explorer.xprnetwork.org/wallet/utilities/format-keys
    2. +
  2. Find the "Mnemonic to Private Key" section
    3. +
  3. Paste your 12-word seed phrase
    4. +
  4. Copy the resulting PVT_K1_... string
    5. +
+
+ +
+
Path B — WebAuth mobile app
+
    +
  1. Open the WebAuth Wallet app on your phone
    2. +
  2. Select the agent account you just created
    3. +
  3. Open Backup Wallet → reveal / export private key
    4. +
  4. Authenticate (Face ID / fingerprint) and copy the PVT_K1_...
    5. +
+
+ +

+ Treat the seed phrase and the PVT_K1_ as equally sensitive until they're in the proton CLI keychain. Don't paste them into chat, logs, or screenshots. Pillar 2 in Step 4 makes both recoverable if either ever leaks — but only after you complete that step. +

+
+
+
+ + {/* ── Step 3: Load PVT_K1_ into proton CLI keychain ── */} +
+
3
+
+

Load the private key into the proton CLI keychain

+
+

One-time setup. The key gets stored encrypted on disk; the agent process never reads it directly — every signed transaction shells out to proton transaction:push.

+ + npm install -g @proton/cli + proton chain:set proton # mainnet (matches xpragents.com default) + proton key:add # paste the PVT_K1_ from Step 2

- On a hosted console without a real TTY (Pinata Agents, gateway containers), use the non-interactive form which auto-answers the encrypt prompt: + On a hosted console without a real TTY (Pinata Agents, gateway containers), the interactive prompt hangs — use the non-interactive form which auto-answers the encrypt prompt:

echo "no" | proton key:add PVT_K1_yourkey

- Verify with proton key:list — you should see your public key and account. If you don't have a PVT_K1_ to paste (e.g. you only have a WebAuth biometric key), run proton key:generate to make a K1 keypair, register the public key on your account's active permission via WebAuth Settings, then run proton key:add with the matching private key. + Verify: proton key:list should show your public key linked to the agent account.

@@ -210,9 +247,9 @@ export default function GetStarted() {
- {/* ── Step 3: Deploy (path-aware) ── */} + {/* ── Step 4: Deploy (path-aware) ── */}
-
3
+
4

Deploy your agent

{deployPath === 'standalone' ? ( @@ -247,9 +284,9 @@ export default function GetStarted() {
- {/* ── Step 4: Lock down owner (Pillar 2) ── */} + {/* ── Step 5: Lock down owner (Pillar 2) ── */}
-
4
+
5

Lock down owner permission (recommended — Pillar 2 security)

@@ -272,9 +309,9 @@ export default function GetStarted() {
- {/* ── Step 5: Build trust ── */} + {/* ── Step 6: Build trust ── */}
-
5
+
6

Register, claim, build trust

diff --git a/openclaw/README.md b/openclaw/README.md index d234869..222cc1c 100644 --- a/openclaw/README.md +++ b/openclaw/README.md @@ -173,8 +173,17 @@ npm i -g @proton/cli # 2. Point at the chain proton chain:set proton # mainnet (use `proton-test` for testnet) -# 3. Don't have an XPR account yet? -proton account:create myagent # or sign up at https://webauth.com +# 3. Create the agent account (if you don't have one yet). +# Most operators: sign up at https://webauth.com — it mints a fresh +# account, gives you a 12-word seed phrase, and supports KYC. +# Then extract the K1 private key from the seed via: +# - https://explorer.xprnetwork.org/wallet/utilities/format-keys +# ("Mnemonic to Private Key" section), or +# - WebAuth mobile app → Backup Wallet → reveal private key +# +# Alternatively, if you already control a funded XPR account, use: +# proton account:create myagent +# This creates the account + key pair in one step — no seed extraction. # 4. Load the key (interactive — pastes are hidden) proton key:add # paste your PVT_K1_ key; stored encrypted @@ -192,6 +201,8 @@ proton key:list # shows your account + public key # proton key:unlock ``` +After your first run, lock down the agent's `owner` permission so a leaked active key can't take over the account: `npx @xpr-agents/openclaw xpr-agents-setup-security --account myagent`. Full rationale: [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md). + ### Required environment variables ```env diff --git a/openclaw/package.json b/openclaw/package.json index 4c146fd..9529a30 100644 --- a/openclaw/package.json +++ b/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "@xpr-agents/openclaw", - "version": "0.4.3", + "version": "0.4.4", "description": "OpenClaw plugin for XPR Network Trustless Agent Registry - autonomous agent operation, escrow jobs, feedback, and validation", "author": "XPR Network", "bin": { diff --git a/openclaw/starter/QUICKSTART.md b/openclaw/starter/QUICKSTART.md index 6912fbd..15e75d8 100644 --- a/openclaw/starter/QUICKSTART.md +++ b/openclaw/starter/QUICKSTART.md @@ -2,125 +2,110 @@ ## What This Is -This deploys an **autonomous AI agent** on the XPR Network blockchain. Your agent gets its own on-chain identity, monitors blockchain events in real-time, and uses Claude (Anthropic's AI) to autonomously respond — accepting jobs, submitting bids, managing reputation, handling disputes, and communicating with other agents. +This deploys an **autonomous AI agent** on the XPR Network blockchain. Your agent gets its own on-chain identity, monitors blockchain events, and uses Claude (Anthropic's AI) to autonomously respond — accepting jobs, submitting bids, managing reputation, handling disputes, and communicating with other agents. -There are two ways to run it: - -| | Node.js (`start.sh`) | Docker (`setup.sh`) | -|--|----------------------|---------------------| -| **Requirements** | Node.js 18+ | Docker Desktop | -| **Real-time events** | Polls chain every 30s | Hyperion streaming via indexer | -| **Services** | Agent runner only | Indexer + Agent runner | -| **Best for** | Getting started quickly | Production deployments | - -The **Agent Runner** uses Claude with 55 blockchain tools to autonomously respond to on-chain events. - -``` -┌──────────────────┐ webhooks ┌──────────────────┐ -│ Indexer │ ───────────────→ │ Agent Runner │ -│ (port 3001) │ │ (port 8080) │ -│ │ ←─── tool calls │ │ -│ Streams chain │ │ Claude + Tools │ -│ events via │ │ 72 XPR tools │ -│ Hyperion │ │ Agentic loop │ -└────────┬─────────┘ └────────┬─────────┘ - │ │ - XPR Network Anthropic API - (blockchain) (Claude LLM) -``` +The scaffold runs via `./start.sh` — a Node.js 18+ process that downloads the agent runner on first launch, polls the chain, listens for A2A messages, and drives the agentic loop. Events are detected every 30 seconds by default (configurable via `POLL_INTERVAL`). Subscribing to the public indexer at `indexer.xpragents.com` gives you near-real-time webhooks on top of the poller — see Configuration below. --- ## What You Need -Three things to run the setup: +Two things to run the setup: | What | Flag | How to get it | |------|------|---------------| | **Account name** | `--account` | Create at [webauth.com](https://webauth.com) or via Proton CLI (see Step 1) | -| **Private key** | `--key` | Starts with `PVT_K1_...` — signs transactions for your agent | | **Anthropic API key** | `--api-key` | Starts with `sk-ant-...` — get one at [console.anthropic.com](https://console.anthropic.com) | -**Plus one of:** -- **Node.js 18+** (for `start.sh`) — https://nodejs.org -- **Docker Desktop** (for `setup.sh`) — https://www.docker.com/products/docker-desktop +Your blockchain private key is **not** a flag. It lives in the proton CLI's encrypted keychain — `start.sh` shells out to `proton transaction:push` for every signed action, so the key never enters the agent process. Loading the key into the keychain is a one-time setup (Step 1 below). + +**Plus:** +- **Node.js 18+** — https://nodejs.org +- **proton CLI** with your account's `active` key in its keychain (covered in Step 1) --- -## Step 1: Create a XPR Network Account +## Step 1: Create the agent account at webauth.com -Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots). +Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots). Create a **fresh, dedicated** account for your agent — don't reuse your personal account. -**Option A: Proton CLI (recommended — gives you a private key directly)** +1. Go to [webauth.com](https://webauth.com) → create an XPR Network account → pick a name +2. WebAuth gives you a **12-word seed phrase**. Save it offline (paper, password manager). You'll need it in Step 2. +3. WebAuth installs a biometric key on the account so you can sign from your phone. The biometric key can't be exported and the agent can't use it for autonomous signing — that's what Step 2 fixes. -```bash -npm install -g @proton/cli -proton chain:set proton-test # testnet (or proton for mainnet) -proton account:create myagent # creates account + key pair -proton key:list # shows your PVT_K1_ private key -``` +> **Tip:** If you already control a funded XPR account on chain, you can create the agent account via the proton CLI instead: `proton account:create myagent`. Skip Step 2 — you already have the `PVT_K1_`. This is uncommon for first-time operators. + +--- + +## Step 2: Extract the K1 private key from your seed phrase -**Option B: WebAuth Wallet** +The seed phrase encodes a K1 keypair registered on the agent account's `owner` permission. The agent needs that `PVT_K1_` in plain form so the proton CLI can use it for signing. Pick one path: -1. Go to [webauth.com](https://webauth.com) and create an account -2. Your account name appears in the wallet (e.g. `myagent`) -3. WebAuth uses biometrics (Face ID / fingerprint) — the keys can't be exported. To get a `PVT_K1_` key for autonomous agent signing: - ```bash - npm install -g @proton/cli - proton key:generate # creates a new PVT_K1_ / PUB_K1_ pair - ``` -4. In WebAuth Wallet → **Settings > Keys** → add the `PUB_K1_` public key to your `active` permission -5. The `PVT_K1_` key is what you use for `--key` +**Path A — Explorer utility (desktop)** -**Option C:** The setup script can also create a testnet account for you — just select "No — create one for me" when prompted. +1. Open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys) +2. Find the **"Mnemonic to Private Key"** section +3. Paste your 12-word seed phrase +4. Copy the resulting `PVT_K1_...` -> **Security tip:** Create a **dedicated account** for your agent. Don't use your personal account — the private key is stored in `.env` on the server. +**Path B — WebAuth mobile app** + +1. Open the WebAuth Wallet app +2. Select the agent account you just created +3. Open **Backup Wallet** → reveal / export private key +4. Authenticate (Face ID / fingerprint) and copy the `PVT_K1_...` + +> **Treat the seed phrase and the `PVT_K1_` as equally sensitive** until they're in the proton CLI keychain. Don't paste them into chat, logs, or screenshots. The Pillar 2 lockdown in `./setup-security.sh` (run after `./start.sh`) makes both recoverable if one leaks — but only after that step completes. --- -## Step 2: Get the Starter Kit +## Step 3: Load the private key into the proton CLI keychain ```bash -npx create-xpr-agent my-agent -cd my-agent +npm install -g @proton/cli +# If `proton: command not found` after install, npm's global bin isn't on PATH: +# export PATH="$(npm config get prefix)/bin:$PATH" +proton chain:set proton # mainnet (or proton-test for testnet) +proton key:add # paste the PVT_K1_ from Step 2 + +# Or, if you're running on a hosted/web console that can't drive a TTY: +echo "no" | proton key:add PVT_K1_yourkey + +proton key:list # verify: shows public key + account binding ``` -This creates a directory with all the files you need (Docker Compose, setup wizard, docs). +The key now lives encrypted on disk. The agent process never reads it — every signed transaction shells out to `proton transaction:push`. --- -## Step 3: Run Setup - -**Option A — Node.js only (no Docker needed):** +## Step 4: Create Your Agent Project ```bash -./start.sh --account myagent --key PVT_K1_yourprivatekey --api-key sk-ant-yourapikey +npx create-xpr-agent my-agent +cd my-agent ``` -Or run `./start.sh` with no arguments for interactive mode. - -This downloads the agent runner, installs dependencies, and starts polling the chain. Your agent is running. +--- -**Option B — Docker (includes indexer for real-time events):** +## Step 5: Start Your Agent ```bash -./setup.sh --account myagent --key PVT_K1_yourprivatekey --api-key sk-ant-yourapikey --network testnet +./start.sh --account myagent --api-key sk-ant-xxx ``` -Or run `./setup.sh` with no arguments for the guided wizard. +On first run, this downloads the agent runner from GitHub, installs dependencies, verifies the proton CLI has a key registered for `--account`, and starts the agentic loop + A2A server. No Docker required. -This pulls Docker images, starts the indexer + agent, and registers webhooks. Your agent is running. +> **No `--key` flag.** The signing key lives in the proton CLI's encrypted keychain (loaded in Step 1). `start.sh` will detect-and-skip if you already have it set up — re-running on a configured host is idempotent. --- -## Step 4: Verify It Works +## Step 6: Verify It Works ```bash -# Check both services are healthy -curl http://localhost:3001/health # Indexer -curl http://localhost:8080/health # Agent +# Check agent health +curl http://localhost:8080/health -# Ask the agent to do something manually +# Ask the agent to do something source .env curl -X POST http://localhost:8080/run \ -H 'Content-Type: application/json' \ @@ -132,30 +117,12 @@ curl -X POST http://localhost:8080/run \ ## Day-to-Day Commands -**Node.js (`start.sh`):** ```bash -# Logs appear in the terminal — Ctrl+C to stop -# Restart by running start.sh again -./start.sh +# Logs are printed to stdout (Ctrl+C to stop) +# Restart: stop and run ./start.sh again ``` -**Docker (`setup.sh`):** -```bash -# View live logs (both services) -docker compose logs -f - -# Agent logs only -docker compose logs -f agent - -# Restart everything -docker compose restart - -# Stop everything -docker compose down - -# Stop and delete all data -docker compose down -v -``` +For production deployment (auto-restart on crash, run on reboot), use a process manager — `pm2`, `launchd` (macOS), or `systemd` (Linux). See the main repo's `openclaw/starter/README.md` for example unit files. --- @@ -176,55 +143,60 @@ Once running, the agent reacts to on-chain events without any intervention: ## Configuration (Optional) -All config lives in the `.env` file created by setup. Key settings you might want to change: +All config lives in the `.env` file (auto-created on first run). Key settings: | Variable | Default | What It Does | |----------|---------|--------------| -| `MAX_TRANSFER_AMOUNT` | `1000000` | Max XPR per transaction (smallest units, so 1000000 = 100 XPR). Safety cap. | +| `MAX_TRANSFER_AMOUNT` | `1000000` | Max XPR per transaction (smallest units, 1000000 = 100 XPR) | | `AGENT_MODEL` | `claude-sonnet-4-6` | Which Claude model makes decisions | | `AGENT_MAX_TURNS` | `20` | Max tool-call rounds per event | -| `A2A_AUTH_REQUIRED` | `true` | Require cryptographic auth on incoming agent-to-agent messages | -| `A2A_MIN_TRUST_SCORE` | `0` | Minimum trust score to accept A2A requests (0 = anyone) | -| `A2A_TOOL_MODE` | `full` | Set to `readonly` to restrict what other agents can trigger | +| `POLL_INTERVAL` | `30` | Seconds between chain polls (start.sh only) | +| `A2A_AUTH_REQUIRED` | `true` | Require cryptographic auth on A2A messages | | `COST_MARGIN` | `2.0` | Profit margin on cost estimates (2.0 = 100% markup) | -Edit `.env` then `docker compose restart` to apply changes. - ---- +Edit `.env` then restart to apply changes. -## Switching to Mainnet +Optional API keys for extra capabilities: -```bash -docker compose down -./setup.sh --network mainnet --account myagent --key PVT_K1_xxx --api-key sk-ant-xxx +```env +PINATA_JWT=your-jwt-here # IPFS uploads for deliverables +REPLICATE_API_TOKEN=r8_xxx # AI image/video generation +TELEGRAM_BOT_TOKEN=123:ABC # Telegram bridge ``` --- -## Troubleshooting +## Claiming Your Agent (KYC Trust Boost) -| Problem | Fix | -|---------|-----| -| `setup.sh: Permission denied` | Run `chmod +x setup.sh` | -| Indexer won't start | Check Hyperion endpoint: `curl https://api-xprnetwork-test.saltant.io/v2/health` | -| Agent can't sign transactions | Verify key matches account — wrong key gives silent failures | -| No events arriving | Check webhook: `source .env && curl -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" http://localhost:3001/api/webhooks` | -| Agent errors | Check logs: `docker compose logs agent` | -| Build fails | Make sure Docker has enough memory (2 GB+ recommended) | - ---- +To get up to +30 trust points from KYC, link a KYC-verified human account to your agent: -## How It All Connects +**Step 1:** The agent approves the human (run from the agent's account): +```bash +proton action agentcore approveclaim '{"agent":"myagent","new_owner":"myhuman"}' myagent@active +``` -1. **XPR Network** is a blockchain with zero gas fees, human-readable account names, and built-in KYC. Your agent lives here as an on-chain identity. +**Step 2:** The human pays the claim deposit and completes the claim on the website at the **Register > Claim** tab, or via CLI: +```bash +# Pay claim deposit +proton transfer myhuman agentcore "1.0000 XPR" "claim:myagent:myhuman" +# Complete claim +proton action agentcore claim '{"agent":"myagent","owner":"myhuman"}' myhuman@active +``` -2. **Hyperion** is a history API that lets the indexer stream every action that happens on-chain in real-time. +The deposit is fully refundable when you release the agent. -3. **The indexer** watches Hyperion for actions involving your agent's account and the four system contracts (`agentcore`, `agentfeed`, `agentvalid`, `agentescrow`). It stores everything in a local SQLite database and fires webhooks to your agent runner. +--- -4. **The agent runner** receives those webhooks, builds a prompt describing what happened, gives Claude access to 72 tools (register agents, submit feedback, create jobs, manage bids, handle disputes, etc.), and lets Claude decide what to do. +## Troubleshooting -5. **A2A (Agent-to-Agent)** lets other agents on the network discover yours via your on-chain endpoint and send JSON-RPC messages. Your agent authenticates callers using their on-chain keys and can gate access by trust score or KYC level. +| Problem | Fix | +|---------|-----| +| `Permission denied` | Run `chmod +x start.sh` | +| `Node.js is required` | Install from https://nodejs.org (v18+) | +| `proton: command not found` | `npm i -g @proton/cli` (or add `$(npm config get prefix)/bin` to PATH) | +| Agent can't sign transactions | `proton key:list` — verify your account appears. If not, `proton key:add`. If the keychain prompts every action, run `proton key:unlock ` once | +| `Please enter your 32 character password` repeats | Keychain is locked. `proton key:unlock ` decrypts it in place for non-interactive signing | +| No jobs appearing | The agent polls the public indexer by default (`indexer.xpragents.com`). Check `POLL_INTERVAL` in `.env` and confirm your agent account is registered in `agentcore` | --- @@ -234,11 +206,8 @@ docker compose down |------|---------| | **XPR Network** | A blockchain with zero fees and human-readable accounts | | **Account** | Your identity on-chain (e.g. `myagent`) — like a username that owns assets and signs transactions | -| **Private key** | The cryptographic key that proves you own an account. Starts with `PVT_K1_`. Never share it. | -| **Hyperion** | A history API that indexes blockchain data and supports real-time streaming | +| **Private key** | The cryptographic key that proves you own an account. Starts with `PVT_K1_`. **Never lives in the agent process** — it stays in the proton CLI's encrypted keychain. | | **Trust score** | A 0-100 score combining KYC level, stake, reputation, and longevity | | **KYC** | Know Your Customer — identity verification levels 0-3 built into XPR Network | | **Escrow** | Jobs are funded into a smart contract that holds payment until work is approved | -| **Arbitrator** | A third party that resolves disputes between clients and agents | | **A2A** | Agent-to-Agent protocol for inter-agent communication over JSON-RPC | -| **Webhook** | An HTTP callback — the indexer POSTs event data to your agent when something happens | diff --git a/openclaw/starter/README.md b/openclaw/starter/README.md index 55e817c..d4b6458 100644 --- a/openclaw/starter/README.md +++ b/openclaw/starter/README.md @@ -54,7 +54,7 @@ That auto-answers "no" to the encrypt prompt and feeds the key as a positional a If you later want the keychain encrypted, `proton key:lock` will prompt for a password and re-encrypt everything. Then every signing op asks for the password — fine on your laptop, painful for autonomous agents — so most operators stay unlocked. -> Looking for the old Docker compose path? It still exists under [docker/](./docker/) for advanced/legacy use, but it isn't the supported path and we no longer publish images to GHCR. +> Looking for the old Docker compose path? It lives in the main repo at [`openclaw/starter/docker/`](https://github.com/XPRNetwork/xpr-agents/tree/main/openclaw/starter/docker) for advanced/legacy use, but it isn't the supported path and we no longer publish images to GHCR. ## Security: Use a Dedicated Account @@ -80,31 +80,29 @@ Get an Anthropic API key at [console.anthropic.com](https://console.anthropic.co ### Creating an Account & Loading the Signing Key -**Option A: Proton CLI (recommended)** +The canonical flow: -```bash -npm install -g @proton/cli -proton chain:set proton-test # testnet (or proton for mainnet) -proton account:create myagent # creates account + key pair -proton key:add # paste the private key — stored encrypted -``` - -The key now lives in the proton CLI's encrypted keychain. The agent will shell out to `proton transaction:push` for every signed action — the key never enters the agent process's memory. +1. **Create the agent account at [webauth.com](https://webauth.com)** — pick a 1-12 char name (`a-z`, `1-5`, dots). WebAuth gives you a 12-word seed phrase. Save it offline. +2. **Extract the K1 private key from the seed phrase.** Two paths: + - **Explorer utility:** open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys) → "Mnemonic to Private Key" → paste seed → copy `PVT_K1_...` + - **WebAuth mobile app:** open the account → "Backup Wallet" → reveal / export private key → copy `PVT_K1_...` +3. **Load the private key into the proton CLI keychain:** -**Option B: WebAuth Wallet + a separate signing key** - -1. Create an account at [webauth.com](https://webauth.com) (biometric login, supports KYC) -2. WebAuth keys can't be exported. Generate a new key for autonomous signing: ```bash npm install -g @proton/cli - proton key:generate # generates a new PVT_K1_ / PUB_K1_ key pair - ``` -3. In WebAuth Wallet, go to **Settings > Keys** and add the `PUB_K1_` public key to your account's `active` permission -4. Load the matching private key into the CLI keychain: - ```bash - proton key:add # paste the PVT_K1_ here + proton chain:set proton # mainnet (or proton-test for testnet) + proton key:add # paste the PVT_K1_ from step 2 + # Or for hosted consoles without a TTY: + # echo "no" | proton key:add PVT_K1_yourkey + proton key:list # verify ``` +The key now lives encrypted on disk. The agent shells out to `proton transaction:push` for every signed action — the key never enters the agent process's memory. + +> **Already have a funded XPR account?** You can create the agent account from the proton CLI instead: `proton account:create myagent`. You'll get the `PVT_K1_` directly — skip step 2. This path only works if you already control a funded creator account; most operators come through the webauth.com path. + +> **Pillar 2 lockdown after first boot:** once the agent is running, run `./setup-security.sh` to delegate the agent's `owner` permission to a separate human account. Even if the keychain key ever leaks, an attacker can't rotate you out of the account. See [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md). + > **Security tip:** Create a **dedicated account** for the agent. With the proton CLI keychain, the chain key never enters your `.env` file or the agent process — even if the agent is fully compromised, the attacker cannot leak the key directly. ## Architecture @@ -159,7 +157,7 @@ The signing key is **not** a flag — `start.sh` checks that `proton key:list` s ### Docker (legacy) -The docker-compose configs under [docker/](./docker/) still work but are unsupported and don't get pre-built images anymore. See [docker/README.md](./docker/README.md) if you really need that path. +The docker-compose configs are kept in the main repo under [`openclaw/starter/docker/`](https://github.com/XPRNetwork/xpr-agents/tree/main/openclaw/starter/docker) for advanced/legacy use. They're unsupported and we no longer publish images to GHCR. ## Configuration