@d20dao/vrf-sdk 0.3.4 → 0.5.0

package/dist/templates.js

@@ -0,0 +1,220 @@
+import { getBytes, hexlify, toUtf8Bytes, toUtf8String } from "ethers";
+/// Data templates: the exact signed-data grammar of an epoch recipe, with the verdicts of EpochEntropy's DataTemplate.
+/// A template is a byte sequence of segments, each an opcode and its operands:
+///   0x01 LITERAL len bytes[len]  exactly these bytes (1 <= len <= 128)
+///   0x02 HEX     n               exactly n characters 0-9 or a-f (1 <= n <= 128)
+///   0x03 DECIMAL flags           unsigned JSON number: 0 or a nonzero digit then digits, then an optional fraction
+///                                when flags & 1 and an optional exponent when flags & 2 (flags <= 3)
+///   0x04 INTEGER min max         a nonzero digit then digits, min <= digit count <= max (1 <= min <= max <= 128)
+/// Variable segments are greedy and never backtrack; data matches when the segments consume it exactly. A well-formed
+/// template has at most 256 bytes, at least one variable segment, and a shortest match of at most 128 bytes.
+export const MAX_EPOCH_DATA_BYTES = 128, MAX_DATA_TEMPLATE_BYTES = 256;
+const LITERAL = 0x01, HEX = 0x02, DECIMAL = 0x03, INTEGER = 0x04, FRACTION = 0x01, EXPONENT = 0x02;
+const byteOperand = (value, name) => {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_EPOCH_DATA_BYTES)
+        throw new Error(`Data template ${name} must be an integer from 1 to ${MAX_EPOCH_DATA_BYTES}`);
+    return value;
+};
+/// Encode readable segments as template bytes; throws with the rule a segment breaks.
+export function encodeDataTemplate(segments) {
+    if (!Array.isArray(segments))
+        throw new Error("A data template is a list of segments");
+    const bytes = [];
+    segments.forEach((segment, index) => {
+        const keys = segment !== null && typeof segment === "object" ? Object.keys(segment) : [];
+        if (keys.length !== 1)
+            throw new Error(`Data template segment ${index} must have exactly one of literal, hex, decimal or integer`);
+        if ("literal" in segment) {
+            if (typeof segment.literal !== "string")
+                throw new Error(`Data template segment ${index}: literal must be a string`);
+            const text = toUtf8Bytes(segment.literal);
+            byteOperand(text.length, `segment ${index} literal length in bytes`);
+            bytes.push(LITERAL, text.length, ...text);
+        }
+        else if ("hex" in segment) {
+            bytes.push(HEX, byteOperand(segment.hex, `segment ${index} hex length`));
+        }
+        else if ("decimal" in segment) {
+            const { fraction, exponent } = segment.decimal ?? {};
+            if (typeof fraction !== "boolean" || typeof exponent !== "boolean" || Object.keys(segment.decimal).length !== 2)
+                throw new Error(`Data template segment ${index}: decimal needs boolean fraction and exponent`);
+            bytes.push(DECIMAL, (fraction ? FRACTION : 0) | (exponent ? EXPONENT : 0));
+        }
+        else if ("integer" in segment) {
+            const { minDigits, maxDigits } = segment.integer ?? {};
+            byteOperand(minDigits, `segment ${index} integer minDigits`);
+            byteOperand(maxDigits, `segment ${index} integer maxDigits`);
+            if (minDigits > maxDigits || Object.keys(segment.integer).length !== 2)
+                throw new Error(`Data template segment ${index}: integer needs minDigits <= maxDigits`);
+            bytes.push(INTEGER, minDigits, maxDigits);
+        }
+        else
+            throw new Error(`Data template segment ${index} must have exactly one of literal, hex, decimal or integer`);
+    });
+    const template = hexlify(Uint8Array.from(bytes));
+    const problem = templateProblem(Uint8Array.from(bytes));
+    if (problem)
+        throw new Error(`Invalid data template: ${problem}`);
+    return template;
+}
+/// Why a template is not well-formed, or undefined when it is. Same rules as DataTemplate.isValid.
+function templateProblem(t) {
+    if (t.length === 0 || t.length > MAX_DATA_TEMPLATE_BYTES)
+        return `it must be 1 to ${MAX_DATA_TEMPLATE_BYTES} bytes`;
+    let at = 0, shortest = 0, variable = false;
+    while (at < t.length) {
+        const op = t[at];
+        if (op === LITERAL) {
+            if (at + 1 >= t.length)
+                return `truncated literal at byte ${at}`;
+            const n = t[at + 1];
+            if (n === 0 || n > MAX_EPOCH_DATA_BYTES || at + 2 + n > t.length)
+                return `invalid literal length at byte ${at}`;
+            shortest += n;
+            at += 2 + n;
+        }
+        else if (op === HEX) {
+            if (at + 1 >= t.length)
+                return `truncated hex segment at byte ${at}`;
+            const n = t[at + 1];
+            if (n === 0 || n > MAX_EPOCH_DATA_BYTES)
+                return `invalid hex length at byte ${at}`;
+            shortest += n;
+            at += 2;
+            variable = true;
+        }
+        else if (op === DECIMAL) {
+            if (at + 1 >= t.length || t[at + 1] > (FRACTION | EXPONENT))
+                return `invalid decimal flags at byte ${at}`;
+            shortest += 1;
+            at += 2;
+            variable = true;
+        }
+        else if (op === INTEGER) {
+            if (at + 2 >= t.length)
+                return `truncated integer segment at byte ${at}`;
+            const min = t[at + 1], max = t[at + 2];
+            if (min === 0 || min > max || max > MAX_EPOCH_DATA_BYTES)
+                return `invalid integer digit bounds at byte ${at}`;
+            shortest += min;
+            at += 3;
+            variable = true;
+        }
+        else
+            return `unknown segment opcode ${op} at byte ${at}`;
+    }
+    if (!variable)
+        return "it needs at least one hex, decimal or integer segment";
+    if (shortest > MAX_EPOCH_DATA_BYTES)
+        return `its shortest match exceeds ${MAX_EPOCH_DATA_BYTES} bytes`;
+    return undefined;
+}
+export function isValidDataTemplate(template) { return templateProblem(getBytes(template)) === undefined; }
+/// Throws unless the template is well-formed.
+export function validateDataTemplate(template) {
+    const problem = templateProblem(getBytes(template));
+    if (problem)
+        throw new Error(`Invalid data template: ${problem}`);
+}
+/// The readable segments of a well-formed template whose literals are UTF-8 text.
+export function decodeDataTemplate(template) {
+    const t = getBytes(template);
+    validateDataTemplate(t);
+    const segments = [];
+    for (let at = 0; at < t.length;) {
+        const op = t[at];
+        if (op === LITERAL) {
+            segments.push({ literal: toUtf8String(t.slice(at + 2, at + 2 + t[at + 1])) });
+            at += 2 + t[at + 1];
+        }
+        else if (op === HEX) {
+            segments.push({ hex: t[at + 1] });
+            at += 2;
+        }
+        else if (op === DECIMAL) {
+            segments.push({ decimal: { fraction: (t[at + 1] & FRACTION) !== 0, exponent: (t[at + 1] & EXPONENT) !== 0 } });
+            at += 2;
+        }
+        else {
+            segments.push({ integer: { minDigits: t[at + 1], maxDigits: t[at + 2] } });
+            at += 3;
+        }
+    }
+    return segments;
+}
+const isDigit = (c) => c !== undefined && c >= 0x30 && c <= 0x39;
+function digits(d, p) { while (isDigit(d[p]))
+    p++; return p; }
+/// End of an unsigned JSON number starting at p, or -1.
+function decimalEnd(d, p, fraction, exponent) {
+    if (!isDigit(d[p]))
+        return -1;
+    if (d[p] === 0x30) {
+        p++;
+        if (isDigit(d[p]))
+            return -1;
+    }
+    else
+        p = digits(d, p);
+    if (fraction && d[p] === 0x2e) {
+        const first = p + 1;
+        p = digits(d, first);
+        if (p === first)
+            return -1;
+    }
+    if (exponent && (d[p] === 0x65 || d[p] === 0x45)) {
+        p++;
+        if (d[p] === 0x2b || d[p] === 0x2d)
+            p++;
+        const first = p;
+        p = digits(d, first);
+        if (p === first)
+            return -1;
+    }
+    return p;
+}
+/// Whether data is exactly a record the template describes; false for a malformed template.
+export function matchesDataTemplate(template, data) {
+    const t = getBytes(template), d = getBytes(data);
+    if (templateProblem(t) !== undefined || d.length === 0 || d.length > MAX_EPOCH_DATA_BYTES)
+        return false;
+    let p = 0;
+    for (let at = 0; at < t.length;) {
+        const op = t[at];
+        if (op === LITERAL) {
+            const n = t[at + 1];
+            if (p + n > d.length)
+                return false;
+            for (let i = 0; i < n; i++)
+                if (d[p + i] !== t[at + 2 + i])
+                    return false;
+            p += n;
+            at += 2 + n;
+        }
+        else if (op === HEX) {
+            const end = p + t[at + 1];
+            if (end > d.length)
+                return false;
+            for (; p < end; p++)
+                if (!isDigit(d[p]) && (d[p] < 0x61 || d[p] > 0x66))
+                    return false;
+            at += 2;
+        }
+        else if (op === DECIMAL) {
+            p = decimalEnd(d, p, (t[at + 1] & FRACTION) !== 0, (t[at + 1] & EXPONENT) !== 0);
+            if (p < 0)
+                return false;
+            at += 2;
+        }
+        else {
+            if (!isDigit(d[p]) || d[p] === 0x30)
+                return false;
+            const end = digits(d, p), count = end - p;
+            if (count < t[at + 1] || count > t[at + 2])
+                return false;
+            p = end;
+            at += 3;
+        }
+    }
+    return p === d.length;
+}

