solana-studio 0.10.0 → 0.12.0

data/README.md

@@ -39,7 +39,10 @@ signature = kp.sign("hello".b)
 client = Solana::Client.new(rpc_url: "https://api.devnet.solana.com")
 
 client.get_balance("9Fy8P3DvKBh3awt...")
-client.get_latest_blockhash
+client.get_latest_blockhash                      # hash only, "finalized"
+client.latest_blockhash                          # hash + last_valid_block_height, "confirmed"
+client.get_block_height                          # compare against last_valid_block_height
+client.send_transaction(wire_b64, preflight_commitment: "confirmed")  # match the fetch
 client.request_airdrop("9Fy8P3DvKBh3awt...", 1_000_000_000)
 client.send_and_confirm(signed_tx_base64)
 ```
@@ -106,6 +109,108 @@ genesis is minted per boot) or an unrecognized cluster name. Treating it as
 `:mismatched` refuses to boot every local validator; treating it as `:aligned`
 trusts a chain nobody checked.
 
+### Gasless cosigned transactions (`Solana::Cosign`)
+
+The pattern every app with a house wallet needs: **the user's wallet signs, the
+house pays the fee**, so users never hold SOL. The server builds the transaction
+with its fee payer in account 0 and an empty slot for each cosigner, the wallet
+signs, and the server proves the returned wire is still what it built before it
+adds its own signature.
+
+The gem holds no keys and knows no program. The caller passes the fee payer's
+`Solana::Keypair` in and supplies its own instructions.
+
+```ruby
+client  = Solana::Client.new
+builder = Solana::Cosign::Builder.new(client: client, fee_payer: house_keypair)
+
+prepared = builder.build(
+  instructions: [my_program_instruction],   # { program_id:, accounts:, data: }
+  cosigners: [user_wallet_address],
+  compute_unit_price: 50_000,               # a priority fee; fee-less txs drop on mainnet
+  compute_unit_limit: 200_000
+)
+prepared.wire_base64              # hand this to the wallet
+prepared.wire_base58              # or this: what a walletOps `prepare` returns
+prepared.last_valid_block_height  # the deadline: past this height it can never land
+```
+
+Store `prepared.wire_base64` and `prepared.last_valid_block_height` server-side
+when the signature comes back in a later request, then:
+
+```ruby
+expectation = Solana::Cosign::Expectation.from_wire(stored_wire, fee_payer: house_keypair,
+                                                    last_valid_block_height: stored_height)
+completer = Solana::Cosign::Completer.new(client: client, fee_payer: house_keypair)
+
+result = completer.complete(signed_wire_from_wallet, expectation: expectation,
+                            before_send: ->(signature) { record.update!(signature: signature) })
+result.signature
+```
+
+A wire from `SolanaStudio.walletOps` arrives in base58: pass `encoding: :base58`
+to `#verify!`, `#cosign`, `#complete` or `Expectation.from_wire`. The encoding is
+declared, never guessed — every base58 string is also made of base64 characters.
+
+`#complete` runs, in order: judge the wire, check every cosigner signature, fill
+the fee payer's slot (`Transaction.cosign_wire`), check the block height against
+the deadline, simulate, call `before_send`, send, confirm. `#cosign` stops after
+the fee payer signs (no RPC), for a flow whose browser broadcasts. `#verify!`
+only judges.
+
+**How the wire is judged.** A wallet re-encodes what it signs, and on mainnet
+Phantom may insert Lighthouse instructions, so bytes are never compared. The
+fee payer must be account 0 and writable; the signer set must be exactly the
+fee payer plus the cosigners; with ComputeBudget and admitted extra programs
+(Lighthouse by default) set aside, the instructions must equal the built ones —
+program, ordered accounts, data and order; ComputeBudget is read and the fee it
+makes the house pay is capped at 10x the builder's own. A System transfer from
+the fee payer, a nonce advance, an extra signer, an altered amount: each is
+refused before the house signs.
+
+**Lighthouse is read, not waved through.** Most Lighthouse instructions are
+assertions, which can only make a transaction fail. Two are not. MemoryWrite
+(variant 0) makes a signer fund a "memory" account of any size, and the fee
+payer signs every cosigned wire, so a wire naming it as payer would lock the
+house's SOL. MemoryClose (variant 1) refunds one. The guard therefore admits a
+Lighthouse instruction only when its first data byte is an assertion variant,
+2 through 17. It refuses 0 (`lighthouse_memory_write`), 1
+(`lighthouse_memory_close`), empty data (`lighthouse_empty_data`) and any other
+byte (`lighthouse_unknown_disc`). It does not refuse an assertion for naming
+the fee payer, because Phantom's assertions check the fee payer's own state.
+The deployed program is immutable, so the variants cannot drift; the mainnet
+evidence is in the `Solana::Cosign::LIGHTHOUSE_PROGRAM_ID` comment.
+`extra_programs:` accepts only programs the guard has such a rule for, which
+today is Lighthouse alone; pass `extra_programs: []` to refuse Lighthouse
+entirely.
+
+**The error class tells you what you may do next.**
+
+| Raised | Sent? | What to do |
+|---|---|---|
+| `WireRejected` | No | Refuse. `#reason` is a stable code; the message is for logs only. |
+| `PreflightRejected` → `BlockhashExpired`, `SimulationFailed` | Provably not | Rebuild freely. `BlockhashExpired` means ask the user to sign again. |
+| `BroadcastFailed` → `BroadcastExpired` | Maybe | Look `#signature` up on chain before rebuilding. |
+| `TransactionFailed` | Landed, failed | The fee was paid. `#err` has the program error. |
+
+`BroadcastExpired` is deliberately NOT a `PreflightRejected`: `Solana::Client`
+retries a lost answer by re-posting the same wire, so a send-time "Blockhash not
+found" can follow an attempt that was already forwarded.
+
+**Build and send at the same commitment.** The builder fetches at `"confirmed"`
+by default and the completer preflights at the commitment the expectation
+carries. A confirmed blockhash sent with the RPC's default `"finalized"`
+preflight is refused as `Blockhash not found` while still valid.
+
+**Wallet-first by default.** Every slot starts empty and the house signs last.
+`presign: true` signs the fee payer's slot at build instead — the order Phantom
+can flag as "could be malicious" — and exists only so server-first flows can
+adopt the builder before they flip.
+
+No durable nonce: a nonce transaction is recognized only when
+`advanceNonceAccount` is instruction 0, and Phantom inserts instructions ahead of
+it, so a nonce cannot anchor a wallet-signed transaction.
+
 ## Rails engine (optional)
 
 The gem is Rails-free by default — `railties` is **not** a runtime dependency,
