Random: two-step randomness for contracts

sh.stellarium.random.Random gives contracts random values that nobody can choose. Use it for anything a random value decides money with, such as a draw, a raffle winner or a tiebreak. Like Account, it’s built into every node, and the operator draws the values, so no peer can answer for it.

const random: sh.stellarium.random.Random

Function	Parameters	Returns
`requestValue`	`key: string`	`void`
`value`	`key: string`	`string`

Why two steps

A value a run could see as soon as it starts could be tried again: whoever runs the contract could start runs until one draws a value they like, then let only that one succeed. So randomness takes two runs:

Request

A run calls requestValue(key). The request is staged with the run’s money changes, so it stands or falls with the run.

Draw

Once the run’s changes apply, the operator draws the value, signed and bound to the contract’s node, name, version and key. Until then, nobody knows it.

Use

A later run reads the value with value(key).

By the time anyone knows the value, the request can’t be taken back.

requestValue

Asks the operator for a random value under key, a string of 1 to 255 characters. Each contract version can request each key once: requesting it again fails the run. If the requesting run fails or its changes are dropped, the request is dropped too, and the key can be requested again. The function is named requestValue because request is a RequestScript keyword.

value

Returns the value drawn for key: 32 random bytes as a base64url string. It fails until the value has been drawn, so call it from a later run than the one that requested it.

Example: a raffle

Raffle.req

payable contract com.example.Raffle(action: string, round: string): string {
    const random: sh.stellarium.random.Random
    if (action == "draw") {
        // The value is drawn only after this run's changes apply.
        random.requestValue(key: round)
        return "requested"
    }
    // Fails until the value exists.
    return random.value(key: round).value
}

Call it once with action: "draw", and again with any other action once the first run has settled.

Rules

Only a running contract can call it. A call from a request script fails.
Values belong to the contract version that requested them. Another version, or another contract, can’t read them.
Checked on replay. When the operator replays a run, it checks each request against the change the run staged, and each value the run read against the one it drew.
For ids, use Uuid instead. A value that decides nothing, such as a job id, gains nothing from being drawn again, so sh.stellarium.stdlib.Uuid is enough.

Getting Started

Concepts

Running a node

Built-in resources

Standard Library

Inference

Community