feat: add ContractAddress type #159

tdelabro · 2025-09-16T15:05:09Z

Add a ContractAddress wrapper type that guarantee the felt it contains is a valid starknet contract address.
Contain some quality of like function for string conversion

Not a breaking change

Discussion:
@xJonathanLEI suggested we add ClassHash too
I chose to exclude addresses 0x0 and 0x1 from the normal ContractAddress flow. You can still build them with the unchecked one. Should we add constant ContractAddress::ZERO and ContractAddress::ONE to make those special case more explicit?
Do we want to allow them at all? Is there a risk to make some API unusable downstream if those value are entierly excluded?

gabrielbosio

Some small comments

crates/starknet-types-core/src/contract_address.rs

tdelabro · 2025-09-23T22:04:39Z

@gabrielbosio do you have an opinion about the points I highlighted in the issue description?

gabrielbosio · 2025-09-24T22:09:30Z

@gabrielbosio do you have an opinion about the points I highlighted in the issue description?

It depends if we want to migrate the ContractAddress struct from the sequencer repo. If that's the case then the try_from method should only check for the upper bound like it's done here.

tdelabro · 2025-09-25T16:25:06Z

@dorimedini-starkware you are maintaining the sequencer repo?
What do you think?
Is there a reason not to have a common ContractAddress shared between the whole ecosystem (sequencer, starknet-rs, ...)

dorimedini-starkware · 2025-09-28T06:43:47Z

@dorimedini-starkware you are maintaining the sequencer repo? What do you think? Is there a reason not to have a common ContractAddress shared between the whole ecosystem (sequencer, starknet-rs, ...)

no reason I can think of, but this suggested implementation differs from ours in several ways, like:

we have another indirection (ContractAddress(pub PatriciaKey(Felt)) vs. ContractAddress(Felt))
we allow zero and one as valid addresses
we use derive_more::Display and derive_more::Deref
serde derives are not feature-gated

tdelabro · 2025-09-30T00:28:15Z

@dorimedini-starkware

If I remember correctly the intermediate indirection to PatriciaKey is made useless by the fact that the internal value is pub. Which mean you can freely overstep the types restriction ContractAddress(PatriciaKey(<Some totally non valid Felt value>)). So by making the internal hidden, and using From/TryFrom rather than value.0 we will increase the type safety, without need for internal nesting of types
This make sense. I believe we can ma them valid values, and just add a checking method is_regular_contract_address(&self) -> bool that allow for users to check if they are not receiving special address values. An alternative is to have a second type, in the same way we have NonZeroFelt, RegularContractAddress (or something). Maybe the best solution, as it is still optional, but provide the best protection for users willing to use it
Sure I can add those quality of life impl
You can just enable the feature and it will be the same. But it is a good practice to have non-core features requiring the import of depencies (like serde , num-traits, and so on) feature gated. It doesn't cost much and is a good practice.

crates/starknet-types-core/src/contract_address.rs

dorimedini-starkware · 2025-09-30T13:32:35Z

@dorimedini-starkware

1. If I remember correctly the intermediate indirection to `PatriciaKey` is made useless by the fact that the internal value is `pub`. Which mean you can freely overstep the types restriction `ContractAddress(PatriciaKey(<Some totally non valid Felt value>))`. So by making the internal hidden, and using `From`/`TryFrom` rather than `value.0` we will increase the type safety, without need for internal nesting of types

2. This make sense. I believe we can ma them valid values, and just add a checking method `is_regular_contract_address(&self) -> bool` that allow for users to check if they are not receiving special address values. An alternative is to have a second type, in the same way we have `NonZeroFelt`, `RegularContractAddress` (or something). Maybe the best solution, as it is still optional, but provide the best protection for users willing to use it

3. Sure I can add those quality of life `impl`

4. You can just enable the feature and it will be the same. But it is a good practice to have non-core features requiring the import of depencies (like `serde` , `num-traits`, and so on) feature gated. It doesn't cost much and is a good practice.

PatriciaKey is pub but it's internal Felt is not, and creating a PatriciaKey with an out of range Felt should panic. I'm not saying the safety changes, I'm saying changing this indirection will require wide refactors if and when we migrate our ContractAddress type
.
please do :)
makes sense.

