RubyGems - solana-studio - Versions diffs - 0.4.6 → 0.5.0 - Mend

solana-studio 0.4.6 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +46 -0
data/README.md +145 -2
data/app/assets/javascripts/solana_studio/network_guard.js +299 -0
data/app/views/solana_studio/modals/_network_mismatch.html.erb +83 -0
data/lib/solana/client.rb +16 -0
data/lib/solana/network.rb +179 -0
data/lib/solana/transaction.rb +125 -0
data/lib/solana_studio/engine.rb +36 -0
data/lib/solana_studio/version.rb +20 -0
data/lib/solana_studio.rb +10 -3
metadata +8 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fca2972e96c5cc005be5505673727eb85a24549f7632f0b1d3d9809ec27411d
-  data.tar.gz: 6dc069c098e0b6e664ed5fededf8c15848b73a39d845199357c009acf785298e
+  metadata.gz: d9f198cf717ac69a1a570b082b7ebf76a7d0560e1f863d3410bbc4eeeeca71e5
+  data.tar.gz: 4bbea890a22fafaba9449bd4aac5483ecfdf3366e694ac9c142c75e898d4435d
 SHA512:
-  metadata.gz: 8186c3bf21e01bda36d230e1c43a4fb775a9e98812cdd87fa3d7c2513c44ac12178f981b083b3566f8e26eb3062daaaba2427ec6f32310ccfa8b3108ab8ab6ec
-  data.tar.gz: 67274a43c5f27c1e9765b0ab3ffbd0f871acb22484506bdfdfe74785c02ae4598e702244cf23a90f9ad0e86c08a4bada67ba0e1bbac2d3fbf3cf89907652f376
+  metadata.gz: 5becc3ebd6544d5275f1107e1eb9338b47ce5cfeb19e682c9ebdf9bc44e5814f72c3b999f7f4839c1205fd4b9393713dc060edd94264334b999c997c75437a16
+  data.tar.gz: 90e26c9214ef297a84e43f910bda3d8d22278703672f1eb564a36c83071c6c90717cae87f836b5ba57844b7f1a4ab5b2793c01ec5d16b7cea1cf820eddb1c3dc

data/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,52 @@
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## Unreleased — targets v0.5.0 (minor)
+Ships the gem's first Rails half, and its first CI. The version number is
+allocated by the release conductor, not by this entry.
+### Added
+- **The browser lane** — a real Chromium against the gem's real onchain surface. `e2e/boot.rb` serves a minimal `test/dummy` host (no `bin/rails`, no `config.ru`, no database — the partial's only inputs are locals and one data attribute) and COPIES the shipped `network_guard.js` into it, so the specs drive the bytes a consumer installs rather than a re-typed copy. Runs as a PARALLEL CI job, ~40s, and is deliberately not in `bin/release-check`: a release should not install a browser to publish. Pieces: `playwright.config.js`, `e2e/*.spec.js`, `test/dummy/`, `config/e2e_lane.yml`, `bin/e2e-executed-set-check`, `test/e2e_lane_contract_test.rb`.
+- **`config/e2e_lane.yml` + `bin/e2e-executed-set-check`** — the lane's verdict gate. A test lane can report that its specs PASSED; it structurally cannot report that it RAN THEM ALL. The gate reads Playwright's own receipt and asserts `expected == total_specs && skipped == 0 && unexpected == 0`, so a runtime `testInfo.skip()`, a `--grep`, `--only-changed` and an uncollected file all surface as one arithmetic failure instead of four invisible ones. It also refuses a `--list` receipt by name rather than reading it as a catastrophic failure, and NAMES an unreadable one — a run killed mid-write leaves a truncated file, and "the lane never finished" and "the gate is broken" are different findings that a bare parse error makes look identical. Mutation-proven ELEVEN ways, every mode red: a runtime skip, a `--grep`, a dropped spec file, a stale total, per-file drift that keeps the total right, a missing receipt, a `--list` receipt, an all-zero receipt, a truncated receipt, a receipt that is not a Playwright report, and a `grepInvert`/`shard` added to the config.
+### Fixed
+- **The network-mismatch modal leaked `%>` into the rendered card.** Its header comment spelled the registration example out in real ERB tags, and the example's own closing marker ended the comment early — so the remaining prose rendered as literal text in the card, and the broken structure took Alpine down with it (`Cannot set properties of null`). It compiled, so `test/views_test.rb` was green; it passed review, CI and 114 tests. **The browser lane caught it on its first real run**, which is the clearest possible statement of what the lane is for. The comment now describes the integration in words; the runnable example lives in the README, where a stray marker cannot escape into a page.
+- The modal's documented host requirements now name the one that is easy to miss: an **ancestor `x-data` scope** (normally a bare `x-data` on the host's `<body>`). studio-engine's modal host roots itself at a `template x-if` with no `x-data` of its own, and Alpine only walks trees beneath an `x-data` root — without it the host is never processed, the modal never opens, and the served HTML looks perfectly correct.
+### Tests
+- `test/e2e_lane_contract_test.rb` (9): the contract names exactly the spec files that exist, per-file counts match the committed specs, the total equals their sum, no spec or config can narrow the set (`test.only`, `testInfo.skip`, `test.fixme`, `grep`, `grepInvert`, `--only-changed`, `testIgnore`, `testMatch`, `shard`, retries), the lab renders the gem's real partials by name, `boot.rb` copies the real assets, and the layout supplies the Alpine root the host requires.
+- `test/e2e_executed_set_test.rb` (10): the gate's arithmetic without a browser — a clean run, a runtime skip, a failure, a narrowed run, a spec moved between files, a `--list` receipt, a truncated receipt, valid JSON that is not a Playwright report, a real receipt parsing, and nested-suite flattening.
+### Added
+- **`Solana::Network`** — cluster identity, Rails-free and RPC-free. Pinned genesis hashes for mainnet-beta/devnet/testnet, `cluster_for_genesis` (what an RPC URL *actually* points at, as opposed to what its hostname claims), Wallet Standard chain ids, alias normalization, and `expected_for_environment`. `alignment(cluster:, genesis_hash:)` returns **three** states — `:aligned`, `:mismatched`, `:unverifiable` — because localnet has no pinnable genesis and an unknown cluster name has no hash to compare: collapsing `:unverifiable` into `:mismatched` refuses to boot every local validator, and collapsing it into `:aligned` trusts a chain nobody checked.
+- **`SolanaStudio::Engine`** — an **optional** Rails engine, required only when `Rails::Engine` is already defined. `railties` is deliberately NOT a runtime dependency: plain-Ruby consumers (chain-ops scripts, rake tasks, `ruby -e`) load the gem exactly as before and never install Rails. Both directions are asserted, in separate subprocesses, in `test/engine_test.rb`.
+- **`solana_studio/modals/_network_mismatch`** — the network-mismatch explainer modal, rendering through studio-engine's shared modal blocks.
+- **`solana_studio/network_guard.js`** — `SolanaStudio.network`, a validation wrapper for onchain actions. A website **cannot** read which network a wallet is set to (Phantom does not expose it; the Wallet Standard `chains` array lists what a wallet supports, not what it selected), so the guard does the only two things that work: `withSignInChainId` asserts the app's cluster as a SIWS `chainId` and lets the wallet contradict it, and `guard(fn, {onHint})` classifies a *failure* after the fact. It never blocks, and it re-throws the original rejection untouched — a hint beside the real error, never instead of it. `classify` is calibrated to under-claim, and precedence is what makes that true: a custom program error means the program RAN on a chain that has it, so it outranks the "Transaction simulation failed" wrapper that Solana puts around every failed simulation. Without that ordering an ordinary "contest is full" classified as a probable network problem at top confidence — the exact wrong-thing-to-fix this feature exists to prevent, in the feature's own voice.
+- **`bin/release-check`** — one entry point for local cert, CI, and release. Enumerates test files by glob (no curated list to drift) and fails any file that runs **zero** tests or **skips** one.
+- **`.github/workflows/gem-ci.yml`** — the gem's first CI lane. Runs the suite, builds the gem, and asserts the engine's files are inside the **built artifact** (a manifest can be right while the build excludes a file; only the artifact is what a consumer installs).
+### Changed
+- **`spec.files` now includes `app/**/*`.** This is the highest-consequence line in the gemspec: the release sweep publishes on membership rather than content, so a view left outside this glob would ship an engine with no views in it — green suite, green CI, green sweep, and a `missing partial` raised in a consumer app. `test/gemspec_test.rb` asserts the **invariant** (every file in a shipped tree is in the manifest) rather than a filename checklist, which would pass forever while the next new file escaped.
+### Tests
+- `test/network_test.rb` (13): genesis hashes asserted literally rather than round-tripped through the table that defines them; the three-state alignment, each state separately; `canonical` returning nil rather than a default for an unknown name; and that no boolean exists to collapse the third state.
+- `test/engine_test.rb` (6): the conditional in both directions, in separate processes (`require` is idempotent, so one process cannot observe both).
+- `test/gemspec_test.rb` (8): the packaging invariant, no directory entries, the version file's single literal asserted with the RELEASE CONDUCTOR'S OWN regex rather than a proxy for it, the gemspec holding no literal of its own, and no Rails runtime dependency.
+- `test/network_guard_js_test.rb` (18): the classifier under node, including the inversion found in review — a custom program error outranks the "Transaction simulation failed" wrapper, so a full contest is never reported as a network problem — plus the wrapper's transparency: original error re-thrown, success passed through, a throwing hint callback unable to replace the real error.
+- `test/views_test.rb` (3): every shipped ERB template compiles under **ActionView's** Erubi (stdlib ERB cannot compile the `render … do` block form), the glob is non-empty, and the modal still renders the wallet's own error text.
+## v0.4.7 (2026-06-05)
+### Added
+- **`Solana::Transaction.cosign_wire(signed_wire_bytes, signer:, require_complete:)`** — client-first cosign. Adds one signature to an already-(partially-)signed wire tx WITHOUT rebuilding it: parses the compact-u16 signature count + message header, finds the signer's account-key index, asserts that slot is currently zero (never clobbers a real signature), signs the EXACT message bytes, writes the 64-byte signature in, and (when `require_complete:`, default true) re-asserts OPSEC-017 — every required slot non-zero. Pure Ruby, no RPC. Enables the Phantom-signs-FIRST / server-cosigns-SECOND entry flow that clears Phantom's multi-signer-order "could be malicious" Lighthouse banner. `cosign_wire_base64` is the base64 wrapper.
+- **`Solana::Transaction.read_compact_u16(bytes, offset)`** — ShortVec compact-u16 decoder, `[value, next_offset]` (wire-parser primitive behind `cosign_wire`).
+- **`Solana::Client#simulate_transaction(tx_base64, sig_verify:, replace_recent_blockhash:, commitment:)`** — server-side `simulateTransaction` pre-flight; returns the RPC `value` object (`err`/`logs`/`unitsConsumed`). Lets the server run the same pre-broadcast simulation the entry board did client-side, now that broadcast moved server-side.
+### Tests
+- `test/transaction_test.rb` (+9 tests): correct slot filled + verifies over message, other signer's sig + message bytes untouched, 2/2 sigs valid, refuses to clobber a filled slot, rejects a non-signer, off-by-one slot guard, malformed-header count-mismatch rejection, base64 round-trip.
+- `test/client_test.rb` (+2 tests): simulate_transaction sends the right RPC + parses `value`; surfaces a program error in `value["err"]`.
 ## v0.4.6 (2026-06-02)
 ### Added

