docs(research): explore VFS wallet views for issue 114

[0xdewy]

Visual prototype

Start with the showcase index. It links six Bloom-branded, responsive HTML examples: Portfolio, Next Moves, Receive, Send, Activity, and Permissions & Security.

These are static, script-free fixture views for discussion; they do not add runtime VFS handlers. To see them rendered, check out the branch and open docs/research/vfs-view-mockups/index.html locally.

Research for #114.

What this PR proposes

Six concrete, Bloom-generated VFS views. Each view exposes one typed snapshot as JSON
for agents, Markdown for every chat client, and optional self-contained HTML for richer
clients. Agents read and explain these files; they do not populate them.

1. Portfolio — “What do I own and where?”

/wallets/<wallet>/portfolio.{json,md,html}

One snapshot combines:

• native and discovered ERC-20 balances across configured EVM chains;
• Hyperliquid equity, spot balances, and leveraged positions; and
• Polymarket cash, bets, value, PnL, redeemability, and deadlines.

It reports a conservative priced_net_value_usd, unpriced items, freshness, and
per-provider coverage. It never implies token discovery is complete or double-counts
position notional as wealth.

2. Next Moves — “What needs my attention?”

/next.{json,md,html}
/wallets/<wallet>/next.{json,md,html}

A small priority inbox with two lanes:

• Needs attention: pending approvals, stuck transactions, blocked workflows,
  margin risk, stale monitoring, or failed cleanup.
• Available now: verified follow-ups such as redeeming a resolved Polymarket
  position.

Every item includes evidence and a supported next path. This is not an airdrop finder,
trading recommender, generic gas nagger, or authorization mechanism.

3. Receive — “Where can someone safely send funds?”

/wallets/<wallet>/receive.{json,md,html}

Receive presents verified, chain-qualified destinations rather than one ambiguous
address:

• one owner-account route per configured chain; and
• a Polymarket deposit route only when persisted onboarding state proves it is
  fundable.

Each route shows network, purpose, full address, accepted-asset constraints,
provenance, and readiness. QR codes remain secondary to visible network and address
details. Hyperliquid Bridge2 is excluded as a generic Receive route in V0: direct credit follows the sending account, so it is a funding workflow, not Alice's receive address. A future permit-based on-behalf flow would need its own sender-bound review.

4. Send + AddressBook — “Who am I paying, and what will be signed?”

/wallets/<wallet>/send.{json,md,html}
/wallets/<wallet>/chains/<chain>/outbox/pending/<id>/review.{json,md,html}
/addressbook/...

Send adds recipient context and exact transaction review without creating a second
execution path:

• chain-qualified saved contacts and ENS resolution, showing both name and full
  address;
• simulation and standard transfer/approval decoding over the exact staged
  transaction;
• outgoing-history-derived recipients; and
• an optional Save contact? suggestion after the second verified successful direct
  send—never automatic and never derived from incoming dust.

The review remains inside the existing outbox, policy, and Sealed Approval flow. The
passkey approval commits to both the exact EVM signing hash and the canonical
interpretation shown to the user. Bloom-verified effects may affect policy and contact
suggestions; Petal-provided labels remain claims. Petals can initially add declarative,
exact-context transaction descriptors, while executable decoders remain a later escape
hatch.

This work also identifies a current bug to fix first: AddressBook writes update a
separate in-memory copy from Send, simulation, and DeFi, so a newly saved contact may
not work until restart.

5. Activity — “What happened?”

/wallets/<wallet>/activity.{json,md,html}
/wallets/<wallet>/activity/events/<event_id>.json

Activity is an outcome-first wallet timeline, not a transaction explorer or raw audit
log:

• In progress pins actions awaiting approval, submission, inclusion, or finality.
• Timeline groups settled outcomes by day and shows the semantic result, signed
  asset effects, fees, venue or chain, status, and time.
• Details retain full addresses, hashes, blocks, orders, source evidence, trust
  labels, and conflicts.

One user action becomes one card. Exact action, workflow, transaction, order, and trade
IDs deduplicate local outbox state with EVM indexers, Hyperliquid fills, and Polymarket
settlement. Approval-plus-swap, partial fills, replacements, failures, and reorgs remain
one honest lifecycle rather than several misleading successes. Bloom never guesses
grouping from nearby timestamps.

