Consider the use of Opaque Types

[krzkaczor]

TypeScript's Opaque types (nominal types) allow the creation of a subset of a broader type e.g. an even number like 4. Opaque types add extra level of protection to the app by ensuring that certain types are always properly handled.

Here are some examples that I think would fit viem's domain nicely:

• Hex type - representing any Hex string
• Hash type - representing a 256-bit hash expressed as a string
• Address type - representing a string holding address with a checksum

Obviously, Viem already contains definitions of these types, using template literals such as:

export type Hex = `0x${string}`
export type Hash = `0x${string}`

The problem is that they are verified at the type level only. Use of opaque types can enforce runtime validation:

type StringLiteral<Type> = Type extends string ? (string extends Type ? never : Type) : never

declare const __OPAQUE_TYPE__: unique symbol

export type WithOpaque<Token extends string> = {
  readonly [__OPAQUE_TYPE__]: Token
}

export type Opaque<Type, Token extends string> = Token extends StringLiteral<Token> ? Type & WithOpaque<Token> : never


export type Hex = Opaque<ViemHex, 'Hex'>
export function Hex(hex: string): Hex {
  assert(hex.match(/^0x[0-9a-fA-F]+$/), `Invalid hex: ${hex}`)
  return hex as Hex
}

export type Hash = Opaque<ViemHash, 'Hash'>
export function Hash(hash: string): Hash {
  assert(hash.match(/^0x[0-9a-fA-F]{64}$/), `Invalid hash: ${hash}`)
  return hash as Hash
}

The only way to create Hex and Hash values is by using the Hex and Hash functions. This way, all values are automatically verified at runtime. Furthermore, one can't accidentally pass a Hex value when a Hash value is expected. But where a 0x${string} type is expected, it’s still fine to pass this new Hex type.

This gets even better for the Address type. The creator function can enforce checksumming the address. This enables safely comparing addresses with the == operator!

/**
 * Represents an Ethereum address with a checksum. i.e. 0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5
 */
export type CheckedAddress = Opaque<`0x${string}`, 'CheckedAddress'>
export function CheckedAddress(value: string): CheckedAddress {
  if (!isAddress(value)) {
    throw new Error(`Invalid address: ${value}`)
  }
  return getAddress(value) as CheckedAddress
}

To be clear, I suggest viem expose such opaque types in all public interfaces.

In our apps, we also introduced a bunch of numeric types such as BaseUnitNumber (e.g., 10^18) and NormalizedUnitNumber (e.g., 1). They allow to express that certain function works only with normalized units or the other way around, but I think they sit on the user-land side of things...

To see this in action across a bigger codebase, see usage of CheckedAddress in spark-app.

Attaching helpers

Creator functions as Hash are also an interesting place to put helpers such as this:

Hash.fromText = (text: string): Hash => {
  return Hash(keccak256(toHex(text)))
}

Drawbacks

A drawback of using Opaque types could be that developers can't use bare string literals anymore to represent values. Rather, such literals have to be wrapped with the creator function. In my experience, it's not a problem, and it actually very useful if the value gets loaded from an environment variable or elsewhere—we get validation for free, and in the past, it required ugly casts.

const a = '0x0x6b175474e89094c44da98b954eedeac495271d0f'
const b = process.env.DAI as any as Address
const c = CheckedAddress(process.env.DAI)

Another drawback could be a performance hit associated with those extra function calls, but this has a negligible effect in 99% of cases. If it really matters (in a very hot loop), one can always use the aforementioned "ugly" casts.

[tmm]

Thanks for posting this! Something we've been thinking about for a while. The main thing that comes to mind is should opaque (or more strict types) be the default behavior and should we make it configurable (via declaration merging)?

If we make it the default, then it will be a breaking change and might catch some folks off guard in their current workflows. I think stricter types are worth it, especially if we are able to nail the API. If it's not the default, then guessing most people won't know about it or enable it. Declaration merging similar to how ABIType is configured would work well in either case (opt in or opt out). Likely thinking this gets implemented in Ox. Maybe it's switched off by default there (since Ox is more unopinionated) and gets enabled in Viem by default.

Need to think more about the best approach for the implementation. What you've outlined above is very helpful.

Tagging @fubhy becuase he might have some thoughts on this.

[krzkaczor]

Good points, I thought about this as a breaking change but maybe there is a way to introduce it in a configurable manner 🤔. Either way, I think creator functions might be a great place to attach helpers like Hash.fromText, i added section about it in the original post.

[fubhy]

Yeah. This resonates with me. I've been pestering @tmm and @jxom about this for quite some time too.

As the JS/TS developer community and ecosystem evolves around us, fewer people are oblivious to the benefits of nominal typing techniques where they matter. Here, they definitely do. Thus, I feel pretty confident that this would be welcomed as a positive change by a majority of our users.

Ox should come with these pretty much for everything. Viem should then enforce these strictly at the I/O boundaries. Parse/decode/validate once, trust afterwards.

For some cases within Viem (any generic functionality where values are not accompanied by e.g. their ABI) it might even make sense to wrap things with even stronger & "runtime-robust" tagged types. The added runtime overhead of this usually armortizes itself through the simpler abstractions it enables (simple pattern matching instead of repeated type evaluation). But I reckognize that this will be a tough pill to swallow for some. I'm confident that we'll get there over time too though. One stept at a time ;-)

[SebastienGllmt]

A drawback of using Opaque types could be that developers can't use bare string literals anymore to represent values

This is not necessarily true. For Paima (which uses Viem under the hood for the upcoming v2) we used @coderspirit/nominal which exposes two different types:

1. Brands, which as you say require explicitly ugly casting
2. Flavors which do NOT require ugly casting on primitive types, yet still give you a compiler error if you try to mix two opaque types. Ex:
   1. ✅Hash -> string
   2. ✅string -> Hash
   3. ✖Hash -> Address
   4. ✖Address -> Hash

These "flavors" are super useful to have things "just work" if you're receiving a JSON payload from an external library (like receiving from Viem in our case). If you use the "brand"s, you have to ugly-cast entire payloads from libraries everywhere which gets ugly really quickly