@verify-network/protocol 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verify Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @verify-network/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The off-chain half of the Verify Network VRF protocol. Use it to verify a fulfillment the router delivered, to sign and send a direct request to a node, and to compute request ids, fees, and the typed data the router checks. Every function mirrors the router byte for byte.
+
+## Install
+
+```sh
+npm install @verify-network/protocol viem effect
+```
+
+`viem` (`^2.56.3`) and `effect` (`^4.0.0`) are peer dependencies. Node 22 or later.
+
+## Entry points
+
+| Import                                 | Contents                                                                                                                         |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `@verify-network/protocol`             | Everything below, plus the direct-request client (`DirectClient`), the router quote (`Quote`), the router watch, and the schemas |
+| `@verify-network/protocol/ecvrf`       | ECVRF-SECP256K1-SHA256-TAI (RFC 9381): `prove`, `verify`, `deriveRandomness`, `proofCommitment`, `isSentinel`, `isFulfillable`   |
+| `@verify-network/protocol/event`       | The router's `RandomnessRequested` and `RandomnessFulfilled` events and their decoders                                           |
+| `@verify-network/protocol/fee`         | The reservation, the charge, and the settlement, as the router computes them                                                     |
+| `@verify-network/protocol/fulfillment` | The EIP-712 typed data an enclave signs, and its digest                                                                          |
+| `@verify-network/protocol/request`     | `requestId`, the stale delay, and the callback data limit                                                                        |
+
+The subpath entries do not load Effect. Import from them in a browser bundle. The root entry loads Effect for its schemas, the quote, the router watch, and the direct-request client.
+
+## Verify a fulfillment
+
+A fulfillment is valid when three things hold. The enclave signature recovers to the request's fulfiller. The proof verifies under that node's key for the request id. The randomness is the one the proof derives.
+
+In a browser, import the same names from `/ecvrf`, `/event`, and `/fulfillment` instead of the root.
+
+```ts
+import {
+  decodeRandomnessFulfilled,
+  decodeRandomnessRequested,
+  deriveRandomness,
+  fulfillmentDigest,
+  isFulfillable,
+  isSentinel,
+  proofCommitment,
+  randomnessFulfilledEvent,
+  randomnessRequestedEvent,
+  verify,
+} from "@verify-network/protocol";
+import {
+  isAddressEqual,
+  parseAbi,
+  recoverAddress,
+  type Address,
+  type Hex,
+  type PublicClient,
+} from "viem";
+
+const nodes = parseAbi(["function publicKeyOf(address node) view returns (uint256[2])"]);
+
+export const checkFulfillment = async ({
+  publicClient,
+  router,
+  requestId,
+  fromBlock,
+}: {
+  publicClient: PublicClient;
+  router: Address;
+  requestId: Hex;
+  fromBlock: bigint;
+}) => {
+  const [requested] = await publicClient.getLogs({
+    address: router,
+    event: randomnessRequestedEvent,
+    args: { requestId },
+    fromBlock,
+  });
+  const [fulfilled] = await publicClient.getLogs({
+    address: router,
+    event: randomnessFulfilledEvent,
+    args: { requestId },
+    fromBlock,
+  });
+  if (requested === undefined || fulfilled === undefined) throw new Error("not fulfilled yet");
+
+  const { request } = decodeRandomnessRequested(requested);
+  const { proof, randomness, enclaveSignature } = decodeRandomnessFulfilled(fulfilled);
+  const chainId = await publicClient.getChainId();
+  const publicKey = await publicClient.readContract({
+    address: router,
+    abi: nodes,
+    functionName: "publicKeyOf",
+    args: [request.fulfiller],
+  });
+
+  const signer = await recoverAddress({
+    hash: fulfillmentDigest({
+      chainId,
+      router,
+      requestId,
+      proofCommitment: proofCommitment(proof),
+    }),
+    signature: enclaveSignature,
+  });
+  const proven = isSentinel(proof)
+    ? !isFulfillable(publicKey, requestId)
+    : verify({ publicKey, proof, alpha: requestId });
+  return (
+    isAddressEqual(signer, request.fulfiller) && proven && deriveRandomness(proof) === randomness
+  );
+};
+```
+
+A fulfillment that fails this check is evidence for `challengeFulfillment(request, proof, enclaveSignature)` on the router. Anyone may send it while the node still holds stake.
+
+## Send a direct request
+
+A direct request skips the consumer's own transaction. A signer signs an authorization, posts it to one node, and the node lands the request and its fulfillment in one transaction. The signer's balance on the router pays.
+
+`DirectClient` finds the fastest serving node on the router, signs, posts, and waits until the fulfillment lands. Its methods return Effects. `run` turns one into a promise, so a caller needs no Effect code.
+
+```ts
+import { DirectClient, run } from "@verify-network/protocol";
+import { createPublicClient, http, toHex, type Chain } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+// Widened to `Chain`: `DirectClient` takes a `PublicClient` of any chain.
+const publicClient = createPublicClient({ chain: base as Chain, transport: http() });
+const client = await run(
+  DirectClient.connect({
+    publicClient,
+    chainId: base.id,
+    router: "0x…",
+    account: privateKeyToAccount("0x…"), // a session key or a backend key, funded on the router
+  }),
+);
+
+const result = await run(client.request({ consumer: "0x…", callbackData: toHex("round-1") }));
+if (result._tag === "Landed") {
+  console.log(result.requestId, result.randomness, result.hash);
+} else {
+  // NotLanded: the deadline passed on the chain's clock and nothing landed. Fall back to an on-chain request.
+}
+```
+
+The consumer contract implements `IDirectVrfReceiver` from `@verify-network/contracts`. The signer is passed to its callback, so the consumer decides which signers it accepts.
+
+To sign an authorization yourself, use `signDirectRequest` and `directRequestId`. `validateEndpoint` checks an endpoint read from the chain before you connect to it.
+
+## License
+
+MIT