Incoming history is treated as attacker-controlled: unsolicited assets can be
collapsed in the human view but remain in JSON evidence, and incoming senders never
become copy targets or contact suggestions.

6. Permissions & Security — “Who can act, and how is my key protected?”

/wallets/<wallet>/permissions.{json,md,html}
/wallets/<wallet>/permissions/entries/<permission_id>.json
/wallets/<wallet>/permissions/recovery.{json,md,html}

Permissions is an authority and key-custody inventory, not a security score:

• Account control: owner signer, EIP-7702 delegation, Hyperliquid multisig, and
  Polymarket deposit-wallet controller.
• Spending and trading access: ERC-20/NFT/Permit2 approvals, Bloom standing
  sessions, Hyperliquid API wallets, and builder fees.
• Service access: credentials with their exact non-signing powers.
• Safeguards and recovery: wallet/passkey/policy state, factual backup status,
  encrypted portable backup, and guarded raw-key reveal.
• Coverage: exact chains, block anchors, providers, ranges, errors, and blind spots.

Every permission has separate enforcing-system and Bloom-executor states. This makes
“Bloom stopped locally, but the venue still authorizes the agent” visible instead of
mislabeling it revoked. Findings are deterministic; the page never says “Secure” or
turns incomplete discovery into “no permissions.”

Recovery never places key material in VFS, IPC, logs, command output, or the static
HTML. The recommended export is a standard encrypted Ethereum keystore created through
a fresh trusted passkey/passphrase ceremony. Raw-key reveal is an advanced escape hatch
because that copy can bypass Bloom's passkey, policy, and Sealed Approval protections.
Rebind is correctly described as changing the authenticator around the same owner key,
not backup or key rotation.

This research identifies several current gaps: the capability rollup omits durable EVM
owner-signing sessions; Hyperliquid stop is local-only; Bloom lacks a general approval
inventory; and the current one-time recovery display cannot safely become an on-demand
agent-triggered export without a new ceremony boundary.

Shared implementation pattern

• One typed, versioned snapshot feeds all three formats, with a shared snapshot ID and
  timestamp.
• Independent providers run concurrently and report ok, partial, or unavailable
  instead of making the whole view fail.
• HTML is read-only, script-free, escaped, responsive to 320 CSS pixels, and makes no
  network requests. Trusted signing/recovery ceremonies remain separate foreground
  surfaces.
• Interactive actions continue through existing canonical writable paths, policy,
  Sealed Approval, and terminal-state verification; views never create a parallel
  execution path.
• Prices and chain-status pages can reuse this pattern later but are not researched in
  this PR.

Decisions requested

• Which of the six views should be implemented first? The recommendation remains
  Portfolio.
• Are JSON + Markdown + HTML the right minimum formats across Codex, Claude, OpenCode,
  and other hosts?
• Is the second verified outgoing transfer the right threshold for suggesting a
  contact?
• Should declarative Petal transaction descriptors ship with the first Send iteration
  or immediately after native standard decoding?
• Should Activity V0 stop at the latest roughly 50 semantic events, with keyset-
  paginated history following later?
• For recovery, should encrypted Web3 Secret Storage become the default creation-time
  backup while raw-key reveal moves behind an advanced warning?

Scope and validation

Documentation only: six research notes plus seven HTML mockups and one shared stylesheet, with no handlers or runtime contracts. The
recommendations were traced against the current VFS, transaction engine, Sealed
Approval, Petal ABI, local/central action lifecycles, passkey/key-custody implementation,
EVM history and authority standards, and Hyperliquid and Polymarket APIs.

Checklist

• Tests added or updated for behavior changes — N/A, documentation-only research
• Architecture docs (docs/architecture/) updated if contracts or behavior changed
  — N/A, no contracts or behavior changed
• Sealed Approval invariants respected — the Send, Activity, and Permissions
  recommendations retain canonical staged bytes and trusted ceremony boundaries
• Agent Documentation updated (crates/bloom-vfs/src/docs/agent-guidance.md and
  affected Petal READMEs) — N/A, no runtime surface changed