@d20dao/vrf-sdk 0.1.0

package/dist/sources.d.ts

@@ -0,0 +1,14 @@
+export interface ApiRequest {
+    operation: string;
+    parameters: Record<string, unknown>;
+    responseProjection?: Record<string, string>;
+}
+export interface ApiAttestation {
+    timestamp: bigint;
+    data: string;
+    signature: string;
+}
+export declare function canonicalApiRequest(request: ApiRequest): string;
+export declare function attestationDigest(requestHash: string, a: ApiAttestation): string;
+export declare function hashAttestation(requestHash: string, a: ApiAttestation): string;
+export declare function validateApiSignatureEncoding(signature: string): void;

package/dist/sources.js

@@ -0,0 +1,27 @@
+import { AbiCoder, getBytes, hexlify, keccak256, solidityPacked } from "ethers";
+const abi = AbiCoder.defaultAbiCoder();
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === "object")
+        return Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, v]) => [key, canonical(v)]);
+    return value;
+}
+export function canonicalApiRequest(request) {
+    const parts = [request.operation, canonical(request.parameters)];
+    if (request.responseProjection !== undefined)
+        parts.push(canonical(request.responseProjection));
+    return JSON.stringify(parts);
+}
+export function attestationDigest(requestHash, a) {
+    return keccak256(solidityPacked(["bytes32", "uint256", "bytes"], [requestHash, a.timestamp, a.data]));
+}
+export function hashAttestation(requestHash, a) {
+    return keccak256(abi.encode(["bytes32", "uint256", "bytes32", "bytes32"], [requestHash, a.timestamp, keccak256(a.data), keccak256(a.signature)]));
+}
+export function validateApiSignatureEncoding(signature) {
+    const bytes = getBytes(signature);
+    if (bytes.length !== 65 || (bytes[64] !== 27 && bytes[64] !== 28) ||
+        BigInt(hexlify(bytes.slice(32, 64))) > 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0n)
+        throw new Error("Expected canonical 65-byte low-s EIP-191 signature");
+}

package/dist/verification.d.ts

@@ -0,0 +1,37 @@
+import { type MappingSpec } from "./mapping.js";
+export type XY = readonly [bigint, bigint];
+export interface VRFProof {
+    pk: XY;
+    gamma: XY;
+    c: bigint;
+    s: bigint;
+    seed: bigint;
+    uWitness: string;
+    cGammaWitness: XY;
+    sHashWitness: XY;
+    zInv: bigint;
+}
+export interface RequestContext {
+    chainId: bigint;
+    coordinator: string;
+    keyHash: string;
+    requestId: bigint;
+    consumer: string;
+    clientSeed: string;
+    mapping: MappingSpec;
+    requestBlock: bigint;
+    targetBlock: bigint;
+    blockHash: string;
+    epochId: bigint;
+    epochHash: string;
+}
+export declare function deriveRequestSeed(r: RequestContext): bigint;
+export declare function hashPublicKey(pk: XY): string;
+export declare function hashProof(p: VRFProof): string;
+export declare function verifyVRFProof(proof: VRFProof, expectedKey: XY, expectedSeed: bigint): {
+    valid: true;
+    randomness: string;
+} | {
+    valid: false;
+    reason: string;
+};

package/dist/verification.js

