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

# Bytes16

> Fixed-size 16-byte (128-bit) values with strict type safety

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

<Info>
  **Type-Safe Primitive** - Bytes16 provides compile-time guarantees for 16-byte values like UUIDs and medium hashes.
</Info>

## Overview

Bytes16 is a branded `Uint8Array` type representing exactly 16 bytes (128 bits). It provides strict size validation and type safety for fixed-size byte values.

```typescript theme={null}
import * as Bytes16 from 'tevm/primitives/Bytes/Bytes16';

// Create from hex
const bytes = Bytes16('0x' + '12'.repeat(16));
console.log(bytes.length); // 16

// Create zero-filled
const zeros = Bytes16.zero();
console.log(Bytes16.isZero(zeros)); // true

// Size is strictly enforced
Bytes16(new Uint8Array(15)); // Error: must be 16 bytes
```

## Use Cases

**UUIDs (128-bit)**

```typescript theme={null}
const uuid = Bytes16('550e8400e29b41d4a716446655440000');
```

**Medium Hashes**

```typescript theme={null}
// MD5, RIPEMD-128, etc.
const hash = Bytes16('0x...');
```

**Fixed-Size Keys**

```typescript theme={null}
const key = Bytes16('0x' + 'ab'.repeat(16));
```

## Type Safety

Bytes16 uses Symbol branding for compile-time safety:

```typescript theme={null}
type Bytes16Type = Uint8Array & {
  readonly [Symbol.for("Bytes16")]: true;
  readonly length: 16;
};
```

This prevents mixing different byte types:

```typescript theme={null}
const bytes16 = Bytes16('0x' + '12'.repeat(16));
const bytes32 = Bytes32('0x' + '12'.repeat(32));

// Type error: cannot assign Bytes32 to Bytes16
const wrong: Bytes16.Bytes16Type = bytes32;
```

### Hex Variants

Bytes16 also supports hex string variants with case flags:

```typescript theme={null}
// Lowercase hex (default)
type HexBytes16 = string & {
  readonly [Symbol.for("HexBytes16")]: true;
  readonly length: 34; // "0x" + 32 hex chars
  readonly lowercase: true;
};

// Uppercase hex
type HexBytes16Upper = string & {
  readonly [Symbol.for("HexBytes16")]: true;
  readonly length: 34;
  readonly uppercase: true;
};
```

For generic byte concepts, see [Bytes](/primitives/bytes).

## Constructors

### from

Create Bytes16 from hex string or bytes:

```typescript theme={null}
// From hex
const b1 = Bytes16('0x' + '12'.repeat(16));

// From bytes
const b2 = Bytes16(Bytes16());
```

### fromHex

Create from hex string with strict validation:

```typescript theme={null}
const bytes = Bytes16('0x1234567890abcdef1234567890abcdef');

// Without 0x prefix
const bytes2 = Bytes16('ab'.repeat(16));

// Throws on wrong length
Bytes16('0x1234'); // Error: must be 32 hex chars
```

### fromBytes

Create from Uint8Array with size check:

```typescript theme={null}
const arr = Bytes16();
const bytes = Bytes16(arr);

// Throws on wrong size
Bytes16(new Uint8Array(15)); // Error
```

### zero

Create zero-filled Bytes16:

```typescript theme={null}
const zeros = Bytes16.zero();
console.log(Bytes16.isZero(zeros)); // true
```

## Conversions

### toHex

Convert to hex string:

```typescript theme={null}
const bytes = Bytes16(Bytes16());
const hex = Bytes16.toHex(bytes);
console.log(hex); // "0x00000000000000000000000000000000"
```

### toUint8Array

Convert to raw bytes:

```typescript theme={null}
const bytes = Bytes16('0x' + '12'.repeat(16));
const arr = Bytes16.toUint8Array(bytes);
console.log(arr instanceof Uint8Array); // true
```

## Operations

### equals

Check equality:

```typescript theme={null}
const a = Bytes16('0x' + 'aa'.repeat(16));
const b = Bytes16('0x' + 'aa'.repeat(16));
console.log(Bytes16.equals(a, b)); // true
```

### compare

Compare two values:

```typescript theme={null}
const a = Bytes16('0x' + '01'.repeat(16));
const b = Bytes16('0x' + '02'.repeat(16));
console.log(Bytes16.compare(a, b)); // -1 (a < b)
```

### clone

Create independent copy:

```typescript theme={null}
const original = Bytes16('0x' + '12'.repeat(16));
const copy = Bytes16.clone(original);
```

### isZero

Check if all zeros:

```typescript theme={null}
const zeros = Bytes16.zero();
console.log(Bytes16.isZero(zeros)); // true

const nonZero = Bytes16('0x' + '00'.repeat(15) + '01');
console.log(Bytes16.isZero(nonZero)); // false
```

### size

Get size (always 16):

```typescript theme={null}
const bytes = Bytes16('0x' + '12'.repeat(16));
console.log(Bytes16.size(bytes)); // 16
```

## Constants

### SIZE

Bytes16 size in bytes:

```typescript theme={null}
console.log(Bytes16.SIZE); // 16
```

### ZERO

Zero-filled constant:

```typescript theme={null}
console.log(Bytes16.ZERO.length); // 16
console.log(Bytes16.isZero(Bytes16.ZERO)); // true
```

## Error Handling

Bytes16 validates size strictly:

```typescript theme={null}
try {
  Bytes16(new Uint8Array(15));
} catch (error) {
  console.log(error.code); // "BYTES16_INVALID_LENGTH"
  console.log(error.message); // "Bytes16 must be 16 bytes, got 15"
}

try {
  Bytes16('0x1234');
} catch (error) {
  console.log(error.code); // "BYTES16_INVALID_HEX_LENGTH"
  console.log(error.message); // "Bytes16 hex must be 32 characters..."
}
```

## Related

* [Bytes32](/primitives/bytes/bytes32) - 256-bit fixed-size bytes (most common)
* [Bytes64](/primitives/bytes/bytes64) - 512-bit fixed-size bytes
* [Keccak256](/crypto/keccak256) - 256-bit cryptographic hashes
* [Hex](/primitives/hex) - Variable-length hex strings