all in all I have no issue with this addition; it may take time for us to migrate to this new type though

tdelabro · 2025-09-30T13:50:52Z

@dorimedini-starkware so do you want this crate to also add a PatriciaKey type. Would it be helpful for you?

dorimedini-starkware · 2025-09-30T14:06:32Z

@dorimedini-starkware so do you want this crate to also add a PatriciaKey type. Would it be helpful for you?

I guess it would make the transition less painful, so sure.
We use PatriciaKey to describe an index in any of our state trees (only one of which is actually indexed by contract addresses) - the class tree and each storage tree also need to be bound by the patricia key limit

tdelabro · 2025-09-30T18:36:12Z

@dorimedini-starkware going back to point 2.

using derive_more::Display, or manual impl end up being the same. So no worries here

Now regarding derive_more::Deref, we won't implement it and will ask you to use as_ref or into instead.
Indeed the Deref trait purpose is to create smart-pointers, to add on the native ownership semantic, not to perform implicit type conversion. I understand the attraction of having the compiler quietly do those for you, but this is not what this trait is designed for and can be surprising for the user.
It is a bit more verbose, but for the best.

crates/starknet-types-core/src/contract_address.rs

0xLucqs · 2025-10-06T17:03:14Z

crates/starknet-types-core/src/regular_contract_address.rs

+    feature = "parity-scale-codec",
+    derive(parity_scale_codec::Encode, parity_scale_codec::Decode)
+)]
+pub struct RegularContractAddress(ContractAddress);


what is this ?

Addresses that are not 0x0 and 0x1. Most users facing application code should never interact with the protocol special addresses. If they do, it is because of a bug.
It can be enforced at the type level this way.

@tdelabro note that not just 0x1 is "reserved", see here

sounds super confusing, why not add just a regular ContractAddress and have specific functions to create 0x1 etc etc ?

or go the other way around and create a type ReservedContractAddresses

@dorimedini-starkware thanks for the head ups. Those are not mention on the doc https://docs.starknet.io/learn/protocol/state#special-addresses

@0xLucqs the use case I envision is more the opposite of what you are describing.
I'm writing rust code that allows users to interact with some contracts deployed on chain.
By using RegularContractAddress instead of ContractAddress, I can guarantee that a bug where I send money to 0x0 or 0x1 due to some badly initialized value, or corrupted json deserialization, will never happen.
A good use case would be: any code that references a user account should use the most restrictive type of the two.

why not add just a regular ContractAddress and have specific functions to create 0x1

This is a good quality of like improvment (hardcoded const for reserved addresses). I will add it

@dorimedini-starkware thanks for the head ups. Those are not mention on the doc https://docs.starknet.io/learn/protocol/state#special-addresses

yeah, we should probably link to blockifier versioned constants for this. 0x3 is reserved without use ATM, but it is possible we will also use 0x3 and even 0x4 in the future. versioned constants should be the point of truth

dorimedini-starkware · 2025-10-08T07:36:48Z

@dorimedini-starkware going back to point 2.

using derive_more::Display, or manual impl end up being the same. So no worries here

Now regarding derive_more::Deref, we won't implement it and will ask you to use as_ref or into instead. Indeed the Deref trait purpose is to create smart-pointers, to add on the native ownership semantic, not to perform implicit type conversion. I understand the attraction of having the compiler quietly do those for you, but this is not what this trait is designed for and can be surprising for the user. It is a bit more verbose, but for the best.

the point was to get a Felt by doing **address, but we can refactor usages, not an issue

dorimedini-starkware · 2025-10-15T06:55:21Z

crates/starknet-types-core/src/regular_contract_address.rs

