Skip to content

docs: lead Step 1 with WebAuth + seed-to-K1 extraction (everyone, not just CLI users)#26

Merged
paulgnz merged 1 commit into
mainfrom
fix/webauth-seed-extraction-flow
May 15, 2026
Merged

docs: lead Step 1 with WebAuth + seed-to-K1 extraction (everyone, not just CLI users)#26
paulgnz merged 1 commit into
mainfrom
fix/webauth-seed-extraction-flow

Conversation

@paulgnz
Copy link
Copy Markdown
Collaborator

@paulgnz paulgnz commented May 15, 2026

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, works for everyone. What was missing: the seed-phrase-to-PVT_K1_ extraction step between "I made an account on webauth.com" and "I run proton key:add". This PR 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:
  3. Load the key: proton key:add (interactive) or echo "no" | proton key:add PVT_K1_... (hosted consoles).

proton account:create myagent is demoted to a footnote: "if you already control a funded XPR account, this gives you the K1 directly — skip step 2."

Why this matters

A first-time operator hitting the previous Step 1 ran proton account:create and got either a prompt for a creator account they don't have, or an unhelpful EOSIO error about RAM / no sponsor. Then they bounced. 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 for the extraction step. Subsequent steps renumbered (Deploy → 4, Pillar 2 → 5, Register/build trust → 6).
  • create-xpr-agent/template/QUICKSTART.md — same 3-step structure.
  • create-xpr-agent/template/README.md — "Creating an Account" block rewritten.
  • openclaw/starter/{QUICKSTART,README}.md — synced (CI scaffold-sanity).
  • openclaw/README.md (npm landing page) — keychain setup expanded with both extraction paths.
  • docs/SECURITY.md — Flow A now names the two extraction paths explicitly.

Versions

  • @xpr-agents/openclaw0.4.4 (README content only)
  • create-xpr-agent0.6.1 (template QUICKSTART + README changes)

Verification

  • Frontend builds clean (all 13 routes prerendered)
  • 80 openclaw tests pass
  • CI scaffold-sanity (start.sh, setup-security.sh, .env.example diffs unchanged this PR)

… just CLI users)

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)
@paulgnz paulgnz merged commit 8e658c9 into main May 15, 2026
5 checks passed
@paulgnz paulgnz deleted the fix/webauth-seed-extraction-flow branch May 15, 2026 23:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant