feat: complete portal, site builder, links, and redirects

docs/SUMMARY.md

@@ -39,6 +39,8 @@
   - [Bonus: Set a SuiNS name](./walrus-sites/tutorial-suins.md)
   - [Advanced configuration](./walrus-sites/tutorial-config.md)
 - [Technical overview](./walrus-sites/overview.md)
+  - [Linking from and to Walrus Sites](./walrus-sites/linking.md)
+  - [Redirecting objects to Walrus Sites](./walrus-sites/redirects.md)
   - [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/linking.md

@@ -0,0 +1,42 @@
+# Linking from and to Walrus Sites
+
+Links in Walrus Sites work _almost_ as you would expect in a regular website. We specify here a few
+of the details.
+
+## Linking to resources within the same site
+
+Relative and absolute links (`href="/path/to/resource.html"`) work as usual.
+
+## Linking to resources on the Web
+
+Linking to a resource on the web (`href="https://some.cdn.example.com/stylesheet.css"`) also work as
+usual.
+
+## Linking to resources in other Walrus Sites
+
+Here is the part that is a bit different. Assume there is some image that you can browse at
+`https://gallery.walrus.site/walrus_arctic.webp`, and you want to link it from your own Walrus Site.
+
+Recall that, however, `https://walrus.site` is just one of the possibly many Portals. I.e., the same
+resource is browsable from a local portal (`http://gallery.localhost:8080/walrus_arctic.webp`), or
+from any other portal (e.g., `https://gallery.myotherportal.com/walrus_arctic.webp`). Therefore, how
+can you link the resource in a _Portal independent way_? This is important for interoperability,
+availability, and respecting the user's choice of portal.
+
+### The solution: Walrus Sites links
+
+We solve this problem by having the Portals interpret special links, that are normally invalid on
+the Web, and redirect to the corresponding Walrus Sites resource in the portal itself.
+
+Consider the example above, where the resource `/walrus_arctic.webp` is browsed from the Walrus Site
+with SuiNS name `gallery`, which points to the object ID `abcd123…` (in Base36 encoding). Then,
+the Portal-independent link is: `https://gallery.suiobj/walrus_arctic.webp`.  To fix the object ID
+instead of the SuiNS name, you can use `https://abcd123….suiobj/walrus_arctic.webp`.
+
+Another possibility is to directly point to the Walrus _blob ID_ of the resource, and have the
+browser "sniff" the content type. This works for images, for example, but not for script or
+stylesheets. For example to point to the blob ID (e.g., containing an image) `qwer5678…`, use the
+URL `https://blobid.walrus/qwer5678…`.
+
+With such a link, the Portal will extract the blob ID and redirect the request to the aggregator it
+is using to fetch blobs.

docs/walrus-sites/portal.md

@@ -1 +1,48 @@
 # The Walrus Sites Portal
+
+We use the term "Portal" to indicate any technology that is used to access an browse Walrus Sites.
+As mentioned in the [overview](./overview.md#the-site-rendering-path), we foresee three kinds of
+Portals:
+
+1. Server-side Portals;
+1. custom local apps; and
+1. service-worker based Portals in the browser.
+
+Currently, only the service-worker based Portal is available.
+
+## Running the Portal locally
+
+You can run a service worker Portal locally:
+
+- To browse Walrus Sites without accessing external Portals; or
+- for development purposes.
+
+This requires having the [`pnpm`](https://pnpm.io/) tool installed. To start, clone the repo and
+enter the `portal` directory. Here, run:
+
+``` sh
+pnpm install
+```
+
+to install the dependencies, and
+
+``` sh
+pnpm serve
+```
+
+to serve the Portal. Typically, you will find it served at `localhost:8080` (but check the output of
+the serve command).
+
+## Configuring the Portal
+
+The most important configuration parameters for the Portal are in `constants.ts`.
+
+- `NETWORK`: The Sui network to be used for fetching the Walrus Sites objects. Currently, we
+  use Sui `testnet`.
+- `AGGREGATOR`: The URL of the [aggregator](../usage/web-api) from which the service worker will
+  fetch the Walrus blobs.
+- `SITE_PACKAGE`: "0x514cf7ce2df33b9e2ca69e75bc9645ef38aca67b6f2852992a34e35e9f907f58"
+- `MAX_REDIRECT_DEPTH`: The number of [redirects](./redirects.md) the service worker will follow
+  before stopping.
+- `SITE_NAMES`: Hard coded `name: objectID` mappings, to override the SuiNS names. For development
+  only.

docs/walrus-sites/redirects.md

@@ -0,0 +1,41 @@
+# Redirecting objects to Walrus Sites
+
+We have seen in the [overview](./overview.md) how a Walrus Site object on Sui looks like. We will
+discuss now how you can create ensure that a _set of arbitrary objects_ can all be tied to a
+specific, and possibly unique, Walrus site.
+
+## The goal
+
+Consider a collection of NFTs, such as the one published by <https://flatland.walrus.site>. As we
+show there, each minted NFT has its own Walrus Site, that can be personalized based on the contents
+(e.g., the color) of the NFT itself. How can we achieve this?
+
+## Redirect links
+
+The solution is simple: We add a "redirect" in the NFT's
+[`Display`](https://docs.sui.io/standards/display#sui-utility-objects) property. Each time an NFT's
+object ID is browsed through a Portal, the Portal will check the `Display` of the NFT and, if it
+encounters the `walrus site address` key, it will go fetch the Walrus Site that is at the
+corresponding object ID.
+
+### Redirects in Move
+
+Practically speaking, when creating the `Display` of the NFT, you can include the key-value pair
+that points to the Walrus site that is to beused.
+
+``` move
+...
+const VISUALIZATION_SITE: address = @0x901fb0...;
+display.add(b"walrus site address".to_string(), VISUALIZATION_SITE.to_string());
+...
+```
+
+### How to personalize based on the NFT?
+
+The code above will only open the specified Walrus Site when browsing the object ID of the NFT. How
+do we ensure that the properties of the NFT can be used to personalize the site?
+
+This needs to be done in the `VISUALIZATION_SITE`: Since the subdomain is still pointing to the
+NFT's object ID, the Walrus Site that is loaded can check its `origin` in Javascript, and use the
+subdomain to determine the NFT, fetch it from chain, and use its internal fields to modify the
+displayed site.

docs/walrus-sites/site-builder.md

@@ -1 +1,26 @@
 # The site builder
+
+To facilitate the creation of Walrus Sites, we provide the "site builder" tool. The site builder
+takes care of creating Walrus Sites object on Sui, with the correct structure, and stores the site
+resources to Walrus.
+
+## Site builder commands
+
+The site builder tool exposes the following commands:
+
+- `publish`: Allows to publish a specific directory to Walrus. The directory must contain files that
+  can be served with HTTP, and have an `index.html` file. This command will return a Sui object ID
+  for the newly created site.
+- `update`: After creating a site, you can update it with this command. It takes as input a
+  directory, as above, with the new or updated files, and the object ID of the site to update. Note
+  that the wallet you are using must be the _owner_ of the Walrus Site object to be able to update
+  it. This command will remove and create resources as required, to ensure that the Walrus Sites
+  object on Sui matches the local directory. If run with `--watch`, this command re-updates the site
+  _every time a file in the directory changes_. This is useful during development, but pay attention
+  to costs!
+- `convert`: A utility tool. Given a Sui object ID in Hex format, it converts it to Base36. This is
+  useful if you know the Sui object ID of a site, and want to find the URL.
+- `sitemap`: A utility tool. For a give Walrus Sites Sui object ID, prints out all the resources
+  that compose the site and their object ID.
+
+Check the commands' `--help` for more information.