bsv-sdk 0.1.0

data/lib/bsv/script/interpreter/script_number.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module BSV
+  module Script
+    # Bitcoin script number: arbitrary-precision integer with sign-magnitude
+    # little-endian byte encoding.
+    #
+    # Script numbers use a specialised encoding where the sign bit occupies
+    # the MSB of the last byte, and the magnitude is stored little-endian.
+    # This class handles encoding/decoding, minimal encoding validation,
+    # and arithmetic operations as required by the script interpreter.
+    class ScriptNumber # rubocop:disable Metrics/ClassLength
+      include Comparable
+
+      # Maximum byte length for script numbers (post-Genesis: 750 KB).
+      MAX_BYTE_LENGTH = 750_000
+
+      # Minimum 32-bit signed integer value.
+      INT32_MIN = -(2**31)
+
+      # Maximum 32-bit signed integer value.
+      INT32_MAX = (2**31) - 1
+
+      # @return [Integer] the numeric value
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # Decode little-endian sign-magnitude bytes into a ScriptNumber.
+      #
+      # Encoding: little-endian magnitude with sign bit in the MSB of the last byte.
+      #   127 -> [0x7f]
+      #  -127 -> [0xff]
+      #   128 -> [0x80 0x00]
+      #  -128 -> [0x80 0x80]
+      #   256 -> [0x00 0x01]
+      #  -256 -> [0x00 0x81]
+      def self.from_bytes(bytes, max_length: MAX_BYTE_LENGTH, require_minimal: false)
+        bytes = bytes.b if bytes.encoding != Encoding::ASCII_8BIT
+        return new(0) if bytes.empty?
+
+        if bytes.bytesize > max_length
+          raise ScriptError.new(
+            ScriptErrorCode::NUMBER_TOO_BIG,
+            "script number overflow: #{bytes.bytesize} > #{max_length}"
+          )
+        end
+
+        check_minimal_encoding!(bytes) if require_minimal
+
+        # Accumulate little-endian magnitude
+        val = 0
+        bytes.each_byte.with_index do |byte, i|
+          val |= byte << (8 * i)
+        end
+
+        # Extract sign from MSB of last byte
+        if bytes.getbyte(bytes.bytesize - 1) & 0x80 != 0
+          val ^= 0x80 << (8 * (bytes.bytesize - 1))
+          val = -val
+        end
+
+        new(val)
+      end
+
+      # Encode as little-endian sign-magnitude bytes.
+      def to_bytes
+        return ''.b if @value.zero?
+
+        negative = @value.negative?
+        abs_val = @value.abs
+
+        result = []
+        v = abs_val
+        while v.positive?
+          result << (v & 0xff)
+          v >>= 8
+        end
+
+        if result.last & 0x80 != 0
+          # MSB conflicts with sign bit — add padding byte
+          result << (negative ? 0x80 : 0x00)
+        elsif negative
+          # Set sign bit in MSB
+          result[-1] |= 0x80
+        end
+
+        result.pack('C*')
+      end
+
+      # Strip trailing zero-padding while preserving sign.
+      def self.minimally_encode(data)
+        return ''.b if data.nil? || data.empty?
+
+        data = data.b
+        last = data.getbyte(data.bytesize - 1)
+
+        # If MSB has non-sign bits set, already minimal
+        return data.dup if last.anybits?(0x7f)
+
+        # Single byte with only sign/zero bits — encode as empty
+        return ''.b if data.bytesize == 1
+
+        # If second-to-last byte needs the sign extension, keep it
+        return data.dup if data.getbyte(data.bytesize - 2) & 0x80 != 0
+
+        # Scan backwards to find last non-zero byte
+        i = data.bytesize - 2
+        i -= 1 while i.positive? && data.getbyte(i).zero?
+
+        if data.getbyte(i).zero?
+          # All zeros
+          ''.b
+        elsif data.getbyte(i) & 0x80 != 0
+          # This byte has high bit set — keep sign extension byte
+          result = data.byteslice(0, i + 1)
+          result << [last].pack('C')
+          result
+        else
+          # Fold sign bit into this byte
+          result = data.byteslice(0, i + 1).b
+          result.setbyte(i, data.getbyte(i) | (last & 0x80))
+          result
+        end
+      end
+
+      # Clamp to int32 range (for opcodes that need bounded indices).
+      def to_i32
+        return INT32_MIN if @value < INT32_MIN
+        return INT32_MAX if @value > INT32_MAX
+
+        @value
+      end
+
+      def to_i
+        @value
+      end
+
+      def zero?
+        @value.zero?
+      end
+
+      # --- Arithmetic (returns new ScriptNumber) ---
+
+      def +(other)
+        self.class.new(@value + other.value)
+      end
+
+      def -(other)
+        self.class.new(@value - other.value)
+      end
+
+      def *(other)
+        self.class.new(@value * other.value)
+      end
+
+      # Truncated-toward-zero division (matching Bitcoin consensus).
+      def /(other)
+        raise ScriptError.new(ScriptErrorCode::DIVIDE_BY_ZERO, 'division by zero') if other.value.zero?
+
+        result = @value.abs / other.value.abs
+        result = -result if @value.negative? ^ other.value.negative?
+        self.class.new(result)
+      end
+
+      # Remainder with sign of dividend (matching Bitcoin consensus).
+      def %(other)
+        raise ScriptError.new(ScriptErrorCode::DIVIDE_BY_ZERO, 'modulo by zero') if other.value.zero?
+
+        result = @value.abs % other.value.abs
+        result = -result if @value.negative?
+        self.class.new(result)
+      end
+
+      def -@
+        self.class.new(-@value)
+      end
+
+      def abs
+        self.class.new(@value.abs)
+      end
+
+      def <=>(other)
+        case other
+        when ScriptNumber
+          @value <=> other.value
+        when Integer
+          @value <=> other
+        end
+      end
+
+      def self.check_minimal_encoding!(bytes)
+        return if bytes.empty?
+
+        msb = bytes.getbyte(bytes.bytesize - 1)
+
+        # If MSB has non-sign bits set, encoding is minimal
+        return if msb.anybits?(0x7f)
+
+        # Single byte that is pure sign/zero (0x00 or 0x80) — not minimal
+        if bytes.bytesize == 1
+          raise ScriptError.new(ScriptErrorCode::MINIMAL_DATA, 'non-minimal script number encoding')
+        end
+
+        # Padding is justified if second-to-last byte has high bit set
+        return if bytes.getbyte(bytes.bytesize - 2) & 0x80 != 0
+
+        raise ScriptError.new(ScriptErrorCode::MINIMAL_DATA, 'non-minimal script number encoding')
+      end
+
+      private_class_method :check_minimal_encoding!
+    end
+  end
+end

