docs: finish tutorial

docs/SUMMARY.md

@@ -34,12 +34,12 @@
 - [Introduction to Walrus Sites](./walrus-sites/intro.md)
 - [Your first Walrus Site](./walrus-sites/tutorial.md)
   - [Installing the site builder](./walrus-sites/tutorial-install.md)
-  - [Using the site builder](./walrus-sites/tutorial-use.md)
-  - [Configuring the site builder](./walrus-sites/tutorial-config.md)
+  - [Publishing a Walrus Site](./walrus-sites/tutorial-publish.md)
   - [Bonus: Set a SuiNS name](./walrus-sites/tutorial-suins.md)
+  - [Advanced configuration](./walrus-sites/tutorial-config.md)
 - [Technical overview](./walrus-sites/overview.md)
-  - [The site builder]()
-  - [The Walrus Sites Portal]()
+  - [The site builder](./walrus-sites/site-builder.md)
+  - [The Walrus Sites Portal](./walrus-sites/portal.md)
   - [Known restrictions](./walrus-sites/restrictions.md)
 
 ---

docs/walrus-sites/restrictions.md

@@ -1,63 +1,51 @@
 # Known restrictions
 
-Walrus Sites can be used to deploy almost any form of traditional
-static "Web 2" website build for modern browsers. There are, however,
-a number of restrictions that a developer should keep in mind when
-creating or porting a website to Walrus Sites.
+Walrus Sites can be used to deploy almost any form of traditional static "Web 2" website build for
+modern browsers. There are, however, a number of restrictions that a developer should keep in mind
+when creating or porting a website to Walrus Sites.
 
 ## No secret values
 
-Walrus Sites are fully publicly accessible, as the metadata is stored
-on Sui and the site content is stored on Walrus. Therefore, developers
-_must_ not store secret values within the sites.
+Walrus Sites are fully publicly accessible, as the metadata is stored on Sui and the site content is
+stored on Walrus. Therefore, developers _must_ not store secret values within the sites.
 
-We emphasize again that any such backend-specific operations (storing
-secret values, authentication, etc.) are achievable by leveraging the
-integration with Sui blockchain and the Sui wallet.
+We emphasize again that any such backend-specific operations (storing secret values, authentication,
+etc.) are achievable by leveraging the integration with Sui blockchain and the Sui wallet.
 
 ## There is a maximum redirect depth
 
-The number of consecutive [redirects](./walrus-sites/) a Walrus Site
-can perform is capped by the Portal (see [Portal configuration]()).
-This measure ensure that loading a Walrus Site does not result in an
-infinite loading loop.
+The number of consecutive redirects a Walrus Site can perform is capped by the
+Portal (see [Portal configuration](./portal.md)).  This measure ensure that loading a Walrus Site
+does not result in an infinite loading loop.
 
