This repository contains two files you will use to integrate Jiritsu random numbers into your contract:

• JiriRngGatewayInterface.sol
  • used to make requests of the Jiritsu Rng Gateway
• JiriRngBaseInterface.sol
  • derive from this and implement the 3 required callbacks to receive messages from the gatway.

Your contract will send two requests to the gateway via JiriRngGatewayInterface:

• requestCommitments(subscriptionId, numCommitments, [gatewayVersion])
  • Requests commitments to random numbers that will be revealed later
• requestDecommit(subscriptionId, commitmentId, [gatewayVersion])
  • Requests the reveal (decommit) of a particular commitment id

Your contract will need to implement 3 callbacks that the Gateway will use to send you information via JiriRngBaseInterface:

• function receiveNewCommitments(bytes32[] memory commitments) external virtual;
  • Receives commitments requested via requestCommitments()
• function revealRequestedCommitment(bytes32 commitmentId, uint256 randomNumber, uint256 rangeMaxPrime) external virtual;
  • Receives revealed random numbers requested via requestDecommit()
• function receiveTimeoutNotification(bytes32 commitmentId) external virtual;
  • Receives timeout notifications when a requested decommit/reveal has not taken place within a configured number of blocks

Your contract will also need to include your subscription_id to identify it to the service, and the address of the Jiritsu rngCoordinator contract (also referred to as Gateway).

The address of the Jiritsu rngCoordinator will be published on the Jiritsu Rng site and you can copy it from there. (Link to follow).

Your subscription_id is created by your admin wallet by direct transaction, facilitated by a convenient dashboard on the jiritsu rng site (link to follow). Once your subscription_id is created, you can additionally configure operational parameters for your RNG service, like how many jiri nodes are required to report before a result will be accepted, on the same dashboard using the same admin wallet that created the subscription, or another wallet that was authorized by the original.

The public contract interfaces are limited to request functions and result callbacks. The admin functionality described above is not included in these interfaces because they are not intended to be called by your contract, rather from your admin wallet directly.

Here is a very simple example of a contract and how it would integrate with these 2 Jiritsu contracts:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import '@jiritsu/contracts/src/v0.1/interfaces/JiriRngGatewayInterface.sol';
import '@jiritsu/contracts/src/v0.1/interfaces/JiriRngBaseInterface.sol';

contract HouseGateway is JiriRngBaseInterface {
  JiriRngGatewayInterface RNGCoordinator;
  address rngCoordinator = 0xea12b35F8B0581298FEC5d78AA263038697B461A;
  uint64 subscriptionId = 49817401;

  modifier onlyAdmin() {
    true;
    _;
  }

  constructor() {
    // ...
    RNGCoordinator = JiriRngGatewayInterface(rngCoordinator);
  }

  receive() external payable {}

  function requestNewCommitments(uint16 numCommitments) external onlyAdmin {
    // send request to gateway contract for new commitments
    // RNGCoordinator.requestCommitments(subscriptionId, numCommitments, "1.1"); // uses gateway version v1.1
    RNGCoordinator.requestCommitments(subscriptionId, numCommitments); // uses gateway latest version
  }

  function commitWager(
    uint8 _gameId,
    uint _gameOptions,
    bytes32 commitmentId
  ) external payable {
    // ...

    wagerCache[commitmentId] = Wager(
      _gameId,
      _gameOptions,
      msg.sender,
      msg.value
    );

    // ...

    // RNGCoordinator.requestDecommit(subscriptionId, commitmentId, "1.1"); // uses gateway version v1.1
    RNGCoordinator.requestDecommit(subscriptionId, commitmentId); // uses gateway latest version
  }

  /**
   * @notice Callback function called by the gateway when new commiments are generated
   * @param commitments - list of new commitment IDs
   */
  function receiveNewCommitments(
    bytes32[] memory commitments
  ) external override {
    // store commitmentIds
    for (uint i = 0; i < commitments.length; i++) {
      commitmentCache.push(commitments[i]);
    }

    // ...
    emit NewCommitmentsAvailable(commitments);
  }

  function checkGameResult(bytes32 commitmentId, uint256 randomNumber) private {
    // ...

    emit GameResult();
  }

  /**
   * @notice Callback function called by the gateway when decommit request is completed
   * @param commitmentId - commitment ID
   * @param randomNumber - generated random number for the commitment
   * @param rangeMaxPrime - prime number set for the commitment
   */
  function revealRequestedCommitment(
    bytes32 commitmentId,
    uint256 randomNumber,
    uint256 rangeMaxPrime
  ) external override {
    require(wagerCache[commitmentId].exists, 'CommitmentDoesNotExist');

    // scale number to window (1 - 10)
    uint N = (10 - 1 + 1);
    uint16 scaledNumber = (randomNumber % N) + 1;

    // ...

    checkGameResult(commitmentId, scaledNumber);
  }

  /**
   * @notice Callback function called by the gateway when a decommit request is timedout
   * @param commitmentId - commitment ID of timed out decommit
   */
  function receiveTimeoutNotification(bytes32 commitmentId) external override {
    // ...
    emit TimedOut(commitmentId);
    emit GameResult();
  }
}