package/examples/DiceConsumer.sol

@@ -3,48 +3,56 @@ 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 {RandomnessMapping} from "@d20dao/vrf-sdk/contracts/libraries/RandomnessMapping.sol";
-
-/// @notice Minimal request/storage starter; no game payment, proof, mint or deployment policy.
-/// @dev The player pays the request. A wallet cannot know the exact same-transaction quote in advance, so it quotes
-///      off-chain with quoteFeeAt(callbackGasLimit, latestBlock.baseFeePerGas) plus a buffer (the SDK's quoteRequestFee
-///      helper does this) and sends that value. The whole payment is forwarded: the coordinator escrows exactly
-///      quoteFee(callbackGasLimit) and credits any excess to the player (the refund address) as refund credit that only
-///      the player can pull with withdrawRefundCredit. Underpayment reverts inside the coordinator with
-///      IncorrectFee(expected, actual). A contract that funds requests from its own balance would instead pay
-///      rng.quoteFee(callbackGasLimit) in the same transaction, as the D20VRFRequests helpers do.
+import {D20VRFRequests} from "@d20dao/vrf-sdk/contracts/libraries/D20VRFRequests.sol";
+
+/// @notice One d20 per player, paid by the player. Swap `d20` for `d6` or `coinFlip` and nothing else moves.
 contract DiceConsumer is D20VRFConsumer {
-    struct Roll { address player; bytes32 rawWord; bool ready; }
+    using D20VRFRequests for ID20VRF;
+
+    /// The callback does two storage writes and nothing else, and the fee grows with this number.
+    uint32 private constant CALLBACK_GAS = 100_000;
+
+    struct Roll { address player; bytes32 word; bool ready; }
     mapping(uint256 => Roll) public rolls;
-    mapping(uint256 => bool) public refunded;
+
+    error Underpaid(uint256 quoted, uint256 sent);
+    error ChangeRefused();
     error UnexpectedCallback();
     error NotReady();
 
     constructor(address coordinator) D20VRFConsumer(coordinator) {}
 
-    function roll(bytes32 clientSeed, uint32 callbackGasLimit) external payable returns (uint256 requestId) {
-        // One d20. The callback still receives the raw word; result() reads the canonical mapped value.
-        RandomnessMapping.Spec memory spec = RandomnessMapping.Spec(RandomnessMapping.Operation.DiceRoll, 0, 20, 1, 0);
-        requestId = ID20VRF(vrfCoordinator).requestMappedRandomness{value: msg.value}(
-            clientSeed, callbackGasLimit, msg.sender, spec
-        );
+    function roll() external payable returns (uint256 requestId) {
+        ID20VRF rng = ID20VRF(vrfCoordinator);
+        // quoteFee prices from block.basefee, so it is exact here and only here. A wallet cannot read it in
+        // advance: off-chain it quotes quoteFeeAt(gas, the latest header's baseFeePerGas) plus a buffer and
+        // sends that, never through eth_call, where the base fee is reported as 0.
+        uint256 fee = rng.quoteFee(CALLBACK_GAS);
+        if (msg.value < fee) revert Underpaid(fee, msg.value);
+        // The helper pays exactly `fee` out of this contract's balance, which msg.value just funded.
+        // The player is the refund address, so if the request expires, refundRequest returns the fee straight to them.
+        requestId = rng.d20(D20VRFRequests.Options(keccak256(abi.encode(msg.sender)), CALLBACK_GAS, msg.sender));
         rolls[requestId] = Roll(msg.sender, bytes32(0), false);
+        // Hand the player's buffer back now. Left with the coordinator it becomes refund credit they would
+        // have to claim in a separate withdrawRefundCredit transaction.
+        if (msg.value > fee) {
+            (bool sent,) = payable(msg.sender).call{value: msg.value - fee}("");
+            if (!sent) revert ChangeRefused();
+        }
     }
 
     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;
-    }
-
-    // Called after an expired request's refund share was paid to the player or recorded as the player's refund credit.
-    function _onRefund(uint256 requestId) internal override {
-        Roll storage result = rolls[requestId];
-        if (result.player == address(0) || result.ready) revert UnexpectedCallback();
-        refunded[requestId] = true;
+        Roll storage entry = rolls[requestId];
+        // Refuse a request this contract never made, and a repeat of one it already holds. A failed delivery is
+        // retried by anyone with retryCallback and a successful one is never repeated; the check costs one read.
+        if (entry.player == address(0) || entry.ready) revert UnexpectedCallback();
+        // Store, do not compute. The callback runs inside CALLBACK_GAS; work that overruns it fails the
+        // delivery, and although the request stays served and paid, someone must retryCallback it.
+        entry.word = randomness;
+        entry.ready = true;
     }
 
+    /// @return 1 to 20. The coordinator maps the stored word; a losing roll is never re-rolled.
     function result(uint256 requestId) external view returns (uint256) {
         if (!rolls[requestId].ready) revert NotReady();
         return ID20VRF(vrfCoordinator).getMappedResult(requestId)[0];

package/examples/LootDropConsumer.sol

@@ -0,0 +1,60 @@
+// 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 {RandomnessMapping} from "@d20dao/vrf-sdk/contracts/libraries/RandomnessMapping.sol";
+
+/// @notice A weighted drop: common 60%, uncommon 25%, rare 13%, legendary 2%. Edit weights and TOTAL_WEIGHT
+///         together to move the odds; nothing else changes.
+contract LootDropConsumer is D20VRFConsumer {
+    uint32 private constant CALLBACK_GAS = 100_000;
+    uint256 private constant TOTAL_WEIGHT = 1000;
+    /// Tier 0 to 3, rarest last. Must sum to TOTAL_WEIGHT.
+    uint256[4] private weights = [uint256(600), 250, 130, 20];
+
+    struct Drop { address player; bytes32 word; bool ready; }
+    mapping(uint256 => Drop) public drops;
+
+    error UnexpectedCallback();
+    error NotReady();
+
+    constructor(address coordinator) D20VRFConsumer(coordinator) {}
+
+    function open() external payable returns (uint256 requestId) {
+        // One draw in [1, TOTAL_WEIGHT]. The coordinator samples the range without modulo bias and stores the
+        // mapping with the request, so the draw is read back from getMappedResult and anyone can replay it.
+        // Asking for the range you actually want is what makes the weights below mean what they say.
+        RandomnessMapping.Spec memory spec =
+            RandomnessMapping.Spec(RandomnessMapping.Operation.NumberRange, 1, TOTAL_WEIGHT, 1, 0);
+        // Forwards everything sent: the coordinator keeps exactly its quote for this transaction, reverts
+        // IncorrectFee if that is more than arrived, and credits the surplus to msg.sender as refund credit.
+        requestId = ID20VRF(vrfCoordinator).requestMappedRandomness{value: msg.value}(
+            keccak256(abi.encode(msg.sender, block.number)), CALLBACK_GAS, msg.sender, spec
+        );
+        drops[requestId] = Drop(msg.sender, bytes32(0), false);
+    }
+
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
+        Drop storage drop = drops[requestId];
+        // Unknown request, or a repeat of one already delivered: neither may touch a finished drop.
+        if (drop.player == address(0) || drop.ready) revert UnexpectedCallback();
+        // Store the word and stop. The tier walk below is cheap, but it belongs on the reading side: a
+        // callback that runs out of CALLBACK_GAS fails delivery, while a stored word can be read forever.
+        drop.word = randomness;
+        drop.ready = true;
+    }
+
+    /// @return tier 0 common, 1 uncommon, 2 rare, 3 legendary. Read-only: one request, one answer, forever.
+    function tierOf(uint256 requestId) external view returns (uint256 tier) {
+        if (!drops[requestId].ready) revert NotReady();
+        uint256 draw = ID20VRF(vrfCoordinator).getMappedResult(requestId)[0];
+        uint256 cursor;
+        // Weights become adjacent ranges: 1-600 common, 601-850 uncommon, 851-980 rare, the rest legendary.
+        for (uint256 i; i + 1 < weights.length; ++i) {
+            cursor += weights[i];
+            if (draw <= cursor) return i;
+        }
+        return weights.length - 1;
+    }
+}

package/examples/RaffleConsumer.sol

@@ -0,0 +1,71 @@
+// 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 {RandomnessMapping} from "@d20dao/vrf-sdk/contracts/libraries/RandomnessMapping.sol";
+
+/// @notice One winner drawn from a list of entrants. Swap ChooseOne for ChooseMany to draw several.
+contract RaffleConsumer is D20VRFConsumer {
+    uint32 private constant CALLBACK_GAS = 100_000;
+
+    address[] public entrants;
+    /// The outstanding or served request: zero before the first draw, and zero again once an expired one was refunded.
+    uint256 public drawId;
+    bytes32 public word;
+    bool public closed; bool public drawn;
+
+    error AlreadyClosed();
+    error NoEntrants();
+    error RaffleFull();
+    error AlreadyDrawn();
+    error UnexpectedCallback();
+    error NotDrawn();
+
+    constructor(address coordinator) D20VRFConsumer(coordinator) {}
+
+    function enter() external {
+        if (closed) revert AlreadyClosed();
+        // ChooseOne answers with an index, and the coordinator maps at most 256 items.
+        if (entrants.length == 256) revert RaffleFull();
+        entrants.push(msg.sender);
+    }
+
+    function draw() external payable {
+        // A raffle that can be drawn twice is not a raffle: one served request, one winner, and no second
+        // request while one is outstanding or after one was served.
+        if (drawId != 0) revert AlreadyDrawn();
+        if (entrants.length == 0) revert NoEntrants();
+        closed = true;
+        // The answer is an index, so the list must be frozen before the request goes out; hashing it into the
+        // client seed publishes that promise, because RandomnessRequested logs the seed. msg.value is
+        // forwarded whole: the coordinator keeps exactly its quote, reverts IncorrectFee when that is more
+        // than arrived, and credits the surplus to msg.sender as refund credit to withdraw later.
+        drawId = ID20VRF(vrfCoordinator).requestMappedRandomness{value: msg.value}(
+            keccak256(abi.encode(entrants)), CALLBACK_GAS, msg.sender,
+            RandomnessMapping.Spec(RandomnessMapping.Operation.ChooseOne, 0, 0, 1, uint32(entrants.length))
+        );
+    }
+
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
+        // Only the one request this raffle made, and only once: a failed delivery is retried by anyone with
+        // retryCallback, and ids this contract never used are not its business.
+        if (requestId != drawId || drawn) revert UnexpectedCallback();
+        // Store and stop, so the callback cannot run out of its budget. Paying the prize belongs in a
+        // separate transaction anyone can send once `drawn` is true.
+        word = randomness;
+        drawn = true;
+    }
+
+    /// If no proof is accepted within 60 seconds the request expires and anyone may call refundRequest(drawId)
+    /// on the coordinator. That returns the fee to whoever sent draw() and then calls this hook: the list stays
+    /// frozen and draw() may be sent again, so an expired request never leaves the raffle stuck.
+    function _onRefund(uint256 requestId) internal override {
+        if (requestId == drawId && !drawn) drawId = 0;
+    }
+
+    function winner() external view returns (address) {
+        if (!drawn) revert NotDrawn();
+        return entrants[ID20VRF(vrfCoordinator).getMappedResult(drawId)[0]];
+    }
+}

