This issue improves SDK correctness at the typing/documentation layer: no protocol change, but it prevents avoidable user crashes caused by misleading non-optional hints on outputs that are intentionally optional at runtime
Issue
CallDecoder decode methods in hypersync/init.py return lists where each element can be either:
- decoded values (list[DecodedSolValue])
- or None when calldata does not match loaded function signatures
However, several Python return annotations/documentation currently imply non-optional nested lists, which misleads users into unsafe indexing.
This is a Python API contract/documentation correctness issue .
User-facing impact
out = decoder.decode_inputs_sync(inputs)
print(out[0][0].val)
This crashes when out[0] is None:
TypeError: 'NoneType' object is not subscriptable
The crash is expected runtime behavior for unmatched selectors; the issue is that current type hints/docstrings don’t clearly communicate this.
Scope of fix
Expected return annotation shape
list[Optional[list[DecodedSolValue]]]
If we add this return type in the function then user gets the idea to handle None condition also .
Example : def decode_inputs_sync(self, inputs: list[str]) -> list[Optional[list[DecodedSolValue]]]:
Update Python wrapper type hints + docstrings in hypersync/init.py for CallDecoder methods so API contract reflects actual behavior.
Methods that should be optional-aware
- decode_inputs
- decode_inputs_sync
- decode_transactions_input
- decode_transactions_input_sync
- decode_traces_input
- decode_traces_input_sync
This issue improves SDK correctness at the typing/documentation layer: no protocol change, but it prevents avoidable user crashes caused by misleading non-optional hints on outputs that are intentionally optional at runtime
Issue
CallDecoder decode methods in hypersync/init.py return lists where each element can be either:
However, several Python return annotations/documentation currently imply non-optional nested lists, which misleads users into unsafe indexing.
This is a Python API contract/documentation correctness issue .
User-facing impact
This crashes when out[0] is None:
TypeError: 'NoneType' object is not subscriptableThe crash is expected runtime behavior for unmatched selectors; the issue is that current type hints/docstrings don’t clearly communicate this.
Scope of fix
Expected return annotation shape
list[Optional[list[DecodedSolValue]]]If we add this return type in the function then user gets the idea to handle None condition also .
Example :
def decode_inputs_sync(self, inputs: list[str]) -> list[Optional[list[DecodedSolValue]]]:Update Python wrapper type hints + docstrings in hypersync/init.py for CallDecoder methods so API contract reflects actual behavior.
Methods that should be optional-aware