+    /// https://docs.starknet.io/learn/protocol/state#special-addresses
+    /// https://github.com/starkware-libs/sequencer/blob/ecd4779abef7bf345938a69f18ef70b6239d3a50/crates/blockifier/resources/blockifier_versioned_constants_0_15_0.json#L92-L97
+    pub fn is_regular_contract_address(&self) -> bool {
+        self > &Felt::THREE && self < &PATRICIA_KEY_UPPER_BOUND


maybe hard-coding Felt::THREE as the lower bound isn't ideal, consider defining RegularContractAddress::LOWER_BOUND or something

@dorimedini-starkware
Can you explain this to me too:
https://github.com/starkware-libs/starknet-api/blob/91fcc564b125c16ada9d956dcbfa2628415ca011/src/core.rs#L120C1-L121C101

It makes it look like the max contract address is not PATRICIA_KEY_UPPER_BOUND, but PATRICIA_KEY_UPPER_BOUND - 256.
Can you confirm this? And give me an explanation on why so that I can add it to the impl and doc in this PR

@dorimedini-starkware Do you have infos on this?

crates/starknet-types-core/src/contract_address.rs

tdelabro requested review from dan-starkware, gabrielbosio and pefontana as code owners September 16, 2025 15:05

tdelabro requested review from 0xLucqs, antiyro and xJonathanLEI September 16, 2025 15:05

tdelabro force-pushed the add-contract-address-type branch 2 times, most recently from bea90b3 to 02d6946 Compare September 16, 2025 15:15

gabrielbosio requested changes Sep 23, 2025

View reviewed changes

crates/starknet-types-core/src/contract_address.rs Outdated Show resolved Hide resolved

crates/starknet-types-core/src/contract_address.rs Outdated Show resolved Hide resolved

gabrielbosio self-requested a review September 23, 2025 21:50

gabrielbosio requested changes Sep 23, 2025

View reviewed changes

crates/starknet-types-core/src/contract_address.rs Outdated Show resolved Hide resolved

0xLucqs requested changes Sep 30, 2025

View reviewed changes

crates/starknet-types-core/src/contract_address.rs Outdated Show resolved Hide resolved

0xLucqs requested changes Oct 6, 2025

View reviewed changes

tdelabro force-pushed the add-contract-address-type branch from 67dd9f2 to 0f3e898 Compare October 13, 2025 15:49

tdelabro requested review from 0xLucqs, dorimedini-starkware and gabrielbosio October 13, 2025 17:45

dorimedini-starkware reviewed Oct 15, 2025

View reviewed changes

crates/starknet-types-core/src/contract_address.rs Outdated Show resolved Hide resolved

tdelabro force-pushed the add-contract-address-type branch from 794750f to 0ec371c Compare October 15, 2025 17:14

tdelabro force-pushed the add-contract-address-type branch from 0ec371c to 6143570 Compare October 15, 2025 17:23

tdelabro added 8 commits October 15, 2025 14:24

feat: add ContractAddress type

3183fd9

patricia key

41c3f69

feat: add PatriciaKey and RegularContractAddress types

bdece5e

doc: RegularContractAddress

dbe73a8

add 0x2 0x3 to reserved addresses

fe06694

rebase and rename method

0a1f96b

fix: different felt display if alloc not enabled

7b24a2a

feat: add UPPER_BOUND & LOWER_BOUND to all our new types

1a3ea40

tdelabro force-pushed the add-contract-address-type branch from 6143570 to 1a3ea40 Compare October 15, 2025 17:24

dorimedini-starkware approved these changes Oct 16, 2025

View reviewed changes

feat: add ContractAddress type #159

Are you sure you want to change the base?

feat: add ContractAddress type #159

Uh oh!

Conversation

tdelabro commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gabrielbosio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tdelabro commented Sep 23, 2025

Uh oh!

gabrielbosio commented Sep 24, 2025

Uh oh!

tdelabro commented Sep 25, 2025

Uh oh!

dorimedini-starkware commented Sep 28, 2025

Uh oh!

tdelabro commented Sep 30, 2025

Uh oh!

Uh oh!

dorimedini-starkware commented Sep 30, 2025

Uh oh!

tdelabro commented Sep 30, 2025

Uh oh!

dorimedini-starkware commented Sep 30, 2025

Uh oh!

tdelabro commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdelabro Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xLucqs Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdelabro Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dorimedini-starkware commented Oct 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tdelabro commented Sep 16, 2025 •

edited

Loading

tdelabro commented Sep 30, 2025 •

edited

Loading

tdelabro Oct 6, 2025 •

edited

Loading

0xLucqs Oct 8, 2025 •

edited

Loading

tdelabro Oct 8, 2025 •

edited

Loading