feat: migrate shield-swap-sdk to the new shield_swap.aleo stack

.agents/voice.md

@@ -55,6 +55,41 @@ Why it fails: filler ("easily", "powerfully", "seamless"); restates types; says
 "a result" instead of what you get and what you do with it; no side-effect or
 error information.
 
+### Phrasings to avoid
+
+Beyond the filler above, these are banned outright. Each one reads like guidance
+while leaving the caller with nothing to act on — replace it with the concrete
+instruction, or delete it.
+
+- **"reach for"** — never use it. Say what to call and when.
+- **"defensively"**, **"as appropriate"**, **"where necessary"** — name the
+  actual condition instead.
+
+```python
+# Bad — sounds like advice, gives none
+"""… either may be ``None``, so reach for them defensively."""
+
+# Good — states the check and what it protects
+"""… treat both as optional — guard with ``if entry.token0_info`` before
+reading a field rather than assuming a default."""
+```
+
+### Plain verbs
+
+Say what the code does, not what it is like. A service or object does not
+"speak", "know", "want", or "see" — it returns, accepts, requires, stores,
+decrypts. Figurative verbs read as style and cost the reader a translation step.
+
+```python
+# Bad — figurative
+"""The API speaks decimal amounts; the contract speaks base units."""
+"""Every pool the indexer knows."""
+
+# Good — plain
+"""The API returns decimal amounts; the contract takes base units."""
+"""Every pool the DEX lists."""
+```
+
 ## Naming in prose and examples
 
 - Use the Pythonic surface: properties (`key.address`, not `key.address()`),
@@ -71,4 +106,5 @@ error information.
 This is a privacy chain. Do not document or add affordances that link
 signatures to signer addresses (no `recover`-style verb). When a feature shares
 secret material with a service (e.g. delegated record scanning shares the view
-key), state that tradeoff plainly and point to the self-hosted alternative.
+key), state that tradeoff plainly. Where an alternative exists, name the
+supported extension point (e.g. assigning a custom ``RecordProvider``).

.claude/skills/shield-swap/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: shield-swap
-description: Use when the user wants to trade, LP, or build on the shield_swap AMM — setting up an account, redeeming an invite, getting the airdrop, swapping privately, managing liquidity positions, or collecting winnings via the aleo_shield_swap Python SDK.
+description: Use when the user wants to trade, LP, or build on the shield_swap AMM — setting up an account, optionally crediting a referral code, getting the airdrop, swapping privately, managing liquidity positions, or collecting winnings via the aleo_shield_swap Python SDK.
 ---
 
 Read `shield-swap-sdk/AGENTS.md` (generated from the SDK — always current)
 and follow its Tier 1 lifecycle and conversation pattern. Write Python
-against the SDK; don't re-implement flows the verbs already provide, and
+against the SDK; don't re-implement flows the methods already provide, and
 don't read SDK source unless AGENTS.md genuinely lacks the answer.
 Preconditions are enforced in code — on error, read the exception message;
-it names the verb that fixes it.
+it names the method that fixes it.

AGENTS.md

@@ -1,6 +1,6 @@
 # Aleo Python SDK — Agent Guide
 
-Python SDK for Aleo: PyO3 bindings over **snarkvm v4.8.1** plus pure-Python
+Python SDK for Aleo: PyO3 bindings over **snarkvm v4.9.1** plus pure-Python
 client / record-scanner / delegated-proving layers and a Web3.py-style facade.
 Two shipped packages:
 
@@ -61,15 +61,22 @@ addopts if you invoke pytest from the repo root.
 
 ## Delegated services (DPS + record scanner)
 
-**Auth, proving, and scanning are all Provable *services* on `api.provable.com`,
-hosted at the API ORIGIN — NOT under the read node's `/v2/{network}` base.** The
-read/RPC endpoints live at `https://api.provable.com/v2/{network}/…`; the
-services hang off the bare origin (`https://api.provable.com`) at their own path
-prefixes. Each is confirmed working against live testnet (see
-`tests/e2e/test_testnet_e2e.py`):
+**Proving and scanning are Provable *services* hung off the hosted API's
+SERVICE ROOT — NOT under the read node's `/v2/{network}` base.** Two hosts:
 
-- **JWT auth** — origin, no prefix: `POST {origin}/jwts/{consumerId}`. Derive the
-  origin with `jwt_origin(base_url)` (`scheme://host`, path stripped).
+- **`https://edge.provable.com/api` (the default, `DEFAULT_HOST`)** — open: no
+  API key, consumer id, or JWT for reads, `/prove`, or `/scanner`. Note the
+  `/api` path prefix: reads are `{root}/v2/{network}/…`, services `{root}/prove`,
+  `{root}/scanner`. Derive the root with `service_root(url)` (keeps the prefix;
+  strips a legacy `/v2[/{network}]` suffix) — NOT `jwt_origin`, which drops it.
+- **`https://api.provable.com` (`LEGACY_HOST`)** — credentialed: the same
+  layout at the bare origin, with the prover and scanner behind
+  `api_key` + `consumer_id` JWTs. `requires_credentials(url)` is True only here;
+  everything below about JWTs applies only to this host.
+
+Each is confirmed working against live testnet (see `tests/e2e/`):
+
+- **JWT auth (legacy host only)** — `POST {root}/jwts/{consumerId}`.
 - **Delegated proving** — `{origin}/prove/{network}` prefix:
   - `GET {origin}/prove/{network}/pubkey` — ephemeral X25519 key + key id + a
     `Set-Cookie` **affinity** session. The ephemeral private key lives only on
