# ScaledEntropyProvider

**Contract Address:** [`0x5D030DEC2e0d38935e662C0d2feD44B050c8Ae51`](https://basescan.org/address/0x5D030DEC2e0d38935e662C0d2feD44B050c8Ae51)

Provides cryptographically secure random number generation using Pyth Network entropy. Used for provably fair drawing winner selection.

## State Variables

| Variable          | Type         | Description                   |
| ----------------- | ------------ | ----------------------------- |
| `entropy`         | `IEntropyV2` | Pyth Network entropy contract |
| `entropyProvider` | `address`    | Pyth entropy provider address |
| `pending`         | `mapping`    | Pending randomness requests   |

## Structs

### SetRequest

```solidity
struct SetRequest {
    uint8 samples;          // Number of random values to generate
    uint256 minRange;       // Minimum value (inclusive)
    uint256 maxRange;       // Maximum value (inclusive)
    bool withReplacement;   // Allow duplicate values
}
```

### PendingRequest (internal)

```solidity
struct PendingRequest {
    address callback;       // Contract to call with results
    bytes4 selector;        // Function selector for callback
    bytes context;          // Additional data for callback
    bytes32 userRandomNumber; // User-provided randomness
    SetRequest[] setRequests; // Randomness specifications
}
```

## Events

### ScaledRandomnessDelivered

```solidity
event ScaledRandomnessDelivered(
    uint64 indexed sequence,
    address indexed callback,
    uint256 samples
);
```

### EntropyFulfilled

```solidity
event EntropyFulfilled(uint64 indexed sequence, bytes32 randomNumber);
```

## Functions

### getFee

Get the fee required for an entropy request.

```solidity
function getFee(uint32 _gasLimit) public view returns (uint256)
```

**Parameters:**

| Name        | Type     | Description                      |
| ----------- | -------- | -------------------------------- |
| `_gasLimit` | `uint32` | Gas limit for callback execution |

**Returns:**

| Type      | Description       |
| --------- | ----------------- |
| `uint256` | Fee amount in wei |

**Example:**

```solidity
uint32 gasLimit = 500000;
uint256 fee = entropyProvider.getFee(gasLimit);
// Use this fee when calling requestAndCallbackScaledRandomness
```

***

### getEntropyContract

Get the address of the Pyth Network entropy contract.

```solidity
function getEntropyContract() external view returns (address)
```

**Returns:**

| Type      | Description                           |
| --------- | ------------------------------------- |
| `address` | Pyth Network entropy contract address |

***

### getEntropyProvider

Get the currently configured entropy provider.

```solidity
function getEntropyProvider() external view returns (address)
```

**Returns:**

| Type      | Description              |
| --------- | ------------------------ |
| `address` | Entropy provider address |

***

### getPendingRequest

Get details of a pending entropy request.

```solidity
function getPendingRequest(uint64 _sequence) external view returns (PendingRequest memory)
```

**Parameters:**

| Name        | Type     | Description             |
| ----------- | -------- | ----------------------- |
| `_sequence` | `uint64` | Request sequence number |

**Returns:**

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `PendingRequest` | Request details including callback info |

## How Pyth Entropy Works

### Request Flow

1. **Request**: Contract calls `requestAndCallbackScaledRandomness` with fee
2. **Pyth Processing**: Pyth Network generates cryptographic randomness
3. **Callback**: Pyth calls back with random number
4. **Scaling**: Provider scales randomness to requested ranges
5. **Delivery**: Callback function receives scaled results

### Lottery Drawing Example

For the Jackpot drawing:

```solidity
// Jackpot requests random numbers for drawing
SetRequest[] memory requests = new SetRequest[](2);

// Request 5 normal ball numbers without replacement
requests[0] = SetRequest({
    samples: 5,
    minRange: 1,
    maxRange: 69,          // Normal ball max
    withReplacement: false // Unique numbers
});

// Request 1 bonusball
requests[1] = SetRequest({
    samples: 1,
    minRange: 1,
    maxRange: 26,          // Bonusball max
    withReplacement: true  // Single value
});

// Request randomness (internal to Jackpot)
uint256 fee = entropy.getFee(gasLimit);
entropy.requestAndCallbackScaledRandomness{value: fee}(
    gasLimit,
    requests,
    callback.selector,
    context
);
```

## Randomness Methods

### Fisher-Yates Shuffle

Used for sampling **without replacement** (unique values):

* Guarantees no duplicate values
* Unbiased selection algorithm
* Used for normal ball selection

### Rejection Sampling

Used for **unbiased scaling**:

* Prevents modulo bias
* Ensures uniform distribution
* Used for both methods

## Security Properties

### Cryptographic Security

* Randomness generated by Pyth Network validators
* Unpredictable before reveal
* Verifiable on-chain

### Bias Prevention

* Rejection sampling eliminates modulo bias
* Fisher-Yates provides uniform permutation
* No advantage from timing or position

### Provable Fairness

* All randomness is on-chain verifiable
* Request and callback are auditable
* Results cannot be manipulated


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megapot.io/developers/contract-overview/entropy-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.