BrandedHardfork

Branded type pattern for type-safe hardfork representation

Try it Live

Run Hardfork examples in the interactive playground

BrandedHardfork

Branded type pattern for type-safe hardfork representation.

Overview

BrandedHardfork uses TypeScript’s branded type pattern to create a distinct type from strings while maintaining runtime string behavior.

type BrandedHardfork = string & { readonly __tag: "Hardfork" };

Type Definition

BrandedHardfork Type

/**
 * Branded Hardfork type
 *
 * Hardfork is a branded string type that represents Ethereum protocol upgrades.
 * Each hardfork represents a protocol upgrade that changes EVM behavior,
 * gas costs, or adds new features.
 */
export type BrandedHardfork = string & {
  readonly __tag: "Hardfork";
};

Key Properties:

• Extends string - all string methods available
• Phantom __tag property - compile-time only, no runtime overhead
• Readonly - immutable by type system
• Nominal typing - distinct from plain strings

Branded Type Pattern

What is Branding?

Branding adds a phantom type property to distinguish similar types at compile time:

type UserId = string & { __tag: "UserId" };
type Email = string & { __tag: "Email" };

// Compile error - types are distinct
function sendEmail(email: Email) { }
const userId: UserId = "user123" as UserId;
sendEmail(userId);  // Error: UserId not assignable to Email

Why Use Branding?

Type Safety:

// Without branding - both are strings
function processNetwork(hardfork: string, chainId: string) {
  // Easy to swap arguments accidentally
}

// With branding - compile-time protection
function processNetwork(hardfork: BrandedHardfork, chainId: ChainId) {
  // Arguments can't be swapped
}

Runtime Behavior:

// Branded types are still strings at runtime
const fork: BrandedHardfork = "cancun" as BrandedHardfork;
console.log(typeof fork);  // "string"
console.log(fork.toUpperCase());  // "CANCUN"

No Runtime Overhead:

// Phantom property doesn't exist at runtime
const fork: BrandedHardfork = "cancun" as BrandedHardfork;
console.log(fork.__tag);  // undefined (not "Hardfork")

Implementation

Constants

All hardfork constants are branded strings:

// From constants.js
export const FRONTIER: BrandedHardfork = "frontier" as BrandedHardfork;
export const HOMESTEAD: BrandedHardfork = "homestead" as BrandedHardfork;
export const CANCUN: BrandedHardfork = "cancun" as BrandedHardfork;
// ...

Factory Function

function fromString(name: string): BrandedHardfork | undefined {
  const lower = name.toLowerCase();
  return NAME_TO_HARDFORK[lower];  // Returns branded type or undefined
}

Ordering Array

export const HARDFORK_ORDER: BrandedHardfork[] = [
  FRONTIER,
  HOMESTEAD,
  DAO,
  // ...
  OSAKA,
];

Name Lookup

export const NAME_TO_HARDFORK: Record<string, BrandedHardfork> = {
  frontier: FRONTIER,
  homestead: HOMESTEAD,
  // ...
  paris: MERGE,  // Alias
};

Usage Patterns

Type Guards

function isBrandedHardfork(value: unknown): value is BrandedHardfork {
  if (typeof value !== "string") return false;
  return Hardfork.isValidName(value);
}

// Usage
const input: unknown = getUserInput();
if (isBrandedHardfork(input)) {
  // input is BrandedHardfork here
  Hardfork.hasEIP1559(input);
}

Type Assertions

// Safe - validated first
const fork = Hardfork("cancun");
if (fork) {
  // fork is BrandedHardfork
}

// Unsafe - skip validation (use carefully)
const fork = "cancun" as BrandedHardfork;

Function Signatures

// Clear type requirements
function estimateGas(
  fork: BrandedHardfork,
  bytecode: Uint8Array
): bigint {
  if (Hardfork.hasEIP3855(fork)) {
    // PUSH0 available
  }
  // ...
}

// Can't accidentally pass wrong type
estimateGas("cancun", data);  // Error: string not BrandedHardfork
estimateGas(CANCUN, data);    // OK

Advantages

1. Compile-Time Safety

// Prevents mixing up similar string parameters
function compare(a: BrandedHardfork, b: BrandedHardfork): number {
  return Hardfork.compare(a, b);
}

// Can't accidentally swap with other strings
const chainId = "1";
compare(CANCUN, chainId);  // Error: string not assignable to BrandedHardfork

2. Self-Documenting Code

// Clear what type of string is expected
function getFeatures(fork: BrandedHardfork): Features {
  // Obviously dealing with hardfork, not just any string
}

3. Zero Runtime Cost

// No runtime overhead - still just strings
const fork: BrandedHardfork = "cancun" as BrandedHardfork;
console.log(fork.length);     // 6
console.log(fork[0]);          // "c"
console.log(fork.includes("c")); // true

Best Practices

1. Use Factory Functions

// Good - validated and branded
const fork = Hardfork(userInput);
if (!fork) throw new Error("Invalid hardfork");

// Bad - unsafe assertion
const fork = userInput as BrandedHardfork;

2. Validate at Boundaries

// Validate at system boundaries
function handleApiRequest(req: Request): Response {
  const hardforkStr = req.body.hardfork;

  // Validate and brand
  const fork = Hardfork(hardforkStr);
  if (!fork) {
    return badRequest("Invalid hardfork");
  }

  // Now type-safe throughout application
  return processRequest(fork);
}

3. Documentation

/**
 * Estimates gas for operation
 * @param fork - Ethereum hardfork version (e.g., CANCUN, SHANGHAI)
 * @param operation - Operation to estimate
 * @returns Estimated gas cost
 */
function estimateGas(fork: BrandedHardfork, operation: Operation): bigint {
  // ...
}

Related Branded Types

Similar pattern used throughout primitives:

// Address primitive
type AddressType = Uint8Array & { __tag: "Address" };

// Hex primitive
type HexType = string & { __tag: "Hex" };

// Hash primitive
type HashType = Uint8Array & { __tag: "Hash" };

Consistency Benefits:

• Similar API patterns across primitives
• Predictable type safety
• Zero runtime overhead across all types