Documentation

Easyntropy is a randomness oracle that supplies Solidity contracts with secure bytes32 seeds.

Installation

1. Install the package

Download the latest version of the package from Github (CURRENTLY THE REPO IS STILL PRIVATE). Integration contract can be found at /src/contracts/Easyntropy/EasyntropyConsumer.sol.

2. Add integration to your Solidity contract:

import "../Easyntropy/EasyntropyConsumer.sol";

contract DemoContract is EasyntropyConsumer {
  constructor(address _entropy) EasyntropyConsumer(_entropy) {}
}

The _entropy parameter should point to the Easyntropy oracle contract. The addresses are:

Usage

Once your contract implements the EasyntropyConsumer interface, you can start using the oracle.

To make a RNG request, call the easyntropyRequestWithCallback() function (provided by EasyntropyConsumer) on your contract. The fee will be automatically sent along with the transaction.

You can use the easyntropyFee() function (provided by EasyntropyConsumer) to retrieve the current fee.

The easyntropyRequestWithCallback() function returns a uint64 requestId, which can be used to track and reference the request when the response arrives.

Default RNG callback

By default, the oracle will invoke the easyntropyFulfill() function as the callback, so make sure such that function exists.

function exampleRNGRequest() public payable {
  if (msg.value < entropyFee()) revert NotEnoughEth();
  uint64 requestId = easyntropyRequestWithCallback();

  // See the examples page for how to use `requestId`
}

function easyntropyFulfill(uint64 requestId, bytes32 seed) external onlyEasyntropy {
  // `requestId` and `seed` are provided in the callback
}

Custom RNG callback

You can customize the callback function invoked by the oracle by passing a selector to the easyntropyRequestWithCallback() function.

This is especially useful if your contract uses RNG in multiple scenarios. It allows you to group requests and responses pairs together in a more readable way.

  function setPlayerStats() public payable {
    if (msg.value < entropyFee()) revert NotEnoughEth();
    easyntropyRequestWithCallback(this.assignPlayerStats.selector);
  }

  function assignPlayerStats(uint64 requestId, bytes32 seed) external onlyEasyntropy {
    // stats implementation...
  }

  function startBattle() public payable {
    if (msg.value < entropyFee()) revert NotEnoughEth();
    easyntropyRequestWithCallback(this.battle.selector);
  }

  function battle(uint64 requestId, bytes32 seed) external onlyEasyntropy {
    // battle implementation...
  }

RNG request without sending fee

Easyntropy allows you to prepay your balance so you don’t have to send the fee with each transaction.

Since the easyntropyRequestWithCallback() function automatically sends fees, the proper way to send a request to the oracle is:

function exampleRNGRequestWithoutFees() public payable {
  //
  // Assuming your balance covers the RNG fees, you don't need to send any additional fee:
  uint64 requestId = entropy.requestWithCallback();

  // See the examples page for how to use `requestId`
}

function easyntropyFulfill(uint64 requestId, bytes32 seed) external onlyEasyntropy {
  // `requestId` and `seed` are provided in the callback
}

Fees

Unlike other solutions, Easyntropy uses balances associated with each caller address. If your address has enough balance to pay for a request, the request will be processed.

The most common way to pay for a request is to send the required amount of ETH along with the request. If you use easyntropyRequestWithCallback() The fee will be automatically sent along with the transaction.

// The fee will be automatically sent along with the transaction.
easyntropyRequestWithCallback();

Alternatively, you can prepay your contract’s balance externally.

Prepaying

You can prepay your contract’s address balance with ETH externally. To do so, send ETH your contract's easyntropyDeposit() function. easyntropyDeposit() funciton is provided by EasyntropyConsumer contract.

easyntropyDeposit();

You can also check your balance at any time. Call the easyntropyCurrentBalance() function on your contract easyntropyCurrentBalance() funciton is provided by EasyntropyConsumer contract.

easyntropyCurrentBalance();

Widthrawing

Withdrawing funds is possible at any time. However, due to the asynchronous nature of the oracle, funds related to ongoing requests are marked as reserved and cannot be withdrawn.

Once a request is fulfilled, the reserved fee is deducted from your balance.

Unlike the easyntropyDeposit() function, the easyntropyWithdraw() function provided by EasyntropyConsumer is not publicly accessible. Due to security concerns, its scope is set to internal. To withdraw funds, you must implement your own function that wraps the internal easyntropyWithdraw(), taking into account all relevant restrictions and permissions for who can withdraw funds.

Funds will be withdrawn to the corresponding contract address, so ensure your contract can accept ETH and pass it along to the address you intend to withdraw to.

import "../Easyntropy/EasyntropyConsumer.sol";

contract DemoContract is EasyntropyConsumer {
  constructor(address _entropy) EasyntropyConsumer(_entropy) {}

  function withdrawFromEasyntropy(uint256 amount) public {
    easyntropyWithdraw(amount);
    // Funds are transferred to the contract. Make sure it can accept transfers.
  }

  receive() external payable {}
}

Oracle contract is set in a way that reserverd funds are released after about a week of inactivity of given request, allowing users to eventually widraw all the funds.

Randomness

Easyntropy is an oracle that provides random bytes32 seeds to Solidity contracts. It uses the drand.love quicknet chain as its source of randomness.

Each fulfillment emits an on-chain FulfillmentSucceeded event, which includes the drand seed and seedId. These two values ensure full transparency, verifiability, and traceability of the randomness used.

To verify a seed, you can use the following API — just replace <seedId> with the actual seedId from the event:

https://api.drand.sh/52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971/public/<seedId>

(52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971 is drand quicknet chainId)