randomness-js

.github/workflows/build.yml

@@ -0,0 +1,26 @@
+name: build
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: "actions/checkout@v4"
+
+      - name: Install nodejs 🔧
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22.3.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -0,0 +1,18 @@
+# Compiler files
+cache/
+out/
+src/generated
+node_modules
+index.js
+*.d.ts
+
+# Ignores development broadcast logs
+!/broadcast
+/broadcast/*/31337/
+/broadcast/**/dry-run/
+
+# Docs
+docs/
+
+# Dotenv file
+.env

README.md

@@ -0,0 +1,7 @@
+## @randamu/randomness-js
+
+A convenience library for retrieving, verifying and deriving randomness from the dcrypt network.
+
+Build everything by running `npm run build`. This creates an `index.js` and `index.d.ts` at the root directory.
+
+Solidity interfaces for randomenss can be found in the [contracts](./contracts) directory.

contracts/IRandomnessReceiver.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+interface IRandomnessReceiver {
+    /**
+     * @notice Receives a random value associated with a specific request.
+     * @dev This function is called to provide the randomness generated for a given request ID.
+     * It is intended to be called by a trusted source that provides randomness.
+     * @param requestID The unique identifier of the randomness request.
+     * @param randomness The generated random value, provided as a `bytes32` type.
+     */
+    function receiveRandomness(uint256 requestID, bytes32 randomness) external;
+}

contracts/IRandomnessSender.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+import "./TypesLib.sol";
+
+// todo subscription and payments
+// todo we could embed the following for subscription and payments - subscriptionID, numberOfRequestTxConfirmations, callbackGasLimit, numRandomValues
+// todo check for potential gaps in using uint256 as id compared to bytes32
+interface IRandomnessSender {
+    /**
+     * @notice Requests the generation of a random value for a specified blockchain height.
+     * @dev Initiates a randomness request.
+     * The generated randomness will be associated with the returned `requestID`.
+     * @return requestID The unique identifier assigned to this randomness request.
+     */
+    function requestRandomness() external returns (uint256 requestID);
+    /**
+     * @notice Retrieves a specific request by its ID.
+     * @dev This function returns the Request struct associated with the given requestId.
+     * @param requestId The ID of the request to retrieve.
+     * @return The Request struct corresponding to the given requestId.
+     */
+    function getRequest(uint256 requestId) external view returns (TypesLib.RandomnessRequest memory);
+
+    /**
+     * @notice Retrieves all requests.
+     * @dev This function returns an array of all Request structs stored in the contract.
+     * @return An array containing all the Request structs.
+     */
+    function getAllRequests() external view returns (TypesLib.RandomnessRequest[] memory);
+    /**
+     * @notice Generates a message from the given request.
+     * @dev Creates a hash-based message using the `DST` and `nonce` fields of the `Request` struct.
+     * The resulting message is the hash of the encoded values, packed into a byte array.
+     * @param r The `Request` struct containing the data for generating the message.
+     * @return A byte array representing the hashed and encoded message.
+     */
+    function messageFrom(TypesLib.RandomnessRequest memory r) external pure returns (bytes memory);
+}

contracts/TypesLib.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+library TypesLib {
+
+    // RandomnessRequest stores details needed to verify the signature
+    struct RandomnessRequest {
+        uint256 requestID;
+        address callback;
+    }
+
+}

eslint.config.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {"ignores": ["src/generated/**", "index.js"]}
+);

jest.config.mjs

@@ -0,0 +1,11 @@
+export default {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.(ts|tsx)$": ["ts-jest", {
+      useESM: true,
+    }],
+  },
+};
+