solana-studio 0.10.0 → 0.12.0

data/lib/solana/cosign/builder.rb

@@ -0,0 +1,159 @@
+module Solana
+  module Cosign
+    # A built transaction, ready for its cosigners, with the deadline attached.
+    #
+    #   wire_base64              the wire to hand the wallet(s); #wire_base58 too
+    #   blockhash                the recent blockhash it is anchored on (base58)
+    #   last_valid_block_height  once the cluster's block height passes this, the
+    #                            transaction can never land — rebuild BEFORE
+    #                            prompting if the remainder is short
+    #   commitment               what the blockhash was fetched at; send at the same
+    #   fee_payer                base58
+    #   signers                  base58, in signature-slot order (fee payer first)
+    #   expectation              what Completer judges the returned wire against
+    #
+    # Store wire_base64 and last_valid_block_height server-side if the signature
+    # comes back in a later request; Expectation.from_wire rebuilds the rest.
+    Prepared = Struct.new(:wire_base64, :blockhash, :last_valid_block_height, :commitment,
+                          :fee_payer, :signers, :expectation, keyword_init: true) do
+      # The same wire in base58, the format SolanaStudio.walletOps `prepare`
+      # returns to the browser — no conversion in host JavaScript.
+      def wire_base58
+        Keypair.encode_base58(Base64.strict_decode64(wire_base64))
+      end
+    end
+
+    # Builds a transaction the SERVER pays for.
+    #
+    # The fee payer is account 0 and every named cosigner gets an empty slot. By
+    # default the fee payer's slot is empty too (WALLET-FIRST): the wallet signs
+    # an unsigned transaction, and the server fills its own slot afterwards. That
+    # is the order Phantom does not flag. When the server signs first and the
+    # wallet second, Phantom's Lighthouse heuristics can warn "could be
+    # malicious", which is why turf-monster flipped its entries on 2026-06-05.
+    #
+    # `presign: true` signs the fee payer's slot at build time instead. It exists
+    # for flows that still sign server-first (several N-signer operator flows do)
+    # so they can adopt this builder before they flip; prefer the default. A
+    # presigned wire that a wallet modifies no longer carries a valid fee-payer
+    # signature, and Completer refuses it.
+    class Builder
+      def initialize(client:, fee_payer:)
+        @client = client
+        @fee_payer = fee_payer
+        @fee_payer_bytes = Cosign.key_bytes(fee_payer)
+      end
+
+      # instructions: [{ program_id:, accounts: [{ pubkey:, is_signer:, is_writable: }], data: }]
+      #   — the hashes Transaction#add_instruction takes (SplToken and
+      #   SystemProgram encoders return this shape). Keys may be base58, raw
+      #   bytes, or a Keypair.
+      # cosigners: public keys whose slots stay empty for the wallet(s).
+      # compute_unit_price: micro-lamports per CU (a priority fee). A fee-less
+      #   transaction lands on an idle devnet and is dropped by a loaded mainnet.
+      # compute_unit_limit: CU cap; the fee is price x limit.
+      # commitment: the blockhash is fetched at this commitment and the expectation
+      #   carries it, so Completer preflights at the same one.
+      def build(instructions:, cosigners:, compute_unit_price: nil, compute_unit_limit: nil,
+                commitment: DEFAULT_COMMITMENT, presign: false, fee_margin: DEFAULT_FEE_MARGIN,
+                extra_programs: DEFAULT_EXTRA_PROGRAMS)
+        if presign && !(@fee_payer.respond_to?(:sign) && @fee_payer.respond_to?(:public_key_bytes))
+          raise ArgumentError, "presign: true needs the fee payer as a Solana::Keypair, not a bare public key"
+        end
+
+        cosigner_bytes = Array(cosigners).map { |k| Cosign.key_bytes(k) }
+        raise ArgumentError, "cosigners must be distinct" unless cosigner_bytes.uniq.size == cosigner_bytes.size
+        raise ArgumentError, "the fee payer cannot also be a cosigner" if cosigner_bytes.include?(@fee_payer_bytes)
+
+        built = Array(instructions).map { |ix| normalize_instruction(ix) }
+        raise ArgumentError, "at least one instruction is required" if built.empty?
+
+        assert_signers_named!(built, cosigner_bytes)
+
+        latest = @client.latest_blockhash(commitment: commitment)
+
+        tx = Transaction.new
+        tx.set_recent_blockhash(latest.blockhash)
+        tx.add_signer(@fee_payer) if presign
+        tx.add_instruction(**ComputeBudget.set_compute_unit_price(compute_unit_price)) unless compute_unit_price.nil?
+        tx.add_instruction(**ComputeBudget.set_compute_unit_limit(compute_unit_limit)) unless compute_unit_limit.nil?
+        built.each { |ix| tx.add_instruction(**ix) }
+
+        # Keyless build: Transaction#serialize_partial takes the FIRST additional
+        # signer as the fee payer when it holds no local signer.
+        additional = presign ? cosigner_bytes : [@fee_payer_bytes, *cosigner_bytes]
+        wire = tx.serialize_partial(additional_signers: additional)
+
+        message = WireMessage.parse(wire)
+        unless message.fee_payer == @fee_payer_bytes
+          raise "Cosign::Builder invariant: account 0 is #{Cosign.base58(message.fee_payer)}, not the fee payer"
+        end
+
+        max_price, max_fee = Cosign.fee_caps(compute_unit_price: compute_unit_price,
+                                             compute_unit_limit: compute_unit_limit, margin: fee_margin)
+        expectation = Expectation.new(
+          fee_payer: @fee_payer_bytes,
+          cosigners: cosigner_bytes,
+          instructions: built,
+          last_valid_block_height: latest.last_valid_block_height,
+          commitment: commitment,
+          max_compute_unit_price: max_price,
+          max_priority_fee_micro_lamports: max_fee,
+          extra_programs: extra_programs
+        )
+
+        Prepared.new(
+          wire_base64: message.to_base64,
+          blockhash: latest.blockhash,
+          last_valid_block_height: latest.last_valid_block_height,
+          commitment: commitment,
+          fee_payer: Cosign.base58(@fee_payer_bytes),
+          signers: message.signer_keys.map { |k| Cosign.base58(k) },
+          expectation: expectation
+        )
+      end
+
+      private
+
+      # Every key normalized to raw bytes BEFORE it reaches Transaction, whose
+      # own normalizer reads any 32-byte string as raw — a 32-character base58
+      # address included.
+      def normalize_instruction(ix)
+        raise ArgumentError, "instruction must be a Hash with program_id:, accounts:, data:" unless ix.is_a?(Hash)
+
+        program_id = Cosign.key_bytes(ix.fetch(:program_id))
+        if program_id == ComputeBudget::PROGRAM_ID.b
+          raise ArgumentError, "pass compute_unit_price:/compute_unit_limit: instead of a ComputeBudget instruction"
+        end
+
+        data = ix.fetch(:data)
+        {
+          program_id: program_id,
+          accounts: Array(ix.fetch(:accounts)).map do |meta|
+            raise ArgumentError, "account metas must be Hashes with pubkey:" unless meta.is_a?(Hash)
+
+            { pubkey: Cosign.key_bytes(meta.fetch(:pubkey)),
+              is_signer: meta[:is_signer] ? true : false,
+              is_writable: meta[:is_writable] ? true : false }
+          end,
+          data: data.is_a?(Array) ? data.pack("C*") : data.to_s.b
+        }
+      end
+
+      # A signer no one will sign for makes a transaction that can never land;
+      # say which key, here, instead of a signer-count mismatch at serialize.
+      def assert_signers_named!(built, cosigner_bytes)
+        named = [@fee_payer_bytes, *cosigner_bytes]
+        built.each_with_index do |ix, n|
+          ix[:accounts].each do |meta|
+            next unless meta[:is_signer]
+            next if named.include?(meta[:pubkey])
+
+            raise ArgumentError, "instruction #{n} requires a signature from #{Cosign.base58(meta[:pubkey])}, " \
+                                 "which is neither the fee payer nor a named cosigner"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solana/cosign/completer.rb

