Sui is an object-centric L1 with parallel transaction execution, written in Move. `@mysten/sui` is the canonical TS SDK for building Programmable Transaction Blocks (PTBs), signing, and reading on-chain objects; `@mysten/dapp-kit` provides React hooks and wallet connection for Sui Wallet, Suiet, Phantom, and others.
- 01Sui dapps and Move smart contracts
- 02object-model NFTs and dynamic fields
- 03Programmable Transaction Blocks (PTBs)
- 04sponsored transactions and zkLogin
- 05high-parallel-throughput consumer apps
- pnpm add @mysten/sui @mysten/dapp-kit @tanstack/react-query
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_SUI_NETWORK | Client | Network identifier — `mainnet`, `testnet`, `devnet`, or `localnet`. Used by `getFullnodeUrl()`. |
| NEXT_PUBLIC_SUI_RPC_URL | Client | Optional override for the Sui JSON-RPC fullnode URL (e.g. https://fullnode.mainnet.sui.io:443). |
| SUI_PACKAGE_ID | Client | Object ID (0x…) of your published Move package. |
Use `@mysten/sui` + `@mysten/dapp-kit`. Wrap the app in `<SuiClientProvider networks={{ mainnet: { url: getFullnodeUrl('mainnet') } }} defaultNetwork='mainnet'><WalletProvider>...</WalletProvider></SuiClientProvider>` and read state via `useSuiClient()`, `useCurrentAccount()`, `useSignAndExecuteTransaction()`. Build transactions as Programmable Transaction Blocks: `const tx = new Transaction(); tx.moveCall({ target: '${PKG}::module::fn', arguments: [tx.object(id), tx.pure.u64(123)] });` then `signAndExecute({ transaction: tx })`. Read objects with `client.getObject({ id, options: { showContent: true } })` and events with `client.queryEvents({ query: { MoveEventType: '...' } })`. For onboarding, use zkLogin (`@mysten/sui/zklogin`) to derive a Sui address from a Google/Apple OAuth JWT — no seed phrase required.
- ⚑Sui uses an object model (not accounts/balances) — every coin, NFT, and shared resource is its own object with a unique 0x… ID and an owner; treating it like an EVM account leads to confused state management.
- ⚑Owned objects can be mutated in parallel without consensus; shared objects (e.g. AMM pools) require Narwhal/Bullshark consensus and are slower — design data layout to keep hot paths on owned objects.
- ⚑Move arguments are BCS-serialized (Binary Canonical Serialization) — use `tx.pure.u64(...)`, `tx.pure.string(...)`, `tx.object(...)` builders; passing raw JS values silently mis-encodes and the call aborts at runtime.
- ⚑Gas is paid in SUI from a `Coin<SUI>` object passed as the gas payment; merging tiny gas coins is automatic via the SDK but custom sponsored-tx flows must build `GasData` manually with the sponsor's coins.
- ⚑Finality is via checkpoints (~250–500ms for owned, ~2–3s for shared) — `executeTransactionBlock` returns once the validator quorum signs, but client tools must `waitForTransaction` before reading derived state.
- ⚑Move package IDs change on every upgrade unless you publish with `--upgrade-policy compatible` and reuse the upgrade cap; downstream callers must reference the original package ID via `Package.upgrade()` or break.