> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellarium.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Random: two-step randomness for contracts

> Reference for sh.stellarium.random.Random: request a random value in one run and read it in a later one, so nobody can retry a run until it draws a value they like.

`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`](https://docs.stellarium.sh/builtins/account), it's built into every node, and the operator draws the values, so no peer can answer for it.

```kotlin theme={null}
const random: sh.stellarium.random.Random
```

| Function | Parameters | Returns |
| - | - | - |
| [`requestValue`](#requestvalue) | `key: string` | `void` |
| [`value`](#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:

**1. Request**

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

**2. 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.

**3. 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

```kotlin Raffle.req theme={null}
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](https://docs.stellarium.sh/concepts/payable-contracts.md#when-money-moves) 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`](https://docs.stellarium.sh/stdlib/uuid) is enough.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.