Introduce the Address type

[Padraic-O-Mhuiris]

Structural vs Nominal typing

One of the most discussed features in typescript is that around "non-structural (nominal)" typing. This thread goes back nearly 8 years on the subject.

For the unawares reader, typescript's type system considers a type A to be equivalent to type B if B has at least the same members of A.

interface Person {
    name: string;
    age: number,
}

interface Alien {
    name: string;
    age: number,
    planet: string;
}

declare const x: Alien
const y: Person = x // valid

declare const xx: Person
const y: Alien = xx // invalid

The informal label for this is duck-typing where there is a phrase "if it walks like a duck and quacks like a duck than it's probably a duck". This makes typescript's type system very flexible as developers can easily spin up their own interfaces where necessary and don't have to extend their dependency tree to find the exact type for an api.

A nominal type system has the property where all types are unique and distinct of each other, regardless of the nature of equivalence of their properties. Typescript does not support nominal types but as in the linked thread, there are discussions surrounding how they can be added. However, even in the current version of typescript, it is possible to implement a "simulation" of them while incurring some verbosity and minor inconveniences that I will touch on.

interface Person {
    __brand: "Person";
    name: string;
    age: number,
}

interface Alien {
    __brand: "Alien";
    name: string;
    age: number,
    planet: string;
}

declare const x: Alien
const y: Person = x // invalid
// Type 'Alien' is not assignable to type 'Person'.
// Types of property '__brand' are incompatible.
// Type '"Alien"' is not assignable to type '"Person"'.

The above example exemplifies a way where two objects which are structurally similar can be kept distinct through the inclusion of a "brand" property __brand. This is a very important tool in a typescript developer's toolbox because often when working in a project with multiple other developers, there may be an implicit rule that we should never assign an Alien to a Person even though the rules of the type system enable us to do so. By using the brand example above, we can make that rule explicit and have the compiler tell us when that mistake has been made, thus improving code quality and preventing bugs at the source.

That being said, the above is a somewhat contrived example and the intent could be expressed better using a higher generic type, e.g LifeForm<T extends "Alien" | "Person"> or using a kind enum where the implied hidden __brand would be replaced with an explicit kind property however that is a digression.

How to use Nominal types for domain modelling

Where this "nominal" typing approach is best used is in implementing constraints on primitive types, primarily string and number. This becomes very useful as we can explicitly and safely model an arbitrary domain at the cost of some runtime overhead. Imagine we wanted to mirror the uint8 datatype from the evm in a ts/js environment safely.

First lets introduce the Nominal generic type which will be used use now and later.

type Nominal<T extends string> = { readonly [k in T as `__${k}__`]: void }

On to the example:

type Uint8 = number & Nominal<"uint8"> // number & { __uint8__: void }

This approach technically isn't nominal typing as we can invoke another type Uint8Alt the same way and both will be equivalent. What is important is that it incurs a compile time constraint on the number type enabling us to do this:

declare const x: Uint8
declare const y: number

function doubleUint8(n: Uint8): Uint8 {
  return (n * 2) as Uint8 // * more on this in a sec
}

function doubleNumber(n: number): number {
  return n * 2
}

doubleUint8(x)  // valid
doubleNumber(x) // valid
doubleUint8(y)  // invalid
doubleNumber(y) // valid

No we nicely have doubleUint8(y) throwing a compile time error and also proves Uint8's backwards compatibility with the original number type when we call doubleNumber(x). However, the doubleUint8 operates exactly as doubleNumber does and merely dangerously recasts as a Uint8. This must be replaced with a type guard function:

function isUint8(n: number): n is Uint8 {
  return n >= 0 && n <= 255 && Number.isInteger(n)
}

We would rewrite doubleUint8 as:

function doubleUint8(n: Uint8): Uint8 {
  const x = n * 2;
  if (isUint8(x)) return x; // x is now a Uint8
  throw new Error("...") // alternatively wrap by using "% 256"
}

Having the type guard isUint8 gives us the guarantee of the correctness of our code at the cost of runtime overhead. This pattern is called "runtime type checking" as the developer must add functionality to validate domain constraints. Unfortunately, doing something like this in a real project is impractical as any operation over a "nominal number" like Uint8 will always revert to a number, e.g Uint8 + number = number. An extensive library would have to be written to redefine basic numeric operations and others to make it practical.

The Address type

One place where I think the "nominal" approach would be useful is in explicitly representing Ethereum addresses distinct from the string type. Much like a uuid, an "address" is unique and in it's usage is not "operated" on as often as numbers leaving only conversions to upper/lower casing. Once a string is validated as an address it is not subject to change and so once defined, there is not going to be huge overhead in using it.

