Integration Guide

Quick Start

1. Install the SDK

npm install @diceprotocol/sdk

Published on npm.

2. Request Randomness (Solidity)

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;

import { IEntropyConsumer } from "@diceprotocol/sdk/solidity/IEntropyConsumer.sol";
import { IEntropy } from "@diceprotocol/sdk/solidity/IEntropy.sol";

contract MyGame is IEntropyConsumer {
    IEntropy public immutable dice;
    address public provider;
    
    mapping(uint64 => bytes32) public results;
    
    constructor(address _dice, address _provider) {
        dice = IEntropy(_dice);
        provider = _provider;
    }
    
    function roll() external payable {
        bytes32 userRandom = keccak256(abi.encodePacked(
            msg.sender, block.timestamp, block.prevrandao, gasleft()
        ));
        
        dice.requestV2{value: msg.value}(provider, userRandom, 200000);
    }
    
    function entropyCallback(uint64 seq, address, bytes32 random)
        internal override {
        results[seq] = random;
    }
    
    function getEntropy() internal view override returns (address) {
        return address(dice);
    }
}

3. Request Randomness (TypeScript)

import { TorinoxProtocol } from '@diceprotocol/sdk';
import { ethers, JsonRpcProvider, Wallet } from 'ethers';

const rpcUrl = 'https://rpc.mainnet.chain.robinhood.com';
const provider = '0x8741b8a825644D9Ef18Faf2DAB5e9b47B900F2b6';
const signer = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));
const dice = new TorinoxProtocol({
  rpcUrl,
  contractAddress: '0xd8a0680e7699526b57140ed4eafdcc7219dc0a0c',
});

const fee = await dice.getFee(provider, 200000); // must be exact
const userRandom = ethers.hexlify(ethers.randomBytes(32));
const seqNum = await dice.requestRandom(signer, provider, userRandom, 200000);

Contract Addresses

Network

Map to a range

Solidity (1 to 100)

function entropyCallback(
    uint64 sequenceNumber,
    address,
    bytes32 randomNumber
) internal override {
    // Inclusive range [1, 100]
    uint256 roll = (uint256(randomNumber) % 100) + 1;
    results[sequenceNumber] = randomNumber;
    // use roll ...
}

TypeScript / agent (1 to 100)

// randomNumber is 0x-prefixed hex bytes32 from reveal or x402 response
const roll = (BigInt(randomNumber) % 100n) + 1n; // 1n .. 100n

General form

// Inclusive [lo, hi], with lo >= 0 and hi >= lo
uint256 span = hi - lo + 1;
uint256 value = (uint256(randomNumber) % span) + lo;

Testnet (builders)

Agent path (x402 + USDG)

Stake subscription (Phase 1+2)

Error Reference