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

# SHA-256 Inline

> High-performance SHA-256 hash function for Jolt zkVM

## Overview

The SHA-256 inline provides an optimized implementation of the SHA-2 family hash function with 256-bit output. It offers significant performance improvements over standard SHA-256 implementations by using custom RISC-V instructions.

## API Reference

### `Sha256`

Main hasher struct that supports both streaming and one-shot hashing.

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

#### Methods

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

Creates a new SHA-256 hasher.

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

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

Writes data to the hasher incrementally. Can be called multiple times.

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

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

Finalizes the hash and returns the 32-byte digest. Consumes the hasher.

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

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

Computes SHA-256 hash in one call. Recommended for most use cases.

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

## Usage Examples

### Basic Usage

```rust theme={null}
use sha2_inline::Sha256;

#[jolt::provable]
fn verify_hash(data: &[u8], expected: [u8; 32]) -> bool {
    let hash = Sha256::digest(data);
    hash == expected
}
```

### Streaming API

For large inputs or when data arrives in chunks:

```rust theme={null}
use sha2_inline::Sha256;

#[jolt::provable]
fn hash_chunks(chunks: &[&[u8]]) -> [u8; 32] {
    let mut hasher = Sha256::new();
    for chunk in chunks {
        hasher.update(chunk);
    }
    hasher.finalize()
}
```

### Merkle Tree Leaf Hashing

```rust theme={null}
use sha2_inline::Sha256;

#[jolt::provable]
fn hash_leaf(index: u64, data: &[u8]) -> [u8; 32] {
    let mut hasher = Sha256::new();
    hasher.update(&index.to_le_bytes());
    hasher.update(data);
    hasher.finalize()
}
```

## Implementation Details

### Custom Instructions

The SHA-256 inline uses two custom RISC-V instructions:

1. **`SHA256_COMPRESSION`** (funct3=0x00, funct7=0x00): Performs SHA-256 compression with existing state
2. **`SHA256_COMPRESSION_INITIAL`** (funct3=0x01, funct7=0x00): Performs compression with initial IV constants

### Memory Layout

* **Input block**: 64 bytes (16 × 32-bit words)
* **State**: 32 bytes (8 × 32-bit words)
* **Output**: 32 bytes

### Endianness Handling

The implementation automatically handles endianness:

* On little-endian systems (RISC-V), uses `swap_bytes()` to convert to big-endian
* On big-endian systems, data is used directly

The `swap_bytes()` function uses a custom virtual instruction on RISC-V for performance:

```rust theme={null}
core::arch::asm!(
    ".insn i {opcode}, {funct3}, {r_inout}, {r_inout}, 0",
    opcode = const VIRTUAL_INSTRUCTION_TYPE_I_OPCODE,
    funct3 = const REV8W_FUNCT3,
    // ...
);
```

### Performance Characteristics

* **Block processing**: \~64 bytes per compression (512 bits)
* **Optimization**: Initial block uses specialized instruction that embeds IV constants
* **Memory efficiency**: Uses `MaybeUninit` for buffer allocation to reduce initialization overhead

## Comparison with Standard Implementation

When compared to the Rust `sha2` crate:

* **Cycle count**: \~10-100x reduction in VM cycles
* **Proving time**: Proportionally faster proof generation
* **Compatibility**: Drop-in replacement with identical output

## Feature Flags

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

## Safety Considerations

The implementation uses `unsafe` for:

* Inline assembly for custom RISC-V instructions
* Raw pointer operations for zero-copy buffer access
* `MaybeUninit` for performance optimization

All unsafe code is carefully reviewed and encapsulated within safe APIs.

## Source Code Location

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

## Constants

```rust theme={null}
pub const INLINE_OPCODE: u32 = 0x0B;
pub const SHA256_FUNCT3: u32 = 0x00;
pub const SHA256_FUNCT7: u32 = 0x00;
pub const SHA256_NAME: &str = "SHA256_INLINE";

pub const SHA256_INIT_FUNCT3: u32 = 0x01;
pub const SHA256_INIT_FUNCT7: u32 = 0x00;
pub const SHA256_INIT_NAME: &str = "SHA256_INIT_INLINE";
```

## See Also

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