@verify-network/protocol 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,148 @@
+# @verify-network/protocol
+
+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/index.d.ts

@@ -76,7 +76,7 @@ export declare const NodeIdentity: Schema.Struct<{
 export type NodeIdentity = typeof NodeIdentity.Type;
 declare const DirectRequestRefused_base: Schema.Class<DirectRequestRefused, Schema.TaggedStruct<"DirectRequestRefused", {
   readonly reason: Schema.Literals<readonly ["too-long", "wrong-node", "deadline", "max-gas-price", "callback-gas-limit", "bad-signature", "unfulfillable", "insufficient-balance"]>;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * A 400: why `POST /direct` refused an authorization, cheapest check first (ADR 0026, 0028):
  * the callback data is over the router's cap; the named node is another; the deadline has
@@ -89,12 +89,12 @@ export declare class DirectRequestRefused extends DirectRequestRefused_base {}
 declare const NonceTaken_base: Schema.Class<NonceTaken, Schema.TaggedStruct<"NonceTaken", {
   readonly signer: Schema.String;
   readonly nonce: Schema.BigInt;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** A 409: this node already took up, or saw land, an authorization under `signer` and `nonce`. */
 export declare class NonceTaken extends NonceTaken_base {}
 declare const TooManyRequests_base: Schema.Class<TooManyRequests, Schema.TaggedStruct<"TooManyRequests", {
   readonly reason: Schema.Literals<readonly ["in-flight", "signer", "ip", "edge"]>;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * A 429: the node is past a bound (as many direct requests in flight as it takes at once, as
  * many under this signer, or a block on the caller's address for the incorrect authorizations it
@@ -104,7 +104,7 @@ declare const TooManyRequests_base: Schema.Class<TooManyRequests, Schema.TaggedS
 export declare class TooManyRequests extends TooManyRequests_base {}
 declare const NotServing_base: Schema.Class<NotServing, Schema.TaggedStruct<"NotServing", {
   readonly reason: Schema.Literals<readonly ["not-set-up", "not-active", "disconnected", "chain-unreachable"]>;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * A 503: the node serves no direct request right now: it is not set up; it is not in the active
  * set (exiting, ejected, forgotten, or stopped); its request source reports no connection, so it
@@ -113,7 +113,7 @@ declare const NotServing_base: Schema.Class<NotServing, Schema.TaggedStruct<"Not
 export declare class NotServing extends NotServing_base {}
 declare const DeadlinePassed_base: Schema.Class<DeadlinePassed, Schema.TaggedStruct<"DeadlinePassed", {
   readonly deadline: Schema.BigInt;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * A 504: the authorization's deadline passed before the source saw the fulfillment land: it can
  * no longer land, so the signer may make an on-chain request instead (ADR 0026).
@@ -286,7 +286,7 @@ type Pricing = {
 declare const RouterUnreadable_base: Schema.Class<RouterUnreadable, Schema.TaggedStruct<"RouterUnreadable", {
   readonly operation: Schema.String;
   readonly cause: Schema.Defect;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** The router could not be read; `operation` names the viem call. */
 export declare class RouterUnreadable extends RouterUnreadable_base {}
 /** The request being priced: its callback data's length, and its callback gas limit when not the router's default. */
@@ -370,7 +370,7 @@ type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
 declare const NoNodeServing_base: Schema.Class<NoNodeServing, Schema.TaggedStruct<"NoNodeServing", {
   readonly active: Schema.Int;
   readonly published: Schema.Int;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * No node to post to: of `active` nodes, `published` had an endpoint the client trusts the shape
  * of, and none of those answered `GET /` as itself in time.
@@ -378,13 +378,13 @@ declare const NoNodeServing_base: Schema.Class<NoNodeServing, Schema.TaggedStruc
 export declare class NoNodeServing extends NoNodeServing_base {}
 declare const SigningFailed_base: Schema.Class<SigningFailed, Schema.TaggedStruct<"SigningFailed", {
   readonly cause: Schema.Defect;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** The account did not sign the authorization: a wallet refused, or the key could not. */
 export declare class SigningFailed extends SigningFailed_base {}
 declare const UnexpectedResponse_base: Schema.Class<UnexpectedResponse, Schema.TaggedStruct<"UnexpectedResponse", {
   readonly status: Schema.Int;
   readonly body: Schema.String;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * The node answered something `POST /direct` does not: neither a landing nor a refusal it
  * spells, under a status that says the authorization was not taken up (a 4xx of the edge's, a
@@ -541,7 +541,7 @@ export declare const SubscriptionFrame: Schema.Union<readonly [Schema.Struct<{
   }>;
 }>]>;
 export type SubscriptionFrame = typeof SubscriptionFrame.Type;
-export declare const decodeSubscriptionFrame: (input: unknown, options?: import("effect/unstable/SchemaAST").ParseOptions) => Result.Result<{
+export declare const decodeSubscriptionFrame: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Result.Result<{
   readonly id: number;
   readonly result?: string;
   readonly error?: {
@@ -566,7 +566,7 @@ export declare const PendingLog: Schema.Struct<{
   readonly removed: Schema.optionalKey<Schema.Boolean>;
 }>;
 export type PendingLog = typeof PendingLog.Type;
-export declare const decodePendingLog: (input: unknown, options?: import("effect/unstable/SchemaAST").ParseOptions) => Result.Result<{
+export declare const decodePendingLog: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Result.Result<{
   readonly address: `0x${string}`;
   readonly topics: readonly `0x${string}`[];
   readonly data: `0x${string}`;
@@ -608,14 +608,14 @@ export declare const seenIn: (router: Address$1, result: unknown, at: number) =>
 declare const SubscriptionRefused_base: Schema.Class<SubscriptionRefused, Schema.TaggedStruct<"SubscriptionRefused", {
   readonly url: Schema.String;
   readonly reason: Schema.String;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** The endpoint refused the router's log subscription, or never confirmed it. */
 export declare class SubscriptionRefused extends SubscriptionRefused_base {
   get message(): string;
 }
 declare const WatchEnded_base: Schema.Class<WatchEnded, Schema.TaggedStruct<"WatchEnded", {
   readonly url: Schema.String;
-}>, import("effect/unstable/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** The socket carrying the router's logs ended while something was still waiting on it. */
 export declare class WatchEnded extends WatchEnded_base {
   get message(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verify-network/protocol",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Verify Network VRF protocol off-chain: ECVRF prove and verify, request ids, fulfillment typed data, router events and fees, and the router watch and direct-request client.",
   "license": "MIT",
   "files": [