Add to_json() to contract ABI objects

Author: fjarri

docs/changelog.rst

@@ -16,6 +16,7 @@ Added
 
 - Support for contract errors with anonymous fields. (PR_90_)
 - Support for partially named method arguments. (PR_91_)
+- ``to_json()`` methods in contract ABI objects. (PR_93_)
 
 
 Fixed
@@ -27,6 +28,7 @@ Fixed
 .. _PR_90: https://github.com/fjarri-eth/pons/pull/90
 .. _PR_91: https://github.com/fjarri-eth/pons/pull/91
 .. _PR_92: https://github.com/fjarri-eth/pons/pull/92
+.. _PR_93: https://github.com/fjarri-eth/pons/pull/93
 
 
 0.10.0 (2025-10-19)

pons/_contract_abi.py

@@ -173,6 +173,18 @@ def decode(self, value_bytes: bytes) -> FieldValues:
         """
         return FieldValues(list(zip(self.names, decode_args(self.types, value_bytes), strict=True)))
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        args = []
+        for name, tp in zip(self.names, self.types, strict=True):
+            args.append(
+                {
+                    "name": name if name is not None else "",
+                    "type": tp.canonical_form,
+                }
+            )
+        return args
+
     def __str__(self) -> str:
         fields = ", ".join(
             tp.canonical_form + ((" " + name) if name is not None else "")
@@ -297,6 +309,19 @@ def decode_log_entry(self, topics: Sequence[bytes], data: bytes) -> FieldValues:
 
         return FieldValues(decoded_data)
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        args: list[ABI_JSON] = []
+        for name, tp, indexed in zip(self.names, self.types, self.indexed, strict=True):
+            args.append(
+                {
+                    "indexed": indexed,
+                    "name": name if name is not None else "",
+                    "type": tp.canonical_form,
+                }
+            )
+        return args
+
     def __str__(self) -> str:
         params = []
         for name, tp, indexed in zip(self.names, self.types, self.indexed, strict=True):
@@ -359,6 +384,14 @@ def __call__(self, *args: Any, **kwargs: Any) -> "ConstructorCall":
         input_bytes = self.inputs.encode(self._inputs_signature.bind(*args, **kwargs).args)
         return ConstructorCall(input_bytes)
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "constructor",
+            "stateMutability": "payable" if self.payable else "nonpayable",
+            "inputs": self.inputs.to_json(),
+        }
+
     def __str__(self) -> str:
         return f"constructor{self.inputs} " + ("payable" if self.payable else "nonpayable")
 
@@ -515,6 +548,16 @@ def with_method(self, method: "Method") -> "MultiMethod":
         """Returns a multimethod resulting from joining this method with `method`."""
         return MultiMethod(self, method)
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "function",
+            "name": self.name,
+            "stateMutability": self._mutability.value,
+            "inputs": self.inputs.to_json(),
+            "outputs": self.outputs.to_json(),
+        }
+
     def __str__(self) -> str:
         returns = "" if not self.outputs.names else f" returns {self.outputs}"
         return f"function {self.name}{self.inputs} {self._mutability.value}{returns}"
@@ -586,6 +629,10 @@ def __call__(self, *args: Any, **kwds: Any) -> "MethodCall":
 
         raise TypeError("Could not find a suitable overloaded method for the given arguments")
 
+    def to_json(self) -> list[ABI_JSON]:
+        """Returns this object's JSON ABI."""
+        return [method.to_json() for method in self._methods.values()]
+
     def __str__(self) -> str:
         return "; ".join(str(method) for method in self._methods.values())
 
@@ -689,6 +736,15 @@ def decode_log_entry(self, log_entry: LogEntry) -> FieldValues:
 
         return self.fields.decode_log_entry([bytes(topic) for topic in topics], log_entry.data)
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "event",
+            "name": self.name,
+            "inputs": self.fields.to_json(),
+            "anonymous": self.anonymous,
+        }
+
     def __str__(self) -> str:
         return f"event {self.name}{self.fields}" + (" anonymous" if self.anonymous else "")
 
@@ -743,6 +799,14 @@ def decode_fields(self, data_bytes: bytes) -> FieldValues:
         """Decodes the error fields from the given packed data."""
         return self.fields.decode(data_bytes)
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "error",
+            "name": self.name,
+            "inputs": self.fields.to_json(),
+        }
+
     def __str__(self) -> str:
         return f"error {self.name}{self.fields}"
 
@@ -773,6 +837,13 @@ def from_json(cls, method_entry: ABI_JSON) -> "Fallback":
     def __init__(self, *, payable: bool = False):
         self.payable = payable
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "fallback",
+            "stateMutability": "payable" if self.payable else "nonpayable",
+        }
+
     def __str__(self) -> str:
         return "fallback() " + ("payable" if self.payable else "nonpayable")
 
@@ -801,6 +872,13 @@ def from_json(cls, method_entry: ABI_JSON) -> "Receive":
     def __init__(self, *, payable: bool = False):
         self.payable = payable
 
+    def to_json(self) -> ABI_JSON:
+        """Returns this object's JSON ABI."""
+        return {
+            "type": "receive",
+            "stateMutability": "payable" if self.payable else "nonpayable",
+        }
+
     def __str__(self) -> str:
         return "receive() " + ("payable" if self.payable else "nonpayable")
 
@@ -996,6 +1074,27 @@ def resolve_error(self, error_data: bytes) -> tuple[Error, FieldValues]:
 
         raise UnknownError(f"Could not find an error with selector {selector.hex()} in the ABI")
 
