05 · Wallets, Custody & Authorization
Identity, master-wallet authority, trading authority and wager accounting are separate concerns. Every sensitive action has an explicit principal, credential path, policy and recovery procedure.
Exact ownership and authority
| Actor/service | Owns | May do | Must not do |
|---|---|---|---|
| Privy user | Authenticated product identity/consent | Authorize master actions and direct controls | Bypass policy or impersonate another wallet |
| Privy master wallet | Account-level authority and funds | Fund, transfer, withdraw, approve/revoke agent, account modes | Enter model context |
| Hyperliquid agent wallet | Signer-specific nonce/action authority; no funds | Allowlisted registered trading actions | Sensitive master-only actions; cross-account reuse |
| Signing service | Protected signer access and audit boundary | Sign a verdict-bound request | Interpret strategy/free text or expose key material |
| Trading-tool service | Tool schema and orchestration | Read, validate, request execution and return structured results | Sign directly or skip risk |
| Risk kernel | Versioned deterministic policy | Accept/clamp/reject | Hold credentials or submit exchange actions |
| Match service | State revision, timer and effect authorization | Authorize lock/snapshot/flatten/settlement sequence | Move funds directly or use client time |
| Settlement service | Formula/decision/payout plan | Calculate and execute idempotent approved custody effects | Change wager commitments or frozen evidence |
Privy DID is identity; wallet ownership is explicit data
Verify access tokens server-side, use the Privy DID as the user identity and resolve an explicit user-to-master-wallet record. The legacy statement “JWT sub equals wallet address” is superseded. Authorization checks bind user, session, wallet, account, match and action on every boundary.
Create fresh, register, monitor, rotate, revoke
- Authenticate the user and verify the intended master wallet/account/network.
- Create a fresh agent signer in the approved protected storage system; expose only an opaque signer reference.
- Use the master authorization path to register the agent with a purpose-specific name and expiration.
- Record master, agent address, network, account scope, process owner, policy version, registration transaction and expiry.
- Operate through one nonce writer; monitor registration/funding prerequisites.
- Rotate before expiry or compromise: pause, cancel/flatten as policy requires, register a new signer, reconcile, then revoke the old signer.
- Never reuse a deregistered agent address.
Trading funds and committed wager records must be traceable
The master path owns deposits, withdrawals and account transfers. The approved VS baseline additionally uses additive-layer wager custody/accounting, but the exact transfer/escrow path, legal entity, account segregation and administrative powers are an open implementation/legal decision. No real-money deployment proceeds until those records and specialist approval exist. Self mode never creates a wager commitment.
Deployment secrets are configuration, not a per-user key database
Cloudflare Secrets protect service credentials and wrapping keys. Per-user signer material requires an explicit encrypted storage design with key wrapping, authenticated access, separation of duties, rotation, deletion and audit events. The browser, static assets, model context, replay and logs contain only signer references/addresses.
Safe lifecycle endings
Logout
Invalidate product session. State whether an active Self agent continues; default to policy-defined pause unless the user explicitly created a persistent session.
Account deletion
Stop sessions, reconcile, revoke agents, delete protected signer material, retain only legally required redacted audit records and provide withdrawal instructions.
Compromised key
Global/account pause, cancel/flatten, master revocation, fresh signer, nonce/event review, user notice and incident record.