@bolyra/sdk 0.2.0 → 0.3.0

package/src/errors.ts

@@ -67,3 +67,49 @@ export class StaleProofError extends BolyraError {
     );
   }
 }
+
+export class InvalidSecretError extends BolyraError {
+  constructor(reason: string) {
+    super(
+      `Invalid secret: ${reason}. Provide a non-zero bigint less than the BN254 scalar field order (approx 2^254).`,
+      'INVALID_SECRET',
+      { reason }
+    );
+  }
+}
+
+export class CircuitArtifactNotFoundError extends ProofGenerationError {
+  constructor(artifactPath: string, artifactType: 'wasm' | 'zkey' | 'vkey') {
+    super(
+      artifactType === 'vkey' ? 'verification' : 'proof generation',
+      `Circuit artifact not found: ${artifactPath}. ` +
+        `Ensure the ${artifactType} file exists at this path. ` +
+        `If using a custom circuitDir, verify it contains the compiled circuit outputs. ` +
+        `Run the circuit build script or download trusted artifacts from the Bolyra release.`
+    );
+    this.code = 'CIRCUIT_ARTIFACT_NOT_FOUND';
+    this.details = { ...this.details, artifactPath, artifactType };
+  }
+}
+
+export class MerkleTreeError extends BolyraError {
+  constructor(reason: string, details?: Record<string, unknown>) {
+    super(
+      `Merkle tree operation failed: ${reason}. ` +
+        `Check that the tree is properly initialized and the leaf index is within bounds.`,
+      'MERKLE_TREE_ERROR',
+      { reason, ...details }
+    );
+  }
+}
+
+export class ConfigurationError extends BolyraError {
+  constructor(field: string, reason: string) {
+    super(
+      `Invalid SDK configuration for "${field}": ${reason}. ` +
+        `Review the BolyraConfig interface and ensure all required fields are set correctly.`,
+      'CONFIGURATION_ERROR',
+      { field, reason }
+    );
+  }
+}

package/src/handshake.ts

@@ -1,5 +1,6 @@
 import * as snarkjs from 'snarkjs';
 import * as path from 'path';