package/notices/BLS-BN254-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kevin Charm
+
+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/notices/PROVENANCE.md

@@ -9,3 +9,15 @@
 - 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.
+
+# Vendored BLS library on BN254
+
+- Upstream: https://github.com/kevincharm/bls-bn254
+- Commit: `9f70fb4dff2cd0921dc2144929dc0aff6f21a9b9` (release 2.0.0)
+- Files, in `bls-bn254/`:
+  - `contracts/BLS.sol`, SHA-256 `887fd94553b9d6d0a247900bdb05523d3b9ef3b8ca049e2a0524a0b1a9d37e69`
+  - `contracts/ModExp.sol`, SHA-256 `fd91ae9291511668914b05fece03fb9bf6e2b57f7784d2edddc82456af12b495`
+- License: MIT, preserved in `bls-bn254/LICENSE`, SHA-256 `af36460fa628a7aca8c5b1f1b6b3615376f00212284fa0fd61a013ee982a3666`.
+- Modifications: none. `npm run vendor:check` verifies the original bytes, the license included.
+
+`D20BeaconVerifier` uses this library's RFC 9380 hash-to-curve onto G1 (expand_message_xmd with keccak256 and the Shallue-van de Woestijne map) and its point checks. These are the operations of drand's `bls-bn254-unchained-on-g1` scheme. The verifier runs the pairing itself, with a fixed gas allowance, instead of the library's `verifySingle`, which forwards all remaining gas to the precompile. Reusing this file neither makes D20DAO a drand or League of Entropy service nor extends any upstream review to our registry or keeper.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@d20dao/vrf-sdk",
-  "version": "0.3.4",
-  "description": "D20DAO verifiable randomness: Solidity consumer helpers, contract ABIs and public proof replay",
+  "version": "0.5.0",
+  "description": "Verifiable randomness (VRF) for onchain apps: Solidity consumers, contract ABIs, USDC fee quotes and public proof replay. Live on Arc.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -28,6 +28,7 @@
     },
     "./abi/D20VRFCoordinator.json": "./abi/D20VRFCoordinator.json",
     "./abi/EpochEntropy.json": "./abi/EpochEntropy.json",
