solana-studio 0.4.5 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2ffb18603f4ee37c57d42d010090922d657450172cf5d6623e9d637f1650eb5
-  data.tar.gz: 1e50dff5950f8dd69dae20590c899930f0e6c4342173cbac93d36b8828554307
+  metadata.gz: 29449e0ba9a251d17b60b4c453754953630d4b41604dd93285889f58f2d7df3b
+  data.tar.gz: a37bd87c44b6934571e0c3e82959caa519f327c5345fa674a956a9695c71c0eb
 SHA512:
-  metadata.gz: 41cba2106cced3ae803cb268ed5a5b94d46052ba20045ec50004b40e6f4745443515a015244417d0ab65558d79ff274ceffcaa1a43398d6c11bcdfc7256a3eb6
-  data.tar.gz: 444c36f828dcc16865f48cd749b5490cf541298f470b8c8f1628875f3d05df33f23e4c1295170772e6f9adb92d9aad3064bd31104b2e5b1c065b06cad4cdf8b0
+  metadata.gz: 6537687173850b20cfed221277a3cabf714572ccc765782961ae95ab66bcf6f33150183690e32ca1e0ca3881753c2149661e22eaa413c8c606632fde1c0f513f
+  data.tar.gz: f4426121b94008ccf816394f812b31496e53b421da57e29fef38e256bdd3776a659b4d918ee60cc7660800c5995a98a228db91e5dddc638dedd9ead04732ec88

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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
+- **`Solana::SystemProgram`** — System-Program instruction encoders for durable nonce support: `create_account` (ix 0), `advance_nonce_account` (4), `withdraw_nonce_account` (5), `initialize_nonce_account` (6), `authorize_nonce_account` (7). Plus constants `RECENT_BLOCKHASHES_SYSVAR`, `RENT_SYSVAR`, `NONCE_ACCOUNT_LENGTH` (80). A durable nonce lets a tx stay valid indefinitely (until consumed) instead of expiring with a ~90s recent blockhash — the canonical pattern for long / async / multi-party signing.
+- **`Solana::NonceAccount.parse(bytes)`** — parses an 80-byte nonce account (version, state, authority, stored nonce, lamports_per_signature) with `initialized?` + `authority?(expected)` guards.
+
+### Tests
+- `test/system_program_test.rb` (8 tests): **byte-match** each encoder against the exact `@solana/web3.js` layout (u32 LE index + fields, account metas + signer flags), nonce-account parse round-trip (init + uninit), and an advance-instruction-into-partial-tx composition check.
+
+## v0.4.5 (2026-06-02)
+
+### Fixed
+- **Fully keyless `serialize_partial`** — a build with zero local `@signers` (every required signature supplied externally) now works: the empty-signers guard fires only when neither a local nor an additional signer is present, the fee payer falls back to the first additional signer, and `@signers.drop(1)` is nil-safe. Enables the no-server-key multi-party signing console. (v0.4.4 began this; v0.4.5 completed the fee-payer/signers fallback.)
+
 ## v0.4.3 (2026-05-27)
 
 ### Fixed

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/nonce_account.rb

