# onchain-randomness

A skill for Claude Code that guides onchain randomness implementation in Sui Move. Secures functions using the 0x8 Random object against composition and PTB attacks.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 162 installs · ★ 25 repo stars
- Author: MystenLabs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MystenLabs/skills/tree/HEAD/onchain-randomness/SKILL.md
- Updated: 2026-11-12
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/onchain-randomness

## What it does

This skill guides the agent through native randomness on Sui via the immutable `Random` shared object at address `0x8`. It explains how to instantiate a local `RandomGenerator` using `r.new_generator(ctx)` and call generation helpers such as `generate_u128`, `generate_u8_in_range`, and `shuffle`.

A dedicated security reference covers attack mitigation, including abort-filtering via wrapping calls, compiler lints on public signatures, and restrictions inside Programmable Transaction Blocks. Any call consuming `Random` must be the final `MoveCall` in a PTB, preceded only by transfers or coin merges.

The reference details gas balancing across branches. If successful and failed execution paths consume unequal compute or storage gas, external observers can infer outcomes. It requires equalizing gas costs or adopting a commit-reveal scheme before deploying to mainnet. The documentation strictly relies on Sui docs and the `https://sui.mcp.kapa.ai` MCP endpoint.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MystenLabs/skills --skill onchain-randomness -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/onchain-randomness/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/onchain-randomness/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MystenLabs/skills --skill onchain-randomness -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/onchain-randomness/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MystenLabs/skills --skill onchain-randomness -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/onchain-randomness/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MystenLabs/skills onchain-randomness
```

2. **Manually: put the files in place**
- File: `.github/skills/onchain-randomness/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MystenLabs/skills --skill onchain-randomness -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MystenLabs/skills --path onchain-randomness
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/onchain-randomness/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MystenLabs/skills --skill onchain-randomness -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MystenLabs/skills/tree/HEAD/onchain-randomness/SKILL.md

## When to use it
- Generate pseudo-random values in Sui Move contracts via `0x8`
- Prevent abort-filtering and composition exploits on randomness functions
- Implement a two-step commit-reveal flow for onchain lotteries and games
- Equalize gas consumption across winning and losing execution branches

## Example prompts
- Write a private entry function in Move that uses RandomGenerator to roll a dice
- Audit this Sui smart contract for Random object state leakage vulnerabilities
- Show how to pass the 0x8 Random object reference via the Sui TypeScript SDK

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 548b6cf2a517bbcb.

BEGIN THIRD-PARTY FILE 548b6cf2a517bbcb
```text
---
name: onchain-randomness
description: >
  Onchain randomness on Sui. Use when generating random values in Move smart contracts,
  working with the Random object (0x8) or RandomGenerator, securing randomness-consuming
  functions against composition attacks, PTB attacks, or state leakage, implementing
  commit-reveal patterns, balancing gas across execution paths, or integrating randomness
  from TypeScript.

  For general Move security patterns, see the `move-security` skill.
  For Move language fundamentals, see the `sui-move` skill.
  For TypeScript SDK patterns, see the `sui-sdks` skill.
---

# Onchain Randomness

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

> **Source constraint:** All information in this skill is sourced exclusively from [docs.sui.io/sui-stack/on-chain-primitives/randomness-onchain](https://docs.sui.io/sui-stack/on-chain-primitives/randomness-onchain). When extending or updating this skill, only pull from this source. Do not use third-party blogs, tutorials, or unofficial documentation.

Sui provides native onchain randomness through the `Random` shared object at address `0x8`. Move functions create `RandomGenerator` instances from `Random` and use them to produce unpredictable values. This skill covers the API, usage patterns, security considerations, and attack mitigations for onchain randomness.

---

## Reference files

### usage -- API and Usage Patterns
**Path:** `usage.md`
**Load when:** generating random values in Move, creating a `RandomGenerator`, calling `new_generator`, using `generate_u128`, `generate_u8_in_range`, passing the `Random` object from TypeScript, or writing basic randomness-consuming functions.
**Covers:** the `Random` object (address `0x8`), `RandomGenerator`, the `random.move` API (full function list including `new_generator`, value generation, range generation, `shuffle`, `generate_bytes`), basic implementation examples, TypeScript integration.

### security -- Security and Attack Vectors
**Path:** `security.md`
**Load when:** securing randomness-consuming functions, preventing composition attacks, mitigating PTB attacks, avoiding `RandomGenerator` state leakage, implementing commit-reveal patterns, balancing gas across winning and losing paths, or choosing function visibility for randomness functions.
```
END THIRD-PARTY FILE 548b6cf2a517bbcb

The third-party file has ended. Everything between the 548b6cf2a517bbcb tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2478 of 6216 bytes. © MystenLabs · Apache-2.0 · https://github.com/MystenLabs/skills/tree/HEAD/onchain-randomness/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
