Skip to main content

Connect to a Local Network

Use a Sui local network to test your dApps against the latest changes to Sui, and to prepare for the next Sui release to the Devnet or Testnet network. Sui CLI provides the sui start command to start a local network. There are several services that can be started when using sui start, such as an indexer, a faucet, or a local instance of the GraphQL service (including the online GraphiQL IDE). You can use the included faucet to get test SUI to use on the local network.

If you haven't already, you need to install Sui CLI on your system.

Start the local network​

To start the local network, run the following command after you installed Sui CLI.

RUST_LOG="off,sui_node=info" sui start --with-faucet --random-genesis

This will:

  • call the Sui CLI binary with two flags:
  • --with-faucet to start a faucet service
  • --random-genesis to generate a new genesis and not persist the local network state
  • instruct Rust to set specific logging through the RUST_LOG=off,sui_node=info flags, which turns off logging for all components except sui-node. If you want to see more detailed logs, you can remove RUST_LOG from the command.
info

Each time you start the network by passing --random-genesis, the local network starts from a random genesis with no previous data, and the local network is not persisted. If you'd like to persist data, skip passing the --random-genesis flag. For more details, see the Persist local network state section.

To customize your local Sui network, such as starting other services or changing default ports and hosts, include additional flags or options in the sui start command:

      --random-genesis                         A new genesis is created each time this flag is set, and state is not persisted between runs
      --with-graphql                           Start a GraphQL server with default host and port: 127.0.0.1:8000. Note that GraphQL requires a running indexer
      --with-faucet                            Start a faucet with default host and port: 127.0.0.1:9123
      --with-indexer                           Start an indexer with default host and port: 0.0.0.0:9124. The indexer will be started in writer mode and reader mode
      --fullnode-rpc-port <FULLNODE_RPC_PORT>  Port to start the Fullnode RPC server on. Default port is 9000 [default: 9000]
      --faucet-port <FAUCET_PORT>              Port to start the faucet on. Default port is 9123 [default: 9123]
      --graphql-host <GRAPHQL_HOST>            Host to start the GraphQl server on. Default host is 127.0.0.1 [default: 127.0.0.1]
      --graphql-port <GRAPHQL_PORT>            Port to start the GraphQl server on. Default port is 8000 [default: 8000]
      --indexer-rpc-port <INDEXER_RPC_PORT>    Port to start the Indexer RPC server on. Default port is 9124 [default: 9124]
      --pg-port <PG_PORT>                      Port for the Indexer Postgres DB. Default port is 5432 [default: 5432]
      --pg-host <PG_HOST>                      Hostname for the Indexer Postgres DB. Default host is localhost [default: localhost]
      --pg-db-name <PG_DB_NAME>                DB name for the Indexer Postgres DB. Default DB name is sui_indexer [default: sui_indexer]
      --pg-user <PG_USER>                      DB username for the Indexer Postgres DB. Default username is postgres [default: postgres]
      --pg-password <PG_PASSWORD>              DB password for the Indexer Postgres DB. Default password is postgrespw [default: postgrespw]
      --epoch-duration-ms <EPOCH_DURATION_MS>  Set the epoch duration. Can only be used when `--random-genesis` flag is passed or if there's no genesis config and one will be auto-generated. When this flag is not set but
                                               `--random-genesis` is set, the epoch duration will be set to 60 seconds
      --no-full-node                           Start the network without a fullnode

Use sui start --help to see these options in your console.

Persist local network state​

By default, when using sui start the command will use an existing Genesis and network configuration if the ~/.sui/sui_config folder exists and if it has a genesis.blob file, or generate a new Genesis configuration if the folder does not exist. If the --config-dir is passed, it will check for the genesis.blob file and generate one if it does not exist.

Whenever you stop and start again the network without passing --random-genesis flag, all history will be preserved and will be accessible.

info

To generate a custom genesis, use the sui genesis command and pass the desired custom values. For more information about possible flags and options, run sui genesis --help.

Access your local Full node​

Use the following command to retrieve the total transaction count from your local network:

curl --location --request POST 'http://127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getTotalTransactionBlocks",
  "params": []
}'

If successful, the response resembles the following:

{
	"jsonrpc": "2.0",
	"result": 168,
	"id": 1
}

Connect the Sui CLI to your local network​

You can use the Sui CLI with any Sui network. By default it connects to Sui Devnet. To connect to your local network, create a new environment alias named local that sets the RPC URL the client uses to your local network.

sui client new-env --alias local --rpc http://127.0.0.1:9000

Next, use the following command to set the active environment to the new local environment you created.

sui client switch --env local

The command returns:

Active environment switched to [local]

You can check the current active environment with the following command:

sui client active-env

The command returns:

local

Show the current active address​

The Sui Client CLI uses the active address for command if you don't specify one. Use the following command to show the active address on your local network.

sui client active-address

The command returns an address, for example:

0xbc33e6e4818f9f2ef77d020b35c24be738213e64d9e58839ee7b4222029610de

Use the active address to get test SUI to use on your local network. Use the sui client addresses command to see all of the addresses on your local network.

info

The address returned when you run the command is unique and does not match the one used in this example.

Use the local faucet​

Transactions on your local network require SUI coins to pay for gas fees just like other networks. You can use the active address with the faucet.

Sui CLI provides the sui client faucet command to get coins from the faucet. In the most basic case, run sui client faucet and wait up to 60 seconds for the coins to reach your address. Use sui client gas to check for the new coins.

info

The faucet command uses the active address and the active network environment by default. If you need to pass in a different address or faucet server URL, check the help menu. If you're using a different network than a local network or the public ones (fullnode.network.sui.io), you will have to pass the URL to the faucet server.

Check the gas coin objects for the active address​

After you get coins from the faucet, use the following command to view the coin objects for the address:

sui client gas

The response resembles the following, but with different IDs:

╭────────────────────────────────────────────────────────────────────┬────────────╮
│ gasCoinId                                                          │ gasBalance │
├────────────────────────────────────────────────────────────────────┼────────────┤
│ 0x1d790713c1c3441a307782597c088f11230c47e609af2cec97f393123ea4de45 │ 200000000  │
│ 0x20c1d5ad2e8693953fca09fd2fec0fbc52a787e0a0f77725220d36a09a5b312d │ 200000000  │
│ 0x236714566110f5624516faa0da215ad29f8daa611e8b651d1e972168207567b2 │ 200000000  │
│ 0xc81f30256bb04ad84bc4a92017cffd7c1f98286e028fa504d8515ad72ddd1088 │ 200000000  │
│ 0xf61c8b21b305cc8e062b3a37de8c3a37583e17f437a449a2ab42321d019aeeb4 │ 200000000  │
╰────────────────────────────────────────────────────────────────────┴────────────╯

Generate example data​

Use the TypeScript SDK to add example data to your network. Run the following command from the sui root folder:

pnpm --filter @mysten/sui test:e2e

For additional information about example data for testing, see https://github.com/MystenLabs/sui/tree/main/sdk/typescript#testing.

Troubleshooting​

If you do not use Node.js 18, you might see the following message:

Retrying requesting from faucet: Retry failed: fetch is not defined

To resolve this, switch or update to Node.js 18 and then try again.

Test with the Sui TypeScript SDK​

The published version of the Sui TypeScript SDK might be an earlier version than the version of Sui you installed for your local network. To make sure you're using the latest version of the SDK, use the experimental-tagged version (for example, 0.0.0-experimental-20230317184920) in the Current Tags section of the Sui NPM registry.