package/dist/domain-CXJsoNRU.d.ts

@@ -0,0 +1,9 @@
+import { Address } from "viem";
+//#region src/domain.d.ts
+/** One router deployment: what request ids and fulfillment digests are bound to. */
+type RouterDomain = {
+  readonly chainId: bigint | number;
+  readonly router: Address;
+};
+//#endregion
+export { RouterDomain as t };

package/dist/ecvrf.d.ts

@@ -0,0 +1,69 @@
+import { Hex } from "viem";
+//#region src/ecvrf.d.ts
+/**
+ * ECVRF-SECP256K1-SHA256-TAI, the RFC 9381 cipher suite the router's `ECVRFVerifier` checks,
+ * on `@noble/curves` and `@noble/hashes`. Hash-to-curve, the challenge, the proof encoding,
+ * and the randomness derivation mirror `VRF.sol` so the enclave and the router agree byte for
+ * byte; the nonce is RFC 6979, as RFC 9381 prescribes for the suite. Every function is pure and
+ * synchronous, so it runs unchanged on a `node:worker_threads` worker, under Node and Bun.
+ */
+/** A proof as the router takes it: `[gammaX, gammaY, c, s]`. */
+export type Proof = readonly [gammaX: bigint, gammaY: bigint, c: bigint, s: bigint];
+/** An enclave key as the router stores it: the uncompressed point's `[x, y]`. */
+export type PublicKey = readonly [x: bigint, y: bigint];
+/**
+ * `VRF.HASH_TO_CURVE_MAX_ITERATIONS`: the try-and-increment attempts the on-chain verifier makes
+ * before declaring an alpha unfulfillable (probability 2^-50 per request).
+ */
+export declare const HASH_TO_CURVE_MAX_ITERATIONS = 50;
+/** What a fulfiller submits for an alpha that fails the hash-to-curve check. */
+export declare const SENTINEL_PROOF: Proof;
+/** The router recognises the sentinel by its gamma alone. */
+export declare const isSentinel: ([gammaX, gammaY]: Proof) => boolean;
+/**
+ * The `[x, y]` point the router stores, from the key viem derives (`0x04 || x || y`). Throws
+ * when the key is not on the curve.
+ */
+export declare const publicKeyPoint: (publicKey: Hex) => PublicKey;
+/**
+ * Proves `alpha` (the request id) under the enclave key. Deterministic: RFC 6979 fixes the nonce.
+ * Throws when `alpha` has no curve point within the on-chain cap; the fulfiller submits the
+ * sentinel for such a request (see `isFulfillable`).
+ */
+export declare const prove: ({ privateKey, alpha }: {
+  privateKey: Hex;
+  alpha: Hex;
+}) => Proof;
+/**
+ * Whether `proof` proves `alpha` under `publicKey`, as `ECVRFVerifier.verify` decides: gamma must
+ * be a curve point with the `y` as submitted (the router multiplies it as given), `c` must fit 16
+ * bytes, `s` must be below the group order, and `alpha` must hash to a point within the cap.
+ */
+export declare const verify: ({ publicKey, proof, alpha }: {
+  publicKey: PublicKey;
+  proof: Proof;
+  alpha: Hex;
+}) => boolean;
+/**
+ * The 81-byte RFC 9381 proof string: compressed gamma, `c` in 16 bytes, `s` in 32. Throws when
+ * a scalar does not fit.
+ */
+export declare const encodeProof: ([gammaX, gammaY, c, s]: Proof) => Hex;
+/** The router's four limbs from an RFC 9381 proof string. Throws when the string is malformed. */
+export declare const decodeProof: (encoded: Hex) => Proof;
+/**
+ * The randomness a proof yields, as `VRF.gammaToHash` derives it: sha256 of the suite byte,
+ * `0x03`, the compressed gamma, and a zero byte. Zero for the sentinel, as the router emits it.
+ */
+export declare const deriveRandomness: (proof: Proof) => Hex;
+/** What the enclave signs over: `keccak256(abi.encode(proof))` in the router. */
+export declare const proofCommitment: (proof: Proof) => Hex;
+/**
+ * The try-and-increment attempts `VRF.tryHashToPoint` needs to hash `alpha` to a point for
+ * `publicKey`, or `null` when none is found within `maxIterations`: such a request cannot be
+ * proven and is closed with the sentinel.
+ */
+export declare const hashToCurveIterations: (publicKey: PublicKey, alpha: Hex, maxIterations?: number) => number | null;
+/** Whether the on-chain verifier can hash `alpha` to a point for `publicKey`. */
+export declare const isFulfillable: (publicKey: PublicKey, alpha: Hex, maxIterations?: number) => boolean;
+//#endregion

