/setup-sui-contracts

name: setup-sui-contracts
description: "Set up a Sui Move smart contract project with OpenZeppelin Contracts for Sui. Use when users need to: (1) install the Sui CLI and Move toolchain, (2) create a new Sui Move package, (3) discover and add OpenZeppelin Sui dependencies to Move.toml via the Move Registry (MVR), (4) learn the integration pattern from the library's examples and API docs before implementing, or (5) understand Sui Move import conventions and build/test commands for OpenZeppelin."
license: AGPL-3.0-only
metadata:
  author: OpenZeppelin

Sui Setup

Prerequisites

Install the Sui CLI by following the [Sui installation guide](https://docs.sui.io/getting-started/onboarding/sui-install). The CLI bundles the Move toolchain and the Move Registry (MVR) resolver, so no separate Move install is needed.

Any time you need to investigate the library, start from its AI discovery entry point, [`llms.txt`](https://raw.githubusercontent.com/OpenZeppelin/contracts-sui/main/llms.txt) — it maps the library's content (the architecture doc, the `contracts/` and `math/` package catalogs, each package's README/examples/API reference, and audits). Follow its links rather than guessing paths.

OpenZeppelin Contracts for Sui pins a specific Sui CLI version in its top-level [README](https://raw.githubusercontent.com/OpenZeppelin/contracts-sui/main/README.md) (this is repo metadata, not linked from `llms.txt`) — read the required version there and check your local install against it. The pinned version is the tested one and safest to match; a newer patch/minor generally works too, so treat a small drift as a warning, not a blocker:

sui --version

Create a Project

Initialize a new Move package (only if starting a new project):

sui move new my_project
cd my_project

This creates `Move.toml`, a `.gitignore`, and commented-out stub modules `sources/my_project.move` and `tests/my_project_tests.move`, using Move `edition = "2024"`. The stubs are inert placeholders (fully wrapped in `/* … */`); replace or delete them when you add your own modules.

OpenZeppelin Dependencies

OpenZeppelin packages are published to the **Move Registry (MVR)** and added to `Move.toml` under `[dependencies]` with the `r.mvr` format, mapping the Move package name to its MVR slug:

[dependencies]
<move_package_name> = { r.mvr = "@openzeppelin-move/<slug>" }

Do **not** rely on a memorized package list — it drifts as the library evolves. Discover what is available from the library's own metadata, which is the single source of truth:

1. Start — as always — at the AI discovery entry point, [`llms.txt`](https://raw.githubusercontent.com/OpenZeppelin/contracts-sui/main/llms.txt). 2. Follow its links to **every package catalog it lists** — `llms.txt` is the authority on which catalogs exist, so read the set from there rather than assuming a fixed one (new top-level catalogs get added over time). Each catalog table lists the MVR slug, the Move package name, docs, and highlights. 3. Read the individual package's `README.md` for the exact `r.mvr` install snippet and its module list. Confirm the slug resolves — either by looking it up on [moveregistry.com](https://www.moveregistry.com) or, definitively, by running the build (below), which resolves every slug against the MVR.

> **Catalog paths are relative to the catalog file's own directory.** A catalog at `<catalog-dir>/README.md` lists each package by a `Path` relative to `<catalog-dir>/`, so the package's raw README is `.../main/<catalog-dir>/<path>/README.md` — resolve `<path>` against the directory of the catalog that links it, not the repo root (the bare `.../main/<path>/README.md` 404s). When in doubt, list the tree: `gh api 'repos/OpenZeppelin/contracts-sui/git/trees/main?recursive=1'` (quote the endpoint — an unquoted `?` is a glob in some shells).

> The Move package name (used in `use` statements) differs from the MVR slug — slug `@openzeppelin-move/integer-math` is Move package `openzeppelin_math`. Only add the packages the project actually uses.

> **A package usually contains several modules.** The catalog lists *packages*; the building block you want is often one module among several inside a package. Read the package README's module list and its `examples/` to see what a package actually exposes — don't assume one package equals one component, and don't rely on a fixed mental catalog: the set of packages and modules grows over time.

> The OpenZeppelin **Sui MCP** exposes this same metadata as deterministic tool calls — `sui-list-recipes` (discover recipes), `sui-get-recipe` (a recipe's source plus the packages it uses, each with its install line), and `sui-get-package` (a package's install line + docs). When the MCP is available, query it instead of crawling the files by hand, then wire the returned install lines into `Move.toml` and re-home the recipe source into your package. The MCP returns data, not a buildable package — that wiring and re-homing are what turn it into one.

Packages not on the Move Registry

Not every package is on the Move Registry — some are not published there at all. When a package's `README.md` has no `r.mvr` install snippet, depend on it from a **GitHub release** instead — a git dependency pinned to a release tag, never a moving branch:

[dependencies]
<move_package_name> = { git = "https://github.com/OpenZeppelin/contracts-sui.git", subdir = "<catalog-dir>/<path>", rev = "<release-tag>" }

`<catalog-dir>/<path>` is the package's directory in the repo (the same `Path` its catalog row lists); pin `rev` to a published GitHub **release** tag, not a branch. Keep every OpenZeppelin dependency on one consistent revision to avoid the diamond conflict below.

Resolving version conflicts (diamond dependencies)

Two OZ packages can pull *different revisions* of a shared transitive dependency — for example, if one package embeds its own revision of a math package that you also dep