block_given 0.1.0 → 0.2.0

data/lib/block_given/abi/interface.rb

@@ -3,21 +3,65 @@
 require "json"
 
 module BlockGiven
+  # ABI layer: parsed interfaces, functions, events, custom errors, parameters and value coercion.
+  #
+  # {Abi::Interface.parse} turns an ABI (Array, artifact Hash, JSON String or file) into typed objects
+  # that {BlockGiven::Contract} relies on to encode calls, decode outputs and logs, and name reverts.
   module Abi
     # Parsed ABI: functions (with overload resolution), events and custom errors.
+    #
+    # Functions are grouped by snake_case Ruby name so that overloads (`safeMint(address)` and
+    # `safeMint(address,bytes)`) can be resolved from the call arguments or from a full signature.
+    #
+    # @example
+    #   interface = BlockGiven::Abi::Interface.parse(File.read("abis/erc20.json"))
+    #   interface.function(:balance_of).encode([owner])   # => "0x70a08231..."
+    #   interface.event(:Transfer).topic                  # => "0xddf252ad..."
+    #   interface.error_by_selector("0xe450d38c")         # => #<BlockGiven::Abi::CustomError ...>
     class Interface
+      # @!attribute [r] functions
+      #   @return [Array<Function>] every `function` definition, in ABI order
+      # @!attribute [r] events
+      #   @return [Array<Event>] every `event` definition, in ABI order
+      # @!attribute [r] errors
+      #   @return [Array<CustomError>] every `error` definition, in ABI order
+      # @!attribute [r] constructor
+      #   @return [Hash, nil] the raw `constructor` definition (String keys), or `nil` when the ABI has
+      #     none; it is kept for reference only and cannot be encoded through this class
+      # @!attribute [r] raw
+      #   @return [Array<Hash>] the ABI definitions as given, with keys converted to Strings
       attr_reader :functions, :events, :errors, :constructor, :raw
 
-      # Accepts an ABI Array, a Hardhat/Foundry artifact Hash (with "abi"), a JSON String or a Pathname.
+      # Parses an ABI from any supported source.
+      #
+      # @param source [Array<Hash>, Hash, String, Symbol, Pathname, File, Interface] an ABI Array, a Hardhat/Foundry
+      #   artifact Hash with an `"abi"` (or `:abi`) key, a JSON String, the Symbol name of a shipped standard
+      #   ({Standards.fetch}: `:erc20`, `:erc721`, `:erc1155`, `:erc4626`), a Pathname/File to read, or an Interface
+      #   (returned as is)
+      # @return [Interface]
+      # @raise [BlockGiven::AbiError] when the JSON is invalid, the Hash has no `abi` key or the source
+      #   type is not supported
+      # @example
+      #   BlockGiven::Abi::Interface.parse(JSON.parse(File.read("artifacts/Usdc.json")))
+      #   BlockGiven::Abi::Interface.parse(Pathname.new("abis/erc20.json"))
+      #   BlockGiven::Abi::Interface.parse(:erc20)
+      #   BlockGiven::Abi::Interface.parse([{ "type" => "function", "name" => "decimals", ... }])
       def self.parse(source)
         return source if source.is_a?(Interface)
 
         new(load_definitions(source))
       end
 
+      # Turns a source accepted by {.parse} into an Array of raw ABI definitions.
+      #
+      # @api private
+      # @param source [Array<Hash>, Hash, String, Pathname, File] see {.parse}
+      # @return [Array<Hash>] the ABI definitions
+      # @raise [BlockGiven::AbiError] when the source cannot be turned into an ABI Array
       def self.load_definitions(source)
         case source
         when Array then source
+        when Symbol then Standards.fetch(source)
         when Hash then source["abi"] || source[:abi] || raise(AbiError, "Hash has no 'abi' key")
         when Pathname, File then load_definitions(JSON.parse(File.read(source)))
         when String then load_definitions(JSON.parse(source))
@@ -27,6 +71,13 @@ module BlockGiven
         raise AbiError, "invalid ABI JSON: #{e.message}"
       end
 
