Skip to content

feat(entropy): Split out V2 interface into separate file. #2645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 2, 2025
Merged

feat(entropy): Split out V2 interface into separate file. #2645

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0b5db8a
comment
jayantk May 1, 2025
e417127
version num
jayantk May 1, 2025
c4606d1
missed doc
jayantk May 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 2 additions & 119 deletions target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ pragma solidity ^0.8.0;
import "./EntropyEvents.sol";
import "./EntropyEventsV2.sol";
import "./EntropyStructsV2.sol";
import "./IEntropyV2.sol";

interface IEntropy is EntropyEvents, EntropyEventsV2 {
interface IEntropy is EntropyEvents, EntropyEventsV2, IEntropyV2 {
// 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).
Expand All @@ -29,96 +30,6 @@ interface IEntropy is EntropyEvents, EntropyEventsV2 {
// balance of fees in the contract).
function withdrawAsFeeManager(address provider, uint128 amount) external;

/// @notice Request a random number using the default provider with default gas limit
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2()`) as msg.value.
/// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2()`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2()
external
payable
returns (uint64 assignedSequenceNumber);

/// @notice Request a random number using the default provider with specified gas limit
/// @param gasLimit The gas limit for the callback function.
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(gasLimit)`) as msg.value.
/// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2(gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2(
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

/// @notice Request a random number from a specific provider with specified gas limit
/// @param provider The address of the provider to request from
/// @param gasLimit The gas limit for the callback function
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
/// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2(
address provider,
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

/// @notice Request a random number from a specific provider with a user-provided random number and gas limit
/// @param provider The address of the provider to request from
/// @param userRandomNumber A random number provided by the user for additional entropy
/// @param gasLimit The gas limit for the callback function
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
/// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
function requestV2(
address provider,
bytes32 userRandomNumber,
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

// 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.)
Expand Down Expand Up @@ -185,43 +96,15 @@ interface IEntropy is EntropyEvents, EntropyEventsV2 {
address provider
) external view returns (EntropyStructs.ProviderInfo memory info);

function getProviderInfoV2(
address provider
) external view returns (EntropyStructsV2.ProviderInfo memory info);

function getDefaultProvider() external view returns (address provider);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note that I moved this function over to IEntropyV2 as well since end users may want to call it


function getRequest(
address provider,
uint64 sequenceNumber
) external view returns (EntropyStructs.Request memory req);

function getRequestV2(
address provider,
uint64 sequenceNumber
) external view returns (EntropyStructsV2.Request memory req);

// Get the fee charged by provider for a request with the default gasLimit (`request` or `requestWithCallback`).
// If you are calling any of the `requestV2` methods, please use `getFeeV2`.
function getFee(address provider) external view returns (uint128 feeAmount);

// Get the fee charged by the default provider for the default gas limit.
// Use this function to determine the fee to pass to `requestV2`.
function getFeeV2() external view returns (uint128 feeAmount);

// Get the fee charged by the default provider for the specified gas limit.
// Use this function to determine the fee to pass to `requestV2`.
function getFeeV2(
uint32 gasLimit
) external view returns (uint128 feeAmount);

// Get the fee charged by `provider` for a request with a specific `gasLimit`.
// Use this function to determine the fee to pass to `requestV2`.
function getFeeV2(
address provider,
uint32 gasLimit
) external view returns (uint128 feeAmount);

function getAccruedPythFees()
external
view
Expand Down
150 changes: 150 additions & 0 deletions target_chains/ethereum/entropy_sdk/solidity/IEntropyV2.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
// SPDX-License-Identifier: Apache 2
pragma solidity ^0.8.0;

import "./EntropyEvents.sol";
import "./EntropyEventsV2.sol";
import "./EntropyStructsV2.sol";

interface IEntropyV2 is EntropyEventsV2 {
/// @notice Request a random number using the default provider with default gas limit
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2()`) as msg.value.
/// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2()`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2()
external
payable
returns (uint64 assignedSequenceNumber);

/// @notice Request a random number using the default provider with specified gas limit
/// @param gasLimit The gas limit for the callback function.
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(gasLimit)`) as msg.value.
/// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2(gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2(
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

/// @notice Request a random number from a specific provider with specified gas limit
/// @param provider The address of the provider to request from
/// @param gasLimit The gas limit for the callback function
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
/// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
///
/// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
/// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
/// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
function requestV2(
address provider,
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

/// @notice Request a random number from a specific provider with a user-provided random number and gas limit
/// @param provider The address of the provider to request from
/// @param userRandomNumber A random number provided by the user for additional entropy
/// @param gasLimit The gas limit for the callback function. Pass 0 to get a sane default value -- see note below.
/// @return assignedSequenceNumber A unique identifier for this request
/// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
/// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
/// the generated random number.
///
/// `entropyCallback` will be run with the `gasLimit` provided to this function.
/// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
/// by the provider's configured default limit.
///
/// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
/// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
/// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
function requestV2(
address provider,
bytes32 userRandomNumber,
uint32 gasLimit
) external payable returns (uint64 assignedSequenceNumber);

function getProviderInfoV2(
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

method docs on this function and below are new

address provider
) external view returns (EntropyStructsV2.ProviderInfo memory info);

/// @notice Get the address of the default entropy provider
/// @return provider The address of the default provider
/// @dev This method returns the address of the provider that will be used when no specific provider is specified
/// in the requestV2 calls. The default provider can be used to get the base fee and gas limit information.
function getDefaultProvider() external view returns (address provider);

/// @notice Get information about a specific request
/// @param provider The address of the provider that handled the request
/// @param sequenceNumber The unique identifier of the request
/// @return req The request information including status, random number, and other metadata
/// @dev This method allows querying the state of a previously made request. The returned Request struct
/// contains information about whether the request was fulfilled, the generated random number (if available),
/// and other metadata about the request.
function getRequestV2(
address provider,
uint64 sequenceNumber
) external view returns (EntropyStructsV2.Request memory req);

/// @notice Get the fee charged by the default provider for the default gas limit
/// @return feeAmount The fee amount in wei
/// @dev This method returns the base fee required to make a request using the default provider with
/// the default gas limit. This fee should be passed as msg.value when calling requestV2().
/// The fee can change over time, so this method should be called before each request.
function getFeeV2() external view returns (uint128 feeAmount);

/// @notice Get the fee charged by the default provider for a specific gas limit
/// @param gasLimit The gas limit for the callback function
/// @return feeAmount The fee amount in wei
/// @dev This method returns the fee required to make a request using the default provider with
/// the specified gas limit. This fee should be passed as msg.value when calling requestV2(gasLimit).
/// The fee can change over time, so this method should be called before each request.
function getFeeV2(
uint32 gasLimit
) external view returns (uint128 feeAmount);

/// @notice Get the fee charged by a specific provider for a request with a given gas limit
/// @param provider The address of the provider to query
/// @param gasLimit The gas limit for the callback function
/// @return feeAmount The fee amount in wei
/// @dev This method returns the fee required to make a request using the specified provider with
/// the given gas limit. This fee should be passed as msg.value when calling requestV2(provider, gasLimit)
/// or requestV2(provider, userRandomNumber, gasLimit). The fee can change over time, so this method
/// should be called before each request.
function getFeeV2(
address provider,
uint32 gasLimit
) external view returns (uint128 feeAmount);
}
Loading
Loading