Setup

We provide a pre-compiled walrus client binary for macOS (Intel and Apple CPUs) and Ubuntu, which supports different usage patterns (see the next chapter). This chapter describes the prerequisites, installation, and configuration of the Walrus client.

Walrus is open-source under an Apache 2 license, and can also be built and installed from the Rust source code via cargo.

Prerequisites: Sui wallet, SUI and WAL

Interacting with Walrus requires a valid Sui wallet with some amount of SUI tokens. The normal way to set this up is via the Sui CLI; see the installation instructions in the Sui documentation.

After installing the Sui CLI, you need to set up a wallet by running sui client, which prompts you to set up a new configuration. Make sure to point it to Sui Mainnet, you can use the full node at https://fullnode.mainnet.sui.io:443 for this. See here for further details.

After this, you should get something like this (everything besides the mainnet line is optional):

$ sui client envs
╭──────────┬─────────────────────────────────────┬────────╮
│ alias    │ url                                 │ active │
├──────────┼─────────────────────────────────────┼────────┤
│ devnet   │ https://fullnode.devnet.sui.io:443  │        │
│ localnet │ http://127.0.0.1:9000               │        │
│ testnet  │ https://fullnode.testnet.sui.io:443 │        │
│ mainnet  │ https://fullnode.mainnet.sui.io:443 │ *      │
╰──────────┴─────────────────────────────────────┴────────╯

Make sure you have at least one gas coin with at least 1 SUI.

$ sui client gas
╭─────────────────┬────────────────────┬──────────────────╮
│ gasCoinId       │ mistBalance (MIST) │ suiBalance (SUI) │
├─────────────────┼────────────────────┼──────────────────┤
│ 0x65dca966dc... │ 1000000000         │ 1.00             │
╰─────────────────┴────────────────────┴──────────────────╯

Finally, to publish blobs on Walrus you will need some Mainnet WAL to pay for storage and upload costs. You can buy WAL through a variety of centralized or decentralized exchanges.

The system-wide wallet will be used by Walrus if no other path is specified. If you want to use a different Sui wallet, you can specify this in the Walrus configuration file or when running the CLI.

Installation

We currently provide the walrus client binary for macOS (Intel and Apple CPUs), Ubuntu, and Windows. The Ubuntu version most likely works on other Linux distributions as well.

Install via script

To download and install walrus to your "$HOME"/.local/bin directory, run one of the following commands in your terminal then follow on-screen instructions. See Windows instructions if you are on Windows.

# Run a first-time install using the latest Mainnet version.
curl -sSf https://docs.wal.app/setup/walrus-install.sh | sh

# Install the latest Testnet version instead.
curl -sSf https://docs.wal.app/setup/walrus-install.sh | sh -s -- -n testnet

# Update an existing installation (overwrites prior version of walrus).
curl -sSf https://docs.wal.app/setup/walrus-install.sh | sh -s -- -f

Make sure that the "$HOME"/.local/bin directory is in your $PATH.

Once this is done, you should be able to run Walrus by using the walrus command in your terminal.

You can see usage instructions as follows (see the next chapter for further details):

$ walrus --help
Walrus client

Usage: walrus [OPTIONS] <COMMAND>

Commands:
⋮

Install on Windows

To download walrus to your Microsoft Windows computer, run the following in a PowerShell.

(New-Object System.Net.WebClient).DownloadFile(
  "https://storage.googleapis.com/mysten-walrus-binaries/walrus-testnet-latest-windows-x86_64.exe",
  "walrus.exe"
)

From there, you'll need to place walrus.exe somewhere in your PATH.

GitHub releases

You can find all our releases including release notes on GitHub. Simply download the archive for your system and extract the walrus binary.

Install via Cargo

You can also install Walrus via Cargo. For example, to install the latest Mainnet version:

cargo install --git https://github.com/MystenLabs/walrus --branch mainnet walrus-service --locked

In place of --branch mainnet, you can also specify specific tags (e.g., --tag mainnet-v1.18.2) or commits (e.g., --rev b2009ac73388705f379ddad48515e1c1503fc8fc).

Build from source

Walrus is open-source software published under the Apache 2 license. The code is developed in a git repository at https://github.com/MystenLabs/walrus.

The latest version of Mainnet and Testnet are available under the branches mainnet and testnet respectively, and the latest version under the main branch. We welcome reports of issues and bug fixes. Follow the instructions in the README.md file to build and use Walrus from source.

Configuration

The Walrus client needs to know about the Sui objects that store the Walrus system and staking information, see the developer guide. These need to be configured in a file ~/.config/walrus/client_config.yaml. Additionally, a subsidies object can be specified, which will subsidize storage bought with the client.

You can access Testnet and Mainnet via the following configuration. Note that this example Walrus CLI configuration refers to the standard location for Sui configuration ("~/.sui/sui_config/client.yaml").

