> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# BrandedEther

> Data-first branded Ether type with direct Uint8Array methods

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/denomination.ts">
  Run Denomination examples in the interactive playground
</Card>

# BrandedEther

Data-first branded Ether type - `BrandedUint` representing Ether denomination with zero-overhead runtime.

## Overview

`BrandedEther` is a branded `BrandedUint` (Uint8Array-based) providing compile-time type safety for Ether values with zero-overhead direct data representation.

## Type Definition

```typescript theme={null}
import type { BrandedUint } from 'tevm/BrandedUint'

export type BrandedEther = BrandedUint & { readonly __brand: unique symbol }
```

Inherits all `BrandedUint` properties - 32-byte Uint8Array with bigint arithmetic.

## Construction

### `BrandedEther.from(value)`

Create BrandedEther from numeric input.

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'

const ether1 = BrandedEther(1n)         // 1 Ether
const ether2 = BrandedEther(5n)         // 5 Ether
const ether3 = BrandedEther("10")       // String input
const ether4 = BrandedEther(0.5)        // Number (truncates to 0n)
```

**Parameters:**

* `value: bigint | number | string` - Value to convert

**Returns:** `BrandedEther`

**Note:** Fractional numbers truncate to integer Ether.

### `BrandedEther.fromWei(wei)`

Convert BrandedWei to BrandedEther (divide by 10^18).

```typescript theme={null}
import * as BrandedWei from 'tevm/BrandedWei'
import * as BrandedEther from 'tevm/BrandedEther'

const wei = BrandedWei(1_000_000_000_000_000_000n)
const ether = BrandedEther.fromWei(wei)  // 1n Ether

// Fractional values truncate
const wei2 = BrandedWei(500_000_000_000_000_000n)  // 0.5 ETH
const ether2 = BrandedEther.fromWei(wei2)  // 0n (truncates)
```

**Parameters:**

* `wei: BrandedWei` - Wei amount

**Returns:** `BrandedEther`

**Formula:** `ether = wei / 1_000_000_000_000_000_000` (integer division)

### `BrandedEther.fromGwei(gwei)`

Convert BrandedGwei to BrandedEther (divide by 10^9).

```typescript theme={null}
import * as BrandedGwei from 'tevm/BrandedGwei'
import * as BrandedEther from 'tevm/BrandedEther'

const gwei = BrandedGwei(1_000_000_000n)
const ether = BrandedEther.fromGwei(gwei)  // 1n Ether

// Fractional values truncate
const gwei2 = BrandedGwei(500_000_000n)  // 0.5 ETH
const ether2 = BrandedEther.fromGwei(gwei2)  // 0n (truncates)
```

**Parameters:**

* `gwei: BrandedGwei` - Gwei amount

**Returns:** `BrandedEther`

**Formula:** `ether = gwei / 1_000_000_000` (integer division)

## Conversions To Other Units

### `BrandedEther.toWei(ether)`

Convert BrandedEther to BrandedWei (multiply by 10^18).

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'

const ether = BrandedEther(1n)
const wei = BrandedEther.toWei(ether)  // BrandedWei(1_000_000_000_000_000_000n)

const ether2 = BrandedEther(5n)
const wei2 = BrandedEther.toWei(ether2)  // BrandedWei(5_000_000_000_000_000_000n)
```

**Parameters:**

* `ether: BrandedEther` - Ether amount

**Returns:** `BrandedWei`

**Formula:** `wei = ether * 1_000_000_000_000_000_000`

### `BrandedEther.toGwei(ether)`

Convert BrandedEther to BrandedGwei (multiply by 10^9).

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'

const ether = BrandedEther(1n)
const gwei = BrandedEther.toGwei(ether)  // BrandedGwei(1_000_000_000n)

const ether2 = BrandedEther(2n)
const gwei2 = BrandedEther.toGwei(ether2)  // BrandedGwei(2_000_000_000n)
```

**Parameters:**

* `ether: BrandedEther` - Ether amount

**Returns:** `BrandedGwei`

**Formula:** `gwei = ether * 1_000_000_000`

## Conversions To Base Type

### `BrandedEther.toU256(ether)`

Convert BrandedEther to raw BrandedUint (removes denomination branding).

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedUint from 'tevm/BrandedUint'

const ether = BrandedEther(5n)
const u256 = BrandedEther.toU256(ether)  // BrandedUint (no denomination)

// Can use with BrandedUint operations
const doubled = BrandedUint.times(u256, BrandedUint(2n))
```

**Parameters:**

* `ether: BrandedEther` - Ether amount

**Returns:** `BrandedUint`

**Note:** Removes denomination type safety. Use for arithmetic requiring `BrandedUint`.

## Constants

```typescript theme={null}
import { WEI_PER_ETHER, GWEI_PER_ETHER } from 'tevm/BrandedEther'

WEI_PER_ETHER   // 1_000_000_000_000_000_000n (10^18)
GWEI_PER_ETHER  // 1_000_000_000n (10^9)
```