+      # Builds an interface from raw ABI definitions; prefer {.parse}.
+      #
+      # Definitions typed `function` (or without a `type`, as in very old ABIs) become {Function}s,
+      # `event` become {Event}s, `error` become {CustomError}s and the `constructor` is kept raw.
+      # Other types (`fallback`, `receive`) are ignored.
+      #
+      # @param definitions [Array<Hash>] ABI definitions with String or Symbol keys
       def initialize(definitions)
         @raw = definitions.map { |d| d.transform_keys(&:to_s) }
         @functions = []
@@ -44,11 +95,30 @@ module BlockGiven
         @functions_by_name = @functions.group_by(&:ruby_name)
       end
 
+      # Distinct snake_case function names (overloads share one name).
+      #
+      # @return [Array<Symbol>]
       def function_names = @functions_by_name.keys
 
-      # Finds a function by name (snake_case or camelCase) or by full signature
-      # ("transfer(address,uint256)"). Overloads are disambiguated by argument
-      # count or keyword names.
+      # Finds a function by name or full signature, resolving overloads from the call arguments.
+      #
+      # `name` may be snake_case or camelCase, or a full signature such as `"transfer(address,uint256)"`
+      # (spaces are ignored). When several functions share the name, the overload is chosen by positional
+      # arity (`args.size`) or by the set of snake_cased keyword names (`kwargs.keys`).
+      #
+      # @param name [String, Symbol] function name or signature
+      # @param args [Array] positional arguments of the intended call, used to pick an overload by arity
+      # @param kwargs [Hash] keyword arguments of the intended call, used to pick an overload by names
+      # @return [Function]
+      # @raise [BlockGiven::FunctionNotFoundError] when no function has this name or signature, or when
+      #   no overload matches the given arguments
+      # @raise [BlockGiven::AmbiguousFunctionError] when several overloads match the arguments
+      # @example
+      #   interface.function(:balance_of)
+      #   interface.function("balanceOf")
+      #   interface.function(:safe_mint, args: [to, data])              # overload by arity
+      #   interface.function(:safe_mint, kwargs: { to: to, data: data })  # overload by keyword names
+      #   interface.function("safeMint(address,bytes)")                  # explicit signature
       def function(name, args: [], kwargs: {})
         name = name.to_s
         return function_by_signature(name) if name.include?("(")
@@ -77,15 +147,29 @@ module BlockGiven
               "no overload of #{name} matches the given arguments (#{candidates.map(&:signature).join(' | ')})"
       end
 
+      # Finds a function by its exact canonical signature.
+      #
+      # @param signature [String] for example `"transfer(address,uint256)"`; spaces are removed
+      # @return [Function]
+      # @raise [BlockGiven::FunctionNotFoundError] when no function has this signature
       def function_by_signature(signature)
         @functions.find { |f| f.signature == signature.delete(" ") } ||
           raise(FunctionNotFoundError, "no function with signature #{signature.inspect}")
       end
 
+      # Finds a function by its 4-byte selector.
+      #
+      # @param selector [String] `0x`-prefixed 4-byte selector, any case
+      # @return [Function, nil] `nil` when unknown
       def function_by_selector(selector)
         @functions.find { |f| f.selector == selector.downcase }
       end
 
+      # Finds an event by name (snake_case or camelCase) or by full signature.
+      #
+      # @param name [String, Symbol] for example `:Transfer`, `:transfer` or `"Transfer(address,address,uint256)"`
+      # @return [Event]
+      # @raise [BlockGiven::EventNotFoundError] when the ABI has no such event
       def event(name)
         name = name.to_s
         key = Utils.snake_case(name).to_sym
@@ -93,14 +177,25 @@ module BlockGiven
           raise(EventNotFoundError, "no event #{name.inspect} in ABI (known: #{@events.map(&:name).join(', ')})")
       end
 
+      # Finds a non-anonymous event by its `topics[0]` hash.
+      #
+      # @param topic [String] `0x`-prefixed 32-byte keccak hash of the event signature, any case
+      # @return [Event, nil] `nil` when unknown
       def event_by_topic(topic)
         @events.find { |e| e.topic == topic.to_s.downcase }
       end
 
