Skip to content

Conversation

@abonander
Copy link
Contributor

@abonander abonander commented Nov 14, 2025

Summary

This ended up being harder than expected because the Serde data model has no support for 256-bit integers, and just serializing to bytes gave the wrong result because it adds a length prefix. This required quite a bit of hacking around.

These are problems we shouldn't have when we implement bespoke traits: #336

I ended up punting on explicitly adding any crate integrations, as there's no obvious winners:

  • ruint (used in the Alloy Ethereum SDK) only supports unsigned integers
  • primitive-types is specifically designed for use with Ethereum, and also only supports unsigned integers.
  • bnum (which I did use in the implementation) is worth watching because it supports both signed and unsigned integers, but to expose it now would be a SemVer hazard because it looks to have some major breaking changes on the horizon: Design choices and new features for big upcoming update to bnum isaacholt100/bnum#54
    • I spent a long time thinking about how best to hand-roll integer formatting for client-side binding in SQL but decided it would be better just to shell out to a decent-quality crate.
    • This one has zero dependencies by default which also makes it rather attractive.
  • num-bigint because it requires dynamic allocations

In most cases, these types have from_le_bytes/to_le_bytes (or from_little_endian/to_little_endian) methods that can be used to manually convert using {UInt256, Int256}::to_le_bytes and from_le_bytes, respectively.

closes #48
closes #308

CHANGELOG Description

  • Add clickhouse::types::{UInt256, Int256} for serializing and deserializing 256-bit integers.
    • Note that these are not general-purpose 256-bit integer types. Instead, conversion is provided via From and TryInto traits, and the from_le_bytes() and to_le_bytes() methods.
    • Several external crates were identified as possible integrations, but all had drawbacks. Support for these crates (or others) may be added upon request. See pull request feat: support Int256/UInt256 #352 for details.

Checklist

Delete items not relevant to your PR:

  • Unit and integration tests covering the common scenarios were added
  • A human-readable description of the changes was provided so that we can include it in CHANGELOG later

This was referenced Nov 14, 2025
@abonander abonander requested a review from slvrtrn November 14, 2025 04:11
@slvrtrn
Copy link
Contributor

slvrtrn commented Nov 14, 2025

just serializing to bytes gave the wrong result because it adds a length prefix. This required quite a bit of hacking around.

even similarly to FixedString with [u8; 32]? in that case, the prefix is not added, as it is serialized as a tuple IIRC

@abonander abonander merged commit 605eb10 into main Nov 17, 2025
6 checks passed
@abonander abonander deleted the ab/uint256 branch November 17, 2025 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Uint256 support with validation Support for UInt256

3 participants