Add EIP-55 checksum support and validation for EVM addresses

[iron-prog]

Problem

Currently, EvmAddress does not support EIP-55 checksum formatting or validation.

This can lead to incorrect address handling and lack of checksum-based error detection when working with EVM-compatible addresses.

Solution

Proposed improvements:

• Add checksum generation (EIP-55 compliant)
• Add address validation utilities
• Add checksum verification
• Add normalization support

This will improve correctness, safety, and developer experience when interacting with EVM addresses in the SDK.

Alternatives

No response

[manishdait]

@iron-prog, Thanks for raising this issue, while EIP-55 is a standard for Ethereum, The checksum casing is not a protocol requirement on Hedera itself at this moment. I do not think we should add these utilities directly to the SDK at this time. especially since other SDKs currently dont provide this either.

Like to hear @exploreriii opinion on this.

[iron-prog]

@manishdait Thanks for the clarification. My intention with pr was mainly to improve developer ergonomics and provide optional EIP-55-compatible utilities for users interacting with EVM-style addresses, rather than enforce checksum casing as a Hedera protocol requirement.

That said, I understand the concern about SDK surface area and consistency with the other SDKs. I’d be happy to adjust scope of the pr, or close the pr if the maintainers feel this functionality does not belong in the SDK at the moment.
Looking forward to know @exploreriii’s thoughts on this as well.

[rwalworth]

Thanks for raising this @iron-prog, and thanks for the thoughtful pushback @manishdait - chiming in with a few concerns I think are worth surfacing before this moves forward.

EIP-55 is purely an SDK concern

For context for anyone following along: EIP-55 is a mixed-case checksum encoding for the 20-byte hex address. The bytes don't change - only which hex letters are uppercased, derived from keccak256(lowercase_address). Its purpose is client-side typo detection.

This is entirely a presentation/validation layer:

• The Hedera consensus and mirror nodes only ever see 20 raw bytes - case doesn't exist at the binary level.
• No protocol change, no network behavior change, no on-chain difference.
• Implementing it is two pure functions: a checksum encoder and a checksum validator.

So the question really is just about SDK API surface and developer ergonomics, not protocol semantics.

The actual concern: this is a cross-SDK API decision, not a Python-only one

@manishdait is right that the other Hiero SDKs don't expose this today. That makes a Python-only addition risky - not because the code is wrong, but because the same logical address would render differently depending on which SDK produced the string. Java emits lowercase, Python emits mixed-case, downstream tooling diffs, and we end up with a subtle cross-SDK consistency bug that's painful to walk back later.

This feels like exactly the kind of cross-cutting decision the sdk-collaboration-hub exists for. If we want this, it should land as a design proposal in proposals/ (using templates/sdk-design-doc-template.md) so all the SDKs commit to the same shape - or explicitly opt out together.

Breaking-change risk depends entirely on the API shape chosen

This is the part I most want a design doc to pin down. Looking at the current Python implementation:

def to_string(self) -> str:
    """Return the EVM address as a hex string"""
    return bytes.hex(self.address_bytes)

to_string() today returns all-lowercase, no 0x prefix. Whether EIP-55 support is breaking comes down to which knob gets touched:

Design choice	Breaking?
Add new to_checksum_string() method, leave to_string() unchanged	No - pure addition
Add is_checksum_valid(s) static helper	No - pure addition
Add a separate from_checksum_string() constructor	No - pure addition
Change to_string() / __str__ to return mixed-case	Yes - breaks string comparisons, snapshot tests, log output, hashes, serialized data
Make from_string() reject mixed-case that fails checksum	Yes - breaks callers passing uppercase-but-not-EIP-55 strings (e.g. 0xABCD...)
Equality (__eq__)	Already byte-based, unaffected either way

The clean, non-breaking shape is additive only:

evm.to_string()                              # unchanged: lowercase, no checksum
evm.to_checksum_string()                     # new: EIP-55 mixed-case
EvmAddress.is_checksum_valid("0xfB69...")    # new: static validator

If we go that route, the design doc should explicitly commit that to_string() semantics do not change in any SDK. Otherwise we're back to the cross-SDK drift problem above.

One adjacent concern worth folding in

While we're here: to_string() not emitting the 0x prefix is already inconsistent with how most Ethereum tooling represents addresses. If EIP-55 gets discussed in a design doc, the prefix question should ride along - it's the same surface.

[iron-prog]

Thanks for the detailed feedback @manishdait — this makes a lot of sense.
My original intent with the PR was to keep the change strictly additive and non-breaking:

• preserve the existing lowercase behavior of to_string()
• add separate checksum utilities for validation only
• avoid changing equality or serialization semantics

I agree the bigger concern here is cross-SDK consistency rather than the Python implementation itself. It would definitely be problematic if different SDKs started emitting different canonical string forms for the same address type.

The point about routing this through sdk-collaboration-hub as a design/API discussion also seems reasonable, especially since the surface area touches:

• checksum formatting
• validation helpers
• canonical string representation
• optional 0x prefix behavior

I’ll take a look at the design proposal template and try to frame this as an additive cross-SDK API proposal rather than a Python-only behavior change.

Also agreed that to_string() semantics should remain unchanged if something like this moves forward.

[exploreriii]

Thanks everyone for the thoughtful discussion. Given the cross-SDK implications, I think the best path forward is to first submit a design proposal to the sdk-collaboration-hub repo, get some starter alignment on the API shape there, and then proceed with a first implementation. Even if the current Python PR is strictly additive, moving ahead before broader SDK alignment could create friction later, so a little time up front can save some thinking later

[iron-prog]

That makes sense — thanks everyone for the feedback and clarification around the cross-SDK implications.
I agree it’s better to align on the API shape first before introducing SDK-specific behavior that could change over time
I can work on drafting a proposal in sdk-collaboration-hub
Once there’s alignment there, I can revisit the Python implementation accordingly.

[iron-prog]

@rwalworth @exploreriii I have drafted a proposal according to discussion and guidance on sdk-collaboration-hub
https://github.com/hiero-ledger/sdk-collaboration-hub/pull/256

My 2nd year final exams are currently ongoing, so my response time may be a bit slower for a short period, but I’ll continue following the discussion and refining the proposal based on feedback whenever possible.Would appreciate feedback from maintainers whenever convenient

[github-actions]

Hello, this is CommunityCallBot.

This is a reminder that the Hiero Python SDK Community Call will begin in approximately 3 hours and 3 minutes (14:00 UTC).

The call is an open forum where contributors and users can discuss topics, raise issues, and influence the direction of the Python SDK.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.