+      # Finds a custom error by its 4-byte selector (the first 4 bytes of revert data).
+      #
+      # @param selector [String] `0x`-prefixed 4-byte selector, any case
+      # @return [CustomError, nil] `nil` when unknown
       def error_by_selector(selector)
         @errors.find { |e| e.selector == selector.to_s.downcase }
       end
 
+      # Compact representation with the number of functions, events and errors.
+      #
+      # @return [String]
       def inspect
         "#<BlockGiven::Abi::Interface functions=#{@functions.size} events=#{@events.size} errors=#{@errors.size}>"
       end

data/lib/block_given/abi/parameter.rb

@@ -2,10 +2,30 @@
 
 module BlockGiven
   module Abi
-    # One ABI input/output. Knows its canonical Solidity type ("(uint256,address)[]").
+    # One ABI input/output. Knows its canonical Solidity type (`"(uint256,address)[]"`).
+    #
+    # Parameters describe function inputs and outputs, event parameters, custom error arguments and
+    # tuple components. Unnamed parameters get a positional name (`arg0`, `arg1`...) so they can still
+    # be addressed, and are flagged with {#unnamed?}.
     class Parameter
+      # @!attribute [r] name
+      #   @return [String] the ABI name, or `"argN"` (N = position) when the ABI leaves it empty
+      # @!attribute [r] raw_type
+      #   @return [String] the type as written in the ABI (`"uint256"`, `"tuple[]"`, `"address[2]"`)
+      # @!attribute [r] components
+      #   @return [Array<Parameter>] the tuple components (empty for non-tuple types)
+      # @!attribute [r] indexed
+      #   @return [Boolean] whether an event parameter is `indexed`
+      # @!attribute [r] internal_type
+      #   @return [String, nil] the Solidity-side type from the ABI (`"struct Order"`, `"contract IERC20"`)
+      #     when present
       attr_reader :name, :raw_type, :components, :indexed, :internal_type
 
+      # Builds a parameter from its ABI definition.
+      #
+      # @param definition [Hash] the ABI entry (`"name"`, `"type"`, `"components"`, `"indexed"`,
+      #   `"internalType"`), String or Symbol keys
+      # @param index [Integer] position of the parameter, used to name unnamed ones (`"arg#{index}"`)
       def initialize(definition, index: 0)
         definition = definition.transform_keys(&:to_s)
         @name = definition["name"].to_s
@@ -17,21 +37,46 @@ module BlockGiven
         @components = Array(definition["components"]).each_with_index.map { |c, i| Parameter.new(c, index: i) }
       end
 
+      # Whether the ABI gives no name to this parameter (keyword arguments are then unavailable).
+      #
+      # @return [Boolean]
       def unnamed? = @unnamed
+
+      # Whether this event parameter is `indexed`.
+      #
+      # @return [Boolean]
       def indexed? = indexed
+
+      # The snake_case Symbol used for keyword arguments and decoded Hash keys (`_to` becomes `:to`,
+      # `tokenId` becomes `:token_id`).
+      #
+      # @return [Symbol]
       def ruby_name = Utils.snake_case(name).to_sym
 
+      # Whether the type is a tuple or an array of tuples (`"tuple"`, `"tuple[]"`, `"tuple[2]"`).
+      #
+      # @return [Boolean]
       def tuple? = raw_type.start_with?("tuple")
+
+      # Whether the type is an array, fixed (`"uint256[2]"`) or dynamic (`"uint256[]"`).
+      #
+      # @return [Boolean]
       def array? = raw_type.end_with?("]")
 
-      # "tuple[]" with components -> "(uint256,address)[]"
+      # The canonical type used in signatures, with tuples expanded from their components.
+      #
+      # @return [String] for example `"(uint256,address)[]"` for `"tuple[]"` with two components
       def type
         return raw_type unless tuple?
 
         raw_type.sub("tuple", "(#{components.map(&:type).join(',')})")
       end
 
