diff --git a/docs/walrus-sites/intro.md b/docs/walrus-sites/intro.md new file mode 100644 index 00000000..4c64b33f --- /dev/null +++ b/docs/walrus-sites/intro.md @@ -0,0 +1,62 @@ +# Introduction to Walrus Sites + +_Walrus Sites_ are "web"-sites that use Sui and Walrus as their underlying technology. They are a +prime example of how Walrus can be used to build new and exciting decentralized applications. Anyone +can build and deploy a Walrus Site, and make it accessible to the World! + +At a high level, the most exciting features include: + +- Publishing a site does not require managing servers or complex configurations; just provide the + source files (produced by your favorite web framework), publish them to Walrus Sites using the + [site builder tool](./site-builder.md), and you are done! +- Sites can be linked to from ordinary Sui objects. This feature enables, for example, creating a + NFT collection in which _every single NFT_ has a _personalized website dedicated to it_. +- Walrus Sites are owned by addresses on Sui, and can be exchanged, shared, and updated thanks to + Sui's flexible programming model. This means, among other things, that Walrus Sites can leverage + the [SuiNS](https://suins.io/) naming system to have human readable names. No more messing around + with DNS! +- Thanks to Walrus' decentralization and extremely high data availability, there is no risk of + having your site wiped for no reason. +- Since they live on Walrus, these sites cannot have a backend in the traditional sense, and can be + therefore considered "static" sites. However, the developer can harness the Sui's programmability + to add backend functionality to Walrus Sites! + +## Show me! + +To give you a very high level intuition of how Walrus Sites work, let's look at an example: A simple +NFT collection on Sui, that has a frontend dApp to mint the NFTs hosted on Walrus Sites, and in +which _each NFT_ has a _specific, personalized Walrus Site_. + +You can check out the mint page at +[https://flatland.walrus.site/](https://flatland.walrus.site/). This site is serve to your browser +through the Walrus Site _Portal_ [https://walrus.site](https://walrus.site). While the Portal's +operation is explained in a [later section](./portal.md), consider for now that there +can be many Portals (hosted by whomever wants to have their own, and even on `localhost`). Further, +the only function of the Portal is to provide the browser with some code (specifically, a service +worker) that allows it to fetch the Walrus Site from Sui and Walrus. + +If you have a Sui wallet with some Testnet SUI, you can try and "mint a new Flatlander" from the +site. This creates an NFT from the collection, and shows you two links, one to the explorer, and one +to the "Flatlander site". This latter site is a special Walrus Site that exists only for that NFT, +and has special characteristics (the background color, the image...) that are based on the contents +of the NFT. + +The URL to this per-NFT site look something like this +`https://4egmmrw9izzjn0dm2lkd3k0l8phk386z60ub1tpdc1jswbb5dr.walrus.site/`. You'll notice that the +domain remains `walrus.site`, but the subdomain is a long and random-looking string. This string is +actually the [Base36](https://en.wikipedia.org/wiki/Base36) encoding of the object ID of the NFT, +which is +[0xb09b312b...](https://suiscan.xyz/testnet/object/0xb09b312b28049467dd6173b6cebb60ed5fe3046883e248632bf9fb20b7dbdaff). + +In summary: + +- Walrus Sites are served through a portal; in this case, `https://walrus.site`. There can be many + portal, and anyone can host one. +- The subdomain on the URL points to a specific object on Sui, that allows the browser to fetch and + render the site resources. This pointer can be: + - A SuiNS name, such as `flatland` in `https://flatland.walrus.site`; or + - the Base36 encoding of a the Sui object ID, such as `0xb09b312b...` in the example above. + +Curious to know how this magic is possible? Read the [technical +overview](./overview.md)! If you just want to get started try Walrus Sites out, check the +[tutorial](./tutorial.md). diff --git a/docs/walrus-sites/overview.md b/docs/walrus-sites/overview.md new file mode 100644 index 00000000..07dd0c5c --- /dev/null +++ b/docs/walrus-sites/overview.md @@ -0,0 +1 @@ +# Overview diff --git a/docs/walrus-sites/restrictions.md b/docs/walrus-sites/restrictions.md new file mode 100644 index 00000000..4e07ed18 --- /dev/null +++ b/docs/walrus-sites/restrictions.md @@ -0,0 +1,64 @@ +# 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. + + +## 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. + +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. + +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 + +
+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: + +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. + +## The iOS Sui Wallet Mobile does not work with Walrus Sites + +
+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. diff --git a/docs/walrus-sites/tutorial-config.md b/docs/walrus-sites/tutorial-config.md new file mode 100644 index 00000000..b977796c --- /dev/null +++ b/docs/walrus-sites/tutorial-config.md @@ -0,0 +1,33 @@ +# Configuring the site builder + +Configuring the `site-builder` tool is straightforward, but care is required to ensure that +everything works correctly. + +The `site-builder` tool requires a configuration file to know which package to use on Sui, which +wallet to use, the gas budget, and other operational details. Most of these are abstracted away +through sensible defaults, so you should not need to touch them. Yet, for completeness, we provide +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 alredy configured appropriately + +## Advanced configuration + +If you want to have more control over the behavior of the site builder, you can customize the +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`]. +- `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`]. +- `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). diff --git a/docs/walrus-sites/tutorial-install.md b/docs/walrus-sites/tutorial-install.md new file mode 100644 index 00000000..ae71983d --- /dev/null +++ b/docs/walrus-sites/tutorial-install.md @@ -0,0 +1,140 @@ +# Installing the site builder + +We describe here the steps necessary to setup the Walrus Sites' `site-builder` tool, and prepare +your environment for development. + +## Prerequisites + +Before you start, make sure you: + +- Have a recent version of [Rust](https://www.rust-lang.org/tools/install) installed; and +- have the [Sui CLI](https://docs.sui.io/guides/developer/getting-started/sui-install) installed. + +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`). + +Once this is done, you should be able to type `walrus` in your terminal and see: +``` +Walrus client + +Usage: walrus [OPTIONS] + +Commands: + store Store a new blob into Walrus + read Read a blob from Walrus, given the blob ID + publisher Run a publisher service at the provided network address + aggregator Run an aggregator service at the provided network address + daemon Run a client daemon at the provided network address, combining + the functionality of an aggregator and a publisher + info Print information about the Walrus storage system this client + is connected to + json Run the client by specifying the arguments in a JSON string; + CLI options are ignored + blob-id Encode the specified file to obtain its blob ID + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config + The path to the wallet configuration file. + -w, --wallet + The path to the Sui wallet configuration file. + -g, --gas-budget + The gas budget for transactions [default: 500000000] + -h, --help + Print help (see more with '--help') + -V, --version + Print version + +``` + +If, for any reason, you don't want to add `walrus` to `$PATH`, place the binary in your preferred +directory, and remember to configure a pointer to the binary in the `site-builder` config (more on +this later). + +## Point your Sui CLI to testnet, and get some SUI + +Walrus is currently deployed on Sui Testnet. Therefore, you have to ensure that your Sui CLI is +configured accordingly: + +``` +sui client envs +╭──────────┬──────────────────────────────────────┬────────╮ +│ alias │ url │ active │ +├──────────┼──────────────────────────────────────┼────────┤ +│ devnet │ https://fullnode.devnet.sui.io:443 │ │ +│ local │ http://127.0.0.1:9000 │ │ +│ testnet │ https://fullnode.testnet.sui.io:443/ │ * │ +│ mainnet │ https://fullnode.mainnet.sui.io:443 │ │ +╰──────────┴──────────────────────────────────────┴────────╯ +``` + +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. + +``` +sui client faucet --url https://faucet.testnet.sui.io/v1/gas +``` + +After some seconds, running again `sui client gas` should show the newly-minted coins in your +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](https://github.com/MystenLabs/blocksite-poc). (TODO: change link to public repo when available). +``` bash +git clone git@github.com:MystenLabs/blocksite-poc.git +cd blocksite-poc +cd site-builder +``` + +Build the release version of the site builder. +``` bash +cargo build --release +``` + +After the build process completes, it should be possible to run: +``` +./target/release/site-builder +``` +And output should look like the following: +``` +Usage: site-builder [OPTIONS] + +Commands: + publish Publish a new site on Sui + update Update an existing site + convert Convert an object ID in hex format to the equivalent Base36 + format + sitemap Show the pages composing the Walrus site at the given object ID + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config + The path to the configuration file for the site builder [default: + config.yaml] + --rpc-url + The URL or the RPC enpoint to connect the client to + --wallet + The path to the Sui Wallet config + --walrus-binary + The path or name of the walrus binary + --walrus-config + The path to the configuration for the Walrus client + -g, --gas-budget + The gas budget for the operations on Sui + --gas-coin + The gas coin to be used + -h, --help + Print help (see more with '--help') +``` + +## Get the latest `walrus` client configuration + +TODO: get it from the gcp bucket and copy it to the site builder directory diff --git a/docs/walrus-sites/tutorial-suins.md b/docs/walrus-sites/tutorial-suins.md new file mode 100644 index 00000000..4a371fef --- /dev/null +++ b/docs/walrus-sites/tutorial-suins.md @@ -0,0 +1 @@ +# Bonus: Set a SuiNS name diff --git a/docs/walrus-sites/tutorial-use.md b/docs/walrus-sites/tutorial-use.md new file mode 100644 index 00000000..9b0f13c1 --- /dev/null +++ b/docs/walrus-sites/tutorial-use.md @@ -0,0 +1 @@ +# Using the site builder diff --git a/docs/walrus-sites/tutorial.md b/docs/walrus-sites/tutorial.md new file mode 100644 index 00000000..de258b72 --- /dev/null +++ b/docs/walrus-sites/tutorial.md @@ -0,0 +1,4 @@ +# Your first Walrus Site + +This tutorial walks you through the steps necessary to publish a Walrus Site. We also provide the +instructions on how to add a SuiNS name to it for convenient browsing.