solana-studio 0.11.0 → 0.12.0

data/lib/solana/cosign.rb

@@ -0,0 +1,198 @@
+module Solana
+  # Solana::Cosign — gasless, cosigned transactions, for any app.
+  #
+  # THE PATTERN. A user's wallet signs in the browser; the SERVER pays the fee.
+  # The server builds a transaction with its fee payer in account 0 and an empty
+  # signature slot for every named cosigner, hands the wire to the wallet, takes
+  # the signed wire back, proves it is still the transaction it built, fills its
+  # own slot, simulates, broadcasts and confirms. Users never hold SOL.
+  #
+  #   builder   = Solana::Cosign::Builder.new(client: client, fee_payer: house_keypair)
+  #   prepared  = builder.build(instructions: [ix], cosigners: [user_address],
+  #                             compute_unit_price: 50_000, compute_unit_limit: 200_000)
+  #   # store prepared.wire_base64 + prepared.last_valid_block_height server-side,
+  #   # send prepared.wire_base64 to the wallet, receive signed_wire_base64 back
+  #   completer = Solana::Cosign::Completer.new(client: client, fee_payer: house_keypair)
+  #   result    = completer.complete(signed_wire_base64, expectation: prepared.expectation,
+  #                                  before_send: ->(sig) { record.update!(signature: sig) })
+  #
+  # WHAT IS DELIBERATELY NOT HERE. No key storage (the caller passes the fee
+  # payer keypair in), no environment variables, no program of anyone's, and no
+  # durable nonce: a nonce transaction is only recognised when
+  # advanceNonceAccount is instruction 0, and Phantom inserts Lighthouse
+  # instructions ahead of it, so a nonce cannot anchor a wallet-signed
+  # transaction (turf-monster mainnet incident, 2026-06-11).
+  #
+  # THE ERROR HIERARCHY IS THE SAFETY SEAM. What a caller may do after a failure
+  # depends on one question it cannot answer afterwards — did the bytes leave?
+  #
+  #   Cosign::Error
+  #     WireRejected        the wire is not what was built; nothing was sent
+  #     PreflightRejected   provably never sent: rebuild freely
+  #       BlockhashExpired  block height is already past last_valid_block_height
+  #       SimulationFailed  the program refused it (#err, #logs)
+  #     BroadcastFailed     MAY be on chain: reconcile #signature before rebuilding
+  #       BroadcastExpired  the node or the chain says the blockhash is dead
+  #     TransactionFailed   landed on chain and failed (#err); the fee was paid
+  #
+  # A caller that rewinds a claim on anything under BroadcastFailed can re-send a
+  # transaction that already landed. `rescue Solana::Cosign::PreflightRejected`
+  # is the only rescue that licenses a silent rebuild.
+  module Cosign
+    DEFAULT_COMMITMENT = "confirmed"
+
+    # The wallet may raise the priority fee on its own under load, so the cosign
+    # CAPS rather than refuses: at most this many times the builder's own price,
+    # and this many times the builder's whole priority fee. A builder price of 0
+    # makes both caps 0, so no wallet-added fee is ever paid for.
+    DEFAULT_FEE_MARGIN = 10
+
+    # Lighthouse, Phantom's transaction-protection program. On mainnet Phantom
+    # may insert Lighthouse instructions into a transaction it signs, so a guard
+    # that refuses the program refuses every protected Phantom signature
+    # (turf-monster, 2026-06-11).
+    #
+    # NOT EVERY LIGHTHOUSE INSTRUCTION IS AN ASSERTION. The first data byte is
+    # the instruction's variant, and two variants spend a signer's lamports:
+    #
+    #   0  MemoryWrite  the signer named as `payer` funds the rent of a "memory"
+    #                   account whose size the instruction chooses. The fee payer
+    #                   signs every cosigned wire, so a wire naming it as payer
+    #                   locks its SOL — about 0.05 SOL per 10 KiB, repeatable, and
+    #                   recoverable only by a MemoryClose it signs. A drained fee
+    #                   payer stops every gasless transaction.
+    #   1  MemoryClose  refunds a memory account's rent to its payer.
+    #
+    # Variants 2..17 are the sixteen assertions, AssertAccountData through
+    # AssertBubblegumTreeConfigAccount. Each can make a transaction fail; none
+    # moves funds or grants authority. So Expectation#verify! admits a Lighthouse
+    # instruction only when its first byte is 2..17, and refuses 0, 1, empty
+    # data and every other byte. Naming the fee payer is NOT the test: Phantom's
+    # assertions routinely target the fee payer's own post-state.
+    #
+    # Evidence, all read-only against mainnet on 2026-09-16:
+    #   - The program is immutable (no upgrade authority), so the variants
+    #     cannot drift.
+    #   - Simulation: variant 0 made a funded payer fund a 10,008-byte memory
+    #     account (51,490,880 lamports), and variant 1 refunded it. A true
+    #     AssertSysvarClock (15) succeeded and a false one failed its assertion.
+    #   - The program binary names sixteen assertion instructions, and the
+    #     source enum (github.com/Jac0xb/lighthouse, instruction.rs) orders them
+    #     2..17.
+    #   - All 37 Lighthouse instructions in five cosigned mainnet Phantom
+    #     transactions are variant 6 (32) or 10 (5); test/cosign_lighthouse_test.rb
+    #     carries every one.
+    LIGHTHOUSE_PROGRAM_ID = Keypair.decode_base58("L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95").freeze
+    LIGHTHOUSE_MEMORY_WRITE = 0
+    LIGHTHOUSE_MEMORY_CLOSE = 1
+    LIGHTHOUSE_ASSERTIONS = (2..17)
+
+    DEFAULT_EXTRA_PROGRAMS = [LIGHTHOUSE_PROGRAM_ID].freeze
+
+    BASE58_PUBKEY = /\A[1-9A-HJ-NP-Za-km-z]{32,44}\z/
+
+    class Error < StandardError
+      # The transaction's first signature (base58), when one exists. Present on
+      # every error raised after the fee payer's slot is filled, so a caller can
+      # log it, and — for BroadcastFailed — look it up on chain.
+      attr_reader :signature
+
+      def initialize(message = nil, signature: nil)
+        @signature = signature
+        super(message)
+      end
+    end
+
+    # The returned wire is not the transaction the server built, or cannot be
+    # completed. Raised before the fee payer signs; nothing is returned or sent.
+    # #reason is a short stable code; the message carries detail for SERVER LOGS
+    # ONLY — never echo it to a client, it tells an attacker which check tripped.
+    class WireRejected < Error
+      attr_reader :reason
+
+      def initialize(reason, detail = nil)
+        @reason = reason.to_s
+        super(detail ? "#{@reason}: #{detail}" : @reason)
+      end
+    end
+
+    # Signed in memory, provably never sent.
+    class PreflightRejected < Error; end
+
+    class BlockhashExpired < PreflightRejected
+      attr_reader :block_height, :last_valid_block_height
+
+      def initialize(message = nil, signature: nil, block_height: nil, last_valid_block_height: nil)
+        @block_height = block_height
+        @last_valid_block_height = last_valid_block_height
+        super(message, signature: signature)
+      end
+    end
+
+    class SimulationFailed < PreflightRejected
+      attr_reader :err, :logs
+
+      def initialize(message = nil, signature: nil, err: nil, logs: [])
+        @err = err
+        @logs = Array(logs)
+        super(message, signature: signature)
+      end
+    end
+
+    # Everything from the send onward. Solana::Client#call retries a read
+    # timeout or a reset connection by re-posting the same wire, and hands back
+    # only the last answer, so no exception from a send proves the transaction
+    # was not forwarded. Reconcile #signature against the chain before rebuilding.
+    class BroadcastFailed < Error; end
+
+    class BroadcastExpired < BroadcastFailed; end
+
+    class TransactionFailed < Error
+      attr_reader :err
+
+      def initialize(message = nil, signature: nil, err: nil)
+        @err = err
+        super(message, signature: signature)
+      end
+    end
+
+    module_function
+
+    # Normalize a public key to its 32 raw bytes. Accepts a Solana::Keypair, a
+    # base58 address, or 32 raw bytes. A BINARY string of 32 bytes is always raw;
+    # a string that reads as base58 is decoded. (That order matters: a 32-byte
+    # raw key can happen to be 32 base58-legal characters.)
+    def key_bytes(value)
+      return value.public_key_bytes.b if value.respond_to?(:public_key_bytes)
+      raise ArgumentError, "public key required, got #{value.inspect}" unless value.is_a?(String) && !value.empty?
+      return value.b if value.encoding == Encoding::BINARY && value.bytesize == 32
+
+      if value.match?(BASE58_PUBKEY)
+        decoded = Keypair.decode_base58(value)
+        return decoded.b if decoded.bytesize == 32
+      end
+      return value.b if value.bytesize == 32
+
+      raise ArgumentError, "not a 32-byte public key: #{value.inspect}"
+    end
+
+    def base58(bytes)
+      Keypair.encode_base58(bytes)
+    end
+
+    # [max_compute_unit_price, max_priority_fee_micro_lamports] for a builder
+    # that set this price and limit. See DEFAULT_FEE_MARGIN.
+    def fee_caps(compute_unit_price:, compute_unit_limit:, margin: DEFAULT_FEE_MARGIN)
+      price = Integer(compute_unit_price || 0)
+      limit = Integer(compute_unit_limit || ComputeBudget::MAX_COMPUTE_UNIT_LIMIT)
+      margin = Integer(margin)
+      raise ArgumentError, "fee margin must be >= 1, got #{margin}" if margin < 1
+
+      [price * margin, price * limit * margin]
+    end
+  end
+end
+
+require_relative "cosign/expectation"
+require_relative "cosign/builder"
+require_relative "cosign/completer"

