Skip to main content

ICICLE Hashing in Golang

note

For a general overview of ICICLE's hashing logic and supported algorithms, check out the ICICLE Hashing Overview.

Warning

Using the Hash package requires go version 1.22

Overview​

The ICICLE library provides Golang bindings for hashing using a variety of cryptographic hash functions. These hash functions are optimized for both general-purpose data and cryptographic operations such as multi-scalar multiplication, commitment generation, and Merkle tree construction.

This guide will show you how to use the ICICLE hashing API in Golang with examples for common hash algorithms, such as Keccak-256, Keccak-512, SHA3-256, SHA3-512, Blake2s, and Poseidon.

Importing Hash Functions​

To use the hashing functions in Golang, you only need to import the hash package from the ICICLE Golang bindings. For example:

import (
  "github.com/ingonyama-zk/icicle/v3/wrappers/golang/hash"
)

API Usage​

1. Creating a Hasher Instance​

Each hash algorithm can be instantiated by calling its respective constructor. The New<Hash>Hasher function takes an optional default input size, which can be set to 0 unless required for a specific use case.

Example for Keccak-256:

keccakHasher := hash.NewKeccak256Hasher(0 /* default input size */)

2. Hashing a Simple String​

Once you have created a hasher instance, you can hash any input data, such as strings or byte arrays, and store the result in an output buffer. Here’s how to hash a simple string using Keccak-256:

import (
  "encoding/hex"

  "github.com/ingonyama-zk/icicle/v3/wrappers/golang/hash"
)

inputStrAsBytes := []bytes("I like ICICLE! It's so fast and simple")
keccakHasher, error := hash.NewKeccak256Hasher(0 /*default chunk size*/)
if error != runtime.Success {
  fmt.Println("error:", error)
  return
}

outputRef := make([]byte, 32)
keccakHasher.Hash(
  core.HostSliceFromElements(inputStrAsBytes),
  core.HostSliceFromElements(outputRef),
  core.GetDefaultHashConfig(),
)

// convert the output to a hex string for easy readability
outputAsHexStr = hex.EncodeToString(outputRef)
fmt.Println!("Hash(`", input_str, "`) =", &outputAsHexStr)

Using other hash algorithms is similar and only requires replacing the Hasher constructor with the relevant hashing algorithm.

3. Poseidon Example (field elements) and batch hashing​

The Poseidon hash is designed for cryptographic field elements and curves, making it ideal for use cases such as zero-knowledge proofs (ZKPs). Poseidon hash using babybear field:

note

Since poseidon is designed for use with field elements and curves, it is located within the field or curve packages and not in the Hash package though it does rely on using the Hash package.

import (
  "github.com/ingonyama-zk/icicle/v3/wrappers/golang/core"
  babybear "github.com/ingonyama-zk/icicle/v3/wrappers/golang/fields/babybear"
  "github.com/ingonyama-zk/icicle/v3/wrappers/golang/fields/babybear/poseidon"
)

batch := 1 << 4
t := 3 // Currently support arity of 3, 5, 9, 12
// (t - 1) is due to domainTag being non nil
// if domainTag is nil, then the input size should be `batch * t`
// See more in our tests: https://github.com/ingonyama-zk/icicle/blob/docs/v3/golang/poseidon/wrappers/golang/curves/bn254/tests/poseidon_test.go#L23-L27
inputsSize = batch * (t - 1)
inputs := babybear.GenerateScalars(inputsSize)
domainTag := babybear.GenerateScalars(1)[0]

outputsRef := make([]babybear.ScalarField, batch)
poseidonHasherRef, _ := poseidon.NewHasher(uint64(t), &domainTag)
poseidonHasherRef.Hash(
  core.HostSliceFromElements(inputs),
  core.HostSliceFromElements(outputsRef),
  core.GetDefaultHashConfig(),
)

poseidonHasherRef.Delete()