Skip to main content
skill CX Codex

onchain-randomness — Claude Code skill: what it does, how to install

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.

Apache-2.0 162 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill onchain-randomness -a claude-code
Open on GitHub

What onchain-randomness 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.

What it helps with

  • 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 for the agent

  • 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

How to install onchain-randomness

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill onchain-randomness -a claude-code

2Manually: put the files in place

~/.claude/skills/onchain-randomness/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/onchain-randomness/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about onchain-randomness

How to install onchain-randomness in Claude Code?

Run npx skills add MystenLabs/skills --skill onchain-randomness -a claude-code. The skill writes to ~/.claude/skills/onchain-randomness/SKILL.md.

What does onchain-randomness do?

It teaches coding models the patterns, syntax, and security constraints of Sui onchain randomness using Move and TypeScript.

What is required for onchain-randomness?

It requires Move toolchains for Sui and optionally connects to the Sui docs MCP server at https://sui.mcp.kapa.ai.

Source text

SKILL.md · Apache-2.0
---
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.
**Covers:** composition attacks (abort-filtering via public functions), PTB attacks (command chaining after `MoveCall` consuming `Random`), `RandomGenerator` state leakage via `bcs::to_bytes`, compiler lints on public functions accepting `Random` or `RandomGenerator`, two-step commit-reveal pattern, balanced gas usage, entry function restrictions.

---

## Routing guide

| Task | Load |
|------|------|
| Generating random values in Move | usage |
| Creating a RandomGenerator | usage |
| Calling random API functions | usage |
| Passing Random from TypeScript | usage |
| Securing a randomness-consuming function | security |
| Preventing composition or abort-filtering attacks | security |
| Mitigating PTB-based attacks | security |
| Avoiding RandomGenerator state leakage | security |
| Implementing commit-reveal for randomness | security |
| Balancing gas across execution paths | security |
| Choosing function visibility for randomness | security |
| Writing a complete randomness feature | usage + security |
| Reviewing randomness code for vulnerabilities | usage + security |

## Rules

- The `Random` object lives at reserved address `0x8` and is immutable for transactions. Any attempt to modify it causes transaction failure.
- Always create `RandomGenerator` locally within the consuming function using `r.new_generator(ctx)`. Never pass `RandomGenerator` as a `public` function parameter. Passing it to `public(package)` or private functions is acceptable for testing and in-package logic.
- Define randomness-consuming functions as private `entry` functions. The Move compiler lints against `public` functions that accept `Random` or `RandomGenerator` as parameters.
- Sui rejects PTBs containing commands other than `TransferObjects` or `MergeCoins` following a `MoveCall` that consumes `Random`. In other words, a call accepting `Random` must be the last `MoveCall` in a PTB.
- Ensure winning and losing execution paths consume approximately equal total gas (both compute and storage) to prevent attackers from inferring outcomes from gas consumption. Measure gas carefully and test in each published environment before going live.
- Use the two-step commit-reveal pattern when the outcome of randomness must not be observable before a follow-up action completes.

## Common mistakes

- **Making randomness functions `public` instead of private `entry`.** This is a fatal security flaw, not just a mistake. Public functions accepting `Random` enable abort-filtering attacks where an attacker wraps the function and reverts unfavorable outcomes. The compiler lints against this.
- **Accepting `RandomGenerator` as a `public` function parameter.** Callers can predict outputs by serializing the generator's internal state with `bcs::to_bytes(&generator)`. The compiler lints against `public` functions with `RandomGenerator` parameters. Using `RandomGenerator` as a parameter in `public(package)` or private functions is acceptable for testing and in-package logic.
- **Unbalanced gas consumption between branches.** If winning and losing paths consume significantly different total gas (compute + storage), attackers can infer outcomes from gas usage. The success path should cost equal or more gas than the failure path. To achieve this, either perform a simple standard update (e.g., set a bool flag) and claim the result in a follow-up function, or create an equally sized object (e.g., a dynamic field) in the failure path. Gas values must be measured carefully and tested in each published environment before going live.
- **Skipping commit-reveal when outcomes influence subsequent user actions.** If a user can observe and act on a random outcome in the same transaction, they can abort unfavorable results.

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

All skills for Security →

From the same set30

The whole set →
deepbook-margin The deepbook-margin Claude Code skill explains margin trading on DeepBook on Sui. It covers borrowed positions, collateral, risk ratios, and liquidation. CX Codex +1 181installs deepbook-move The deepbook-move Claude Code skill guides Move contract work with DeepBook V3. It covers pools, orders, swaps, flash loans, and BalanceManager permissions. CX Codex +1 181installs deepbook-predict This Claude Code skill covers DeepBook Predict integration for prediction markets on Sui. It explains position creation, settlement, and the liquidity pool. CX Codex +1 181installs sui-ts-sdk-backend The sui-ts-sdk-backend Claude Code skill covers backend services and agents that interact with Sui through the TypeScript SDK. It is invoked for client setup, transaction signing, package publishing, and high-throughput execution. CX Codex +1 167installs zklogin Explains zkLogin and guides its integration into Sui apps. It activates for questions about OpenID providers, address derivation, session lifetime, or security. CX Codex +1 164installs kiosk This Claude Code skill supports writing, reviewing, and debugging Move code for Sui Kiosk. It covers asset trading, NFT listings, TransferPolicy, and Kiosk extensions. CX Codex +1 162installs sui-bridge This Claude Code skill explains Sui Bridge and answers questions about transfers between Sui and Ethereum. It activates for queries about supported assets, limits, finality, or validator governance. CX Codex +1 160installs sui-for-ethereum The sui-for-ethereum Claude Code skill explains how Sui Move differs from Ethereum and Solidity. It activates for pattern comparisons, token mappings, and contract migration questions. CX Codex +1 159installs

Project sponsors

Companies that keep this analytics open