@@ -0,0 +1,217 @@
+module Solana
+  module Cosign
+    # Takes a wallet-signed wire back, and finishes it — or refuses it.
+    #
+    # Three levels, so a flow can stop where its broadcast lives:
+    #
+    #   #verify!   judge the wire against the Expectation. No key, no RPC.
+    #   #cosign    verify, check every cosigner signature, fill the fee payer's
+    #              slot (Transaction.cosign_wire). No RPC. For a flow whose
+    #              browser broadcasts.
+    #   #complete  cosign, check the deadline, simulate, record, send, confirm.
+    #
+    # THE FEE PAYER SIGNS LAST, AND ONLY WHAT PASSED. Every check that can refuse
+    # the wire runs before the fee payer's key is used, so a refused wire leaves
+    # nothing behind that could be broadcast.
+    class Completer
+      Cosigned = Struct.new(:wire_base64, :signature, :message, keyword_init: true) do
+        def wire_base58
+          message.to_base58
+        end
+      end
+      Completed = Struct.new(:signature, :wire_base64, :confirmation_status, keyword_init: true)
+
+      COMMITMENT_RANK = { "processed" => 0, "confirmed" => 1, "finalized" => 2 }.freeze
+
+      # fee_payer: the Solana::Keypair whose slot this server fills. Passed in;
+      # this class never loads, stores or derives a key.
+      # sleeper / clock / poll_interval: injectable so the confirmation loop can be
+      # tested without waiting on a real clock.
+      def initialize(client:, fee_payer:, poll_interval: 1,
+                     sleeper: ->(seconds) { sleep(seconds) },
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        unless fee_payer.respond_to?(:sign) && fee_payer.respond_to?(:public_key_bytes)
+          raise ArgumentError, "fee_payer must be a Solana::Keypair — the completer signs with it"
+        end
+
+        @client = client
+        @fee_payer = fee_payer
+        @fee_payer_bytes = fee_payer.public_key_bytes.b
+        @poll_interval = poll_interval
+        @sleeper = sleeper
+        @clock = clock
+      end
+
+      # signed_wire: the wallet-returned wire, base64 by default; pass
+      # `encoding: :base58` for what SolanaStudio.walletOps hands `complete`.
+      # Returns the decoded WireMessage, or raises WireRejected.
+      def verify!(signed_wire, expectation:, encoding: :base64)
+        unless expectation.fee_payer == @fee_payer_bytes
+          # A wiring mistake in the caller, not something the wire did.
+          raise ArgumentError, "the expectation's fee payer #{Cosign.base58(expectation.fee_payer)} " \
+                               "is not this completer's key #{Cosign.base58(@fee_payer_bytes)}"
+        end
+
+        message =
+          begin
+            WireMessage.parse_encoded(signed_wire, encoding)
+          rescue WireMessage::MalformedError => e
+            raise WireRejected.new(:unparseable_wire, e.message)
+          end
+        expectation.verify!(message)
+        message
+      end
+
+      # Returns Cosigned(wire_base64, signature, message). The signature is the
+      # transaction's id, known BEFORE anything is sent: record it first.
+      def cosign(signed_wire, expectation:, encoding: :base64)
+        message = verify!(signed_wire, expectation: expectation, encoding: encoding)
+
+        # Every cosigner slot must already hold a valid signature over THESE
+        # bytes. An empty or forged slot is refused here, before the fee payer
+        # signs — rather than by the node, after the fee payer has.
+        (1...message.num_required_signatures).each do |slot|
+          signer = Cosign.base58(message.account_keys[slot])
+          raise WireRejected.new(:signature_missing, "slot #{slot} (#{signer}) is unsigned") if message.signature_slot_empty?(slot)
+          raise WireRejected.new(:signature_invalid, "slot #{slot} (#{signer}) does not verify") unless message.signature_valid?(slot)
+        end
+
+        wire =
+          if message.signature_slot_empty?(0)
+            Transaction.cosign_wire(message.to_bytes, signer: @fee_payer, require_complete: true)
+          elsif message.signature_valid?(0)
+            message.to_bytes # presigned at build, and the message is unchanged since
+          else
+            raise WireRejected.new(:fee_payer_signature_invalid,
+                                   "slot 0 holds a signature that does not verify over this message — " \
+                                   "the transaction changed after the fee payer signed it")
+          end
+
+        signed = WireMessage.parse(wire)
+        Cosigned.new(wire_base64: signed.to_base64, signature: signed.signature, message: signed)
+      end
+
+      # Cosign, then put it on chain.
+      #
+      # before_send: called with the signature after every provable check and
+      #   before the send. Persist it there. If it raises, nothing is sent and the
+      #   exception propagates unchanged.
+      # simulate: run simulateTransaction first (sigVerify false — the signatures
+      #   were verified locally; replaceRecentBlockhash true — the deadline check
+      #   judges the blockhash, the simulation judges the program).
+      # confirm_timeout: seconds to wait for the expectation's commitment; nil
+      #   returns right after the send with confirmation_status nil.
+      def complete(signed_wire, expectation:, encoding: :base64, simulate: true, before_send: nil, confirm_timeout: 30)
+        cosigned = cosign(signed_wire, expectation: expectation, encoding: encoding)
+        signature = cosigned.signature
+        wire_base64 = cosigned.wire_base64
+        commitment = expectation.commitment
+
+        assert_not_expired!(expectation, signature)
+        run_simulation!(wire_base64, commitment, signature) if simulate
+
+        before_send&.call(signature)
+
+        returned =
+          begin
+            @client.send_transaction(wire_base64, preflight_commitment: commitment)
+          rescue StandardError => e
+            if blockhash_not_found?(e)
+              raise BroadcastExpired.new("the node no longer knows this blockhash: #{e.message}", signature: signature)
+            end
+
+            raise BroadcastFailed.new("send failed — reconcile #{signature} before rebuilding: #{e.message}", signature: signature)
+          end
+
+        if returned && returned != signature
+          raise BroadcastFailed.new("the node returned #{returned} for a wire whose own first signature is #{signature} — " \
+                                    "reconcile both on chain before acting", signature: signature)
+        end
+
+        return Completed.new(signature: signature, wire_base64: wire_base64, confirmation_status: nil) if confirm_timeout.nil?
+
+        status = await_confirmation!(signature, expectation, confirm_timeout)
+        Completed.new(signature: signature, wire_base64: wire_base64, confirmation_status: status)
+      end
+
+      private
+
+      def assert_not_expired!(expectation, signature)
+        limit = expectation.last_valid_block_height
+        return if limit.nil?
+
+        height =
+          begin
+            @client.get_block_height(commitment: expectation.commitment)
+          rescue StandardError => e
+            raise PreflightRejected.new("could not read the block height to check the deadline: #{e.message}", signature: signature)
+          end
+        return if height <= limit
+
+        raise BlockhashExpired.new("blockhash expired: block height #{height} is past last valid height #{limit}",
+                                   signature: signature, block_height: height, last_valid_block_height: limit)
+      end
+
+      def run_simulation!(wire_base64, commitment, signature)
+        result =
+          begin
+            @client.simulate_transaction(wire_base64, sig_verify: false, replace_recent_blockhash: true, commitment: commitment)
+          rescue StandardError => e
+            raise PreflightRejected.new("simulation could not be run: #{e.message}", signature: signature)
+          end
+        return unless result && result["err"]
+
+        logs = Array(result["logs"])
+        raise SimulationFailed.new("simulation failed: #{result['err'].inspect}", signature: signature,
+                                   err: result["err"], logs: logs)
+      end
+
+      # Polls until the expectation's commitment is reached. A status read that
+      # fails is not a verdict; the loop keeps asking until the deadline.
+      def await_confirmation!(signature, expectation, timeout)
+        wanted = COMMITMENT_RANK.fetch(expectation.commitment, COMMITMENT_RANK["confirmed"])
+        deadline = @clock.call + timeout
+
+        loop do
+          @sleeper.call(@poll_interval)
+          status = read_status(signature)
+
+          if status
+            if status["err"]
+              raise TransactionFailed.new("landed and failed: #{status['err'].inspect}", signature: signature, err: status["err"])
+            end
+
+            reached = COMMITMENT_RANK[status["confirmationStatus"].to_s]
+            return status["confirmationStatus"] if reached && reached >= wanted
+          elsif chain_says_expired?(expectation)
+            raise BroadcastExpired.new("no status for #{signature} and the block height is past its last valid height",
+                                       signature: signature)
+          end
+
+          if @clock.call > deadline
+            raise BroadcastFailed.new("confirmation timed out after #{timeout}s — reconcile #{signature} before rebuilding",
+                                      signature: signature)
+          end
+        end
+      end
+
+      def read_status(signature)
+        @client.confirm_transaction(signature)&.dig("value", 0)
+      rescue StandardError
+        nil
+      end
+
+      def chain_says_expired?(expectation)
+        return false if expectation.last_valid_block_height.nil?
+
+        @client.get_block_height(commitment: expectation.commitment) > expectation.last_valid_block_height
+      rescue StandardError
+        false
+      end
+
+      def blockhash_not_found?(error)
+        error.message.to_s.match?(/blockhash not found/i)
+      end
+    end
+  end
+end

data/lib/solana/cosign/expectation.rb

@@ -0,0 +1,272 @@
+module Solana
+  module Cosign
+    # What the server built, in the form a returned wire is judged against.
+    #
+    # A wallet re-encodes the wire and may insert its own protection
+    # instructions, so the judgement is by MEANING, never by bytes:
+    #
+    #   1. Account 0 — the fee payer — is this server's fee payer, and writable.
+    #   2. The signer set is EXACTLY the fee payer plus the named cosigners. No
+    #      extra signer (an attacker's own key), none missing.
+    #   3. Remove ComputeBudget instructions and instructions of an admitted
+    #      extra program (Lighthouse by default). What remains must EQUAL the
+    #      built instruction list: same programs, same ordered account keys, same
+    #      data, same order. A generic library cannot know which of an app's
+    #      accounts matter, so every one of them does. A System transfer from the
+    #      fee payer, a nonce advance, a duplicated or swapped instruction, an
+    #      altered amount — each fails here.
+    #   4. ComputeBudget is READ, never waved through: only SetComputeUnitLimit
+    #      and SetComputeUnitPrice, once each, and the fee they make the fee payer
+    #      pay is capped (Cosign::DEFAULT_FEE_MARGIN).
+    #   5. An admitted extra program is READ too, never waved through. A
+    #      Lighthouse instruction passes only when its first data byte is an
+    #      assertion variant (Cosign::LIGHTHOUSE_ASSERTIONS). MemoryWrite, which
+    #      makes a signer — the fee payer included — fund an account, MemoryClose,
+    #      empty data and an unknown variant are refused. Its accounts are not
+    #      compared: an assertion takes no payer and writes nothing, so what it
+    #      names cannot move funds, and Phantom's assertions name the fee payer.
+    #   6. Optionally, the recent blockhash is the one built on (`blockhash:`).
+    #      Off by default: turf-monster's production guards never pinned it, and
+    #      whether any wallet rewrites it on mainnet has not been measured. Pin it
+    #      when last_valid_block_height must describe the returned wire exactly.
+    #
+    # Writable flags other than the fee payer's are not compared: they cannot
+    # move the fee payer's funds, and a wallet re-encoding them is not an attack
+    # on the house.
+    class Expectation
+      # The only programs an app may admit as "extra", each with the rule that
+      # reads its instructions. An admitted instruction skips the comparison in
+      # rule 3, so something must prove it cannot move the fee payer's funds,
+      # and a program id alone proves nothing: Lighthouse carries assertions
+      # AND a MemoryWrite that spends its payer's lamports. A program with no
+      # rule here cannot be admitted.
+      EXTRA_PROGRAM_RULES = { LIGHTHOUSE_PROGRAM_ID.b => :admit_lighthouse! }.freeze
+
+      attr_reader :fee_payer, :cosigners, :instructions, :blockhash, :last_valid_block_height,
+                  :commitment, :max_compute_unit_price, :max_priority_fee_micro_lamports, :extra_programs
+
+      # instructions: [{ program_id:, accounts: [meta Hash or key], data: }] — the
+      # same hashes Transaction#add_instruction takes. Account metas may carry
+      # is_signer / is_writable; only the ordered keys are compared.
+      def initialize(fee_payer:, cosigners:, instructions:, max_compute_unit_price:, max_priority_fee_micro_lamports:,
+                     blockhash: nil, last_valid_block_height: nil, commitment: DEFAULT_COMMITMENT,
+                     extra_programs: DEFAULT_EXTRA_PROGRAMS)
+        @fee_payer = Cosign.key_bytes(fee_payer)
+        @cosigners = Array(cosigners).map { |k| Cosign.key_bytes(k) }
+        raise ArgumentError, "cosigners must be distinct" unless @cosigners.uniq.size == @cosigners.size
+        raise ArgumentError, "the fee payer cannot also be a cosigner" if @cosigners.include?(@fee_payer)
+
+        @extra_programs = Array(extra_programs).map { |k| Cosign.key_bytes(k) }.uniq
+        unruled = @extra_programs.reject { |k| EXTRA_PROGRAM_RULES.key?(k) }
+        unless unruled.empty?
+          raise ArgumentError, "cannot admit #{unruled.map { |k| Cosign.base58(k) }.join(', ')} as an extra program: " \
+                               "no rule reads its instructions, so nothing proves they cannot move the fee payer's " \
+                               "funds (admissible: #{EXTRA_PROGRAM_RULES.keys.map { |k| Cosign.base58(k) }.join(', ')})"
+        end
+
+        @instructions = Array(instructions).map { |ix| normalize_instruction(ix) }
+        raise ArgumentError, "at least one instruction is required" if @instructions.empty?
+
+        @instructions.each do |ix|
+          if ix[:program_id] == ComputeBudget::PROGRAM_ID.b
+            raise ArgumentError, "ComputeBudget is priced by the caps, not listed as an instruction"
+          end
+          if @extra_programs.include?(ix[:program_id])
+            raise ArgumentError, "#{Cosign.base58(ix[:program_id])} is both a built instruction and an admitted extra program"
+          end
+        end
+
+        @blockhash = blockhash.nil? ? nil : Cosign.key_bytes(blockhash)
+        @last_valid_block_height = last_valid_block_height.nil? ? nil : Integer(last_valid_block_height)
+        @commitment = commitment.to_s
+        @max_compute_unit_price = non_negative!(max_compute_unit_price, "max_compute_unit_price")
+        @max_priority_fee_micro_lamports = non_negative!(max_priority_fee_micro_lamports, "max_priority_fee_micro_lamports")
+      end
+
+      # Rebuild the expectation from a wire THIS SERVER BUILT and kept in its own
+      # storage (a database row, never a request parameter), for the request that
+      # receives the wallet's signature. The built wire's ComputeBudget pair
+      # derives the fee caps; its signer slots after account 0 are the cosigners.
+      #
+      # A wire from the client is not a source of expectations — it is the thing
+      # being judged. Passing one here judges the wire against itself.
+      def self.from_wire(built_wire, fee_payer:, last_valid_block_height: nil, commitment: DEFAULT_COMMITMENT,
+                         pin_blockhash: false, fee_margin: DEFAULT_FEE_MARGIN, extra_programs: DEFAULT_EXTRA_PROGRAMS,
+                         encoding: :base64)
+        message = WireMessage.parse_encoded(built_wire, encoding)
+        payer = Cosign.key_bytes(fee_payer)
+        unless message.fee_payer == payer
+          raise ArgumentError, "the built wire's fee payer is #{Cosign.base58(message.fee_payer)}, not #{Cosign.base58(payer)}"
+        end
+
+        budget = {}
+        instructions = []
+        message.instructions.each do |ix|
+          if ix[:program_id] == ComputeBudget::PROGRAM_ID.b
+            kind, value = ComputeBudget.parse(ix[:data])
+            raise ArgumentError, "the built wire repeats ComputeBudget #{kind}" if budget.key?(kind)
+
+            budget[kind] = value
+          else
+            instructions << { program_id: ix[:program_id], accounts: ix[:accounts], data: ix[:data] }
+          end
+        end
+
+        max_price, max_fee = Cosign.fee_caps(compute_unit_price: budget[:price], compute_unit_limit: budget[:limit],
+                                             margin: fee_margin)
+        new(
+          fee_payer: payer,
+          cosigners: message.signer_keys.drop(1),
+          instructions: instructions,
+          blockhash: pin_blockhash ? message.recent_blockhash : nil,
+          last_valid_block_height: last_valid_block_height,
+          commitment: commitment,
+          max_compute_unit_price: max_price,
+          max_priority_fee_micro_lamports: max_fee,
+          extra_programs: extra_programs
+        )
+      end
+
+      # The expectation with the recent blockhash pinned. See rule 6 above.
+      def pinned_to(blockhash)
+        dup.tap { |copy| copy.instance_variable_set(:@blockhash, Cosign.key_bytes(blockhash)) }
+      end
+
+      def signer_set
+        [@fee_payer, *@cosigners]
+      end
+
+      # Judge a decoded wire. Returns true, or raises WireRejected naming the
+      # first rule it breaks.
+      def verify!(message)
+        unless message.fee_payer == @fee_payer
+          reject!(:fee_payer_mismatch, "account 0 is #{Cosign.base58(message.fee_payer)}, expected #{Cosign.base58(@fee_payer)}")
+        end
+        reject!(:fee_payer_not_writable, "account 0 is not writable") unless message.writable?(0)
+
+        actual_signers = message.signer_keys
+        extra = actual_signers - signer_set
+        missing = signer_set - actual_signers
+        unless extra.empty? && missing.empty?
+          reject!(:signer_set_mismatch,
+                  "unexpected signer(s) [#{extra.map { |k| Cosign.base58(k) }.join(', ')}], " \
+                  "missing signer(s) [#{missing.map { |k| Cosign.base58(k) }.join(', ')}]")
+        end
+
+        if @blockhash && message.recent_blockhash != @blockhash
+          reject!(:blockhash_mismatch, "wire anchors on #{message.recent_blockhash_base58}, built on #{Cosign.base58(@blockhash)}")
+        end
+
+        budget = {}
+        observed = []
+        message.instructions.each_with_index do |ix, index|
+          if ix[:program_id] == ComputeBudget::PROGRAM_ID.b
+            read_compute_budget!(ix, index, budget)
+          elsif @extra_programs.include?(ix[:program_id])
+            send(EXTRA_PROGRAM_RULES.fetch(ix[:program_id]), ix, index)
+          else
+            observed << ix.merge(index: index)
+          end
+        end
+
+        compare_instructions!(observed)
+        assert_fee_capped!(budget)
+        true
+      end
+
+      private
+
+      def normalize_instruction(ix)
+        raise ArgumentError, "instruction must be a Hash with program_id:, accounts:, data:" unless ix.is_a?(Hash)
+
+        data = ix.fetch(:data)
+        {
+          program_id: Cosign.key_bytes(ix.fetch(:program_id)),
+          accounts: Array(ix.fetch(:accounts)).map { |a| Cosign.key_bytes(a.is_a?(Hash) ? a.fetch(:pubkey) : a) },
+          data: data.is_a?(Array) ? data.pack("C*") : data.to_s.b
+        }
+      end
+
+      def non_negative!(value, name)
+        value = Integer(value)
+        raise ArgumentError, "#{name} must be >= 0, got #{value}" if value.negative?
+
+        value
+      end
+
+      def read_compute_budget!(ix, index, budget)
+        kind, value =
+          begin
+            ComputeBudget.parse(ix[:data])
+          rescue ArgumentError => e
+            reject!(:compute_budget_not_allowed, "ix #{index}: #{e.message}")
+          end
+        reject!(:compute_budget_duplicate, "ix #{index} repeats #{kind}") if budget.key?(kind)
+        budget[kind] = value
+      end
+
+      # Rule 5 for Lighthouse: see Cosign::LIGHTHOUSE_PROGRAM_ID for the variants
+      # and the mainnet evidence behind this list.
+      def admit_lighthouse!(ix, index)
+        variant = ix[:data].getbyte(0)
+        case variant
+        when nil
+          reject!(:lighthouse_empty_data, "ix #{index} carries no instruction variant")
+        when LIGHTHOUSE_MEMORY_WRITE
+          reject!(:lighthouse_memory_write,
+                  "ix #{index} is Lighthouse MemoryWrite (0): a signer would fund a memory account")
+        when LIGHTHOUSE_MEMORY_CLOSE
+          reject!(:lighthouse_memory_close,
+                  "ix #{index} is Lighthouse MemoryClose (1): a memory-account operation, not an assertion")
+        when LIGHTHOUSE_ASSERTIONS
+          nil
+        else
+          reject!(:lighthouse_unknown_disc, "ix #{index} variant #{variant} is not a Lighthouse assertion")
+        end
+      end
+
+      def compare_instructions!(observed)
+        @instructions.each_with_index do |want, n|
+          got = observed[n]
+          reject!(:instruction_missing, "built instruction #{n} (#{Cosign.base58(want[:program_id])}) is absent") if got.nil?
+
+          if got[:program_id] != want[:program_id]
+            reject!(:unexpected_instruction,
+                    "ix #{got[:index]} program #{program_label(got[:program_id])} where built instruction #{n} " \
+                    "expects #{Cosign.base58(want[:program_id])}")
+          end
+          reject!(:instruction_data_mismatch, "ix #{got[:index]} data differs from built instruction #{n}") if got[:data] != want[:data]
+          if got[:accounts] != want[:accounts]
+            reject!(:instruction_accounts_mismatch,
+                    "ix #{got[:index]} accounts [#{got[:accounts].map { |k| Cosign.base58(k) }.join(', ')}] differ from built instruction #{n}")
+          end
+        end
+
+        return if observed.size == @instructions.size
+
+        extra = observed[@instructions.size]
+        reject!(:unexpected_instruction, "ix #{extra[:index]} program #{program_label(extra[:program_id])} was not built")
+      end
+
+      def assert_fee_capped!(budget)
+        price = budget.fetch(:price, 0)
+        if price > @max_compute_unit_price
+          reject!(:compute_unit_price_over_cap, "#{price} > #{@max_compute_unit_price} micro-lamports/CU")
+        end
+
+        fee = ComputeBudget.priority_fee_micro_lamports(price: price, limit: budget[:limit])
+        return if fee <= @max_priority_fee_micro_lamports
+
+        reject!(:priority_fee_over_cap, "#{fee} > #{@max_priority_fee_micro_lamports} micro-lamports")
+      end
+
+      def program_label(program_id)
+        program_id == Transaction::SYSTEM_PROGRAM_ID.b ? "System" : Cosign.base58(program_id)
+      end
+
+      def reject!(reason, detail)
+        raise WireRejected.new(reason, detail)
+      end
+    end
+  end
+end