+import * as fs from 'fs';
 import {
   HumanIdentity,
   AgentCredential,
@@ -7,7 +8,8 @@ import {
   Proof,
   BolyraConfig,
 } from './types';
-import { ProofGenerationError } from './errors';
+import { ProofGenerationError, CircuitArtifactNotFoundError, VerificationError } from './errors';
+import { proveGroth16, ProverBackend } from './prover';
 
 // Default paths to circuit artifacts (relative to package root)
 const DEFAULT_CIRCUIT_DIR = path.join(__dirname, '../../circuits/build');
@@ -38,16 +40,37 @@ export async function proveHandshake(
     scope?: bigint;
     nonce?: bigint;
     config?: BolyraConfig;
+    backend?: ProverBackend;
   },
 ): Promise<{ humanProof: Proof; agentProof: Proof; nonce: bigint }> {
   const scope = options?.scope ?? 1n;
   const nonce = options?.nonce ?? BigInt(Date.now());
   const circuitDir = options?.config?.circuitDir ?? DEFAULT_CIRCUIT_DIR;
+  const backend = options?.backend ?? 'auto';
+
+  // Validate circuit artifacts exist before attempting proof generation
+  const humanWasm = path.join(circuitDir, 'HumanUniqueness_js/HumanUniqueness.wasm');
+  const humanZkey = path.join(circuitDir, 'HumanUniqueness_final.zkey');
+  const agentWasm = path.join(circuitDir, 'AgentPolicy_js/AgentPolicy.wasm');
+  const agentZkey = path.join(circuitDir, 'AgentPolicy_final.zkey');
+
+  if (!fs.existsSync(humanWasm)) {
+    throw new CircuitArtifactNotFoundError(humanWasm, 'wasm');
+  }
+  if (!fs.existsSync(humanZkey)) {
+    throw new CircuitArtifactNotFoundError(humanZkey, 'zkey');
+  }
+  if (!fs.existsSync(agentWasm)) {
+    throw new CircuitArtifactNotFoundError(agentWasm, 'wasm');
+  }
+  if (!fs.existsSync(agentZkey)) {
+    throw new CircuitArtifactNotFoundError(agentZkey, 'zkey');
+  }
 
   // Generate both proofs in parallel
   const [humanProof, agentProof] = await Promise.all([
-    generateHumanProof(human, scope, nonce, circuitDir),
-    generateAgentProof(agent, nonce, circuitDir),
+    generateHumanProof(human, scope, nonce, circuitDir, backend),
+    generateAgentProof(agent, nonce, circuitDir, backend),
   ]);
 
   return { humanProof, agentProof, nonce };
@@ -58,6 +81,7 @@ async function generateHumanProof(
   scope: bigint,
   nonce: bigint,
   circuitDir: string,
+  backend: ProverBackend,
 ): Promise<Proof> {
   const wasmPath = path.join(
     circuitDir,
@@ -78,12 +102,7 @@ async function generateHumanProof(
   };
 
   try {
-    const { proof, publicSignals } = await snarkjs.groth16.fullProve(
-      input,
-      wasmPath,
-      zkeyPath,
-    );
-    return { proof, publicSignals };
+    return await proveGroth16(input, wasmPath, zkeyPath, backend);
   } catch (err: any) {
     throw new ProofGenerationError(
       'HumanUniqueness',
@@ -96,12 +115,13 @@ async function generateAgentProof(
   agent: AgentCredential,
   nonce: bigint,
   circuitDir: string,
+  backend: ProverBackend,
 ): Promise<Proof> {
   const wasmPath = path.join(
     circuitDir,
     'AgentPolicy_js/AgentPolicy.wasm',
   );
-  const zkeyPath = path.join(circuitDir, 'AgentPolicy_plonk.zkey');
+  const zkeyPath = path.join(circuitDir, 'AgentPolicy_final.zkey');
 
   const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
   const requiredScopeMask = 0n; // no required scope for basic handshake
@@ -126,12 +146,7 @@ async function generateAgentProof(
   };
 
   try {
-    const { proof, publicSignals } = await snarkjs.plonk.fullProve(
-      input,
-      wasmPath,
-      zkeyPath,
-    );
-    return { proof, publicSignals };
+    return await proveGroth16(input, wasmPath, zkeyPath, backend);
   } catch (err: any) {
     throw new ProofGenerationError(
       'AgentPolicy',
@@ -158,8 +173,43 @@ export async function verifyHandshake(
 ): Promise<HandshakeResult> {
   const circuitDir = config?.circuitDir ?? DEFAULT_CIRCUIT_DIR;
 
-  // Verify human proof (Groth16)
+  // Validate proof structure before verification
+  if (!humanProof || !humanProof.proof || !Array.isArray(humanProof.publicSignals)) {
+    throw new VerificationError(
+      'Invalid humanProof structure: expected { proof: object, publicSignals: string[] }. ' +
+        'Ensure you are passing the proof object returned by proveHandshake().'
+    );
+  }
+  if (!agentProof || !agentProof.proof || !Array.isArray(agentProof.publicSignals)) {
+    throw new VerificationError(
+      'Invalid agentProof structure: expected { proof: object, publicSignals: string[] }. ' +
+        'Ensure you are passing the proof object returned by proveHandshake().'
+    );
+  }
+  if (humanProof.publicSignals.length < 2) {
+    throw new VerificationError(
+      `humanProof has ${humanProof.publicSignals.length} public signals, expected at least 2. ` +
+        'The proof may have been generated with an incompatible circuit version.'
+    );
+  }
+  if (agentProof.publicSignals.length < 3) {
+    throw new VerificationError(
+      `agentProof has ${agentProof.publicSignals.length} public signals, expected at least 3. ` +
+        'The proof may have been generated with an incompatible circuit version.'
+    );
+  }
+
+  // Verify vkey files exist
   const humanVkeyPath = path.join(circuitDir, 'HumanUniqueness_vkey.json');
+  if (!fs.existsSync(humanVkeyPath)) {
+    throw new CircuitArtifactNotFoundError(humanVkeyPath, 'vkey');
+  }
+  const agentVkeyPath = path.join(circuitDir, 'AgentPolicy_groth16_vkey.json');
+  if (!fs.existsSync(agentVkeyPath)) {
+    throw new CircuitArtifactNotFoundError(agentVkeyPath, 'vkey');
+  }
+
+  // Verify human proof (Groth16)
   const humanVkey = require(humanVkeyPath);
   const humanValid = await snarkjs.groth16.verify(
     humanVkey,
@@ -167,10 +217,9 @@ export async function verifyHandshake(
     humanProof.proof,
   );
 
-  // Verify agent proof (PLONK)
-  const agentVkeyPath = path.join(circuitDir, 'AgentPolicy_vkey.json');
+  // Verify agent proof (Groth16)
   const agentVkey = require(agentVkeyPath);
-  const agentValid = await snarkjs.plonk.verify(
+  const agentValid = await snarkjs.groth16.verify(
     agentVkey,
     agentProof.publicSignals,
     agentProof.proof,

package/src/identity.ts

@@ -1,6 +1,58 @@
 import { HumanIdentity, AgentCredential, Permission } from './types';
 import { poseidon2, poseidon5, eddsaSign, derivePublicKey, derivePublicKeyScalar } from './utils';
-import { InvalidPermissionError } from './errors';
+import { InvalidPermissionError, InvalidSecretError } from './errors';
+
+// BN254 scalar field order (Baby Jubjub subgroup order)
+export const BN254_FIELD_ORDER = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+
+/**
+ * Validate a secret value for use with createHumanIdentity.
+ * Throws InvalidSecretError if the secret is zero, negative, or exceeds BN254 field.
+ *
+ * Call this before createHumanIdentity() for strict input validation.
+ * createHumanIdentity itself is permissive (the crypto layer handles reduction),
+ * but using an invalid secret will produce an identity that fails proof generation.
+ *
+ * @param secret - The secret to validate
+ * @throws InvalidSecretError if validation fails
+ */
+export function validateHumanSecret(secret: bigint): void {
+  if (secret === 0n) {
+    throw new InvalidSecretError(
+      'secret must be non-zero — a zero secret produces a trivial identity that cannot generate valid proofs'
+    );
+  }
+  if (secret < 0n) {
+    throw new InvalidSecretError(
+      'secret must be positive — negative values are not valid field elements'
+    );
+  }
+  if (secret >= BN254_FIELD_ORDER) {
+    throw new InvalidSecretError(
+      `secret exceeds BN254 scalar field order (got ${secret.toString().slice(0, 20)}..., max is ~2^254). Use a value less than ${BN254_FIELD_ORDER}`
+    );
+  }
+}
+
+/**
+ * Validate an expiry timestamp for use with createAgentCredential.
+ * Throws InvalidPermissionError if the timestamp is in the past.
+ *
+ * Call this before createAgentCredential() to catch expired timestamps early.
+ * The circuit enforces expiry at verification time, but this provides an early check.
+ *
+ * @param expiryTimestamp - Unix timestamp to validate
+ * @throws InvalidPermissionError if timestamp is not in the future
+ */
+export function validateAgentExpiry(expiryTimestamp: bigint): void {
+  const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+  if (expiryTimestamp <= nowSeconds) {
+    throw new InvalidPermissionError(
+      `expiryTimestamp (${expiryTimestamp}) is not in the future (current time: ${nowSeconds}). ` +
+        `Set expiryTimestamp to a Unix timestamp after the current time, e.g. BigInt(Math.floor(Date.now() / 1000) + 86400) for +1 day.`
+    );
+  }
+}
 
 /**
  * Create a human identity (EdDSA keypair + commitment).
@@ -19,6 +71,7 @@ import { InvalidPermissionError } from './errors';
 export async function createHumanIdentity(
   secret: bigint,
 ): Promise<HumanIdentity> {
+  validateHumanSecret(secret);
   // HumanUniqueness circuit uses BabyPbk (direct scalar multiply),
   // NOT EdDSA prv2pub. Use derivePublicKeyScalar here.
   const publicKey = await derivePublicKeyScalar(secret);
@@ -52,6 +105,7 @@ export async function createAgentCredential(
   permissions: Permission[],
   expiryTimestamp: bigint,
 ): Promise<AgentCredential> {
+  validateAgentExpiry(expiryTimestamp);
   const bitmask = permissionsToBitmask(permissions);
   validateCumulativeBitEncoding(bitmask);
 

package/src/index.ts

@@ -4,8 +4,11 @@ export type {
   AgentCredential,
   HandshakeResult,
   DelegationResult,
+  DelegateeMerkleProof,
   Proof,
   BolyraConfig,
+  OffchainVerificationResult,
+  BatchCheckpoint,
 } from './types';
 
 // Permission enum
@@ -17,13 +20,33 @@ export {
   createAgentCredential,
   permissionsToBitmask,
   validateCumulativeBitEncoding,
+  validateHumanSecret,
+  validateAgentExpiry,
+  BN254_FIELD_ORDER,
 } from './identity';
 
-// Handshake (v0.2 — real proof generation via snarkjs)
+// Handshake (v0.2 — real proof generation via snarkjs / rapidsnark)
 export { proveHandshake, verifyHandshake } from './handshake';
 
-// Delegation (stubs — coming in v0.3)
+// Prover backend (v0.4 — rapidsnark for sub-200ms proofs)
+export { proveGroth16, activeProverBackend } from './prover';
+export type { ProverBackend } from './prover';
+
+// Off-chain verification (v0.3 — batch mode, ~100x gas reduction)
+export {
+  verifyHandshakeOffchain,
+  OffchainVerificationBatch,
+  postBatchRoot,
+  computeSessionCommitment,
+  verifyMerkleInclusion,
+} from './offchain';
+
+// Delegation (v0.3 — scope-narrowing one-way delegation, chain-linked on-chain)
 export { delegate, verifyDelegation } from './delegation';
+export type { DelegateInput } from './delegation';
+
+// Poseidon hashes (exposed for chain-link verification in integrations)
+export { poseidon2, poseidon3, poseidon4 } from './utils';
 
 // Errors
 export {
@@ -34,4 +57,8 @@ export {
   ExpiredCredentialError,
   ScopeEscalationError,
   StaleProofError,
+  InvalidSecretError,
+  CircuitArtifactNotFoundError,
+  MerkleTreeError,
+  ConfigurationError,
 } from './errors';

package/src/offchain.ts

@@ -0,0 +1,344 @@
+import * as snarkjs from 'snarkjs';
+import * as path from 'path';
+import * as fs from 'fs';
+import { ethers } from 'ethers';
+import {
+  Proof,
+  BolyraConfig,
+  HandshakeResult,
+  OffchainVerificationResult,
+  BatchCheckpoint,
+} from './types';
+import { VerificationError, CircuitArtifactNotFoundError } from './errors';
+import { poseidon2 } from './utils';
+
+// Default paths to circuit artifacts (relative to package root)
+const DEFAULT_CIRCUIT_DIR = path.join(__dirname, '../../circuits/build');
+
+/**
+ * Verify a handshake off-chain using local snarkjs verification.
+ * Same interface as verifyHandshake but never touches the chain.
+ * Produces a HandshakeResult suitable for batching.
+ *
+ * Gas savings: 0 gas per verification (vs ~300k+ on-chain).
+ * The batch root is posted once for N verifications.
+ */
+export async function verifyHandshakeOffchain(
+  humanProof: Proof,
+  agentProof: Proof,
+  nonce: bigint,
+  config?: BolyraConfig,
+): Promise<HandshakeResult> {
+  const circuitDir = config?.circuitDir ?? DEFAULT_CIRCUIT_DIR;
+
+  // Validate proof structure
+  if (!humanProof || !humanProof.proof || !Array.isArray(humanProof.publicSignals)) {
+    throw new VerificationError(
+      'Invalid humanProof structure: expected { proof: object, publicSignals: string[] }.'
+    );
+  }
+  if (!agentProof || !agentProof.proof || !Array.isArray(agentProof.publicSignals)) {
+    throw new VerificationError(
+      'Invalid agentProof structure: expected { proof: object, publicSignals: string[] }.'
+    );
+  }
+  if (humanProof.publicSignals.length < 2) {
+    throw new VerificationError(
+      `humanProof has ${humanProof.publicSignals.length} public signals, expected at least 2.`
+    );
+  }
+  if (agentProof.publicSignals.length < 3) {
+    throw new VerificationError(
+      `agentProof has ${agentProof.publicSignals.length} public signals, expected at least 3.`
+    );
+  }
+
+  // Load verification keys
+  const humanVkeyPath = path.join(circuitDir, 'HumanUniqueness_vkey.json');
+  if (!fs.existsSync(humanVkeyPath)) {
+    throw new CircuitArtifactNotFoundError(humanVkeyPath, 'vkey');
+  }
+  const agentVkeyPath = path.join(circuitDir, 'AgentPolicy_groth16_vkey.json');
+  if (!fs.existsSync(agentVkeyPath)) {
+    throw new CircuitArtifactNotFoundError(agentVkeyPath, 'vkey');
+  }
+
+  // Verify both proofs locally (no on-chain interaction)
+  const humanVkey = require(humanVkeyPath);
+  const humanValid = await snarkjs.groth16.verify(
+    humanVkey,
+    humanProof.publicSignals,
+    humanProof.proof,
+  );
+
+  const agentVkey = require(agentVkeyPath);
+  const agentValid = await snarkjs.groth16.verify(
+    agentVkey,
+    agentProof.publicSignals,
+    agentProof.proof,
+  );
+
+  return {
+    humanNullifier: BigInt(humanProof.publicSignals[1]),
+    agentNullifier: BigInt(agentProof.publicSignals[1]),
+    sessionNonce: nonce,
+    scopeCommitment: BigInt(agentProof.publicSignals[2]),
+    verified: humanValid && agentValid,
+  };
+}
+
+/**
+ * Compute the session commitment for a HandshakeResult.
+ * sessionCommitment = Poseidon2(humanNullifier, Poseidon2(agentNullifier, sessionNonce))
+ * This binds all three fields into a single leaf for the batch Merkle tree.
+ */
+export async function computeSessionCommitment(result: HandshakeResult): Promise<bigint> {
+  const inner = await poseidon2(result.agentNullifier, result.sessionNonce);
+  return poseidon2(result.humanNullifier, inner);
+}
+
+/**
+ * Accumulates verified handshake sessions and produces a Poseidon Merkle root.
+ * The root can be posted on-chain in a single transaction, amortizing gas
+ * across all sessions in the batch (target: ~100x reduction).
+ *
+ * Tree construction: binary Poseidon Merkle tree. If the number of leaves
+ * is not a power of 2, zero-padding is applied to the right.
+ */
+export class OffchainVerificationBatch {
+  private sessions: HandshakeResult[] = [];
+  private commitments: bigint[] = [];
+  private cachedRoot: bigint | null = null;
+
+  /** Number of sessions in the batch. */
+  get size(): number {
+    return this.sessions.length;
+  }
+
+  /**
+   * Add a verified handshake result to the batch.
+   * Resets the cached Merkle root (will be recomputed on next getMerkleRoot call).
+   *
+   * @returns The OffchainVerificationResult with batchIndex set.
+   */
+  async add(result: HandshakeResult): Promise<OffchainVerificationResult> {
+    if (!result.verified) {
+      throw new VerificationError(
+        'Cannot add unverified handshake to batch. Verify the handshake first.'
+      );
+    }
+
+    const batchIndex = this.sessions.length;
+    const commitment = await computeSessionCommitment(result);
+
+    this.sessions.push(result);
+    this.commitments.push(commitment);
+    this.cachedRoot = null; // invalidate cache
+
+    return {
+      ...result,
+      batchIndex,
+    };
+  }
+
+  /**
+   * Compute the Poseidon Merkle root of all session commitments.
+   * Uses a binary tree with zero-padding to the next power of 2.
+   * Result is cached until a new session is added.
+   */
+  async getMerkleRoot(): Promise<bigint> {
+    if (this.sessions.length === 0) {
+      return 0n;
+    }
+
+    if (this.cachedRoot !== null) {
+      return this.cachedRoot;
+    }
+
+    this.cachedRoot = await buildPoseidonMerkleRoot(this.commitments);
+    return this.cachedRoot;
+  }
+
+  /**
+   * Get a Merkle inclusion proof for a specific session in the batch.
+   * Returns sibling hashes and path indices (0 = left, 1 = right) from leaf to root.
+   *
+   * @param sessionIndex - Index of the session (from OffchainVerificationResult.batchIndex)
+   * @returns Merkle proof (siblings + pathIndices) or throws if index is out of bounds.
+   */
+  async getProofOfInclusion(
+    sessionIndex: number,
+  ): Promise<{ siblings: bigint[]; pathIndices: number[] }> {
+    if (sessionIndex < 0 || sessionIndex >= this.sessions.length) {
+      throw new VerificationError(
+        `Session index ${sessionIndex} out of bounds (batch has ${this.sessions.length} sessions).`
+      );
+    }
+
+    return buildPoseidonMerkleProof(this.commitments, sessionIndex);
+  }
+
+  /**
+   * Get the session commitment at a given index.
+   */
+  getCommitment(index: number): bigint {
+    if (index < 0 || index >= this.commitments.length) {
+      throw new VerificationError(
+        `Index ${index} out of bounds (batch has ${this.commitments.length} sessions).`
+      );
+    }
+    return this.commitments[index];
+  }
+
+  /**
+   * Get all session commitments (for external verification).
+   */
+  getCommitments(): bigint[] {
+    return [...this.commitments];
+  }
+}
+
+/**
+ * Post a batch Merkle root on-chain. A single transaction checkpoints N sessions.
+ *
+ * Gas cost: ~50k-80k gas for a single storage write + event emission,
+ * regardless of how many sessions are in the batch.
+ * For 100 sessions: ~500 gas/session vs ~300k gas/session on-chain = ~600x reduction.
+ *
+ * @param batch - The batch to checkpoint
+ * @param signer - An ethers Signer (connected to the target chain)
+ * @param registryAddress - Address of the IdentityRegistry (or a BatchCheckpoint contract)
+ * @returns The BatchCheckpoint with on-chain timestamp
+ */
+export async function postBatchRoot(
+  batch: OffchainVerificationBatch,
+  signer: ethers.Signer,
+  registryAddress: string,
+): Promise<BatchCheckpoint> {
+  if (batch.size === 0) {
+    throw new VerificationError('Cannot post empty batch root on-chain.');
+  }
+
+  const root = await batch.getMerkleRoot();
+
+  // ABI for the postBatchRoot function on the BatchCheckpoint extension contract.
+  // function postBatchRoot(uint256 root, uint256 sessionCount) external
+  const abi = [
+    'function postBatchRoot(uint256 root, uint256 sessionCount) external',
+    'event BatchRootPosted(uint256 indexed root, uint256 sessionCount, uint256 timestamp)',
+  ];
+
+  const contract = new ethers.Contract(registryAddress, abi, signer);
+  const tx = await contract.postBatchRoot(root, batch.size);
+  const receipt = await tx.wait();
+
+  const timestamp = receipt?.blockNumber
+    ? (await signer.provider!.getBlock(receipt.blockNumber))?.timestamp ?? Math.floor(Date.now() / 1000)
+    : Math.floor(Date.now() / 1000);
+
+  return {
+    root,
+    timestamp,
+    sessionCount: batch.size,
+  };
+}
+
+// ============ Internal Merkle Tree Helpers ============
+
+/**
+ * Pad leaves array to the next power of 2 with zeros.
+ */
+function padToPowerOfTwo(leaves: bigint[]): bigint[] {
+  if (leaves.length === 0) return [0n];
+  let size = 1;
+  while (size < leaves.length) {
+    size *= 2;
+  }
+  const padded = [...leaves];
+  while (padded.length < size) {
+    padded.push(0n);
+  }
+  return padded;
+}
+
+/**
+ * Build a Poseidon Merkle root from a list of leaf commitments.
+ * Binary tree, zero-padded to next power of 2.
+ */
+async function buildPoseidonMerkleRoot(leaves: bigint[]): Promise<bigint> {
+  let layer = padToPowerOfTwo(leaves);
+
+  while (layer.length > 1) {
+    const nextLayer: bigint[] = [];
+    for (let i = 0; i < layer.length; i += 2) {
+      nextLayer.push(await poseidon2(layer[i], layer[i + 1]));
+    }
+    layer = nextLayer;
+  }
+
+  return layer[0];
+}
+
+/**
+ * Build a Merkle inclusion proof for a specific leaf index.
+ * Returns siblings and path indices (0 = leaf is on the left, 1 = leaf is on the right).
+ */
+async function buildPoseidonMerkleProof(
+  leaves: bigint[],
+  index: number,
+): Promise<{ siblings: bigint[]; pathIndices: number[] }> {
+  const padded = padToPowerOfTwo(leaves);
+  const siblings: bigint[] = [];
+  const pathIndices: number[] = [];
+
+  let layer = padded;
+  let currentIndex = index;
+
+  while (layer.length > 1) {
+    const siblingIndex = currentIndex % 2 === 0 ? currentIndex + 1 : currentIndex - 1;
+    siblings.push(layer[siblingIndex]);
+    pathIndices.push(currentIndex % 2); // 0 = left, 1 = right
+
+    // Build next layer
+    const nextLayer: bigint[] = [];
+    for (let i = 0; i < layer.length; i += 2) {
+      nextLayer.push(await poseidon2(layer[i], layer[i + 1]));
+    }
+    layer = nextLayer;
+    currentIndex = Math.floor(currentIndex / 2);
+  }
+
+  return { siblings, pathIndices };
+}
+
+/**
+ * Verify a Merkle inclusion proof against a known root.
+ * Useful for verifiers who receive a proof-of-inclusion from a session participant.
+ *
+ * @param leaf - The session commitment (leaf value)
+ * @param siblings - Sibling hashes from the proof
+ * @param pathIndices - Path indices (0 = left, 1 = right)
+ * @param expectedRoot - The expected Merkle root (from on-chain checkpoint)
+ * @returns true if the proof is valid
+ */
+export async function verifyMerkleInclusion(
+  leaf: bigint,
+  siblings: bigint[],
+  pathIndices: number[],
+  expectedRoot: bigint,
+): Promise<boolean> {
+  if (siblings.length !== pathIndices.length) {
+    return false;
+  }
+
+  let current = leaf;
+  for (let i = 0; i < siblings.length; i++) {
+    if (pathIndices[i] === 0) {
+      current = await poseidon2(current, siblings[i]);
+    } else {
+      current = await poseidon2(siblings[i], current);
+    }
+  }
+
+  return current === expectedRoot;
+}