@privacy-protocol/beacon

Client SDK for the Beacon ZK proof oracle. Generate membership proofs in the browser or Node and hand the (proof, publicInputs) straight to your consumer contract via VerifierHub.verify. Proving runs locally — secrets never leave the device.

Install

npm install @privacy-protocol/beacon @noir-lang/[email protected] @aztec/[email protected]

The two proving libraries are peer dependencies pinned to exact versions — they must match the versions the deployed verifier was built with, or proofs won't verify on-chain. Do not bump them independently of the deployed catalog circuit.

Usage

import { proveMembershipFromWitness, MEMBERSHIP_ID } from "@privacy-protocol/beacon";

// `scope` binds the proof to your app context (e.g. your contract address or a proposal id).
const { proof, publicInputs } = await proveMembershipFromWitness({
  scope: myContractAddress,        // bytes32 / bigint / hex
  secret,                          // the member's private identity secret
  leafIndex,                       // their position in the tree
  siblingPath,                     // their Merkle path (from the published member set)
  root,                            // the on-chain membership root
});

// publicInputs = [scope, root, nullifier]
await myGate.doGatedAction(proof, publicInputs); // your contract calls hub.verify(MEMBERSHIP_ID, ...)

Demo / small-group helper (one party holds all secrets):

import { proveMembershipFromSecrets } from "@privacy-protocol/beacon";
const res = await proveMembershipFromSecrets({ scope, secrets, voterIndex });

API

| Export | Purpose | | --- | --- | | proveMembershipFromWitness | Prove from a member's own witness (secret + sibling path). The production path. | | proveMembershipFromSecrets | Build the tree from all secrets + prove for one index (demo/small group). | | MEMBERSHIP_ID, CATALOG | On-chain circuit ids (match CircuitRegistry.circuitId). Pin these in your contract. | | circuitId(name, version) | Compute a circuit id, identical to the on-chain registry. | | createIdentity, computeLeaf, computeNullifier | Identity + commitment + nullifier helpers. | | buildMembershipTree, buildMembershipTreeFromLeaves | Poseidon2 Merkle tree (depth 32) + sibling paths. | | toBytes32, toField, requireField, poseidon2 | Field / hashing utilities. |

Develop

npm run typecheck
npm run smoke   # proves the demo inputs, checks deterministic outputs, writes the Foundry fixture
npm run build

npm run smoke writes a real proof to ../test/fixtures/membership_valid.json; running forge test in beacon/ then confirms the SDK's proof verifies against the on-chain verifier.

Toolchain: TypeScript 6 · viem 2 · @noir-lang/noir_js 1.0.0-beta.16 · @aztec/bb.js 3.0.0-nightly.20251104.