-      # Base type without the outermost array dimension.
+      # The element parameter of an array type, i.e. this type without its outermost array dimension.
+      #
+      # @return [Parameter] a parameter with the same name and components, for `"uint256[][2]"` the
+      #   element is `"uint256[]"`
+      # @return [nil] when the type is not an array
       def element
         return nil unless array?
 
@@ -41,11 +86,23 @@ module BlockGiven
         )
       end
 
+      # Whether the type is dynamically sized in the ABI encoding.
+      #
+      # True for `string`, `bytes`, dynamic arrays, tuples with a dynamic component and fixed arrays of a
+      # dynamic element. Indexed event parameters of dynamic type are stored hashed in topics.
+      #
+      # @return [Boolean]
       def dynamic?
         raw_type == "string" || raw_type == "bytes" || raw_type.end_with?("[]") ||
           (tuple? && components.any?(&:dynamic?)) || (array? && element.dynamic?)
       end
 
+      # The ABI definition of this parameter, rebuilt with String keys.
+      #
+      # Unnamed parameters get an empty `"name"`, `"components"` is only present for tuples and
+      # `"indexed"` only when true; `internalType` is not included.
+      #
+      # @return [Hash{String => Object}]
       def to_h
         h = { "name" => unnamed? ? "" : name, "type" => raw_type }
         h["components"] = components.map(&:to_h) if tuple?

data/lib/block_given/abi/standards/erc1155.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    module Standards
+      # EIP-1155 with ERC-165, the metadata URI extension and the ERC-6093 errors (OpenZeppelin 5 naming).
+      ERC1155 = Definition.deep_freeze(
+        [
+          Definition.view("supportsInterface", ["bytes4 interfaceId"], ["bool"]),
+          Definition.view("balanceOf", ["address account", "uint256 id"], ["uint256"]),
+          Definition.view("balanceOfBatch", ["address[] accounts", "uint256[] ids"], ["uint256[]"]),
+          Definition.view("isApprovedForAll", ["address account", "address operator"], ["bool"]),
+          Definition.view("uri", ["uint256 id"], ["string"]),
+          Definition.write("setApprovalForAll", ["address operator", "bool approved"]),
+          Definition.write("safeTransferFrom",
+                           ["address from", "address to", "uint256 id", "uint256 value", "bytes data"]),
+          Definition.write("safeBatchTransferFrom",
+                           ["address from", "address to", "uint256[] ids", "uint256[] values", "bytes data"]),
+
+          Definition.event("TransferSingle",
+                           ["address operator indexed", "address from indexed", "address to indexed",
+                            "uint256 id", "uint256 value"]),
+          Definition.event("TransferBatch",
+                           ["address operator indexed", "address from indexed", "address to indexed",
+                            "uint256[] ids", "uint256[] values"]),
+          Definition.event("ApprovalForAll", ["address account indexed", "address operator indexed", "bool approved"]),
+          Definition.event("URI", ["string value", "uint256 id indexed"]),
+
+          Definition.error("ERC1155InsufficientBalance",
+                           ["address sender", "uint256 balance", "uint256 needed", "uint256 tokenId"]),
+          Definition.error("ERC1155InvalidSender", ["address sender"]),
+          Definition.error("ERC1155InvalidReceiver", ["address receiver"]),
+          Definition.error("ERC1155MissingApprovalForAll", ["address operator", "address owner"]),
+          Definition.error("ERC1155InvalidApprover", ["address approver"]),
+          Definition.error("ERC1155InvalidOperator", ["address operator"]),
+          Definition.error("ERC1155InvalidArrayLength", ["uint256 idsLength", "uint256 valuesLength"])
+        ]
+      )
+    end
+  end
+end