@@ -0,0 +1,64 @@
+module Solana
+  # Parser for a System-Program durable NONCE account's on-chain data (80 bytes):
+  #
+  #   version                u32  (offset 0)
+  #   state                  u32  (offset 4)   0 = Uninitialized, 1 = Initialized
+  #   authority              [32] (offset 8)
+  #   stored_nonce/blockhash [32] (offset 40)  ← anchor a tx's recentBlockhash on this
+  #   fee_calculator         u64  (offset 72)  lamports_per_signature
+  #
+  # Used to read the value a durable-nonce-anchored tx must use, and to verify the
+  # account is initialized + owned by the expected authority before trusting it.
+  class NonceAccount
+    UNINITIALIZED = 0
+    INITIALIZED   = 1
+
+    attr_reader :version, :state, :authority, :nonce, :lamports_per_signature
+
+    def initialize(version:, state:, authority:, nonce:, lamports_per_signature:)
+      @version = version
+      @state = state
+      @authority = authority # base58
+      @nonce = nonce         # base58 — use as the tx recentBlockhash
+      @lamports_per_signature = lamports_per_signature
+    end
+
+    # `data` is the raw account bytes (binary). Accepts a base64 string too.
+    def self.parse(data)
+      bytes = data
+      if bytes.is_a?(String) && bytes.encoding != Encoding::ASCII_8BIT
+        bytes = bytes.b
+      end
+      # Tolerate a base64-encoded blob (what getAccountInfo returns in data[0]).
+      if bytes.bytesize != NonceLength && looks_base64?(bytes)
+        require "base64"
+        bytes = Base64.decode64(bytes).b
+      end
+      raise ArgumentError, "nonce account too small (#{bytes.bytesize} bytes, need >= 80)" if bytes.bytesize < 80
+
+      new(
+        version:                bytes[0, 4].unpack1("V"),
+        state:                  bytes[4, 4].unpack1("V"),
+        authority:              Keypair.encode_base58(bytes.byteslice(8, 32)),
+        nonce:                  Keypair.encode_base58(bytes.byteslice(40, 32)),
+        lamports_per_signature: bytes[72, 8].unpack1("Q<")
+      )
+    end
+
+    NonceLength = 80
+
+    def self.looks_base64?(str)
+      str.bytesize > 80 && str.match?(%r{\A[A-Za-z0-9+/=\r\n]+\z})
+    end
+
+    def initialized?
+      state == INITIALIZED
+    end
+
+    # True when the account is initialized AND its authority matches `expected`
+    # (base58). The guard before anchoring any tx on this nonce.
+    def authority?(expected)
+      initialized? && authority == expected.to_s
+    end
+  end
+end

data/lib/solana/system_program.rb

