Repository navigation
Description
Direction (Anders, 12 Nov): get WalletConnect running and part of onboarding ("passkey and/or walletconnect"). Owner: Main's side (Codex and Cursor writers); Ahmed reviews chain specifics.
- Phase 1: the connector works end to end on the Home (relay path, sessions, config, lifecycle). First-run shows equal choices, passkey or wallet, as reversible screens (Anders, 12 Nov).
- Phase 2: wallet signup and sign-in ship once Sign-in and recovery: one identity across devices and Homes (design question) #574 settles the conditions there (encrypted data, offline, stolen wallet, first-run consent) with @irzhywau's review.
Where Reown's SDK runs (Anders, 12 Nov): option A. WalletConnect is a connector capsule that acts as a signer for the Wallet, like the passkey; the same capsule is the candidate for signup and sign-in, decided in #574. The SDK (2.16 MB, 317 locked packages) runs only in the connector's sandboxed frame, never in the Home page. It reaches only its own app-scoped Runtime routes with its launch token, and the Runtime writes, binds and verifies every message to be signed. Limit: isolation protects Home, not the phone; a compromised SDK could still send a bad request to the phone wallet, whose own confirmation is the last guard. Deferred: the WalletConnect internet consent copies Browser's (inbox.js), and the bundle's QR renderer duplicates the Runtime's wallet_qr_svg.
Goal. In the desktop app: open Wallet, choose Connect a wallet, then WalletConnect, scan the QR code with a phone wallet, and approve there. The phone wallet holds the keys and signs; ElastOS never sees them. This replaces the MetaMask browser extension, which a desktop app does not have. Sash asked for it with the desktop app (11 Nov), and Anders discussed it with Codex on 10 Nov.
Where it stands (v2.0.1).
- The connector capsule
wallet-walletconnectexists (WALLET_PROVIDER.md).- It can request an account, have the wallet sign a Runtime challenge, and carry transaction requests.
wallet-providerkeeps the proofs, linked accounts, approvals and receipts.
- It stays hidden and unlaunchable until the Home has two things: a Reown project ID, and a locally pinned, hash-checked Reown/AppKit adapter (
scripts/vendor-walletconnect-adapter.sh,scripts/configure-walletconnect-connector.mjs). Neither ships, and no default project ID may be committed. 2.0.x hides it from Marketplace for that reason. - Essentials and ELA signing are meant to build on this connector.
What is required
-
Network and session boundary. Capsules may only talk to Home today, but WalletConnect needs its relay. Agree on a narrow, reviewed way for the connector to reach the relay and keep its session through the Runtime, without loosening other capsules' isolation. This comes first.
-
Configuration for the official release. An operator-owned Reown project, and the reviewed adapter installed automatically, so a person only presses Connect. Independent operators pin their own.
-
The adapter's supply chain. Lock its whole dependency graph, and ship the reviewed bundle inside the verified release.
-
The connection lifecycle. Connected and disconnected states; disconnect as a separate action from removing a linked account; account and network changes; expired sessions; restart and reconnect; prompt cancellation.
-
Binding every request to the person, the requesting capsule, the account, the chain, the exact payload and its expiry. Pairing alone grants no capsule the right to sign.
-
A small first scope:
- one phone wallet;
- one EVM network;
- a harmless ownership signature, then one authorized transaction on a test network.
ELA mainchain, Bitcoin and Essentials follow separately.
Done means
- On the desktop app (Mac first, then Windows and Linux): pair, sign the ownership challenge, reject a request, refuse a wrong account, survive expiry and reconnect, disconnect, and complete one test-network transaction without a duplicate send.
- A person never handles a project ID or a setup script.
- Review by a different model family, plus @irzhywau for the network and session boundary.
- 2.0.2 scope (Anders, 16 Nov): the same holds for the three connector windows (WalletConnect, MetaMask or Brave Wallet, UniSat) and Wallet's connect section. Every state in the design's state list is reached through its real producer in the built Home, every control shown is pressed and works, and a state the build cannot make true is removed only with Anders's word.
- One request with one identity goes Inbox, Wallet, its connector window, the outside wallet and back to a shown result, for a message on each connector and for a transaction on WalletConnect and MetaMask, with no control that fails on the way. (UniSat signs messages only today; a Bitcoin transaction through UniSat would be new authority and is not in this scope.)
- The situations that are common or block a person each have a designed, built and tested outcome: a locked wallet, the wrong account, a prompt already open, a declined or late answer, a browser that cannot run the extension, a connection that ran out, an error from the wallet, access removed in the wallet, a request that cannot be sent.
- Integrated journeys pass on an installed Home with a scripted phone wallet over the real relay and with the real MetaMask and UniSat extensions at least once; a WebKit and desktop-app run; an update from 2.0.1 with a linked account, then Undo; then Anders's own trial.
Related: #521 (desktop app account access), Elacity/elastos-agent-host-spike#1386 (the desktop app), #565 (how a connector launch request is presented).
Network path (Anders's idea, 11 Nov, checked by an independent review). A team-hosted ElastOS node lends internet access over Carrier to anyone who connects a wallet. The design:
-
Each person's own Home runs the WalletConnect client and keeps the pairing and session keys. WalletConnect is end-to-end encrypted between that client and the phone wallet (spec).
-
The hosted node is only a network Exit. It forwards encrypted traffic to Reown's relay hosts and nowhere else, using the existing remote Exit model (
docs/BROWSER_CAPSULE.md:170-174). It never runs other people's sessions. If it did, it would see every account and request, and could push fake signing requests. -
Default: the person's own internet through a Runtime-mediated local Exit. Consent (Anders, 13 Nov): after sign-in, "Connect a wallet" asks once in Inbox with the passkey, and Turn Off sits in the same Inbox entry, as for Browser (Browser uses this computer's internet only after the owner grants it, as a revocable capability #559). At first run, before any account exists, the tap on "Use a wallet" is the setup-only consent (Sign-in and recovery: one identity across devices and Homes (design question) #574). The hosted Exit is optional, for networks that block the relay, and its operator still learns who connects, when, and how much traffic flows.
-
Must be proven, not assumed:
- the remote Exit code is Browser-specific today; a long-lived
wssrelay connection needs admission, heartbeat and idle handling; - authenticated TLS through the Exit;
- quotas, revocation and reconnect.
Reown allowlists by project and origin, not by IP, so shared egress should not break it, but throttling limits are undocumented.
- the remote Exit code is Browser-specific today; a long-lived
-
@irzhywau reviews this boundary.
Reown project ID (12 Nov): created by Anders for Elacity ("ElastOS Home"). It is kept outside the repository, on the operator's Mac, and supplied to test Homes through ELASTOS_WALLETCONNECT_PROJECT_FILE. The release secret REOWN_PROJECT_ID is set when the connector branch merges. Reown permits localhost origins regardless of the allowlist, so the ID is not a secret.
Scope for 2.0.2: the whole wallet connection work (Anders, 16 Nov 2026)
Anders: "we have to include walletconnect"; "the connection overhaul needs to be a part of 2.0.2"; on the design "no repeating ... simple and responsive", ""phone wallet" doesnt make sense ... we follow walletconnect best practice", "the inbox/grant/notification system must be standardized"; "desing looks good. do 3 more passes ... and build it"; "we need to make sure to provide a stable and smooth user experience"; asked whether to split it into a later release: "lets get this all done under 2.0.2 properly. first principles. elastos alignment. end to end testing and hypithetical simulations from user point of view". No date is set.
What it covers. The three connector windows and Wallet's connect section in one design (one heading per window, one status line, one main action that fits the state, one account card, requests shown once), and the changes outside the windows without which a shown control would fail or a sentence would be false:
- N1 Home navigation and Wallet: exact routes from a connector window to the request in Wallet, to Wallet's activity, from an extension window to WalletConnect, and from a connector window back to the app that asked (the target is read from the Runtime's request record, never Home, a shell or the sender); the request's identity carried through the launch.
- N2 Home's side of the MetaMask and UniSat connectors: which wallet will be used, whether this browser can run it, a locked wallet, the selected account, one deadline per wait, the account and network checked before a request is consumed, stop and late answers, error kinds passed on and never raw extension text.
- N3 Runtime, Inbox and Wallet: a request on an outside wallet's account gets the existing review action in Inbox; today Inbox offers Approve and the Runtime refuses it. Wallet's request view opens the right connector.
- N4 Runtime and Wallet: the wallet's name and a bundled mark stored at linking, with a fallback.
- N5 Runtime and Inbox: the WalletConnect internet access entry keeps Allow after a refusal, turning off or running out.
- N6 WalletConnect window: outcomes by kind (declined, unsupported network, the wallet ended the connection, no answer in time), the request kept visible when the connection ended, and separate handling of a message and a transaction whose answer did not arrive. Inside the connector's existing authority; no new Runtime route.
- N7 Runtime, Inbox and Wallet: the request card names the site that asks. The Browser already records it when it creates a wallet request; the summary shown to the person left it out. Display text only, bounded, never an input to a decision (added 17 Nov after the walk of imagined people: "the person deciding cannot see who is asking").
How Home presents requests in general is Home presents every approval request the same way (Inbox keeps the record) #565 and does not change in 2.0.2; the internet access step follows the Browser's present pattern, with the differences the design's comparison lists.
Principles it holds to (PRINCIPLES.md sections 3, 5, 7, 11, 12, 14, 16, 19). Authority stays where it is: the Runtime decides, Wallet's provider owns accounts and requests, Inbox is where a permission is decided, a connector window can only ask. The narrow additions are exactly these and each gets an adversarial review: N2's closed kinds and outcome codes on Home's page; N1's navigation rows; N3's Inbox action (the Runtime's refusal stays); N4's stored name from untrusted wallet metadata, bounded and cleaned; N5's kept Allow entry; the Clipboard purpose for "Copy link". A state is built only when the code can be in it, a control only when it works.
Order.
- No product code: the design covers every situation the build promises and every journey across Inbox, Wallet and the windows; the contracts are written as edits to
docs/HOME_SHELL_HOST_CONTRACT.md(N2, N1) anddocs/WALLET_PROVIDER.md(N3, N4, N5); the real MetaMask and UniSat extensions are run once and their replies recorded. - Two enabling commits: the shared view, and a scripted extension that replays the recorded replies.
- In parallel on disjoint files: the Runtime, Inbox, Wallet and navigation lane (owns
capsules/wallet/**,capsules/inbox/**,home-shell-host.js, all Rust) and Home's extension lane (ownshome-wallet-connector-host.js). - The windows: MetaMask and UniSat with the shared view; WalletConnect on the round 19 logic.
- One integration branch on this pull request's branch with develop merged. It enters the release once, whole, at one named SHA.
Tests. Each lane: tests through the real modules for every state it makes real, failing before the change. Integrated: the journeys in Done means, each also started from what a failed attempt leaves behind (a saved unfinished connection, a pending Inbox entry, a handed-off request, a busy host, a reopened window, a reloaded Home tab). A test imports the design's state list, reaches each state through its producer and presses every control. Simulations of a person's journey on the design before code, judged against Apple's guidance on permission requests, Nielsen's heuristics and WCAG 2.2 AA, and again on the built Home.
Desktop app (Anders, 17 Nov 2026). His question: "also consider dekstop app and interactions with wallet signers in all this. perhaps only support walletconnect? how to handle that seemlessly?" Decided: in the desktop app (Elacity/elastos-agent-host-spike#1386) WalletConnect is the way to connect a wallet. Browser extensions cannot run in the app's window, so Home shows only WalletConnect there, once the app tells Home that extensions cannot run; that one fact is a new narrow input and gets a security review. In a browser all three choices stay. Nothing changes in 2.0.2.
- Not announced as working in the app until the WalletConnect journey has passed inside the app on macOS, Windows and Linux with a scripted and a real wallet: allowing internet access, the passkey confirmation, signing, reconnecting after the connection ran out, and the app closed while a request waits.
- Known limits in the app until designed: no Bitcoin wallet (UniSat is an extension; WalletConnect here covers Ethereum-type networks only), and an account linked through the MetaMask extension cannot sign there, because an approval is tied to the connector it was linked through. "One account, several ways to sign" is a separate design with Sign-in and recovery: one identity across devices and Homes (design question) #574; no release is promised for it.
- Not chosen: WalletConnect as the only way everywhere (Bitcoin, the extension connectors already shipped in 2.0.1, dependence on internet access and one relay), and hiding MetaMask and UniSat in a browser where Home does not find them (Home cannot tell why a wallet is absent).
Open, and whose. @irzhywau: the N2 and N1 contracts before code (including the route back to the asking app and what the silent check may return), the network and session boundary above, and whether Home says anything when a phone wallet shows it as unverified; waiting for him or waiving is Anders's decision. Anders: whether a guest account may link an extension wallet; his trial at the end.
Acceptance record
- Candidate: public PR #597 remains draft at
4cd5a7302ac4b8ec3441c05fe886c8e5b115bba8. Round 18 is prepared locally at6f7c1d9f0c9366c567107aa0a70e96c1232d8433, treee9866480afce8b7bfc8e158bbe75b1fb76df0af6, in six new commits. Publication remains with Main; the task branch is 62 ahead / 0 behind its fetched remote and 171 ahead / 7 behind fetched develop. - Exercised checks: local serial narrow batch 188/188 PASS, with all 186 unchanged names retained and two Allow labels replaced by stronger Home-return assertions; product-data 110/110 PASS; syntax, both format checks, connector-launch smoke and diff-check PASS. Exact-head Linux slot 3 format, all-target server Clippy and WalletConnect library tests PASS (438 s). The final return/launch run passes 20/20: Home return refreshes guidance before the idle interval, including an older off-state read held across Allow. A/B use the real window/client/pinned SDK and replay the installed stale 500 body; one Connect after Allow produces a QR in the same frame. The stale real-route test fails before with three 500 responses and passes after with 409. Main owns the excluded broad release-batch checks; three annotated operator real-relay/worker tests stay ignored under the narrow Linux command.
- Review links and SHA: current local independent development and adversarial source reviews PASS on
6f7c1d9f0; the adversarial review covers the separate Rust status-classification commit. Current published review links remain a gate after Main publishes this head. Earlier posted reviews keep their original scope. The active-instruction finding is fixed with a fail-before/pass-after test; retained non-blocking review notes remain with Main. - Installed release evidence: the retained installed
f6b2562fdHome reproduced refusal/Turn Off followed by Allow failing in the old window. Its four connector browser files matched the pinned source. The fixed candidate's QR captures use real modules with fixture APIs and relay. Fresh installed acceptance remains: Main repeats the walk from a new build, then Anders's phone trial through a test-network transaction. The retained harness is stopped and its data is kept. - Remaining gate: Main integrates current develop, publishes this local candidate through the release-batch checks, obtains published current-head development/adversarial reviews and Irzhy's network/session review, and completes fresh installed and human phone acceptance. The Done means checklist stays open.
- Next owner: Main.
Activity
andersalm commentedon Nov 16, 2026
Root gives a bounded source PASS for the 2.0.2 stage-2 candidate
8f58fe87fcbabb418294766887abddae7059342a(tree38ce08b7af4867396bafe5bea3849fa9f1b82df5) across the three conflict resolutions and nine integration commits. Inbox keeps update notices separate from wallet requests and retains each action route; update notices keep their original origin-free shape. System focuses Cancel when the passkey removal dialog opens. Nine syntax checks and candidate whitespace pass.Root verified the completed full Linux receipt against the exact commit, tree and develop base
f6d819571. The gate, server and capsule steps exited 0. Main ran the checks. The merge-only compile break and the earlier extra behaviour run's wallet timing failure remain recorded; the passing receipt belongs to the repaired head.Main's source Home can support a trial. The new connector windows, real wallet and relay journeys, linked-account update and Undo, and installed and human acceptance remain open. Earlier consent recovery and stale-revision regression results retain their original scope.