WAX RNG Basics
How it Works
- WAX RNG Smart Contract. The WAX RNG smart contract runs on the WAX mainnet, owned by the orng.wax account.
- WAX RNG Oracle Service. Secured by the oracle.wax account, this service monitors the WAX Blockchain externally, listening for new calls to the WAX RNG smart contract. When you request a new random number, the RNG oracle creates RSA signatures that generate provably fair random numbers.
Here’s the typical WAX RNG flow:
- Your user or your client-side app supplies a 64-bit random number (signing_value). For example, you could display a button that calls a javascript function that generates a pseudo-random number. When the user is satisfied with their seed value, they can click another button (e.g., Start Playing).
- You also need to supply a unique tracking number (assoc_id). This can be an internal job id or database id.
- Your smart contract calls the WAX RNG service to request a random number, sending your assoc_id and the user’s signing_value.
- The WAX RNG oracle accepts your request, then uses an internal public and private key pair to create an RSA signature based on the number supplied by your customer (signing_value). This signature is hashed and becomes your random number.
- The WAX RNG service verifies the RSA signature returned from the WAX RNG oracle, then sends the random number to a call-back action in your smart contract, along with your tracking number (assoc_id).
- You display the random number to the client or implement some sort of randomization logic, animation, or in-game function.
To provide fairness, provability, and user confidence, it’s recommended that you allow the customer to view or even edit the client-side signing_value. If you prefer to generate the signing_value on the back-end or your app doesn’t require a front-end signing_value, you could use the user’s transaction hash sent from their wallet. This value is a sha256 hash signed by the client, making it a unique, collision-resistant choice. For example:
ACTION getrand(const name& caller) {
require_auth(caller);
auto size = transaction_size();
char buf[size];
auto read = read_transaction(buf, size);
check(size == read, "read_transaction() has failed.");
auto tx_signing_value = sha256(buf, size);
//now that you've generated a unique signing_value, call the WAX RNG action.
action({ get_self(), "active"_n }, "orng.wax"_n, "requestrand"_n, std::tuple{ order_id, tx_signing_value, get_self() }).send();
}
Parameters
The WAX RNG requestrand action accepts the following parameters:
Parameter | Example | Description |
---|---|---|
assoc_id | 1405 | Required uint64_t. A unique value assigned by you (e.g., job id, database id). |
signing_value | 84569725 | Required uint64_t. A pseudo-random number generated client-side or on the back-end. Must be unique and never used before, even by other users. |
caller | get_self() | Required name. The smart contract account calling the orng.wax action. |
Example
ACTION requestrand(uint64_t assoc_id, uint64_t signing_value, const name& caller)
Callback Function
To receive your random number from the WAX RNG service, your smart contract must include the receiverand callback function with the following parameters:
Parameter | Example | Description |
---|---|---|
assoc_id | 1405 | Required uint64_t. A unique value assigned by you (e.g., job id, database id). |
random_value | Refer to Description. | Required checksum256. The RSA signed random value returned from the WAX RNG service. Example: 0979df3b6cb654bfe059481b586c2277697e7f0bfcef3e0dd198e19b54bce278 |
Example
ACTION waxrng::receiverand(uint64_t assoc_id, const eosio::checksum256& random_value)
Action Constructor
To call the WAX RNG requestrand external action, you’ll need to use the action constructor. Action constructors accept the following parameters (customized below for the requestrand action):
Parameter | Example | Description |
---|---|---|
permission | { get_self(), "active"_n } | Required structure. This is your WAX Blockchain Account and permission type. For example, if you're smart contract's blockchain account is named waxsc1, { get_self(), "active"_n } returns [email protected] permissions. |
code | "orng.wax"_n | Required name. The WAX RNG smart contract account. |
action | "requestrand"_n | Required string. The action name in the WAX RNG smart contract. |
data | std::tuple{ your_id, signing_value, get_self() }) | Required fixed-size collection. The parameters required for the requestrand action. |