solana-studio 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7241d6d065b9809d2860f069a5719e7e45ffe69d819b7b179556153a1e18fc8
-  data.tar.gz: 4f3463bdabd2e64fd778485856cfdf7615d5f75cb373bf025f044c24e4d1a000
+  metadata.gz: b39e73cb89b5702df9fe20f382981a4828b8b1323f2ef9080f1b001c8e8396c2
+  data.tar.gz: be1c8214f63bcf63d87c2f8b25954f36d09c61e11aad4adf51241a07a4ff8f5e
 SHA512:
-  metadata.gz: 5fb81a7cd7050a2be3d6ae91f38d3ac2e39c0907d57585cca239e86d3e1ecc2a433561df2bf43cffb1d9f1593f9d97acdad6ae48a5d811bf5d99c7e55576c501
-  data.tar.gz: e19a0a621a94498d9fabb1c2fdeb5322fd135f2f695ff8d1adb58685eeea08133566f3e2b5f33a4e2a238e3734df2cc00ec380ae65f0a284489904358e001d66
+  metadata.gz: 3178007eec399ce2356ca861d2d8ebbb48bf13d9c9ca5da4deaedf9c0a1e7fe0df80114571a08263e58fce779a8f1557b4a4cee00b9d1484c7ab933f46e2a673
+  data.tar.gz: 39d356918c3e8b0681c1447538946f178e8dc6ff8173de5c8b95d95b2b1b7725190de477fdd7e4656544d7552344c61688634f22a9b2216a0cebbafe468b3556

data/CHANGELOG.md

@@ -5,6 +5,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 ## Unreleased
 
 ### Added
