@collectorcrypt/vrf-client 0.1.0

package/dist/verifyEndToEnd.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickCanonicalCommit = pickCanonicalCommit;
+exports.verifyEndToEnd = verifyEndToEnd;
+exports.verifyAuthorityCommitEndToEnd = verifyAuthorityCommitEndToEnd;
+const ecvrf_1 = require("@collectorcrypt/ecvrf");
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const addresses_1 = require("./addresses");
+const constants_1 = require("./constants");
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/**
+ * Resolve which committed event corresponds to a known-valid proof. Use this
+ * when fetching event-mode commits where the chain doesn't enforce
+ * one-commit-per-memo. Pass in all candidates from `fetchProofCommitEvents`
+ * plus the proof bytes the operator gave you; you get back the unique
+ * canonical row (or null if none match).
+ */
+function pickCanonicalCommit(candidates, proof) {
+    const proofHash = (0, sha2_js_1.sha256)(proof);
+    const matching = candidates.filter((c) => bytesEqual(proofHash, c.proofHash));
+    return {
+        canonical: matching[0] ?? null,
+        candidates,
+        duplicateMemoEvents: candidates.length > 1,
+        multipleVerifying: matching.length > 1,
+    };
+}
+function verifyEndToEnd(input) {
+    const reasons = [];
+    const suite = input.suite ?? constants_1.SUITE_EDWARDS25519_SHA512_TAI;
+    const suiteSupported = suite === constants_1.SUITE_EDWARDS25519_SHA512_TAI;
+    if (!suiteSupported)
+        reasons.push(`unsupported-suite-${suite}`);
+    const ecvrfValid = suiteSupported && (0, ecvrf_1.verifyVRF)(input.pk, input.alpha, input.proof);
+    if (!ecvrfValid)
+        reasons.push("ecvrf-verify-failed");
+    const computedProofHash = (0, sha2_js_1.sha256)(input.proof);
+    const proofHashMatches = bytesEqual(computedProofHash, input.onChainCommit.proofHash);
+    if (!proofHashMatches) {
+        reasons.push(`proof-hash-mismatch (computed=${(0, ecvrf_1.bytesToHex)(computedProofHash)} onchain=${(0, ecvrf_1.bytesToHex)(input.onChainCommit.proofHash)})`);
+    }
+    const computedAlphaHash = (0, sha2_js_1.sha256)(input.alpha);
+    const alphaHashMatches = bytesEqual(computedAlphaHash, input.onChainCommit.alphaHash);
+    if (!alphaHashMatches)
+        reasons.push("alpha-hash-mismatch");
+    const memoBytes = typeof input.memo === "string"
+        ? new TextEncoder().encode(input.memo)
+        : input.memo;
+    const computedMemoHash = (0, sha2_js_1.sha256)(memoBytes);
+    const memoHashMatches = bytesEqual(computedMemoHash, input.onChainCommit.memoHash);
+    if (!memoHashMatches)
+        reasons.push("memo-hash-mismatch");
+    const valid = suiteSupported &&
+        ecvrfValid &&
+        proofHashMatches &&
+        alphaHashMatches &&
+        memoHashMatches;
+    const beta = ecvrfValid ? (0, ecvrf_1.vrfProofToHash)(input.proof) : null;
+    return {
+        valid,
+        ecvrfValid,
+        suiteSupported,
+        proofHashMatches,
+        alphaHashMatches,
+        memoHashMatches,
+        beta,
+        reasons,
+    };
+}
+function verifyAuthorityCommitEndToEnd(input) {
+    const base = verifyEndToEnd({
+        pk: input.authority.pk,
+        suite: input.authority.suite,
+        alpha: input.alpha,
+        proof: input.proof,
+        onChainCommit: input.onChainCommit,
+        memo: input.memo,
+    });
+    const reasons = [...base.reasons];
+    const authorityFrozen = input.authority.frozen;
+    if (!authorityFrozen)
+        reasons.push("authority-not-frozen");
+    const authorityNotRevoked = !input.authority.revoked;
+    if (!authorityNotRevoked)
+        reasons.push("authority-revoked");
+    const authorityOwnerMatches = input.expectedOwner
+        ? input.authority.owner.equals(input.expectedOwner)
+        : true;
+    if (!authorityOwnerMatches)
+        reasons.push("authority-owner-mismatch");
+    const authorityLabelMatches = input.expectedLabel
+        ? bytesEqual(input.authority.label, input.expectedLabel)
+        : true;
+    if (!authorityLabelMatches)
+        reasons.push("authority-label-mismatch");
+    // Always rederive the canonical authority address from (owner, label) and
+    // require the commit to point at it. This closes the prior footgun where a
+    // hand-built OnChainAuthority + missing expectedAuthorityAddress silently
+    // skipped the commit-to-authority binding.
+    const programId = input.programId ?? constants_1.CC_VRF_PROGRAM_ID;
+    const derivedAuthorityAddress = (0, addresses_1.deriveAuthorityAddress)(input.authority.owner, input.authority.label, programId);
+    const commitAuthority = input.onChainCommit.authority;
+    const commitAuthorityMatches = commitAuthority?.equals(derivedAuthorityAddress) === true;
+    if (!commitAuthorityMatches) {
+        reasons.push(commitAuthority
+            ? "commit-authority-mismatch"
+            : "commit-authority-missing");
+    }
+    // If the caller passed their own expectedAuthorityAddress, it must also
+    // match the derived one — otherwise the caller's expectation contradicts
+    // the (owner, label) they supplied.
+    const expectedAuthorityMatchesDerived = input.expectedAuthorityAddress
+        ? input.expectedAuthorityAddress.equals(derivedAuthorityAddress)
+        : true;
+    if (!expectedAuthorityMatchesDerived) {
+        reasons.push("expected-authority-address-mismatch");
+    }
+    const betaMatches = input.onChainBeta
+        ? base.beta !== null && bytesEqual(input.onChainBeta, base.beta)
+        : null;
+    if (betaMatches === false)
+        reasons.push("beta-mismatch");
+    const valid = base.valid &&
+        authorityFrozen &&
+        authorityNotRevoked &&
+        authorityOwnerMatches &&
+        authorityLabelMatches &&
+        commitAuthorityMatches &&
+        expectedAuthorityMatchesDerived &&
+        betaMatches !== false;
+    return {
+        ...base,
+        valid,
+        reasons,
+        authorityFrozen,
+        authorityNotRevoked,
+        authorityOwnerMatches,
+        authorityLabelMatches,
+        commitAuthorityMatches,
+        betaMatches,
+    };
+}
+//# sourceMappingURL=verifyEndToEnd.js.map