contexts:
  mainnet:
    system_object: 0x2134d52768ea07e8c43570ef975eb3e4c27a39fa6396bef985b5abc58d03ddd2
    staking_object: 0x10b9d30c28448939ce6c4d6c6e0ffce4a7f8a4ada8248bdad09ef8b70e4a3904
    subsidies_object: 0xb606eb177899edc2130c93bf65985af7ec959a2755dc126c953755e59324209e
    exchange_objects: []
    wallet_config:
      path: ~/.sui/sui_config/client.yaml
      active_env: mainnet
  testnet:
    system_object: 0x6c2547cbbc38025cf3adac45f63cb0a8d12ecf777cdc75a4971612bf97fdf6af
    staking_object: 0xbe46180321c30aab2f8b3501e24048377287fa708018a5b7c2792b35fe339ee3
    subsidies_object: 0xda799d85db0429765c8291c594d334349ef5bc09220e79ad397b30106161a0af
    exchange_objects:
      - 0xf4d164ea2def5fe07dc573992a029e010dba09b1a8dcbc44c5c2e79567f39073
      - 0x19825121c52080bb1073662231cfea5c0e4d905fd13e95f21e9a018f2ef41862
      - 0x83b454e524c71f30803f4d6c302a86fb6a39e96cdfb873c2d1e93bc1c26a3bc5
      - 0x8d63209cf8589ce7aef8f262437163c67577ed09f3e636a9d8e0813843fb8bf1
    wallet_config:
      path: ~/.sui/sui_config/client.yaml
      active_env: testnet
default_context: mainnet

curl https://docs.wal.app/setup/client_config.yaml -o ~/.config/walrus/client_config.yaml

Custom path (optional)

By default, the Walrus client will look for the client_config.yaml (or client_config.yml) configuration file in the current directory, $XDG_CONFIG_HOME/walrus/, ~/.config/walrus/, or ~/.walrus/. However, you can place the file anywhere and name it anything you like; in this case you need to use the --config option when running the walrus binary.

Advanced configuration (optional)

The configuration file currently supports the following parameters for each of the contexts:

# These are the only mandatory fields. These objects are specific for a particular Walrus
# deployment but then do not change over time.
system_object: 0x2134d52768ea07e8c43570ef975eb3e4c27a39fa6396bef985b5abc58d03ddd2
staking_object: 0x10b9d30c28448939ce6c4d6c6e0ffce4a7f8a4ada8248bdad09ef8b70e4a3904

# The subsidies object allows the client to use the subsidies contract to purchase storage
# which will reduce the cost of obtaining a storage resource and extending blobs and also
# adds subsidies to the rewards of the staking pools.
subsidies_object: 0xb606eb177899edc2130c93bf65985af7ec959a2755dc126c953755e59324209e

# You can define a custom path to your Sui wallet configuration here. If this is unset or `null`
# (default), the wallet is configured from `./sui_config.yaml` (relative to your current working
# directory), or the system-wide wallet at `~/.sui/sui_config/client.yaml` in this order. Both
# `active_env` and `active_address` can be omitted, in which case the values from the Sui wallet
# are used.
wallet_config:
  # The path to the wallet configuration file.
  path: ~/.sui/sui_config/client.yaml
  # The optional `active_env` to use to override whatever `active_env` is listed in the
  # configuration file.
  active_env: mainnet
  # The optional `active_address` to use to override whatever `active_address` is listed in the
  # configuration file.
  active_address: 0x...

# The following parameters can be used to tune the networking behavior of the client. There is no
# risk in playing around with these values. In the worst case, you may not be able to store/read
# blob due to timeouts or other networking errors.
communication_config:
  max_concurrent_writes: null
  max_concurrent_sliver_reads: null
  max_concurrent_metadata_reads: 3
  max_concurrent_status_reads: null
  max_data_in_flight: null
  reqwest_config:
    total_timeout_millis: 30000
    pool_idle_timeout_millis: null
    http2_keep_alive_timeout_millis: 5000
    http2_keep_alive_interval_millis: 30000
    http2_keep_alive_while_idle: true
  request_rate_config:
    max_node_connections: 10
    backoff_config:
      min_backoff_millis: 1000
      max_backoff_millis: 30000
      max_retries: 5
  disable_proxy: false
  disable_native_certs: false
  sliver_write_extra_time:
    factor: 0.5
    base_millis: 500
  registration_delay_millis: 200
  max_total_blob_size: 1073741824
  committee_change_backoff:
    min_backoff_millis: 1000
    max_backoff_millis: 5000
    max_retries: 5
refresh_config:
  refresh_grace_period_secs: 10
  max_auto_refresh_interval_secs: 30
  min_auto_refresh_interval_secs: 5
  epoch_change_distance_threshold_secs: 300
  refresher_channel_size: 100