data/lib/solana/ed25519_strict.rb

@@ -0,0 +1,185 @@
+require "ed25519"
+
+module Solana
+  # Ed25519 verification with the checks the `ed25519` gem leaves out.
+  #
+  # `Ed25519::VerifyKey` (ref10) answers one question: does the verification
+  # equation hold? It does not ask whether the public key is a key anyone could
+  # hold a secret for. A small-order point — or a non-canonical spelling of one —
+  # decodes, and signatures verify against it with no secret key behind them. For
+  # a sign-in that means an address nobody owns can sign in.
+  #
+  # So before the equation runs, this module requires:
+  #
+  #   public key  a CANONICAL encoding (y < p, no negative zero) of a curve point
+  #               that is NOT small-order and IS in the prime-order subgroup
+  #               ([L]A is the identity). Every key a wallet generates is [a]B,
+  #               which always passes; nothing a real user holds is refused.
+  #   R           a canonical encoding of a point that is NOT small-order.
+  #   S           reduced: S < L. The library only checks the top three bits,
+  #               which leaves S + L as a second valid spelling.
+  #
+  # That is Solana's own rule (`verify_strict`: small-order A and R and an
+  # unreduced S are refused) plus the subgroup check on A, which the chain does
+  # not make but which no generated key can fail. A signature this module
+  # accepts is one the cluster accepts too.
+  #
+  # Pure Ruby on Integer#pow: no new dependency. A full check costs a few
+  # milliseconds, dominated by one 253-bit scalar multiplication.
+  module Ed25519Strict
+    PUBLIC_KEY_BYTES = 32
+    SIGNATURE_BYTES = 64
+
+    # Field prime, group order, curve constant d, and sqrt(-1) mod p.
+    P = 2**255 - 19
+    L = 2**252 + 27_742_317_777_372_353_535_851_937_790_883_648_493
+    D = (-121_665 * 121_666.pow(P - 2, P)) % P
+    D2 = (2 * D) % P
+    SQRT_M1 = 2.pow((P - 1) / 4, P)
+
+    # Extended coordinates [X, Y, Z, T], x = X/Z, y = Y/Z, xy = T/Z.
+    IDENTITY = [0, 1, 1, 0].freeze
+
+    module_function
+
+    # nil when `bytes` is a public key a secret key can stand behind; otherwise
+    # a short reason, suitable for an error message.
+    def public_key_problem(bytes)
+      bytes = bytes.to_s.b
+      return "must be #{PUBLIC_KEY_BYTES} bytes, got #{bytes.bytesize}" unless bytes.bytesize == PUBLIC_KEY_BYTES
+
+      point = decode_point(bytes)
+      return "is not a canonical encoding of an ed25519 point" if point.nil?
+      return "is a small-order ed25519 point" if small_order?(point)
+      return "is not in the ed25519 prime-order subgroup" unless in_prime_order_subgroup?(point)
+
+      nil
+    end
+
+    # nil when `bytes` is a well-formed signature (R canonical and not
+    # small-order, S reduced); otherwise a short reason. Says nothing about
+    # whether it verifies — that is #verify.
+    def signature_problem(bytes)
+      bytes = bytes.to_s.b
+      return "must be #{SIGNATURE_BYTES} bytes, got #{bytes.bytesize}" unless bytes.bytesize == SIGNATURE_BYTES
+
+      r = decode_point(bytes.byteslice(0, 32))
+      return "R is not a canonical encoding of an ed25519 point" if r.nil?
+      return "R is a small-order ed25519 point" if small_order?(r)
+      return "S is not reduced below the group order" unless le_int(bytes.byteslice(32, 32)) < L
+
+      nil
+    end
+
+    def valid_public_key?(bytes)
+      public_key_problem(bytes).nil?
+    end
+
+    # True only when the key and signature pass the checks above AND the
+    # verification equation holds. Never raises on malformed input.
+    def verify(public_key, signature, message)
+      public_key = public_key.to_s.b
+      signature = signature.to_s.b
+      return false if public_key_problem(public_key) || signature_problem(signature)
+
+      Ed25519::VerifyKey.new(public_key).verify(signature, message)
+      true
+    rescue Ed25519::VerifyError, ArgumentError
+      false
+    end
+
+    # RFC 8032 §5.1.3, strict: a y at or above p, a negative zero x, and a y
+    # with no x on the curve all return nil.
+    def decode_point(bytes)
+      bytes = bytes.to_s.b
+      return nil unless bytes.bytesize == PUBLIC_KEY_BYTES
+
+      int = le_int(bytes)
+      y = int & ((1 << 255) - 1)
+      sign = int >> 255
+      return nil if y >= P
+
+      u = (y * y - 1) % P
+      v = (D * y * y + 1) % P
+      x = (u * v.pow(3, P) * (u * v.pow(7, P)).pow((P - 5) / 8, P)) % P
+      vx2 = (v * x * x) % P
+      if vx2 == u
+        # x is a square root of u/v
+      elsif vx2 == (P - u) % P
+        x = (x * SQRT_M1) % P
+      else
+        return nil
+      end
+      return nil if x.zero? && sign == 1
+
+      x = P - x if (x & 1) != sign
+      [x, y, 1, (x * y) % P]
+    end
+
+    # RFC 8032 §5.1.2.
+    def encode_point(point)
+      x, y, z, = point
+      z_inv = z.pow(P - 2, P)
+      x = (x * z_inv) % P
+      y = (y * z_inv) % P
+      int = y | ((x & 1) << 255)
+      Array.new(32) { |i| (int >> (8 * i)) & 0xff }.pack("C*")
+    end
+
+    def identity?(point)
+      x, y, z, = point
+      (x % P).zero? && ((y - z) % P).zero?
+    end
+
+    # [8]P is the identity: P is one of the eight points of the torsion subgroup.
+    def small_order?(point)
+      identity?(double(double(double(point))))
+    end
+
+    # [L]P is the identity. The identity itself passes, so callers check
+    # small_order? first.
+    def in_prime_order_subgroup?(point)
+      identity?(scalar_mult(L, point))
+    end
+
+    # RFC 8032 §5.1.4 addition (complete for this curve).
+    def add(p1, p2)
+      x1, y1, z1, t1 = p1
+      x2, y2, z2, t2 = p2
+      a = ((y1 - x1) * (y2 - x2)) % P
+      b = ((y1 + x1) * (y2 + x2)) % P
+      c = (t1 * D2 % P * t2) % P
+      d = (z1 * 2 * z2) % P
+      e = b - a
+      f = d - c
+      g = d + c
+      h = b + a
+      [(e * f) % P, (g * h) % P, (f * g) % P, (e * h) % P]
+    end
+
+    def double(point)
+      x1, y1, z1, = point
+      a = (x1 * x1) % P
+      b = (y1 * y1) % P
+      c = (2 * z1 * z1) % P
+      h = a + b
+      e = h - (x1 + y1)**2
+      g = a - b
+      f = c + g
+      [(e * f) % P, (g * h) % P, (f * g) % P, (e * h) % P]
+    end
+
+    def scalar_mult(scalar, point)
+      result = IDENTITY
+      (scalar.bit_length - 1).downto(0) do |i|
+        result = double(result)
+        result = add(result, point) if scalar[i] == 1
+      end
+      result
+    end
+
+    def le_int(bytes)
+      bytes.unpack("C*").each_with_index.sum { |byte, i| byte << (8 * i) }
+    end
+  end
+end