+    "./abi/D20BeaconVerifier.json": "./abi/D20BeaconVerifier.json",
     "./contracts/*": "./contracts/*",
     "./examples/*": "./examples/*",
     "./AGENTS.md": "./AGENTS.md",
@@ -40,13 +41,15 @@
     "examples/*.sol",
     "AGENTS.md",
     "API.md",
+    "CHANGELOG.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
     "notices/*",
     "BUILD-MANIFEST.json",
     "PROTOCOL-PROVENANCE.json",
     "abi/D20VRFCoordinator.json",
-    "abi/EpochEntropy.json"
+    "abi/EpochEntropy.json",
+    "abi/D20BeaconVerifier.json"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -75,5 +78,29 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/d20dao/d20-sdk.git"
-  }
+  },
+  "homepage": "https://d20dao.org",
+  "bugs": {
+    "url": "https://github.com/d20dao/d20-sdk/issues"
+  },
+  "keywords": [
+    "vrf",
+    "verifiable-random-function",
+    "verifiable-randomness",
+    "randomness",
+    "random-number",
+    "rng",
+    "oracle",
+    "arc",
+    "arc-network",
+    "usdc",
+    "solidity",
+    "smart-contracts",
+    "evm",
+    "ethers",
+    "onchain",
+    "dice",
+    "raffle",
+    "d20dao"
+  ]
 }