+- **`SolanaStudio.walletSession` — the wallet session is written down, so a returning user signs in ONE hop** (`app/assets/javascripts/solana_studio/wallet_journal.js`, `.../wallet_ops.js`). Sessions **never expire** on Phantom, Solflare or Backpack — all three vendors state it in their own docs (verified 2026-09-07, recorded per wallet in `wallet_transport.js`'s profile table) — but nothing persisted one, so EVERY mobile signing trip paid two app switches: connect, then sign. `runRedirect` already had the warm branch and a comment claiming it was "taken once per user, not once per action"; no caller could be on it, because there was nowhere for a session to live. Declare `run(..., { owner })` and there is: the connect hop's session is stored, scoped to that user, that wallet and that cluster, and the next trip goes straight to `signTransaction`. That halves the app switches on the flow that takes money and halves the surface where a trip can break — a real user's entry was lost on QA in precisely the second hop. **A SEPARATE RECORD, IN THE SAME FILE, and both halves of that are deliberate.** The journal is single-use and expires in ten minutes BY DESIGN (`take()` clears it so a double-fired callback cannot advance a step twice); a session is the opposite, long-lived and reusable. Share one record and every completed signature would `take()` the session away with it, which is the two-hop behaviour this removes. What must be separate is the RECORD, not the file: everything about reaching `localStorage` safely — the guarded accessor, the three browser states it really presents, the quota branch, the corrupt-entry drop — is one algorithm, and a second file would be a second copy of it (see the `B58_ALPHABET` note in `wallet_transport.js` for what that costs here). Sharing the file also keeps `purge()` whole: ONE call sweeps by key prefix and clears the session with the journal, so no consumer has to learn a second call. **But it is a call the host MUST ADD, not one it already makes** — turf-monster's layout sweeps the older `phantom_dl_` prefix, which does not match this subsystem's `wallet_dl_` and so clears NEITHER record. Adopt `owner` and that call in the same change, or ship a session that never expires — and the dapp encryption secret beside it — surviving a logout on a shared device. **THE TOKEN IS OPAQUE AND STAYS OPAQUE.** It decodes to a 64-byte signature plus JSON carrying `app_url`, timestamp, chain and cluster; none of it is read. The wallet is the only authority on validity, so a local parse can only ever be a second opinion that is wrong in one of two directions — `test_a_remembered_session_is_recalled_verbatim_and_never_parsed` stores a value containing `0`, `O`, `I` and `l` (the four characters base58 omits) and asserts it round-trips, so a decode added later cannot pass. **THE OWNER IS REFUSED RATHER THAN STRINGIFIED**, which is the guard that matters most: an object would `String()` to `[object Object]` — one token every user of that browser matches — and the failure would be a stranger offered a one-hop signature with a session they never established. A string or a number is a real handle; anything else is refused at `run()` by name and again inside `remember()`. An ANONYMOUS trip is not remembered at all: a session with nobody to scope it to cannot be kept from the next person, and there is no logout event on an anonymous page for `purge()` to ride. The scope is read from the JOURNAL in preference to the callback page's `opts.owner`, and that direction is the safety property — the journal says who STARTED the trip, and stamping whoever is signed in when the wallet answers is the one read that could hand a session to someone else. **A DECLARED `expectedAccount` IS NOW HONOURED ON A WARM TRIP**, which it never was: the session records the address it was established for, so a wallet keypair change is a local MISS that falls through to a connect hop instead of two app switches and a refusal. Omit `owner` and nothing changes — same hops, and an undeclared intent's journal is byte-identical to the one it wrote before this existed, which is why `JOURNAL_VERSION` does not move.
+- **A refused session recovers through a connect hop instead of losing the entry** (`app/assets/javascripts/solana_studio/wallet_ops.js`). A stored session can be refused mid-trip, and the vendors name the causes: an explicit disconnect, a wallet keypair change, the user switching networks, an `app_url` blocklisting. The refusal lands on the SIGNING callback — by which point the user has already left for their wallet and come back, so they are committed, and failing there loses their work. So the trip takes the hop it skipped: forget the session, navigate to `connect` carrying THE SAME INTENT, and the ordinary connect callback advances it to signing on its own. One extra app switch — the two-hop cost they would have paid anyway — rather than starting over. **`prepare()` IS NOT RE-RUN**: the journalled `intent.state` is reused, because prepare MINTS things (turf-monster's mints a prepared-transaction row with a fresh blockhash) and a second one would strand the first and charge the flow twice for one user action. **RECOVERY IS BOUNDED TO ONCE BY SHAPE, NOT BY A COUNTER**: the retry intent carries its `scope` but NOT its `recovery` block, so the hop it produces has nothing to recover to and a second refusal surfaces the wallet's own words — there is no field anyone can forget to decrement. **A `4001` USER REJECTION IS NOT A REFUSED SESSION** and reaches the caller as itself; sending someone who just declined back to their wallet for another look is hostile, and their session is fine. A decryption failure is likewise out of the rule: it carries no error code, no vendor documents it as a refusal channel, and a corrupt payload should read as itself rather than as a session problem. The rule is deliberately WIDER than the four documented causes, whose codes are not pinned here — guessing narrow costs the user their entry, guessing wide costs one app switch and then reports the same error honestly, and when the two mistakes are that asymmetric you take the cheap one. Recovery also RESTORES a guard the warm path gives up: the recovered trip goes through connect, where a declared `expectedAccount` is checked, so a keypair change ends in a sentence the user can act on rather than a chain error. Covered by 20 node tests across simulated page deaths and 3 browser specs in `e2e/wallet_session.spec.js`; all 24 mutations of the new guards were confirmed to fail a named test.
 - **`walletOps.run(..., { expectedAccount })` — a declared account the trip refuses to run without** (`app/assets/javascripts/solana_studio/wallet_ops.js`). Consumers were checking the connected pubkey against the session's linked address by hand, on the inline path only, because the redirect path had nowhere to put it: `resume()` goes from `completeConnect` straight into the signing hop. Declaring the address at `run()` gives both transports the check. **IT IS UX, NOT SECURITY, and overselling it would be the more expensive mistake**: the ownership proof is on-chain — Anchor rejects any `enter_contest_direct` whose signer does not match the entry PDA's owner, with or without this. What it buys is a sentence a user can act on (`Wrong wallet — this account is linked to GkxH…kQrM, but the wallet connected as 9WzD…AWWM`) instead of a program error, and on the inline transport a server-minted prepared transaction that is never spent to discover the wrong wallet is connected. The refusal carries `err.wrongAccount`, `err.expected` and `err.connected` so a host can compose its own sentence instead of parsing the default one. **A DECLARED VALUE RATHER THAN A POST-CONNECT HOOK, which is the obvious design and the wrong one**: the connect callback is a DIFFERENT DOCUMENT — studio-engine's `solana_sessions/phantom_callback`, which knows nothing about any consumer's flows — and `resume` deliberately does not require a registered handler to advance from connect to signing (`test_the_sign_only_declaration_holds_when_the_callback_page_lacks_the_intent` pins that). A hook would therefore be looked up on exactly the hop it exists to guard, come back empty, and be SKIPPED IN SILENCE. A string in the journal cannot be skipped, because there is nothing to look up — the same argument that put `signOnly` there, and it is proven by a test that clears the registry between the run and the callback. Stamped ONLY when declared, so an undeclared intent's journal stays byte-identical and `JOURNAL_VERSION` does not move.
 - **Where the check lands differs per transport, and that asymmetry is documented rather than papered over.** Inline: after `connect()`, BEFORE `prepare()` — which is why connect now runs first (below). Redirect on a cold session: on the connect callback, before the signing hop, so `prepare` has already run and whatever it minted is spent — unavoidable, because the connect hop destroys the page and the journal is the only thing that crosses it. Redirect on a WARM session (`opts.session`): not checked at all, because no connect hop happens and walletOps never learns an account; a caller holding a session learned the address when it established one. A README table states all three.
 - **Wallet failures on both web3 modals now reach the host's error log** (`app/views/solana_studio/modals/_wallet_connect.html.erb`, `_web3_step_up.html.erb`). Each catch block already mapped the wallet's throw into a paragraph and stopped there, so every rejection on this surface died in the browser. Both now call the host's optional `window.reportWalletFailure(stage, provider, raw, mapped)` behind a `typeof` guard, with stage `wallet_connect` and `web3_step_up`. **The reporter and its endpoint stay HOST-owned, and that is a dependency call rather than a convenience**: by the two-axis test in `docs/agents/modules/modal-lifecycle.md` neither axis fires on the reporter — it needs no gem code to render and binds to no wallet/chain runtime, only `fetch` and a CSRF meta every base app already has — so it is not solana-studio-bound, and what makes it LOOK gem-shaped is subject matter, the error that module names outright (`blocks/_wallet_brand_sprite` is wallet-depicting and engine-owned for the same reason). The decisive half is that the ENDPOINT cannot move: it writes an `ErrorLog` through `rescue_and_log`, and `lib/solana_studio/engine.rb` mounts no routes by design. A gem-side reporter would therefore be half a mechanism whose other half every consumer still hand-rolls, and its failure mode would upgrade from silence to a **silent 404** on a surface that now looks wired — harder to catch than the darkness it replaced. The graduation trigger has not fired either: one app has the reporter, zero second adopters, and the module's rule is a second app that has ALREADY shipped the shape, never a forecast. What answers the rediscovery cost instead is DECLARING the contract where a consumer meets it — both partial headers and a new README section now name all six host globals, what each absence degrades, and the four-value body.

data/README.md

@@ -444,6 +444,7 @@ SolanaStudio.walletOps.define('contest_entry', {
 SolanaStudio.walletOps.run('contest_entry', { contestId: 12 }, {
   provider: walletProvider.detect(),
   expectedAccount: session.address,          // optional
+  owner: currentUser.id,                     // optional — see below
   appUrl: location.origin,                   // redirect transport only
   redirectLink: location.origin + '/auth/phantom/callback',
   cluster: document.body.dataset.solanaCluster
@@ -542,13 +543,19 @@ place the two genuinely cannot be made identical:
 |---|---|---|
 | Inline | after `connect()`, **before** `prepare()` | nothing — `prepare` never runs |
 | Redirect, cold session | on the connect callback, **before** the signing hop | whatever `prepare` already minted; no signing prompt |
+| Redirect, warm session (`owner`) | locally, **before** the trip starts | nothing — the trip falls back to a connect hop |
 | Redirect, warm session (`opts.session`) | **not checked** | — |
 
 The redirect path cannot check earlier because the connect hop destroys the
 page: everything `prepare` returns must already be in the journal before the
-navigation. A warm session takes no connect hop at all, so walletOps never learns
-an account — a caller holding a session learned the address when it established
-one, and that is where the check belongs.
+navigation.
+
+A session recalled through `owner` records the address it was established for,
+so the check happens locally and costs nothing: a mismatch is a **miss**, the
+trip takes an ordinary connect hop, and the account is checked there. A session
+handed in as `opts.session` carries no address walletOps knows about, so it stays
+unchecked — a caller holding one learned the address when it established one, and
+that is where the check belongs.
 
 It is a declared **value** rather than a post-connect hook on purpose. The
 connect callback is a different document — in this ecosystem, studio-engine's
@@ -557,6 +564,89 @@ wallet callback view, which knows nothing about any consumer's flows — and
 connect to signing. A hook would be looked up on exactly the hop it exists to
 guard, come back empty, and be skipped in silence.
 
+#### `owner` — one hop for a returning user
+
+Sessions **never expire** on Phantom, Solflare or Backpack. All three vendors say
+so in their own docs — recorded per wallet as `sessionsExpire: false`, each with
+the `sessionDocs` URL it came from, in `wallet_transport.js`'s `PROFILES` table
+(verified 2026-09-07). Nothing persisted one, so every
+mobile signing trip paid **two app switches** — connect, then sign — and the
+second one is where a real user's entry was lost on QA.
+
+Declare an `owner` and the connect hop's session is written down. The next trip
+skips straight to signing:
+
+```js
+SolanaStudio.walletOps.run('contest_entry', { contestId: 12 }, {
+  provider: walletProvider.detect(),
+  owner: currentUser.id,                     // string or number; an object is refused
+  cluster: document.body.dataset.solanaCluster,
+  // ...
+});
+```
+
+Omit it and every trip behaves exactly as it did before — same hops, same journal
+bytes, including a caller that supplies its own `opts.session`. Recovery and the
+scope stamp are written only for a session **this gem recalled**; a session you
+hand in stays yours to manage, because the gem has no record of it to forget.
+The session lives in `SolanaStudio.walletSession`
+(`solana_studio/wallet_journal.js`, a **separate record** from the journal: the
+journal is single-use and expires in ten minutes, a session is reusable and does
+not).
+
+**The token is opaque.** It decodes to a 64-byte signature plus JSON, and nothing
+in this gem reads any of it. The wallet is the only authority on whether a
+session is still good, so a local parse can only produce a second opinion that is
+wrong in one of two directions.
+
+##### What the host owes
+
+| Call | When | Why |
+|---|---|---|
+| `run(..., { owner, cluster })` | every trip | scopes the session; without it nothing is stored |
+| `resume(params, { owner, cluster })` | the callback page, for a **plain sign-in** connect | walletOps did not start that trip, so the owner can only come from here — and a sign-in session is what makes a user's *first* action one hop |
+| `walletJournal.purge()` | logout / user switch | sweeps both records. **A session outliving a logout is a stranger signing.** |
+
+> ⚠ **`purge()` is a call you must ADD, not one you already make.** It sweeps the
+> `wallet_dl_` prefix. A host carrying a `phantom_dl_`-era sweep from before this
+> gem existed — turf-monster's layout does — clears **neither** record, because
+> the prefixes do not match. Adopt `owner` and that call in the same change:
+> without it a session that *never expires*, and the dapp encryption secret
+> stored beside it, both survive a logout on a shared device.
+
+A trip started through `run` carries its own owner in the journal, so `resume`
+needs nothing for it. The stamp is read from the journal in preference to
+`opts.owner` deliberately: the journal says who *started* the trip, and stamping
+the user who happens to be signed in when the wallet answers is the one outcome
+that could hand a session to someone who never established it.
+
+##### When the wallet refuses a stored session
+
+It can, and vendor docs name the causes: an **explicit disconnect**, a **wallet
+keypair change**, the **user switching networks**, and an **`app_url`
+blocklisting**. The refusal arrives on the signing callback — by which point the
+user has already left for their wallet and come back, so failing there loses
+whatever they were doing.
+
+So the trip does not fail. walletOps forgets the session and takes the hop it
+skipped: a connect, carrying the **same intent**, which the ordinary connect
+callback picks up and advances to signing on its own. The user pays one extra app
+switch — the two-hop cost they would have paid anyway — instead of starting over.
+
+- **`prepare()` is not re-run.** The journalled intent is reused, so a
+  prepared-transaction row minted for the first attempt is the one that gets
+  signed. Re-preparing would strand the first and mint a second for one user
+  action.
+- **Recovery happens at most once**, structurally: the retry intent carries no
+  recovery block, so a second refusal surfaces the wallet's own error.
+- **A user rejection (`4001`) is not a refusal.** The session is fine, the user
+  said no, and it reaches the caller as itself.
+
+Its lifetime ends at exactly four events — a wallet refusal, a scope change
+(different user, wallet or cluster), `purge()`, or `walletSession.forget()`.
+There is **no timer**, because inventing one would contradict the vendor fact the
+feature rests on.
+
 #### `signOnly`
 
 A **co-signed** transaction cannot be broadcast by the wallet: the chain rejects

data/app/assets/javascripts/solana_studio/redirect_provider.js

@@ -134,7 +134,10 @@
         url: t.url.method(walletKey, method, {
           dappPublicKey: journal.dappPublicKey,
           nonce: sealed.nonce,
-          redirectLink: opts.redirectLink,
+          // The caller's value wins when present, but a resume has no caller —
+          // it runs on a page the wallet sent us to. The journal is the fallback
+          // that makes the second hop possible at all.
+          redirectLink: opts.redirectLink || journal.redirectLink,
           payload: sealed.payload,
           useScheme: opts.useScheme
         }),
@@ -142,6 +145,7 @@
           dappSecretKey: journal.dappSecretKey,
           dappPublicKey: journal.dappPublicKey,
           walletPublicKey: journal.walletPublicKey,
+          redirectLink: opts.redirectLink || journal.redirectLink,
           session: journal.session,
           intent: opts.intent || journal.intent || null
         })
@@ -187,9 +191,15 @@
             cluster: opts.cluster,
             useScheme: opts.useScheme
           }),
+          // redirectLink IS TRIP STATE, not call state. The hop AFTER this one
+          // runs in a different document — often reached by the wallet, not by
+          // us — and it needs the same return address. Capturing only what the
+          // next LINE uses is what lost it; the journal exists precisely for
+          // what the whole trip needs.
           journal: newJournal(walletKey, 'connect', {
             dappSecretKey: t.base58.encode(pair.secretKey),
             dappPublicKey: dappPublicKey,
+            redirectLink: opts.redirectLink,
             intent: opts.intent || null
           })
         };

data/app/assets/javascripts/solana_studio/wallet_journal.js

@@ -1,10 +1,44 @@
-// SolanaStudio.walletJournal — the only thing that survives the page's death.
+// The redirect transport's STORAGE — the only thing that survives the page's
+// death. Two records, two opposite lifetimes, one store.
+//
+//   SolanaStudio.walletJournal — ONE TRIP. Single-use, expiring.
+//   SolanaStudio.walletSession — ONE WALLET, ONE USER. Long-lived, reusable.
 //
 // A redirect destroys the document. Whatever the app needs on the other side has
 // to be written down first, and this is where. Everything else about the
 // redirect transport is pure functions over data; this file is the one place
 // that touches storage, which is why it is small and separately testable.
 //
+// WHY THE SESSION LIVES HERE AND NOT IN A FILE OF ITS OWN, since the two records
+// could hardly be more different. Everything about reaching localStorage safely
+// — the guarded accessor, the three browser states it really presents, the
+// quota branch, the corrupt-entry drop — is one algorithm, and a second file
+// would be a second copy of it. This codebase has already been bitten by exactly
+// that (see the B58_ALPHABET note in wallet_transport.js, and the "one factory,
+// not three adapters" note in redirect_provider.js). What must be separate is
+// the RECORD, not the file, and the records below share no key, no lifetime and
+// no reader.
+//
+// It also keeps `purge()` whole: ONE call clears both records, because both are
+// stored under this PREFIX. Split them and a host would have to learn a second
+// call, and the one it forgot would be the session.
+//
+// ⚠ BUT `purge()` IS NOT WIRED UP IN THIS ECOSYSTEM TODAY, and the difference
+// between "a call a host already makes" and "a call a host MUST add" is a
+// stranger signing. No consumer calls it: turf-monster's layout sweeps the
+// `phantom_dl_` prefix from the era before this gem existed, and THIS subsystem's
+// prefix is `wallet_dl_`, so that sweep clears NEITHER record. Exposure is zero
+// only because no consumer passes `owner` yet — the first one that does inherits
+// a session that never expires AND the dapp secret key beside it, both surviving
+// a logout on a shared device. Adopting `owner` means adding the purge call in
+// the same change. See the host-owes table in the README.
+//
+// THE NAME ON THE FILE IS NOW NARROWER THAN ITS CONTENTS, and that is a
+// deliberate cost, not an oversight. The path is shipped: consumers load
+// `solana_studio/wallet_journal.js` from a script tag, lib/solana_studio/engine.rb
+// precompiles it by name, and test/gemspec_test.rb pins it. Renaming a shipped
+// asset path to improve a noun breaks every consumer at once.
+//
 // WHY NOT sessionStorage. The wallet round trip leaves the browser entirely and
 // may return in a NEW TAB — iOS in particular does not guarantee the originating
 // tab is what receives a universal link. sessionStorage is per-tab and would be
@@ -29,6 +63,7 @@
 
   var PREFIX = 'wallet_dl';
   var KEY = PREFIX + '_journal';
+  var SESSION_KEY = PREFIX + '_session';
 
   // Ten minutes. Long enough for a human to read a wallet approval screen,
   // think, and approve; short enough that an abandoned trip is gone before it
@@ -48,11 +83,17 @@
     }
   }
 