data/lib/block_given/abi/standards/erc20.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    module Standards
+      # EIP-20 with the optional metadata functions and the ERC-6093 errors, with the input names of
+      # OpenZeppelin 5 (`to` / `value`): the version those errors come from, and the names of the events.
+      ERC20 = Definition.deep_freeze(
+        [
+          Definition.view("name", [], ["string"]),
+          Definition.view("symbol", [], ["string"]),
+          Definition.view("decimals", [], ["uint8"]),
+          Definition.view("totalSupply", [], ["uint256"]),
+          Definition.view("balanceOf", ["address account"], ["uint256"]),
+          Definition.view("allowance", ["address owner", "address spender"], ["uint256"]),
+          Definition.write("approve", ["address spender", "uint256 value"], ["bool"]),
+          Definition.write("transfer", ["address to", "uint256 value"], ["bool"]),
+          Definition.write("transferFrom", ["address from", "address to", "uint256 value"], ["bool"]),
+
+          Definition.event("Transfer", ["address from indexed", "address to indexed", "uint256 value"]),
+          Definition.event("Approval", ["address owner indexed", "address spender indexed", "uint256 value"]),
+
+          Definition.error("ERC20InsufficientBalance", ["address sender", "uint256 balance", "uint256 needed"]),
+          Definition.error("ERC20InvalidSender", ["address sender"]),
+          Definition.error("ERC20InvalidReceiver", ["address receiver"]),
+          Definition.error("ERC20InsufficientAllowance", ["address spender", "uint256 allowance", "uint256 needed"]),
+          Definition.error("ERC20InvalidApprover", ["address approver"]),
+          Definition.error("ERC20InvalidSpender", ["address spender"])
+        ]
+      )
+    end
+  end
+end

data/lib/block_given/abi/standards/erc4626.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    module Standards
+      # EIP-4626 tokenized vault: the full ERC20 interface plus the vault functions, events and
+      # OpenZeppelin 5 errors.
+      ERC4626 = Definition.deep_freeze(
+        ERC20 + [
+          Definition.view("asset", [], ["address"]),
+          Definition.view("totalAssets", [], ["uint256"]),
+          Definition.view("convertToShares", ["uint256 assets"], ["uint256"]),
+          Definition.view("convertToAssets", ["uint256 shares"], ["uint256"]),
+          Definition.view("maxDeposit", ["address receiver"], ["uint256"]),
+          Definition.view("previewDeposit", ["uint256 assets"], ["uint256"]),
+          Definition.write("deposit", ["uint256 assets", "address receiver"], ["uint256"]),
+          Definition.view("maxMint", ["address receiver"], ["uint256"]),
+          Definition.view("previewMint", ["uint256 shares"], ["uint256"]),
+          Definition.write("mint", ["uint256 shares", "address receiver"], ["uint256"]),
+          Definition.view("maxWithdraw", ["address owner"], ["uint256"]),
+          Definition.view("previewWithdraw", ["uint256 assets"], ["uint256"]),
+          Definition.write("withdraw", ["uint256 assets", "address receiver", "address owner"], ["uint256"]),
+          Definition.view("maxRedeem", ["address owner"], ["uint256"]),
+          Definition.view("previewRedeem", ["uint256 shares"], ["uint256"]),
+          Definition.write("redeem", ["uint256 shares", "address receiver", "address owner"], ["uint256"]),
+
+          Definition.event("Deposit",
+                           ["address sender indexed", "address owner indexed", "uint256 assets", "uint256 shares"]),
+          Definition.event("Withdraw",
+                           ["address sender indexed", "address receiver indexed", "address owner indexed",
+                            "uint256 assets", "uint256 shares"]),
+
+          Definition.error("ERC4626ExceededMaxDeposit", ["address receiver", "uint256 assets", "uint256 max"]),
+          Definition.error("ERC4626ExceededMaxMint", ["address receiver", "uint256 shares", "uint256 max"]),
+          Definition.error("ERC4626ExceededMaxWithdraw", ["address owner", "uint256 assets", "uint256 max"]),
+          Definition.error("ERC4626ExceededMaxRedeem", ["address owner", "uint256 shares", "uint256 max"])
+        ]
+      )
+    end
+  end
+end

