block_given 0.1.0

data/lib/block_given/wallet.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # A private key + (optional) client, able to sign and send transactions
+  # (viem's WalletClient + Account).
+  #
+  #   wallet = BlockGiven::Wallet.new(private_key: ENV["PRIVATE_KEY"])
+  #   wallet.address
+  #   wallet.send_transaction(to: "0x...", value: BlockGiven::Utils.parse_ether("0.01")).wait
+  class Wallet
+    attr_reader :address
+
+    def self.generate(client: nil)
+      new(private_key: Eth::Key.new.private_hex, client: client)
+    end
+
+    def initialize(private_key:, client: nil)
+      hex = Utils.strip_hex(private_key.to_s.strip)
+      raise InvalidArgumentError, "private key must be 32 bytes hex" unless hex.match?(/\A[0-9a-fA-F]{64}\z/)
+
+      @key = Eth::Key.new(priv: hex)
+      @address = @key.address.checksummed
+      @client = client
+    end
+
+    def private_key = Utils.prefix_hex(@key.private_hex)
+    def public_key = Utils.prefix_hex(@key.public_hex)
+
+    def client = @client || BlockGiven.client
+    def with_client(client) = self.class.new(private_key: private_key, client: client)
+    def chain = client.chain
+
+    def balance(block: :latest) = client.get_balance(address, block: block)
+    def nonce(block: :pending) = client.get_transaction_count(address, block: block)
+
+    # EIP-191 personal_sign. Returns the 65-byte signature as hex.
+    def sign_message(message)
+      Utils.prefix_hex(@key.personal_sign(message))
+    end
+
+    # EIP-712 typed data (Hash with :types, :primaryType, :domain, :message).
+    def sign_typed_data(typed_data)
+      Utils.prefix_hex(@key.sign_typed_data(typed_data))
+    end
+
+    # Fills in nonce / gas / fees from the client and signs, without broadcasting.
+    # Returns a BlockGiven::SignedTransaction: its #hash and #nonce are known before
+    # any network call (persist them, then #broadcast). Same keywords as prepare_transaction;
+    # pass gas_price: to build a legacy (type 0) transaction instead of EIP-1559.
+    def signed_transaction(**params)
+      prepared = prepare_transaction(**params)
+      tx = Eth::Tx.new(to_eth_tx_params(prepared))
+      tx.sign(@key)
+      SignedTransaction.new(raw: Utils.prefix_hex(tx.hex), params: prepared, wallet: self)
+    end
+
+    # Signs and returns the raw tx hex.
+    def sign_transaction(**params) = signed_transaction(**params).raw
+
+    # Signs and broadcasts. Returns a BlockGiven::Transaction.
+    def send_transaction(**params) = signed_transaction(**params).broadcast
+
+    # Resolves every missing field (nonce, gas, fees, chain id) without signing.
+    def prepare_transaction(to: nil, value: 0, data: nil, gas: nil, nonce: nil, max_fee_per_gas: nil,
+                            max_priority_fee_per_gas: nil, gas_price: nil, chain_id: nil, access_list: nil)
+      to = Utils.checksum_address(to) if to
+      value = coerce_wei(value)
+      data = data.nil? || data.empty? ? "" : Utils.prefix_hex(data)
+
+      params = {
+        from: address, to: to, value: value, data: data,
+        chain_id: chain_id || client.chain.id,
+        nonce: nonce || self.nonce,
+        gas: gas || estimate_gas(to: to, data: data, value: value),
+        access_list: access_list
+      }
+
+      if gas_price
+        params[:gas_price] = gas_price
+      else
+        fees = if max_fee_per_gas && max_priority_fee_per_gas
+                 { max_fee_per_gas: max_fee_per_gas, max_priority_fee_per_gas: max_priority_fee_per_gas }
+               else
+                 estimated = client.estimate_fees_per_gas
+                 { max_fee_per_gas: max_fee_per_gas || estimated[:max_fee_per_gas],
+                   max_priority_fee_per_gas: max_priority_fee_per_gas || estimated[:max_priority_fee_per_gas] }
+               end
+        params.merge!(fees)
+      end
+      params
+    end
+
+    def ==(other) = other.is_a?(Wallet) && other.address == address
+    alias eql? ==
+    def hash = address.hash
+    def to_s = address
+    def inspect = "#<BlockGiven::Wallet #{address}>"
+
+    private
+
+    def estimate_gas(to:, data:, value:)
+      raise InvalidArgumentError, "contract creation requires an explicit gas: value" if to.nil?
+
+      estimate = client.estimate_gas(to: to, data: data, from: address, value: value)
+      (estimate * BlockGiven.config.gas_multiplier).ceil
+    end
+
+    def coerce_wei(value)
+      case value
+      when nil then 0
+      when Integer then value
+      when Float, BigDecimal, Rational
+        unless value == value.to_i
+          raise InvalidArgumentError,
+                "value must be an integer amount of wei (use BlockGiven::Utils.parse_ether)"
+        end
+
+        value.to_i
+      when String then Utils.hex?(value) ? Utils.hex_to_int(value) : Integer(value, 10)
+      else raise InvalidArgumentError, "invalid value: #{value.inspect}"
+      end
+    end
+
+    def to_eth_tx_params(params)
+      base = {
+        chain_id: params[:chain_id], nonce: params[:nonce], gas_limit: params[:gas],
+        to: params[:to], value: params[:value], data: params[:data]
+      }
+      if params[:gas_price]
+        base.merge(gas_price: params[:gas_price])
+      else
+        base[:access_list] = params[:access_list] || []
+        base.merge(priority_fee: params[:max_priority_fee_per_gas], max_gas_fee: params[:max_fee_per_gas])
+      end
+    end
+  end
+end

