Setup

At this stage of the project, our Walrus code is not yet public. Instead, 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.

Prerequisites: Sui wallet and Testnet SUI

Quick wallet setup

If you just want to set up a new SUI wallet for Walrus, you can skip this section and use the walrus generate-sui-wallet command after installing Walrus. In that case, make sure to set the wallet_config parameter in the Walrus configuration to the newly generated wallet.

Interacting with Walrus requires a valid Sui Testnet 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 Testnet wallet by running sui client, which prompts you to set up a new configuration. Make sure to point it to Sui Testnet, you can use the full node at https://fullnode.testnet.sui.io:443 for this. See here for further details.

If you already have a Sui wallet configured, you can directly set up the Testnet environment (if you don't have it yet),

sui client new-env --alias testnet --rpc https://fullnode.testnet.sui.io:443

and switch the active environment to it:

sui client switch --env testnet

After this, you should get something like this (everything besides the testnet 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 │        │
╰──────────┴─────────────────────────────────────┴────────╯

Finally, make sure you have at least one gas coin with at least 1 SUI. You can obtain one from the Testnet faucet:

sui client faucet

After some seconds, you should see your new SUI coins:

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

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:

OSCPUArchitecture
UbuntuIntel 64bitubuntu-x86_64
UbuntuIntel 64bit (generic)ubuntu-x86_64-generic
MacOSApple Siliconmacos-arm64
MacOSIntel 64bitmacos-x86_64
WindowsIntel 64bitwindows-x86_64.exe

Windows

We now offer a pre-built binary also for Windows. However, most of the remaining instructions assume a UNIX-based system for the directory structure, commands, etc. If you use Windows, you may need to adapt most of those.

You can download the latest build from our Google Cloud Storage (GCS) bucket (correctly setting the $SYSTEM variable):

SYSTEM= # set this to your system: ubuntu-x86_64, ubuntu-x86_64-generic, macos-x86_64, macos-arm64, windows-x86_64.exe
curl https://storage.googleapis.com/mysten-walrus-binaries/walrus-testnet-latest-$SYSTEM -o walrus
chmod +x walrus

On Ubuntu, you should generally use the ubuntu-x86_64 version. However, this is incompatible with old hardware and certain virtualized environments (throwing an "Illegal instruction (core dumped)" error); in these cases you can use the ubuntu-x86_64-generic version.

To be able to run it simply as walrus, move the binary to any directory included in your $PATH environment variable. Standard locations are /usr/local/bin/, $HOME/bin/, or $HOME/.local/bin/.

Note

Previously, this guide recommended placing the binary in $HOME/.local/bin/. If you install the latest binary somewhere else, make sure to clean up old versions. You can find the binary in use by calling which walrus and its version through walrus -V.

Once this is done, you should be able to simply type walrus in your terminal. For example you can get usage instructions (see the next chapter for further details):

$ walrus --help
Walrus client

Usage: walrus [OPTIONS] <COMMAND>

Commands:
⋮

Tip

Our latest Testnet Walrus binaries are also available on Walrus itself, namely on https://bin.blob.store, for example, https://bin.blob.store/walrus-testnet-latest-ubuntu-x86_64.

Previous versions (optional)

In addition to the latest version of the walrus binary, the GCS bucket also contains previous versions. An overview in XML format is available at https://storage.googleapis.com/mysten-walrus-binaries/.

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, if the contracts were upgraded at any point, the object ID of the latest package version can be specified in the walrus_package field. Finally, exchange objects are needed to swap SUI for WAL.

The current Testnet deployment uses the following objects:

system_object: 0x50b84b68eb9da4c6d904a929f43638481c09c03be6274b8569778fe085c1590d
staking_object: 0x37c0e4d7b36a2f64d51bba262a1791f844cfd88f31379f1b7c04244061d43914
walrus_package: 0x3d35ad1028562025f6f24336f0298d3775ba896bbbb63be7ad5b9fee8255dd89
exchange_object:
  - 0x0e60a946a527902c90bbc71240435728cd6dc26b9e8debc69f09b71671c3029b
  - 0x8a23a552895e341bca0106861786e014b5bb2f576bd7f76754226cc92266a0ee
  - 0x7c469c2b189379bff42874742c292934c03cde9d0a2c20f293f1a32f8eece68c
  - 0x59e7fa1b967c739ce676a7a3d8de444ac165f742421ba3b17656e2aee9fe541e

Note that configuring multiple exchange objects are only supported with the CLI version 1.2.0 or higher.

Tip

The easiest way to obtain the latest configuration is by downloading it from https://docs.blob.store/client_config.yaml:

curl https://docs.blob.store/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:

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

# The latest version of the Walrus package can be specified with the `walrus_package` parameter.
walrus_package: 0x3d35ad1028562025f6f24336f0298d3775ba896bbbb63be7ad5b9fee8255dd89

# The exchange objects are used to swap SUI for WAL. If multiple ones are defined (as below), a
# random one is chosen for the exchange.
exchange_object:
  - 0x0e60a946a527902c90bbc71240435728cd6dc26b9e8debc69f09b71671c3029b
  - 0x8a23a552895e341bca0106861786e014b5bb2f576bd7f76754226cc92266a0ee
  - 0x7c469c2b189379bff42874742c292934c03cde9d0a2c20f293f1a32f8eece68c
  - 0x59e7fa1b967c739ce676a7a3d8de444ac165f742421ba3b17656e2aee9fe541e

# You can define a custom path to your Sui wallet configuration here. If this is unset or `null`,
# 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.
wallet_config: null

# 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: null
  max_concurrent_status_reads: null
  max_data_in_flight: null
  reqwest_config:
    total_timeout:
      secs: 30
      nanos: 0
    pool_idle_timeout: null
    http2_keep_alive_timeout:
      secs: 5
      nanos: 0
    http2_keep_alive_interval:
      secs: 30
      nanos: 0
    http2_keep_alive_while_idle: true
  request_rate_config:
    max_node_connections: 10
    max_retries: 5
    min_backoff:
      secs: 2
      nanos: 0
    max_backoff:
      secs: 60
      nanos: 0
  disable_proxy: false
  disable_native_certs: false
  sliver_write_extra_time:
    factor: 0.5
    base:
      secs: 0
      nanos: 500000000

Important

If you specify a wallet path, make sure your wallet is set up for Sui Testnet.

Testnet WAL faucet

The Walrus Testnet uses Testnet WAL tokens to buy storage and stake. Testnet WAL tokens have no value and can be exchanged (at a 1:1 rate) for some Testnet SUI tokens, which also have no value, through the following command:

walrus get-wal

You can check that you have received Testnet WAL by checking the Sui balances:

sui client balance
╭─────────────────────────────────────────╮
│ Balance of coins owned by this address  │
├─────────────────────────────────────────┤
│ ╭─────────────────────────────────────╮ │
│ │ coin  balance (raw)     balance     │ │
│ ├─────────────────────────────────────┤ │
│ │ Sui   8869252670        8.86 SUI    │ │
│ │ WAL   500000000         0.50 WAL    │ │
│ ╰─────────────────────────────────────╯ │
╰─────────────────────────────────────────╯

By default, 0.5 SUI are exchanged for 0.5 WAL, but a different amount of SUI may be exchanged using the --amount option (the value is in MIST/FROST), and a specific SUI/WAL exchange object may be used through the --exchange-id option. The walrus get-wal --help command provides more information about those.