sui-deployer

name	sui-deployer
description	Use when deploying or upgrading Move packages to devnet/testnet/mainnet, managing UpgradeCaps, or planning deployment strategy. Triggers on "deploy", "publish", "upgrade package", "sui client publish", "mainnet release", "staged rollout", or any deployment/release task. Also use when the user asks about package versioning or upgrade compatibility.

SUI Deployer

Staged deployment orchestration for SUI Move packages.

Quick Start

# Build and publish to current network
sui client publish --gas-budget 100000000

# Dry-run first (recommended)
sui client publish --dry-run --gas-budget 100000000

# Publish and preserve all dependencies in bytecode dump
sui client publish --dump-bytecode-as-base64 --no-tree-shaking

SUI Protocol 127 Deployment Updates (shipped testnet v1.74.0; now v1.74.1 / P128 on both testnet and mainnet)

RPC Migration (CRITICAL):

• JSON-RPC is deprecated — permanent deactivation 2026-07-31. Quorum Driver fully disabled.
• gRPC is the primary API — transaction submission exclusively via Transaction Driver.
• sui client CLI already uses gRPC internally — no changes needed for CLI workflows.

gRPC Endpoints:

Network	Endpoint
Mainnet	grpc.mainnet.sui.io:443
Testnet	grpc.testnet.sui.io:443
Devnet	grpc.devnet.sui.io:443

Protocol 127 Notes (shipped testnet v1.74.0):

• Timestamp-based epoch close (P127 mainnet behavior): Mainnet switches to timestamp-based epoch close at P127 — no operator action required. (Live on both networks; mainnet now v1.74.1 / P128. First shipped testnet v1.74.0.)
• New Move VM (Testnet): Active on testnet. Account for gas metering differences in cross-network testing.
• Offline Bytecode Dump: sui move build --dump --no-tree-shaking works offline — enables air-gapped deployment pipelines.
• Compatibility verification enabled by default (was opt-in).

Deployment Stages

Stage 1: Devnet

sui client switch --env devnet
sui client publish --gas-budget 100000000

Quick iteration, no verification needed.

Stage 2: Testnet

sui client switch --env testnet
sui move test              # run all tests first
sui client publish --gas-budget 200000000

Public testing, 48+ hours soak time before mainnet.

Stage 3: Mainnet

sui client switch --env mainnet
sui client publish --gas-budget 500000000

Requires: security audit, multisig UpgradeCap transfer, rollback plan.

Upgrade Management

# Step 1: Build upgrade bytecode
sui move build --dump-bytecode-as-base64

# Step 2: Execute upgrade with existing UpgradeCap
sui client upgrade --gas-budget 200000000 --upgrade-capability <UPGRADE_CAP_ID>

UpgradeCap best practices:

• Transfer to multisig address immediately after first publish
• Store the cap object ID in your deployment records
• Use sui client object <CAP_ID> to verify cap ownership

Post-Deployment Checklist

1. Save published package ID and UpgradeCap ID
2. Transfer UpgradeCap to multisig/admin address
3. Update frontend .env with new package ID
4. Run smoke tests against deployed package
5. Verify on-chain bytecode via explorer (Suivision / Suiscan)

Common Mistakes

❌ Forgetting to transfer UpgradeCap — stuck in deployer address, cannot upgrade with multisig later. Transfer immediately after publish.

❌ Not saving deployment artifacts — lost package IDs mean you can't verify on-chain code or reference it. Save package ID + upgrade cap ID + tx digest.

❌ Not updating frontend package IDs — frontend calls old package, all transactions fail. Automate package ID updates in .env post-deployment.

See reference.md for upgrade compatibility rules and examples.md for deployment scripts. If the CLI is missing or you hit client/server api version mismatch, see the sui-install skill.