Skip to main content

Connecting to a Local Network

The Sui CLI provides the sui start command to create and start a local instance of the Sui network. You can start services such as an indexer, a faucet, or a local instance of the GraphQL service (including the web-based GraphiQL IDE). sui start also includes a local faucet to get test SUI to use in the local network you create.

Starting the local network​

To start the local network, run the following command:

$ RUST_LOG="off,sui_node=info" sui start --with-faucet --force-regenesis

This command:

  • Calls the Sui CLI binary with 2 flags:

    • --with-faucet to start a faucet service.

    • --force-regenesis to generate a new genesis and not persist the local network state.

  • Instructs 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.

caution

Each time you start the network by passing --force-regenesis, the local network starts from a random genesis with no previous data and the local network is not persisted. If you want to persist data, do not pass the --force-regenesis flag.

A temporary directory is created in /tmp, which might not work if the /tmp folder is mounted to /tmpfs. If this is the case, set TMPDIR=./some_folder.

Customization​

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.

Options and flags like with-indexer and with-graphql require you to have PostgreSQL/libpq installed. Check out the list of possible options below to find which is the default database or how to pass a different database.

The following is a list of possible options and flags to pass to sui start. Use sui start --help to see these options in your console.

--network.config <CONFIG_DIR>
          Config directory that will be used to store network config, node db,
          keystore. sui genesis -f --with-faucet generates a genesis config that
          can be used to start this process. Use with caution as the `-f` flag
          will overwrite the existing config directory. We can use any config
          dir that is generated by the `sui genesis`

      --force-regenesis
          A new genesis is created each time this flag is set, and state is not
          persisted between runs. Only use this flag when you want to start the
          network from scratch every time you run this command.
          
          To run with persisted state, do not pass this flag and use the `sui
          genesis` command to generate a genesis that can be used to start the
          network with.

      --with-faucet[=<FAUCET_HOST_PORT>]
          Start a faucet with default host and port: 0.0.0.0:9123. This flag
          accepts also a port, a host, or both (e.g., 0.0.0.0:9123). When
          providing a specific value, please use the = sign between the flag and
          value: `--with-faucet=6124` or `--with-faucet=0.0.0.0`, or
          `--with-faucet=0.0.0.0:9123`

      --with-indexer[=<DATABASE_URL>]
          Start an indexer with a PostgreSQL database.
          
          Three modes of operation: - Not specified: No indexer is started
          (unless --with-graphql is set) - `--with-indexer`: Create/use a
          temporary database in the network's configuration directory -
          `--with-indexer=<URL>`: Use the provided PostgreSQL database URL
          
          When providing a database URL, use the = sign:
          `--with-indexer=postgres://user:pass@host:5432/db`

      --with-consistent-store[=<CONSISTENT_STORE_HOST_PORT>]
          Start a Consistent Store with default host and port: 0.0.0.0:9124.
          This flag accepts also a port, a host, or both (e.g., 0.0.0.0:9124).
          
          When providing a specific value, please use the = sign between the
          flag and value: `--with-consistent-store=9124` or
          `--with-consistent-store=0.0.0.0`, or
          `--with-consistent-store=0.0.0.0:9124` The Consistent Store will be
          automatically enabled when `--with-graphql` is set.

      --with-graphql[=<GRAPHQL_HOST_PORT>]
          Start a GraphQL server with default host and port: 0.0.0.0:9125. This
          flag accepts also a port, a host, or both (e.g., 0.0.0.0:9125).
          
          When providing a specific value, please use the = sign between the
          flag and value: `--with-graphql=9125` or `--with-graphql=0.0.0.0`, or
          `--with-graphql=0.0.0.0:9125`
          
          Note that GraphQL requires a running indexer and consistent store,
          which will be enabled by default even if those flags are not set.

      --fullnode-rpc-port <FULLNODE_RPC_PORT>
          Port to start the Fullnode RPC server on. Default port is 9000
          
          [default: 9000]

      --epoch-duration-ms <EPOCH_DURATION_MS>
          Set the epoch duration. Can only be used when `--force-regenesis` flag
          is passed or if there's no genesis config and one will be
          auto-generated. When this flag is not set but `--force-regenesis` is
          set, the epoch duration will be set to 60 seconds

      --data-ingestion-dir <DATA_INGESTION_DIR>
          Make the fullnode dump executed checkpoints as files to this
          directory. This is incompatible with --no-full-node.
          
          If --with-indexer is set, this defaults to a temporary directory.

      --no-full-node
          Start the network without a fullnode

      --committee-size <COMMITTEE_SIZE>
          Set the number of validators in the network. If a genesis was already
          generated with a specific number of validators, this will not override
          it; the user should recreate the genesis with the desired number of
          validators

Persisting local network state​

If you stop and start the network without passing the --force-regenesis flag, all history is preserved and accessible.

By default, sui start uses an existing genesis and network configuration if the ~/.sui/sui_config folder exists and includes a genesis.blob file. If the folder does not exist, it creates the folder and generates a new genesis configuration. If you pass --network.config, the command checks for the network configuration file and tries to load the genesis blob as per the network configuration file.

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.

To view the transaction history for your local network, use the following command to retrieve the local total transaction count:

$ 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
}

Connecting the Sui CLI to your local network​

You can use the Sui CLI with any Sui network. To connect it to your local network, create a new environment alias named local that sets the CLI's RPC URL configuration to the local network's URL.

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

Next, 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 CLI uses the active address for each command if you do not explicitly specify one as a flag in the command. To see the current active address on your local network, use the command:

sui client active-address

The command returns an address, for example, 0xbc33e6e4818f9f2ef77d020b35c24be738213e64d9e58839ee7b4222029610de.

Use the local faucet​

Transactions on your local network require SUI coins to pay for gas fees just like on Mainnet, Testnet, and Devnet. The Sui CLI provides the sui client faucet command to get SUI from the local faucet. The faucet command uses the active address and the active network environment by default.

Run sui client faucet and wait approximately 60 seconds for the coins to reach your 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:

╭────────────────────────────────────────────────────────────────────┬────────────╮
│ 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. This requires that you start a local network with an indexer and GraphQL. To do so, use the following command:

sui start --force-regenesis --with-faucet --with-indexer --with-graphql

Then run the following command from the sui root folder:

$ pnpm --filter @mysten/sui test:e2e

For additional information about example data for testing, see the TypeScript example on GitHub.

Monitor activity​

Use a Sui network explorer to monitor your local network activity. You can build and run one locally or use the Custom RPC URL setting available on many online explorers to provide your local network's RPC URL (http://127.0.0.1:9000 by default).

Testing 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.

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, then try again.