docs: minor cleanup (#75)

MystenLabs · Jun 18, 2024 · 30b3106 · 30b3106
1 parent 11b6ac7
commit 30b3106
Show file tree

Hide file tree

Showing 14 changed files with 49 additions and 40 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -43,7 +43,7 @@ storage node management and blob certification leverages Sui smart contracts.
 
 This documentation is split into three parts:
 
-1. _About Walrus_ describes the objectives, security properties, and architecture of Walrus.
+1. _Design_ describes the objectives, security properties, and architecture of Walrus.
 1. _Usage_ provides concrete information for developers. If you want to get started quickly, you can
    jump directly to the [setup chapter](./usage/setup.md).
 1. _Walrus sites_ describes how you can use Walrus and Sui together to build truly decentralized

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -14,15 +14,15 @@
 
 # Design
 
-- [Objectives and use-cases](./overview/objectives_use_cases.md)
-- [Overview](./overview/overview.md)
-  - [Architecture](./overview/architecture.md)
-  - [Encoding](./overview/encoding.md)
-- [Operations](./overview/operations.md)
-  - [Sui operations](./overview/operations-sui.md)
-  - [Off-chain operations](./overview/operations-off-chain.md)
-- [Properties](./overview/properties.md)
-- [Future discussion](./overview/future.md)
+- [Objectives and use-cases](./design/objectives_use_cases.md)
+- [Overview](./design/overview.md)
+  - [Architecture](./design/architecture.md)
+  - [Encoding](./design/encoding.md)
+- [Operations](./design/operations.md)
+  - [Sui operations](./design/operations-sui.md)
+  - [Off-chain operations](./design/operations-off-chain.md)
+- [Properties](./design/properties.md)
+- [Future discussion](./design/future.md)
 
 # Usage
 

diff --git a/docs/overview/architecture.md → docs/design/architecture.md b/docs/overview/architecture.md → docs/design/architecture.md
diff --git a/docs/overview/encoding.md → docs/design/encoding.md b/docs/overview/encoding.md → docs/design/encoding.md
diff --git a/docs/overview/future.md → docs/design/future.md b/docs/overview/future.md → docs/design/future.md
diff --git a/docs/overview/objectives_use_cases.md → docs/design/objectives_use_cases.md b/docs/overview/objectives_use_cases.md → docs/design/objectives_use_cases.md
diff --git a/docs/overview/operations-off-chain.md → docs/design/operations-off-chain.md b/docs/overview/operations-off-chain.md → docs/design/operations-off-chain.md
diff --git a/docs/overview/operations-sui.md → docs/design/operations-sui.md b/docs/overview/operations-sui.md → docs/design/operations-sui.md
diff --git a/docs/overview/operations.md → docs/design/operations.md b/docs/overview/operations.md → docs/design/operations.md
diff --git a/docs/overview/overview.md → docs/design/overview.md b/docs/overview/overview.md → docs/design/overview.md
diff --git a/docs/overview/properties.md → docs/design/properties.md b/docs/overview/properties.md → docs/design/properties.md
diff --git a/docs/dev-guide/dev-guide.md b/docs/dev-guide/dev-guide.md
@@ -1,7 +1,7 @@
 # Developer Guide
 
 This guide introduces all the concepts needed to build applications that use Walrus as a storage
-or availability layer. The [overview](../overview/overview.md) provides more background and explains
+or availability layer. The [overview](../design/overview.md) provides more background and explains
 in more detail how Walrus operates internally.
 
 This developer guide describes:

diff --git a/docs/dev-guide/dev-operations.md b/docs/dev-guide/dev-operations.md
@@ -2,7 +2,7 @@
 
 ## Blob encoding and blob ID
 
-Walrus stores blobs across storage nodes in an [encoded form](../overview/encoding.md), and refers
+Walrus stores blobs across storage nodes in an [encoded form](../design/encoding.md), and refers
 to blobs by their _blob ID_. The blob ID is deterministically derived from the content of a blob
 and the Walrus configuration. The blob ID of two files with the same content will be the same.
 

diff --git a/docs/usage/web-api.md b/docs/usage/web-api.md
@@ -53,37 +53,48 @@ authentication and compensation for the Sui used.
 
 ## HTTP API Usage
 
+For the following examples, we assume you set the `AGGREGATOR` and `PUBLISHER` environment variables
+to your desired aggregator and publisher, respectively. For example:
+
+```sh
+AGGREGATOR=https://aggregator-devnet.walrus.space
+PUBLISHER=https://publisher-devnet.walrus.space
+```
+
 ### Store
 
 You can interact with the daemon through simple HTTP PUT requests. For example, with
 [cURL](https://curl.se), you can store blobs using a publisher or daemon as follows:
 
 ```sh
-ADDRESS="127.0.0.1:31415"
-curl -X PUT "http://$ADDRESS/v1/store" -d "some string" # store the string `some string` for 1 storage epoch
-curl -X PUT "http://$ADDRESS/v1/store?epochs=5" --upload-file "some/file" # store file `some/file` for 5 storage epochs
+curl -X PUT "$PUBLISHER/v1/store" -d "some string" # store the string `some string` for 1 storage epoch
+curl -X PUT "$PUBLISHER/v1/store?epochs=5" --upload-file "some/file" # store file `some/file` for 5 storage epochs
 ```
 
 The store HTTP API end points return information about the blob stored in JSON format. When a blob
 is stored for the first time, a `newlyCreated` field contains information about the
 new blob:
 
 ```sh
-$ curl -X PUT "http://ord-dnt-sto-00.devnet.sui.io:9000/v1/store" -d "some other string"
+$ curl -X PUT "$PUBLISHER/v1/store" -d "some other string"
 {
-  "newlyCreated":{
-    "id":"0xa74d376bb6923c4b8d73825fce3b798524e2bda34d02dae64ab5865556c54000",
-    "storedEpoch":0,
-    "blobId":"gsYzDXsK326Wihzt3X5evZCPFgaNZrb84zCjodLJaVs",
-    "size":36,
-    "erasureCodeType":"RedStuff",
-    "certified":0,
-    "storage":{
-        "id":"0x2479b3096efa58fa9bfbebe805268746c235110ee0713e5a123d8f1754c2ccc3",
-        "startEpoch":0,
-        "endEpoch":1,
-        "storageSize":4747680
-    }
+  "newlyCreated": {
+    "blobObject": {
+      "id": "0xd765d11848cbac5b1f6eec2fbeb343d4558cbe8a484a00587f9ef5385d64d235",
+      "storedEpoch": 0,
+      "blobId": "Cmh2LQEGJwBYfmIC8duzK8FUE2UipCCrshAYjiUheZM",
+      "size": 17,
+      "erasureCodeType": "RedStuff",
+      "certifiedEpoch": 0,
+      "storage": {
+        "id": "0x28cc75b33e31b3e672646eacf1a7c7a2e5d638644651beddf7ed4c7e21e9cb8e",
+        "startEpoch": 0,
+        "endEpoch": 1,
+        "storageSize": 4747680
+      }
+    },
+    "encodedSize": 4747680,
+    "cost": 231850
   }
 }
 ```
@@ -94,15 +105,15 @@ When the aggregator finds a certified blob with the same blob ID and a sufficien
 it returns a `alreadyCertified` JSON structure:
 
 ```sh
-$ curl -X PUT "http://ord-dnt-sto-00.devnet.sui.io:9000/v1/store" -d "some other string"
+$ curl -X PUT "$PUBLISHER/v1/store" -d "some other string"
 {
-  "alreadyCertified":{
-    "blobId":"gsYzDXsK326Wihzt3X5evZCPFgaNZrb84zCjodLJaVs",
-    "event":{
-      "txDigest":"2oMC1dTaMGpApphFWKzARSsTM9837ox4zN8rY2RqLf6c",
-      "eventSeq":"0"
+  "alreadyCertified": {
+    "blobId": "Cmh2LQEGJwBYfmIC8duzK8FUE2UipCCrshAYjiUheZM",
+    "event": {
+      "txDigest": "CLE41JTPR2CgZRC1gyKK6P3xpQRHCetQMsmtEgqGjwst",
+      "eventSeq": "0"
     },
-    "endEpoch":1
+    "endEpoch": 1
   }
 }
 ```
@@ -116,15 +127,13 @@ Blobs may be read from an aggregator or daemon using HTTP GET. For example the f
 command reads a blob and writes it to an output file:
 
 ```sh
-ADDRESS="127.0.0.1:31415"
-curl "http://$ADDRESS/v1/<some blob ID> -o <some file name>"
+curl "$AGGREGATOR/v1/<some blob ID> -o <some file name>"
 ```
 
 Alternatively you may print the contents of a blob in the terminal with the cURL command:
 
 ```sh
-ADDRESS="127.0.0.1:31415"
-curl "http://$ADDRESS/v1/<some blob ID>
+curl "$AGGREGATOR/v1/<some blob ID>
 ```
 
 Modern browsers will attempt to sniff the content type for such resources, and will generally do a