Skip to content

Commit

Permalink
docs: update walrus sites references and addresses
Browse files Browse the repository at this point in the history
Signed-off-by: giac-mysten <giacomo@mystenlabs.com>
  • Loading branch information
giac-mysten committed Oct 17, 2024
1 parent 90ef27d commit b58cf28
Show file tree
Hide file tree
Showing 7 changed files with 51 additions and 91 deletions.
6 changes: 3 additions & 3 deletions docs/walrus-sites/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,11 @@ and has special characteristics (the background color, the image, ...) that are
contents of the NFT.

The URL to this per-NFT site looks something like this:
`https://4egmmrw9izzjn0dm2lkd3k0l8phk386z60ub1tpdc1jswbb5dr.walrus.site/`. You'll notice that the
`https://2hzpawjycxuiuh36047yocxapc69g8ercrypa7ccsk8ek4iqu6.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).
[0x644bc958...](https://suiscan.xyz/testnet/object/0x644bc958052463785c026a13be051d579c8a4d2dc93b1874dce5839d4fb18c5e).

In summary:

Expand All @@ -70,7 +70,7 @@ In summary:
- 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.
- the Base36 encoding of a the Sui object ID, such as `0x644bc958...` 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 trying Walrus Sites out, check the [tutorial](./tutorial.md).
2 changes: 1 addition & 1 deletion docs/walrus-sites/linking.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Here is the part that is a bit different. Assume there is some image that you ca

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
from any other portal (e.g., `https://gallery.blob.store/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.

Expand Down
4 changes: 2 additions & 2 deletions docs/walrus-sites/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ This struct just holds the string of the path (`/index.html`); having a separate
we will not have namespace collisions with other dynamic fields, possibly added by other packages.