data/lib/solana/keypair.rb

@@ -90,7 +90,10 @@ module Solana
         num = num * 58 + idx
       end
 
-      hex = num.to_s(16)
+      # A value of zero has NO body: every byte of it is a leading '1', counted
+      # below. `0.to_s(16)` is "0", which padded to "00" used to add a 33rd byte
+      # to the all-'1' System Program id.
+      hex = num.zero? ? "" : num.to_s(16)
       hex = "0" + hex if hex.length.odd?
 
       # Count leading '1's (zero bytes)

data/lib/solana/wire_message.rb

@@ -0,0 +1,223 @@
+require "base64"
+require "ed25519"
+require_relative "ed25519_strict"
+
+module Solana
+  # A decoded LEGACY wire transaction: the signature array plus the message it
+  # signs. Pure — no RPC, no keys.
+  #
+  # WHY A SERVER NEEDS TO READ ITS OWN WIRE BACK. A wallet does not return the
+  # bytes it was given. It re-serializes them, and on mainnet Phantom may insert
+  # Lighthouse assertion instructions (and their accounts) before signing, so a
+  # byte comparison against the prepared wire refuses legitimate signatures. A
+  # cosigning server has to decode what came back and judge it by meaning. This
+  # is the decoder turf-monster kept privately in Vault#parse_wire_message, and
+  # the walk Transaction.cosign_wire does inline.
+  #
+  # FAILS CLOSED. Truncation, trailing bytes, an out-of-range index and a
+  # versioned (v0+) message all raise MalformedError. Versioned messages are
+  # refused rather than half-read: this decoder cannot walk address-table
+  # lookups, and Solana::Transaction only ever builds legacy messages.
+  class WireMessage
+    class MalformedError < ArgumentError; end
+
+    EMPTY_SIGNATURE = ("\x00" * 64).b.freeze
+
+    attr_reader :signatures, :message_bytes, :num_required_signatures,
+                :num_readonly_signed, :num_readonly_unsigned,
+                :account_keys, :recent_blockhash, :instructions
+
+    def self.parse_base64(wire_base64)
+      raise MalformedError, "wire is empty" if wire_base64.nil? || wire_base64.to_s.empty?
+
+      parse(Base64.strict_decode64(wire_base64.to_s))
+    rescue ArgumentError => e
+      raise e if e.is_a?(MalformedError)
+
+      raise MalformedError, "wire is not strict base64: #{e.message}"
+    end
+
+    # Base58 is the wire format of the gem's own browser seam (walletOps hands
+    # `prepare` and `complete` base58), so a host can pass it straight through.
+    def self.parse_base58(wire_base58)
+      raise MalformedError, "wire is empty" if wire_base58.nil? || wire_base58.to_s.empty?
+
+      parse(Keypair.decode_base58(wire_base58.to_s))
+    rescue ArgumentError => e
+      raise e if e.is_a?(MalformedError)
+
+      raise MalformedError, "wire is not base58: #{e.message}"
+    end
+
+    # encoding: :base64 or :base58. Explicit, never sniffed: every base58
+    # string is also made of base64 characters, so guessing can misread one.
+    def self.parse_encoded(wire, encoding)
+      case encoding
+      when :base64 then parse_base64(wire)
+      when :base58 then parse_base58(wire)
+      else raise ArgumentError, "encoding must be :base64 or :base58, got #{encoding.inspect}"
+      end
+    end
+
+    # `wire` is the binary wire transaction: compact-u16 signature count, the
+    # 64-byte signatures, then the message.
+    def self.parse(wire)
+      new(wire.to_s.b)
+    end
+
+    def initialize(wire)
+      @wire = wire
+      cursor = 0
+
+      sig_count, cursor = read_compact_u16(cursor)
+      malformed!("zero signature slots") if sig_count.zero?
+      need!(cursor + (sig_count * 64), "signature array")
+      @signatures = Array.new(sig_count) { |i| @wire.byteslice(cursor + (i * 64), 64) }
+      message_start = cursor + (sig_count * 64)
+      @message_bytes = @wire.byteslice(message_start, @wire.bytesize - message_start)
+
+      need!(message_start + 3, "message header")
+      first = @wire.getbyte(message_start)
+      malformed!("versioned (v0+) message is not supported") if (first & 0x80) != 0
+      @num_required_signatures = first
+      @num_readonly_signed = @wire.getbyte(message_start + 1)
+      @num_readonly_unsigned = @wire.getbyte(message_start + 2)
+
+      unless @num_required_signatures == sig_count
+        malformed!("header requires #{@num_required_signatures} signature(s) but the wire carries #{sig_count} slot(s)")
+      end
+
+      cursor = message_start + 3
+      account_count, cursor = read_compact_u16(cursor)
+      need!(cursor + (account_count * 32), "account keys")
+      @account_keys = Array.new(account_count) { |i| @wire.byteslice(cursor + (i * 32), 32) }
+      cursor += account_count * 32
+      malformed!("#{account_count} account key(s) cannot cover #{@num_required_signatures} signer(s)") if account_count < @num_required_signatures
+      # The runtime refuses a key loaded twice. Refusing it here too means a
+      # signer check and an instruction check can never read two different
+      # entries for the same key.
+      malformed!("duplicate account key in the account list") unless @account_keys.uniq.size == account_count
+      if @num_readonly_signed > @num_required_signatures || @num_readonly_unsigned > (account_count - @num_required_signatures)
+        malformed!("readonly counts exceed the account list")
+      end
+
+      need!(cursor + 32, "recent blockhash")
+      @recent_blockhash = @wire.byteslice(cursor, 32)
+      cursor += 32
+
+      ix_count, cursor = read_compact_u16(cursor)
+      @instructions = Array.new(ix_count) do |n|
+        need!(cursor + 1, "instruction #{n} program index")
+        program_id_index = @wire.getbyte(cursor)
+        cursor += 1
+        malformed!("instruction #{n} program index #{program_id_index} is out of range") if program_id_index >= account_count
+
+        accounts_len, cursor = read_compact_u16(cursor)
+        need!(cursor + accounts_len, "instruction #{n} account indices")
+        account_indices = @wire.byteslice(cursor, accounts_len).bytes
+        cursor += accounts_len
+        bad = account_indices.find { |idx| idx >= account_count }
+        malformed!("instruction #{n} account index #{bad} is out of range") if bad
+
+        data_len, cursor = read_compact_u16(cursor)
+        need!(cursor + data_len, "instruction #{n} data")
+        data = @wire.byteslice(cursor, data_len)
+        cursor += data_len
+
+        {
+          program_id_index: program_id_index,
+          program_id: @account_keys[program_id_index],
+          account_indices: account_indices,
+          accounts: account_indices.map { |idx| @account_keys[idx] },
+          data: data
+        }
+      end
+
+      malformed!("#{@wire.bytesize - cursor} trailing byte(s) after the last instruction") unless cursor == @wire.bytesize
+    end
+
+    def to_bytes
+      @wire.dup
+    end
+
+    def to_base64
+      Base64.strict_encode64(@wire)
+    end
+
+    def to_base58
+      Keypair.encode_base58(@wire)
+    end
+
+    # The fee payer: account 0, always the first signer.
+    def fee_payer
+      @account_keys[0]
+    end
+
+    def signer_keys
+      @account_keys.first(@num_required_signatures)
+    end
+
+    def signer?(key_or_index)
+      index = key_or_index.is_a?(Integer) ? key_or_index : @account_keys.index(key_or_index.to_s.b)
+      !index.nil? && index < @num_required_signatures
+    end
+
+    # Standard legacy layout: writable signers, readonly signers, writable
+    # non-signers, readonly non-signers.
+    def writable?(key_or_index)
+      index = key_or_index.is_a?(Integer) ? key_or_index : @account_keys.index(key_or_index.to_s.b)
+      return false if index.nil? || index >= @account_keys.length
+
+      if index < @num_required_signatures
+        index < (@num_required_signatures - @num_readonly_signed)
+      else
+        (index - @num_required_signatures) < (@account_keys.length - @num_required_signatures - @num_readonly_unsigned)
+      end
+    end
+
+    def signature_slot_empty?(index)
+      @signatures.fetch(index) == EMPTY_SIGNATURE
+    end
+
+    # True when slot `index` holds a valid ed25519 signature, by the key in that
+    # signer slot, over these exact message bytes. An empty slot is not valid.
+    # Strict (Solana::Ed25519Strict): a slot the cluster's own signature check
+    # would refuse — a small-order key or R, an unreduced S — is not valid here
+    # either, so a completer refuses it before the fee payer signs.
+    def signature_valid?(index)
+      return false if index >= @num_required_signatures || signature_slot_empty?(index)
+
+      Ed25519Strict.verify(@account_keys[index], @signatures[index], @message_bytes)
+    end
+
+    # The transaction's identity on chain: its FIRST signature (the fee payer's),
+    # base58. Knowable before any broadcast, which is what lets a caller record
+    # it before the bytes leave. Raises when that slot is still empty, because an
+    # all-zero "signature" names nothing.
+    def signature
+      raise MalformedError, "the fee-payer slot is empty, so this wire has no signature yet" if signature_slot_empty?(0)
+
+      Keypair.encode_base58(@signatures[0])
+    end
+
+    def recent_blockhash_base58
+      Keypair.encode_base58(@recent_blockhash)
+    end
+
+    private
+
+    def read_compact_u16(offset)
+      Transaction.read_compact_u16(@wire, offset)
+    rescue RuntimeError => e
+      malformed!(e.message)
+    end
+
+    def need!(end_offset, what)
+      malformed!("truncated #{what}") if @wire.bytesize < end_offset
+    end
+
+    def malformed!(reason)
+      raise MalformedError, "malformed wire: #{reason}"
+    end
+  end
+end

data/lib/solana_studio/engine.rb

@@ -34,6 +34,7 @@ module SolanaStudio
         solana_studio/redirect_provider.js
         solana_studio/wallet_journal.js
         solana_studio/wallet_ops.js
+        solana_studio/wallet_identity.js
       ]
     end
   end

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.11.0"
+  VERSION = "0.12.0"
 end

data/lib/solana_studio.rb

@@ -5,8 +5,14 @@ require_relative "solana/transaction"
 require_relative "solana/spl_token"
 require_relative "solana/system_program"
 require_relative "solana/nonce_account"
+require_relative "solana/ed25519_strict"
 require_relative "solana/auth_verifier"
 require_relative "solana/network"
+require_relative "solana/compute_budget"
+require_relative "solana/wire_message"
+# Gasless, cosigned transactions: the house pays the fee, the wallet signs, the
+# server verifies and fills its slot. Keyless — the caller passes the fee payer.
+require_relative "solana/cosign"
 
 # 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