> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

# Keccak-256 Inline

> High-performance Keccak-256 (SHA-3) hash function for Jolt zkVM

## Overview

The Keccak-256 inline provides an optimized implementation of the Keccak hash function (also known as SHA-3) with 256-bit output. It's commonly used in Ethereum and other blockchain applications.

## API Reference

### `Keccak256`

Main hasher struct supporting both streaming and one-shot hashing.

```rust theme={null}
pub struct Keccak256 {
    // Internal state - users don't need to access directly
}
```

#### Methods

##### `new() -> Self`

Creates a new Keccak-256 hasher.

```rust theme={null}
let mut hasher = Keccak256::new();
```

##### `update(&mut self, input: &[u8])`

Writes data to the hasher incrementally.

```rust theme={null}
let mut hasher = Keccak256::new();
hasher.update(b"hello ");
hasher.update(b"world");
```

##### `finalize(self) -> [u8; 32]`

Finalizes the hash and returns the 32-byte digest.

```rust theme={null}
let hash = hasher.finalize();
```

##### `digest(input: &[u8]) -> [u8; 32]`

Computes Keccak-256 hash in one call. Optimized for performance.

```rust theme={null}
let hash = Keccak256::digest(b"hello world");
```

## Usage Examples

### Ethereum Address Generation

```rust theme={null}
use keccak256_inline::Keccak256;

#[jolt::provable]
fn compute_ethereum_address(public_key: &[u8; 64]) -> [u8; 20] {
    let hash = Keccak256::digest(public_key);
    let mut address = [0u8; 20];
    address.copy_from_slice(&hash[12..32]);
    address
}
```

### Merkle Tree Hashing

```rust theme={null}
use keccak256_inline::Keccak256;

#[jolt::provable]
fn hash_pair(left: [u8; 32], right: [u8; 32]) -> [u8; 32] {
    let mut hasher = Keccak256::new();
    hasher.update(&left);
    hasher.update(&right);
    hasher.finalize()
}
```

### Streaming Large Data

```rust theme={null}
use keccak256_inline::Keccak256;

#[jolt::provable]
fn hash_transaction(tx_data: &[&[u8]]) -> [u8; 32] {
    let mut hasher = Keccak256::new();
    for field in tx_data {
        hasher.update(field);
    }
    hasher.finalize()
}
```

## Implementation Details

### Keccak-f\[1600] Permutation

The core operation is the Keccak-f\[1600] permutation function, which operates on a 1600-bit state (25 × 64-bit words). The inline uses a single custom instruction:

* **`KECCAK_F`** (funct3=0x00, funct7=0x01): Performs the full 24-round Keccak-f\[1600] permutation

### Memory Layout

* **State**: 200 bytes (25 × 64-bit words)
* **Rate**: 136 bytes (absorption rate for Keccak-256)
* **Capacity**: 64 bytes (security parameter)
* **Output**: 32 bytes

### Sponge Construction

Keccak uses the sponge construction:

1. **Absorb phase**: XOR input into state, permute
2. **Squeeze phase**: Extract output from state

For Keccak-256:

* Rate = 136 bytes (1088 bits)
* Capacity = 64 bytes (512 bits)
* Security level = 256 bits

### Padding

Keccak uses the following padding scheme:

```
padding = 0x01 || 0x00...00 || 0x80
```

* First byte after message: `0x01`
* Last byte of block: `0x80`
* If they overlap (single-byte padding): `0x81`

### Alignment Optimization

The `digest()` function includes alignment-aware optimizations:

```rust theme={null}
let is_aligned = input.as_ptr() as usize % 8 == 0;
if is_aligned {
    absorb_aligned(&mut state, block);
} else {
    absorb_unaligned(&mut state, block);
}
```

This provides optimal performance regardless of input buffer alignment.

## Performance Characteristics

* **Block size**: 136 bytes per permutation
* **Optimization**: Aligned memory access when possible
* **Zero-copy**: Direct state manipulation without intermediate buffers

## Type Definitions

```rust theme={null}
pub const NUM_LANES: usize = 25;
pub type Keccak256State = [u64; NUM_LANES];
```

## Feature Flags

* **`host`**: Enables reference implementation for host-side execution
  * Guest code: Compile WITHOUT this feature
  * Prover code: Compile WITH this feature

## Constants

```rust theme={null}
pub const INLINE_OPCODE: u32 = 0x0B;
pub const KECCAK256_FUNCT3: u32 = 0x00;
pub const KECCAK256_FUNCT7: u32 = 0x01;
pub const KECCAK256_NAME: &str = "KECCAK256_INLINE";
```

## Comparison with Standard Implementation

When compared to the Rust `sha3` crate:

* **Cycle count**: \~10-100x reduction in VM cycles
* **Proving time**: Proportionally faster proof generation
* **Compatibility**: Identical output to `sha3::Keccak256`

## Safety Considerations

The implementation uses `unsafe` for:

* Inline assembly for the Keccak-f permutation instruction
* Raw pointer operations for zero-copy state access
* Endianness conversions on big-endian platforms

All unsafe code is encapsulated within safe APIs and thoroughly tested.

## Source Code Location

```
jolt-inlines/keccak256/
├── src/
│   ├── lib.rs          # Module definitions and constants
│   ├── sdk.rs          # Public API (Keccak256 struct)
│   ├── exec.rs         # Host-side reference implementation
│   └── sequence_builder.rs  # Instruction sequence generation
└── Cargo.toml
```

## See Also

* [SHA-256](/api/inlines/sha2) - Alternative hash function (SHA-2 family)
* [BLAKE2](/api/inlines/blake2) - BLAKE2b hash function
* [BLAKE3](/api/inlines/blake3) - BLAKE3 hash function
* [Inlines Overview](/api/inlines/overview) - General information about cryptographic inlines