+    def to_json(self) -> ABI_JSON:
+        """Returns the serialized list of contract items (methods, errors, events)."""
+        all_items: Iterable[
+            Constructor | Fallback | Receive | Method | MultiMethod | Event | Error
+        ] = chain(
+            [self.constructor] if self.constructor else [],
+            [self.fallback] if self.fallback else [],
+            [self.receive] if self.receive else [],
+            self.method,
+            self.event,
+            self.error,
+        )
+        entries: list[ABI_JSON] = []
+        for item in all_items:
+            if isinstance(item, MultiMethod):
+                entries.extend(item.to_json())
+            else:
+                entries.append(item.to_json())
+
+        return entries
+
     def __str__(self) -> str:
         all_items: Iterable[
             Constructor | Fallback | Receive | Method | MultiMethod | Event | Error

tests/TestContractABI.sol

@@ -0,0 +1,91 @@
+pragma solidity >=0.8.0 <0.9.0;
+
+
+// A contract with various possible edge cases to test the conversion to/from JSON
+contract RoundTrip {
+    // A public field will generate a getter method
+    uint256 public field;
+
+    constructor(uint256 x) payable {
+        field = x;
+    }
+
+    receive() external payable {
+    }
+
+    // Note that the argument and the return type will not be present
+    // in the JSON ABI returned by `solc`.
+    fallback(bytes calldata) external payable returns (bytes memory) {
+    }
+
+    // Regular methods
+
+    function pureMethod(uint256 y) public view returns (uint256) {
+        revert();
+    }
+
+    function viewMethod(uint256 y) public view returns (uint256) {
+        revert();
+    }
+
+    function nonpayableMethod(uint256 y) public returns (uint256) {
+        revert();
+    }
+
+    function payableMethod(uint256 y) public payable returns (uint256) {
+        revert();
+    }
+
+    // A method with some unnamed arguments
+
+    function unnamedArgsMethod(uint256, address) public view returns (uint256) {
+        revert();
+    }
+
+    function partiallyNamedArgsMethod(uint256 y, address) public view returns (uint256) {
+        revert();
+    }
+
+    function partiallyNamedArgsAndReturnsMethod(uint256, address y) public view returns (uint256 z, uint256) {
+        revert();
+    }
+
+    // Overloaded method
+
+    function overloadedMethod(uint256 x) public view returns (uint256) {
+        revert();
+    }
+
+    function overloadedMethod(uint256 x, address y) public view returns (uint256) {
+        revert();
+    }
+
+    // Event with some fields indexed
+    event regularEvent(
+        uint32 indexed x,
+        uint256 y
+    );
+
+    // Anonymous event
+    event anonymousEvent(
+        uint32 x,
+        uint256 indexed y
+    ) anonymous;
+
+    // An event with partially named fields
+    event partiallyNamedFieldsEvent(
+        uint32 x,
+        uint256,
+        uint32 indexed y,
+        uint256 indexed
+        );
+
+    // Error with all fields named
+    error regularError(uint256 x, address y);
+
+    // Errors with some unnamed fields
+
+    error unnamedFieldsError(uint256, address);
+
+    error partiallyNamedFieldsError(uint256, address y);
+}

tests/test_contract_abi.py

@@ -1,6 +1,9 @@
 import re
+from copy import deepcopy
+from pathlib import Path
 
 import pytest
+import solcx
 from ethereum_rpc import Address, BlockHash, LogEntry, LogTopic, TxHash, keccak
 
 from pons import (
@@ -546,6 +549,63 @@ def test_contract_abi_json() -> None:
     assert isinstance(cabi.error.CustomError, Error)
 
 
+def clean_entries(abi: list[ABI_JSON]) -> list[ABI_JSON]:
+    """
+    Makes JSON ABI entries comparable.
+
+    Currently just removes `internalType` items (we do not support keeping them at the moment).
+    """
+    abi = deepcopy(abi)
+    for entry in abi:
+        assert isinstance(entry, dict)
+        if "inputs" in entry:
+            for arg in entry["inputs"]:
+                if "internalType" in arg:
+                    del arg["internalType"]
+        if "outputs" in entry:
+            for arg in entry["outputs"]:
+                if "internalType" in arg:
+                    del arg["internalType"]
+
+    return abi
+
+
+def test_json_roundtrip() -> None:
+    # Since we need the raw JSON ABI, we cannot use the existing compiler function
+    # (which wraps the ABI in `ContractABI` straight away).
+
+    compiled = solcx.compile_files(
+        [Path(__file__).resolve().parent / "TestContractABI.sol"],
+        output_values=["abi"],
+    )
+
+    results = {}
+    for identifier, compiled_contract in compiled.items():
+        _path, contract_name = identifier.split(":")
+        results[contract_name] = compiled_contract["abi"]
+
+    json_abi = results["RoundTrip"]
+
+    cabi = ContractABI.from_json(json_abi)
+
+    assert isinstance(json_abi, list)
+    json_abi_ref = clean_entries(json_abi)
+
+    json_abi_test = cabi.to_json()
+    assert isinstance(json_abi_test, list)
+    json_abi_test = clean_entries(json_abi_test)
+
+    # The comparison is a little tricky:
+    # - ABI entries are a list, and the order may have changed after the roundtrip
+    # - There will be multiple entries with the same name for overloaded methods
+
+    assert len(json_abi_ref) == len(json_abi_test)
+
+    for ref_entry in json_abi_ref:
+        matches = [entry for entry in json_abi_test if entry == ref_entry]
+        assert len(matches) == 1, "expected one and only one match for each entry"
+
+
 def test_contract_abi_init() -> None:
     cabi = ContractABI(
         constructor=Constructor(inputs=dict(a=abi.uint(8), b=abi.bool), payable=True),