From 08d71a52be063f944b7fcce34b1da9e9355b374b Mon Sep 17 00:00:00 2001 From: George Danezis <4999882+gdanezis@users.noreply.github.com> Date: Thu, 16 Jan 2025 17:03:13 +0000 Subject: [PATCH] docs: A few edits (#206) --- docs/blog/05_testnet_redeployment.md | 37 ++++++++++++++++------------ docs/usage/client-cli.md | 19 +++++++------- 2 files changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/blog/05_testnet_redeployment.md b/docs/blog/05_testnet_redeployment.md index 32bb47a..a74a124 100644 --- a/docs/blog/05_testnet_redeployment.md +++ b/docs/blog/05_testnet_redeployment.md @@ -2,23 +2,27 @@ Published on: 2025-01-16 -We have reached a stage in development where it is beneficial to redeploy the Walrus Testnet to -incorporate various improvements that include some backwards-incompatible changes. This redeployment -has happened on 2025-01-16. Make sure to get the latest binary and configuration as described in the -[setup section](../usage/setup.md). -Note that all data on the previous Testnet instance has been wiped. All blobs need to be re-uploaded -to the new Testnet instance, including Walrus Sites. In addition, there is a new version of the WAL -token, so your previous WAL tokens will not work anymore. To use the Testnet v2, you need to obtain -new WAL tokens. In the following sections, we describe the notable changes and the actions required -for existing Walrus Sites. - -## Epochs +We are today redeploying the Walrus Testnet to incorporate various improvements, including some +backwards-incompatible changes. Make sure to get the latest binary and configuration as described +in the [setup section](../usage/setup.md). + +Note that all blob data on the previous Testnet instance has been wiped. All blobs need to be +re-uploaded to the new Testnet instance, including Walrus Sites. In addition, there is a new version +of the WAL token, so your previous WAL tokens will not work anymore. To use the Testnet v2, you +need to obtain new WAL tokens. + +In the following sections, we describe the notable changes and the actions required for existing +Walrus Sites. + +## Epoch duration The epoch duration has been increased from one day to two days to emphasize that this duration is different from Sui epochs (at Mainnet, epochs will likely be multiple weeks long). In addition, the maximum number of epochs a blob can be stored for has been reduced from 200 to 183 (corresponding -to one year). The `walrus store` command now also supports the `--epochs max` flag, which will store -the blob for the maximum number of epochs. +to one year). + +The `walrus store` command now also supports the `--epochs max` flag, which will store +the blob for the maximum number of epochs. Note that the `--epochs` flag is now mandatory. ## New features @@ -31,12 +35,13 @@ also brings several user-facing improvements. with glob patterns offered by many shells, so you can for example run a command like `walrus store *.png --epochs 100` to store all PNG files in the current directory. - The `walrus` CLI now supports creating, funding, and extending *shared blobs* using the `walrus - share`, `walrus store --share`, and `walrus fund-shared-blob` commands. See the [shared blobs + share`, `walrus store --share`, and `walrus fund-shared-blob` commands. Shared blobs are an + example of collectively managed and funded blobs. See the [shared blobs section](../usage/client-cli.md#shared-blobs) for more details. ## New WAL token -Along with the redeployment of Walrus, we have also deployed a new version of the WAL contract. This +Along with the redeployment of Walrus, we have also deployed a fresh WAL contract. This means that you cannot use any WAL token from the previous Testnet instance with the new Testnet instance. You need to request new WAL tokens through the [Testnet WAL faucet](../usage/setup.md#testnet-wal-faucet). @@ -64,7 +69,7 @@ Please refer to the CLI help (`walrus --help`, or `walrus --help`) for ### HTTP APIs -The paths, request, and response formats of the HTTP APIs have changed for the storage nodes but +The paths, request, and response formats of the HTTP APIs have changed for the storage nodes, and also the aggregator and publisher. Please refer to the section on the [HTTP API](../usage/web-api.md) for further details. diff --git a/docs/usage/client-cli.md b/docs/usage/client-cli.md index e016c75..598cf1f 100644 --- a/docs/usage/client-cli.md +++ b/docs/usage/client-cli.md @@ -71,7 +71,7 @@ confidentiality. ```admonish warning It must be ensured that only a single process uses the Sui wallet for write actions (storing or deleting). When using multiple instances of the client simultaneously, each of them must be pointed -to a different wallet. However, it is possible to store multiple blobs with a single `walrus store` +to a different wallet. Note, it is possible to store multiple blobs with a single `walrus store` command. ``` @@ -100,7 +100,6 @@ blobs](#reclaiming-space-via-deletable-blobs) for more details on deletable blob an owned `Blob` object is created. It is possible to wrap this into a shared object, which can be funded and extended by anyone, see the [shared blobs section](#shared-blobs). -```admonish tip title="Automatic optimizations" When storing a blob, the client performs a number of automatic optimizations, including the following: @@ -108,12 +107,11 @@ following: the command does not store it again. This behavior can be overwritten with the `--force` CLI option, which stores the blob again and creates a fresh blob object on Sui belonging to the wallet address. -- If the user's wallet has a compatible storage resource, this one is (re-)used instead of buying a - new one. +- If the user's wallet has a storage resource of suitable size and duration, it is (re-)used instead + of buying a new one. - If the blob is already certified on Walrus but as a *deletable* blob or not for a sufficient - number of epochs, the command skips sending data to the storage nodes and just collects the - availability certificate -``` + number of epochs, the command skips sending encoded blob data to the storage nodes and just + collects the availability certificate ## Querying blob status @@ -146,7 +144,7 @@ a Sui RPC node to use instead of the one set in the wallet configuration or the ## Reclaiming space via deletable blobs -By default `walrus store` uploads a blob and Walrus will keep it available until after its expiry +By default `walrus store` uploads a permanent blob available until after its expiry epoch. Not even the uploader may delete it beforehand. However, optionally, the store command may be invoked with the `--deletable` flag, to indicate the blob may be deleted before its expiry by the owner of the Sui blob object representing the blob. Deletable blobs are indicated as such @@ -197,10 +195,11 @@ walrus share --blob-obj-id ``` The resulting shared blob can be directly funded by adding an `--amount`, or you can fund an -existing shared blob with the `walrus fund-shared-blob` command.Additionally, you can immediately +existing shared blob with the `walrus fund-shared-blob` command. Additionally, you can immediately share a newly created blob by adding the `--share` option to the `walrus store` command. -You can use the `walrus extend` command to extend the lifetime of a shared blob object. +You can use the `walrus extend` command to extend the lifetime of a shared blob object. Shared blobs +can only contain permanent blobs and cannot be deleted before their expiry. ## Blob ID utilities