To see this in action, look at [a Walrus Site in the
explorer](https://suiscan.xyz/testnet/object/0x049b6d3f34789904efcc20254400b7dca5548ee35cd7b5b145a211f85b2532fa),
explorer](https://suiscan.xyz/testnet/object/0xd20b90149409ba5d005d4a2cd981db9494bc3cdb2f04c47ca1af98dd8f71610a),
and check its dynamic fields.

### The site rendering path
Expand Down Expand Up @@ -86,7 +86,7 @@ uniquely associated to the object ID of the Walrus Site through SuiNS.

Walrus Sites also work without SuiNS: a site can *always* be browsed by using as subdomain the
Base36 encoding of the Sui object ID of the site. For the Flatland dApp, this URL is:
<https://44terjw9uzwbmtful0387e2bx3k3ro64s0it82hw9x9sz4ttm.walrus.site>.
<https://58gr4pinoayuijgdixud23441t55jd94ugep68fsm72b8mwmq2.walrus.site>.

Base36 was chosen for two reasons, forced by the subdomain standards:

Expand Down
5 changes: 4 additions & 1 deletion docs/walrus-sites/redirects.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ display.add(b"walrus site address".to_string(), VISUALIZATION_SITE.to_string());
...
```

### How to personalize based on the NFT?
### How to change the site 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?
Expand All @@ -39,3 +39,6 @@ This needs to be done in the `VISUALIZATION_SITE`: Since the subdomain is still
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.

For an end-to-end example, see the `flatland`
[repo](https://github.com/MystenLabs/example-walrus-sites/tree/main/flatland).
5 changes: 5 additions & 0 deletions docs/walrus-sites/tutorial-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@ The migration will result in a new Site object on Sui (with a different object I
objects on Walrus Testnet.
```

``` admonish danger title="New default configuration path"
The default configuration file for the `site-builder` has been moved to the `./sites-config.yaml`
instead of the old `./site-builder/assets/builder-example.yaml`.
```

The steps are the following:

- Get the latest version of the `walrus` binary, as well as the latest Walrus configuration file,
Expand Down
57 changes: 35 additions & 22 deletions docs/walrus-sites/tutorial-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,44 @@ Since we have placed the `walrus` binary and configuration in their default loca
the `./examples/snake` site is as simple as calling the publishing command:

``` sh
./target/release/site-builder --config site-builder/assets/builder-example.yaml publish ./examples/snake
./target/release/site-builder publish ./examples/snake --epochs 100
```

The output should look like the following:
``` admonish tip
Currently on Walrus testnet, the duration of an epoch is 1 day. If you want your site to stay up
longer, specify the number of epochs with the `--epochs` flag!
```

```admonish note
The site builder will look for the default configuration file `sites-config.yaml` in the
`./walrus-sites` directory. In case you are calling the `site-builder` command from a different
location, use the `--config` flag to specify the path to the configuration file.
```

The end of 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 SSzbpPfO2Tqk6xNyF1i-NG9I9CjUjuWnhUATVSs5nic
- created resource /walrus.png with blob ID SGrrw5NQyFWtqtxzLAQ1tLpcChGc0VNbtFRhfsQPuiM
Execution completed
Resource operations performed:
- created resource /Oi-Regular.ttf with blob ID 76npyqDyGF10-jP_ov-UBHpi-RaRFnxcWgslueGEfr0
- created resource /file.svg with blob ID w70pYgtLmi--38Jg1sTGaLlZkQtximNMHXjxDQdXKa0
- created resource /index.html with blob ID LVLk9VSnBrEgQ2HJHAgU3p8IarKypQpfn38aSeUZzzE
- created resource /walrus.svg with blob ID 866UDjMAy_BB8SsTcgjGEOFp2uAO9BbcVbLh5-_oBNE
The site routes were modified
Created new site: test site
New site object ID: 0x5ac988828a0c9842d91e6d5bdd9552ec9fcdddf11c56bf82dff6d5566685a31e
Browse the resulting site at: https://29gjzk8yjl1v7zm2etee1siyzaqfj9jaru5ufs6yyh1yqsgun2.walrus.site
New site object ID: 0x407a308190eb82b266be9cc28b888d04c5b2e5a503c7d0ffd3f69681ea83b73a
Browse the resulting site at: https://1lupgq2auevjruy7hs9z7tskqwjp5cc8c5ebhci4v57qyl4piy.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.
Note here that we are passing the default config `./sites-config.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](./builder-config.md) section.
Expand All @@ -57,22 +69,23 @@ First, make this edit on in the `./examples/snake/index.html` file.

Then, you can update the existing site by running the `update` command, providing the directory
where to find the updated files (still `./example/snake`) and the object ID of the existing site
(`0x5ac988...`):
(`0x407a3081...`):

``` sh
./target/release/site-builder --config site-builder/assets/builder-example.yaml update ./examples/snake 0x5ac9888...
./target/release/site-builder update --epochs 100 examples/snake 0x407a3081...
```

The output this time should be:

``` txt
Operations performed:
- deleted resource /index.html with blob ID SSzbpPfO2Tqk6xNyF1i-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
Execution completed
Resource operations performed:
- deleted resource /index.html with blob ID LVLk9VSnBrEgQ2HJHAgU3p8IarKypQpfn38aSeUZzzE
- created resource /index.html with blob ID pcZaosgEFtmP2d2IV3QdVhnUjajvQzY2ev8d9U_D5VY
The site routes were left unchanged
Site object ID: 0x407a308190eb82b266be9cc28b888d04c5b2e5a503c7d0ffd3f69681ea83b73a
Browse the resulting site at: https://1lupgq2auevjruy7hs9z7tskqwjp5cc8c5ebhci4v57qyl4piy.walrus.site
```

Compared to the `publish` action, we can see that now the only actions performed were to delete the
Expand Down
63 changes: 1 addition & 62 deletions docs/walrus-sites/tutorial-suins.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Bonus: Set a SuiNS name

Browsing a URL like `https://29gjzk8yjl1v7zm2etee1siyzaqfj9jaru5ufs6yyh1yqsgun2.walrus.site` is not
Browsing a URL like `https://1lupgq2auevjruy7hs9z7tskqwjp5cc8c5ebhci4v57qyl4piy.walrus.site` is not
particularly nice. Therefore, Walrus Sites allows to use SuiNS names (this is like DNS for Sui) to
assign a human-readable name to a Walrus 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`
Expand All @@ -26,64 +26,3 @@ the "three dots" menu icon above the name you want to map, and click "Link To Wa
in the bar the object ID of the Walrus Site, check that it is correct, and click "Apply".

After approving the transaction, we can now browse <https://walrusgame.walrus.site>!

---

## The CLI way

For completeness, we report here a manual way of setting the mapping between the SuiNS name and the
Walrus Site, using the CLI.

### Get the SuiNS object ID

Go to the ["names you own"](https://testnet.suins.io/account/my-names) section of the SuiNS website,
click the three-dots menu on the top-right corner of the name, choose "View all info", and copy the
`ObjectID`. In our case, this is `0x6412...`.

### Send the SuiNS registration object to the address you use with the Sui CLI

The steps that follow require that the SuiNS registration object is owned by the address you are
using on the Sui CLI. Therefore, unless you use the same address in your browser wallet and the CLI,
we need to send this registration object from the address you use in your browser wallet to the
address of your Sui CLI.

To find the Sui CLI address, execute:

``` sh
sui client active-address
```

Then, from your browser wallet, select the "Assets" tab and look for the NFT of the SuiNS
registration, which should look as follows:
![the SuiNS registration inside the wallet](../assets/suins-asset.png)

Click on it, scroll down to "Send NFT", and send it to the address discovered with the command
above. Now, your Sui CLI address owns the registration NFT, and you can proceed to the next step.

### Use the CLI to 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, one is to issue the following transaction using the Sui CLI to create
this mapping:

```sh
SUINS_UTILS_PACKAGE=0x7954ae683314ec7e156acbf0c0fc964ce035fd7f456fe7576848226502cfde1b
SUINS_CORE_OBJECT=0x300369e8909b9a6464da265b9a5a9ab6fe2158a040e84e808628cde7a07ee5a3
MY_SUINS_REGISTRATION_OBJECT=0x6412... # adjust this to your own SuiNS object
MY_WALRUS_SITE_OBJECT=0x5ac9... # adjust this to your Walrus Site object
sui client call \
--package $SUINS_UTILS_PACKAGE \
--module direct_setup \
--function set_target_address \
--gas-budget 500000000 \
--args $SUINS_CORE_OBJECT \
--args $MY_SUINS_REGISTRATION_OBJECT \
--args "[$MY_WALRUS_SITE_OBJECT]" \
--args 0x6
```

```admonish note
Note that the SuiNS package and object on Testnet may change. You can find the latest ones by
looking at the `TESTNET_CONFIG` in the [SuiNS
contract](https://github.com/MystenLabs/suins-contracts/blob/main/sdk/src/constants.ts).
```

0 comments on commit b58cf28

Please sign in to comment.