Imported from dusk-network/Poseidon252 (AGENTS.md). Install upstream with npx skills add dusk-network/Poseidon252. Copyright stays with the author.

AGENTS.md — dusk-poseidon

Care Level: Cryptographic — Elevated

Core hash function used across the Dusk stack (nullifiers, Merkle trees, encryption). A bug here affects consensus and privacy. See the root CLAUDE.md at ~/dusk/CLAUDE.md for cross-repo propagation rules.

Overview

Poseidon hash over the BLS12-381 scalar field. Uses the Hades252 permutation (8 full + 60 partial rounds, width 5) via the SAFE sponge framework. Single crate, no_std with alloc.

Commands

Run make help for the full target list.

Architecture

Key Files

Features

• zk — PLONK circuit gadgets (gates dusk-plonk)
• encryption — encrypt/decrypt module (gates dusk-safe/encryption)

Elevated Care Zones

The entire crate is a care zone — it is a consensus-critical hash function. Changes to the permutation constants, round structure, or sponge logic can silently break nullifier derivation, Merkle proofs, and on-chain encryption.

• Hades permutation (src/hades/): round constants, MDS matrix, and round structure must match the specification exactly.
• Domain separation (src/hash.rs): changing domain tags breaks compatibility with all downstream consumers.
• Encryption (src/encryption.rs): used for on-chain note encryption in Phoenix.

Conventions

• no_std with alloc — do not add std dependencies
• Always use --release for tests — the zk feature pulls in dusk-plonk, which is extremely slow in debug mode
• No unwrap()/expect() outside of tests — return errors instead
• No #[allow(...)] lint suppression — fix the underlying issue
• Run make fmt before committing (requires nightly toolchain)
• Run make clippy to check for warnings

Change Propagation

Git Conventions

• Default branch: master
• License: MPL-2.0

Commit messages

Format: <Description> — imperative mood, capitalize first word.

Cross-cutting prefixes (ci, docs, chore) for non-code changes.

Changelog

• Update CHANGELOG.md under [Unreleased] for any user-visible change
• Use the Keep a Changelog format
• Only link to GitHub issues — no other tracking identifiers
• Follow standard markdown formatting: separate headings from surrounding content with blank lines, leave a blank line before and after lists, and never have two headings back-to-back without a blank line between them