Mirroring the Uint8 definition, the Address type would look like:

export type Address = string & Nominal<"address">

For the type guard, ideally the ethers.utils.isAddress() function would be that but it is trivial to wrap around that:

const isAddress = (val: string): val is Address => ethers.utils.isAddress(val)

Again much like Uint8, the Address type when used in a function interface will throw a compiler error but preserves backwards compatibility with string.

declare const x: Address;
declare const y: string;

function getEthBalanceAddress(a: Address) { ... }
function getEthBalanceString(a: string) { ... }

getEthBalanceAddress(x) // valid
getEthBalanceString(x)  // valid
getEthBalanceAddress(y) // invalid
getEthBalanceString(y)  // valid

Taking this example further we can extend on Address with another nominal "tag" to provide constraint on a particular address or a set of addresses.

type DaiAddress = Address & Nominal<"dai">

const isDaiAddress = (x: Address): x is DaiAddress => x === <DAI_ADDRESS>

type ERC20Address = Address & Nominal<"erc20">

const isERC20Address = (x: Address): x is ERC20Address => MY_LIST_OF_VALID_ERC20.some(erc20Address => erc20Address === x)

The goal of using this approach is that a developer building an SDK or frontend for a smart-contract system would be able to model the collection of valid addresses and discriminate the associated business logic for the correct "address" type in each case. To be clear, the above example would be what is built on the Address type that Ethers would provide.

There are some drawbacks that we would have to be aware about if we were to include this right now. One of the typical ways a developer may use these Address types is using them as keys in objects. We can create a type Record<Address, { ... }> but the operating on such an object using Object.keys or Object.entries will reduce the key Address type to a string. I believe the same is the case for lodash and other popular tooling. It may be the case that ethers would have to provide a keys or entries methods to ergonomically preserve the Address.

[ricmoo]

I will need to read-through this solution more, but my original plan was just to wait until nominal types are added to TypeScript.

I may move this to the “Ideas Discussion” area than an issue? I’ll read it over a few more times first though.

[Padraic-O-Mhuiris]

Great to hear. Yes, from my current reading on their progress with nominal types it's a way's off as it is arguably their most disruptive change. I haven't finished the full thesis as I fat-fingered post but am editing the final bits

[Padraic-O-Mhuiris]

@ricmoo Feel free to move to an Idea Discussion. There are certainly multiple implications to introducing this that would have to be thrashed out.

[Padraic-O-Mhuiris]

@ricmoo I'm thinking of submitting a mvp PR of what I think this approach might look like in the v6 beta. I have looked at some of the v6 beta branch (which may I see includes bigint for evm num types! +1), specifically the address.ts which I imagine where this would live. One question I have is if there is any place where an "address" is implied by any other type other than a string.

[ricmoo]

I’m still a bit apprehensive about using an adhoc solution for nominal types, but yes string is the only type for an address. There are also Addressable types, such as Contract and Signer which can get used as addresses in any async context, and Promise will also be included in async contexts for addresses too.

[Padraic-O-Mhuiris]

I do entirely agree on being apprehensive, I'd much prefer if a solution emerged that was initially opt-in as I imagine such a change would be cumbersome for some developers who use typescript less-strictly and for also preserving backwards-compatibility. How that may work given the architecture I'm not sure.
The point I will make about it being an ad hoc solution is that developers who want something like this are waiting a long time for an official stance from the typescript team on anything concrete for microsoft/TypeScript#202. We could be waiting a lot longer yet, however they do say they are investigating it per their roadmap so who knows.

The downside risk I see is that if hypothetically ethers was to use this by default for v6 and typescript did emerge with a nominal solution differing from the one I suggested, it would be a possible breaking change.
The upside is that it allows developers to be much more prescriptive in how they want to model the ecosystem, imagine we wanted to differentiate between the Contract and Signer you mentioned. They both qualify as valid evm address strings but are very different in reality.

type Nominal<T extends string> = { readonly [k in T as `__${k}__`]: void }

type Address = string & Nominal<"address">

type ContractAddress = Address & Nominal<"contractAddress">

const isContractAddress = (address: Address): address is ContractAddress => ... // getCode

type SignerAddress = Address & Nominal<"signerAddress">

const isSignerAddress = (address: Address): address is SignerAddress => !isContractAddress(address)

[DeepDoge]

Instead of abusing underscores, using symbols here might be a better solution.

declare const Nominal: unique symbol;
export type Nominal<T extends string> = { [Nominal]: { [k in T]: void } };

export type Hex = string & Nominal<'Hex'>;
export type Address = Hex & Nominal<'Address'>;
export type ContractAddress = Address & Nominal<'ContractAddress'>;