Building on Sui
A comprehensive developer's guide to the high-performance blockchain
Learn how to leverage Move to build scalable dApps and smart contracts on Sui's object-centric, low-latency platform.
In This Guide
What is Sui?
A high-throughput, low-latency blockchain designed for scalability and speed
Object-Centric Model
Sui's core data unit is the object, not accounts. Objects are mutable, programmable, and can be owned or shared. This enables more natural representation of digital assets and complex interactions.
Why Build on Sui?
Developers choose Sui for its horizontal scalability, low latency, high throughput, and the Move programming language designed for safe and efficient smart contracts. Sui's architecture enables parallel transaction processing and fast finality.
Architecture & Components
Sui uses a delegated Proof-of-Stake (dPoS) consensus mechanism. The core components are Validators (responsible for transaction processing and consensus), Objects (fundamental data units), and Transactions (operations that modify objects). Full nodes store the entire blockchain history.
Development Ecosystem
Sui development primarily uses the Move programming language. The Sui SDK (available in multiple languages like TypeScript, Rust, and Python) provides tools for interacting with the Sui blockchain, creating and deploying packages, and managing objects.
Understanding Sui's Architecture
The technical components that make up the Sui ecosystem
The Move Programming Language
Technical components of the safe and expressive language powering Sui
Resource Model
Move's resource model is a key feature that prevents double-spending and ensures asset safety. Resources are special types that can only be created and destroyed by the module that defines them. They cannot be copied or accidentally dropped, guaranteeing their scarcity and preventing unintended duplication or loss.
Type System
Move has a strong, static type system that helps catch errors at compile time. Types are defined within modules and can be structs, resources, or primitive types like integers and booleans. The type system enforces rules about how data can be used, preventing many common programming errors.
Modules
Move code is organized into modules. Modules define data structures (structs and resources) and procedures (functions) that operate on those structures. Modules encapsulate logic and data, promoting code reuse and modularity. Modules are analogous to smart contracts in other blockchains but with a more structured approach.
Safety & Verifiability
Move is designed for safety and verifiability. The Move Prover, a formal verification tool, can mathematically prove the correctness of Move code, ensuring that it behaves as intended and preventing vulnerabilities. This formal verification is crucial for building secure and trustworthy applications.
Generics
Move supports generics, allowing developers to write code that can work with different types. This enables code reuse and reduces duplication. Generic types are specified using type parameters, and the compiler ensures type safety at all usage sites.
Entry Functions
Entry functions are the public interface of a Move module. They are the functions that can be called from transactions. Entry functions define the valid operations that can be performed on the objects managed by the module. They act as the entry points for interacting with a Sui smart contract.
Abilities
Abilities control what operations can be performed on a type. The four abilities are `copy`, `drop`, `key`, and `store`. `copy` allows a value to be duplicated. `drop` allows a value to be discarded. `key` allows a value to be used as a global key (for objects). `store` allows a value to be stored in global storage. These abilities provide fine-grained control over how data is used and help prevent errors.
Bytecode Verification
Before Move bytecode is executed on the Sui Virtual Machine (SVM), it undergoes bytecode verification. The bytecode verifier checks the code for type safety, resource safety, and other correctness properties. This ensures that the code is well-behaved and cannot violate the rules of the Sui blockchain.
Sui Objects
Key concepts and properties of Sui's object-centric model
Object ID
Every object in Sui has a unique, globally immutable ID. This ID is used to reference the object in transactions and to retrieve its data. Object IDs are typically represented as a sequence of bytes, and they ensure that each object is distinct.
Ownership
Objects in Sui can be owned or shared. *Owned* objects have a single owner (an address) and can only be modified by transactions signed by that owner. *Shared* objects can be modified by multiple users, according to the rules defined in the object's Move module. *Immutable* objects can never be modified after creation.
Mutability
Objects can be mutable or immutable. Mutable objects can be modified by transactions, while immutable objects cannot be changed after they are created. Mutability is determined by the object's type and is enforced by the Move verifier.
Data & Bytecode
Objects store data and, optionally, Move bytecode. The data represents the object's state, and it is defined by the object's type. The bytecode defines the object's behavior and the operations that can be performed on it. Both data and bytecode are stored on-chain.
Object Versioning
Every time a mutable object is modified, its version number is incremented. This versioning is crucial for Sui's optimistic execution model. Transactions specify the expected version of the objects they modify, and if the actual version is different, the transaction is aborted. This prevents race conditions and ensures consistency.
Creating Objects
Objects are created by transactions that call Move entry functions. The Move code defines how the object is initialized and what data it contains. The transaction that creates an object typically sets the object's owner and initial state.
Transferring Objects
Owned objects can be transferred to another owner. Transferring an object changes its ownership field to the new owner's address. Object transfers are performed by transactions and require the signature of the current owner.
Deleting Objects
Objects can be deleted by transactions, which removes them from the on-chain storage. Deleting an object frees up storage space and may result in a gas rebate. Only owned objects can be deleted, and the deletion requires the signature of the owner.
Sui Transactions
Understanding transaction types, structure, and execution
Smart Contract Development
Building with Move on Sui
Development Tools
Essential tools for building on Sui
Sui CLI
The Sui Command-Line Interface is the primary tool for interacting with the Sui network. It includes commands for: building Move packages, publishing packages, calling functions, managing keys, transferring objects, and querying the blockchain state. The CLI is essential for all Sui development activities.
Sui SDKs
Sui provides SDKs in multiple programming languages, including TypeScript, Rust, Python, and Go. These SDKs provide libraries for interacting with the Sui blockchain, constructing transactions, and managing objects. The SDKs simplify the development of client applications that interact with Sui.
Move Analyzer
The Move Analyzer is a language server that provides real-time feedback and analysis for Move code. It integrates with text editors and IDEs (such as Visual Studio Code) to provide features like code completion, error highlighting, and type checking. The Move Analyzer improves developer productivity and helps catch errors early.
Sui Explorer
The Sui Explorer is a web-based tool for browsing the Sui blockchain. It allows users to view transactions, objects, and packages. The Explorer can also be used to interact with deployed smart contracts by calling entry functions. It's a valuable tool for debugging and understanding the state of the blockchain.
Local Network
The Sui CLI allows you to run a local Sui network for development and testing. This local network provides a fast and isolated environment for testing smart contracts and dApps without needing to connect to the public testnet or mainnet. The local network simulates the behavior of the Sui blockchain and allows for rapid iteration.
Move Prover
The Move Prover is a formal verification tool that can mathematically prove the correctness of Move code. It can be used to verify that smart contracts adhere to specific properties and are free from certain classes of bugs. While not required for all development, it's highly recommended for high-value contracts where security is paramount.
Faucet
The Sui Faucet provides test SUI tokens for use on the devnet and testnet. Developers can request tokens to pay for gas fees when testing their applications. The Faucet is an essential tool for development and testing on public networks.
Sui Wallet
Various wallets, including the official Sui Wallet, allow users to manage their SUI tokens, objects, and interact with dApps. Wallets provide a user-friendly interface for signing transactions and connecting to the Sui network. Developers should integrate with wallets to provide a seamless user experience.
Testing & Deployment
Best practices for validating and launching Sui applications
Gas & Economics
Understanding gas fees and economic incentives in Sui
Gas Metering
Sui uses a gas metering system to charge for transaction execution and storage. Every operation in a Move program consumes a certain amount of *computation gas*. The gas cost is calculated based on the complexity of the operation. Transactions specify a *gas budget*, and if the budget is exceeded, the transaction fails. The gas price fluctuates based on network demand.
Storage Fund
Sui employs a *storage fund* to manage the costs of storing data on-chain. When objects are created, a portion of the gas fee is deposited into the storage fund. When objects are deleted, a *storage rebate* is returned from the fund. This incentivizes efficient storage usage and helps prevent state bloat.
Gas Price Survey
The gas price in Sui is determined by a *gas price survey* conducted at the beginning of each epoch. Validators submit their bids for the minimum gas price they are willing to accept, and the reference gas price is set based on these bids. This mechanism ensures that the gas price reflects the current network conditions.
Transaction Prioritization
Transactions with higher gas prices are typically prioritized by validators. This allows users to pay more for faster transaction processing during periods of high network demand. However, Sui's parallel processing capabilities reduce the need for gas price competition for single-owner transactions.
Delegated Proof-of-Stake
Sui uses a Delegated Proof-of-Stake (dPoS) model. SUI token holders delegate their stake to validators. Validators earn rewards for processing transactions and securing the network. The rewards are distributed proportionally to the stake delegated to each validator. This incentivizes validators to act honestly and maintain the network's integrity.
Economic Modeling
Sui's economic model is designed to be sustainable and to align incentives among all participants. The combination of gas fees, storage fees, and staking rewards aims to create a balanced ecosystem where users pay for the resources they consume, and validators are rewarded for securing the network.
Security Best Practices
Protecting your applications in the Sui ecosystem
Move Language Safety
Leverage Move's built-in safety features: resource model, type system, and bytecode verification. These features help prevent common smart contract vulnerabilities like reentrancy, double-spending, and unauthorized access. Use the Move Prover for formal verification whenever possible.
Input Validation
Carefully validate all inputs to your Move entry functions. Check that object IDs are valid, that arguments have the expected types, and that values are within expected ranges. This prevents malicious users from exploiting your contracts with unexpected input.
Access Control
Implement proper access control to restrict who can modify objects and call functions. Use the `sender` address in Move to verify that the transaction sender is authorized to perform the requested operation. Use owned objects and capabilities to enforce ownership and permission rules.
Handle Errors Properly
Use Move's `abort` mechanism to handle errors and revert state changes if something goes wrong. Return informative error codes to help users understand why a transaction failed. Avoid silent failures that can lead to unexpected behavior.
Object Ownership Patterns
Carefully consider object ownership when designing your application. Decide whether objects should be owned, shared, or immutable. Use appropriate ownership patterns to enforce the desired access control and mutability rules. Understand the implications of each ownership type for transaction processing and concurrency.
Auditing and Testing
Thoroughly test your smart contracts with unit tests, integration tests, and end-to-end tests. Consider using the Move Prover for formal verification. Before deploying to mainnet, conduct security audits by independent experts to identify potential vulnerabilities.
Gas Optimization
Optimize your Move code to minimize gas consumption. Avoid unnecessary computations and storage operations. Use efficient data structures and algorithms. Gas optimization not only reduces costs but also improves performance and can prevent denial-of-service attacks.
Upgradability Considerations
Plan for upgradability. Sui supports package upgrades, but you need to design your contracts with upgradability in mind. Use appropriate patterns to ensure that upgrades do not break existing functionality or leave objects in an inconsistent state. Carefully consider the implications of upgrades for object ownership and data migration.
Real-World Examples
Success stories and use cases from the Sui ecosystem
Gaming with Dynamic NFTs
Sui's object-centric model and high throughput make it ideal for gaming applications that use dynamic NFTs (Non-Fungible Tokens). Objects can represent game assets that change over time, and Sui's fast finality ensures a smooth gaming experience. Several games are being built on Sui, leveraging its capabilities for in-game items, characters, and virtual worlds.
DeFi Applications
Sui's low latency and high throughput are also well-suited for Decentralized Finance (DeFi) applications. Decentralized exchanges (DEXs), lending platforms, and other financial protocols can benefit from Sui's performance and the safety features of the Move language. Several DeFi projects are being developed on Sui, exploring new possibilities for financial applications.
Social Media Platforms
Sui's ability to handle large numbers of transactions and its object-centric model can be used to build decentralized social media platforms. Objects can represent posts, profiles, and social connections, and Sui's scalability ensures that the platform can handle a large number of users and interactions.
Tokenized Assets
Sui's object model is well suited for representing and managing tokenized assets. Objects can be used to represent real-world assets, such as real estate or commodities, or digital assets, such as securities or collectibles. Sui's features enable efficient and secure transfer and management of these assets.
Composable Applications
Move's modularity and Sui's support for cross-contract calls enable the creation of highly composable applications. Developers can build applications that leverage the functionality of other deployed contracts, creating a rich ecosystem of interoperable services. This composability is a key driver of innovation on Sui.
Digital Identity
Sui's object capabilities can be used to implement robust digital identity solutions. Objects can represent user identities and associated data, and Sui's security features ensure that this data is managed securely and with user control.
Future of Sui
Upcoming developments and the roadmap for the ecosystem
Frequently Asked Questions
Common questions about developing on Sui
Additional Resources
Essential links and tools for Sui developers
Sui Documentation
Official documentation covering all aspects of Sui, including architecture, Move, and development.
Move Documentation
Documentation for the Move programming language.
Sui CLI
Download and installation instructions for the Sui Command-Line Interface.
Sui SDKs
Links to the various Sui SDKs (TypeScript, Rust, Python, etc.).
Sui Explorer
Web-based tool for browsing the Sui blockchain.
Sui GitHub
Sui's official GitHub repository.
Sui Developer Forum
Forum for Sui developers to ask questions and share knowledge.
Sui Discord
Sui's official Discord server for community discussion and support.
Move by Example
A collection of examples demonstrating Move language features and concepts.
Sui Wallet
Official Sui Wallet and links to other supported wallets.
Ready to Build on Sui?
Take the next steps in your Sui development journey