data/lib/bsv/script/interpreter/stack.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'script_number'
+
+module BSV
+  module Script
+    # Script execution stack providing push/pop/peek operations for bytes,
+    # integers ({ScriptNumber}), and booleans.
+    #
+    # Implements Forth-like stack manipulation operations (dup, drop, swap,
+    # rot, over, pick, roll, tuck) parameterised by count for the multi-element
+    # opcodes (OP_2DUP, OP_2SWAP, etc.).
+    class Stack # rubocop:disable Metrics/ClassLength
+      def initialize
+        @items = []
+      end
+
+      # --- Push ---
+
+      def push_bytes(data)
+        @items.push(data.b)
+      end
+
+      def push_int(script_number)
+        @items.push(script_number.to_bytes)
+      end
+
+      def push_bool(val)
+        @items.push(val ? "\x01".b : ''.b)
+      end
+
+      # --- Pop ---
+
+      def pop_bytes
+        stack_error!('stack empty') if @items.empty?
+
+        @items.pop
+      end
+
+      def pop_int(max_length: ScriptNumber::MAX_BYTE_LENGTH, require_minimal: false)
+        ScriptNumber.from_bytes(pop_bytes, max_length: max_length, require_minimal: require_minimal)
+      end
+
+      def pop_bool
+        self.class.cast_bool(pop_bytes)
+      end
+
+      # --- Peek ---
+
+      def peek_bytes(idx = 0)
+        check_index!(idx)
+
+        @items[@items.length - 1 - idx]
+      end
+
+      def peek_int(idx = 0, max_length: ScriptNumber::MAX_BYTE_LENGTH, require_minimal: false)
+        ScriptNumber.from_bytes(peek_bytes(idx), max_length: max_length, require_minimal: require_minimal)
+      end
+
+      def peek_bool(idx = 0)
+        self.class.cast_bool(peek_bytes(idx))
+      end
+
+      # --- Info ---
+
+      def depth
+        @items.length
+      end
+
+      def empty?
+        @items.empty?
+      end
+
+      def clear
+        @items.clear
+      end
+
+      def to_a
+        @items.dup
+      end
+
+      # --- FORTH-like operations ---
+
+      # Duplicate the top N items.
+      def dup_n(count)
+        check_count!(count, 'dup_n')
+        stack_error!("stack too small for dup_n(#{count})") if @items.length < count
+
+        start = @items.length - count
+        count.times { |i| @items.push(@items[start + i].dup) }
+      end
+
+      # Remove the top N items.
+      def drop_n(count)
+        check_count!(count, 'drop_n')
+        stack_error!("stack too small for drop_n(#{count})") if @items.length < count
+
+        @items.pop(count)
+        nil
+      end
+
+      # Remove item at offset idx from top (0 = top).
+      def nip_n(idx)
+        check_index!(idx)
+
+        @items.delete_at(@items.length - 1 - idx)
+      end
+
+      # Rotate: move the bottom N of the top 3N items to the top.
+      # OP_ROT (n=1): [x1 x2 x3] -> [x2 x3 x1]
+      # OP_2ROT (n=2): [x1 x2 x3 x4 x5 x6] -> [x3 x4 x5 x6 x1 x2]
+      def rot_n(count)
+        check_count!(count, 'rot_n')
+        stack_error!("stack too small for rot_n(#{count})") if @items.length < (3 * count)
+
+        removed = @items.slice!(@items.length - (3 * count), count)
+        @items.concat(removed)
+      end
+
+      # Swap the top N items with the next N.
+      # OP_SWAP (n=1): [x1 x2] -> [x2 x1]
+      # OP_2SWAP (n=2): [x1 x2 x3 x4] -> [x3 x4 x1 x2]
+      def swap_n(count)
+        check_count!(count, 'swap_n')
+        stack_error!("stack too small for swap_n(#{count})") if @items.length < (2 * count)
+
+        count.times do |i|
+          a = @items.length - count + i
+          b = @items.length - (2 * count) + i
+          @items[a], @items[b] = @items[b], @items[a]
+        end
+      end
+
+      # Copy N items from 2N depth to top.
+      # OP_OVER (n=1): [x1 x2] -> [x1 x2 x1]
+      # OP_2OVER (n=2): [x1 x2 x3 x4] -> [x1 x2 x3 x4 x1 x2]
+      def over_n(count)
+        check_count!(count, 'over_n')
+        stack_error!("stack too small for over_n(#{count})") if @items.length < (2 * count)
+
+        start = @items.length - (2 * count)
+        count.times { |i| @items.push(@items[start + i].dup) }
+      end
+
+      # Copy item at index n to top (0 = top).
+      def pick_n(idx)
+        check_index!(idx)
+
+        @items.push(@items[@items.length - 1 - idx].dup)
+      end
+
+      # Move item at index n to top (0 = top).
+      def roll_n(idx)
+        check_index!(idx)
+
+        val = @items.delete_at(@items.length - 1 - idx)
+        @items.push(val)
+      end
+
+      # Copy top and insert before second: [x1 x2] -> [x2 x1 x2]
+      def tuck
+        stack_error!('stack too small for tuck') if @items.length < 2
+
+        @items.insert(@items.length - 2, @items.last.dup)
+      end
+
+      # --- Boolean conversion ---
+
+      # Bitcoin consensus boolean: false if empty, all-zero, or negative zero (0x80 last byte).
+      def self.cast_bool(bytes) # rubocop:disable Naming/PredicateMethod
+        return false if bytes.nil? || bytes.empty?
+
+        bytes.each_byte.with_index do |byte, i|
+          next if byte.zero?
+
+          # Negative zero: last byte is exactly 0x80
+          return !(i == bytes.bytesize - 1 && byte == 0x80)
+        end
+
+        false
+      end
+
+      private
+
+      def stack_error!(message)
+        raise ScriptError.new(ScriptErrorCode::INVALID_STACK_OPERATION, message)
+      end
+
+      def check_index!(idx)
+        return if idx >= 0 && idx < @items.length
+
+        stack_error!("index #{idx} invalid for stack size #{@items.length}")
+      end
+
+      def check_count!(count, operation)
+        return if count >= 1
+
+        stack_error!("#{operation} requires n >= 1, got #{count}")
+      end
+    end
+  end
+end