package/dist/ecvrf.js

@@ -0,0 +1,174 @@
+import { bytesToHex, encodeAbiParameters, hexToBytes, keccak256, zeroHash } from "viem";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { bytesToNumberBE, concatBytes, createHmacDrbg, numberToBytesBE } from "@noble/curves/utils.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+//#region src/ecvrf.ts
+/**
+* `VRF.HASH_TO_CURVE_MAX_ITERATIONS`: the try-and-increment attempts the on-chain verifier makes
+* before declaring an alpha unfulfillable (probability 2^-50 per request).
+*/
+const HASH_TO_CURVE_MAX_ITERATIONS = 50;
+/** What a fulfiller submits for an alpha that fails the hash-to-curve check. */
+const SENTINEL_PROOF = [
+	0n,
+	0n,
+	0n,
+	0n
+];
+/** The router recognises the sentinel by its gamma alone. */
+const isSentinel = ([gammaX, gammaY]) => gammaX === 0n && gammaY === 0n;
+const { Point } = secp256k1;
+const G = Point.BASE;
+/** The group order, RFC 9381's `q`. */
+const Q = Point.Fn.ORDER;
+/** The suite string; the byte after it separates the three hashes the suite takes. */
+const SUITE = 254;
+/** RFC 9381 sizes for the suite: the challenge `c` is 16 bytes, the proof string 33 + 16 + 32. */
+const C_BYTES = 16;
+const C_LIMIT = 1n << 128n;
+const PROOF_BYTES = 81;
+/** The curve point at `[x, y]`. Throws when there is none, including for the sentinel. */
+const point = ([x, y]) => {
+	const p = Point.fromAffine({
+		x,
+		y
+	});
+	p.assertValidity();
+	return p;
+};
+const limbs = (p) => {
+	const { x, y } = p.toAffine();
+	return [x, y];
+};
+/** `VRF.encodePoint`: SEC 1 compressed, the parity prefix then `x`, over the limbs as given. */
+const encodePoint = (x, y) => concatBytes(Uint8Array.of(y % 2n === 0n ? 2 : 3), numberToBytesBE(x, 32));
+const compressed = (p) => encodePoint(...limbs(p));
+/**
+* The `[x, y]` point the router stores, from the key viem derives (`0x04 || x || y`). Throws
+* when the key is not on the curve.
+*/
+const publicKeyPoint = (publicKey) => limbs(Point.fromBytes(hexToBytes(publicKey)));
+/**
+* `VRF.tryHashToPoint`: try-and-increment over
+* `sha256(0xfe || 0x01 || compressed key || alpha || counter || 0x00)`, reading each digest as
+* the `x` of an even-`y` point; a digest of zero or at least the field prime yields none, as
+* `EllipticCurve.isOnCurve` decides. The point and the attempts it took, or `null` past the cap.
+*/
+const hashToCurve = (publicKey, alpha, maxIterations) => {
+	const prefix = concatBytes(Uint8Array.of(SUITE, 1), encodePoint(...publicKey), alpha);
+	for (let counter = 0; counter < maxIterations; counter++) {
+		const digest = sha256(concatBytes(prefix, Uint8Array.of(counter, 0)));
+		try {
+			return {
+				point: Point.fromBytes(concatBytes(Uint8Array.of(2), digest)),
+				iterations: counter + 1
+			};
+		} catch {}
+	}
+	return null;
+};
+/**
+* `VRF.hashPoints`: the first 16 bytes of `sha256(0xfe || 0x02 || H || Gamma || U || V || 0x00)`,
+* the points compressed.
+*/
+const challenge = (points) => bytesToNumberBE(sha256(concatBytes(Uint8Array.of(SUITE, 2), ...points.map(compressed), Uint8Array.of(0))).subarray(0, C_BYTES));
+const drbg = createHmacDrbg(32, 32, (key, message) => hmac(sha256, key, message));
+/**
+* RFC 9381 §5.4.2.1: the nonce RFC 6979 §3.2 derives from the secret scalar and `sha256` of the
+* compressed `H`, so a proof is a function of the key and alpha alone.
+*/
+const nonce = (x, h) => {
+	const h1 = bytesToNumberBE(sha256(compressed(h))) % Q;
+	return drbg(concatBytes(numberToBytesBE(x, 32), numberToBytesBE(h1, 32)), (candidate) => {
+		const k = bytesToNumberBE(candidate);
+		return k > 0n && k < Q ? k : void 0;
+	});
+};
+/**
+* Proves `alpha` (the request id) under the enclave key. Deterministic: RFC 6979 fixes the nonce.
+* Throws when `alpha` has no curve point within the on-chain cap; the fulfiller submits the
+* sentinel for such a request (see `isFulfillable`).
+*/
+const prove = ({ privateKey, alpha }) => {
+	const x = bytesToNumberBE(hexToBytes(privateKey));
+	const publicKey = G.multiply(x);
+	const hashed = hashToCurve(limbs(publicKey), hexToBytes(alpha), 50);
+	if (hashed === null) throw new Error("ECVRF alpha has no curve point within the on-chain cap");
+	const h = hashed.point;
+	const gamma = h.multiply(x);
+	const k = nonce(x, h);
+	const c = challenge([
+		h,
+		gamma,
+		G.multiply(k),
+		h.multiply(k)
+	]);
+	return [
+		...limbs(gamma),
+		c,
+		(k + c * x) % Q
+	];
+};
+/**
+* Whether `proof` proves `alpha` under `publicKey`, as `ECVRFVerifier.verify` decides: gamma must
+* be a curve point with the `y` as submitted (the router multiplies it as given), `c` must fit 16
+* bytes, `s` must be below the group order, and `alpha` must hash to a point within the cap.
+*/
+const verify = ({ publicKey, proof, alpha }) => {
+	const [gammaX, gammaY, c, s] = proof;
+	if (c >= C_LIMIT || s >= Q) return false;
+	try {
+		const y = point(publicKey);
+		const gamma = point([gammaX, gammaY]);
+		const hashed = hashToCurve(publicKey, hexToBytes(alpha), 50);
+		if (hashed === null) return false;
+		const h = hashed.point;
+		const u = G.mulAddUnsafe(s, y.negate(), c);
+		const v = h.mulAddUnsafe(s, gamma.negate(), c);
+		return challenge([
+			h,
+			gamma,
+			u,
+			v
+		]) === c;
+	} catch {
+		return false;
+	}
+};
+/**
+* The 81-byte RFC 9381 proof string: compressed gamma, `c` in 16 bytes, `s` in 32. Throws when
+* a scalar does not fit.
+*/
+const encodeProof = ([gammaX, gammaY, c, s]) => bytesToHex(concatBytes(encodePoint(gammaX, gammaY), numberToBytesBE(c, C_BYTES), numberToBytesBE(s, 32)));
+/** The router's four limbs from an RFC 9381 proof string. Throws when the string is malformed. */
+const decodeProof = (encoded) => {
+	const proof = hexToBytes(encoded);
+	if (proof.length !== PROOF_BYTES) throw new Error("ECVRF proof must be 81 bytes");
+	const gamma = Point.fromBytes(proof.subarray(0, 33));
+	const c = bytesToNumberBE(proof.subarray(33, 49));
+	const s = bytesToNumberBE(proof.subarray(49));
+	if (s >= Q) throw new Error("ECVRF proof scalar s must be below the group order");
+	return [
+		...limbs(gamma),
+		c,
+		s
+	];
+};
+/**
+* The randomness a proof yields, as `VRF.gammaToHash` derives it: sha256 of the suite byte,
+* `0x03`, the compressed gamma, and a zero byte. Zero for the sentinel, as the router emits it.
+*/
+const deriveRandomness = (proof) => isSentinel(proof) ? zeroHash : bytesToHex(sha256(concatBytes(Uint8Array.of(SUITE, 3), encodePoint(proof[0], proof[1]), Uint8Array.of(0))));
+/** What the enclave signs over: `keccak256(abi.encode(proof))` in the router. */
+const proofCommitment = (proof) => keccak256(encodeAbiParameters([{ type: "uint256[4]" }], [proof]));
+/**
+* The try-and-increment attempts `VRF.tryHashToPoint` needs to hash `alpha` to a point for
+* `publicKey`, or `null` when none is found within `maxIterations`: such a request cannot be
+* proven and is closed with the sentinel.
+*/
+const hashToCurveIterations = (publicKey, alpha, maxIterations = 50) => hashToCurve(publicKey, hexToBytes(alpha), maxIterations)?.iterations ?? null;
+/** Whether the on-chain verifier can hash `alpha` to a point for `publicKey`. */
+const isFulfillable = (publicKey, alpha, maxIterations = 50) => hashToCurveIterations(publicKey, alpha, maxIterations) !== null;
+//#endregion
+export { HASH_TO_CURVE_MAX_ITERATIONS, SENTINEL_PROOF, decodeProof, deriveRandomness, encodeProof, hashToCurveIterations, isFulfillable, isSentinel, proofCommitment, prove, publicKeyPoint, verify };