package/contracts/examples/MiningRandomnessConsumer.sol

@@ -1,59 +0,0 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.28;
-
-import {D20VRFConsumer} from "../D20VRFConsumer.sol";
-import {ID20VRF} from "../interfaces/ID20VRF.sol";
-
-/// @notice Integration building block, not a replacement for the game's mining/economy contracts.
-/// @dev The actual game validates PoW, locks payment and immutable claim attributes BEFORE
-///      calling _requestForClaim inside that same transaction. No user reveal/contribution call.
-abstract contract MiningRandomnessConsumer is D20VRFConsumer {
-    struct ClaimRandomness { uint256 requestId; bytes32 randomness; bool requested; bool ready; }
-    mapping(uint256 => ClaimRandomness) public claimRandomness;
-    mapping(uint256 => uint256) public requestToClaim;
-    mapping(uint256 => bool) private knownRequest;
-    event ClaimRandomnessRequested(uint256 indexed claimId, uint256 indexed requestId);
-    event ClaimReady(uint256 indexed claimId, uint256 indexed requestId, bytes32 randomness);
-    error ClaimAlreadyRequested();
-    error UnexpectedCallback();
-    error ClaimNotReady();
-    error InvalidCandidate();
-
-    constructor(address coordinator) D20VRFConsumer(coordinator) {}
-
-    function _requestForClaim(uint256 claimId, bytes32 lockedWork, uint32 callbackGasLimit, address refundAddress)
-        internal returns (uint256 requestId)
-    {
-        if (claimRandomness[claimId].requested) revert ClaimAlreadyRequested();
-        claimRandomness[claimId].requested = true;
-        ID20VRF rng = ID20VRF(vrfCoordinator);
-        // The same-transaction quote is exact; only off-chain senders need a buffer.
-        requestId = rng.requestRandomness{value: rng.quoteFee(callbackGasLimit)}(
-            keccak256(abi.encode(claimId, lockedWork)), callbackGasLimit, refundAddress
-        );
-        claimRandomness[claimId].requestId = requestId;
-        requestToClaim[requestId] = claimId;
-        knownRequest[requestId] = true;
-        emit ClaimRandomnessRequested(claimId, requestId);
-    }
-
-    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
-        if (!knownRequest[requestId]) revert UnexpectedCallback();
-        uint256 claimId = requestToClaim[requestId];
-        ClaimRandomness storage claim = claimRandomness[claimId];
-        if (claim.ready) revert UnexpectedCallback();
-        claim.randomness = randomness;
-        claim.ready = true;
-        emit ClaimReady(claimId, requestId, randomness);
-    }
-
-    function candidateSeed(uint256 claimId, uint8 candidate) public view returns (bytes32) {
-        ClaimRandomness storage claim = claimRandomness[claimId];
-        if (!claim.ready) revert ClaimNotReady();
-        if (candidate >= 3) revert InvalidCandidate();
-        return keccak256(abi.encode(
-            keccak256("VRF_D20DAO_CARD_V1"), block.chainid, address(this),
-            claimId, claim.requestId, claim.randomness, candidate
-        ));
-    }
-}