data/lib/block_given.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "eth"
+
+require_relative "block_given/version"
+require_relative "block_given/errors"
+require_relative "block_given/utils"
+require_relative "block_given/chain"
+require_relative "block_given/configuration"
+require_relative "block_given/connectors/base"
+require_relative "block_given/connectors/http"
+require_relative "block_given/connectors/alchemy"
+require_relative "block_given/connectors/stub"
+require_relative "block_given/normalizer"
+require_relative "block_given/poller"
+require_relative "block_given/receipt"
+require_relative "block_given/transaction"
+require_relative "block_given/signed_transaction"
+require_relative "block_given/client"
+require_relative "block_given/wallet"
+require_relative "block_given/abi/parameter"
+require_relative "block_given/abi/coder"
+require_relative "block_given/abi/function"
+require_relative "block_given/abi/event"
+require_relative "block_given/abi/custom_error"
+require_relative "block_given/abi/interface"
+require_relative "block_given/event"
+require_relative "block_given/contract"
+require_relative "block_given/railtie" if defined?(Rails::Railtie)
+
+# viem-inspired toolkit to read from and write to EVM smart contracts.
+#
+#   BlockGiven.configure do |c|
+#     c.connector = BlockGiven::Connectors::Alchemy.new(api_key: ENV["ALCHEMY_API_KEY"])
+#     c.chain = :base
+#   end
+module BlockGiven
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      @client = nil
+      config
+    end
+
+    # Default client built from the global configuration.
+    def client
+      @client ||= Client.new
+    end
+
+    attr_writer :client
+
+    # Running background watchers (see BlockGiven::Watcher.find / stop / stop_all).
+    def watchers = Watcher.all
+
+    # Forget configuration and default client, stop every watcher (useful in tests).
+    def reset!
+      Watcher.stop_all(join: 1)
+      @config = nil
+      @client = nil
+    end
+
+    def logger = config.logger
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: block_given
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Remi Wallaere
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: eth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.17
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.17
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: |
+  BlockGiven lets you talk to EVM smart contracts from Ruby with a small, explicit API
+  inspired by viem: typed contract classes generated from an ABI, wallets that sign
+  EIP-1559 transactions, pluggable JSON-RPC connectors (Alchemy first) and
+  polling helpers for receipts, blocks and events.
+email:
+- remi@boleromusic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/block_given.rb
+- lib/block_given/abi/coder.rb
+- lib/block_given/abi/custom_error.rb
+- lib/block_given/abi/event.rb
+- lib/block_given/abi/function.rb
+- lib/block_given/abi/interface.rb
+- lib/block_given/abi/parameter.rb
+- lib/block_given/chain.rb
+- lib/block_given/client.rb
+- lib/block_given/configuration.rb
+- lib/block_given/connectors/alchemy.rb
+- lib/block_given/connectors/base.rb
+- lib/block_given/connectors/http.rb
+- lib/block_given/connectors/stub.rb
+- lib/block_given/contract.rb
+- lib/block_given/errors.rb
+- lib/block_given/event.rb
+- lib/block_given/normalizer.rb
+- lib/block_given/poller.rb
+- lib/block_given/railtie.rb
+- lib/block_given/receipt.rb
+- lib/block_given/signed_transaction.rb
+- lib/block_given/transaction.rb
+- lib/block_given/utils.rb
+- lib/block_given/version.rb
+- lib/block_given/wallet.rb
+homepage: https://github.com/Bolero-Music/block_given
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Bolero-Music/block_given
+  source_code_uri: https://github.com/Bolero-Music/block_given
+  changelog_uri: https://github.com/Bolero-Music/block_given/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Bolero-Music/block_given/issues
+  documentation_uri: https://rubydoc.info/gems/block_given
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: viem-inspired Ruby client for EVM smart contracts.
+test_files: []