docs: A few edits (#206)

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 <command> --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.
 

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,20 +100,18 @@ 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:
 
 - If the blob is already stored as a *permanent blob* on Walrus for a sufficient number of epochs
   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 <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