data/README.md CHANGED Viewed

@@ -8,9 +8,11 @@ Ruby primitives for building on Solana — JSON-RPC client, Ed25519 keypairs, Bo
 ```ruby
 # Gemfile
-gem "solana-studio", git: "https://github.com/amcritchie/solana-studio.git"
+gem "solana-studio", "~> 0.5"
 ```
+Consumer apps use the RubyGems release. Use a local path only while actively developing the gem, and restore the RubyGems dependency before merging.
 ## Usage
 ### Keypair
@@ -77,14 +79,155 @@ pda, bump = Solana::Transaction.find_pda(
 )
 ```
+### Network (cluster identity)
+A Solana cluster has three names that must agree, and nothing in the protocol
+makes them agree for you: the operator's name (`devnet`), the chain's own
+fingerprint (its genesis hash), and the wallet's name (`solana:devnet`).
+`Solana::Network` is the lookup table that relates them.
+```ruby
+Solana::Network.genesis_hash("devnet")          # => "EtWTRABZaYq6..."
+Solana::Network.cluster_for_genesis(hash)       # => "mainnet-beta" (what an RPC ACTUALLY is)
+Solana::Network.wallet_standard_chain("mainnet-beta")  # => "solana:mainnet"  (note: no -beta)
+Solana::Network.canonical("mainnet")            # => "mainnet-beta"; nil if unrecognized
+Solana::Network.expected_for_environment("qa")  # => "devnet"
+```
+Alignment has **three** outcomes, and collapsing the middle one is a bug:
+```ruby
+Solana::Network.alignment(cluster: "devnet", genesis_hash: live_hash)
+# => :aligned | :mismatched | :unverifiable
+```
+`:unverifiable` means there was no pinned hash to compare — localnet (whose
+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.
+## Rails engine (optional)
+The gem is Rails-free by default — `railties` is **not** a runtime dependency,
+and plain-Ruby consumers (scripts, rake tasks, `chain-ops`) never load a line of
+it. When the gem is required inside a Rails process, `SolanaStudio::Engine`
+defines itself and contributes the onchain UI primitives.
+### Network mismatch guard
+The problem: a user whose wallet is set to Mainnet, using a QA app that runs on
+Devnet. Their wallet simulates against the wrong chain, shows a frightening
+approval sheet and a balance from a chain nobody is using, and they abandon the
+flow.
+**A website cannot detect this directly.** Phantom does not expose its selected
+network, and the Wallet Standard `chains` array lists what a wallet *supports*,
+not what it has *selected*. There is no pre-flight read to write. So the guard
+does the only two things that work:
+**1. Assert at sign-in.** Hand the wallet a SIWS `chainId` and let it contradict
+you — the one pre-emptive signal that exists.
+```js
+var signInInput = SolanaStudio.network.withSignInChainId({
+  domain: window.location.host,
+  nonce: nonce
+});
+// => adds chainId: "solana:devnet"
+```
+**2. Explain after a failure.** Wrap any onchain action. The guard never blocks
+and never swallows an error — it re-throws the original rejection untouched, and
+hands you a hint only when a mismatch would actually explain the failure.
+```js
+SolanaStudio.network.guard(
+  function() { return provider.signTransaction(tx); },
+  {
+    action: "Entering this contest",
+    onHint: function(hint) { Alpine.store('modals').open('network-mismatch', hint); }
+  }
+).then(broadcast);   // your existing .catch still receives the real error
+```
+`classify(err)` returns `"likely"`, `"possible"`, or `"unrelated"`, and is
+calibrated to **under-claim**: an insufficient-funds error stays an
+insufficient-funds error. Dressing up an unrelated failure as a network problem
+sends the user to fix the wrong thing, which is the bug this feature exists to
+remove.
+### Host setup
+```erb
+<%# once, inside your modal host %>
+<template x-if="$store.modals.current().id === 'network-mismatch'">
+  <%= render "solana_studio/modals/network_mismatch" %>
+</template>
+```
+```erb
+<%# so the browser can read what the server knows %>
+<body data-solana-network="<%= Solana::Network.describe(
+        Solana::Config::NETWORK, environment: Rails.env).to_json %>">
+```
+The guard falls back to discrete `data-solana-cluster` / `data-app-environment`
+attributes, so a host can adopt it before changing its layout.
+Requires studio-engine's modal host (`Alpine.store('modals')`) and its shared
+modal blocks. The JS is `solana_studio/network_guard.js` on the asset path.
 ## Dependencies
 - `ed25519` (~> 1.3) — Ed25519 signing
 - 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.
 ## Development Notes
-See [CLAUDE.md](./CLAUDE.md) for detailed development context including the full API reference, design decisions, and AI agent instructions.
+See [RUNBOOK.md](./RUNBOOK.md) for troubleshooting and local test commands.
+### The browser lane
+The Ruby suite cannot see two things this gem ships: whether
+`network_guard.js` actually **runs** in a browser, and whether
+`_network_mismatch.html.erb` **renders** (rendering it needs studio-engine's modal
+blocks and a view context, so `test/views_test.rb` only proves it compiles).
+```bash
+npm ci && npx playwright install chromium
+npx playwright test              # ~40s, boots its own server
+npx playwright test --headed     # watch it
+bin/e2e-executed-set-check       # did the lane run its WHOLE declared set?
+```
+The lane drives the **shipped bytes**: `e2e/boot.rb` copies the real
+`app/assets/javascripts/solana_studio/network_guard.js` into the dummy's `public/`,
+and the lab pages render the real partials by name. A lab page may set up a
+partial's locals and nothing else — `test/e2e_lane_contract_test.rb` asserts that,
+because a page that hand-rolled what the gem does would leave the specs grading the
+lab while reporting green over untested gem code.
+It is **not** in `bin/release-check`. It runs as a parallel CI job, so it adds ~0
+to the wall time a PR waits and a release does not install a browser to publish.
+**Two halves, one number.** `config/e2e_lane.yml` declares how many specs must
+execute. `bin/e2e-executed-set-check` reads Playwright's own receipt after the run
+and asserts the executed set against it; `test/e2e_lane_contract_test.rb` asserts
+the committed specs still declare it. Static counting answers "how many are
+DECLARED" and can never answer "how many RAN" — and a runtime skip, a stray
+`--grep`, `--only-changed`, and an uncollected file are four spellings of the same
+event. The receipt turns all four into one arithmetic failure.
+Derive the counts, never hand-count them: `npx playwright test --list`.
+Run the suite with `bin/release-check` — the same entry point CI and the release
+gate use, so they cannot drift apart. It enumerates test files by glob (no list
+to forget a file from) and **fails a file that runs zero tests or skips one**,
+because a suite that quietly stops covering something is the failure a green
+build cannot show you. `node` is required: the browser guard's suite runs the
+shipped `.js` under node with `window`/`document` stubs.
 ## License

data/app/assets/javascripts/solana_studio/network_guard.js ADDED Viewed

@@ -0,0 +1,299 @@
+// SolanaStudio.network — cluster-mismatch validation for onchain actions.
+//
+// THE CONSTRAINT THAT SHAPES ALL OF THIS: a website cannot read which network a
+// browser wallet is set to. Phantom does not expose it, and the Wallet Standard
+// `chains` array advertises what a wallet SUPPORTS, not what it has selected.
+// So there is no pre-flight check to write. You cannot ask the wallet where it
+// is. You can only do two things:
+//
+//   1. ASSERT, at sign-in, and let the wallet contradict you. Handing the wallet
+//      a SIWS `chainId` makes it compare that against its own selected network
+//      and object. This is the one pre-emptive signal that exists, it costs a
+//      signature the user is already making, and it fires once per session.
+//
+//   2. EXPLAIN, after a failure. When a wallet action fails in a way a cluster
+//      mismatch would explain, say so — as a hint beside the real error, never
+//      instead of it. A misclassification that HIDES the true error is a worse
+//      bug than the one this file exists to fix.
+//
+// Deliberately not a blocker. In a `signTransaction` + app-side
+// `sendRawTransaction` architecture the app's own RPC decides where the
+// transaction lands, so a wrong-network wallet cannot misroute funds. What it
+// does is make the wallet simulate against the wrong chain — a frightening
+// approval sheet, a balance from a chain nobody is using, and an abandoned
+// flow. That is a clarity problem, and clarity is what this ships.
+(function() {
+  "use strict";
+  var W = window;
+  W.SolanaStudio = W.SolanaStudio || {};
+  var LABELS = {
+    "mainnet-beta": "Mainnet",
+    "devnet": "Devnet",
+    "testnet": "Testnet",
+    "localnet": "Localnet"
+  };
+  // Mirrors Solana::Network::WALLET_STANDARD_CHAINS. Note mainnet loses its
+  // -beta suffix here — "solana:mainnet-beta" is not a chain any wallet knows.
+  var WALLET_STANDARD_CHAINS = {
+    "mainnet-beta": "solana:mainnet",
+    "devnet": "solana:devnet",
+    "testnet": "solana:testnet",
+    "localnet": "solana:localnet"
+  };
+  var ENVIRONMENT_LABELS = {
+    qa: "QA",
+    production: "Production",
+    development: "Development",
+    test: "Test"
+  };
+  // --- Page facts ------------------------------------------------------------
+  // The server is the authority on which cluster this app runs against; the
+  // browser only reads it. Preferred form is one JSON blob written from
+  // Solana::Network.describe. The discrete attributes are a fallback so a host
+  // can adopt the guard before it changes its layout.
+  function context() {
+    var body = document.body;
+    if (!body || !body.dataset) return blank();
+    var described = null;
+    if (body.dataset.solanaNetwork) {
+      try { described = JSON.parse(body.dataset.solanaNetwork); } catch (e) { described = null; }
+    }
+    var cluster = (described && described.cluster) || body.dataset.solanaCluster || "";
+    var environment = (described && described.environment) || body.dataset.appEnvironment || "";
+    return {
+      cluster: cluster,
+      known: !!LABELS[cluster],
+      label: (described && described.label) || LABELS[cluster] || "Unknown Network",
+      environment: environment,
+      environmentLabel: ENVIRONMENT_LABELS[environment] ||
+        (environment ? environment.charAt(0).toUpperCase() + environment.slice(1) : "Unknown"),
+      walletStandardChain: (described && described.wallet_standard_chain) ||
+        WALLET_STANDARD_CHAINS[cluster] || null
+    };
+  }
+  function blank() {
+    return {
+      cluster: "", known: false, label: "Unknown Network",
+      environment: "", environmentLabel: "Unknown", walletStandardChain: null
+    };
+  }
+  // --- 1. Assert at sign-in --------------------------------------------------
+  // The value to put on a SIWS input's `chainId`. Returns null when this app's
+  // cluster has no Wallet Standard name, in which case the field must be OMITTED
+  // rather than sent empty — an unrecognized chainId reads to the wallet as a
+  // mismatch against every network, so a blank one rejects everybody.
+  function signInChainId() {
+    return context().walletStandardChain;
+  }
+  // Apply the chainId to a SIWS input, non-destructively. A host that does not
+  // want the assertion simply does not call this.
+  function withSignInChainId(signInInput) {
+    var chainId = signInChainId();
+    if (!chainId) return signInInput;
+    var out = {};
+    for (var k in signInInput) {
+      if (Object.prototype.hasOwnProperty.call(signInInput, k)) out[k] = signInInput[k];
+    }
+    out.chainId = chainId;
+    return out;
+  }
+  // --- 2. Explain after a failure -------------------------------------------
+  // Error shapes a cluster mismatch would explain, ranked by how much of the
+  // message the mismatch actually accounts for.
+  //
+  // UNRELATED, AND CHECKED FIRST. A custom program error means the program RAN:
+  // it was found, on a chain that has it, and it rejected the instruction on its
+  // own terms. Whatever else the envelope says, a cluster mismatch cannot explain
+  // that outcome.
+  //
+  // This precedence is the fix for a real inversion. "Transaction simulation
+  // failed" is the WRAPPER Solana puts around every failed simulation, including
+  // ordinary business rejections, so matching it as LIKELY classified
+  //
+  //   "Transaction simulation failed: Error processing Instruction 0:
+  //    custom program error: 0x1770"
+  //
+  // — a plain "contest is full" — as a probable network problem at top
+  // confidence. That sends a user to change their wallet's network over a full
+  // contest: the exact wrong-thing-to-fix this feature exists to prevent, with the
+  // feature's own voice behind it. Found in review by executing this file.
+  // Every entry here must name a PROGRAM CODE — proof the program ran and chose
+  // this outcome. "Error processing Instruction 0:" is deliberately NOT here: it
+  // is Solana's generic InstructionError envelope, and it wraps the not-found
+  // failures below just as readily as it wraps a business rejection. Putting it
+  // here fixed the first inversion by creating its mirror image: a wrapper at this
+  // precedence answered `unrelated` for
+  //
+  //   "Transaction simulation failed: Error processing Instruction 0:
+  //    Attempt to load a program that does not exist"
+  //
+  // so explain() returned null and the modal never opened. Precedence, verified
+  // against solana-sdk's transaction-error source: ProgramAccountNotFound,
+  // AccountNotFound and BlockhashNotFound all render TOP-LEVEL — only
+  // InstructionError carries the "Error processing Instruction {i}:" wrapper. So
+  // the composed string above is DEFENSIVE rather than observed; our own captured
+  // corpus has never wrapped a not-found. It costs nothing to order correctly and
+  // the rule generalizes: a wrapper must never decide confidence. That was the
+  // lesson of the first fix, and this list is where it has to hold.
+  var PROGRAM_ERROR = [
+    /custom program error/i,
+    /\b0x1[0-9a-f]{3}\b/i,          // Anchor's 6000+ user error range, as hex
+    /\bAnchorError\b/i
+  ];
+  // The generic instruction envelope, checked AFTER the not-found signals. On its
+  // own — no program code, and nothing above matched — an instruction failed on
+  // its own terms and there is no wrong-chain signal to explain it, so it demotes
+  // an otherwise-POSSIBLE shrug to `unrelated` rather than deciding anything.
+  var INSTRUCTION_ERROR = [
+    /error processing instruction/i,
+    /\bInstructionError\b/i
+  ];
+  // LIKELY — the wallet looked for our program or our blockhash on a chain that
+  // does not have them. Each of these names a thing that WAS NOT FOUND, which is
+  // what a wrong chain actually produces; none of them is a wrapper.
+  var LIKELY = [
+    /attempt to load a program that does not exist/i,
+    /program that does not exist/i,
+    /ProgramAccountNotFound/i,
+    /unlikely to succeed/i,
+    /blockhash not found/i,
+    // TransactionError::AccountNotFound. The canonical "this account has no
+    // balance on the chain being simulated against" — top-level, unwrapped, and
+    // with no business-logic reading, which is what earns it a place here when
+    // the Anchor account errors deliberately do not get one (an
+    // AccountNotInitialized on a PDA is genuinely ambiguous: wrong network, or a
+    // right-network account nobody initialized).
+    /found no record of a prior credit/i,
+    /\bAccountNotFound\b/i
+  ];
+  // POSSIBLE — genuinely ambiguous. Phantom collapses a failed simulation into
+  // a bare "Unexpected error", and a user who bails at a scary approval sheet is
+  // indistinguishable from one who changed their mind. Worth a hint; never worth
+  // replacing the real message.
+  var POSSIBLE = [
+    /^unexpected error$/i,
+    /^unexpected/i,
+    /user rejected/i,
+    /user declined/i,
+    // The bare wrapper, with no program error to account for it. Genuinely
+    // ambiguous — worth a hint, never worth top confidence.
+    /transaction simulation failed/i
+  ];
+  function messageOf(err) {
+    if (!err) return "";
+    if (typeof err === "string") return err;
+    return err.message || err.error || String(err);
+  }
+  // How much would a cluster mismatch explain this failure?
+  //   "likely" | "possible" | "unrelated"
+  //
+  // Nothing here is proof. The wallet never tells us where it was, so this is
+  // inference over error text, and it is calibrated to under-claim: an
+  // insufficient-funds error stays an insufficient-funds error.
+  function classify(err) {
+    var msg = messageOf(err);
+    if (!msg) return "unrelated";
+    var i;
+    // Precedence, not just membership: a program error is checked BEFORE the
+    // LIKELY list, because the wrapper text can carry both.
+    for (i = 0; i < PROGRAM_ERROR.length; i++) {
+      if (PROGRAM_ERROR[i].test(msg)) return "unrelated";
+    }
+    for (i = 0; i < LIKELY.length; i++) {
+      if (LIKELY[i].test(msg)) return "likely";
+    }
+    // AFTER the not-found signals, never before: the envelope wraps them too.
+    for (i = 0; i < INSTRUCTION_ERROR.length; i++) {
+      if (INSTRUCTION_ERROR[i].test(msg)) return "unrelated";
+    }
+    for (i = 0; i < POSSIBLE.length; i++) {
+      if (POSSIBLE[i].test(msg)) return "possible";
+    }
+    return "unrelated";
+  }
+  function couldBeMismatch(err) {
+    return classify(err) !== "unrelated";
+  }
+  // The props a mismatch explainer modal needs. Returns null when a mismatch
+  // would not explain the failure, so `var hint = explain(err); if (hint) {...}`
+  // is the whole integration.
+  function explain(err, opts) {
+    opts = opts || {};
+    var confidence = classify(err);
+    if (confidence === "unrelated") return null;
+    var ctx = context();
+    return {
+      confidence: confidence,
+      cluster: ctx.cluster,
+      networkLabel: ctx.label,
+      environment: ctx.environment,
+      environmentLabel: ctx.environmentLabel,
+      action: opts.action || "This transaction",
+      originalMessage: messageOf(err),
+      title: "Check your wallet's network",
+      message: (opts.action || "This transaction") + " runs on " + ctx.label +
+               ", because you're on " + ctx.environmentLabel + ". If your wallet " +
+               "is set to a different network, it will warn you and show the " +
+               "wrong balance."
+    };
+  }
+  // --- The wrapper -----------------------------------------------------------
+  // Put this around any onchain action. It does not gate the call — it cannot,
+  // and pretending otherwise would be a lie in the shape of a safety feature.
+  // It runs the action, and when the action fails in a mismatch-shaped way it
+  // hands the host a hint to show beside the error.
+  //
+  //   SolanaStudio.network.guard(
+  //     function() { return provider.signTransaction(tx); },
+  //     { action: "Entering this contest", onHint: showNetworkHint }
+  //   )
+  //
+  // The original rejection is always re-thrown, unchanged. Callers keep their
+  // existing error handling exactly as written.
+  function guard(fn, opts) {
+    opts = opts || {};
+    return Promise.resolve()
+      .then(fn)
+      .catch(function(err) {
+        var hint = explain(err, opts);
+        if (hint && typeof opts.onHint === "function") {
+          try { opts.onHint(hint, err); } catch (e) { /* a broken hint must not eat the error */ }
+        }
+        throw err;
+      });
+  }
+  W.SolanaStudio.network = {
+    context: context,
+    signInChainId: signInChainId,
+    withSignInChainId: withSignInChainId,
+    classify: classify,
+    couldBeMismatch: couldBeMismatch,
+    explain: explain,
+    guard: guard,
+    WALLET_STANDARD_CHAINS: WALLET_STANDARD_CHAINS
+  };
+})();

data/app/views/solana_studio/modals/_network_mismatch.html.erb ADDED Viewed

@@ -0,0 +1,83 @@
+<%#
+  Network-mismatch explainer — the onchain modal primitive from solana-studio.
+  Opened when a wallet action fails in a way a cluster mismatch would explain.
+  Props come from SolanaStudio.network.explain(err) (see
+  app/assets/javascripts/solana_studio/network_guard.js) and carry:
+    confidence       "likely" | "possible" — how much a mismatch accounts for it
+    networkLabel     the cluster THIS APP runs on ("Devnet")
+    environmentLabel the environment the user is in ("QA")
+    action           what they were doing ("Entering this contest")
+    originalMessage  the wallet's own error text — always shown, never replaced
+  This modal EXPLAINS; it does not block. A website cannot read which network a
+  wallet is set to (Phantom does not expose it, and the Wallet Standard `chains`
+  array lists what a wallet supports rather than what it selected), so an
+  honest modal states what the app knows — its own network — and leaves the
+  comparison to the person who can actually see the wallet.
+  HOST REQUIREMENTS — both are load-bearing, and the second is easy to miss:
+    1. studio-engine's modal host (Alpine $store.modals) and the shared modal
+       blocks, with this partial registered under the id "network-mismatch"
+       inside a template x-if on that id.
+    2. AN ANCESTOR x-data SCOPE, normally a bare `x-data` on the host app's
+       <body>. The engine's modal host roots itself at a template x-if with no
+       x-data of its own, and Alpine only walks trees beneath an x-data root —
+       without it the host is never processed, the modal never opens, and the
+       page looks perfectly correct in the served HTML.
+  NO ERB TAGS IN THIS COMMENT, deliberately. An earlier version spelled the
+  registration example out in real tags; the example's own closing marker ended
+  this comment early and the remaining prose leaked into the rendered card as
+  literal text. It compiled, it passed every Ruby tier, and only the browser lane
+  saw it. Describe the integration in words here; the runnable example lives in
+  the gem README, where a stray marker cannot escape into a page.
+%>
+<div x-data="{
+       get props() { var c = $store.modals.current(); return (c && c.props) || {}; }
+     }">
+  <%= render 'studio/modals/blocks/card_header',
+        icon_emoji: '🔀',
+        title_key: "props.title || 'Check your wallet\\'s network'" do %>
+    <span x-text="props.message"></span>
+  <% end %>
+  <%# The app's own facts. Stated plainly and without hedging, because these two
+      rows are the half of the comparison we can actually vouch for. %>
+  <div class="rounded-lg border border-subtle bg-surface-alt p-3 mb-4 text-sm">
+    <div class="flex items-center justify-between gap-3">
+      <span class="text-secondary">This app runs on</span>
+      <span class="font-semibold text-heading" x-text="props.networkLabel"></span>
+    </div>
+    <div class="flex items-center justify-between gap-3 mt-2">
+      <span class="text-secondary">Environment</span>
+      <span class="font-semibold text-heading" x-text="props.environmentLabel"></span>
+    </div>
+  </div>
+  <div class="rounded-lg border border-subtle p-3 mb-4">
+    <p class="text-xs font-semibold text-heading mb-2">If your wallet is on a different network</p>
+    <p class="text-xs text-secondary">
+      Open Phantom, then <span class="font-semibold text-heading">Settings → Developer Settings</span>
+      and switch the network to <span class="font-semibold text-heading" x-text="props.networkLabel"></span>.
+      Your wallet shows a separate balance for every network, so a wallet on the
+      wrong one looks empty even when it isn't.
+    </p>
+  </div>
+  <%# The wallet's real error, always. The hint sits BESIDE the error, never in
+      place of it — a mismatch is inferred from error text, and a wrong guess
+      that swallowed the true message would be a worse bug than the confusion
+      this modal exists to clear up. %>
+  <template x-if="props.originalMessage">
+    <details class="mb-4 rounded-lg border border-subtle bg-surface-alt p-3">
+      <summary class="text-xs text-secondary cursor-pointer">What the wallet reported</summary>
+      <p class="mt-2 text-xs text-secondary break-words" x-text="props.originalMessage"></p>
+    </details>
+  </template>
+  <button type="button" class="btn btn-primary btn-lg w-full" @click="$store.modals.close()">
+    Got it
+  </button>
+</div>

data/lib/solana/client.rb CHANGED Viewed

@@ -54,6 +54,22 @@ module Solana
       call("sendTransaction", [signed_tx_base64, opts])
     end
+    # Server-side pre-flight: run simulateTransaction against a base64 wire tx.
+    # sig_verify:false lets us simulate a tx without all signatures present (or
+    # without re-verifying ones that are). Returns the RPC `value` object
+    # ({ "err" =>, "logs" =>, "unitsConsumed" =>, … }); `value["err"]` is nil on
+    # success. Mirrors the client-side simulate the entry board used to run.
+    def simulate_transaction(signed_tx_base64, sig_verify: false, replace_recent_blockhash: false, commitment: "confirmed")
+      opts = {
+        encoding: "base64",
+        sigVerify: sig_verify,
+        replaceRecentBlockhash: replace_recent_blockhash,
+        commitment: commitment
+      }
+      result = call("simulateTransaction", [signed_tx_base64, opts])
+      result&.dig("value")
+    end
     def confirm_transaction(signature, commitment: "confirmed")
       call("getSignatureStatuses", [[signature], { searchTransactionHistory: true }])
     end

data/lib/solana/network.rb ADDED Viewed

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+module Solana
+  # Cluster identity — the one place that knows what "devnet" IS.
+  #
+  # A Solana cluster has three names that must agree, and nothing in the
+  # protocol makes them agree for you:
+  #
+  #   1. The operator's name for it   — "devnet"          (SOLANA_NETWORK)
+  #   2. The chain's own fingerprint  — genesis hash      (getGenesisHash)
+  #   3. The wallet's name for it     — "solana:devnet"   (Wallet Standard)
+  #
+  # Every mis-alignment bug in this ecosystem is two of those three disagreeing:
+  # a mainnet program ID against a devnet RPC (caught at boot by the host's
+  # alignment check), or an app on devnet against a wallet on mainnet (caught at
+  # sign-in, by handing the wallet name #3 and letting it object).
+  #
+  # This module is deliberately Rails-free and RPC-free — it is a lookup table
+  # with opinions. Fetching the live genesis hash is the HOST's job — the RPC call
+  # is `getGenesisHash`, which this gem's Solana::Client does not wrap today (turf
+  # monster adds it in an initializer); deciding what to DO about a mismatch is the
+  # host's too.
+  module Network
+    # Canonical cluster names, as Solana's own tooling spells them. Note
+    # "mainnet-beta" — the hyphenated form is the real one; "mainnet" is an
+    # alias people type, normalized by .canonical.
+    MAINNET = "mainnet-beta"
+    DEVNET  = "devnet"
+    TESTNET = "testnet"
+    LOCALNET = "localnet"
+    CLUSTERS = [MAINNET, DEVNET, TESTNET, LOCALNET].freeze
+    # The genesis block hash of each public cluster — a chain's immutable
+    # fingerprint, and the only cluster identifier that cannot be misconfigured.
+    # An RPC URL can lie (a proxy, a fork, a typo'd host); its genesis hash
+    # cannot. localnet is absent on purpose: a fresh validator generates a new
+    # genesis every time it boots, so there is no constant to pin.
+    GENESIS_HASHES = {
+      MAINNET => "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d",
+      DEVNET  => "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG",
+      TESTNET => "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY"
+    }.freeze
+    # Wallet Standard chain identifiers (CAIP-2 namespace "solana"), the form a
+    # browser wallet speaks. Phantom and every Wallet-Standard wallet advertise
+    # these in `wallet.chains` and accept one as the SIWS `chainId`.
+    #
+    # Mind the asymmetry: the Wallet Standard spells mainnet "solana:mainnet",
+    # WITHOUT the -beta suffix the operator name carries. Passing
+    # "solana:mainnet-beta" is not a near-miss the wallet forgives — it is an
+    # unrecognized chain.
+    WALLET_STANDARD_CHAINS = {
+      MAINNET  => "solana:mainnet",
+      DEVNET   => "solana:devnet",
+      TESTNET  => "solana:testnet",
+      # localnet is a valid Wallet Standard chain, but NOT a valid SIWS chainId —
+      # no wallet can verify a sign-in against a chain only your machine has. It is
+      # here for completeness of the chain table; do not send it as a chainId.
+      LOCALNET => "solana:localnet"
+    }.freeze
+    # Human labels for UI. Anything unrecognized is deliberately NOT given a
+    # friendly name — an unknown cluster is a fact worth showing the operator,
+    # not something to paper over.
+    LABELS = {
+      MAINNET  => "Mainnet",
+      DEVNET   => "Devnet",
+      TESTNET  => "Testnet",
+      LOCALNET => "Localnet"
+    }.freeze
+    ALIASES = {
+      "mainnet"      => MAINNET,
+      "mainnet-beta" => MAINNET,
+      "main"         => MAINNET,
+      "dev"          => DEVNET,
+      "local"        => LOCALNET,
+      "localhost"    => LOCALNET
+    }.freeze
+    module_function
+    # Normalize an operator-supplied cluster name to its canonical spelling.
+    # Returns nil for anything unrecognized — callers decide whether an unknown
+    # cluster is a warning or a refusal, and they need to be able to tell.
+    def canonical(cluster)
+      return nil if cluster.nil?
+      name = cluster.to_s.strip.downcase
+      return nil if name.empty?
+      return name if CLUSTERS.include?(name)
+      ALIASES[name]
+    end
+    def known?(cluster)
+      !canonical(cluster).nil?
+    end
+    # The pinned genesis hash for a cluster, or nil when there isn't one
+    # (unknown cluster, or localnet — whose genesis is per-boot).
+    def genesis_hash(cluster)
+      GENESIS_HASHES[canonical(cluster)]
+    end
+    # Reverse lookup: given a hash from getGenesisHash, which cluster is this?
+    # This is how you learn what an RPC URL ACTUALLY points at, as opposed to
+    # what its hostname claims. nil means "no public cluster we know" — which
+    # for a localnet validator is the correct and expected answer.
+    def cluster_for_genesis(hash)
+      return nil if hash.nil? || hash.to_s.strip.empty?
+      GENESIS_HASHES.key(hash.to_s.strip)
+    end
+    # The Wallet Standard chain id for a cluster — the value to hand a browser
+    # wallet as the SIWS `chainId` so the wallet compares it against its OWN
+    # selected network and objects when they differ.
+    #
+    # This is the ONLY pre-emptive mismatch signal available to a website:
+    # wallets do not expose their selected cluster for reading. You cannot ask;
+    # you can only assert and let the wallet contradict you.
+    def wallet_standard_chain(cluster)
+      WALLET_STANDARD_CHAINS[canonical(cluster)]
+    end
+    def label(cluster)
+      LABELS[canonical(cluster)] || "Unknown Network"
+    end
+    # The cluster an environment is SUPPOSED to run against. Production means
+    # real money, so it means mainnet; everything else means devnet. A host that
+    # disagrees (a mainnet-facing staging rehearsal, say) passes its own map.
+    def expected_for_environment(environment)
+      environment.to_s == "production" ? MAINNET : DEVNET
+    end
+    # Does a live genesis hash confirm the declared cluster?
+    #
+    # Three outcomes, and the middle one matters: :aligned (the chain is who it
+    # says), :mismatched (it is a DIFFERENT known chain — the dangerous case),
+    # and :unverifiable (no pinned hash to compare, i.e. localnet or an unknown
+    # cluster name). Callers must not collapse :unverifiable into either of the
+    # other two — refusing to boot on localnet is as wrong as trusting a
+    # mainnet RPC that answered with a devnet genesis.
+    #
+    # THERE IS DELIBERATELY NO `aligned?` BOOLEAN. One existed and was removed in
+    # review: it answered `false` for :unverifiable, so a host writing the obvious
+    # `raise unless aligned?` would refuse to boot against a local validator —
+    # precisely the mistake the paragraph above warns about, re-introduced by the
+    # convenience wrapper meant to save callers from it. Three states, three
+    # branches; the caller decides what :unverifiable means for them.
+    def alignment(cluster:, genesis_hash:)
+      expected = self.genesis_hash(cluster)
+      return :unverifiable if expected.nil?
+      return :unverifiable if genesis_hash.nil? || genesis_hash.to_s.strip.empty?
+      genesis_hash.to_s.strip == expected ? :aligned : :mismatched
+    end
+    # Everything a UI needs to explain a network to a person, in one hash.
+    # Serialized straight into a data attribute by the host so the browser guard
+    # reads the same facts the server holds.
+    def describe(cluster, environment: nil)
+      canonical_name = canonical(cluster)
+      {
+        cluster: canonical_name,
+        declared: cluster.to_s,
+        known: !canonical_name.nil?,
+        label: label(cluster),
+        genesis_hash: genesis_hash(cluster),
+        wallet_standard_chain: wallet_standard_chain(cluster),
+        environment: environment&.to_s,
+        expected_cluster: environment.nil? ? nil : expected_for_environment(environment)
+      }
+    end
+  end
+end

data/lib/solana/transaction.rb CHANGED Viewed

@@ -155,6 +155,131 @@ module Solana
       Base64.strict_encode64(serialize_partial(additional_signers: additional_signers))
     end
+    # Add one signature to an already-(partially-)signed wire transaction WITHOUT
+    # rebuilding it. This is the inverse-order cosign: a client wallet (Phantom)
+    # signs FIRST and returns the wire bytes with its slot filled and the other
+    # slots zero; the server then drops its own signature into the correct slot.
+    #
+    # Why this exists (Phantom "could be malicious" banner fix): when the SERVER
+    # pre-signs and Phantom signs SECOND, Phantom's Lighthouse heuristics flag
+    # the multi-signer ordering. Flipping the order — Phantom signs the
+    # fully-unsigned tx first, server cosigns after — clears that rule. The
+    # server can't rebuild-and-resign (that would change the message bytes and
+    # invalidate Phantom's signature), so it must surgically patch the existing
+    # wire payload.
+    #
+    # Pure Ruby, no RPC. Parses the compact-u16 signature count + the message
+    # header, locates `signer` in the account-key list, asserts that slot is
+    # still zero (never clobber a real signature), signs the EXACT message bytes
+    # Phantom signed, and writes the 64-byte signature into that slot. Re-asserts
+    # OPSEC-017 afterwards: every one of the numRequiredSignatures slots must be
+    # non-zero (the tx is now fully signed and broadcastable).
+    #
+    # signed_wire_bytes : String (binary) — the wire-format tx (sig count + sigs + message)
+    # signer:           : Solana::Keypair — the cosigner (e.g. the admin keypair)
+    # require_complete: : when true (default) re-assert OPSEC-017 AFTER the write —
+    #   every one of the numRequiredSignatures slots must be non-zero, i.e. this
+    #   cosigner is the LAST one and the tx is now fully broadcastable. The
+    #   turf-monster server cosign is always the final signer, so it leaves this
+    #   on. Pass false for an intermediate cosign in a 3+-signer chain.
+    # Returns the patched wire bytes (binary String). Phantom's signature and the
+    # message bytes are left byte-for-byte untouched.
+    def self.cosign_wire(signed_wire_bytes, signer:, require_complete: true)
+      bytes = signed_wire_bytes.b.dup
+      cursor = 0
+      # 1. Compact-u16 signature count.
+      sig_count, cursor = read_compact_u16(bytes, cursor)
+      raise "cosign_wire: zero signatures in wire payload" if sig_count.zero?
+      sigs_start = cursor
+      sigs_len = sig_count * 64
+      raise "cosign_wire: truncated signature array" if bytes.bytesize < sigs_start + sigs_len
+      message_start = sigs_start + sigs_len
+      # 2. Message header — first byte is numRequiredSignatures. It MUST equal the
+      # signature-array length (a well-formed message reserves exactly one slot
+      # per declared signer). Guard against an off-by-one / malformed payload.
+      num_required = bytes.getbyte(message_start)
+      raise "cosign_wire: empty message" if num_required.nil?
+      unless num_required == sig_count
+        raise "cosign_wire: header numRequiredSignatures=#{num_required} != " \
+              "signature slots=#{sig_count} (malformed wire payload)"
+      end
+      # 3. Account keys. Header is 3 bytes, then a compact-u16 account count,
+      # then `count` * 32-byte keys. The first `num_required` account keys are
+      # the signer slots, in the SAME order as the signature array.
+      acct_cursor = message_start + 3
+      account_count, acct_cursor = read_compact_u16(bytes, acct_cursor)
+      raise "cosign_wire: account count #{account_count} < required signers #{num_required}" if account_count < num_required
+      target = signer.public_key_bytes.b
+      slot_index = nil
+      num_required.times do |i|
+        key = bytes.byteslice(acct_cursor + (i * 32), 32)
+        if key == target
+          slot_index = i
+          break
+        end
+      end
+      raise "cosign_wire: signer #{signer.address} is not a required signer of this transaction" if slot_index.nil?
+      # 4. The target slot must be empty (all-zero). Never clobber a signature
+      # that's already there (Phantom's, or a prior cosigner's).
+      slot_offset = sigs_start + (slot_index * 64)
+      existing = bytes.byteslice(slot_offset, 64)
+      unless existing == ("\x00" * 64).b
+        raise "cosign_wire: slot #{slot_index} for #{signer.address} already holds a signature — refusing to clobber"
+      end
+      # 5. Sign the EXACT message bytes Phantom signed and write the signature in.
+      message = bytes.byteslice(message_start, bytes.bytesize - message_start)
+      signature = signer.sign(message)
+      raise "cosign_wire: signature is not 64 bytes" unless signature.bytesize == 64
+      bytes[slot_offset, 64] = signature.b
+      # 6. OPSEC-017 post-condition (when require_complete): the tx must now be
+      # fully signed — every one of the num_required slots non-zero. A leftover
+      # zero slot means another signer is still missing and the payload is not
+      # broadcastable. The server cosign is the last signer, so it asserts this;
+      # an intermediate cosign in a 3+-signer chain passes require_complete:false.
+      if require_complete
+        num_required.times do |i|
+          off = sigs_start + (i * 64)
+          if bytes.byteslice(off, 64) == ("\x00" * 64).b
+            raise "cosign_wire: slot #{i} is still empty after cosign — " \
+                  "transaction needs #{num_required} signatures and is not yet complete"
+          end
+        end
+      end
+      bytes
+    end
+    # Convenience: cosign a base64 wire tx, return base64.
+    def self.cosign_wire_base64(signed_wire_base64, signer:, require_complete: true)
+      require "base64"
+      patched = cosign_wire(Base64.decode64(signed_wire_base64), signer: signer, require_complete: require_complete)
+      Base64.strict_encode64(patched)
+    end
+    # Decode a compact-u16 (ShortVec) starting at `offset`. Returns [value, next_offset].
+    def self.read_compact_u16(bytes, offset)
+      value = 0
+      shift = 0
+      loop do
+        byte = bytes.getbyte(offset)
+        raise "read_compact_u16: ran off the end of the buffer" if byte.nil?
+        offset += 1
+        value |= (byte & 0x7F) << shift
+        break if (byte & 0x80).zero?
+        shift += 7
+        raise "read_compact_u16: value too large" if shift > 21
+      end
+      [value, offset]
+    end
     private
     def normalize_pubkey(key)

data/lib/solana_studio/engine.rb ADDED Viewed

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module SolanaStudio
+  # The gem's OPTIONAL Rails half.
+  #
+  # solana-studio is a Rails-free gem by design — chain-ops scripts, rake tasks
+  # and bare `ruby -e` consumers load Solana::Keypair and Solana::Transaction
+  # without ever paying for railties. This file is the one place that assumes
+  # Rails, and lib/solana_studio.rb requires it ONLY when Rails::Engine is
+  # already defined. Nothing here runs for a non-Rails consumer, and railties is
+  # deliberately absent from the gemspec's runtime dependencies: the host app
+  # supplies Rails, this engine merely joins it.
+  #
+  # What the engine adds is the onchain UI surface — the modals and browser
+  # guard that every Solana-backed app in the ecosystem would otherwise fork.
+  # Rails picks up app/views automatically for any Engine subclass, so a host
+  # can `render "solana_studio/modals/network_mismatch"` with no configuration.
+  #
+  # Namespace is NOT isolated, matching studio-engine. These are partials a host
+  # renders into its own modal host, not a mounted sub-application; isolating
+  # would scope helpers and routes away from the host for no gain.
+  class Engine < ::Rails::Engine
+    # Sprockets hosts (mcritchie-studio, turf-monster) need every gem-shipped
+    # asset named here or it 404s in production with no local warning —
+    # propshaft hosts serve everything on config.assets.paths and ignore this.
+    # Guarded because a propshaft host has no config.assets.precompile at all.
+    initializer "solana_studio.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+      next unless app.config.assets.respond_to?(:precompile)
+      app.config.assets.precompile += %w[
+        solana_studio/network_guard.js
+      ]
+    end
+  end
+end

data/lib/solana_studio/version.rb ADDED Viewed

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module SolanaStudio
+  # THE gem's version, and the only place it is written.
+  #
+  # This file exists to be rewritten by the release conductor and by nothing
+  # else. `bin/release prepare` allocates the number from the candidate's
+  # membership and rewrites the single literal below
+  # (Release::GemVersion.rewrite_version, which refuses a file declaring more
+  # than one rather than guess which is real), so keep it to exactly one.
+  #
+  # It used to live in solana-studio.gemspec, which made the WHOLE gemspec
+  # release-owned in bin/dor-check's eyes — including spec.files, the runtime
+  # dependencies and the metadata, none of which the conductor touches and none
+  # of which had another writer. That left the manifest permanently un-editable
+  # 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.5.0"
+end

data/lib/solana_studio.rb CHANGED Viewed

@@ -6,7 +6,14 @@ require_relative "solana/spl_token"
 require_relative "solana/system_program"
 require_relative "solana/nonce_account"
 require_relative "solana/auth_verifier"
+require_relative "solana/network"
-module SolanaStudio
-  VERSION = "0.4.6"
-end
+# The version is its own file so the release conductor has exactly one literal
+# to rewrite, and so editing this gem's MANIFEST does not read as editing its
+# version. See lib/solana_studio/version.rb.
+require_relative "solana_studio/version"
+# The Rails half of the gem — views, assets, and the browser network guard.
+# Loaded only inside a Rails process; a plain-Ruby consumer never sees it and
+# never needs railties installed. See lib/solana_studio/engine.rb.
+require_relative "solana_studio/engine" if defined?(::Rails::Engine)

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -37,16 +37,21 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- app/assets/javascripts/solana_studio/network_guard.js
+- app/views/solana_studio/modals/_network_mismatch.html.erb
 - lib/solana-studio.rb
 - lib/solana/auth_verifier.rb
 - lib/solana/borsh.rb
 - lib/solana/client.rb
 - lib/solana/keypair.rb
+- lib/solana/network.rb
 - lib/solana/nonce_account.rb
 - lib/solana/spl_token.rb
 - lib/solana/system_program.rb
 - lib/solana/transaction.rb
 - lib/solana_studio.rb
+- lib/solana_studio/engine.rb
+- lib/solana_studio/version.rb
 homepage: https://github.com/amcritchie/solana-studio
 licenses:
 - MIT
@@ -70,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: 'Ruby primitives for Solana: JSON-RPC client, Ed25519 keypairs, Borsh serialization,