Entropy Solidity SDK & usage example

fortuna/config.yaml

@@ -2,3 +2,9 @@ chains:
   optimism-goerli:
     geth_rpc_addr: https://goerli.optimism.io
     contract_addr: 0x28F16Af4D87523910b843a801454AEde5F9B0459
+  avalanche-fuji:
+    geth_rpc_addr: https://api.avax-test.network/ext/bc/C/rpc
+    contract_addr: 0xD42c7a708E74AD19401D907a14146F006c851Ee3
+  eos-evm-testnet:
+    geth_rpc_addr: https://api.testnet.evm.eosnetwork.com/
+    contract_addr: 0xD42c7a708E74AD19401D907a14146F006c851Ee3

fortuna/src/main.rs

@@ -16,7 +16,7 @@ pub mod state;
 // Server TODO list:
 // - Tests
 // - Reduce memory requirements for storing hash chains to increase scalability
-// - Name things nicely (service name, API resource names)
+// - Name things nicely (API resource names)
 // - README
 // - Choose data formats for binary data
 #[tokio::main]

package.json

@@ -12,6 +12,7 @@
     "target_chains/cosmwasm/tools",
     "target_chains/cosmwasm/deploy-scripts",
     "target_chains/ethereum/contracts",
+    "target_chains/ethereum/entropy_sdk/solidity",
     "target_chains/ethereum/sdk/js",
     "target_chains/ethereum/sdk/solidity",
     "target_chains/ethereum/examples/oracle_swap/app",

target_chains/ethereum/contracts/contracts/random/PythRandom.sol

@@ -2,9 +2,10 @@
 
 pragma solidity ^0.8.0;
 
-import "./PythRandomState.sol";
-import "./PythRandomErrors.sol";
-import "./PythRandomEvents.sol";
+import "@pythnetwork/entropy-sdk-solidity/PythRandomState.sol";
+import "@pythnetwork/entropy-sdk-solidity/PythRandomErrors.sol";
+import "@pythnetwork/entropy-sdk-solidity/PythRandomEvents.sol";
+import "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
 
 // PythRandom implements a secure 2-party random number generation procedure. The protocol
 // is an extension of a simple commit/reveal protocol. The original version has the following steps:
@@ -78,7 +79,7 @@ import "./PythRandomEvents.sol";
 // - function to check invariants??
 // - need to increment pyth fees if someone transfers funds to the contract via another method
 // - off-chain data ERC support?
