diff --git a/README.md b/README.md
index 508cb7546f..f490503299 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,8 @@
[SafenetForum.org](https://safenetforum.org/)
Own your data. Share your disk space. Get paid for doing so.
-The Data on the Safe Network is Decentralised, Autonomous, and built atop of Kademlia and Libp2p.
+The Data on the Safe Network is Decentralised, Autonomous, and built atop of Kademlia and
+Libp2p.
## Table of Contents
@@ -15,20 +16,29 @@ The Data on the Safe Network is Decentralised, Autonomous, and built atop of Kad
### For Users
-- [CLI](https://github.com/maidsafe/safe_network/blob/main/sn_cli/README.md) The Command Line Interface, allowing users to interact with the network from their terminal.
-- [Node](https://github.com/maidsafe//safe_network/blob/main/sn_node/README.md) The backbone of the safe network. Nodes can be run on commodity hardware and provide storage space and validation of transactions to the network.
+- [CLI](https://github.com/maidsafe/safe_network/blob/main/sn_cli/README.md) The Command Line
+ Interface, allowing users to interact with the network from their terminal.
+- [Node](https://github.com/maidsafe//safe_network/blob/main/sn_node/README.md) The backbone of the
+ safe network. Nodes can be run on commodity hardware and provide storage space and validation of
+ transactions to the network.
### For Developers
-- [Client](https://github.com/maidsafe/safe_network/blob/main/sn_client/README.md) The client APIs allowing use of the SafeNetwork to users and developers.
-- [Registers](https://github.com/maidsafe/safe_network/blob/main/sn_registers/README.md) The CRDT registers structures available on the network.
-- [Node Manager](https://github.com/maidsafe/safe_network/blob/main/sn_node_manager/README.md) Use to create a local network for development and testing.
-- [Faucet](https://github.com/maidsafe/safe_network/blob/main/sn_faucet/README.md) The local faucet server, used to claim genesis and request tokens from the network.
-- [Node RPC](https://github.com/maidsafe/safe_network/blob/main/sn_node_rpc_client/README.md) The RPC server used by the nodes to expose API calls to the outside world.
+- [Client](https://github.com/maidsafe/safe_network/blob/main/sn_client/README.md) The client APIs
+ allowing use of the SafeNetwork to users and developers.
+- [Registers](https://github.com/maidsafe/safe_network/blob/main/sn_registers/README.md) The CRDT
+ registers structures available on the network.
+- [Node Manager](https://github.com/maidsafe/safe_network/blob/main/sn_node_manager/README.md) Use
+ to create a local network for development and testing.
+- [Faucet](https://github.com/maidsafe/safe_network/blob/main/sn_faucet/README.md) The local faucet
+ server, used to claim genesis and request tokens from the network.
+- [Node RPC](https://github.com/maidsafe/safe_network/blob/main/sn_node_rpc_client/README.md) The
+ RPC server used by the nodes to expose API calls to the outside world.
#### Releases
-` ./resources/scripts/bump_version.sh` will bump the version of the crates in the `Cargo.toml` files. And generate a `chore(release):` commit, which if pushed
+` ./resources/scripts/bump_version.sh` will bump the version of the crates in the `Cargo.toml`
+files. And generate a `chore(release):` commit, which if pushed
to main will result in CI doing a full release run.
` ./resources/scripts/bump_version.sh` can also be namespaced for other release
@@ -39,9 +49,12 @@ a `beta` release on any changed crates.
The Safe Network uses `quic` as the default transport protocol.
-The `websockets` feature is available for the `sn_networking` crate, and above, and will allow for tcp over websockets.
+The `websockets` feature is available for the `sn_networking` crate, and above, and will allow for
+tcp over websockets.
-If building for `wasm32` then `websockets` are enabled by default as this is the only method avilable to communicate with a network as things stand. (And that network must have `websockets` enabled.)
+If building for `wasm32` then `websockets` are enabled by default as this is the only method
+avilable to communicate with a network as things stand. (And that network must have `websockets`
+enabled.)
##### Building for wasm32
@@ -54,23 +67,32 @@ eg `await safe.get_data("/ip4/127.0.0.1/tcp/59324/ws/p2p/12D3KooWG6kyBwLVHj5hYK2
#### Browser usage
-Browser usage is highly experimental, but the wasm32 target for `sn_client` _should_ work here. YMMV until stabilised.
+Browser usage is highly experimental, but the wasm32 target for `sn_client` _should_ work here.
+YMMV until stabilised.
### For the Technical
-- [Logging](https://github.com/maidsafe/safe_network/blob/main/sn_logging/README.md) The generalised logging crate used by the safe network (backed by the tracing crate).
-- [Metrics](https://github.com/maidsafe/safe_network/blob/main/metrics/README.md) The metrics crate used by the safe network.
-- [Networking](https://github.com/maidsafe/safe_network/blob/main/sn_networking/README.md) The networking layer, built atop libp2p which allows nodes and clients to communicate.
-- [Protocol](https://github.com/maidsafe/safe_network/blob/main/sn_protocol/README.md) The protocol used by the safe network.
-- [Transfers](https://github.com/maidsafe/safe_network/blob/main/sn_transfers/README.md) The transfers crate, used to send and receive tokens on the network.
-- [Peers Acquisition](https://github.com/maidsafe/safe_network/blob/main/sn_peers_acquisition/README.md) The peers peers acqisition crate, or: how the network layer discovers bootstrap peers.
-- [Build Info](https://github.com/maidsafe/safe_network/blob/main/sn_build_info/README.md) Small helper used to get the build/commit versioning info for debug purposes.
+- [Logging](https://github.com/maidsafe/safe_network/blob/main/sn_logging/README.md) The
+ generalised logging crate used by the safe network (backed by the tracing crate).
+- [Metrics](https://github.com/maidsafe/safe_network/blob/main/metrics/README.md) The metrics crate
+ used by the safe network.
+- [Networking](https://github.com/maidsafe/safe_network/blob/main/sn_networking/README.md) The
+ networking layer, built atop libp2p which allows nodes and clients to communicate.
+- [Protocol](https://github.com/maidsafe/safe_network/blob/main/sn_protocol/README.md) The protocol
+ used by the safe network.
+- [Transfers](https://github.com/maidsafe/safe_network/blob/main/sn_transfers/README.md) The
+ transfers crate, used to send and receive tokens on the network.
+- [Peers Acquisition](https://github.com/maidsafe/safe_network/blob/main/sn_peers_acquisition/README.md)
+ The peers peers acqisition crate, or: how the network layer discovers bootstrap peers.
+- [Build Info](https://github.com/maidsafe/safe_network/blob/main/sn_build_info/README.md) Small
+ helper used to get the build/commit versioning info for debug purposes.
## Using a Local Network
We can explore the network's features by using multiple node processes to form a local network.
-The latest version of [Rust](https://www.rust-lang.org/learn/get-started) should be installed. If you already have an installation, use `rustup update` to get the latest version.
+The latest version of [Rust](https://www.rust-lang.org/learn/get-started) should be installed. If
+you already have an installation, use `rustup update` to get the latest version.
Run all the commands from the root of this repository.
@@ -81,7 +103,7 @@ Follow these steps to create a local network:
1. Create the test network:
```bash
-cargo run --bin safenode-manager --features local-discovery -- run --build
+cargo run --bin safenode-manager --features local-discovery -- local run --build
```
2. Verify node status:
@@ -96,11 +118,14 @@ cargo run --bin safenode-manager --features local-discovery -- status
cargo run --bin safe --features local-discovery -- wallet get-faucet 127.0.0.1:8000
```
-The node manager's `run` command starts the node processes and a faucet process, the latter of which will dispense tokens for use with the network. The `status` command should show twenty-five running nodes. The `wallet` command retrieves some tokens, which enables file uploads.
+The node manager's `run` command starts the node processes and a faucet process, the latter of
+which will dispense tokens for use with the network. The `status` command should show twenty-five
+running nodes. The `wallet` command retrieves some tokens, which enables file uploads.
### Files
-The file storage capability can be demonstrated by uploading files to the local network, then retrieving them.
+The file storage capability can be demonstrated by uploading files to the local network, then
+retrieving them.
Upload a file or a directory:
@@ -118,32 +143,45 @@ cargo run --bin safe --features local-discovery -- files download
### Folders
-The folders storage capability can be demonstrated by storing folders on the network, making changes and syncing them with the stored version on the network, as well as downloading the entire folders hierarchy onto a local directory.
+The folders storage capability can be demonstrated by storing folders on the network, making
+changes and syncing them with the stored version on the network, as well as downloading the entire
+folders hierarchy onto a local directory.
-All the following commands act on the current directory by default, but since we are building the CLI binary to run it, we will have to always provide the directory we want them to act as a path argument.
-When otherwise running directly an already built CLI binary, we can simply make sure we are located at the directory we want to act on without the need of providing the path as argument.
+All the following commands act on the current directory by default, but since we are building the
+CLI binary to run it, we will have to always provide the directory we want them to act as a path
+argument.
+When otherwise running directly an already built CLI binary, we can simply make sure we are located
+at the directory we want to act on without the need of providing the path as argument.
-Initialise a directory to then be able to track changes made on it, and sync them up with the network:
+Initialise a directory to then be able to track changes made on it, and sync them up with the
+network:
```bash
cargo run --bin safe --features local-discovery -- folders init
```
-Make sure you made a backup copy of the "recovery secret" generated by the above command, or the one you have provided when prompted.
+Make sure you made a backup copy of the "recovery secret" generated by the above command, or the
+one you have provided when prompted.
-If any changes are now made to files or directories within this folder (at this point all files and folders are considered new since it has just been initalised for tracking), before trying to push those changes to the network, we can get a report of the changes that have been made locally:
+If any changes are now made to files or directories within this folder (at this point all files and
+folders are considered new since it has just been initalised for tracking), before trying to push
+those changes to the network, we can get a report of the changes that have been made locally:
```bash
cargo run --bin safe --features local-discovery -- folders status
```
-We can now push all local changes made to files and directories to the network, as well as pull any changes that could have been made to the version stored on the network since last time we synced with it:
+We can now push all local changes made to files and directories to the network, as well as pull any
+changes that could have been made to the version stored on the network since last time we synced
+with it:
```bash
cargo run --bin safe --features local-discovery -- folders sync
```
-Now that's all stored on the network, you can download the folders onto any other path by providing it as the target directory to the following command (you will be prompted to enter the "recovery secret" you obtained when initialising the directory with `init` command):
+Now that's all stored on the network, you can download the folders onto any other path by providing
+it as the target directory to the following command (you will be prompted to enter the "recovery
+secret" you obtained when initialising the directory with `init` command):
```bash
cargo run --bin safe --features local-discovery -- folders download
@@ -167,7 +205,8 @@ cargo run --bin safe --features local-discovery -- wallet send 2 [address]
This will output a transfer as a hex string, which should be sent to the recipient out-of-band.
-For demonstration purposes, copy the transfer string and use it to receive the transfer in your own wallet:
+For demonstration purposes, copy the transfer string and use it to receive the transfer in your own
+wallet:
```
cargo run --bin safe --features local-discovery -- wallet receive [transfer]
@@ -175,31 +214,39 @@ cargo run --bin safe --features local-discovery -- wallet receive [transfer]
#### Out of band transaction signing
-When you want to transfer tokens from a cold storage or hardware wallet, you can create and sign the transaction offline. This is done to prevent the private key from being exposed to any online threats.
-For this type of scenarios you can create a watch-only wallet (it holds only a public key) on the online device, while using a hot-wallet (which holds the secret key) on a device that is offline. The following steps are a simple guide for performing such an operation.
+When you want to transfer tokens from a cold storage or hardware wallet, you can create and sign
+the transaction offline. This is done to prevent the private key from being exposed to any online
+threats.
+For this type of scenarios you can create a watch-only wallet (it holds only a public key) on the
+online device, while using a hot-wallet (which holds the secret key) on a device that is offline.
+The following steps are a simple guide for performing such an operation.
Steps on the online device/computer with a watch-only wallet:
1. Create a watch-only wallet using the hex-encoded public key:
`cargo run --release --bin safe -- wowallet create `
-2. Deposit a cash-note, owned by the public key used above when creating, into the watch-only wallet:
+2. Deposit a cash-note, owned by the public key used above when creating, into the watch-only
+ wallet:
`cargo run --release --bin safe -- wowallet deposit --cash-note `
3. Build an unsigned transaction:
`cargo run --release --bin safe -- wowallet transaction `
-4. Copy the built unsigned Tx generated by the above command, and send it out-of-band to the desired device where the hot-wallet can be loaded.
+4. Copy the built unsigned Tx generated by the above command, and send it out-of-band to the
+ desired device where the hot-wallet can be loaded.
Steps on the offline device/computer with the corresponding hot-wallet:
-5. If you still don't have a hot-wallet created, which owns the cash-notes used to build the unsigned transaction, create it with the corresponding secret key:
+5. If you still don't have a hot-wallet created, which owns the cash-notes used to build the
+ unsigned transaction, create it with the corresponding secret key:
`cargo run --release --bin safe -- wallet create `
6. Use the hot-wallet to sign the built transaction:
`cargo run --release --bin safe -- wallet sign `
-7. Copy the signed Tx generated by the above command, and send it out-of-band back to the online device.
+7. Copy the signed Tx generated by the above command, and send it out-of-band back to the online
+ device.
Steps on the online device/computer with the watch-only wallet:
@@ -209,7 +256,8 @@ Steps on the online device/computer with the watch-only wallet:
9. Deposit the change cash-note to the watch-only wallet:
`cargo run --release --bin safe -- wowallet deposit `
-10. Send/share the output cash-note generated by the above command at step #8 to/with the recipient.
+10. Send/share the output cash-note generated by the above command at step #8 to/with the
+ recipient.
### Auditing
@@ -236,7 +284,9 @@ In the first terminal, using the registers example, Alice creates a register:
cargo run --example registers --features=local-discovery -- --user alice --reg-nickname myregister
```
-Alice can now write a message to the register and see anything written by anyone else. For example she might enter the text "hello, who's there?" which is written to the register and then shown as the "Latest value", in her terminal:
+Alice can now write a message to the register and see anything written by anyone else. For example
+she might enter the text "hello, who's there?" which is written to the register and then shown as
+the "Latest value", in her terminal:
```
Register address: "50f4c9d55aa1f4fc19149a86e023cd189e509519788b4ad8625a1ce62932d1938cf4242e029cada768e7af0123a98c25973804d84ad397ca65cb89d6580d04ff07e5b196ea86f882b925be6ade06fc8d"
@@ -264,15 +314,22 @@ Enter a blank line to receive updates, or some text to be written.
```
-For anyone else to write to the same register they need to know its xor address, so to communicate with her friend Bob, Alice needs to find a way to send it to Bob. In her terminal, this is the value starting "50f4..." in the output above. This value it will be different each time you run the example to create a register.
+For anyone else to write to the same register they need to know its xor address, so to communicate
+with her friend Bob, Alice needs to find a way to send it to Bob. In her terminal, this is the
+value starting "50f4..." in the output above. This value it will be different each time you run the
+example to create a register.
-Having received the xor address, in another terminal Bob can access the same register to see the message Alice has written, and he can write back by running this command with the address received from Alice. (Note that the command should all be on one line):
+Having received the xor address, in another terminal Bob can access the same register to see the
+message Alice has written, and he can write back by running this command with the address received
+from Alice. (Note that the command should all be on one line):
```
cargo run --example registers --features=local-discovery -- --user bob --reg-address 50f4c9d55aa1f4fc19149a86e023cd189e509519788b4ad8625a1ce62932d1938cf4242e029cada768e7af0123a98c25973804d84ad397ca65cb89d6580d04ff07e5b196ea86f882b925be6ade06fc8d
```
-After retrieving the register and displaying the message from Alice, Bob can reply and at any time, Alice or Bob can send another message and see any new messages which have been written, or enter a blank line to poll for updates.
+After retrieving the register and displaying the message from Alice, Bob can reply and at any time,
+Alice or Bob can send another message and see any new messages which have been written, or enter a
+blank line to poll for updates.
Here's Bob writing from his terminal:
@@ -290,7 +347,8 @@ Alice will see Bob's message when she either enters a blank line or writes anoth
### Inspect a Register
-A second example, `register_inspect` allows you to view its structure and content. To use this with the above example you again provide the address of the register. For example:
+A second example, `register_inspect` allows you to view its structure and content. To use this with
+the above example you again provide the address of the register. For example:
```
cargo run --example register_inspect --features=local-discovery -- --reg-address 50f4c9d55aa1f4fc19149a86e023cd189e509519788b4ad8625a1ce62932d1938cf4242e029cada768e7af0123a98c25973804d84ad397ca65cb89d6580d04ff07e5b196ea86f882b925be6ade06fc8d
@@ -328,7 +386,8 @@ where a node occurs more than once.
### RPC
-The node manager launches each node process with a remote procedure call (RPC) service. The workspace has a client binary that can be used to run commands against these services.
+The node manager launches each node process with a remote procedure call (RPC) service. The
+workspace has a client binary that can be used to run commands against these services.
Run the `status` command with the `--details` flag to get the RPC port for each node:
@@ -429,31 +488,42 @@ Listening to transfers notifications... (press Ctrl+C to exit)
Writing cash notes to: ./royalties-cash-notes
```
-Each received cash note is written to a file in the directory above, under another directory corresponding to the public address of the recipient.
+Each received cash note is written to a file in the directory above, under another directory
+corresponding to the public address of the recipient.
### Tear Down
When you're finished experimenting, tear down the network:
```
-cargo run --bin safenode-manager -- kill
+cargo run --bin safenode-manager -- local kill
```
## Metrics Dashboard
-Use the `open-metrics` feature flag on the node / client to start an [OpenMetrics](https://github.com/OpenObservability/OpenMetrics/) exporter. The metrics are served via a webserver started at a random port. Check the log file / stdout to find the webserver URL, `Metrics server on http://127.0.0.1:xxxx/metrics`
+Use the `open-metrics` feature flag on the node / client to start
+an [OpenMetrics](https://github.com/OpenObservability/OpenMetrics/) exporter. The metrics are
+served via a webserver started at a random port. Check the log file / stdout to find the webserver
+URL, `Metrics server on http://127.0.0.1:xxxx/metrics`
-The metrics can then be collected using a collector (for e.g. Prometheus) and the data can then be imported into any visualization tool (for e.g., Grafana) to be further analyzed. Refer to this [Guide](./metrics/README.md) to easily setup a dockerized Grafana dashboard to visualize the metrics.
+The metrics can then be collected using a collector (for e.g. Prometheus) and the data can then be
+imported into any visualization tool (for e.g., Grafana) to be further analyzed. Refer to
+this [Guide](./metrics/README.md) to easily setup a dockerized Grafana dashboard to visualize the
+metrics.
## Contributing
-Feel free to clone and modify this project. Pull requests are welcome.
You can also visit **[The MaidSafe Forum](https://safenetforum.org/)** for discussion or if you would like to join our online community.
+Feel free to clone and modify this project. Pull requests are welcome.
You can also visit *
+*[The MaidSafe Forum](https://safenetforum.org/)** for discussion or if you would like to join our
+online community.
### Pull Request Process
1. Please direct all pull requests to the `alpha` branch instead of the `main` branch.
-1. Ensure that your commit messages clearly describe the changes you have made and use the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+1. Ensure that your commit messages clearly describe the changes you have made and use
+ the [Conventional Commits](https://www.conventionalcommits.org/) specification.
## License
-This Safe Network repository is licensed under the General Public License (GPL), version 3 ([LICENSE](http://www.gnu.org/licenses/gpl-3.0.en.html)).
+This Safe Network repository is licensed under the General Public License (GPL), version
+3 ([LICENSE](http://www.gnu.org/licenses/gpl-3.0.en.html)).