package/dist/verifyEndToEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyEndToEnd.js","sourceRoot":"","sources":["../src/verifyEndToEnd.ts"],"names":[],"mappings":";;AA8IA,kDAYC;AAED,wCA4DC;AAED,sEAsFC;AAhTD,iDAA8E;AAC9E,mDAA+C;AAE/C,2CAAqD;AACrD,2CAA+E;AAwD/E,SAAS,UAAU,CAAC,CAAa,EAAE,CAAa;IAC9C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAsED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CACjC,UAA2B,EAC3B,KAAiB;IAEjB,MAAM,SAAS,GAAG,IAAA,gBAAM,EAAC,KAAK,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9E,OAAO;QACL,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI;QAC9B,UAAU;QACV,mBAAmB,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC;QAC1C,iBAAiB,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;KACvC,CAAC;AACJ,CAAC;AAED,SAAgB,cAAc,CAC5B,KAA0B;IAE1B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,yCAA6B,CAAC;IAC3D,MAAM,cAAc,GAAG,KAAK,KAAK,yCAA6B,CAAC;IAC/D,IAAI,CAAC,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,KAAK,EAAE,CAAC,CAAC;IAEhE,MAAM,UAAU,GACd,cAAc,IAAI,IAAA,iBAAS,EAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAClE,IAAI,CAAC,UAAU;QAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAErD,MAAM,iBAAiB,GAAG,IAAA,gBAAM,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,gBAAgB,GAAG,UAAU,CACjC,iBAAiB,EACjB,KAAK,CAAC,aAAa,CAAC,SAAS,CAC9B,CAAC;IACF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,iCAAiC,IAAA,kBAAU,EAAC,iBAAiB,CAAC,YAAY,IAAA,kBAAU,EAAC,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,CACvH,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAA,gBAAM,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,gBAAgB,GAAG,UAAU,CACjC,iBAAiB,EACjB,KAAK,CAAC,aAAa,CAAC,SAAS,CAC9B,CAAC;IACF,IAAI,CAAC,gBAAgB;QAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAE3D,MAAM,SAAS,GACb,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC5B,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QACtC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IACjB,MAAM,gBAAgB,GAAG,IAAA,gBAAM,EAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,eAAe,GAAG,UAAU,CAChC,gBAAgB,EAChB,KAAK,CAAC,aAAa,CAAC,QAAQ,CAC7B,CAAC;IACF,IAAI,CAAC,eAAe;QAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAEzD,MAAM,KAAK,GACT,cAAc;QACd,UAAU;QACV,gBAAgB;QAChB,gBAAgB;QAChB,eAAe,CAAC;IAClB,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,IAAA,sBAAc,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7D,OAAO;QACL,KAAK;QACL,UAAU;QACV,cAAc;QACd,gBAAgB;QAChB,gBAAgB;QAChB,eAAe;QACf,IAAI;QACJ,OAAO;KACR,CAAC;AACJ,CAAC;AAED,SAAgB,6BAA6B,CAC3C,KAAyC;IAEzC,MAAM,IAAI,GAAG,cAAc,CAAC;QAC1B,EAAE,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE;QACtB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK;QAC5B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,eAAe,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/C,IAAI,CAAC,eAAe;QAAE,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAE3D,MAAM,mBAAmB,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC;IACrD,IAAI,CAAC,mBAAmB;QAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAE5D,MAAM,qBAAqB,GAAG,KAAK,CAAC,aAAa;QAC/C,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC;QACnD,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,qBAAqB;QAAE,OAAO,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAErE,MAAM,qBAAqB,GAAG,KAAK,CAAC,aAAa;QAC/C,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;QACxD,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,qBAAqB;QAAE,OAAO,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAErE,0EAA0E;IAC1E,2EAA2E;IAC3E,0EAA0E;IAC1E,2CAA2C;IAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,6BAAiB,CAAC;IACvD,MAAM,uBAAuB,GAAG,IAAA,kCAAsB,EACpD,KAAK,CAAC,SAAS,CAAC,KAAK,EACrB,KAAK,CAAC,SAAS,CAAC,KAAK,EACrB,SAAS,CACV,CAAC;IACF,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC;IACtD,MAAM,sBAAsB,GAC1B,eAAe,EAAE,MAAM,CAAC,uBAAuB,CAAC,KAAK,IAAI,CAAC;IAC5D,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,CACV,eAAe;YACb,CAAC,CAAC,2BAA2B;YAC7B,CAAC,CAAC,0BAA0B,CAC/B,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,yEAAyE;IACzE,oCAAoC;IACpC,MAAM,+BAA+B,GAAG,KAAK,CAAC,wBAAwB;QACpE,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC,uBAAuB,CAAC;QAChE,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,+BAA+B,EAAE,CAAC;QACrC,OAAO,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW;QACnC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC;QAChE,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,WAAW,KAAK,KAAK;QAAE,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAEzD,MAAM,KAAK,GACT,IAAI,CAAC,KAAK;QACV,eAAe;QACf,mBAAmB;QACnB,qBAAqB;QACrB,qBAAqB;QACrB,sBAAsB;QACtB,+BAA+B;QAC/B,WAAW,KAAK,KAAK,CAAC;IAExB,OAAO;QACL,GAAG,IAAI;QACP,KAAK;QACL,OAAO;QACP,eAAe;QACf,mBAAmB;QACnB,qBAAqB;QACrB,qBAAqB;QACrB,sBAAsB;QACtB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@collectorcrypt/vrf-client",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the cc-vrf on-chain VRF program (Solana + Light Protocol)",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/collectorcrypt/cc-vrf.git",
+    "directory": "packages/vrf-client"
+  },
+  "homepage": "https://vrf.collectorcrypt.com",
+  "keywords": [
+    "vrf",
+    "ecvrf",
+    "solana",
+    "anchor",
+    "light-protocol",
+    "compressed-pda",
+    "verifiable-random-function",
+    "rfc-9381"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@lightprotocol/stateless.js": "^0.23.3",
+    "@noble/hashes": "^2.2.0",
+    "@solana/web3.js": "^1.98.4",
+    "@collectorcrypt/ecvrf": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"const fs=require('node:fs');fs.mkdirSync('dist/idl',{recursive:true});fs.copyFileSync('src/idl/cc_vrf.json','dist/idl/cc_vrf.json')\"",
+    "refresh:idl": "node -e \"const fs=require('node:fs');fs.mkdirSync('src/idl',{recursive:true});fs.copyFileSync('../../target/idl/cc_vrf.json','src/idl/cc_vrf.json');console.log('idl refreshed')\"",
+    "test": "vitest run"
+  }
+}

