docs: add setup instructions

.gitignore

@@ -24,5 +24,8 @@ config.yml
 working_dir
 *.log
 
-# Walrus binary
+# Walrus binary and configuration
+walrus
 examples/CONFIG/bin/walrus
+client_config.yaml
+examples/CONFIG/config_dir/client_config.yaml

docs/usage/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+## Configuration file
+
+You can configure the Walrus client through a `client_config.yaml` file. By default, the CLI will
+look for it in the current directory or in `~/.walrus/`, but you can specify a custom path through
+the `--client` option.
+
+The configuration file currently supports the following parameters:
+
+```yaml
+# This is the only mandatory field. The system object is specific for a particular Walrus
+# deployment. This is an example value; you can get the object ID for the current devnet deployment
+# as described below.
+system_object: 0x3243f6a8885a308d313198a2e03707344a4093822299f31d0082efa98ec4e6c8
+
+# 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: 3
+  max_concurrent_status_reads: null
+  reqwest_config:
+    total_timeout:
+      secs: 180
+      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
+```
+
+## System object ID
+
+You can get the system object ID of the current devnet deployment as follows:
+
+```sh
+curl https://storage.googleapis.com/mysten-walrus-binaries/walrus-configs/client_config.yaml
+```
+
+If you want, you can directly store this as a configuration file:
+
+```sh
+curl https://storage.googleapis.com/mysten-walrus-binaries/walrus-configs/client_config.yaml -o client_config.yaml
+```

docs/usage/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+We currently provide the `walrus` client binary for macOS (Intel and Apple CPUs) and Ubuntu. You can
+download the latest build from our Google Cloud Storage (GCS) bucket:
+
+```sh
+SYSTEM=macos-arm64 # or macos-x86_64 or ubuntu-x86_64
+curl https://storage.googleapis.com/mysten-walrus-binaries/latest/walrus-latest-$SYSTEM -o walrus
+chmod +x walrus
+```
+
+You can then run the CLI simply as `./walrus`, or, if it is in a different location, as
+`path/to/walrus`.  Alternatively, you can also place it into any directory that is in your `$PATH`
+and run it as `walrus`. See [the next chapter](./interacting.md) for further details on how to use
+it.
+
+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/>.

docs/usage/prerequisites.md

@@ -0,0 +1,21 @@
+# Prerequisites
+
+Interacting with Walrus requires a valid Sui testnet wallet with some amount of SUI tokens. The
+easiest way to set this up is via the Sui CLI; see the [installation
+instructions](https://docs.sui.io/guides/developer/getting-started/sui-install) 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. You can use the full node at
+`https://fullnode.testnet.sui.io:443`. See
+[here](https://docs.sui.io/guides/developer/getting-started/connect) for further details.
+
+Finally, you need to get testnet SUI tokens from the faucet:
+
+```sh
+sui client faucet
+```
+
+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](./configuration.md) or
+when [running the CLI](./interacting.md).

docs/usage/setup.md

@@ -0,0 +1,7 @@
+# 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](./interacting.md)). This chapter describes the
+[prerequisites](./prerequisites.md), [installation](./installation.md), and
+[configuration](./configuration.md) of the Walrus client.

examples/CONFIG/bin/README.md

@@ -1,3 +1,7 @@
-# Configuration
+# Walrus binary
 
-Place the 'walrus' client binary for your system in this directory.
+Place the `walrus` client binary for your system in this directory.
+
+See [the installation
+documentation](https://mystenlabs.github.io/walrus-docs/usage/installation.html) for how to obtain
+the binary.

examples/CONFIG/config_dir/README.md

@@ -0,0 +1,7 @@
+# Configuration
+
+Place the `client_config.yaml` configuration file in this directory.
+
+See [the configuration
+documentation](https://mystenlabs.github.io/walrus-docs/usage/configuration.html) for details of the
+available parameters and how to obtain the mandatory parameters.

examples/python/README.md

@@ -2,12 +2,29 @@
 
 ## Prerequisites
 
-- [Configure Sui Client](https://docs.sui.io/guides/developer/getting-started/connect) to connect
-  to testnet, and some testnet Sui tokens.
-- Configure Walrus TODO(#12).
-- Update the paths PATH_TO_WALRUS and PATH_TO_WALRUS_CONFIG and other
-  constant in `utils.py`.
+- Set up Sui and Walrus as described
+  [here](https://mystenlabs.github.io/walrus-docs/usage/setup.html).
+- Optional: Set up a Python virtual environment:
+
+  ```sh
+  python -m venv .venv
+  source .venv/bin/activate
+  ```
+
+- Install the dependencies:
+
+  ```sh
+  pip install -r requirements.txt
+  ```
+
+- Update the paths `PATH_TO_WALRUS` and `PATH_TO_WALRUS_CONFIG` and other constant in `utils.py`.
 
 ## Index of examples
 
-- ...
+- `hello_walrus_jsonapi.py` shows how to store and read blobs using the JSON API of the Walrus
+  client.
+- `hello_walrus_sui_system.py` prints information on the Walrus deployment based on the system
+  object.
+- `hello_walrus_webapi.py` shows how to store and read blobs using the HTTP API of the Walrus
+  client.
+- `track_walrus_events.py` is a simple script to track all Walrus-related events on Sui.

examples/python/hello_walrus_jsonapi.py

@@ -13,7 +13,7 @@
 from utils import num_to_blob_id, PATH_TO_WALRUS, PATH_TO_WALRUS_CONFIG, FULL_NODE_URL
 
 try:
-    # Create a 1MB file of random data
+    # Create a 1MiB file of random data
     random_data = os.urandom(1024 * 1024)
     tmp = tempfile.NamedTemporaryFile(delete=False)
     tmp.write(random_data)

examples/python/track_walrus_events.py

@@ -6,9 +6,7 @@
 import requests
 import re
 
-from utils import num_to_blob_id
-
-PATH_TO_WALRUS_CONFIG = "../CONFIG/config_dir/client_config.yaml"
+from utils import num_to_blob_id, PATH_TO_WALRUS_CONFIG
 
 system_object_id = re.findall(
     r"system_object:[ ]*(.*)", open(PATH_TO_WALRUS_CONFIG).read()