BLAKE3 Inline

High-performance BLAKE3 hash function for Jolt zkVM

Overview

The BLAKE3 inline provides an optimized implementation of the BLAKE3 hash function with 256-bit output. BLAKE3 is significantly faster than BLAKE2, SHA-1, SHA-2, and SHA-3 while maintaining security.

The current implementation is optimized for inputs up to 64 bytes (single block).

API Reference

Blake3

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

pub struct Blake3 {
    // Internal state - users don't need to access directly
}

Methods

new() -> Self

Creates a new BLAKE3 hasher.

let mut hasher = Blake3::new();

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

Writes data to the hasher incrementally. Panics if total input exceeds 64 bytes.

let mut hasher = Blake3::new();
hasher.update(b"hello ");
hasher.update(b"world");

finalize(self) -> [u8; 32]

Finalizes the hash and returns the 32-byte digest.

let hash = hasher.finalize();

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

Computes BLAKE3 hash in one call. Input must be ≤64 bytes.

let hash = Blake3::digest(b"hello world");

AlignedHash32

8-byte aligned 32-byte hash/key type for efficient operations.

#[repr(align(8))]
pub struct AlignedHash32(pub [u8; 32]);

Methods

pub const fn new(bytes: [u8; 32]) -> Self;
pub const fn zeroed() -> Self;
pub fn as_bytes(&self) -> &[u8; 32];
pub fn as_bytes_mut(&mut self) -> &mut [u8; 32];

blake3_keyed64()

BLAKE3 keyed hash for 64-byte inputs (Merkle tree optimization).

pub fn blake3_keyed64(
    left: &AlignedHash32,
    right: &AlignedHash32,
    key: &mut AlignedHash32
)

This is equivalent to blake3::keyed_hash(key, left || right) but optimized for when left and right are in separate memory locations.

Usage Examples

Basic Hashing (≤64 bytes)

use blake3_inline::Blake3;

#[jolt::provable]
fn hash_short_data(data: &[u8]) -> [u8; 32] {
    assert!(data.len() <= 64);
    Blake3::digest(data)
}

Merkle Tree Parent Node

use blake3_inline::{blake3_keyed64, AlignedHash32, BLAKE3_IV};

#[jolt::provable]
fn hash_merkle_parent(left: [u8; 32], right: [u8; 32]) -> [u8; 32] {
    let left_aligned = AlignedHash32::new(left);
    let right_aligned = AlignedHash32::new(right);
    let mut iv = BLAKE3_IV;
    
    blake3_keyed64(&left_aligned, &right_aligned, &mut iv);
    iv.0
}

Streaming API (≤64 bytes total)

use blake3_inline::Blake3;

#[jolt::provable]
fn hash_fields(field1: &[u8], field2: &[u8]) -> [u8; 32] {
    let mut hasher = Blake3::new();
    hasher.update(field1);
    hasher.update(field2);
    hasher.finalize()
}

Implementation Details

Compression Function

BLAKE3 uses a ChaCha-like compression function:

• State: 8 × 32-bit words (256 bits)
• Message block: 16 × 32-bit words (512 bits)
• Counter: 2 × 32-bit words (64 bits)
• Flags: 1 × 32-bit word (32 bits)
• Rounds: 7 rounds

Custom Instructions

1. BLAKE3_COMPRESS (funct3=0x00, funct7=0x03): Standard compression
2. BLAKE3_KEYED64 (funct3=0x01, funct7=0x03): Keyed 64-byte hash for Merkle trees

BLAKE3 Flags

pub const FLAG_CHUNK_START: u32 = 1;
pub const FLAG_CHUNK_END: u32 = 2;
pub const FLAG_PARENT: u32 = 4;      // For Merkle tree parent nodes
pub const FLAG_ROOT: u32 = 8;
pub const FLAG_KEYED_HASH: u32 = 16;

Initialization Vector

pub const IV: [u32; 8] = [
    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
    0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
];

Message Scheduling

pub const MSG_SCHEDULE: [[usize; 16]; 7] = [
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
    [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8],
    // ... (5 more rounds)
];

Constants

pub const INLINE_OPCODE: u32 = 0x0B;
pub const BLAKE3_FUNCT3: u32 = 0x00;
pub const BLAKE3_KEYED64_FUNCT3: u32 = 0x01;
pub const BLAKE3_FUNCT7: u32 = 0x03;

pub const NUM_ROUNDS: u8 = 7;
pub const CHAINING_VALUE_LEN: usize = 8;
pub const MSG_BLOCK_LEN: usize = 16;
pub const BLOCK_INPUT_SIZE_IN_BYTES: usize = 64;
pub const OUTPUT_SIZE_IN_BYTES: usize = 32;

Input Size Limitation

The current implementation only supports inputs up to 64 bytes (single block):

if len > BLOCK_INPUT_SIZE_IN_BYTES {
    panic!("Input too large: {len} bytes, max is {BLOCK_INPUT_SIZE_IN_BYTES}");
}

This is sufficient for:

• Merkle tree nodes (2 × 32-byte hashes)
• Small messages
• Hash-based signatures

For larger inputs, use BLAKE2 or SHA-256 inlines instead.

Performance Characteristics

• Block size: 64 bytes per compression
• Output size: 32 bytes (256 bits)
• Speed: Fastest among all hash inlines
• Optimization: Specialized blake3_keyed64() for Merkle trees

Alignment Requirements

The AlignedHash32 type ensures 8-byte alignment for efficient 64-bit load/store operations:

#[repr(align(8))]
pub struct AlignedHash32(pub [u8; 32]);

This is critical for RISC-V performance.

Feature Flags

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

Comparison with Standard Implementation

When compared to the official blake3 crate:

• Cycle count: ~10-50x reduction for single-block inputs
• Proving time: Proportionally faster proof generation
• Compatibility: Identical output to blake3::hash()

Source Code Location

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

See Also

• BLAKE2 - Previous generation BLAKE hash
• SHA-256 - SHA-2 hash function
• Keccak-256 - SHA-3 hash function
• Inlines Overview - General information about cryptographic inlines