@d20dao/vrf-sdk 0.1.2 → 0.3.0

package/examples/DiceConsumer.sol

@@ -3,24 +3,31 @@ 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";
+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.
 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));
+        // 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
+        );
         rolls[requestId] = Roll(msg.sender, bytes32(0), false);
     }
 
@@ -31,7 +38,7 @@ contract DiceConsumer is D20VRFConsumer {
         result.ready = true;
     }
 
-    // Requires a coordinator implementation supporting refund notifications.
+    // 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();

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "@d20dao/vrf-sdk",
-  "version": "0.1.2",
-  "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"
-  }
-}
+{
+  "name": "@d20dao/vrf-sdk",
+  "version": "0.3.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"
+  }
+}