@@ -664,9 +769,116 @@ the RPC. The redirect leg also needs a host callback page to call
 `walletOps.resume(params, { navigate })`; studio-engine's
 `solana_sessions/phantom_callback` does this from 0.73.0.
 
+### The wallet as a session identity (`walletIdentity`)
+
+`solana_studio/wallet_identity.js` makes the connected wallet an **identity
+source** for studio-engine's session-drift primitive (`window.StudioSession`,
+documented in studio-engine's `docs/SESSION_DRIFT.md`). The engine compares the
+identities a page was rendered for with the identities the browser observes now,
+and it stays web2: it never learns what a wallet is. This file supplies that
+half, and nothing else in the gem depends on it.
+
+Load it after `studio/session.js`, then register once per window. Registering
+the same name twice throws, and on a Turbo host the session store and its
+registrations outlive a visit, so a script that runs on every visit must register
+only the first time:
+
+```erb
+<%= javascript_include_tag "studio/session" %>
+<%= javascript_include_tag "solana_studio/wallet_identity" %>
+```
+
+```js
+var wallet = SolanaStudio.walletIdentity.register({
+  getProvider: hostResolver,                    // your registry's pick, or omit for window.phantom.solana
+  trustedConnect: sessionHasAWallet,            // see the options table
+  rescanOn: ["wallet-provider:registered"]      // your registry's "a wallet arrived" event, if it has one
+});
+
+wallet.source.current();                        // { status, address, providerName }
+wallet.source.subscribe(function (next, previous) { /* repaint the navbar */ });
+document.addEventListener("session:mismatch", function (event) {
+  if (event.detail.source === "wallet") { /* an undeclared switch */ }
+});
+```
+
+`register` returns `{ source, registration }`. Without a `StudioSession` on the
+page, `registration` is null and the source still runs, so a page can render
+wallet state without the session primitive.
+`SolanaStudio.walletIdentity.create(options)` returns the bare source for a host
+that registers it itself.
+
+#### What it reports
+
+| `status` | Reported to the session | Meaning |
+|----------|-------------------------|---------|
+| `unknown` | `undefined` (cannot tell) | Provider discovery or a silent connect is still pending |
+| `none` | `null` | No wallet provider appeared before the discovery window closed |
+| `disconnected` | `null` | A provider is present and holds no account for this site |
+| `connected` | the base58 address | This wallet is connected |
+
+`unknown` and `none` never collapse: a page that cannot tell yet must not render
+as "you have no wallet". The session sees only the middle column.
+
+**A mismatch is a different connected address, and nothing else.** A disconnect,
+a locked extension, or a page with no wallet is not a switch to someone else, so
+the source's `equals` treats an observed `null` as agreeing with the bound
+address. The page still sees the disconnect through `current()`. Pass
+`disconnectIsMismatch: true` to count it.
+
+#### How it reads the wallet
+
+- **Two provider shapes.** An injected provider (Phantom's
+  `window.phantom.solana`, or a host adapter normalized to it): live
+  `publicKey`, plus `accountChanged`, `connect` and `disconnect`. A raw Wallet
+  Standard wallet: live `accounts` and `standard:events` `change`.
+- **Live, never cached.** Every read goes back to the wallet. On a Wallet
+  Standard `change` it reads `wallet.accounts`, not the event's copy, because
+  an adapter that cached its account once reported the previous account forever
+  after a switch the wallet never announced.
+- **Events are best-effort.** `focus`, `visibilitychange` to visible and
+  `pageshow` re-resolve the provider and re-read it. That catches a switch made
+  while the tab was hidden.
+- **One binding per provider object**, however often the page reconciles. A
+  provider replaced by a later one (a Wallet Standard registration superseding
+  the injected object) is detached, and its events are ignored.
+
+#### Options
+
+| Option | Default | |
+|--------|---------|---|
+| `getProvider` | `window.phantom.solana \|\| window.solana` | The provider to watch now, or null. Called on every reconcile. |
+| `trustedConnect` | `false` | When the wallet holds no account, ask it silently (`onlyIfTrusted` / `{ silent: true }`) before believing `disconnected`. **Off by default** because a silent connect can pop Phantom's unlock prompt; turn it on only where a wallet session is already expected. |
+| `discoveryMs`, `discoveryIntervalMs` | `3000`, `100` | How long "no provider yet" stays `unknown` while a late injection is polled for. `0` reads `none` at once. |
+| `rescanOn` | `[]` | Extra `window` events that re-resolve the provider. |
+| `name` | `"wallet"` | The identity source name, and the key the server binds under. |
+| `bound` | engine default | Passed through to the engine: `bound(snapshot)` returns the bound identity. |
+| `disconnectIsMismatch` | `false` | See above. |
+| `session` | `window.StudioSession` | The store `register` uses. |
+
+#### What the host owes
+
+- **The server half.** Bind the session under the same name:
+  `studio_session_identities` returns `{ wallet: <the wallet this session signed
+  in with> }`. Bind nothing for a session that has no wallet of its own (a guest,
+  or a managed wallet the browser never holds). An unbound source still reports
+  what it sees and never mismatches.
+- **Holds are per SOURCE, not per address.** `StudioSession.expectChange("wallet")`
+  marks every switch expected until it is released. A flow that walks through
+  specific wallets, such as a multi-signer ceremony, must still check the observed
+  address against the wallets it declared, or a switch to any other wallet goes
+  quiet for the length of the hold.
+- **The UI and the re-auth.** The switch card, the navbar, and signing in again
+  with the new wallet (then `StudioSession.refresh()`) are the host's.
+
+It never signs, sends, writes storage or opens a modal.
+
 ## Dependencies
 