data/lib/block_given/abi/standards/erc721.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    module Standards
+      # EIP-721 with ERC-165, the metadata and enumerable extensions and the ERC-6093 / enumerable errors.
+      # Mutability follows OpenZeppelin (nonpayable) where EIP-721 says payable. Both `safeTransferFrom`
+      # overloads are present: pick one by arity or full signature ("safeTransferFrom(address,address,uint256,bytes)").
+      ERC721 = Definition.deep_freeze(
+        [
+          Definition.view("supportsInterface", ["bytes4 interfaceId"], ["bool"]),
+          Definition.view("balanceOf", ["address owner"], ["uint256"]),
+          Definition.view("ownerOf", ["uint256 tokenId"], ["address"]),
+          Definition.view("name", [], ["string"]),
+          Definition.view("symbol", [], ["string"]),
+          Definition.view("tokenURI", ["uint256 tokenId"], ["string"]),
+          Definition.view("getApproved", ["uint256 tokenId"], ["address"]),
+          Definition.view("isApprovedForAll", ["address owner", "address operator"], ["bool"]),
+          Definition.view("totalSupply", [], ["uint256"]),
+          Definition.view("tokenOfOwnerByIndex", ["address owner", "uint256 index"], ["uint256"]),
+          Definition.view("tokenByIndex", ["uint256 index"], ["uint256"]),
+          Definition.write("approve", ["address to", "uint256 tokenId"]),
+          Definition.write("setApprovalForAll", ["address operator", "bool approved"]),
+          Definition.write("transferFrom", ["address from", "address to", "uint256 tokenId"]),
+          Definition.write("safeTransferFrom", ["address from", "address to", "uint256 tokenId"]),
+          Definition.write("safeTransferFrom", ["address from", "address to", "uint256 tokenId", "bytes data"]),
+
+          Definition.event("Transfer", ["address from indexed", "address to indexed", "uint256 tokenId indexed"]),
+          Definition.event("Approval",
+                           ["address owner indexed", "address approved indexed", "uint256 tokenId indexed"]),
+          Definition.event("ApprovalForAll", ["address owner indexed", "address operator indexed", "bool approved"]),
+
+          Definition.error("ERC721InvalidOwner", ["address owner"]),
+          Definition.error("ERC721NonexistentToken", ["uint256 tokenId"]),
+          Definition.error("ERC721IncorrectOwner", ["address sender", "uint256 tokenId", "address owner"]),
+          Definition.error("ERC721InvalidSender", ["address sender"]),
+          Definition.error("ERC721InvalidReceiver", ["address receiver"]),
+          Definition.error("ERC721InsufficientApproval", ["address operator", "uint256 tokenId"]),
+          Definition.error("ERC721InvalidApprover", ["address approver"]),
+          Definition.error("ERC721InvalidOperator", ["address operator"]),
+          Definition.error("ERC721OutOfBoundsIndex", ["address owner", "uint256 index"]),
+          Definition.error("ERC721EnumerableForbiddenBatchMint", [])
+        ]
+      )
+    end
+  end
+end