-contract PythRandom is PythRandomState, PythRandomEvents {
+contract PythRandom is IEntropy, PythRandomState {
     // TODO: Use an upgradeable proxy
     constructor(uint pythFeeInWei) {
         _state.accruedPythFeesInWei = 0;
@@ -95,7 +96,7 @@ contract PythRandom is PythRandomState, PythRandomEvents {
         bytes32 commitment,
         bytes32 commitmentMetadata,
         uint64 chainLength
-    ) public {
+    ) public override {
         if (chainLength == 0) revert PythRandomErrors.AssertionFailure();
 
         PythRandomStructs.ProviderInfo storage provider = _state.providers[
@@ -124,7 +125,7 @@ contract PythRandom is PythRandomState, PythRandomEvents {
     // Withdraw a portion of the accumulated fees for the provider msg.sender.
     // Calling this function will transfer `amount` wei to the caller (provided that they have accrued a sufficient
     // balance of fees in the contract).
-    function withdraw(uint256 amount) public {
+    function withdraw(uint256 amount) public override {
         PythRandomStructs.ProviderInfo storage providerInfo = _state.providers[
             msg.sender
         ];
@@ -155,7 +156,7 @@ contract PythRandom is PythRandomState, PythRandomEvents {
         address provider,
         bytes32 userCommitment,
         bool useBlockHash
-    ) public payable returns (uint64 assignedSequenceNumber) {
+    ) public payable override returns (uint64 assignedSequenceNumber) {
         PythRandomStructs.ProviderInfo storage providerInfo = _state.providers[
             provider
         ];
@@ -205,7 +206,7 @@ contract PythRandom is PythRandomState, PythRandomEvents {
         uint64 sequenceNumber,
         bytes32 userRandomness,
         bytes32 providerRevelation
-    ) public returns (bytes32 randomNumber) {
+    ) public override returns (bytes32 randomNumber) {
         // TODO: do we need to check that this request exists?
         // TODO: this method may need to be authenticated to prevent griefing
         bytes32 key = requestKey(provider, sequenceNumber);
@@ -257,41 +258,49 @@ contract PythRandom is PythRandomState, PythRandomEvents {
 
     function getProviderInfo(
         address provider
-    ) public view returns (PythRandomStructs.ProviderInfo memory info) {
+    )
+        public
+        view
+        override
+        returns (PythRandomStructs.ProviderInfo memory info)
+    {
         info = _state.providers[provider];
     }
 
     function getRequest(
         address provider,
         uint64 sequenceNumber
-    ) public view returns (PythRandomStructs.Request memory req) {
+    ) public view override returns (PythRandomStructs.Request memory req) {
         bytes32 key = requestKey(provider, sequenceNumber);
         req = _state.requests[key];
     }
 
-    function getFee(address provider) public view returns (uint feeAmount) {
+    function getFee(
+        address provider
+    ) public view override returns (uint feeAmount) {
         return _state.providers[provider].feeInWei + _state.pythFeeInWei;
     }
 
     function getAccruedPythFees()
         public
         view
+        override
         returns (uint accruedPythFeesInWei)
     {
         return _state.accruedPythFeesInWei;
     }
 
     function constructUserCommitment(
         bytes32 userRandomness
-    ) public pure returns (bytes32 userCommitment) {
+    ) public pure override returns (bytes32 userCommitment) {
         userCommitment = keccak256(bytes.concat(userRandomness));
     }
 
     function combineRandomValues(
         bytes32 userRandomness,
         bytes32 providerRandomness,
         bytes32 blockHash
-    ) public pure returns (bytes32 combinedRandomness) {
+    ) public pure override returns (bytes32 combinedRandomness) {
         combinedRandomness = keccak256(
             abi.encodePacked(userRandomness, providerRandomness, blockHash)
         );

target_chains/ethereum/contracts/package.json

@@ -36,6 +36,7 @@
     "@openzeppelin/hardhat-upgrades": "^1.22.1",
     "@pythnetwork/pyth-multisig-wh-message-builder": "*",
     "@pythnetwork/pyth-sdk-solidity": "^2.2.0",
+    "@pythnetwork/entropy-sdk-solidity": "*",
     "contract_manager": "*",
     "dotenv": "^10.0.0",
     "elliptic": "^6.5.2",

target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache 2
+pragma solidity ^0.8.0;
+
+import "./PythRandomEvents.sol";
+
+interface IEntropy is PythRandomEvents {
+    // Register msg.sender as a randomness provider. The arguments are the provider's configuration parameters
+    // and initial commitment. Re-registering the same provider rotates the provider's commitment (and updates
+    // the feeInWei).
+    //
+    // chainLength is the number of values in the hash chain *including* the commitment, that is, chainLength >= 1.
+    function register(
+        uint feeInWei,
+        bytes32 commitment,
+        bytes32 commitmentMetadata,
+        uint64 chainLength
+    ) external;
+
+    // Withdraw a portion of the accumulated fees for the provider msg.sender.
+    // Calling this function will transfer `amount` wei to the caller (provided that they have accrued a sufficient
+    // balance of fees in the contract).
+    function withdraw(uint256 amount) external;
+
+    // As a user, request a random number from `provider`. Prior to calling this method, the user should
+    // generate a random number x and keep it secret. The user should then compute hash(x) and pass that
+    // as the userCommitment argument. (You may call the constructUserCommitment method to compute the hash.)
+    //
+    // This method returns a sequence number. The user should pass this sequence number to
+    // their chosen provider (the exact method for doing so will depend on the provider) to retrieve the provider's
+    // number. The user should then call fulfillRequest to construct the final random number.
+    //
+    // This method will revert unless the caller provides a sufficient fee (at least getFee(provider)) as msg.value.
+    // Note that excess value is *not* refunded to the caller.
+    function request(
+        address provider,
+        bytes32 userCommitment,
+        bool useBlockHash
+    ) external payable returns (uint64 assignedSequenceNumber);
+
+    // Fulfill a request for a random number. This method validates the provided userRandomness and provider's proof
+    // against the corresponding commitments in the in-flight request. If both values are validated, this function returns
+    // the corresponding random number.
+    //
+    // Note that this function can only be called once per in-flight request. Calling this function deletes the stored
+    // request information (so that the contract doesn't use a linear amount of storage in the number of requests).
+    // If you need to use the returned random number more than once, you are responsible for storing it.
+    function reveal(
+        address provider,
+        uint64 sequenceNumber,
+        bytes32 userRandomness,
+        bytes32 providerRevelation
+    ) external returns (bytes32 randomNumber);
+
+    function getProviderInfo(
+        address provider
+    ) external view returns (PythRandomStructs.ProviderInfo memory info);
+
+    function getRequest(
+        address provider,
+        uint64 sequenceNumber
+    ) external view returns (PythRandomStructs.Request memory req);
+
+    function getFee(address provider) external view returns (uint feeAmount);
+
+    function getAccruedPythFees()
+        external
+        view
+        returns (uint accruedPythFeesInWei);
+
+    function constructUserCommitment(
+        bytes32 userRandomness
+    ) external pure returns (bytes32 userCommitment);
+
+    function combineRandomValues(
+        bytes32 userRandomness,
+        bytes32 providerRandomness,
+        bytes32 blockHash
+    ) external pure returns (bytes32 combinedRandomness);
+}

target_chains/ethereum/entropy_sdk/solidity/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pythnetwork/entropy-sdk-solidity",
+  "version": "0.1.0",
+  "description": "Generate secure random numbers with Pyth Entropy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyth-network/pyth-crosschain",
+    "directory": "target_chains/ethereum/entropy_sdk/solidity"
+  },
+  "scripts": {
+    "format": "npx prettier --write ."
+  },
+  "keywords": [
+    "pyth",
+    "solidity",
+    "random"
+  ],
+  "author": "Douro Labs",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/pyth-network/pyth-crosschain/issues"
+  },
+  "homepage": "https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ethereum/entropy_sdk/solidity",
+  "devDependencies": {
+    "prettier": "^2.7.1",
+    "prettier-plugin-solidity": "^1.0.0-rc.1",
+    "solc": "^0.8.15"
+  }
+}

target_chains/ethereum/examples/coin_flip/contract/.gitignore

@@ -0,0 +1,4 @@
+lib/*
+!lib/README.md
+cache
+out