-Different Portals can set this limit as they desire. The limit for the
-Portal hosted at [walrus.site](http://walrus.site) has a maximum
-redirect depth of 3.
+Different Portals can set this limit as they desire. The limit for the Portal hosted at
+[walrus.site](http://walrus.site) has a maximum redirect depth of 3.
 
 ## Service workers are not available
 
-<div class="warning">
-This limitation only applies to Portal based on service workers. A web
-Portal will not have this limitation.
-</div>
+**WARNING**: This limitation only applies to Portal based on service workers. A web Portal will not
+have this limitation.
 
-Walrus Sites leverage service workers in the clients' browsers to
-perform the essential operations of:
+Walrus Sites leverage service workers in the clients' browsers to perform these essential
+operations:
 
 1. reading the site metadata from Sui;
 1. fetching the page content from Walrus; and
 1. serving the content to the browser.
 
-Therefore, a site deployed on Walrus Sites cannot use service
-workers. Installing a service worker from within a Walrus Site will
-result is a dysfunctional site and a poor experience for the user.
+Therefore, a site deployed on Walrus Sites cannot use service workers. Installing a service worker
+from within a Walrus Site will result is a dysfunctional site and a poor experience for the user.
 
 ## The iOS Sui Wallet Mobile does not work with Walrus Sites
 
-<div class="warning">
-This limitation only applies to Portal based on service workers. A web
-Portal will not have this limitation.
-</div>
-
-Service workers cannot be loaded inside an in-app browser on iOS,
-because of a limitation of the WebKit engine. As a consequence, Walrus
-Sites cannot be used within the [Sui Wallet
-Mobile](https://apps.apple.com/us/app/sui-wallet-mobile/id6476572140)
-app on iOS, and therefore using the Sui wallet on a Walrus Site is
-currently impossible. Note, however, that _browsing_ a Walrus Site is
-still possible on iOS through any browser. Only the connection to the
-wallet is impacted.
+**WARNING**: This limitation only applies to Portal based on service workers. A web Portal will not
+have this limitation.
+
+Service workers cannot be loaded inside an in-app browser on iOS, because of a limitation of the
+WebKit engine. As a consequence, Walrus Sites cannot be used within the [Sui Wallet
+Mobile](https://apps.apple.com/us/app/sui-wallet-mobile/id6476572140) app on iOS, and therefore
+using the Sui wallet on a Walrus Site is currently impossible. Note, however, that _browsing_ a
+Walrus Site is still possible on iOS through any browser. Only the connection to the wallet is
+impacted.
 
 The connection with the Sui Wallet Mobile app works on Android devices.

docs/walrus-sites/tutorial-config.md

@@ -10,9 +10,9 @@ here the details for all the configuration options.
 
 ## Minimal configuration
 
-The config file is expected to be in `./config.yaml`, and it is possible to point elsewhere with the
-`--config` flag.  For your first run, it should be sufficient to call the `site-builder` with
-`--config assets/config-example.yaml`, which is already configured appropriately
+The config file is expected to be in `./builder.yaml`, and it is possible to point elsewhere with
+the `--config` flag.  For your first run, it should be sufficient to call the `site-builder` with
+`--config assets/builder-example.yaml`, which is already configured appropriately.
 
 ## Advanced configuration
 
@@ -21,13 +21,16 @@ following variables in the config file:
 
 - `package`: the object ID of the Walrus Sites package on Sui. This must always be specified in the
   config, and is already appropriately configured in `assets/example-config.yaml`.
-- `module`: the name of the module in the Walrus Sites package [default: `site`].
+- `module`: the name of the module in the Walrus Sites package.
 - `portal`: the name of the portal through which the site will be viewed; this only affects the
-  output of the CLI, and nothing else [default: `walrus.site`].
+  output of the CLI, and nothing else (default: `walrus.site`).
 - `general`: these are general options, that can be configured both through the CLI and the config:
-  - `rpc_url`: The URL of the RPC to use. If not set, the `site-builder` will infer it from the wallet.
-  - `wallet`: Pointer to the Sui wallet to be used. By default, it uses???
-  - `walrus_binary`: Pointer to the `walrus` binary. By default, this is expected to be run from `$PATH`.
-  - `walrus_config`: The configuration for the `walrus` client binary. See [the relative documentation](TODO: link).
-  - `gas_budget`: The maximum amount of gas to be spent for transactions [default: 500M MIST].
-  - `gas_coin`: The gas coin to be used to pay for the transaction (TODO: remove).
+  - `rpc_url`: The URL of the RPC to use. If not set, the `site-builder` will infer it from the
+    wallet.
+  - `wallet`: Pointer to the Sui wallet to be used. By default, it uses the system-wide wallet (the
+    one from `sui client addresses`).
+  - `walrus_binary`: Pointer to the `walrus` binary. By default, this is expected to be run from
+    `$PATH`.
+  - `walrus_config`: The configuration for the `walrus` client binary. See the relative
+    documentation (TODO: link).
+  - `gas_budget`: The maximum amount of gas to be spent for transactions (default: 500M MIST).

docs/walrus-sites/tutorial-install.md

@@ -14,13 +14,18 @@ Then, follow these additional setup steps.
 
 ## Get the `walrus` binary and install it
 
-Download the [latest `walrus` binary](TODO: link) for your architecture, and add it to your
-`$PATH`. For example, on MacOS you can copy it to `/Users/myusername/.local/bin/` (check what
-directories are in your `$PATH` by running `echo $PATH`).
+Download the latest `walrus` binary for your architecture from
+`https://storage.googleapis.com/mysten-walrus-binaries/walrus-v0.1.0-a0fb8c9-<arch>`, where `<arch>`
+is your architecture.  If you are on a Macbook with M* chip, substitute `macos-arm64`. Other
+possible values are `macos-x86_64` or `ubuntu-x86_64`.
+
+Then, add it to your `$PATH`. For example, on MacOS you can copy it to
+`/Users/myusername/.local/bin/` (check what directories are in your `$PATH` by running `echo
+$PATH`).
 
 Once this is done, you should be able to type `walrus` in your terminal and see:
 
-```
+``` txt
 Walrus client
 
 Usage: walrus [OPTIONS] <COMMAND>
@@ -62,7 +67,7 @@ this later).
 Walrus is currently deployed on Sui Testnet. Therefore, you have to ensure that your Sui CLI is
 configured accordingly:
 
-```
+``` bash
 sui client envs
 ╭──────────┬──────────────────────────────────────┬────────╮
 │ alias    │ url                                  │ active │
@@ -77,7 +82,7 @@ sui client envs
 Further, make sure you have at least 2 separate gas coins, with at least 1 SUI each, by running `sui
 client gas`.  If you don't have enough SUI, you can hit the testnet faucet by running.
 
-```
+``` sh
 sui client faucet --url https://faucet.testnet.sui.io/v1/gas
 ```
 
@@ -86,31 +91,30 @@ wallet.
 
 ## Clone the Walrus Sites repo, and build the `site-builder` tool
 
-TODO: do we want to provide the binary for the site builder too?
+First clone and enter the Walrus Sites repo from
+`https://github.com/MystenLabs/blocksite-poc`). (TODO: change link to public repo when available).
 
-First clone and enter the [Walrus Sites repo](https://github.com/MystenLabs/blocksite-poc). (TODO: change link to public repo when available).
-
-``` bash
+``` sh
 git clone [email protected]:MystenLabs/blocksite-poc.git
 cd blocksite-poc
 cd site-builder
 ```
 
 Build the release version of the site builder.
 
-``` bash
+``` sh
 cargo build --release
 ```
 
 After the build process completes, it should be possible to run:
 
-```
+``` sh
 ./target/release/site-builder
 ```
 
 And output should look like the following:
 
-```
+``` txt
 Usage: site-builder [OPTIONS] <COMMAND>
 
 Commands:
@@ -143,4 +147,7 @@ Options:
 
 ## Get the latest `walrus` client configuration
 
-TODO: get it from the gcp bucket and copy it to the site builder directory
+First,
+[download](https://storage.googleapis.com/mysten-walrus-binaries/walrus-configs/client_config.yaml)
+the `walrus` client config.  Then, copy it to `~/.walrus/config.yaml`. This ensures that the
+`walrus` binary can connect to the correct Walrus object on Sui.

docs/walrus-sites/tutorial-publish.md

@@ -0,0 +1,96 @@
+# Publishing a Walrus Site
+
+Now that everything is installed and configured, you should be able to start publishing
+your first Walrus Site!
+
+## Select the source material for the site
+
+The `site-builder` works by uploading a directory of files produced by any web framework to Walrus,
+and adding the relevant metadata to Sui. This directory should have a file called `index.html` in
+its root, which will be the entry point to the Walrus Site.
+
+For the rest of the tutorial, we will use as an example the simple site contained in
+`./examples/snake`.
+
+## Publish the site
+
+Since we have placed the `walrus` binary and configuration in their default locations, publishing
+the `./examples/snake` site is simple:
+
+- Ensure that you are in the `site-builder` directory;
+- Run the publishing command:
+
+  ``` sh
+  ./target/release/site-builder --config assets/builder-example.yaml publish ../examples/snake
+  ```
+
+The output should look like the following:
+
+``` txt
+Operations performed:
+- created resource /Oi-Regular.ttf with blob ID 2YLU3Usb-WoJAgoNSZUNAFnmyo8cfV8hJYt2YdHL2Hs
+- created resource /file.png with blob ID R584P82qm4Dn8LoQMlzkGZS9IAkU0lNZTVlruOsUyOs
+- created resource /index.html with blob ID SSzbpPfOtTqk6xNyF1i-NG9I9CjUjuWnhUATVSs5nic
+- created resource /walrus.png with blob ID SGrrw5NQyFWtqtxzLAQ1tLpcChGc0VNbtFRhfsQPuiM
+
+Created new site: test site
+New site object ID: 0x5ac988828a0c9842d91e6d5bdd9552ec9fcdddf11c56bf82dff6d5566685a31e
+
+Browse the resulting site at: https://29gjzk8yjl1v7zm2etee1siyzaqfj9jaru5ufs6yyh1yqsgun2.walrus.site
+```
+
+This output tells you that, for each file in the folder, a new Walrus blob was created, and the
+respective blob ID.  Further it prints the object ID of the Walrus Site object on Sui (so you can
+have a look in the explorer, and use it to set the SuiNS name), and, finally, the URL at which you
+can browse the site.
+
+Note here that we are passing the example config `assets/builder-example.yaml` as the config for the
+site builder. The configuration file is necessary to ensure that the `site-builder` knows the
+correct Sui package for the Walrus Sites logic.
+
+More details on the configuration of the `site-builder` can be found under the [advanced
+configuration](tutorial-config.md) section.
+
+## Update the site
+
+Let's say now you want to update the content of the site, for example by changing the title from
+"eat all the blobs!" to "Glob all the Blobs!".
+
+First, make this edit on in the `../examples/snake/index.html` file.
+
+Then, you can update the existing site by running the `update` command, and providing the directory
+where to find the updated files (still `../example/snake`), and the object ID of the existing site
+(`0x5ac988...`):
+
+``` sh
+./target/release/site-builder --config assets/builder-example.yaml update ../examples/snake 0x5ac9888...
+```
+
+The output this time should be:
+
+``` txt
+Operations performed:
+  - deleted resource /index.html with blob ID SSzbpPfOtTqk6xNyF1i-NG9I9CjUjuWnhUATVSs5nic
+  - created resource /index.html with blob ID LXtY0VdY5kM-3Ph7gLvj8URdz5yiRa5DUy3ZxYqDView
+
+Updated site at object ID: 0x5ac988828a0c9842d91e6d5bdd9552ec9fcdddf11c56bf82dff6d5566685a31e
+
+Browse the resulting site at: https://29gjzk8yjl1v7zm2etee1siyzaqfj9jaru5ufs6yyh1yqsgun2.walrus.site
+```
+
+Compared to the `publish` action, we can see that now the only actions performed were to delete the
+old `index.html`, and update it with the newer one.
+
+Browsing to the provided URL should reflect the change. You've updated the site!
+
+## Additional commands
+
+The `site-builder` tool provides two additional utilities:
+
+- the `convert` command, which converts an object ID in hex format to the equivalent Base36
+  format. This command is useful if you have the Sui object ID of a Walrus Site, and want to know
+  the subdomain where you can browse it.
+- the `sitemap` command, which shows the resources that compose the Walrus Site at the given object
+  ID.
+
+In general, the `--help` flag is your friend!

docs/walrus-sites/tutorial-suins.md

@@ -1 +1,45 @@
 # Bonus: Set a SuiNS name
+
+Browsing a URL like `https://29gjzk8yjl1v7zm2etee1siyzaqfj9jaru5ufs6yyh1yqsgun2.walrus.site` is not
+particularly nice. Therefore, Walrus Sites allows to use SuiNS names (this is like DNS for Sui) to
+give human-readable names to site. To do so, you simply have to get a SuiNS name you like, and point
+it to the object ID of the Walrus Site (as provided by the `publish` or `update` commands).
+
+Let's do this step by step.
+
+## Get a SuiNS name
+
+IMPORTANT: for this to work, the wallet with which you purchase the SuiNS name should be the same as
+the wallet you use in the Sui CLI. Unfortunately the SuiNS interface on Testnet does not allow
+setting the resolution through the UI.
+
+- Navigate to [https://testnet.suins.io/](https://testnet.suins.io/), and buy a domain name with
+  your testnet wallet. For example, `walursgame` (NOTE: this is already taken, choose another you
+  like!). NOTE: At the moment, you can only select names that are composed of letters `a-z` and
+  numbers `0-9`, but no special characters (e.g., `-`).
+- In the [page](https://testnet.suins.io/account/my-names) listing the domains you own, you should
+  see the newly-bought name.
+- Click the three-dots menu on the top-right corner of the name you want to assign. Choose "View all
+  info", and copy the `ObjectID`. In our case, this is
+  `0x6412c4cfbe50e219c2d4d30108d7321d064e15bf64e752307100bff5eb91da38`.
+
+## Map the SuiNS name to the Walrus Site
+
+This step associates the name `walrusgame` to the object ID of our Walrus Site. There are possibly
+many ways to achieve this, and as the SuiNS UI improves this could be done from the webapp as well.
+
+Here, we issue an transaction using the Sui CLI that creates this mapping.
+
+``` sh
+ sui client call \
+    --package 0x22fa05f21b1ad71442491220bb9338f7b7095fe35000ef88d5400d28523bdd93 \
+    --module controller \
+    --function set_target_address \
+    --gas-budget 500000000 \
+    --args 0x300369e8909b9a6464da265b9a5a9ab6fe2158a040e84e808628cde7a07ee5a3 \
+    --args 0x6412c4cfbe50e219c2d4d30108d7321d064e15bf64e752307100bff5eb91da38 \
+    --args "[0x5ac988828a0c9842d91e6d5bdd9552ec9fcdddf11c56bf82dff6d5566685a31e]" \
+    --args 0x6
+```
+
+If all succeeds, we can now browse [https://walrusgame.walrus.site](https://walrusgame.walrus.site)!