PRNG Library with Pyth Entropy Integration (#1733)

* Pyth Entropy PRNG library

* Update to a contract to store internal state

* Add seed setter function

* Make functions internal

* Add tests and address PR comments

* Run end-of-file fixer

target_chains/ethereum/contracts/forge-test/PRNG.t.sol

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache 2
+pragma solidity ^0.8.0;
+
+import "@pythnetwork/entropy-sdk-solidity/PRNG.sol";
+import "forge-std/Test.sol";
+
+contract PRNGTestHelper is PRNG {
+    constructor(bytes32 _seed) PRNG(_seed) {}
+
+    function publicNextBytes32() public returns (bytes32) {
+        return nextBytes32();
+    }
+
+    function publicRandUint() public returns (uint256) {
+        return randUint();
+    }
+
+    function publicRandUint64() public returns (uint64) {
+        return randUint64();
+    }
+
+    function publicRandUintRange(
+        uint256 min,
+        uint256 max
+    ) public returns (uint256) {
+        return randUintRange(min, max);
+    }
+
+    function publicRandomPermutation(
+        uint256 length
+    ) public returns (uint256[] memory) {
+        return randomPermutation(length);
+    }
+}
+
+contract PRNGTest is Test {
+    PRNGTestHelper prng;
+
+    function setUp() public {
+        prng = new PRNGTestHelper(keccak256(abi.encode("initial seed")));
+    }
+
+    function testNextBytes32() public {
+        bytes32 randomValue1 = prng.publicNextBytes32();
+        bytes32 randomValue2 = prng.publicNextBytes32();
+
+        assertNotEq(
+            randomValue1,
+            randomValue2,
+            "Random values should not be equal"
+        );
+    }
+
+    function testRandUint() public {
+        uint256 randomValue1 = prng.publicRandUint();
+        uint256 randomValue2 = prng.publicRandUint();
+
+        assertNotEq(
+            randomValue1,
+            randomValue2,
+            "Random values should not be equal"
+        );
+    }
+
+    function testRandUint64() public {
+        uint64 randomValue1 = prng.publicRandUint64();
+        uint64 randomValue2 = prng.publicRandUint64();
+
+        assertNotEq(
+            randomValue1,
+            randomValue2,
+            "Random values should not be equal"
+        );
+    }
+
+    function testRandUintRange() public {
+        uint256 min = 10;
+        uint256 max = 20;
+
+        for (uint256 i = 0; i < 100; i++) {
+            uint256 randomValue = prng.publicRandUintRange(min, max);
+            assertGe(
+                randomValue,
+                min,
+                "Random value should be greater than or equal to min"
+            );
+            assertLt(randomValue, max, "Random value should be less than max");
+        }
+    }
+
+    function testRandomPermutation() public {
+        uint256 length = 5;
+        uint256[] memory permutation = prng.publicRandomPermutation(length);
+
+        assertEq(permutation.length, length, "Permutation length should match");
+
+        bool[] memory found = new bool[](length);
+        for (uint256 i = 0; i < length; i++) {
+            assertLt(
+                permutation[i],
+                length,
+                "Permutation value should be within range"
+            );
+            found[permutation[i]] = true;
+        }
+        for (uint256 i = 0; i < length; i++) {
+            assertTrue(found[i], "Permutation should contain all values");
+        }
+    }
+}

target_chains/ethereum/entropy_sdk/solidity/PRNG.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache 2
+pragma solidity ^0.8.0;
+
+/// @title PRNG Contract
+/// @notice A contract for pseudorandom number generation and related utility functions
+/// @dev This PRNG contract is designed to work with Pyth Entropy as the seed source.
+///      Pyth Entropy provides secure, rapid random number generation for blockchain applications,
+///      enabling responsive UX for NFT mints, games, and other use cases requiring randomness.
+contract PRNG {
+    bytes32 private seed;
+    uint256 private nonce;
+
+    /// @notice Initialize the PRNG with a seed
+    /// @param _seed The Pyth Entropy seed (bytes32)
+    constructor(bytes32 _seed) {
+        seed = _seed;
+        nonce = 0;
+    }
+
+    /// @notice Set a new seed and reset the nonce
+    /// @param _newSeed The new seed (bytes32)
+    function setSeed(bytes32 _newSeed) internal {
+        seed = _newSeed;
+        nonce = 0;
+    }
+
+    /// @notice Generate the next random bytes32 value and update the state
+    /// @return The next random bytes32 value
+    function nextBytes32() internal returns (bytes32) {
+        bytes32 result = keccak256(abi.encode(seed, nonce));
+        nonce++;
+        return result;
+    }
+
+    /// @notice Generate a random uint256 value
+    /// @return A random uint256 value
+    function randUint() internal returns (uint256) {
+        return uint256(nextBytes32());
+    }
+
+    /// @notice Generate a random uint64 value
+    /// @return A random uint64 value
+    function randUint64() internal returns (uint64) {
+        return uint64(uint256(nextBytes32()));
+    }
+
+    /// @notice Generate a random uint256 value within a specified range
+    /// @param min The minimum value (inclusive)
+    /// @param max The maximum value (exclusive)
+    /// @return A random uint256 value between min and max
+    /// @dev The result is uniformly distributed between min and max, with a slight bias toward lower numbers.
+    /// @dev This bias is insignificant as long as (max - min) << MAX_UINT256.
+    function randUintRange(
+        uint256 min,
+        uint256 max
+    ) internal returns (uint256) {
+        require(max > min, "Max must be greater than min");
+        return (randUint() % (max - min)) + min;
+    }
+
+    /// @notice Generate a random permutation of a sequence
+    /// @param length The length of the sequence to permute
+    /// @return A randomly permuted array of uint256 values
+    function randomPermutation(
+        uint256 length
+    ) internal returns (uint256[] memory) {
+        uint256[] memory permutation = new uint256[](length);
+        for (uint256 i = 0; i < length; i++) {
+            permutation[i] = i;
+        }
+        for (uint256 i = 0; i < length; i++) {
+            uint256 j = i + (randUint() % (length - i));
+            (permutation[i], permutation[j]) = (permutation[j], permutation[i]);
+        }
+        return permutation;
+    }
+}

target_chains/ethereum/entropy_sdk/solidity/README.md

@@ -101,3 +101,47 @@ This method will combine the user and provider's random numbers, along with the
 
 The [Coin Flip](/target_chains/ethereum/examples/coin_flip) example demonstrates how to build a smart contract that
 interacts with Pyth Entropy as well as a typescript client for that application.
+
+## PRNG Contract
+
+The PRNG (Pseudorandom Number Generation) Contract is designed to work seamlessly with Pyth Entropy.
+
+### Features
+
+- **Pyth Entropy Integration**: Utilizes Pyth Entropy as a secure seed source
+- **Stateful Randomness**: Maintains an internal state to ensure unique random numbers on each call
+- **Versatile Random Generation**: Includes functions for generating random uint256, uint64, integers within specified ranges, and permutations
+- **Random Bytes Generation**: Ability to generate random byte sequences of specified length
+
+### Key Functions
+
+- `randUint() -> uint256`: Generate a random uint256 value
+- `randUint64() -> uint64`: Generate a random uint64 value
+- `randUintRange(uint256 min, uint256 max) -> uint256`: Generate a random integer within a specified range
+- `randomBytes(uint256 length) -> bytes`: Generate a sequence of random bytes
+- `randomPermutation(uint256 length) -> uint256[]`: Generate a random permutation of a sequence
+
+### Usage
+
+To use the PRNG contract in your project:
+
+1. Create a contract that inherits from PRNG and uses its internal functions with a seed from Pyth Entropy:
+
+```solidity
+contract MyContract is PRNG {
+  constructor(bytes32 _seed) {
+    PRNG(_seed);
+  }
+}
+
+```
+
+2. Use the contract functions to generate random numbers:
+
+```solidity
+bytes32 pythEntropySeed = ...; // Get this from Pyth Entropy
+setSeed(pythEntropySeed)
+uint256 randomNumber = randUint();
+uint64 randomSmallNumber = randUint64();
+uint256 randomInRange = randUintRange(1, 100);
+```

target_chains/ethereum/entropy_sdk/solidity/abis/PRNG.json

@@ -0,0 +1,13 @@
+[
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "_seed",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "nonpayable",
+    "type": "constructor"
+  }
+]

target_chains/ethereum/entropy_sdk/solidity/package.json

@@ -12,7 +12,7 @@
   },
   "scripts": {
     "format": "prettier --write .",
-    "generate-abi": "generate-abis IEntropy IEntropyConsumer EntropyErrors EntropyEvents EntropyStructs",
+    "generate-abi": "generate-abis IEntropy IEntropyConsumer EntropyErrors EntropyEvents EntropyStructs PRNG",
     "check-abi": "git diff --exit-code abis"
   },
   "keywords": [