## Usage Examples

### User Balance Display

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

// RPC returns balance in Wei
const balanceWei = BrandedWei(5_234_567_890_123_456_789n)

// Convert to Ether for display
const balanceEther = BrandedWei.toEther(balanceWei)  // 5n Ether

console.log(`Balance: ${balanceEther} ETH`)  // "Balance: 5 ETH"
```

### Transaction Value

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'

// User wants to send 1 ETH
const valueEther = BrandedEther(1n)

// Convert to Wei for transaction
const valueWei = BrandedEther.toWei(valueEther)

const tx = {
  to: "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  value: valueWei,  // Type-safe BrandedWei
  gasPrice: /* ... */,
}
```

### Balance Operations

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedUint from 'tevm/BrandedUint'

const balance = BrandedEther(10n)
const amount = BrandedEther(3n)

// Convert to Uint256 for arithmetic
const balanceU256 = BrandedEther.toU256(balance)
const amountU256 = BrandedEther.toU256(amount)

const remaining = BrandedUint.minus(balanceU256, amountU256)
const remainingEther = BrandedEther(remaining)  // 7n Ether

console.log(`Remaining: ${remainingEther} ETH`)
```

### Conversion Chain

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'
import * as BrandedGwei from 'tevm/BrandedGwei'

// Start with Ether (user input)
const ether = BrandedEther(1n)

// Convert to Wei (for calculations)
const wei = BrandedEther.toWei(ether)  // 1_000_000_000_000_000_000n

// Convert to Gwei (for gas price comparison)
const gwei = BrandedEther.toGwei(ether)  // 1_000_000_000n

// Back to Ether (for display)
const etherAgain = BrandedWei.toEther(wei)  // 1n
```

### Fractional Display

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'
import * as BrandedUint from 'tevm/BrandedUint'

// Balance with fractional Ether
const balanceWei = BrandedWei(1_500_000_000_000_000_000n)  // 1.5 ETH

// Convert to Ether (truncates)
const wholeEther = BrandedWei.toEther(balanceWei)  // 1n

// Calculate remainder for fractional display
const weiPerEther = BrandedUint(1_000_000_000_000_000_000n)
const balanceU256 = BrandedWei.toU256(balanceWei)
const remainder = BrandedUint.modulo(balanceU256, weiPerEther)

console.log(`${wholeEther}.${remainder} ETH`)  // "1.500000000000000000 ETH"
```

## Type Safety

BrandedEther prevents mixing denominations at compile time:

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

const ether = BrandedEther(1n)
const wei = BrandedWei(1_000_000_000_000_000_000n)

// ✗ Type error - incompatible brands
BrandedEther.toWei(wei)

// ✗ Type error - cannot compare different denominations
if (ether === wei) { }

// ✓ Correct - explicit conversion
const etherFromWei = BrandedWei.toEther(wei)
if (ether === etherFromWei) { }  // Type-safe comparison
```

## Performance

BrandedEther uses direct Uint8Array representation:

* Zero wrapper overhead
* Direct bigint arithmetic
* Optimal for hot paths
* Same memory layout as BrandedUint

For balance calculations in tight loops, prefer BrandedEther over Ether namespace.

## Common Ether Values

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'

// Common amounts
const ONE_ETH = BrandedEther(1n)
const TEN_ETH = BrandedEther(10n)
const HUNDRED_ETH = BrandedEther(100n)

// Contract deposits
const MIN_STAKE = BrandedEther(32n)     // ETH 2.0 validator stake
const SMALL_TX = BrandedEther(1n)       // Typical user transfer
const LARGE_TX = BrandedEther(100n)     // Large transfer
```

## Integer Division Notes

All conversions to Ether use integer division. Fractional Wei/Gwei amounts truncate:

```typescript theme={null}
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

// Less than 1 Ether truncates to 0
const smallWei = BrandedWei(999_999_999_999_999_999n)  // 0.999... ETH
const ether = BrandedWei.toEther(smallWei)  // 0n (truncates)

// Exact Ether amounts convert cleanly
const exactWei = BrandedWei(1_000_000_000_000_000_000n)  // 1.0 ETH
const exactEther = BrandedWei.toEther(exactWei)  // 1n
```

For fractional display, work with Wei and format manually (see Fractional Display example above).

## When to Use BrandedEther

Use BrandedEther when:

* Type safety is critical
* Working with existing BrandedUint infrastructure
* Building type-safe APIs
* Performance-sensitive balance operations

## Related

* [BrandedWei](/primitives/denomination/branded-wei) - Branded Wei type
* [BrandedGwei](/primitives/denomination/branded-gwei) - Branded Gwei type
* [BrandedUint](/primitives/uint/branded-uint) - Underlying branded Uint256 type
* [Conversions](/primitives/denomination/conversions) - Converting between units