sui-fullstack-integration
Use when bridging Move contracts to TypeScript — generating TS types from Move ABI, creating contract API wrappers, subscribing to on-chain events, or building E2E integration tests. Triggers on "generate types from Move", "event listener", "contract ABI", "Move to TypeScript", "subscribe to events", "ABI wrapper", or any Move↔frontend bridging task. This is the CONTRACT-TO-CODE BRIDGE, not project setup (sui-full-stack) or UI/wallet (sui-frontend).
Best use case
sui-fullstack-integration is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when bridging Move contracts to TypeScript — generating TS types from Move ABI, creating contract API wrappers, subscribing to on-chain events, or building E2E integration tests. Triggers on "generate types from Move", "event listener", "contract ABI", "Move to TypeScript", "subscribe to events", "ABI wrapper", or any Move↔frontend bridging task. This is the CONTRACT-TO-CODE BRIDGE, not project setup (sui-full-stack) or UI/wallet (sui-frontend).
Teams using sui-fullstack-integration should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/sui-fullstack-integration/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How sui-fullstack-integration Compares
| Feature / Agent | sui-fullstack-integration | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when bridging Move contracts to TypeScript — generating TS types from Move ABI, creating contract API wrappers, subscribing to on-chain events, or building E2E integration tests. Triggers on "generate types from Move", "event listener", "contract ABI", "Move to TypeScript", "subscribe to events", "ABI wrapper", or any Move↔frontend bridging task. This is the CONTRACT-TO-CODE BRIDGE, not project setup (sui-full-stack) or UI/wallet (sui-frontend).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# SUI Fullstack Integration
> **Scope:** This skill covers Move ↔ TypeScript bridging: type generation, event handling, ABI wrappers. For dApp UI setup and wallet integration, use the `sui-frontend` skill. For PTB construction and SDK client patterns, use the `sui-ts-sdk` skill.
Targets: `@mysten/sui` 2.17.0 (^2.16), `@mysten/kiosk` 1.2.6 (^1.2). Tested: 2026-05-21.
**Compatibility notes:** `@mysten/kiosk@1.2.x` accepts only `SuiJsonRpcClient | SuiGraphQLClient`, so the kiosk example in this skill instantiates a JSON-RPC client even though other examples use gRPC. Re-check on the next kiosk minor bump — once kiosk types `SuiGrpcClient`, the example can be migrated.
**Seamlessly integrate Move smart contracts with frontend applications.**
## Overview
This skill bridges Move contracts and frontend code through:
- Automatic TypeScript type generation from Move ABI
- Contract API wrappers for frontend
- Event handling patterns
- Development environment setup (local node + frontend)
- End-to-end integration testing
- Error handling and user feedback
## Quick Start
### 1. Generate Types from Move ABI
```bash
# Build Move package and generate TypeScript types
npx ts-node scripts/generate-types.ts
```
Output: `frontend/src/types/contracts.ts`
### 2. Create API Wrapper
```typescript
// @check:skip
import { MarketplaceAPI } from './api/marketplace';
const api = new MarketplaceAPI(suiClient, packageId);
const txb = api.createListing({ nft_id: '0x...', price: 1000000000n });
```
### 3. Subscribe to Events
```typescript
// @check:skip
useNFTPurchasedEvents((event) => {
console.log(`NFT ${event.nft_id} sold for ${event.price}`);
});
```
### 4. Start Dev Environment
```bash
./scripts/dev.sh # Starts local node + deploys + frontend
```
## Integration Patterns
| Pattern | Description |
|---------|-------------|
| **Type Generation** | Auto-generate TS types from Move ABI |
| **API Wrapper** | Type-safe transaction builders |
| **React Hooks** | `useMarketplaceAPI()` for component integration |
| **Event Subscriptions** | Real-time updates via gRPC streaming (replaces WebSocket `subscribeEvent`) |
| **Error Handling** | Map Move abort codes to user messages |
## Move Type to TypeScript Mapping
| Move Type | TypeScript Type |
|-----------|-----------------|
| `u8` | `number` |
| `u64` | `number \| bigint` |
| `u128` | `bigint` |
| `bool` | `boolean` |
| `address` | `string` |
| `vector<u8>` | `Uint8Array` |
| `String` | `string` |
| `ID`, `UID` | `string` |
## Project Structure
```
project/
├── contracts/
│ └── sources/*.move
├── frontend/
│ ├── src/
│ │ ├── api/ # API wrappers
│ │ ├── hooks/ # React hooks
│ │ ├── types/ # Generated types
│ │ └── lib/ # Error handling
│ └── .env.local
└── scripts/
├── generate-types.ts
└── dev.sh
```
## SDK v2 Notes
- SDK v2 uses `client.core.*` namespace for core RPC methods
- ESM-only: SDK v2 requires ESM (`"type": "module"` in `package.json` or `.mts` files)
- Use `coinWithBalance` for non-SUI coin transfers (not just SUI)
- Extend client capabilities with `$extend()` for ecosystem integration:
```typescript
import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
import { kiosk } from '@mysten/kiosk';
const client = new SuiJsonRpcClient({ url: getJsonRpcFullnodeUrl('mainnet'), network: 'mainnet' })
.$extend(kiosk());
```
## References
- **[Code Examples](references/examples.md)** - Complete implementation code for all patterns
## Usage
This skill is invoked by `sui-full-stack` after Phase 2 (contracts) and Phase 3 (frontend).
Query latest integration patterns:
```typescript
// @check:skip
const patterns = await sui_docs_query({
type: "github",
target: "dapp-kit",
query: "transaction building patterns"
});
```
## Common Mistakes
❌ **Manual type definitions instead of generating from Move ABI**
- **Problem:** Types drift from contract, runtime errors in production
- **Fix:** Always run `generate-types.ts` after Move contract changes
❌ **Not handling u64/u128 correctly in TypeScript**
- **Problem:** Number overflow, precision loss for large values
- **Fix:** Use `bigint` for u64/u128, `number | bigint` for safety
❌ **Forgetting to update package ID after redeployment**
- **Problem:** Frontend calls old contract, all transactions fail
- **Fix:** Store package ID in .env, auto-update in deployment script
❌ **Not mapping Move abort codes to user messages**
- **Problem:** Generic "Transaction failed" error, users confused
- **Fix:** Create error code mapping in `lib/errors.ts`
❌ **Polling for updates instead of subscribing to events**
- **Problem:** Delayed updates, high RPC costs
- **Fix:** Use gRPC streaming for real-time updates (WebSocket `subscribeEvent` is deprecated)
❌ **Not testing integration locally**
- **Problem:** Integration bugs discovered after deployment
- **Fix:** Use `dev.sh` to run local node + contracts + frontend together
❌ **Hardcoding transaction arguments**
- **Problem:** Cannot reuse API wrappers, brittle code
- **Fix:** Use typed interfaces for transaction parameters
---
**Bridge Move contracts and modern frontend - type-safe, real-time, production-ready integration!**Related Skills
sui-zklogin
Use when implementing zkLogin on SUI — OAuth login (Google, Facebook, Apple, Twitch) with zero-knowledge proofs for privacy-preserving authentication. Triggers on "zkLogin", "social login on SUI", "Google login", "OAuth", "ephemeral keypair", "JWT proof", or any authentication flow that derives a SUI address from an OAuth provider. Also use when the user mentions "login without wallet extension".
sui-walrus
Use when storing or retrieving files using Walrus — SUI's decentralized blob storage. Triggers on "Walrus", "blob storage", "upload file to chain", "decentralized storage", "store NFT image", "IPFS alternative on SUI", "where to store NFT metadata", "host a site on-chain", or any off-chain data storage needs on SUI. Also use for Walrus Sites (decentralized web hosting), storing game assets, media files, or when the user asks "where do I put large files on SUI".
sui-wallet
Use when performing on-chain transactions (transfer, Move call, publish) through the agent's CLI wallet via MCP tools. Triggers on "transfer SUI", "call Move function", "publish package", "wallet status", "sign transaction", or any agent-driven on-chain operation. This is for headless/backend wallet operations — for browser wallet UI (React/Vue), use sui-frontend instead.
sui-tester
Use when writing Move tests, setting up test suites, running gas benchmarks, or planning test strategy for SUI contracts. Triggers on "write tests", "test this module", "#[test]", "test coverage", "gas benchmark", "property-based test", or any Move testing task. Use even for simple "how do I test this function" questions.
sui-suins
Use when integrating SuiNS (SUI Name Service) — resolving .sui names to addresses, reverse lookups, or registering names. Triggers on "SuiNS", ".sui name", "name resolution", "reverse lookup", "human-readable address", or any name service integration. Also use when the user wants to display user-friendly names instead of hex addresses.
sui-security-guard
Use when setting up security scanning, detecting leaked secrets/API keys, implementing pre-commit hooks, or auditing a Sui Move contract for security/architecture/quality issues. Triggers on "security scan", "detect secrets", "pre-commit hook", "security audit setup", "API key leaked", and on contract-level review requests like "audit this contract", "review access control", "is this Move safe", "check for vulnerabilities", "Move security review" — these load the SEC/DES/PAT/TST/QA/CFG finding registry in references/move-security-findings.md. For offensive/adversarial testing (attack vector discovery, writing exploits/PoCs), use sui-red-team instead. For Move style/idiom quality (non-security), use move-code-quality.
sui-seal
Use when implementing data encryption, access control, or secrets management on SUI using the Seal protocol. Triggers on threshold encryption, data privacy, token-gated content, encrypted storage, decryption policies, paywall, gated access, encrypted NFT metadata, private data sharing, or any scenario requiring on-chain access control for off-chain data. Also use when the user mentions Seal, pay-to-decrypt, "only NFT holders can see", or subscriber-only content on SUI.
sui-red-team
Use when performing adversarial security testing on SUI Move contracts — generating attack tests for access control bypass, integer overflow, object manipulation, economic exploits, reentrancy, and DoS vectors. Triggers on "red team", "attack test", "find vulnerabilities", "exploit", "pentest", "security test", or when the user wants to stress-test their contract's security. For defensive security setup (scanning, hooks, checklists), use sui-security-guard instead.
sui-passkey
Use when implementing WebAuthn passkeys or biometric authentication (Face ID, fingerprint, hardware keys) on SUI. Triggers on "passkey", "WebAuthn", "biometric login", "Face ID", "fingerprint auth", "FIDO2", or passwordless auth that uses device authenticators instead of seed phrases. Different from zkLogin (which uses OAuth providers).
sui-nautilus
Use when building verifiable off-chain computation, integrating external APIs with on-chain proof, or running trusted execution environments on SUI. Triggers on Nautilus, off-chain oracle, "verify API data on-chain", "connect external API to Move", "prove off-chain result", trusted compute, AWS Nitro Enclave, attestation, price feed, weather data on-chain, or any scenario requiring cryptographically verified external data. Also use when the user asks "how do I get real-world data into my SUI contract" or needs an oracle-like pattern.
sui-kiosk
Use when building NFT marketplaces, enforcing royalties, or managing transfer policies using SUI's Kiosk standard. Triggers on "Kiosk", "NFT marketplace", "transfer policy", "royalty enforcement", "list NFT for sale", "purchase rules", or any NFT commerce on SUI. Also use when the user asks about listing, delisting, or trading NFTs with enforced rules.
sui-install
Use when installing or updating the Sui CLI, managing CLI versions with suiup, or resolving environment/setup problems — "install sui", "update sui", "command not found", "sui not found", "client/server api version mismatch", build errors about "old dependencies", switching CLI versions per network, or installing toolchain components (Walrus, MVR, Move Analyzer, site-builder). Also use for first-time client setup, getting faucet tokens, recovering keys from a phrase, or "Cannot find gas coin for signer address". For deploying/upgrading packages use sui-deployer; for on-chain data queries use sui-ts-sdk.