hash

Documentation

Overview

Package hash provides an interface that hash functions (as gadget) should implement.

Index

• func Register(m Hash, builder func(api frontend.API) (FieldHasher, error))
• func RegisterCustomHash(name string, builder func(api frontend.API) (FieldHasher, error))
• type BinaryFixedLengthHasher
• type BinaryHasher
• type Compressor
• type FieldHasher
  • func GetFieldHasher(name string, api frontend.API) (FieldHasher, error)
  • func NewMerkleDamgardHasher(api frontend.API, f Compressor, initialState frontend.Variable) FieldHasher
• type Hash
  • func (m Hash) Available() bool
  • func (m Hash) New(api frontend.API) (FieldHasher, error)
  • func (m Hash) String() string
• type HasherConfig
• type Option
  • func WithMinimalLength(minimalLength int) Option
• type StateStorer

Functions

func Register

func Register(m Hash, builder func(api frontend.API) (FieldHasher, error))

Register registers a new hash function by its constant index. To ensure that the hash function is registered, import the corresponding hash gadget package so that it would call this method.

Alternatively, you can import the github.com/consensys/gnark/std/hash/all package which automatically registers all hash functions.

func RegisterCustomHash

func RegisterCustomHash(name string, builder func(api frontend.API) (FieldHasher, error))

RegisterCustomHash registers a new hash function by a name. To ensure that the hash function is registered, import the corresponding hash gadget package so that it would call this method.

Alternatively, you can import the github.com/consensys/gnark/std/hash/all package which automatically registers all hash functions.

Types

type BinaryFixedLengthHasher

type BinaryFixedLengthHasher interface {
	BinaryHasher
	// FixedLengthSum returns digest of the first length bytes. See the
	// [WithMinimalLength] option for setting lower bound on length.
	FixedLengthSum(length frontend.Variable) []uints.U8
}

BinaryFixedLengthHasher is like BinaryHasher, but assumes the length of the input is not full length as defined during compile time. This allows to compute digest of variable-length input, unlike BinaryHasher which assumes the length of the input is the total number of bytes written.

type BinaryHasher

type BinaryHasher interface {
	// Sum finalises the current hash and returns the digest.
	Sum() []uints.U8

	// Write writes more bytes into the current hash state.
	Write([]uints.U8)

	// Size returns the number of bytes this hash function returns in a call to
	// [BinaryHasher.Sum].
	Size() int
}

BinaryHasher hashes inputs into a short digest. It takes as inputs bytes and outputs byte array whose length depends on the underlying hash function. For SNARK-native hash functions use FieldHasher.

type Compressor

type Compressor interface {
	Compress(frontend.Variable, frontend.Variable) frontend.Variable
}

Compressor is a 2-1 one-way function. It takes two inputs and compresses them into one output.

NB! This is lossy compression, meaning that the output is not guaranteed to be unique for different inputs. The output is guaranteed to be the same for the same inputs.

The Compressor is used in the Merkle-Damgard construction to build a hash function.

type FieldHasher

type FieldHasher interface {
	// Sum computes the hash of the internal state of the hash function.
	Sum() frontend.Variable

	// Write populate the internal state of the hash function with data. The inputs are native field elements.
	Write(data ...frontend.Variable)

	// Reset empty the internal state and put the intermediate state to zero.
	Reset()
}

FieldHasher hashes inputs into a short digest. This interface mocks BinaryHasher, but is more suitable in-circuit by assuming the inputs are scalar field elements and outputs digest as a field element. Such hash functions are for example Poseidon, MiMC etc.

func GetFieldHasher

func GetFieldHasher(name string, api frontend.API) (FieldHasher, error)

GetFieldHasher retrieves a hash function by its name. The name should match the output of Hash.String or name used in RegisterCustomHash method. To ensure that the hash function is correctly registered (and thus available for getting with this method), import the corresponding hash gadget package so that it would call the Register or RegisterCustomHash method.

Alternatively, you can import the github.com/consensys/gnark/std/hash/all package which automatically registers all hash functions.

func NewMerkleDamgardHasher

func NewMerkleDamgardHasher(api frontend.API, f Compressor, initialState frontend.Variable) FieldHasher

NewMerkleDamgardHasher transforms a 2-1 one-way function into a hash initialState is a value whose preimage is not known

type Hash

type Hash uint

Hash represents a registered hash function.

const (
	// MIMC is the MiMC hash function over the native field of the curve.
	MIMC Hash = iota
	// POSEIDON2 is the Poseidon2 hash function over the native field of the curve.
	POSEIDON2
)

func (Hash) Available

func (m Hash) Available() bool

Available returns true if the hash function is available.

func (Hash) New

func (m Hash) New(api frontend.API) (FieldHasher, error)

New initializes the hash function. This is a convenience function which does not allow setting hash-specific options.

func (Hash) String

func (m Hash) String() string

Returns the unique identifier of the hash function as a string.

type HasherConfig

type HasherConfig struct {
	MinimalLength int
}

HasherConfig allows to configure the behavior of the hash constructors. Do not initialize the configuration directly but rather use the Option functions which perform correct initializations. This configuration is exported for importing in hash implementations.

type Option

type Option func(*HasherConfig) error

Option allows configuring the hash functions.

func WithMinimalLength

func WithMinimalLength(minimalLength int) Option

WithMinimalLength hints the minimal length of the input to the hash function. This allows to optimize the constraint count when calling [BinaryFixedLengthHasher.FixedLengthSum] as we can avoid selecting between the dummy padding and actual padding. If this option is not provided, then we assume the minimal length is 0.

type StateStorer

type StateStorer interface {
	FieldHasher
	// State retrieves the current state of the hash function. Calling this
	// method should not destroy the current state and allow continue the use of
	// the current hasher. The number of returned Variable is implementation
	// dependent.
	State() []frontend.Variable
	// SetState sets the state of the hash function from a previously stored
	// state retrieved using [StateStorer.State] method. The implementation
	// returns an error if the number of supplied Variable does not match the
	// number of Variable expected.
	SetState(state []frontend.Variable) error
}

StateStorer allows to store and retrieve the state of a hash function.