@@ -0,0 +1,87 @@
+// Public-data verification only. Contains no secret-key operations or production proof generation.
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { mod, pow } from "@noble/curves/abstract/modular";
+import { AbiCoder, computeAddress, id, keccak256, solidityPacked, toBeHex } from "ethers";
+import { hashMapping } from "./mapping.js";
+const abi = AbiCoder.defaultAbiCoder();
+const Point = secp256k1.ProjectivePoint;
+const P = secp256k1.CURVE.Fp.ORDER;
+const N = secp256k1.CURVE.n;
+const MAX = (1n << 256n) - 1n;
+export function deriveRequestSeed(r) {
+    return BigInt(keccak256(abi.encode(["bytes32", "uint256", "address", "bytes32", "uint256", "address", "bytes32", "bytes32", "uint64", "uint64", "bytes32", "uint64", "bytes32"], [id("D20_VRF_SEED"), r.chainId, r.coordinator, r.keyHash, r.requestId,
+        r.consumer, r.clientSeed, hashMapping(r.mapping), r.requestBlock, r.targetBlock, r.blockHash, r.epochId, r.epochHash])));
+}
+export function hashPublicKey(pk) { return keccak256(abi.encode(["uint256[2]"], [pk])); }
+export function hashProof(p) {
+    return keccak256(abi.encode([
+        "tuple(uint256[2] pk,uint256[2] gamma,uint256 c,uint256 s,uint256 seed,address uWitness,uint256[2] cGammaWitness,uint256[2] sHashWitness,uint256 zInv)",
+    ], [p]));
+}
+function xy(point) { const a = point.toAffine(); return [a.x, a.y]; }
+function point(p) {
+    if (p[0] < 0n || p[0] >= P || p[1] < 0n || p[1] >= P)
+        throw new Error("Non-canonical point");
+    const q = Point.fromAffine({ x: p[0], y: p[1] });
+    q.assertValidity();
+    if (q.equals(Point.ZERO))
+        throw new Error("Point at infinity");
+    return q;
+}
+function fieldHash(bytes) {
+    let x = BigInt(keccak256(bytes));
+    while (x >= P)
+        x = BigInt(keccak256(toBeHex(x, 32)));
+    return x;
+}
+function hashToCurve(pk, input) {
+    let x = fieldHash(solidityPacked(["uint256", "uint256[2]", "uint256"], [1n, pk, input]));
+    for (;;) {
+        const y2 = mod(x * x * x + 7n, P);
+        let y = pow(y2, (P + 1n) / 4n, P);
+        if (mod(y * y, P) === y2) {
+            if (y % 2n)
+                y = P - y;
+            return point([x, y]);
+        }
+        x = fieldHash(toBeHex(x, 32));
+    }
+}
+/// Verify with EXPECTED key and seed, not values trusted merely because they came in the proof.
+export function verifyVRFProof(proof, expectedKey, expectedSeed) {
+    try {
+        if (proof.pk[0] !== expectedKey[0] || proof.pk[1] !== expectedKey[1])
+            throw new Error("Wrong public key");
+        if (proof.seed !== expectedSeed)
+            throw new Error("Wrong request seed");
+        for (const scalar of [proof.c, proof.s, proof.seed, proof.zInv])
+            if (scalar < 0n || scalar > MAX)
+                throw new Error("Scalar outside uint256");
+        const pk = point(proof.pk), gamma = point(proof.gamma);
+        const cg = point(proof.cGammaWitness), sh = point(proof.sHashWitness);
+        const c = mod(proof.c, N), s = mod(proof.s, N);
+        if (c === 0n || s === 0n)
+            throw new Error("Zero scalar");
+        const h = hashToCurve(proof.pk, expectedSeed);
+        if (!gamma.multiply(c).equals(cg) || !h.multiply(s).equals(sh))
+            throw new Error("Invalid multiplication witness");
+        if (proof.cGammaWitness[0] === proof.sHashWitness[0])
+            throw new Error("Witness points not distinct");
+        const lz = mod(proof.sHashWitness[0] - proof.cGammaWitness[0], P);
+        const dx = mod(lz * lz, P), dy = mod(lz * lz * lz, P);
+        if (mod((dx === dy ? dx : mod(dx * dy, P)) * proof.zInv, P) !== 1n)
+            throw new Error("Invalid inverse witness");
+        const u = pk.multiply(c).add(Point.BASE.multiply(s));
+        const uAddress = computeAddress(`0x${u.toHex(false)}`);
+        if (uAddress.toLowerCase() !== proof.uWitness.toLowerCase())
+            throw new Error("Invalid U witness");
+        const v = cg.add(sh);
+        const derivedC = BigInt(keccak256(solidityPacked(["uint256", "uint256[2]", "uint256[2]", "uint256[2]", "uint256[2]", "address"], [2n, xy(h), proof.pk, proof.gamma, xy(v), uAddress])));
+        if (derivedC !== proof.c)
+            throw new Error("Invalid challenge");
+        return { valid: true, randomness: keccak256(abi.encode(["uint256", "uint256[2]"], [3n, proof.gamma])) };
+    }
+    catch (error) {
+        return { valid: false, reason: error instanceof Error ? error.message : "Invalid proof" };
+    }
+}

