Protocol 25/26 host functions
Protocol 25/26 host functions
PoolPass does no userland Poseidon and no userland BN254 arithmetic. Both route through native Soroban host functions shipped in Stellar Protocol 25 (X-Ray) and 26 (Yardstick). This is what makes on-chain ZK verification cheap enough to be practical.
Why native host functions matter
A Groth16 verification is a handful of elliptic-curve pairings on BN254. Implemented in WASM, the pairings blow far past Soroban’s CPU instruction budget. As native host functions, the same operations are a single priced host call. The two relevant capabilities:
- CAP-0074, BN254. Native BN254 curve operations and pairing, used by the Groth16 verifier.
- CAP-0075, Poseidon. Native Poseidon hashing over BN254 Fr, used for leaves, the Merkle tree, the nullifier, and the commitment.
Every Poseidon hash in the PoolPass contract and the parity gate routes through soroban-poseidon to the native soroban-sdk host function. No contract in the repository contains a userland Poseidon or BN254 implementation.
Gate A, Poseidon parity equality
The parity gate proves the on-chain Poseidon agrees, byte for byte, with the off-chain library and the Circom circuit. This is the single most important piece of evidence in these docs, reproduced verbatim from docs/e2e-transcript.md:
Gate A, Poseidon parity equality
- Input pair, as BN254 Fr decimal strings: "1", "2".
- Off-chain library output: 115cc0f5e7d690413df64c6b9662e9cf2a3617f2743245519e19607a4417189a. Computed by the shared merkle-tools/poseidon.js path backed by circomlibjs 0.1.7.
- Circuit witness output: 115cc0f5e7d690413df64c6b9662e9cf2a3617f2743245519e19607a4417189a. Obtained from the witness generated by circuits/gates/poseidon_pair.circom for the same input pair.
- On-chain host output: 115cc0f5e7d690413df64c6b9662e9cf2a3617f2743245519e19607a4417189a. The Gate A contract returned this value for the forced testnet invocation 94e5d8…e4d5.
- Assertion: all three 32-byte hex strings are byte-identical, confirming off-chain, Circom, and Soroban-host Poseidon parity.
The selected variant is classic circomlib Poseidon over BN254 Fr. Two-input hashing uses t=3, R_F=8, and R_P=57; three-input hashing uses t=4, R_F=8, and R_P=56.
Gate B, native BN254 Groth16 verification
Gate B forces a native BN254 Groth16 verification on chain, proving the verifier path works against the host pairing function rather than a userland fallback:
testnet tx593c2516f1c8b431a0ff8cf09a82ba92eb467bfb0e6f1b72099bfb25d0490ee1Verified invocation: 593c25…0ee1.