-  function save(journal) {
+  // --- the shared record primitives ----------------------------------------
+  //
+  // Both records go through these. Written once because the interesting part is
+  // not the JSON, it is the failure handling around it, and two copies of that
+  // is how one of them quietly stops guarding.
+
+  function writeRecord(key, record) {
     var s = store();
-    if (!s || !journal) return false;
+    if (!s || !record) return false;
     try {
-      s.setItem(KEY, JSON.stringify(journal));
+      s.setItem(key, JSON.stringify(record));
       return true;
     } catch (e) {
       // Quota, private mode, or a disabled store. The caller is about to
@@ -62,29 +103,44 @@
     }
   }
 
-  // Read WITHOUT clearing. For a callback page that wants to inspect before
-  // committing to advancing — the resume path uses take().
-  function peek() {
+  function readRecord(key) {
     var s = store();
     if (!s) return null;
     var raw;
     try {
-      raw = s.getItem(KEY);
+      raw = s.getItem(key);
     } catch (e) {
       return null;
     }
     if (!raw) return null;
 
-    var journal;
+    var record;
     try {
-      journal = JSON.parse(raw);
+      record = JSON.parse(raw);
     } catch (e) {
       // Corrupt entry: drop it rather than leave it to fail every future read.
-      clear();
+      removeRecord(key);
       return null;
     }
+    if (!record || typeof record !== 'object') { removeRecord(key); return null; }
+    return record;
+  }
 
-    if (!journal || typeof journal !== 'object') { clear(); return null; }
+  function removeRecord(key) {
+    var s = store();
+    if (!s) return;
+    try { s.removeItem(key); } catch (e) { /* nothing to do and nothing to say */ }
+  }
+
+  function save(journal) {
+    return writeRecord(KEY, journal);
+  }
+
+  // Read WITHOUT clearing. For a callback page that wants to inspect before
+  // committing to advancing — the resume path uses take().
+  function peek() {
+    var journal = readRecord(KEY);
+    if (!journal) return null;
 
     if (typeof journal.startedAt === 'number' && (Date.now() - journal.startedAt) > MAX_AGE_MS) {
       // EXPIRED IS NOT AN ERROR, it is an answer. Clearing here means the next
@@ -105,14 +161,19 @@
   }
 
   function clear() {
-    var s = store();
-    if (!s) return;
-    try { s.removeItem(KEY); } catch (e) { /* nothing to do and nothing to say */ }
+    removeRecord(KEY);
   }
 
-  // Purge every key this subsystem owns. A host calls this on user switch: a
-  // journal belongs to the person who started it, and one that outlived a logout
-  // would offer to resume a stranger's signature.
+  // Purge every key this subsystem owns — BOTH records. A host MUST call this on
+  // logout and user switch: a journal belongs to the person who started it, and
+  // one that outlived a logout would offer to resume a stranger's signature. The
+  // wallet session is the same hazard with a much longer fuse — it never expires
+  // — and it is swept by this same call because it shares the PREFIX.
+  //
+  // MUST, not DOES. Nothing in this ecosystem calls it yet; turf-monster sweeps
+  // the older `phantom_dl_` prefix, which does not match `wallet_dl_` and so
+  // clears neither record. A consumer adopting `owner` owes this call in the same
+  // change.
   function purge() {
     var s = store();
     if (!s) return;
@@ -151,4 +212,179 @@
       }
     }
   };
+
+  // === SolanaStudio.walletSession ==========================================
+  //
+  // THE RECORD THAT MAKES A RETURNING USER ONE HOP. Every mobile signing trip
+  // costs two app switches today — connect, then sign — and the second one is
+  // paid over and over for a session that, per Phantom's, Solflare's and
+  // Backpack's own docs (verified 2026-09-07; recorded per wallet as
+  // `sessionsExpire: false` alongside a `sessionDocs` URL in wallet_transport.js's
+  // PROFILES table), NEVER EXPIRES. Nothing wrote it down, so nothing could reuse
+  // it. This is the writing down.
+  //
+  // THE OPPOSITE OF THE JOURNAL IN EVERY DIMENSION THAT MATTERS, which is why it
+  // is a separate record rather than another field on one:
+  //
+  //            journal                       session
+  //   reads    take() — clears               recall() — leaves it in place
+  //   life     10 minutes                    until invalidated (see below)
+  //   scope    one trip                      one wallet, for one user
+  //
+  // Share the record and every completed trip would take() the session away with
+  // it, which is precisely the two-hop behaviour this exists to remove.
+  //
+  // WHAT INVALIDATES IT — the complete list, and there is no timer in it:
+  //
+  //   1. The WALLET refuses it. Vendor docs name the causes: an explicit
+  //      disconnect, a wallet keypair change, the user switching networks, an
+  //      app_url blocklisting. walletOps forgets the session and recovers the
+  //      trip through a connect hop; see wallet_ops.js.
+  //   2. The SCOPE no longer matches — a different user, wallet or cluster.
+  //      That is a miss, not an error: the caller takes an ordinary connect hop.
+  //   3. purge(), which a host calls on logout or user switch.
+  //   4. forget(), for an explicit disconnect in the app's own UI.
+  //
+  // No max age, deliberately. Inventing one would contradict the vendor fact
+  // this feature rests on and would re-introduce the second hop on a schedule.
+  //
+  // THE TOKEN IS OPAQUE AND STAYS OPAQUE. It decodes to a 64-byte signature plus
+  // JSON carrying app_url, timestamp, chain and cluster — and none of that is
+  // read here, on purpose. The WALLET is the only authority on whether a session
+  // is still good; a local parse can only ever produce a second opinion that is
+  // wrong in one of two directions. Nothing below decodes, validates, or
+  // inspects `credentials.session`. It is stored as given and handed back as
+  // given.
+  //
+  // WHAT IS STORED, AND THE ONE THING WORTH SAYING OUT LOUD. The credentials
+  // block is exactly the four fields the signing hop needs, and one of them is
+  // the dapp's ephemeral secret key. redirect_provider.js explains why that is
+  // safe — a per-connect x25519 keypair that cannot sign, spend or authorise
+  // anything, whose loss costs one reconnect — and that argument is unchanged
+  // here. What DOES change is its lifetime: it now lives until an invalidation
+  // above rather than ten minutes. The blast radius is still "can decrypt this
+  // app's wallet replies on this device", and purge() on logout is what keeps it
+  // from outliving the person it belongs to.
+  //
+  // NO user private key, NO unsigned transaction bytes, NO personal data — the
+  // same rule the journal keeps, and the owner token below is the host's own
+  // opaque handle, not an email or a name.
+  var SESSION_VERSION = 1;
+
+  // A scope value, reduced to the string it will be compared as. Numbers are
+  // accepted because a host's user id usually IS one; anything else is refused
+  // by owner() below rather than stringified.
+  function scopeValue(v) {
+    return (v === null || v === undefined) ? '' : String(v);
+  }
+
+  // The owner is the whole reason a session cannot be a stranger's.
+  //
+  // REFUSED RATHER THAN STRINGIFIED, and this is the guard that matters most in
+  // the file. An object handed in here would String() to '[object Object]' —
+  // one token that EVERY user matches — and the failure would be a stranger
+  // signing with a wallet session they never established, on a shared device,
+  // discovered by nobody. A string or a number is a real handle; anything else
+  // is a bug, and an unremembered session costs one extra app switch.
+  function ownerToken(owner) {
+    var t = typeof owner;
+    if (t !== 'string' && t !== 'number') return null;
+    var s = String(owner);
+    return s === '' ? null : s;
+  }
+
+  // Persist the session for (owner, wallet, cluster). Returns whether it stuck —
+  // a caller that cannot store one simply keeps paying the connect hop, which is
+  // the behaviour it had before this record existed.
+  //
+  // ANONYMOUS IS REFUSED. A session with nobody to scope it to cannot be kept
+  // away from the next person at this browser, and there is no logout event on
+  // an anonymous page for purge() to ride. Not remembering costs one hop; the
+  // alternative costs a signature.
+  function remember(record) {
+    if (!record) return false;
+    var owner = ownerToken(record.owner);
+    if (!owner) return false;
+
+    var wallet = scopeValue(record.wallet);
+    if (!wallet) return false;
+
+    var c = record.credentials;
+    // ALL FOUR OR NONE. The signing hop re-derives the shared secret from
+    // walletPublicKey + dappSecretKey and puts `session` in the payload; a
+    // record missing any of them would be recalled, used, and fail inside the
+    // codec — a decryption error standing in for a storage bug, one page death
+    // from here.
+    if (!c || !c.session || !c.walletPublicKey || !c.dappSecretKey || !c.dappPublicKey) return false;
+
+    return writeRecord(SESSION_KEY, {
+      v: SESSION_VERSION,
+      owner: owner,
+      wallet: wallet,
+      cluster: scopeValue(record.cluster),
+      // The address this session signs as. Stored so a declared expectedAccount
+      // can be checked BEFORE the trip rather than discovered by a wallet
+      // refusal two app switches later.
+      publicKey: record.publicKey ? String(record.publicKey) : null,
+      credentials: {
+        dappSecretKey: c.dappSecretKey,
+        dappPublicKey: c.dappPublicKey,
+        walletPublicKey: c.walletPublicKey,
+        session: c.session
+      },
+      rememberedAt: Date.now()
+    });
+  }
+
+  // The session for this exact scope, or null. `scope`:
+  //   { owner, wallet, cluster, expectedAccount }  — expectedAccount optional.
+  //
+  // EXACT MATCH ON ALL THREE SCOPE FIELDS, and a miss is an ordinary answer that
+  // costs a connect hop. There is ONE stored session rather than a table keyed
+  // by scope, which is the honest model: a user who switches wallet or network
+  // has changed their mind, and evicting the old one keeps "a stranger cannot
+  // read this" a property of one stamped record instead of an invariant over a
+  // growing set.
+  function recall(scope) {
+    scope = scope || {};
+    var owner = ownerToken(scope.owner);
+    if (!owner) return null;
+
+    var record = readRecord(SESSION_KEY);
+    if (!record) return null;
+
+    // A VERSION WE DO NOT UNDERSTAND READS AS NO SESSION — note the contrast
+    // with the journal, which THROWS on the same event. The journal is a trip in
+    // flight, where carrying on would decrypt garbage and the only safe answer
+    // is to stop loudly. Nothing is in flight here, and "connect again" is a
+    // complete and correct answer, so a stale shape costs one hop and no words.
+    if (record.v !== SESSION_VERSION) { forget(); return null; }
+
+    if (record.owner !== owner) return null;
+    if (record.wallet !== scopeValue(scope.wallet)) return null;
+    if (record.cluster !== scopeValue(scope.cluster)) return null;
+
+    // The account guard, applied where it is FREE. walletOps checks a declared
+    // expectedAccount on the connect callback; a warm session takes no connect
+    // hop, so without this the check would silently not happen on exactly the
+    // trips this feature adds. A wallet keypair change would eventually be
+    // refused by the wallet anyway — this turns two app switches and a refusal
+    // into an immediate, correct connect hop.
+    if (scope.expectedAccount && String(scope.expectedAccount) !== String(record.publicKey)) return null;
+
+    if (!record.credentials || !record.credentials.session) { forget(); return null; }
+    return record;
+  }
+
+  function forget() {
+    removeRecord(SESSION_KEY);
+  }
+
+  W.SolanaStudio.walletSession = {
+    KEY: SESSION_KEY,
+    VERSION: SESSION_VERSION,
+    remember: remember,
+    recall: recall,
+    forget: forget
+  };
 })(typeof window !== 'undefined' ? window : globalThis);

