solana-studio 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fca2972e96c5cc005be5505673727eb85a24549f7632f0b1d3d9809ec27411d
-  data.tar.gz: 6dc069c098e0b6e664ed5fededf8c15848b73a39d845199357c009acf785298e
+  metadata.gz: 29449e0ba9a251d17b60b4c453754953630d4b41604dd93285889f58f2d7df3b
+  data.tar.gz: a37bd87c44b6934571e0c3e82959caa519f327c5345fa674a956a9695c71c0eb
 SHA512:
-  metadata.gz: 8186c3bf21e01bda36d230e1c43a4fb775a9e98812cdd87fa3d7c2513c44ac12178f981b083b3566f8e26eb3062daaaba2427ec6f32310ccfa8b3108ab8ab6ec
-  data.tar.gz: 67274a43c5f27c1e9765b0ab3ffbd0f871acb22484506bdfdfe74785c02ae4598e702244cf23a90f9ad0e86c08a4bada67ba0e1bbac2d3fbf3cf89907652f376
+  metadata.gz: 6537687173850b20cfed221277a3cabf714572ccc765782961ae95ab66bcf6f33150183690e32ca1e0ca3881753c2149661e22eaa413c8c606632fde1c0f513f
+  data.tar.gz: f4426121b94008ccf816394f812b31496e53b421da57e29fef38e256bdd3776a659b4d918ee60cc7660800c5995a98a228db91e5dddc638dedd9ead04732ec88

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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).
 
+## 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/lib/solana/client.rb

@@ -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/transaction.rb

@@ -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.rb

@@ -8,5 +8,5 @@ require_relative "solana/nonce_account"
 require_relative "solana/auth_verifier"
 
 module SolanaStudio
-  VERSION = "0.4.6"
+  VERSION = "0.4.7"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -55,7 +54,6 @@ metadata:
   source_code_uri: https://github.com/amcritchie/solana-studio
   bug_tracker_uri: https://github.com/amcritchie/solana-studio/issues
   changelog_uri: https://github.com/amcritchie/solana-studio/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,8 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: 'Ruby primitives for Solana: JSON-RPC client, Ed25519 keypairs, Borsh serialization,
   transaction builder, wallet signature verifier'