Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add utility function for converting an address to checksummed string #5067

Merged
merged 9 commits into from
Jun 4, 2024
Merged

Add utility function for converting an address to checksummed string #5067

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
215452f
add implementation and tests
cairoeth Jun 3, 2024
3ef22ec
add changeset
cairoeth Jun 3, 2024
db76d54
use shared logic with _setHexString
cairoeth Jun 3, 2024
e05ab88
add addrValue to simplify
cairoeth Jun 3, 2024
b0967a8
use `addrValue`
cairoeth Jun 3, 2024
719978b
Apply PR recommendations
ernestognw Jun 3, 2024
f2ce027
rename to HEX_DIGITS_UPPERCASE
cairoeth Jun 3, 2024
ac713f0
Improve tests
ernestognw Jun 3, 2024
8f11b32
checksum in place to avoid double allocation + simplification
Amxx Jun 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/forty-dodos-visit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'openzeppelin-solidity': minor
---

`Strings`: Added a utility function for converting an address to checksummed string.
31 changes: 31 additions & 0 deletions contracts/utils/Strings.sol
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redesigned toChecksumHexString to avoid double allocation.

  • removed the need for _unsafeSetHexString
  • removed the need for HEX_DIGITS_UPPERCASE

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right this is extremely cleaner. Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great changes, thxs!

Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import {SignedMath} from "./math/SignedMath.sol";
*/
library Strings {
bytes16 private constant HEX_DIGITS = "0123456789abcdef";
bytes16 private constant HEX_DIGITS_CAPITAL = "0123456789ABCDEF";
cairoeth marked this conversation as resolved.
Show resolved Hide resolved
uint8 private constant ADDRESS_LENGTH = 20;

/**
Expand Down Expand Up @@ -85,6 +86,36 @@ library Strings {
return toHexString(uint256(uint160(addr)), ADDRESS_LENGTH);
}

/**
* @dev Converts an `address` with fixed length of 20 bytes to its checksummed ASCII `string` hexadecimal
* representation, according to EIP-55.
*/
function toChecksumHexString(address addr) internal pure returns (string memory) {
uint160 localValue = uint160(addr);
bytes memory lowercase = new bytes(40);
for (uint256 i = 40; i > 0; --i) {
lowercase[i - 1] = HEX_DIGITS[localValue & 0xf];
localValue >>= 4;
}
bytes32 hashedAddr = keccak256(abi.encodePacked(lowercase));
Copy link
Collaborator

@Amxx Amxx Jun 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You often do abi.encodePacked(x) when x is already a bytes. (here and on line 107)

Used like this, abi.encodePacked is the identity function ... the output exactly match the input ... so it is not necessary. One thing that happens however, is that memory is allocated for this copy... there is also a copy loop (or a mcopy if we are lucky).

Anyway, this increasse costs and leaks memory, so we should avoid it!


bytes memory buffer = new bytes(42);
buffer[0] = "0";
buffer[1] = "x";
uint160 addrValue = uint160(addr);
cairoeth marked this conversation as resolved.
Show resolved Hide resolved
uint160 hashValue = uint160(bytes20(hashedAddr));
for (uint256 i = 41; i > 1; --i) {
if (hashValue & 0xf > 7) {
buffer[i] = HEX_DIGITS_CAPITAL[addrValue & 0xf];
} else {
buffer[i] = HEX_DIGITS[addrValue & 0xf];
}
ernestognw marked this conversation as resolved.
Show resolved Hide resolved
addrValue >>= 4;
hashValue >>= 4;
}
return string(abi.encodePacked(buffer));
}

/**
* @dev Returns true if the two strings are equal.
*/
Expand Down
12 changes: 12 additions & 0 deletions test/utils/Strings.test.js
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a rust implementation of this checksum algorithm in Foundry (as seen in cast), so it should be relatively trivial to make a PR and request for it to be exposed through VM.sol as with Base64.

With that, we can fuzz the implementation, which would be extremely valuable.
Not required for this PR though, but something to consider given that the changes we're making are somewhat relevant

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

totally -- fuzzing should be used in some of the other utils as well.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, feel free to open PRs adding fuzzing or Halmos FV to those utils you consider make sense

Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,18 @@ describe('Strings', function () {
});
});

describe('toChecksumHexString address', function () {
it('converts a random address', async function () {
const addr = '0xa9036907dccae6a1e0033479b12e837e5cf5a02f';
expect(await this.mock.getFunction('$toChecksumHexString(address)')(addr)).to.equal(ethers.getAddress(addr));
});

it('converts an address with leading zeros', async function () {
const addr = '0x0000e0ca771e21bd00057f54a68c30d400000000';
expect(await this.mock.getFunction('$toChecksumHexString(address)')(addr)).to.equal(ethers.getAddress(addr));
});
});
Copy link
Member

@ernestognw ernestognw Jun 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a little consideration in the documentation of getAddress:

  • If %%address%% contains both upper-case and lower-case, it is
  • assumed to already be a checksum address and its checksum is
  • validated, and if the address fails its expected checksum an
  • error is thrown.

None of these tests are using mixed-case letters so I'd recommend adding .toLowerCase() according to the same docs:

  • If you wish the checksum of %%address%% to be ignore, it should
  • be converted to lower-case (i.e. .toLowercase()) before
  • being passed in.

Even better, let's rewrite these tests:

const addresses = [...]

describe('toChecksumHexString address', function () {
  for (const addr of addresses) {
    it(`converts ${addr}`, async function () {
      expect(await this.mock.getFunction('$toChecksumHexString(address)')(addr.toLowerCase())).to.equal(
        ethers.getAddress(addr),
      );
    });
  }
});

I'm pushing a commit


describe('equal', function () {
it('compares two empty strings', async function () {
expect(await this.mock.$equal('', '')).to.be.true;
Expand Down