poseidon

Documentation

Overview

Package poseidon implements Poseidon-over-Pallas-Fq, byte-identical to the neptune 13.0.0 reference used by the konareef pod-step ZK circuit (paygate-zk crates/konareef-circuit). It is the Go verifier-side counterpart of scripts/poseidon_pallas.py and the in-circuit gadgets in gadgets/memory_poseidon.rs / troot_poseidon.rs.

All parameters (modulus, domain tags, MDS matrices, round constants) are loaded from the pinned artifact konareef-pod-step-v1-poseidon-params-v1.json, whose SHA-256 is gated against ParamArtifactSHA256 so the Go, Rust, and Python implementations cannot silently diverge.

Field arithmetic uses math/big rather than a Montgomery implementation: a verifier hashes only a handful of nodes per proof, so constant-time/perf concerns do not apply, and mod-p big.Int mirrors the Python oracle exactly, removing the principal silent-divergence risk (parameter/field mismatch).

Index

• Constants
• type Params
  • func Default() *Params
  • func (pr *Params) EmptyRoots() [][32]byte
  • func (pr *Params) InternalHash(l, r [32]byte) ([32]byte, error)
  • func (pr *Params) LeafHash(vh [32]byte) ([32]byte, error)
  • func (pr *Params) RecordToField(record []byte) ([32]byte, error)
  • func (pr *Params) TRoot(records [][]byte) ([32]byte, error)
  • func (pr *Params) ValueHash(payload []byte) ([32]byte, error)

Constants

const MaxRecordBytes = 330

MaxRecordBytes is the pinned per-record cap (PRD 1 §5.4 / troot_poseidon.rs MAX_RECORD_BYTES). Records beyond this could not have been proven in-circuit.

const MaxTLogRecords = 16

MaxTLogRecords is the pinned tool-log record cap (PRD 1 §7 v1 / troot_poseidon.rs MAX_TLOG_RECORDS). Logs beyond this could not have been proven in-circuit.

const ParamArtifactSHA256 = "4aeda63ce430b5f0486bb31c0264923acc493e3d0ab45a92e19efe8ffe4bbf9f"

ParamArtifactSHA256 is the pinned digest of the parameter artifact. It mirrors the Rust circuit's param_drift_gate.rs constant. A drift here means the Go hash outputs would diverge from the circuit/verifier contract.

Types

type Params

type Params struct {
	// contains filtered or unexported fields
}

Params is a loaded, drift-checked set of the three Poseidon instances over the Pallas Fq field.

func Default

func Default() *Params

Default returns the Params loaded from the embedded pinned artifact. It panics if the embedded artifact fails its SHA-256 drift gate or cannot be parsed — both are build-time invariants, not recoverable runtime conditions.

func (*Params) EmptyRoots

func (pr *Params) EmptyRoots() [][32]byte

EmptyRoots returns the 21 empty-subtree roots E0..E20, where E0 = LeafHash(0) and E_k = InternalHash(E_{k-1}, E_{k-1}).

func (*Params) InternalHash

func (pr *Params) InternalHash(l, r [32]byte) ([32]byte, error)

InternalHash is the arity-2 node hash over preimage [l, r]. Both inputs must be canonical 32-byte little-endian field elements.

func (*Params) LeafHash

func (pr *Params) LeafHash(vh [32]byte) ([32]byte, error)

LeafHash is the arity-2 leaf hash over preimage [vh, 0].

func (*Params) RecordToField

func (pr *Params) RecordToField(record []byte) ([32]byte, error)

RecordToField folds one tool-log record's canonical bytes into a single field element (§5.4). Rejects records over MaxRecordBytes (fail-closed: the circuit could not have proven them).

func (*Params) TRoot

func (pr *Params) TRoot(records [][]byte) ([32]byte, error)

TRoot reconstructs the normative Poseidon t_root (§5.4): t_root = InternalHash(length_binding_element(|T|), tree_root_top(records)), where the length element carries the 0x03 count tag. Rejects logs over MaxTLogRecords fail-closed.

func (*Params) ValueHash

func (pr *Params) ValueHash(payload []byte) ([32]byte, error)

ValueHash is the arity-4 sponge hash over [length_element, c0, c1, c2], with chunks beyond those produced by payloadChunks zero-padded to fill the 4 lanes.