-- `ed25519` (~> 1.3) — Ed25519 signing
+- `ed25519` (~> 1.3) — Ed25519 signing and the verification equation. It
+  does not vet the public key, so every verify in this gem
+  (`AuthVerifier.verify!`, `WireMessage#signature_valid?`) runs
+  `Solana::Ed25519Strict` first.
 - Ruby stdlib only (net/http, json, digest, securerandom)
 - **No Rails dependency.** `railties` is a development dependency only; the
   engine loads solely when the host has already loaded Rails.
@@ -675,32 +887,33 @@ the RPC. The redirect leg also needs a host callback page to call
 
 See [RUNBOOK.md](./RUNBOOK.md) for troubleshooting and local test commands.
 
-### 🧊 The durable-nonce primitives have two consumers, and one of them is on ice
+### The durable-nonce primitives: one consumer left, and it is a dead route
 
 `Solana::SystemProgram` and `Solana::NonceAccount` landed together in **v0.4.6
-(2026-06-02, `11ec512`)** for **two** consumers at once, and the commit says so:
-*"the reusable core for the signing console's two-browser flow and for making
-turf's operator tx flows expiry-immune."*
-
-**The first of those went on ice on 2026-08-31.** McRitchie Studio's admin
-signing console — N wallets signing in separate browsers, anchored on a durable
-nonce so a half-signed transaction does not expire between signers — is **frozen
-in place: still working, not removed, not deprecated**, and not expected to drive
-any further work in this gem. Its full note (why it was frozen, and the one
-question that would revive it) lives in the hub, at `docs/SIGNING_CONSOLE_V2.md`.
-
-**Do not read that as permission to drop these two files.** The second consumer
-is the one in production:
-
-| Primitive | Live use |
-|---|---|
-| `Solana::SystemProgram.advance_nonce_account` | turf-monster prepends it as **instruction #0** of a durable-nonce vault cosign transaction (`app/services/solana/vault.rb`). Its cosign validator also **allow-lists exactly this one System instruction** — a nonce-anchored entry with any other System instruction is rejected. |
-| `Solana::NonceAccount.parse` | turf-monster reads the on-chain nonce account in the same path. |
-
-So the frozen consumer is the *quieter* one, never the only one. Both primitives
-are byte-match tested in `test/system_program_test.rb`, and a change to either
-still lands on turf-monster's money path — treat them as `onchain`, not as dead
-code left over from a shelved tool.
+(2026-06-02, `11ec512`)** for two consumers: McRitchie Studio's signing console
+and turf-monster's operator transactions. **Neither is a live flow now.**
+Re-measured 2026-09-16 against turf-monster `origin/accepted` (`61185cdd`); this
+note used to say otherwise.
+
+- **The signing console is gone.** It was frozen on 2026-08-31 and deleted on
+  2026-09-04 (the hub's `retire-signing-console` task), with its doc.
+- **turf-monster reaches the nonce from one dead route.**
+  `Solana::Vault#durable_nonce_config` has one caller,
+  `#build_create_contest(admin_signs: true)`, reached only from
+  `ContestsController#prepare_onchain_contest`. Nothing under `app/views` or
+  `app/javascript` calls that route; only `e2e/rpc-mock.js` names it.
+- **No cosign guard admits a nonce advance.** turf-monster's cosign guards
+  refuse every System instruction, `advanceNonceAccount` included, and so does
+  `Solana::Cosign`.
+- **A nonce cannot anchor a wallet-signed transaction.** A nonce transaction is
+  recognized only when `advanceNonceAccount` is instruction 0, and Phantom
+  inserts Lighthouse instructions ahead of it (turf-monster mainnet incident,
+  2026-06-11). That is why Mr. McRitchie dropped nonce support from the
+  primitives extraction on 2026-09-16.
+
+The files stay, byte-match tested in `test/system_program_test.rb`, until
+turf-monster decides the dead route's fate. Removing them first would break that
+route's build step.
 
 ### The browser lane