package/dist/event.d.ts

@@ -0,0 +1,101 @@
+import { Proof } from "./ecvrf.js";
+import { Request } from "./request.js";
+import { Hex, Log } from "viem";
+//#region src/event.d.ts
+/**
+ * `VrfFacet.RandomnessRequested`: the id, consumer, and fulfiller indexed for filtering, the
+ * whole request as data so anyone can recompute the id and the fulfiller can echo it. Spelled
+ * out here because the protocol package does not depend on the contracts package; the
+ * contracts package's `test/Vrf.test.ts` decodes a real log through it and catches drift.
+ */
+export declare const randomnessRequestedEvent: {
+  readonly name: "RandomnessRequested";
+  readonly type: 'event';
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "requestId";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "consumer";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "fulfiller";
+    readonly indexed: true;
+  }, {
+    readonly type: 'tuple';
+    readonly components: readonly [{
+      readonly type: "address";
+      readonly name: "consumer";
+    }, {
+      readonly type: "uint64";
+      readonly name: "sequence";
+    }, {
+      readonly type: "address";
+      readonly name: "fulfiller";
+    }, {
+      readonly type: "uint40";
+      readonly name: "assignedAt";
+    }, {
+      readonly type: "uint96";
+      readonly name: "fee";
+    }, {
+      readonly type: "uint96";
+      readonly name: "gasPrice";
+    }, {
+      readonly type: "uint32";
+      readonly name: "callbackGasLimit";
+    }, {
+      readonly type: "bytes";
+      readonly name: "callbackData";
+    }];
+    readonly name: "request";
+  }];
+};
+/**
+ * `VrfFacet.RandomnessFulfilled`: the id indexed, the randomness and the evidence (the proof and
+ * the enclave signature, which a challenge takes) as data. Spelled out here for the same reason
+ * as the request event, and held to the real log by the same test.
+ */
+export declare const randomnessFulfilledEvent: {
+  readonly name: "RandomnessFulfilled";
+  readonly type: 'event';
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "requestId";
+    readonly indexed: true;
+  }, {
+    readonly type: "bytes32";
+    readonly name: "randomness";
+  }, {
+    readonly type: "uint256[4]";
+    readonly name: "proof";
+  }, {
+    readonly type: "bytes";
+    readonly name: "enclaveSignature";
+  }];
+};
+/** The part of a log the decoder reads, as every viem client returns it. */
+export type EventLog = Pick<Log, "data" | "topics">;
+/**
+ * Decodes a `RandomnessRequested` log into its id and a `Request` in the schema's shape, so
+ * the decoded request passes to `requestId` or a typed router call unchanged. Throws on a log
+ * of another event.
+ */
+export declare const decodeRandomnessRequested: (log: EventLog) => {
+  readonly requestId: Hex;
+  readonly request: Request;
+};
+/**
+ * Decodes a `RandomnessFulfilled` log into the id it closed, the randomness delivered, and the
+ * evidence (the proof and the enclave signature) a challenge or a verifier takes. Throws on a
+ * log of another event.
+ */
+export declare const decodeRandomnessFulfilled: (log: EventLog) => {
+  readonly requestId: Hex;
+  readonly randomness: Hex;
+  readonly proof: Proof;
+  readonly enclaveSignature: Hex;
+};
+//#endregion

