block_given 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4b499f5165a70b3cc18adbaf4a252debefa3fe690fec649e6e4e763852e888f
-  data.tar.gz: 522255498e152e9c5b3a410550e6774cf6710419d340cddeb79a4b384895be7f
+  metadata.gz: d9b06bd63a9b8cf930fffa7ddb4d38f0df49cba13bdf89f8cdec7dfc58d2afe4
+  data.tar.gz: 2089baad3a9d053cea769f9d40aac2f1344f74070522b2ed992048826e0ead42
 SHA512:
-  metadata.gz: 357a9aaa58ac26362a81ca80aa60e6dabe07840996ed76542389d8b0c5ae0d386f69b37c028932a58c2967952faba99813555a057adb600b3f15cadb57cbb792
-  data.tar.gz: 25da492c348c47987e1675026e63793d7908a99f2a1fbc8f66358bdf026053ddb37ac1ab96b1134ea6e2818e8cc5f1492d5346c4cd0c081156ed859a612a72de
+  metadata.gz: 49357c63673f56b9e417a135625cc13f682751ac6311510f741804c442f7cd93c2af91ace30c1f9b9a1d2a7800b1e2e48795f6cab59824845807ae2796992716
+  data.tar.gz: 7935466e7eb98c515d2f795d7a8ccf4e10a07844f208d17456b97e35e82de80483d0a24b3134209fe26d54067a385f5b8a32afcc01979ec737745da63ab11d1c

data/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-09
+
+### Added
+
+- `BlockGiven::Abi::Standards`: the ERC20, ERC721, ERC1155 and ERC4626 interfaces ship as frozen ABI arrays (EIP
+  functions and events, metadata / ERC-165 / enumerable extensions, ERC-6093 custom errors), with the input names of
+  OpenZeppelin 5 (`transfer(to:, value:)`). `Contract.abi` accepts their Symbol name (`abi :erc20`),
+  `Abi::Standards.fetch("ERC-721")` returns the array, `Abi::Standards.names` lists them.
+
+### Changed
+
+- **The `eth` gem is no longer a dependency**, and with it the unmaintained `rbsecp256k1` native extension, which
+  failed to compile on Debian bullseye (system libsecp256k1 too old, broken bundled download). Keccak-256,
+  secp256k1 (RFC 6979 deterministic signatures, low-s, recovery), RLP, EIP-1559 / legacy EIP-155 transactions,
+  EIP-191, EIP-712 and the ABI codec are now implemented in the gem on top of Ruby's OpenSSL standard library. The
+  gem installs with no native extension and no system package. Keys, signatures, raw transactions, hashes and ABI
+  encodings are byte-identical to what `eth` 0.5.17 produced (golden vectors in `spec/fixtures/`).
+- EIP-712: arrays are now hashed as the specification defines them (as viem and on-chain verifiers do); `eth`
+  encoded them as inline ABI arrays and rejected arrays of structs. `sign_typed_data` also accepts String keys and
+  a payload without an `EIP712Domain` type (derived from the domain, like viem).
+- Errors that used to leak from `eth` are typed: invalid transaction fields (negative values, gas limit below the
+  intrinsic gas) and out-of-range private keys raise `InvalidArgumentError`; ABI failures raise the new
+  `AbiEncodingError` / `AbiDecodingError` (both `AbiError`, same messages); unsupported ABI types (`fixed`,
+  `function`) raise `AbiError`.
+- `SignedTransaction.from_raw` returns a non-empty access list as `[{ address:, storage_keys: }]` (it returned raw
+  RLP bytes), and transactions accept access lists in that form as documented.
+- ABI: a `string` argument that looks like hex (`"0x12"`) is encoded as text (it was encoded as bytes), and decoded
+  `bytes` values are always `0x` hex.
+- YARD documentation for the whole public API (every method, option, block and return value), published on
+  [rubydoc.info](https://rubydoc.info/gems/block_given); `rake doc` builds it locally and `rake doc_check` (part of
+  `rake ci` and GitHub CI) fails under 100% coverage.
+
 ## [0.1.0] - 2026-09-11
 
 Initial release.
@@ -32,5 +64,6 @@ Initial release.
 - Optional Rails railtie (Rails 7.0 to 8.0) routing logs to `Rails.logger`.
 - Supported Ruby 3.1 to 3.4.
 