package/src/addresses.ts

@@ -0,0 +1,105 @@
+import { PublicKey } from "@solana/web3.js";
+import {
+  batchAddressTree,
+  deriveAddressSeedV2,
+  deriveAddressV2,
+} from "@lightprotocol/stateless.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import {
+  AUTHORITY_SEED,
+  PROOF_COMMIT_SEED,
+  PROOF_COMMIT_WITH_BETA_SEED,
+} from "./constants";
+
+/**
+ * Derive the compressed-PDA address of a VrfAuthority. This is the address
+ * the Light state Merkle tree indexes — NOT a Solana account address.
+ *
+ * Seeds: ["vrf_authority", owner_pubkey, label_bytes]
+ */
+export function deriveAuthorityAddress(
+  owner: PublicKey,
+  label: Uint8Array,
+  programId: PublicKey,
+): PublicKey {
+  if (label.length !== 32) {
+    throw new Error("label must be exactly 32 bytes");
+  }
+  const seed = deriveAddressSeedV2([AUTHORITY_SEED, owner.toBytes(), label]);
+  return deriveAddressV2(seed, new PublicKey(batchAddressTree), programId);
+}
+
+/**
+ * Derive the compressed-PDA address of a VrfProofCommit.
+ *
+ * Seeds: ["vrf_proof", authority_pubkey, memo_hash]
+ */
+export function deriveProofCommitAddress(
+  authority: PublicKey,
+  memoHash: Uint8Array,
+  programId: PublicKey,
+): PublicKey {
+  if (memoHash.length !== 32) {
+    throw new Error("memoHash must be exactly 32 bytes");
+  }
+  const seed = deriveAddressSeedV2([
+    PROOF_COMMIT_SEED,
+    authority.toBytes(),
+    memoHash,
+  ]);
+  return deriveAddressV2(seed, new PublicKey(batchAddressTree), programId);
+}
+
+/**
+ * Derive the compressed-PDA address of a VrfProofCommitWithBeta. Uses a
+ * same seed prefix as regular VrfProofCommit records. This makes registry
+ * mode and registry+beta mutually exclusive for a given (authority, memo).
+ *
+ * Seeds: ["vrf_proof", authority_pubkey, memo_hash]
+ */
+export function deriveProofCommitWithBetaAddress(
+  authority: PublicKey,
+  memoHash: Uint8Array,
+  programId: PublicKey,
+): PublicKey {
+  if (memoHash.length !== 32) {
+    throw new Error("memoHash must be exactly 32 bytes");
+  }
+  const seed = deriveAddressSeedV2([
+    PROOF_COMMIT_WITH_BETA_SEED,
+    authority.toBytes(),
+    memoHash,
+  ]);
+  return deriveAddressV2(seed, new PublicKey(batchAddressTree), programId);
+}
+
+/** Convenience: SHA-256 a UTF-8 memo string. */
+export function memoHash(memo: string | Uint8Array): Uint8Array {
+  const input =
+    typeof memo === "string" ? new TextEncoder().encode(memo) : memo;
+  return sha256(input);
+}
+
+/** Convenience: SHA-256 the alpha bytes. */
+export function alphaHash(alpha: Uint8Array): Uint8Array {
+  return sha256(alpha);
+}
+
+/** Convenience: SHA-256 the proof bytes. */
+export function proofHash(proof: Uint8Array): Uint8Array {
+  return sha256(proof);
+}
+
+/**
+ * Pad a short utf-8 label to 32 bytes (right-padded with zeroes). Useful for
+ * human-readable labels like "gacha" or "lottery".
+ */
+export function encodeLabel(label: string): Uint8Array {
+  const bytes = new TextEncoder().encode(label);
+  if (bytes.length > 32) {
+    throw new Error(`label "${label}" exceeds 32 bytes encoded`);
+  }
+  const padded = new Uint8Array(32);
+  padded.set(bytes, 0);
+  return padded;
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Default mainnet program ID (renounced upgrade authority post-deploy).
+ * Override via `new VrfClient({ programId })` for devnet/local testing.
+ */
+export const CC_VRF_PROGRAM_ID = new PublicKey(
+  "ccvrfu3fSpbnPLiUqdWAt85Zn9nq96ekwGTbHqGtdgQ",
+);
+
+export const AUTHORITY_SEED = new TextEncoder().encode("vrf_authority");
+export const PROOF_COMMIT_SEED = new TextEncoder().encode("vrf_proof");
+export const PROOF_COMMIT_WITH_BETA_SEED = PROOF_COMMIT_SEED;
+
+/** RFC 9381 §7.5 IANA suite identifier. */
+export const SUITE_EDWARDS25519_SHA512_TAI = 0x03;