package/dist/event.js

@@ -0,0 +1,53 @@
+import { decodeEventLog, parseAbiItem } from "viem";
+//#region src/event.ts
+/**
+* `VrfFacet.RandomnessRequested`: the id, consumer, and fulfiller indexed for filtering, the
+* whole request as data so anyone can recompute the id and the fulfiller can echo it. Spelled
+* out here because the protocol package does not depend on the contracts package; the
+* contracts package's `test/Vrf.test.ts` decodes a real log through it and catches drift.
+*/
+const randomnessRequestedEvent = parseAbiItem("event RandomnessRequested(bytes32 indexed requestId, address indexed consumer, address indexed fulfiller, (address consumer, uint64 sequence, address fulfiller, uint40 assignedAt, uint96 fee, uint96 gasPrice, uint32 callbackGasLimit, bytes callbackData) request)");
+/**
+* `VrfFacet.RandomnessFulfilled`: the id indexed, the randomness and the evidence (the proof and
+* the enclave signature, which a challenge takes) as data. Spelled out here for the same reason
+* as the request event, and held to the real log by the same test.
+*/
+const randomnessFulfilledEvent = parseAbiItem("event RandomnessFulfilled(bytes32 indexed requestId, bytes32 randomness, uint256[4] proof, bytes enclaveSignature)");
+/**
+* Decodes a `RandomnessRequested` log into its id and a `Request` in the schema's shape, so
+* the decoded request passes to `requestId` or a typed router call unchanged. Throws on a log
+* of another event.
+*/
+const decodeRandomnessRequested = (log) => {
+	const { args } = decodeEventLog({
+		abi: [randomnessRequestedEvent],
+		eventName: "RandomnessRequested",
+		data: log.data,
+		topics: log.topics
+	});
+	return {
+		requestId: args.requestId,
+		request: args.request
+	};
+};
+/**
+* Decodes a `RandomnessFulfilled` log into the id it closed, the randomness delivered, and the
+* evidence (the proof and the enclave signature) a challenge or a verifier takes. Throws on a
+* log of another event.
+*/
+const decodeRandomnessFulfilled = (log) => {
+	const { args } = decodeEventLog({
+		abi: [randomnessFulfilledEvent],
+		eventName: "RandomnessFulfilled",
+		data: log.data,
+		topics: log.topics
+	});
+	return {
+		requestId: args.requestId,
+		randomness: args.randomness,
+		proof: args.proof,
+		enclaveSignature: args.enclaveSignature
+	};
+};
+//#endregion
+export { decodeRandomnessFulfilled, decodeRandomnessRequested, randomnessFulfilledEvent, randomnessRequestedEvent };