data/lib/bsv/script/opcodes.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module BSV
+  module Script
+    # All Bitcoin script opcodes as integer constants.
+    #
+    # Includes data push operations, flow control, stack manipulation,
+    # splice, bitwise, arithmetic, and cryptographic opcodes. Also
+    # provides {.name_for} for reverse lookup (opcode byte → name).
+    module Opcodes
+      # Push value
+      OP_0              = 0x00
+      OP_FALSE          = OP_0
+      OP_PUSHDATA1      = 0x4c
+      OP_PUSHDATA2      = 0x4d
+      OP_PUSHDATA4      = 0x4e
+      OP_1NEGATE        = 0x4f
+      OP_RESERVED       = 0x50
+      OP_1              = 0x51
+      OP_TRUE           = OP_1
+      OP_2              = 0x52
+      OP_3              = 0x53
+      OP_4              = 0x54
+      OP_5              = 0x55
+      OP_6              = 0x56
+      OP_7              = 0x57
+      OP_8              = 0x58
+      OP_9              = 0x59
+      OP_10             = 0x5a
+      OP_11             = 0x5b
+      OP_12             = 0x5c
+      OP_13             = 0x5d
+      OP_14             = 0x5e
+      OP_15             = 0x5f
+      OP_16             = 0x60
+
+      # Flow control
+      OP_NOP            = 0x61
+      OP_VER            = 0x62
+      OP_IF             = 0x63
+      OP_NOTIF          = 0x64
+      OP_VERIF          = 0x65
+      OP_VERNOTIF       = 0x66
+      OP_ELSE           = 0x67
+      OP_ENDIF          = 0x68
+      OP_VERIFY         = 0x69
+      OP_RETURN         = 0x6a
+
+      # Stack
+      OP_TOALTSTACK     = 0x6b
+      OP_FROMALTSTACK   = 0x6c
+      OP_2DROP          = 0x6d
+      OP_2DUP           = 0x6e
+      OP_3DUP           = 0x6f
+      OP_2OVER          = 0x70
+      OP_2ROT           = 0x71
+      OP_2SWAP          = 0x72
+      OP_IFDUP          = 0x73
+      OP_DEPTH          = 0x74
+      OP_DROP           = 0x75
+      OP_DUP            = 0x76
+      OP_NIP            = 0x77
+      OP_OVER           = 0x78
+      OP_PICK           = 0x79
+      OP_ROLL           = 0x7a
+      OP_ROT            = 0x7b
+      OP_SWAP           = 0x7c
+      OP_TUCK           = 0x7d
+
+      # Splice
+      OP_CAT            = 0x7e
+      OP_SPLIT          = 0x7f
+      OP_NUM2BIN        = 0x80
+      OP_BIN2NUM        = 0x81
+      OP_SIZE           = 0x82
+
+      # Bitwise logic
+      OP_INVERT         = 0x83
+      OP_AND            = 0x84
+      OP_OR             = 0x85
+      OP_XOR            = 0x86
+      OP_EQUAL          = 0x87
+      OP_EQUALVERIFY    = 0x88
+      OP_RESERVED1      = 0x89
+      OP_RESERVED2      = 0x8a
+
+      # Arithmetic
+      OP_1ADD           = 0x8b
+      OP_1SUB           = 0x8c
+      OP_2MUL           = 0x8d
+      OP_2DIV           = 0x8e
+      OP_NEGATE         = 0x8f
+      OP_ABS            = 0x90
+      OP_NOT            = 0x91
+      OP_0NOTEQUAL      = 0x92
+      OP_ADD            = 0x93
+      OP_SUB            = 0x94
+      OP_MUL            = 0x95
+      OP_DIV            = 0x96
+      OP_MOD            = 0x97
+      OP_LSHIFT         = 0x98
+      OP_RSHIFT         = 0x99
+      OP_BOOLAND        = 0x9a
+      OP_BOOLOR         = 0x9b
+      OP_NUMEQUAL       = 0x9c
+      OP_NUMEQUALVERIFY = 0x9d
+      OP_NUMNOTEQUAL    = 0x9e
+      OP_LESSTHAN       = 0x9f
+      OP_GREATERTHAN    = 0xa0
+      OP_LESSTHANOREQUAL    = 0xa1
+      OP_GREATERTHANOREQUAL = 0xa2
+      OP_MIN            = 0xa3
+      OP_MAX            = 0xa4
+      OP_WITHIN         = 0xa5
+
+      # Crypto
+      OP_RIPEMD160      = 0xa6
+      OP_SHA1           = 0xa7
+      OP_SHA256         = 0xa8
+      OP_HASH160        = 0xa9
+      OP_HASH256        = 0xaa
+      OP_CODESEPARATOR  = 0xab
+      OP_CHECKSIG       = 0xac
+      OP_CHECKSIGVERIFY = 0xad
+      OP_CHECKMULTISIG  = 0xae
+      OP_CHECKMULTISIGVERIFY = 0xaf
+
+      # Expansion
+      OP_NOP1 = 0xb0
+      OP_CHECKLOCKTIMEVERIFY = 0xb1
+      OP_CHECKSEQUENCEVERIFY = 0xb2
+      OP_NOP4           = 0xb3
+      OP_NOP5           = 0xb4
+      OP_NOP6           = 0xb5
+      OP_NOP7           = 0xb6
+      OP_NOP8           = 0xb7
+      OP_NOP9           = 0xb8
+      OP_NOP10          = 0xb9
+
+      # Pseudo-words (not used in scripts)
+      OP_PUBKEYHASH     = 0xfd
+      OP_PUBKEY         = 0xfe
+      OP_INVALIDOPCODE  = 0xff
+
+      # Reverse lookup: opcode byte → name string.
+      # Sorted so canonical names (OP_0, OP_1) win over aliases (OP_FALSE, OP_TRUE)
+      # regardless of Module#constants enumeration order.
+      NAME = constants
+             .select { |c| c.to_s.start_with?('OP_') }
+             .sort
+             .each_with_object({}) { |c, h| h[const_get(c)] ||= c.to_s }
+             .freeze
+
+      module_function
+
+      # Look up the canonical name for an opcode byte.
+      #
+      # @param opcode [Integer] the opcode byte value
+      # @return [String, nil] the opcode name (e.g. +"OP_DUP"+), or +nil+ if unknown
+      def name_for(opcode)
+        NAME[opcode]
+      end
+    end
+  end
+end