@@ -29,6 +29,96 @@ interface IEntropy is EntropyEvents, EntropyEventsV2 {
2929 // balance of fees in the contract).
3030 function withdrawAsFeeManager (address provider , uint128 amount ) external ;
3131
32+ /// @notice Request a random number using the default provider with default gas limit
33+ /// @return assignedSequenceNumber A unique identifier for this request
34+ /// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
35+ /// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
36+ /// the generated random number.
37+ ///
38+ /// `entropyCallback` will be run with the `gasLimit` provided to this function.
39+ /// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
40+ /// by the provider's configured default limit.
41+ ///
42+ /// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2()`) as msg.value.
43+ /// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2()`
44+ /// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
45+ ///
46+ /// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
47+ /// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
48+ /// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
49+ function requestV2 ()
50+ external
51+ payable
52+ returns (uint64 assignedSequenceNumber );
53+
54+ /// @notice Request a random number using the default provider with specified gas limit
55+ /// @param gasLimit The gas limit for the callback function.
56+ /// @return assignedSequenceNumber A unique identifier for this request
57+ /// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
58+ /// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
59+ /// the generated random number.
60+ ///
61+ /// `entropyCallback` will be run with the `gasLimit` provided to this function.
62+ /// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
63+ /// by the provider's configured default limit.
64+ ///
65+ /// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(gasLimit)`) as msg.value.
66+ /// Note that the fee can change over time. Callers of this method should explicitly compute `getFeeV2(gasLimit)`
67+ /// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
68+ ///
69+ /// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
70+ /// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
71+ /// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
72+ function requestV2 (
73+ uint32 gasLimit
74+ ) external payable returns (uint64 assignedSequenceNumber );
75+
76+ /// @notice Request a random number from a specific provider with specified gas limit
77+ /// @param provider The address of the provider to request from
78+ /// @param gasLimit The gas limit for the callback function
79+ /// @return assignedSequenceNumber A unique identifier for this request
80+ /// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
81+ /// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
82+ /// the generated random number.
83+ ///
84+ /// `entropyCallback` will be run with the `gasLimit` provided to this function.
85+ /// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
86+ /// by the provider's configured default limit.
87+ ///
88+ /// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
89+ /// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
90+ /// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
91+ ///
92+ /// Note that this method uses an in-contract PRNG to generate the user's portion of the random number.
93+ /// Users must trust this PRNG in order to prove the result is random. If you wish to avoid this trust assumption,
94+ /// call a variant of `requestV2` that accepts a `userRandomNumber` parameter.
95+ function requestV2 (
96+ address provider ,
97+ uint32 gasLimit
98+ ) external payable returns (uint64 assignedSequenceNumber );
99+
100+ /// @notice Request a random number from a specific provider with a user-provided random number and gas limit
101+ /// @param provider The address of the provider to request from
102+ /// @param userRandomNumber A random number provided by the user for additional entropy
103+ /// @param gasLimit The gas limit for the callback function
104+ /// @return assignedSequenceNumber A unique identifier for this request
105+ /// @dev The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
106+ /// The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
107+ /// the generated random number.
108+ ///
109+ /// `entropyCallback` will be run with the `gasLimit` provided to this function.
110+ /// The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
111+ /// by the provider's configured default limit.
112+ ///
113+ /// This method will revert unless the caller provides a sufficient fee (at least `getFeeV2(provider, gasLimit)`) as msg.value.
114+ /// Note that provider fees can change over time. Callers of this method should explicitly compute `getFeeV2(provider, gasLimit)`
115+ /// prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
116+ function requestV2 (
117+ address provider ,
118+ bytes32 userRandomNumber ,
119+ uint32 gasLimit
120+ ) external payable returns (uint64 assignedSequenceNumber );
121+
32122 // As a user, request a random number from `provider`. Prior to calling this method, the user should
33123 // generate a random number x and keep it secret. The user should then compute hash(x) and pass that
34124 // as the userCommitment argument. (You may call the constructUserCommitment method to compute the hash.)
@@ -60,26 +150,6 @@ interface IEntropy is EntropyEvents, EntropyEventsV2 {
60150 bytes32 userRandomNumber
61151 ) external payable returns (uint64 assignedSequenceNumber );
62152
63- // Request a random number from `provider`, getting a callback with the result.
64- // The caller must specify a provider to fulfill the request -- `getDefaultProvider()` is a sane default --
65- // and a `userRandomNumber` to combine into the result. The method returns a sequence number which callers
66- // should save to correlate the request with the callback.
67- //
68- // The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
69- // The `entropyCallback` method on that interface will receive a callback with the returned sequence number and
70- // the generated random number. `entropyCallback` will be run with the `gasLimit` provided to this function.
71- // The `gasLimit` will be rounded up to a multiple of 10k (e.g., 19000 -> 20000), and furthermore is lower bounded
72- // by the provider's configured default limit.
73- //
74- // This method will revert unless the caller provides a sufficient fee (at least `getFeeForGas(provider, gasLimit)`) as msg.value.
75- // Note that provider fees can change over time. Thus, callers of this method should explictly compute `getFeeForGas(provider, gasLimit)`
76- // prior to each invocation (as opposed to hardcoding a value). Further note that excess value is *not* refunded to the caller.
77- function requestWithCallbackAndGasLimit (
78- address provider ,
79- bytes32 userRandomNumber ,
80- uint32 gasLimit
81- ) external payable returns (uint64 assignedSequenceNumber );
82-
83153 // Fulfill a request for a random number. This method validates the provided userRandomness and provider's proof
84154 // against the corresponding commitments in the in-flight request. If both values are validated, this function returns
85155 // the corresponding random number.
@@ -132,11 +202,22 @@ interface IEntropy is EntropyEvents, EntropyEventsV2 {
132202 ) external view returns (EntropyStructsV2.Request memory req );
133203
134204 // Get the fee charged by provider for a request with the default gasLimit (`request` or `requestWithCallback`).
135- // If you are calling `requestWithCallbackAndGasLimit` , please use `getFeeForGas `.
205+ // If you are calling any of the `requestV2` methods , please use `getFeeV2 `.
136206 function getFee (address provider ) external view returns (uint128 feeAmount );
137207
138- // Get the fee charged by `provider` for a request with a specific `gasLimit` (`requestWithCallbackAndGasLimit`).
139- function getFeeForGas (
208+ // Get the fee charged by the default provider for the default gas limit.
209+ // Use this function to determine the fee to pass to `requestV2`.
210+ function getFeeV2 () external view returns (uint128 feeAmount );
211+
212+ // Get the fee charged by the default provider for the specified gas limit.
213+ // Use this function to determine the fee to pass to `requestV2`.
214+ function getFeeV2 (
215+ uint32 gasLimit
216+ ) external view returns (uint128 feeAmount );
217+
218+ // Get the fee charged by `provider` for a request with a specific `gasLimit`.
219+ // Use this function to determine the fee to pass to `requestV2`.
220+ function getFeeV2 (
140221 address provider ,
141222 uint32 gasLimit
142223 ) external view returns (uint128 feeAmount );
0 commit comments