@@ -81,8 +88,8 @@ prefixes. Each is confirmed working against live testnet (see
   - `POST {origin}/prove/{network}/prove/authorization` (or `/prove/request`) —
     sealed-box `{key_id, ciphertext}`; JWT + the affinity cookie; SDK retries
     500/503.
-- **Record scanner** — `{origin}/scanner/{network}` prefix (env
-  `RECORD_SCANNER_URL=https://api.provable.com/scanner`).
+- **Record scanner** — `{root}/scanner/{network}` prefix (env
+  `RECORD_SCANNER_URL=https://edge.provable.com/api/scanner`).
 
 Documented endpoints (docs describe paths *relative to the service base*; the
 base is the origin + service prefix above):

README.md

@@ -7,14 +7,14 @@ The SDK ships two layers:
 - A **Web3.py-style facade** (`aleo.Aleo` / `aleo.AsyncAleo`) — a high-level, batteries-included client for connecting to a node, managing accounts, reading state, and building/proving/broadcasting transactions.
 - **Low-level primitives** (`aleo.mainnet`, `aleo.testnet`) — direct Python bindings to Aleo's zero-knowledge cryptographic types, for when you need full control.
 
-Built with snarkvm 4.8.1 (MainnetV0). For build instructions, see [sdk/Readme.md](./sdk/Readme.md).
+Built with snarkvm 4.9.1 (MainnetV0). For build instructions, see [sdk/Readme.md](./sdk/Readme.md).
 
 ## Agent skills (trade on Shield Swap by chatting)
 
 The [`shield-swap-sdk`](./shield-swap-sdk) package ships everything an AI
-agent needs to drive the shield_swap AMM — set up an account, redeem an
-invite code, get the airdrop, make private swaps, manage liquidity, and
-collect earnings — from a single generated guide.
+agent needs to drive the shield_swap AMM — set up an account, get the
+airdrop, make private swaps, manage liquidity, and collect earnings — from
+a single generated guide.
 
 **Any agent (Claude Code, Codex, Cursor, custom):**
 
@@ -27,9 +27,10 @@ Most coding agents (Codex, Cursor, Claude Code, …) automatically read a
 repo-root `AGENTS.md`, so after that one command just chat: *"set up a
 shield-swap account and get tokens"*, *"find pools and start swapping"*.
 (Equivalently, open with "run `python -m aleo_shield_swap` and follow that
-guide", or paste the output into the agent's instructions.) The one thing
-the agent will ask you for is an invite code; everything else — key
-material, API credentials, airdrop — is handled by the SDK. Bring an existing account by exporting
+guide", or paste the output into the agent's instructions.) The agent needs
+nothing from you to get started — key material, API credentials, and the
+airdrop are all handled by the SDK; a friend's referral code is optional.
+Bring an existing account by exporting
 `SHIELD_SWAP_PRIVATE_KEY` (or `SHIELD_SWAP_PRIVATE_KEY_FILE`) before the
 first run — never paste a private key into the chat.
 
@@ -54,7 +55,7 @@ python -m aleo_shield_swap.mcp      # stdio server with the lifecycle tools
 from aleo import Aleo
 
 # Connect (construction is offline — no I/O until you make a call)
-aleo = Aleo(Aleo.HTTPProvider("https://api.provable.com/v2"))
+aleo = Aleo(Aleo.HTTPProvider("https://edge.provable.com/api"))
 print(aleo.network_name)   # "mainnet"
 print(aleo.network_id)     # 0
 
@@ -78,7 +79,7 @@ The facade follows a clean top-to-bottom narrative: **connect → account → re
 ```python
 from aleo import Aleo
 
-aleo = Aleo(Aleo.HTTPProvider("https://api.provable.com/v2"))
+aleo = Aleo(Aleo.HTTPProvider("https://edge.provable.com/api"))
 
 # Optional: check reachability  # requires a live node
 if aleo.is_connected():
@@ -203,7 +204,7 @@ credits.functions.transfer_private(record, str(recipient.address), 1) \
     .delegate(account)
 ```
 
-`aleo.record_provider` is swappable: set it to your own object implementing the `RecordProvider` protocol (`get_unspent_credits_record` / `find`) — e.g. a self-hosted scanner — and the whole facade (including private-fee auto-sourcing) uses it, with no view-key sharing.
+`aleo.record_provider` is swappable: set it to your own object implementing the `RecordProvider` protocol (`get_unspent_credits_record` / `find`), and the whole facade (including private-fee auto-sourcing) uses it, with no view-key sharing.
 
 ## Async (`AsyncAleo`)
 
@@ -214,7 +215,7 @@ import asyncio
 from aleo import AsyncAleo
 
 async def main():
-    aleo = AsyncAleo(AsyncAleo.HTTPProvider("https://api.provable.com/v2"))
+    aleo = AsyncAleo(AsyncAleo.HTTPProvider("https://edge.provable.com/api"))
     print(aleo.network_name)   # sync — no I/O
 
     # Account ops are sync (purely local), even on AsyncAleo