data/lib/block_given/abi/standards.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    # Standard token interfaces shipped with the gem as plain ABI arrays (the same shape as a parsed
+    # JSON ABI): ERC20, ERC721, ERC1155 and ERC4626, with their ERC-6093 custom errors.
+    #
+    #   class Usdc < BlockGiven::Contract
+    #     abi :erc20                        # or: abi BlockGiven::Abi::Standards::ERC20
+    #     address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    #   end
+    #
+    # Your own contracts keep their ABIs in your application (see Contract.abi_file).
+    module Standards
+      # @return [Array<Symbol>] the names of the shipped standards, as {fetch} and `Contract.abi` accept them
+      NAMES = %i[erc20 erc721 erc1155 erc4626].freeze
+
+      class << self
+        # Shipped ABI by name: `:erc20`, `"ERC721"`, `"erc-1155"` all work.
+        #
+        # @param name [Symbol, String] the standard's name, case, dashes and underscores ignored
+        # @return [Array<Hash>] the deep-frozen JSON-ABI definitions of the standard
+        # @raise [BlockGiven::AbiError] when no shipped standard has that name
+        # @example
+        #   BlockGiven::Abi::Standards.fetch("ERC-721") # => [{"type"=>"function", "name"=>"balanceOf", ...}, ...]
+        def fetch(name)
+          key = name.to_s.downcase.delete("-_").to_sym
+          raise AbiError, "unknown ABI #{name.inspect} (shipped: #{NAMES.join(', ')})" unless NAMES.include?(key)
+
+          const_get(key.to_s.upcase, false)
+        end
+
+        # The names of the shipped standards.
+        #
+        # @return [Array<Symbol>] {NAMES}
+        # @example
+        #   BlockGiven::Abi::Standards.names # => [:erc20, :erc721, :erc1155, :erc4626]
+        def names = NAMES
+      end
+
+      # Builds JSON-ABI definitions from Solidity-like parameter strings ("address to", "uint256 id indexed").
+      # @api private
+      module Definition
+        module_function
+
+        # A `view` function definition.
+        #
+        # @param name [String] the function name
+        # @param inputs [Array<String>] Solidity-like parameters, see {params}
+        # @param outputs [Array<String>] Solidity-like return values, see {params}
+        # @return [Hash] the JSON-ABI function definition
+        def view(name, inputs, outputs) = function(name, inputs, outputs, "view")
+
+        # A `nonpayable` function definition.
+        #
+        # @param name [String] the function name
+        # @param inputs [Array<String>] Solidity-like parameters, see {params}
+        # @param outputs [Array<String>] Solidity-like return values, see {params}
+        # @return [Hash] the JSON-ABI function definition
+        def write(name, inputs, outputs = []) = function(name, inputs, outputs, "nonpayable")
+
+        # A function definition with an explicit state mutability.
+        #
+        # @param name [String] the function name
+        # @param inputs [Array<String>] Solidity-like parameters, see {params}
+        # @param outputs [Array<String>] Solidity-like return values, see {params}
+        # @param mutability [String] `"view"`, `"pure"`, `"nonpayable"` or `"payable"`
+        # @return [Hash] the JSON-ABI function definition
+        def function(name, inputs, outputs, mutability)
+          { "type" => "function", "name" => name, "stateMutability" => mutability,
+            "inputs" => params(inputs), "outputs" => params(outputs) }
+        end
+
+        # A non-anonymous event definition.
+        #
+        # @param name [String] the event name
+        # @param inputs [Array<String>] Solidity-like parameters, `indexed` as a third word, see {params}
+        # @return [Hash] the JSON-ABI event definition
+        def event(name, inputs)
+          { "type" => "event", "name" => name, "anonymous" => false, "inputs" => params(inputs) }
+        end
+
+        # A custom error definition.
+        #
+        # @param name [String] the error name
+        # @param inputs [Array<String>] Solidity-like parameters, see {params}
+        # @return [Hash] the JSON-ABI error definition
+        def error(name, inputs)
+          { "type" => "error", "name" => name, "inputs" => params(inputs) }
+        end
+
+        # JSON-ABI parameters from Solidity-like strings: `"<type> [name] [indexed]"`.
+        #
+        # @param list [Array<String>] e.g. `["address from indexed", "uint256 value"]`
+        # @return [Array<Hash>] the parameters, `"indexed" => true` when the third word is `indexed`
+        def params(list)
+          list.map do |entry|
+            type, name, indexed = entry.split
+            param = { "name" => name.to_s, "type" => type }
+            param["indexed"] = true if indexed == "indexed"
+            param
+          end
+        end
+
+        # Freezes a definition and everything it contains.
+        #
+        # @param value [Object] a Hash, an Array or a leaf value
+        # @return [Object] the same value, frozen with all its nested Hashes and Arrays
+        def deep_freeze(value)
+          case value
+          when Hash then value.each_value { |v| deep_freeze(v) }
+          when Array then value.each { |v| deep_freeze(v) }
+          end
+          value.freeze
+        end
+      end
+    end
+  end
+end
+
+require_relative "standards/erc20"
+require_relative "standards/erc721"
+require_relative "standards/erc1155"
+require_relative "standards/erc4626"