data/app/assets/javascripts/solana_studio/wallet_ops.js

@@ -17,9 +17,33 @@
 //
 //   walletOps.run('contest_entry', { contestId: 12 }, {
 //     provider: ...,
-//     expectedAccount: '<the address this account is linked to>'  // optional
+//     expectedAccount: '<the address this account is linked to>',  // optional
+//     owner: currentUser.id                                        // optional
 //   });
 //
+// ONE HOP FOR A RETURNING USER — WHAT `owner` BUYS. Sessions never expire on
+// Phantom, Solflare or Backpack (all three vendors' docs, verified 2026-09-07,
+// recorded per wallet as `sessionsExpire: false` in wallet_transport.js's
+// PROFILES table, each with the doc URL it came from). Nothing persisted one, so
+// every mobile signing trip paid TWO app switches — connect, then sign — and the
+// second one is where a real user's entry was lost on QA. Declare an `owner` and
+// the connect hop's session is remembered, scoped to that user, that wallet and
+// that cluster; the next trip skips straight to signing. Omit it and every trip
+// behaves exactly as it did before, journal bytes included.
+//
+// The session lives in SolanaStudio.walletSession (wallet_journal.js), which
+// documents its own lifetime and the four things that invalidate it. One of them
+// is this file's to handle and is handled below: a wallet that refuses a stored
+// session mid-trip recovers through a connect hop rather than losing the user's
+// work (recoverThroughConnect).
+//
+// ⚠ ANOTHER IS THE HOST'S AND IS NOT WIRED UP TODAY. A logout must call
+// walletJournal.purge(), which sweeps the session with the journal — and no
+// consumer does: turf-monster sweeps the older `phantom_dl_` prefix, which does
+// not match this subsystem's `wallet_dl_`. Passing `owner` without adding that
+// call leaves a never-expiring session, and the dapp secret key beside it,
+// alive across a logout on a shared device. Adopt them together.
+//
 // `signOnly` IS A REQUIREMENT OF THE TRANSACTION, NOT A PREFERENCE ABOUT THE
 // WALLET, and it is the intent's to declare because only the intent knows the
 // shape of the bytes it prepared. A CO-SIGNED transaction — one whose second