@@ -0,0 +1,112 @@
+module Solana
+  # System Program instruction encoders — the subset needed for DURABLE NONCE
+  # accounts (plus CreateAccount, which nonce creation needs). Mirrors the
+  # SplToken encoder pattern: each method returns a { program_id, accounts, data }
+  # hash for Transaction#add_instruction.
+  #
+  # A durable nonce lets a transaction stay valid INDEFINITELY (until consumed)
+  # instead of expiring with a recent blockhash (~90s) — the canonical pattern
+  # for long / async / multi-party signing. A nonce-anchored tx sets
+  # recentBlockhash = the account's stored nonce and MUST carry advance_nonce_account
+  # as its FIRST instruction, signed by the nonce authority.
+  #
+  # Instruction data is `u32 LE index` + fields (the System Program's bincode
+  # layout). Indices: CreateAccount 0, AdvanceNonceAccount 4, WithdrawNonceAccount 5,
+  # InitializeNonceAccount 6, AuthorizeNonceAccount 7. Each encoder is byte-match
+  # tested against a known-good @solana/web3.js reference before being trusted.
+  module SystemProgram
+    module_function
+
+    PROGRAM_ID                 = Transaction::SYSTEM_PROGRAM_ID # 32 zero bytes
+    RECENT_BLOCKHASHES_SYSVAR  = Keypair.decode_base58("SysvarRecentB1ockHashes11111111111111111111")
+    RENT_SYSVAR                = Transaction::SYSVAR_RENT_PUBKEY
+    NONCE_ACCOUNT_LENGTH       = 80
+
+    # CreateAccount (ix 0): fund + allocate `space` bytes owned by `owner`.
+    # Both `from` (payer) and `new_account` must sign.
+    def create_account(from:, new_account:, lamports:, space:, owner:)
+      data = u32(0) + u64(lamports) + u64(space) + normalize(owner)
+      {
+        program_id: PROGRAM_ID,
+        accounts: [
+          { pubkey: normalize(from),        is_signer: true, is_writable: true },
+          { pubkey: normalize(new_account), is_signer: true, is_writable: true }
+        ],
+        data: data
+      }
+    end
+
+    # AdvanceNonceAccount (ix 4): MUST be the first instruction of any tx anchored
+    # on this nonce. The `authority` signs it.
+    def advance_nonce_account(nonce:, authority:)
+      {
+        program_id: PROGRAM_ID,
+        accounts: [
+          { pubkey: normalize(nonce),                     is_signer: false, is_writable: true },
+          { pubkey: RECENT_BLOCKHASHES_SYSVAR,            is_signer: false, is_writable: false },
+          { pubkey: normalize(authority),                 is_signer: true,  is_writable: false }
+        ],
+        data: u32(4)
+      }
+    end
+
+    # WithdrawNonceAccount (ix 5): reclaim lamports from the nonce account.
+    def withdraw_nonce_account(nonce:, to:, authority:, lamports:)
+      {
+        program_id: PROGRAM_ID,
+        accounts: [
+          { pubkey: normalize(nonce),          is_signer: false, is_writable: true },
+          { pubkey: normalize(to),             is_signer: false, is_writable: true },
+          { pubkey: RECENT_BLOCKHASHES_SYSVAR, is_signer: false, is_writable: false },
+          { pubkey: RENT_SYSVAR,               is_signer: false, is_writable: false },
+          { pubkey: normalize(authority),      is_signer: true,  is_writable: false }
+        ],
+        data: u32(5) + u64(lamports)
+      }
+    end
+
+    # InitializeNonceAccount (ix 6): turn a freshly-created account into a nonce
+    # account owned by `authority`. Paired with create_account in one tx.
+    def initialize_nonce_account(nonce:, authority:)
+      {
+        program_id: PROGRAM_ID,
+        accounts: [
+          { pubkey: normalize(nonce),          is_signer: false, is_writable: true },
+          { pubkey: RECENT_BLOCKHASHES_SYSVAR, is_signer: false, is_writable: false },
+          { pubkey: RENT_SYSVAR,               is_signer: false, is_writable: false }
+        ],
+        data: u32(6) + normalize(authority)
+      }
+    end
+
+    # AuthorizeNonceAccount (ix 7): rotate the nonce authority. Current authority signs.
+    def authorize_nonce_account(nonce:, authority:, new_authority:)
+      {
+        program_id: PROGRAM_ID,
+        accounts: [
+          { pubkey: normalize(nonce),     is_signer: false, is_writable: true },
+          { pubkey: normalize(authority), is_signer: true,  is_writable: false }
+        ],
+        data: u32(7) + normalize(new_authority)
+      }
+    end
+
+    # --- helpers --------------------------------------------------------------
+
+    def u32(n) = [n].pack("V")
+    def u64(n) = [n].pack("Q<")
+
+    # base58 string / Keypair / 32-byte binary → 32-byte binary.
+    def normalize(value)
+      if value.is_a?(Keypair)
+        value.public_key_bytes
+      elsif value.is_a?(String) && value.bytesize == 32
+        value.b
+      elsif value.is_a?(String)
+        Keypair.decode_base58(value)
+      else
+        value
+      end
+    end
+  end
+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

@@ -3,8 +3,10 @@ require_relative "solana/borsh"
 require_relative "solana/client"
 require_relative "solana/transaction"
 require_relative "solana/spl_token"
+require_relative "solana/system_program"
+require_relative "solana/nonce_account"
 require_relative "solana/auth_verifier"
 
 module SolanaStudio
-  VERSION = "0.4.5"
+  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.5
+  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
@@ -42,7 +41,9 @@ files:
 - lib/solana/borsh.rb
 - lib/solana/client.rb
 - lib/solana/keypair.rb
+- lib/solana/nonce_account.rb
 - lib/solana/spl_token.rb
+- lib/solana/system_program.rb
 - lib/solana/transaction.rb
 - lib/solana_studio.rb
 homepage: https://github.com/amcritchie/solana-studio
@@ -53,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
@@ -68,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'