-[Unreleased]: https://github.com/Bolero-Music/block_given/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Bolero-Music/block_given/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Bolero-Music/block_given/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Bolero-Music/block_given/releases/tag/v0.1.0

data/README.md

@@ -3,6 +3,7 @@
 [![CI](https://github.com/Bolero-Music/block_given/actions/workflows/ci.yml/badge.svg)](https://github.com/Bolero-Music/block_given/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/block_given.svg)](https://rubygems.org/gems/block_given)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![API docs](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/block_given)
 ![Ruby 3.1+](https://img.shields.io/badge/ruby-%3E%3D%203.1-cc342d)
 
 **Ruby client for EVM smart contracts, inspired by [viem](https://viem.sh).**
@@ -17,7 +18,7 @@ BlockGiven.configure do |c|
 end
 
 class Usdc < BlockGiven::Contract
-  abi_file "abis/erc20.json"   # ABIs live in your repo, not in the gem
+  abi :erc20                   # shipped standard; your own contracts use abi_file "abis/catalog.json"
   address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 end
 
@@ -25,7 +26,7 @@ wallet = BlockGiven::Wallet.new(private_key: ENV["PRIVATE_KEY"])
 usdc = Usdc.new(wallet: wallet)
 
 usdc.balance_of(wallet.address)                 # => 12_500_000  (eth_call, decoded)
-tx = usdc.transfer(to: "0x7099...79C8", amount: 1e6)  # signs + broadcasts, returns BlockGiven::Transaction
+tx = usdc.transfer(to: "0x7099...79C8", value: 1e6)  # signs + broadcasts, returns BlockGiven::Transaction
 receipt = tx.wait!                              # polls until mined, raises if reverted
 usdc.events_from(receipt)                       # => [#<BlockGiven::Event Transfer {from:, to:, value: 1000000}>]
 ```
@@ -37,6 +38,7 @@ usdc.events_from(receipt)                       # => [#<BlockGiven::Event Transf
   - [Connectors](#connectors)
   - [Chains](#chains)
 - [Contracts](#contracts)
+  - [Standard ABIs](#standard-abis)
   - [Calling functions](#calling-functions)
   - [Transactions & receipts](#transactions--receipts)
   - [Reliable writes: sign first, broadcast later](#reliable-writes-sign-first-broadcast-later)
@@ -51,7 +53,7 @@ usdc.events_from(receipt)                       # => [#<BlockGiven::Event Transf
 - [Testing your code](#testing-your-code)
 - [Compatibility](#compatibility)
   - [Rails integration](#rails-integration)
-- [Development](#development)
+- [Development](#development) (the full API reference lives on [rubydoc.info](https://rubydoc.info/gems/block_given))
   - [Versioning & releases](#versioning--releases)
 - [Security](#security)
 - [Contributing](#contributing)
@@ -65,9 +67,9 @@ usdc.events_from(receipt)                       # => [#<BlockGiven::Event Transf
 gem "block_given"
 ```
 
-BlockGiven depends on the [`eth`](https://github.com/q9f/eth.rb) gem for secp256k1, keccak and ABI primitives.
-Its native extension needs libsecp256k1; on macOS `brew install secp256k1` then
-`gem install rbsecp256k1 -- --with-system-library` if the bundled build fails.
+BlockGiven is pure Ruby: keccak-256, secp256k1 signing (RFC 6979), RLP, transactions, EIP-712 and the ABI codec
+are implemented in the gem on top of Ruby's OpenSSL standard library, so it installs with no native extension and
+no system package (the OpenSSL Ruby links against must support the secp256k1 curve, as stock builds do).
 
 Requires Ruby >= 3.1.
 
@@ -112,62 +114,91 @@ client = BlockGiven::Client.new(chain: fork, connector: BlockGiven::Connectors::
 
 ## Contracts
 
-The gem ships no ABI: keep them in your repository (`abis/*.json`, or the Hardhat/Foundry artifacts) and
-point each contract class at its file. With `BlockGiven.config.abi_path = Rails.root.join("abis")` relative
-names resolve from that directory.
+The ABI comes either from a standard the gem ships (`abi :erc20`, see below) or from your repository
+(`abis/*.json`, or the Hardhat/Foundry artifacts) through `abi_file`. With
+`BlockGiven.config.abi_path = Rails.root.join("abis")` relative names resolve from that directory.
 
 ```ruby
-class CatalogShares < BlockGiven::Contract
-  abi_file "CatalogShares.json"             # ABI array, Hardhat/Foundry artifact ({ "abi": [...] }), or JSON string via `abi`
-  address "0x..."                            # optional default address
-  chain :base                                # optional: pins the chain regardless of the global config
+class Usdc < BlockGiven::Contract
+  abi :erc20                                         # or abi_file "catalog.json": ABI array, Hardhat/Foundry artifact, JSON string
+  address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" # optional default address (USDC on Base)
+  chain :base                                        # optional: pins the chain regardless of the global config
+end
+
+usdc = Usdc.new(wallet: wallet)                                          # default address
+usdc = Usdc.at("0x036CbD53842c5426634e7929541eC2318f3dCF7e", wallet: wallet)  # explicit address (USDC on Base Sepolia)
+usdc = Usdc.at("0x036CbD53842c5426634e7929541eC2318f3dCF7e")                 # read-only (no wallet)
+```
+
+### Standard ABIs
+
+`BlockGiven::Abi::Standards` ships the token standards as frozen ABI arrays, so the usual `erc20.json` download is not
+needed and the keyword names below are guaranteed: `ERC20`, `ERC721`, `ERC1155` and `ERC4626`. Each one
+carries the EIP functions and events, the usual extensions (metadata, ERC-165 `supportsInterface`, ERC-721
+enumerable) and the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors, so reverts from
+OpenZeppelin-based tokens decode by name. Input names follow OpenZeppelin 5 (`transfer(to, value)`).
+
+```ruby
+class Usdc < BlockGiven::Contract
+  abi :erc20                                   # Symbol name of a shipped ABI
 end
 
-shares = CatalogShares.new(wallet: wallet)            # default address
-shares = CatalogShares.at("0x...", wallet: wallet)    # explicit address
-shares = CatalogShares.at("0x...")                    # read-only (no wallet)
+class SongShares < BlockGiven::Contract
+  abi BlockGiven::Abi::Standards::ERC1155                # the constant works too
+end
+
+BlockGiven::Abi::Standards.fetch("ERC-721")            # => the ABI Array; extend it: abi BlockGiven::Abi::Standards::ERC721 + extra_definitions
+BlockGiven::Abi::Standards.names                       # => [:erc20, :erc721, :erc1155, :erc4626]
 ```
 
+ERC-721 has two `safeTransferFrom` overloads: positional calls pick one by arity, otherwise use the full
+signature (`nft.write("safeTransferFrom(address,address,uint256,bytes)", ...)`). Your own contracts keep their
+ABIs in the application (`abi_file`): they change with every deployment and the gem must not pin them.
+
 ### Calling functions
 
 Every ABI function is available in snake_case. `view`/`pure` functions run `eth_call` and return decoded
 values; the others sign and broadcast a transaction and return a `BlockGiven::Transaction`.
 
 ```ruby
-shares.balance_of("0x...")                    # positional
-shares.balance_of(account: "0x...")           # keyword (ABI input names, leading _ stripped, snake_cased)
-shares.transfer(to: "0x...", amount: 1e6)     # floats are accepted when they are whole numbers
-shares.transfer(wallet2, 1_000_000)           # anything responding to #address works as an address
+usdc.balance_of("0x...")                      # positional
+usdc.balance_of(account: "0x...")             # keyword (ABI input names, leading _ stripped, snake_cased)
+usdc.transfer(to: "0x...", value: 1e6)       # 1 USDC; floats are accepted when they are whole numbers
+usdc.transfer(wallet2, 1_000_000)             # anything responding to #address works as an address
+usdc.approve(spender, 2**256 - 1)             # uint256 takes any Integer
+usdc.allowance(wallet.address, spender)
 ```
 
 Argument coercion: integers accept `Integer`, whole `Float`/`BigDecimal`, decimal or hex strings; tuples accept
 `Hash` (component names) or `Array`; `bytes` accept hex or binary strings. Decoded outputs give checksummed
 addresses, `0x` hex for bytes, and named tuples as `Hash`. Multiple outputs come back as an `Array`.
 
-Transaction and call overrides live in the reserved `tx:` keyword so they never clash with ABI input names:
+Transaction and call overrides live in the reserved `tx:` keyword so they never clash with ABI input names
+(ERC20 itself has an input called `value`):
 
 ```ruby
-vault.deposit(amount, tx: { value: BlockGiven::Utils.parse_ether("0.1"), gas: 200_000, nonce: 12 })
-shares.balance_of(addr, tx: { block: 20_000_000 })          # historical read
-shares.owner_of(1, tx: { from: "0x..." })                    # msg.sender for eth_call
+usdc.transfer(to: addr, value: 1e6, tx: { gas: 80_000, nonce: 12 })
+usdc.balance_of(addr, tx: { block: 20_000_000 })                # historical read
+weth.deposit(tx: { value: BlockGiven::Utils.parse_ether("0.1") })  # payable: weth = Weth.at("0x4200000000000000000000000000000000000006")
+usdc.simulate(:transfer, addr, 1e6, tx: { from: treasury })     # eth_call with another msg.sender
 # allowed keys: value gas nonce max_fee_per_gas max_priority_fee_per_gas gas_price from block
 ```
 
 Explicit API (handles names clashing with Ruby methods, overloads by signature, etc.):
 
 ```ruby
-shares.read(:balance_of, addr)
-shares.write("safeMint(address,bytes)", addr, "0x")
-shares.simulate(:buy, 42, tx: { value: price })   # eth_call from the wallet: raises the decoded revert without paying gas
-shares.estimate_gas(:buy, 42, tx: { value: price })
-shares.encode_function_data(:transfer, to: addr, amount: 1)
-shares.decode_function_result(:balance_of, "0x...")
+usdc.read(:balance_of, addr)
+usdc.write("transfer(address,uint256)", addr, 1_000_000)   # full signature picks an overload
+usdc.simulate(:transfer, addr, 10**12)     # eth_call from the wallet: raises the decoded revert without paying gas
+usdc.estimate_gas(:transfer, addr, 1_000_000)
+usdc.encode_function_data(:transfer, to: addr, value: 1)
+usdc.decode_function_result(:balance_of, "0x...")
 ```
 
 ### Transactions & receipts
 
 ```ruby
-tx = shares.transfer(to: addr, amount: 1)
+tx = usdc.transfer(to: addr, value: 1e6)
 tx.hash                      # "0x..."
 tx.explorer_url              # https://basescan.org/tx/0x...
 tx.mined?                    # non-blocking
@@ -185,22 +216,22 @@ client.transaction("0x...")  # the same handle for a hash you persisted earlier
 A transaction hash is the keccak of the signed bytes, so it is known **before** anything is sent.
 `prepare_write` (or `Wallet#signed_transaction`) signs without broadcasting; persist the hash and
 nonce, then broadcast. If the RPC call times out you still know exactly which transaction to look for,
-and a same-nonce replacement can never be mined twice.
+and a same-nonce replacement can never be mined twice. Example: paying out USDC from an outbox table.
 
 ```ruby
-signed = registry.prepare_write(:record, movement_id, tx: { nonce: call.nonce })
-signed.hash, signed.nonce, signed.raw          # known now; signed.to_h for persistence
-call.update!(tx_hash: signed.hash, status: :submitted)
-signed.broadcast                               # eth_sendRawTransaction, returns the Transaction
+signed = usdc.prepare_write(:transfer, to: payout.wallet, value: 12_500_000, tx: { nonce: payout.nonce })
+signed.hash, signed.nonce, signed.raw                       # known now; signed.to_h for persistence
+payout.update!(tx_hash: signed.hash, raw_tx: signed.raw, status: :submitted)
+signed.broadcast                                            # eth_sendRawTransaction, returns the Transaction
 
 # later, one tick of your outbox worker (possibly another process: rebuild from the persisted bytes)
-signed = BlockGiven::SignedTransaction.from_raw(call.raw_tx, wallet: wallet, interface: registry.interface)
-tx = signed.transaction                                   # same as client.transaction(call.tx_hash)
+signed = BlockGiven::SignedTransaction.from_raw(payout.raw_tx, wallet: wallet, interface: usdc.interface)
+tx = signed.transaction                                     # same as client.transaction(payout.tx_hash)
 case tx.status
-when :success  then call.confirmed! if tx.confirmed?(5)   # registry.events_from(tx.receipt) has the logs
-when :reverted then call.failed!
-when :unknown  then signed.broadcast                      # dropped by the node: resend the same bytes
-when :pending  then signed.replacement.broadcast if call.submitted_at < 5.minutes.ago
+when :success  then payout.confirmed! if tx.confirmed?(5)   # usdc.events_from(tx.receipt) => [Transfer ...]
+when :reverted then payout.failed!
+when :unknown  then signed.broadcast                        # dropped by the node: resend the same bytes
+when :pending  then signed.replacement.broadcast if payout.submitted_at < 5.minutes.ago
 end
 ```
 
@@ -215,7 +246,7 @@ the original gets mined first, the replacement is rejected for its nonce and `tx
 
 ```ruby
 begin
-  usdc.transfer(to: addr, amount: 10**12)
+  usdc.transfer(to: addr, value: 10**12)
 rescue BlockGiven::ContractRevertError => e
   e.message     # => 'ERC20InsufficientBalance("0xf39F...", 5, 1000000000000)'
   e.error_name  # => "ERC20InsufficientBalance"
@@ -356,7 +387,7 @@ Token helpers are one method away in your own contract class:
 
 ```ruby
 class Erc20 < BlockGiven::Contract
-  abi_file "erc20.json"
+  abi :erc20
   def decimals = @decimals ||= read(:decimals)
   def parse_amount(value) = BlockGiven::Utils.parse_units(value, decimals)    # "1.5" -> 1_500_000
   def format_amount(value) = BlockGiven::Utils.format_units(value, decimals)  # 1_500_000 -> "1.5"
@@ -384,7 +415,6 @@ stub.calls_for("eth_sendRawTransaction")
 | ------ | ------------------------------------------ | ------------------------------------------------------------- |
 | Ruby   | >= 3.1 (3.1, 3.2, 3.3, 3.4)                | CI matrix + local run on each version                         |
 | Rails  | optional, 7.0 / 7.1 / 7.2 / 8.0            | full suite run with Rails loaded (`gemfiles/rails_*.gemfile`) |
-| `eth`  | ~> 0.5, >= 0.5.17 (tuple ABI support)      | pinned in the gemspec                                         |
 | stdlib | `bigdecimal`, `logger` declared explicitly | bundled gems in Ruby 3.4 / 3.5                                |
 
 BlockGiven has no runtime dependency on Rails or ActiveSupport: it is plain Ruby and works in scripts,
@@ -408,13 +438,15 @@ unless the initializer sets `c.logger` itself. Contract classes live wherever yo
 ## Development
 
 ```bash
-bin/setup                            # bundle install (+ libsecp256k1 fallback)
+bin/setup                            # bundle install
 bundle exec rspec                    # unit suite (Stub connector, no network)
 COVERAGE=1 bundle exec rspec         # + SimpleCov report in coverage/ (minimum 90% lines)
 bundle exec rubocop
+bundle exec rake doc                 # YARD API docs in doc/ (also published at rubydoc.info/gems/block_given)
+bundle exec rake doc_check           # fails unless 100% of the public API is documented
 ALCHEMY_API_KEY=... bin/console      # IRB with BlockGiven configured for BLOCK_GIVEN_CHAIN (default base)
 
-bundle exec rake ci                  # specs + rubocop + gem build
+bundle exec rake ci                  # specs + rubocop + doc coverage + gem build
 
 # Ruby / Rails matrix (Docker for the Rubies you do not have locally)
 bin/matrix                           # Ruby 3.2, 3.3, 3.4
@@ -429,11 +461,12 @@ CI runs the suite on Ruby 3.1 to 3.4 and against Rails 7.0, 7.1, 7.2 and 8.0 (`.
 BlockGiven follows [Semantic Versioning](https://semver.org): breaking changes to the public API
 (`BlockGiven::Contract`, `Wallet`, `Client`, connectors, `Utils`) bump the major version, additions the minor,
 fixes the patch. Every change is listed in `CHANGELOG.md`. Dependency policy: Ruby versions are dropped
-only once they reach end of life, Rails versions are tested while they receive security fixes, and the `eth`
-constraint is only tightened when a feature needs it.
+only once they reach end of life, Rails versions are tested while they receive security fixes, and runtime
+dependencies stay limited to Ruby's default and bundled gems.
 
-To release: bump `lib/block_given/version.rb`, move the `Unreleased` notes under the new version in `CHANGELOG.md`,
-commit, then push a `vX.Y.Z` tag. The release workflow checks the tag against the version, runs the suite and
+To release: on a branch off `develop`, bump `lib/block_given/version.rb`, move the `Unreleased` notes under the
+new version in `CHANGELOG.md`, merge it into `develop`, then merge the release pull request `develop` -> `main`
+and push a `vX.Y.Z` tag. The release workflow checks the tag against the version, runs the suite and
 publishes through RubyGems trusted publishing (no API key in CI). `bundle exec rake release` does the same
 from a maintainer machine with RubyGems credentials.
 
@@ -446,16 +479,20 @@ from a maintainer machine with RubyGems credentials.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/Bolero-Music/block_given). Please read
-[CONTRIBUTING.md](CONTRIBUTING.md) (setup, test matrix, conventions) and the
-[code of conduct](CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/Bolero-Music/block_given). Branch from
+`develop` and target `develop`: `main` is release-only, and both branches require a pull request with green CI and
+an approving review. Please read [CONTRIBUTING.md](CONTRIBUTING.md) (branches, setup, test matrix, conventions) and
+the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## Roadmap
 
 - Contract deployment (`Contract.deploy`)
 - Multi-contract indexer helper with pluggable cursor store
 - Human-readable ABI (`parse_abi("function transfer(address to, uint256 amount)")`)
-- WebSocket connector for push-based subscriptions
+- WebSocket connector: `watch_*` helpers subscribe to filtered `logs` (`eth_subscribe`, like viem's `webSocket`
+  transport) so nothing is fetched per block; on every (re)connection a single range-based `eth_getLogs` catch-up
+  runs from the persisted cursor, overlapping logs are deduplicated on `(block_hash, log_index)`, `removed` logs
+  handle reorgs, and polling is the fallback when the socket stays down
 - Multicall batching of reads
 
 ## License

data/lib/block_given/abi/codec/decoder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    module Codec
+      # The decoding half of {Codec}: reads heads, follows offsets, and checks every read against the data size so
+      # that malformed data raises instead of returning garbage.
+      #
+      # @api private
+      module Decoder
+        module_function
+
+        # Decodes a sequence whose head starts at `start`; offsets of dynamic values are relative to `start`.
+        #
+        # @param types [Array<Type>]
+        # @param data [String] the whole encoding, binary
+        # @param start [Integer]
+        # @return [Array]
+        # @raise [BlockGiven::AbiDecodingError] when data is missing
+        def decode_sequence(types, data, start)
+          position = start
+          types.map do |type|
+            value =
+              if type.dynamic?
+                decode_value(type, data, start + read_offset(data, position))
+              else
+                decode_value(type, data, position)
+              end
+            position += type.head_size
+            value
+          end
+        end
+
+        # Decodes one value encoded at a position.
+        #
+        # @param type [Type]
+        # @param data [String] binary
+        # @param position [Integer]
+        # @return [Object]
+        # @raise [BlockGiven::AbiDecodingError] when data is missing
+        def decode_value(type, data, position)
+          return decode_array(type, data, position) if type.array?
+
+          case type.base
+          when "tuple" then decode_sequence(type.components, data, position)
+          when "uint" then read_uint(data, position)
+          when "int"
+            value = read_uint(data, position)
+            value >= 2**255 ? value - (2**256) : value
+          when "address" then Utils.bin_to_hex(read(data, position + 12, 20))
+          when "bool" then read_uint(data, position) == 1
+          when "string" then decode_bytes(data, position).force_encoding(Encoding::UTF_8)
+          else type.size ? read(data, position, type.size) : decode_bytes(data, position)
+          end
+        end
+
+        # @param type [Type] an array type
+        # @param data [String] binary
+        # @param position [Integer]
+        # @return [Array]
+        # @raise [BlockGiven::AbiDecodingError] when the announced length exceeds the data
+        def decode_array(type, data, position)
+          return decode_sequence(Array.new(type.length, type.element), data, position) if type.length
+
+          count = read_uint(data, position)
+          if count * [type.element.head_size, 1].max > data.bytesize - position - 32
+            raise AbiDecodingError, "array length #{count} exceeds the data"
+          end
+
+          decode_sequence(Array.new(count, type.element), data, position + 32)
+        end
+
+        # @param data [String] binary
+        # @param position [Integer] position of the length word
+        # @return [String] the bytes after the length word, binary
+        # @raise [BlockGiven::AbiDecodingError] when the data is shorter than the announced length
+        def decode_bytes(data, position) = read(data, position + 32, read_uint(data, position))
+
+        # @param data [String] binary
+        # @param position [Integer]
+        # @return [Integer] an offset, bounded by the data size
+        # @raise [BlockGiven::AbiDecodingError] when the offset points outside of the data
+        def read_offset(data, position)
+          offset = read_uint(data, position)
+          raise AbiDecodingError, "offset #{offset} points outside of the data" if offset > data.bytesize
+
+          offset
+        end
+
+        # @param data [String] binary
+        # @param position [Integer]
+        # @return [Integer] the unsigned 32-byte word at the position
+        # @raise [BlockGiven::AbiDecodingError] when fewer than 32 bytes remain
+        def read_uint(data, position) = read(data, position, 32).unpack1("H*").to_i(16)
+
+        # @param data [String] binary
+        # @param position [Integer]
+        # @param length [Integer]
+        # @return [String] exactly `length` bytes, binary
+        # @raise [BlockGiven::AbiDecodingError] when the data is too short
+        def read(data, position, length)
+          if position.negative? || length.negative? || position + length > data.bytesize
+            raise AbiDecodingError, "not enough data: needed #{position + length} bytes, got #{data.bytesize}"
+          end
+
+          data.byteslice(position, length)
+        end
+      end
+    end
+  end
+end

data/lib/block_given/abi/codec.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    # The Solidity contract ABI encoding: heads and tails, offsets, two's complement integers, padded bytes.
+    #
+    # Works on already coerced values (see {Coder} for the Ruby-facing layer): Integers for `intN` / `uintN`,
+    # `0x` hex Strings for `address`, `0x` hex or binary Strings for `bytes` / `bytesN`, Strings for `string`,
+    # `true` / `false`, and Arrays for arrays and tuples. Decoding returns the same shapes, with lowercase
+    # addresses and binary Strings for bytes.
+    #
+    # @api private
+    module Codec
+      module_function
+
+      # Encodes values for a list of types, as function arguments are.
+      #
+      # @param types [Array<String, Type>] canonical types
+      # @param values [Array] one value per type
+      # @return [String] the encoding, binary
+      # @raise [BlockGiven::AbiEncodingError] when a value does not fit its type
+      # @raise [BlockGiven::AbiError] when a type is not supported
+      def encode(types, values)
+        types = types.map { |type| type.is_a?(Type) ? type : Type.parse(type) }
+        raise AbiEncodingError, "expected #{types.size} value(s), got #{values.size}" if types.size != values.size
+
+        encode_sequence(types, values)
+      end
+
+      # Decodes data produced for a list of types.
+      #
+      # @param types [Array<String, Type>] canonical types
+      # @param data [String] the encoding, binary
+      # @return [Array] one value per type
+      # @raise [BlockGiven::AbiDecodingError] when the data is too short or an offset points outside of it
+      # @raise [BlockGiven::AbiError] when a type is not supported
+      def decode(types, data)
+        types = types.map { |type| type.is_a?(Type) ? type : Type.parse(type) }
+        Decoder.decode_sequence(types, data.b, 0)
+      end
+
+      # Encodes a sequence (arguments, tuple components or array elements): static values in place, dynamic
+      # ones behind an offset relative to the start of the sequence.
+      #
+      # @param types [Array<Type>]
+      # @param values [Array]
+      # @return [String] binary
+      def encode_sequence(types, values)
+        offset = types.sum(&:head_size)
+        heads = +"".b
+        tails = +"".b
+        types.zip(values).each do |type, value|
+          encoded = encode_value(type, value)
+          if type.dynamic?
+            heads << uint_word(offset + tails.bytesize)
+            tails << encoded
+          else
+            heads << encoded
+          end
+        end
+        heads + tails
+      end
+
+      # Encodes one value.
+      #
+      # @param type [Type]
+      # @param value [Object]
+      # @return [String] binary
+      # @raise [BlockGiven::AbiEncodingError] when the value does not fit the type
+      def encode_value(type, value)
+        return encode_array(type, value) if type.array?
+
+        case type.base
+        when "tuple"
+          unless value.is_a?(Array) && value.size == type.components.size
+            raise AbiEncodingError, "#{type} expects an Array of #{type.components.size} values, got #{value.inspect}"
+          end
+
+          encode_sequence(type.components, value)
+        when "uint", "int" then encode_integer(type, value)
+        when "address" then encode_address(value)
+        when "bool"
+          raise AbiEncodingError, "bool expects true/false, got #{value.inspect}" unless [true, false].include?(value)
+
+          uint_word(value ? 1 : 0)
+        when "string" then encode_bytes(string_bytes(value))
+        else type.size ? encode_fixed_bytes(type, value) : encode_bytes(binary(type, value))
+        end
+      end
+
+      # @param type [Type] an array type
+      # @param value [Array]
+      # @return [String] binary: the length (dynamic arrays only) then the elements as a sequence
+      # @raise [BlockGiven::AbiEncodingError] when the value is not an Array of the declared length
+      def encode_array(type, value)
+        raise AbiEncodingError, "#{type} expects an Array, got #{value.inspect}" unless value.is_a?(Array)
+        if type.length && value.size != type.length
+          raise AbiEncodingError, "#{type} expects #{type.length} elements, got #{value.size}"
+        end
+
+        elements = encode_sequence(Array.new(value.size, type.element), value)
+        type.length ? elements : uint_word(value.size) + elements
+      end
+
+      # @param type [Type] `intN` or `uintN`
+      # @param value [Integer]
+      # @return [String] the two's complement 32-byte word, binary
+      # @raise [BlockGiven::AbiEncodingError] when the value is not an Integer or is out of bounds
+      def encode_integer(type, value)
+        raise AbiEncodingError, "#{type} expects an Integer, got #{value.inspect}" unless value.is_a?(Integer)
+
+        range = type.base == "int" ? (-(2**(type.size - 1))...(2**(type.size - 1))) : (0...(2**type.size))
+        raise AbiEncodingError, "value #{value} is out of bounds for #{type}" unless range.cover?(value)
+
+        uint_word(value % (2**256))
+      end
+
+      # @param value [String] `0x` hex address
+      # @return [String] the left-padded word, binary
+      # @raise [BlockGiven::AbiEncodingError] when the value is not a 20-byte hex address
+      def encode_address(value)
+        raise AbiEncodingError, "invalid address #{value.inspect}" unless Utils.address?(value)
+
+        Utils.hex_to_bin(Utils.pad_hex(value))
+      end
+
+      # @param type [Type] `bytesN`
+      # @param value [String] `0x` hex or binary, at most N bytes
+      # @return [String] the right-padded word, binary
+      # @raise [BlockGiven::AbiEncodingError] when the value is longer than N bytes
+      def encode_fixed_bytes(type, value)
+        bytes = binary(type, value)
+        raise AbiEncodingError, "#{bytes.bytesize} bytes are out of bounds for #{type}" if bytes.bytesize > type.size
+
+        bytes.ljust(32, "\x00".b)
+      end
+
+      # @param bytes [String] binary
+      # @return [String] the length word, then the bytes right-padded to a multiple of 32, binary
+      def encode_bytes(bytes)
+        uint_word(bytes.bytesize) + bytes.ljust(((bytes.bytesize + 31) / 32) * 32, "\x00".b)
+      end
+
+      # @param type [Type] for error messages
+      # @param value [String] `0x` hex (decoded) or any other String (taken as raw bytes)
+      # @return [String] binary
+      # @raise [BlockGiven::AbiEncodingError] when the value is not a String or is odd-length hex
+      def binary(type, value)
+        raise AbiEncodingError, "#{type} expects a String, got #{value.inspect}" unless value.is_a?(String)
+        return value.b unless Utils.hex?(value)
+        raise AbiEncodingError, "#{type} expects an even number of hex digits" if value.size.odd?
+
+        Utils.hex_to_bin(value)
+      end
+
+      # @param value [String]
+      # @return [String] the UTF-8 bytes, binary
+      # @raise [BlockGiven::AbiEncodingError] when the value is not a String
+      def string_bytes(value)
+        raise AbiEncodingError, "string expects a String, got #{value.inspect}" unless value.is_a?(String)
+
+        value.encode(Encoding::UTF_8).b
+      end
+
+      # @param value [Integer] 0 to 2**256 - 1
+      # @return [String] 32 big-endian bytes, binary
+      def uint_word(value) = [value.to_s(16).rjust(64, "0")].pack("H*")
+    end
+  end
+end