@@ -182,6 +206,14 @@
   // from connect to signing. A hook would therefore be unreachable on exactly
   // the hop it exists to guard, and would silently not run there — the worst of
   // the three outcomes. A string survives the redirect; a function does not.
+  // A cluster reduced to the string walletSession will compare it as. Absent,
+  // null and '' all collapse to the same value on both sides, so a host that
+  // never declares a cluster still gets a consistent scope rather than a session
+  // it can store and never recall.
+  function scopeCluster(cluster) {
+    return (cluster === null || cluster === undefined) ? '' : String(cluster);
+  }
+
   function shortAddress(address) {
     var s = String(address);
     return s.length > 12 ? s.slice(0, 4) + '…' + s.slice(-4) : s;
@@ -358,7 +390,73 @@
       // Already connected? Go straight to signing. Otherwise connect first and
       // carry the intent through — sessions do not expire on any of the three
       // wallets, so this branch is taken once per user, not once per action.
+      //
+      // THAT SENTENCE WAS ONLY TRUE FOR A CALLER THAT KEPT THE SESSION ITSELF.
+      // Nothing did, so every trip paid the connect hop and the "once per user"
+      // claim described a code path nobody was on. `opts.owner` is what makes it
+      // literal: walletSession recalls the stored session for this exact
+      // (owner, wallet, cluster), and a returning user signs in ONE hop.
       var existing = opts.session || null;
+      // WHETHER *WE* RECALLED IT, which is a different question from "is there a
+      // session". A caller that hands in `opts.session` owns that session: this
+      // file did not store it, has no record of it, and must not offer to
+      // recover or forget it. Recovery is a service for the sessions walletOps
+      // itself recalled, and this flag is what keeps the two apart.
+      var recalled = false;
+      if (!existing && opts.owner) {
+        var stored = studio().walletSession.recall({
+          owner: opts.owner,
+          wallet: provider.key,
+          cluster: opts.cluster,
+          // Checked HERE, where it is free. A warm trip takes no connect hop, so
+          // this is the only place a declared expectation can be honoured before
+          // the user is committed. A mismatch is a miss, not an error — the trip
+          // falls through to the connect hop below and is checked there.
+          expectedAccount: opts.expectedAccount
+        });
+        if (stored) { existing = stored.credentials; recalled = true; }
+      }
+
+      // A TRIP THAT SKIPS THE CONNECT HOP HAS NO CONNECT HOP TO FALL BACK ON,
+      // so it writes down how to build one. The wallet can refuse a stored
+      // session mid-trip — vendor docs name an explicit disconnect, a keypair
+      // change, a network switch and an app_url blocklisting — and by then the
+      // user has already committed. The refusal arrives on the SIGNING callback,
+      // a different document that knows none of these values, so they travel in
+      // the journal for the same reason signOnly and expectedAccount do.
+      //
+      // `scope` is WHO this trip belongs to; `recovery` is HOW to rebuild the
+      // connect. They are deliberately separate records, on two different
+      // conditions:
+      //
+      //   scope    — whenever an owner is declared, warm or COLD. The cold trip
+      //              is where a session is first learned, and the connect
+      //              callback is a different document that may know no owner of
+      //              its own. Stamping it from the journal is also the SAFER
+      //              read: the session belongs to whoever started the trip, not
+      //              to whoever happens to be signed in at the browser when the
+      //              wallet answers.
+      //   recovery — only on a trip that skipped the connect hop USING A SESSION
+      //              WE RECALLED. Gated on `recalled`, not on `existing`: a
+      //              caller-supplied `opts.session` also skips the hop, but this
+      //              file has no record of it, so forgetting it would evict a
+      //              DIFFERENT scope's session and the recovery would have no
+      //              cluster to rebuild the connect with. The retry keeps scope
+      //              and drops recovery, which bounds recovery to once. See
+      //              recoverThroughConnect.
+      //
+      // Both set ONLY when the new options are used, so a caller that declares
+      // no owner writes a journal byte-identical to the one it wrote before this
+      // feature existed — INCLUDING one that supplies its own `opts.session`,
+      // which is the case the `existing` gate used to get wrong. Same rule
+      // signOnly follows, and the same reason JOURNAL_VERSION does not move.
+      if (opts.owner) {
+        intent.scope = { owner: String(opts.owner), cluster: scopeCluster(opts.cluster) };
+      }
+      if (recalled) {
+        intent.recovery = { appUrl: opts.appUrl || null, redirectLink: opts.redirectLink || null };
+      }
+
       var begun = existing
         ? beginSigning(provider, intent, existing, opts)
         : provider.beginConnect({
@@ -429,6 +527,127 @@
       : provider.beginSignTransaction(payload);
   }
 
+  // --- the persisted session -----------------------------------------------
+  //
+  // WRITTEN ON THE CONNECT CALLBACK, which is the one moment this transport
+  // holds all four credential fields AND the address they belong to. Everything
+  // after this is a lookup.
+  //
+  // The scope is read off the JOURNAL first and `opts` only as a fallback, and
+  // the order is the safety property, not a convenience. The journal says who
+  // STARTED the trip; `opts` says who is signed in at the browser when the
+  // wallet answers. Those are the same person in every ordinary case, and when
+  // they differ — a shared phone, a logout mid-trip — stamping the CURRENT user
+  // onto a wallet session someone else established is the one outcome that lets
+  // a stranger sign. Stamping the originator cannot: the next recall names a
+  // different owner and misses.
+  //
+  // A trip that declared no owner anywhere is simply not remembered. That is the
+  // behaviour every caller had before this existed, and it costs one app switch,
+  // not a signature.
+  function rememberSession(journal, connected, opts) {
+    var intent = connected.journal && connected.journal.intent;
+    var scope = (intent && intent.scope) || null;
+    var owner = (scope && scope.owner) || opts.owner || null;
+    if (!owner) return false;
+
+    return studio().walletSession.remember({
+      owner: owner,
+      wallet: journal.wallet,
+      cluster: scope ? scope.cluster : scopeCluster(opts.cluster),
+      publicKey: connected.publicKey,
+      credentials: {
+        dappSecretKey: connected.journal.dappSecretKey,
+        dappPublicKey: connected.journal.dappPublicKey,
+        walletPublicKey: connected.journal.walletPublicKey,
+        session: connected.session
+      }
+    });
+  }
+
+  // THE REFUSAL PATH, AND THE REASON THIS FEATURE IS NOT JUST A CACHE.
+  //
+  // A stored session can be refused by the wallet mid-trip — vendor docs name an
+  // explicit disconnect, a wallet keypair change, the user switching networks,
+  // and an app_url blocklisting — and it is refused at the WORST possible
+  // moment: the user has already left for their wallet app and come back, so
+  // they are committed. Failing there loses whatever they were doing, which is
+  // exactly the class of loss this epic exists to remove (a real user's entry
+  // was lost on QA in this second hop).
+  //
+  // So the trip does not fail; it takes the hop it skipped. Forget the session,
+  // navigate to connect carrying THE SAME INTENT, and the ordinary connect
+  // callback picks it up and advances to signing on its own. The user pays one
+  // extra app switch — the two-hop cost they would have paid anyway — instead of
+  // starting over.
+  //
+  // `prepare()` IS NOT RE-RUN, and that is the point of reusing the journalled
+  // intent rather than rebuilding one. prepare MINTS things — turf-monster's
+  // mints a prepared-transaction row with a fresh blockhash — so re-running it
+  // would strand the first one and charge the flow twice for one user action.
+  // `intent.state` came back from the original prepare and is signed unchanged.
+  //
+  // ONCE, STRUCTURALLY. The retry intent carries `scope` but NOT `recovery`, so
+  // the hop it produces cannot recover again; a second refusal surfaces the
+  // wallet's own words. That is a shape, not a counter — there is no field to
+  // forget to decrement.
+  //
+  // AND IT RESTORES A GUARD THE WARM PATH GIVES UP. A session-skipping trip
+  // never learns which account connected, so a declared expectedAccount goes
+  // unchecked on it. The recovered trip goes through connect, where it IS
+  // checked — so the recovery from a keypair change ends in a sentence the user
+  // can act on rather than a chain error.
+  function recoverThroughConnect(provider, journal, opts, navigate) {
+    var intent = journal.intent;
+    var recovery = intent && intent.recovery;
+    // No recovery block means this trip already had a connect hop, or ran on a
+    // session this file never stored. There is nothing better to do than report
+    // what the wallet said.
+    if (!recovery) return null;
+
+    // A recovery block is only ever written beside a scope (both come from the
+    // same recall), so this is unreachable from a journal THIS release wrote.
+    // It is checked anyway because the alternative is silent and expensive: the
+    // cluster below would be null, `query()` drops a null, and the wallet would
+    // default the recovered connect to MAINNET-BETA — real funds on a trip that
+    // began on devnet. A journal from an older release is exactly the way that
+    // becomes reachable.
+    if (!intent.scope) return null;
+
+    // The redirect link is what the wallet returns to. Since #44, url.connect
+    // REFUSES to build without one, and that throw would escape this function
+    // and reach the user INSTEAD of the wallet's own error — a worse report
+    // about a different subject. Answer null and let the wallet speak.
+    var redirectLink = opts.redirectLink || recovery.redirectLink;
+    if (!redirectLink) return null;
+
+    // Only now, once the retry is certain to be buildable. Forgetting before
+    // this point would drop the session on a trip that then reports the wallet's
+    // error anyway, costing the user a stored session for nothing.
+    studio().walletSession.forget();
+
+    var again = { op: intent.op, ctx: intent.ctx, state: intent.state };
+    if (intent.signOnly) again.signOnly = true;
+    if (intent.expectedAccount) again.expectedAccount = intent.expectedAccount;
+    again.scope = intent.scope;
+
+    var begun = provider.beginConnect({
+      appUrl: recovery.appUrl,
+      redirectLink: redirectLink,
+      // THE CLUSTER THE TRIP BEGAN ON, never null. See the scope guard above.
+      cluster: intent.scope.cluster,
+      intent: again
+    });
+
+    // A store that cannot record the retry cannot complete it either. Returning
+    // null hands the caller back to the wallet's own error, which is a truer
+    // report than "could not record" for a user whose browser just refused a
+    // write.
+    if (!studio().walletJournal.save(begun.journal)) return null;
+    navigate(begun.url);
+    return { pending: true, suspended: true, recovered: true, url: begun.url };
+  }
+
   // Called by the callback page. Reads the pending journal, advances one step,
   // and either navigates again or hands back the finished result.
   //
@@ -458,6 +677,12 @@
         // next hop, which is what makes a transaction on a cold session two
         // navigations rather than two user-initiated attempts.
         if (!intent) {
+          // A PLAIN SIGN-IN IS THE MOST VALUABLE SESSION THERE IS, because it is
+          // the one every user establishes before they ever ask to sign
+          // anything. Remembering it here is what makes a returning user's FIRST
+          // action one hop rather than their second. The host owns this connect
+          // (walletOps did not start it), so the owner can only come from opts.
+          rememberSession(journal, connected, opts);
           return Promise.resolve({ pending: true, done: true, connect: connected });
         }
 
@@ -474,6 +699,12 @@
         // it established one, and that is where it belongs.
         assertExpectedAccount(intent.expectedAccount, connected.publicKey);
 
+        // AFTER the account guard, never before. A wrong wallet must not evict
+        // the session belonging to the right one — and a session stored for an
+        // account the caller has already refused is a record that can only ever
+        // be recalled into the same refusal.
+        rememberSession(journal, connected, opts);
+
         var next = signingHop(provider, connected.journal, {
           redirectLink: opts.redirectLink || journal.redirectLink
         });
@@ -492,9 +723,37 @@
         var handler = requireHandler(journal.intent && journal.intent.op);
 
         var wallet = journal.step === 'signAndSendTransaction';
-        var out = wallet
-          ? provider.completeSignAndSendTransaction(params, journal)
-          : provider.completeSignTransaction(params, journal);
+        var out;
+        try {
+          out = wallet
+            ? provider.completeSignAndSendTransaction(params, journal)
+            : provider.completeSignTransaction(params, journal);
+        } catch (walletError) {
+          // WHICH FAILURES RECOVER, stated as one rule: an error the WALLET
+          // reported, that is not the user saying no.
+          //
+          // `code` is set only by throwIfWalletError, so its presence IS "the
+          // wallet answered with an error redirect" — the channel every
+          // documented refusal cause arrives on. `rejected` (4001) is carved out
+          // because a user who declined has a perfectly good session and being
+          // sent back to their wallet for another look is hostile.
+          //
+          // Deliberately WIDER than the four documented causes. Their codes are
+          // not pinned here, and guessing a narrow list wrong costs the user
+          // their entry — the exact failure this feature removes — while
+          // guessing wide costs one app switch and then surfaces the same error
+          // honestly, because the retry cannot recover again. When the two
+          // mistakes are that asymmetric, take the cheap one.
+          //
+          // DECRYPTION FAILURES ARE NOT IN THIS RULE, and that is on purpose:
+          // they carry no `code`, they are not a refusal channel any vendor
+          // documents, and a corrupt payload is a different finding that should
+          // read as itself rather than as a session problem.
+          if (!walletError.code || walletError.rejected) throw walletError;
+          var recovered = recoverThroughConnect(provider, journal, opts, navigate);
+          if (recovered) return Promise.resolve(recovered);
+          throw walletError;
+        }
         return Promise.resolve(handler.complete(journal.intent.ctx, {
           signature: out.signature || null,
           signedTransaction: out.transaction || null,
@@ -556,6 +815,22 @@
           typeof opts.expectedAccount + ' — call .toString() on a PublicKey first'
         ));
       }
+      // REFUSED RATHER THAN STRINGIFIED, and for a sharper reason than
+      // expectedAccount's. An object here would String() to '[object Object]' —
+      // ONE owner token that every user of this browser matches — and the
+      // symptom would be a stranger offered a one-hop signature with a wallet
+      // session they never established. walletSession.remember() refuses the
+      // same value on its own, so nothing can actually be stored under it; this
+      // check exists so the bug is named at the call site that wrote it rather
+      // than showing up as a feature that quietly never works.
+      if (opts.owner !== undefined && opts.owner !== null &&
+          typeof opts.owner !== 'string' && typeof opts.owner !== 'number') {
+        return Promise.reject(new Error(
+          'walletOps.run owner must be a string or number identifying the ' +
+          'signed-in user, got ' + typeof opts.owner + ' — an object would ' +
+          'stringify to one token every user shares'
+        ));
+      }
       return opts.provider.transport === 'redirect'
         ? runRedirect(name, ctx, opts)
         : runInline(name, ctx, opts);

data/app/assets/javascripts/solana_studio/wallet_transport.js

@@ -114,6 +114,15 @@
       // different from its own provider methods.
       browsePath: '/ul/browse/',
       clusters: ['mainnet-beta', 'testnet', 'devnet'],
+      // SESSIONS DO NOT EXPIRE. Phantom's "Handling Sessions" page states it
+      // outright: a session token stays valid until the user disconnects, the
+      // wallet's keypair changes, the user switches networks, or the app_url is
+      // blocklisted — there is no TTL. This is the fact SolanaStudio.walletSession
+      // is built on, so it is recorded HERE, as data, next to every other
+      // per-wallet fact, rather than asserted in a comment somewhere downstream.
+      // Verified 2026-09-07.
+      sessionsExpire: false,
+      sessionDocs: 'https://docs.phantom.com/phantom-deeplinks/handling-sessions',
       // DEPRECATED BY PHANTOM: "The signAndSendTransaction deeplink is
       // deprecated. Use signAllTransactions or signTransaction instead." So on
       // Phantom the APP still broadcasts — sendRawTransaction + a confirmation
@@ -136,6 +145,10 @@
       connectKeys: ['solflare_encryption_public_key'],
       browsePath: '/ul/v1/browse/',
       clusters: ['mainnet-beta', 'testnet', 'devnet'],
+      // Same as Phantom, which is expected — Solflare forked the spec and its
+      // docs link Phantom's own blocklist repo. Verified 2026-09-07.
+      sessionsExpire: false,
+      sessionDocs: 'https://docs.solflare.com/solflare/technical/deeplinks/provider-methods/connect',
       send: 'wallet-broadcasts',
       methods: {
         connect: true, disconnect: true, signMessage: true,
@@ -164,6 +177,13 @@
       // devnet cannot currently QA this wallet, which is a lane decision, not a
       // bug to paper over here. supportsCluster() reports it honestly.
       clusters: ['mainnet-beta'],
+      // Same as the other two. Backpack's session handling is the forked
+      // Phantom spec, and nothing in its corpus documents a TTL.
+      // Verified 2026-09-07 — and see the connectKeys note above: this vendor's
+      // docs are the least settled of the three, so this is the entry to
+      // re-confirm first if a session ever comes back refused for no reason.
+      sessionsExpire: false,
+      sessionDocs: 'https://docs.backpack.app/backpack-deeplinks/provider-methods/connect',
       send: 'wallet-broadcasts',
       methods: {
         connect: true, disconnect: true, signMessage: true,
@@ -292,11 +312,39 @@
     return parts.join('&');
   }
 
+  // A REQUEST WITH NOWHERE TO RETURN IS NOT A REQUEST, and until this existed it
+  // was possible to build one and impossible to notice. query() below SKIPS
+  // null/undefined/empty values, so a missing redirect_link simply vanished from
+  // the URL and the request looked perfectly well formed on the way out. Phantom
+  // received it, had nothing to do with it, and opened to its HOME SCREEN — which
+  // is indistinguishable, to a user, from the app being broken.
+  //
+  // Measured on a real iPhone against QA 2026-09-09: hop one (connect) completed
+  // correctly and hop two was built with redirect_link undefined, because the
+  // journal never carried it across the page death. The entry was lost after the
+  // user had already approved it.
+  //
+  // Guarding at the BUILDER rather than at each call site is the point. There are
+  // three places that construct these URLs today and more will follow; a rule
+  // enforced where the string is assembled cannot be forgotten by the next one.
+  function requireField(value, name, method) {
+    if (value === null || value === undefined || value === '') {
+      throw new Error(
+        'Cannot build a ' + method + ' wallet request without ' + name +
+        ' — the wallet would have nowhere to return to. This usually means the ' +
+        'value was not carried across the redirect in the journal.'
+      );
+    }
+    return value;
+  }
+
   var url = {
     // connect carries NO nonce and NO payload — the shared secret does not exist
     // yet. Every other method requires both.
     connect: function (wallet, opts) {
       var b = base(wallet, opts && opts.useScheme);
+      requireField(opts && opts.redirectLink, 'redirect_link', 'connect');
+      requireField(opts && opts.dappPublicKey, 'dapp_encryption_public_key', 'connect');
       return b.prefix + 'connect?' + query({
         app_url: opts.appUrl,
         dapp_encryption_public_key: opts.dappPublicKey,
@@ -310,6 +358,10 @@
         throw new Error(wallet + ' does not support ' + method + ' over the redirect transport');
       }
       var b = base(wallet, opts && opts.useScheme);
+      requireField(opts && opts.redirectLink, 'redirect_link', method);
+      requireField(opts && opts.dappPublicKey, 'dapp_encryption_public_key', method);
+      requireField(opts && opts.payload, 'payload', method);
+      requireField(opts && opts.nonce, 'nonce', method);
       return b.prefix + method + '?' + query({
         dapp_encryption_public_key: opts.dappPublicKey,
         nonce: opts.nonce,

data/lib/solana_studio/version.rb

@@ -16,5 +16,5 @@ module SolanaStudio
   # through the normal cycle. Splitting the version out is the same shape
   # studio-engine already uses (lib/studio/version.rb) and hands each file back
   # to its real owner: this one to the release, the gemspec to the PR.
-  VERSION = "0.9.2"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519