IPythEntropyAdapter

Title: IPythEntropyAdapter

Author: Modified from Pyth (https://github.com/pyth-network/pyth-crosschain)

Interface for the PythEntropyAdapter Diamond facet — on-demand (commit/reveal) randomness.

Request/track layer over Pyth Entropy. A request is caller-funded (the Entropy fee is quoted via getFee and any excess msg.value is refunded); the provider fulfils via entropyCallback, which is gated so only the configured Entropy contract may call it. Consumer facets that inherit PythEntropyAdapter should override entropyCallback (calling super.entropyCallback first) to act on the delivered randomness.

Functions

getConfig

Returns the current Entropy configuration.

function getConfig() external view returns (EntropyConfig memory);

Returns

Name	Type	Description
<none>	`EntropyConfig`

getFee

Returns the fee (in wei) required for one request under the current config.

function getFee() external view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

getUserKey

Returns the user key associated with a pending request.

function getUserKey(uint64 sequenceNumber) external view returns (bytes32);

Parameters

Name	Type	Description
sequenceNumber	`uint64`	The Entropy-assigned sequence number.

Returns

Name	Type	Description
<none>	`bytes32`	The user-supplied key, or `bytes32(0)` if not found.

setConfig

Sets or replaces the Entropy configuration.

Caller must hold DEFAULT_ADMIN_ROLE. Reverts EntropyInvalidConfig if entropy is zero.

function setConfig(EntropyConfig calldata config) external;

Parameters

Name	Type	Description
config	`EntropyConfig`	The new configuration.

requestRandomNumber

Requests a random number, caller-funded with excess refunded.

Caller must hold DEFAULT_ADMIN_ROLE and send msg.value >= getFee().

function requestRandomNumber(bytes32 userKey, bytes32 userRandomNumber)
        external
        payable
        returns (uint64 sequenceNumber);

Parameters

Name	Type	Description
userKey	`bytes32`	Arbitrary key the caller wants associated with this request.
userRandomNumber	`bytes32`	The caller's commitment to its half of the randomness.

Returns

Name	Type	Description
sequenceNumber	`uint64`	The Entropy-assigned sequence number.

entropyCallback

Called by the Entropy contract to deliver a random number.

Verifies the caller is the configured Entropy contract, looks up the user key, clears the pending entry, and emits RandomNumberFulfilled. Consumer facets should override this to consume the randomness.

function entropyCallback(uint64 sequence, address provider, bytes32 randomNumber) external;

Parameters

Name	Type	Description
sequence	`uint64`	The Entropy-assigned sequence number.
provider	`address`	The provider that fulfilled the request.
randomNumber	`bytes32`	The delivered random number.

Events

EntropyConfigSet

Emitted when the Entropy configuration is updated.

event EntropyConfigSet(address entropy, address provider);

Parameters

Name	Type	Description
entropy	`address`	The Pyth Entropy contract.
provider	`address`	The randomness provider (or `address(0)` to use the default provider).

RandomNumberRequested

Emitted when a random number is requested.

event RandomNumberRequested(uint64 indexed sequenceNumber, bytes32 indexed userKey);

Parameters

Name	Type	Description
sequenceNumber	`uint64`	The Entropy-assigned sequence number.
userKey	`bytes32`	The caller-supplied key associated with this request.

RandomNumberFulfilled

Emitted when the provider fulfils a request.

event RandomNumberFulfilled(uint64 indexed sequenceNumber, bytes32 indexed userKey, bytes32 randomNumber);

Parameters

Name	Type	Description
sequenceNumber	`uint64`	The Entropy-assigned sequence number.
userKey	`bytes32`	The caller-supplied key originally associated with this request.
randomNumber	`bytes32`	The delivered random number.

Errors

EntropyNotConfigured

Entropy has not been configured (entropy contract address is zero).

error EntropyNotConfigured();

EntropyInvalidConfig

setConfig was called with a zero Entropy contract address.

error EntropyInvalidConfig();

EntropyInvalidUserKey

requestRandomNumber was called with a zero userKey.

bytes32(0) is the sentinel used to detect a missing pending request.

error EntropyInvalidUserKey();

EntropyInsufficientFee

msg.value was less than the Entropy fee.

error EntropyInsufficientFee(uint256 provided, uint256 required);

Parameters

Name	Type	Description
provided	`uint256`	The value sent.
required	`uint256`	The required fee.

EntropyRefundFailed

The excess-fee refund to the caller failed.

error EntropyRefundFailed();

EntropyOnlyEntropy

entropyCallback was called by an address other than the Entropy contract.

error EntropyOnlyEntropy(address caller);

Parameters

Name	Type	Description
caller	`address`	The unauthorised caller.

EntropyRequestNotFound

The given sequence number has no pending entry.

error EntropyRequestNotFound(uint64 sequenceNumber);

Parameters

Name	Type	Description
sequenceNumber	`uint64`	The unknown sequence number.

Structs

EntropyConfig

Pyth Entropy configuration.

struct EntropyConfig {
        /// @notice The Pyth Entropy contract.
        address entropy;
        /// @notice The randomness provider (`address(0)` resolves to the Entropy default provider).
        address provider;
    }

Properties

Name	Type	Description
entropy	`address`
provider	`address`