> ## 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.

# BrandedWei

> Data-first branded Wei 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>

# BrandedWei

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

## Overview

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

## Type Definition

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

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

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

## Construction

### `BrandedWei.from(value)`

Create BrandedWei from numeric input.

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

const wei1 = BrandedWei(1_000_000_000n)              // 1 Gwei in Wei
const wei2 = BrandedWei(1_000_000_000_000_000_000n)  // 1 Ether in Wei
const wei3 = BrandedWei("1000000000000000000")       // String input
const wei4 = BrandedWei(42)                          // Number input
```

**Parameters:**

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

**Returns:** `BrandedWei`

### `BrandedWei.fromGwei(gwei)`

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

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

const gwei = BrandedGwei(50n)
const wei = BrandedWei.fromGwei(gwei)  // 50_000_000_000n Wei
```

**Parameters:**

* `gwei: BrandedGwei` - Gwei amount

**Returns:** `BrandedWei`

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

### `BrandedWei.fromEther(ether)`

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

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

const ether = BrandedEther(1n)
const wei = BrandedWei.fromEther(ether)  // 1_000_000_000_000_000_000n Wei
```

**Parameters:**

* `ether: BrandedEther` - Ether amount

**Returns:** `BrandedWei`

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

## Conversions To Other Units

### `BrandedWei.toGwei(wei)`

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

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

const wei = BrandedWei(50_000_000_000n)
const gwei = BrandedWei.toGwei(wei)  // BrandedGwei(50n)

// Fractional values truncate
const wei2 = BrandedWei(50_000_000_001n)
const gwei2 = BrandedWei.toGwei(wei2)  // BrandedGwei(50n) - truncates
```

**Parameters:**

* `wei: BrandedWei` - Wei amount

**Returns:** `BrandedGwei`

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

### `BrandedWei.toEther(wei)`

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

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

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

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

**Parameters:**

* `wei: BrandedWei` - Wei amount

**Returns:** `BrandedEther`

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

## Conversions To Base Type

### `BrandedWei.toU256(wei)`

Convert BrandedWei to raw BrandedUint (removes denomination branding).

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

const wei = BrandedWei(1_000_000_000n)
const u256 = BrandedWei.toU256(wei)  // BrandedUint (no denomination)

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

**Parameters:**

* `wei: BrandedWei` - Wei amount

**Returns:** `BrandedUint`

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

## Constants

```typescript theme={null}
import { WEI_PER_GWEI, WEI_PER_ETHER } from 'tevm/BrandedWei'

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

## Usage Examples

### Gas Cost Calculation

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

const gasPrice = BrandedGwei(50n)  // 50 Gwei
const gasUsed = BrandedUint(21_000n)

// Convert to Wei for calculation
const gasPriceWei = BrandedGwei.toWei(gasPrice)
const gasPriceU256 = BrandedWei.toU256(gasPriceWei)

const totalCost = BrandedUint.times(gasPriceU256, gasUsed)
const totalCostWei = BrandedWei(totalCost)

console.log(`Cost: ${totalCostWei} Wei`)
```

### Transaction Value

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

const valueEther = BrandedEther(1n)  // 1 ETH
const valueWei = BrandedEther.toWei(valueEther)

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

### Conversion Chain

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

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

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

// Convert to Gwei
const gwei = BrandedWei.toGwei(wei)  // 1_000_000_000n

// Back to Ether
const etherAgain = BrandedGwei.toEther(gwei)  // 1n
```

## Type Safety

BrandedWei prevents mixing denominations at compile time:

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

const wei = BrandedWei(1_000_000_000n)
const gwei = BrandedGwei(1n)

// ✗ Type error - incompatible brands
BrandedWei.toGwei(gwei)

// ✓ Correct - explicit conversion
const weiFromGwei = BrandedGwei.toWei(gwei)
BrandedWei.toGwei(weiFromGwei)
```

## Performance

BrandedWei uses direct Uint8Array representation:

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

For maximum performance in tight loops, prefer BrandedWei over Wei namespace.

## When to Use BrandedWei

Use BrandedWei when:

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

## Related

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