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
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:
OS | CPU | Architecture |
---|---|---|
Ubuntu | Intel 64bit | ubuntu-x86_64 |
Ubuntu | Intel 64bit (generic) | ubuntu-x86_64-generic |
MacOS | Apple Silicon | macos-arm64 |
MacOS | Intel 64bit | macos-x86_64 |
Windows | Intel 64bit | windows-x86_64.exe |
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/
.
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:
⋮
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.
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
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.