package/examples/DiceConsumer.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {D20VRFConsumer} from "@d20dao/vrf-sdk/contracts/D20VRFConsumer.sol";
+import {ID20VRF} from "@d20dao/vrf-sdk/contracts/interfaces/ID20VRF.sol";
+import {D20VRFRequests} from "@d20dao/vrf-sdk/contracts/libraries/D20VRFRequests.sol";
+
+/// @notice Minimal request/storage starter; no game payment, proof, mint or deployment policy.
+contract DiceConsumer is D20VRFConsumer {
+    using D20VRFRequests for ID20VRF;
+    struct Roll { address player; bytes32 rawWord; bool ready; }
+    mapping(uint256 => Roll) public rolls;
+    mapping(uint256 => bool) public refunded;
+    error WrongFee();
+    error UnexpectedCallback();
+    error NotReady();
+
+    constructor(address coordinator) D20VRFConsumer(coordinator) {}
+
+    function roll(bytes32 clientSeed, uint32 callbackGasLimit) external payable returns (uint256 requestId) {
+        ID20VRF rng = ID20VRF(vrfCoordinator);
+        if (msg.value != rng.requestFee()) revert WrongFee();
+        requestId = rng.d20(D20VRFRequests.Options(clientSeed, callbackGasLimit, msg.sender));
+        rolls[requestId] = Roll(msg.sender, bytes32(0), false);
+    }
+
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
+        Roll storage result = rolls[requestId];
+        if (result.player == address(0) || result.ready || refunded[requestId]) revert UnexpectedCallback();
+        result.rawWord = randomness;
+        result.ready = true;
+    }
+
+    // Requires a coordinator implementation supporting refund notifications.
+    function _onRefund(uint256 requestId) internal override {
+        Roll storage result = rolls[requestId];
+        if (result.player == address(0) || result.ready) revert UnexpectedCallback();
+        refunded[requestId] = true;
+    }
+
+    function result(uint256 requestId) external view returns (uint256) {
+        if (!rolls[requestId].ready) revert NotReady();
+        return ID20VRF(vrfCoordinator).getMappedResult(requestId)[0];
+    }
+}

package/notices/CHAINLINK-LICENSE

@@ -0,0 +1,193 @@
+Copyright (c) 2018 SmartContract ChainLink Limited SEZC
+
+Portions of this software are licensed as follows:
+
+The MIT License (MIT)
+
+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.
+
+===============================================================================
+`./pkg/bindings/abigen` is licensed as follows: 
+
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+Copyright © 2016–2025 The go-ethereum Authors
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/notices/PROVENANCE.md

@@ -0,0 +1,11 @@
+# Vendored VRF verifier
+
+- Upstream: https://github.com/smartcontractkit/chainlink-evm
+- Commit: `b6cf3a6ff90c7172e1d6090d056c0f77282450ce`
+- File: `contracts/src/v0.8/vrf/VRF.sol`
+- Raw source: https://raw.githubusercontent.com/smartcontractkit/chainlink-evm/b6cf3a6ff90c7172e1d6090d056c0f77282450ce/contracts/src/v0.8/vrf/VRF.sol
+- SHA-256: `98e0345fd2dd42178cad4ad16dd8b18621112078d63d0c64839c8bd01c539350`
+- License: MIT as declared in the source. The upstream root license is preserved in `CHAINLINK-LICENSE` (including notices for upstream components not vendored here).
+- Modifications: none. `npm run vendor:check` verifies the original bytes.
+
+This is the Chainlink secp256k1/Keccak VRF construction described in that source, with its documented differences from the referenced IETF draft. It is not advertised as RFC 9381 wire-format interoperability. Reusing this file neither makes D20DAO a Chainlink service nor extends any upstream audit to our coordinator, mapping, consumer or keeper.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@d20dao/vrf-sdk",
+  "version": "0.1.0",
+  "description": "D20DAO verifiable randomness: Solidity consumer helpers, contract ABIs and public proof replay",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./abi": {
+      "types": "./dist/abi.d.ts",
+      "import": "./dist/abi.js"
+    },
+    "./epoch": {
+      "types": "./dist/epoch.d.ts",
+      "import": "./dist/epoch.js"
+    },
+    "./abi/D20VRFCoordinator.json": "./abi/D20VRFCoordinator.json",
+    "./abi/EpochEntropy.json": "./abi/EpochEntropy.json",
+    "./contracts/*": "./contracts/*",
+    "./examples/*": "./examples/*",
+    "./AGENTS.md": "./AGENTS.md"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "contracts/**/*.sol",
+    "examples/*.sol",
+    "AGENTS.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "notices/*",
+    "BUILD-MANIFEST.json",
+    "PROTOCOL-PROVENANCE.json",
+    "abi/D20VRFCoordinator.json",
+    "abi/EpochEntropy.json"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test",
+    "test": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@noble/curves": "1.9.7",
+    "ethers": "6.17.0"
+  },
+  "devDependencies": {
+    "@openzeppelin/contracts": "5.6.1",
+    "@types/node": "24.10.0",
+    "esbuild": "0.28.2",
+    "solc": "0.8.28",
+    "typescript": "5.9.3",
+    "@openzeppelin/contracts-upgradeable": "5.6.1"
+  },
+  "overrides": {
+    "solc": {
+      "tmp": "0.2.7"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d20dao/d20-sdk.git"
+  }
+}