Skip to main content

ZK Proofs on Stellar

X-Ray (Protocol 25) introduced native host functions for zero-knowledge-friendly primitives (BN254 and Poseidon/Poseidon2), marking an important milestone in a long-term strategy to equip developers with the execution-environment infrastructure needed to build compliance-forward, privacy-preserving applications using zero-knowledge cryptography. These primitives are foundational building blocks and do not, on their own, provide end-to-end private payments without additional higher-level protocol or application logic.

For more details on X-Ray, see this blog post.

BN254​

BN254 is a pairing-friendly elliptic curve defined over a 254-bit prime field, commonly used in zero-knowledge proof systems because it supports efficient bilinear pairings. These pairings enable succinct proof constructions where complex statements can be verified quickly on-chain or in constrained environments. BN254 is especially popular in blockchain ecosystems because its arithmetic and pairing operations are relatively efficient to implement and well supported by existing libraries and tooling.

While BN254 host functions provide the cryptographic operations needed for proof verification, developers must still generate proofs using higher-level systems (such as circuits written in Noir or Risc0 methods) and deploy verifier smart contracts on Stellar to implement complete zero-knowledge workflows.

BN254 host functions​

  • g1_add — adds two elliptic-curve points in the G1 group, producing a new point. This is commonly used to combine proof or verification values.
  • g1_mul — multiplies a G1 elliptic-curve point by an integer, returning a new point. This operation is a core building block in many proof verification calculations.
  • pairing_check — verifies a pairing equation over lists of G1 and G2 points. This is typically the final step when checking the validity of a BN254 pairing-based proof.

Resources​

Poseidon​

Poseidon is a cryptographic hash function specifically designed for zero-knowledge proof systems, where efficiency inside arithmetic circuits is critical. Unlike traditional hashes such as SHA-256, Poseidon is optimized to minimize the number of constraints required in zero-knowledge circuits by operating natively over finite fields used by zk-SNARKs. This makes it significantly faster and cheaper to prove and verify statements involving hashing, which is why Poseidon is widely used for commitments, Merkle trees, and nullifiers in zero-knowledge applications.

The Poseidon host functions expose the underlying permutation primitives, not complete hash functions: developers construct the hash function they need on top of a permutation (for example, with a sponge construction), then incorporate it into higher-level proof systems and pair it with Stellar verifier contracts to build end-to-end zero-knowledge application flows. Exposing the permutation, rather than a fixed hash, lets developers configure state size and round parameters to stay interoperable with other ZK systems.

Poseidon host functions​

In the Rust soroban-sdk, these functions are exposed through the CryptoHazmat interface and require enabling the SDK's hazmat-crypto feature — they are not accessible with the default SDK features.

  • poseidon_permutation - performs the Poseidon permutation on an input vector of field elements
  • poseidon2_permutation - performs the Poseidon2 permutation on an input vector of field elements

Resources​

note

Ready-made Poseidon hash functions (built on top of these permutation primitives) live in a separate Rust SDK: rs-soroban-poseidon.