Deploying smart contracts on the SUI blockchain typically involves compiling Move code into bytecode and publishing it to the network. While the SUI CLI automates much of this process, developers occasionally seek guidance on manually handling raw bytecode, especially in local testing environments like Localnet. This article walks through the steps to publish raw bytecode to SUI Localnet, leveraging the SUI CLI and development tools.

---

Prerequisites on SUI Localnet

Before diving into deployment, ensure you have the following:

1. SUI CLI Installed: Follow the official installation guide to set up the sui command-line tool.
2. Localnet Running: Use the sui-test-validator binary to launch a local SUI network for testing (https://docs.sui.io/).
3. Move Package: A functional Move package with modules and dependencies configured.

---

What's SUI Localnet

SUI Localnet is a sandboxed environment for testing smart contracts without risking real assets. It allows developers to simulate interactions, debug logic, and verify deployments before moving to Devnet or Mainnet. To start Localnet, run:

sui-test-validator  

This initializes a local validator node, providing a fresh testing ground with pre-funded accounts (https://docs.sui.io/)(https://scaf.gitbook.io/scaf/).

---

How to Prepare Your Move Package?

A Move package consists of source code (sources/), dependencies (deps/), and build artifacts (build/). To compile raw bytecode, focus on the build directory, which contains .mv files—the compiled Move bytecode.

1. Build the Package:

   sui client build <package_path>  
   

   Replace <package_path> with the directory containing your Move.toml file. This generates bytecode in the build/ folder.

2. Locate Bytecode:
   Navigate to build/<package_name>/bytecode/ to find .mv files for each module. These represent the raw bytecode to be published.

---

Publishing Raw Bytecode to Localnet

While the SUI CLI abstracts bytecode management, you can manually publish raw bytecode using the sui client publish command. This command accepts pre-built bytecode instead of recompiling the package.

Step-by-Step Guide

1. Start Localnet:
   Ensure the local validator is running:

   sui-test-validator  
   

2. Publish Bytecode:
   Use the publish command with the --bytecode flag to specify the raw bytecode directory:

   sui client publish --bytecode <bytecode_path>  
   

   Replace <bytecode_path> with the path to your build/<package_name>/bytecode/ directory.

   Example:

   sui client publish --bytecode ./build/my_package/bytecode/  
   

   The CLI will submit the bytecode to the Localnet, creating a new package object on-chain (https://thelib.to/move-book)(https://sui.io/).

3. Verify Deployment:
   Check the transaction details in the CLI output. Use the SUI Explorer (if available for Localnet) or query the package via:

   sui client get-package <package_id>  
   

---

Typicall Error with Sui CLI

1. CLI Version Mismatches

If the CLI fails to recognize commands, update it using the recommended method for your OS. Avoid manual updates via cargo to prevent dependency conflicts (https://discord.gg/sui).

2. Bytecode Path Errors

Ensure the --bytecode flag points directly to the directory containing .mv files. Incorrect paths will trigger compilation errors.

3. Localnet Connection Failures

Confirm the sui-test-validator is active and that your CLI configuration points to Localnet. Use:

sui client envs  

to verify the active environment (https://docs.sui.io/).

Conclusion

Publishing raw bytecode to SUI Localnet is a basic process when using the SUI CLI’s publish command with the --bytecode flag. By leveraging Localnet’s isolated environment, developers can iteratively test contracts without incurring costs or risks. While manual bytecode manipulation is possible, the platform’s design prioritizes automation, ensuring reliability and simplicity for most use cases.