IAPI3QRNGAdapter

Title: IAPI3QRNGAdapter

Author: Modified from API3 (https://github.com/api3dao/airnode)

Interface for the API3QRNGAdapter Diamond facet — quantum randomness via API3 Airnode RRP.

Request/track layer over the Airnode Request-Response Protocol. The diamond is its own sponsor (self-sponsoring): setSelfSponsorship registers it with the RRP, then requestRandomNumber makes a full request. The Airnode fulfils via fulfillRandomNumber, gated so only the configured Airnode RRP contract may call it (onlyAirnodeRrp). Consumer facets that inherit API3QRNGAdapter should override fulfillRandomNumber (calling super.fulfillRandomNumber first) to act on the randomness.

Functions

getConfig

Returns the current QRNG configuration.

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

Returns

Name	Type	Description
<none>	`QRNGConfig`

getUserKey

Returns the user key associated with a pending request.

function getUserKey(bytes32 requestId) external view returns (bytes32);

Parameters

Name	Type	Description
requestId	`bytes32`	The RRP-assigned request ID.

Returns

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

setConfig

Sets or replaces the QRNG configuration.

Caller must hold DEFAULT_ADMIN_ROLE. Reverts QRNGInvalidConfig on any zero field.

function setConfig(QRNGConfig calldata config) external;

Parameters

Name	Type	Description
config	`QRNGConfig`	The new configuration.

setSelfSponsorship

Registers (or revokes) this contract as its own sponsor with the Airnode RRP.

Caller must hold DEFAULT_ADMIN_ROLE. A full request only succeeds while self-sponsored.

function setSelfSponsorship(bool status) external;

Parameters

Name	Type	Description
status	`bool`	True to self-sponsor, false to revoke.

requestRandomNumber

Requests a quantum random number via the Airnode RRP.

Caller must hold DEFAULT_ADMIN_ROLE.

function requestRandomNumber(bytes32 userKey) external returns (bytes32 requestId);

Parameters

Name	Type	Description
userKey	`bytes32`	Arbitrary key the caller wants associated with this request.

Returns

Name	Type	Description
requestId	`bytes32`	The RRP-assigned request ID.

fulfillRandomNumber

Called by the Airnode RRP to deliver the random number.

Verifies the caller is the configured Airnode RRP, looks up the user key, clears the pending entry, decodes the random number, and emits RandomNumberFulfilled. Consumer facets should override this to consume the randomness.

function fulfillRandomNumber(bytes32 requestId, bytes calldata data) external;

Parameters

Name	Type	Description
requestId	`bytes32`	The RRP-assigned request ID.
data	`bytes`	The ABI-encoded random number (`abi.encode(uint256)`).

Events

QRNGConfigSet

Emitted when the QRNG configuration is updated.

event QRNGConfigSet(address airnodeRrp, address airnode, bytes32 endpointId, address sponsorWallet);

Parameters

Name	Type	Description
airnodeRrp	`address`	The Airnode RRP contract.
airnode	`address`	The Airnode serving requests.
endpointId	`bytes32`	The QRNG endpoint identifier.
sponsorWallet	`address`	The wallet paying for fulfilment gas.

QRNGSelfSponsorshipSet

Emitted when this contract's self-sponsorship status is changed.

event QRNGSelfSponsorshipSet(bool status);

Parameters

Name	Type	Description
status	`bool`	True if now self-sponsored, false if revoked.

RandomNumberRequested

Emitted when a random number is requested.

event RandomNumberRequested(bytes32 indexed requestId, bytes32 indexed userKey);

Parameters

Name	Type	Description
requestId	`bytes32`	The RRP-assigned request ID.
userKey	`bytes32`	The caller-supplied key associated with this request.

RandomNumberFulfilled

Emitted when the Airnode fulfils a request.

event RandomNumberFulfilled(bytes32 indexed requestId, bytes32 indexed userKey, uint256 randomNumber);

Parameters

Name	Type	Description
requestId	`bytes32`	The RRP-assigned request ID.
userKey	`bytes32`	The caller-supplied key originally associated with this request.
randomNumber	`uint256`	The delivered quantum random number.

Errors

QRNGNotConfigured

QRNG has not been configured (Airnode RRP address is zero).

error QRNGNotConfigured();

QRNGInvalidConfig

setConfig was called with a zero Airnode RRP, zero Airnode, zero endpoint, or zero wallet.

error QRNGInvalidConfig();

QRNGInvalidUserKey

requestRandomNumber was called with a zero userKey.

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

error QRNGInvalidUserKey();

QRNGOnlyAirnodeRrp

fulfillRandomNumber was called by an address other than the Airnode RRP contract.

error QRNGOnlyAirnodeRrp(address caller);

Parameters

Name	Type	Description
caller	`address`	The unauthorised caller.

QRNGRequestNotFound

The given request ID has no pending entry.

error QRNGRequestNotFound(bytes32 requestId);

Parameters

Name	Type	Description
requestId	`bytes32`	The unknown request ID.

Structs

QRNGConfig

API3 QRNG configuration. The sponsor is always this contract (self-sponsoring).

struct QRNGConfig {
        /// @notice The Airnode RRP contract.
        address airnodeRrp;
        /// @notice The Airnode serving requests.
        address airnode;
        /// @notice The QRNG endpoint identifier.
        bytes32 endpointId;
        /// @notice The wallet (derived from this sponsor) paying for fulfilment gas.
        address sponsorWallet;
    }

Properties

Name	Type	Description
airnodeRrp	`address`
airnode	`address`
endpointId	`bytes32`
sponsorWallet	`address`