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

/**
 * 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";
};

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

// 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
}

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

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

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

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

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

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

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);
}

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

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

// 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

// 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

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

// 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

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

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

// 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);
}

/**
 * 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 {
  // ...
}

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

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

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