Merge pull request #1890 from nspcc-dev/more-documentation

More documentation

README.md

@@ -25,6 +25,8 @@ A complete toolkit for the NEO blockchain, including:
 - [Smart contract compiler](docs/compiler.md)
 - [NEO virtual machine](docs/vm.md)
 - [Smart contract examples](examples/README.md)
+- [Oracle service](docs/oracle.md)
+- [State validation service](docs/stateroots.md)
 
 This branch (**master**) is under active development now (read: won't work
 out of the box) and aims to be compatible with Neo 3. For the current stable

docs/consensus.md

@@ -54,8 +54,8 @@ place corresponding config named `protocol.privnet.yml` there.
 
 2. Edit configuration file for every node.
 Examples can be found at `config/protocol.privnet.docker.one.yml` (`two`, `three` etc.).
-    1. Note that it differs a bit from C# NEO node json config: our `UnlockWallet` contains
-       an encrypted WIF instead of the path to the wallet. 
+    1. Add `UnlockWallet` section with `Path` and `Password` strings for NEP-6
+       wallet path and password for the account to be used for consensus node.
     2. Make sure that your `MinPeers` setting is equal to
        the number of nodes participating in consensus.
        This requirement is needed for nodes to correctly

docs/oracle.md

@@ -0,0 +1,71 @@
+# NeoGo Oracle service
+
+NeoGo node can act as oracle service node for https and neofs protocols. It
+has to have a wallet with key belonging to one of network's designated oracle
+nodes (stored in `RoleManagement` native contract).
+
+It needs [RPC service](rpc.md) to be enabled and configured properly because
+RPC is used by oracle nodes to exchange signatures of the resulting
+transaction.
+
+## Configuration
+
+To enable oracle service add `Oracle` subsection to `ApplicationConfiguration`
+section of your node config.
+
+Parameters:
+ * `Enabled`: boolean value, enables/disables the service, `true` for service
+   to be enabled
+ * `AllowPrivateHost`: boolean value, enables/disables private IPs (like
+   127.0.0.1 or 192.168.0.1) for https requests, it defaults to false and it's
+   false on public networks, but you can enable it for private ones.
+ * `Nodes`: list of oracle node RPC endpoints, it's used for oracle node
+   communication. All oracle nodes should be specified there.
+ * `NeoFS`: a subsection of its own for NeoFS configuration with two
+   parameters:
+     - `Timeout`: request timeout, like "5s"
+     - `Nodes`: list of NeoFS nodes (their gRPC interfaces) to get data from,
+       one node is enough to operate, but they're used in round-robin fashion,
+       so you can spread the load by specifying multiple nodes
+ * `MaxTaskTimeout`: maximum time a request can be active (retried to
+   process), defaults to 1 hour if not specified.
+ * `RefreshInterval`: retry period for requests that aren't yet processed,
+   defaults to 3 minutes.
+ * `MaxConcurrentRequests`: maximum number of requests processed in parallel,
+   defaults to 10.
+ * `RequestTimeout`: https request timeout, default is 5 seconds.
+ * `ResponseTimeout`: RPC communication timeout for inter-oracle exchange,
+   default is 4 seconds.
+ * `UnlockWallet`: oracle wallet configuration:
+     - `Path`: path to NEP-6 wallet.
+     - `Password`: password for the account to be used by oracle node.
+
+### Example
+
+```
+  Oracle:
+    Enabled: true
+    AllowPrivateHost: false
+    MaxTaskTimeout: 432000000
+    Nodes:
+      - http://oracle1.example.com:20332
+      - http://oracle2.example.com:20332
+      - http://oracle3.example.com:20332
+      - http://oracle4.example.com:20332
+    NeoFS:
+      Nodes:
+        - st1.storage.fs.neo.org:8080
+        - st2.storage.fs.neo.org:8080
+        - st3.storage.fs.neo.org:8080
+        - st4.storage.fs.neo.org:8080
+    UnlockWallet:
+      Path: "/path/to/oracle-wallet.json"
+      Password: "dontworryaboutthevase"
+```
+
+## Operation
+
+To run oracle service on your network you need to:
+ * set oracle node keys in `RoleManagement` contract
+ * configure and run appropriate number of oracle nodes with keys specified in
+   `RoleManagement` contract

docs/stateroots.md

@@ -0,0 +1,53 @@
+# NeoGo state validation
+
+NeoGo supports state validation using N3 stateroots and can also act as state
+validator (run state validation service).
+
+All NeoGo nodes always calculate MPT root hash for data stored by contracts,
+unlike in Neo Legacy this behavior can't be turned off. They also process
+stateroot messages broadcasted through the network and save validated
+signatures from them if state root hash specified there matches the one signed
+by validators (or shouts loud in the log if it doesn't, because it should be
+the same).
+
+## State validation service
+
+The service is configured as `StateRoot` subsection of
+`ApplicationConfiguration` section in your node config.
+
+Parameters:
+ * `Enabled`: boolean value, enables/disables the service, `true` for service
+   to be enabled
+ * `UnlockWallet`: service's wallet configuration:
+     - `Path`: path to NEP-6 wallet.
+     - `Password`: password for the account to be used by state validation
+       node.
+
+### Example
+
+```
+  StateRoot:
+    Enabled: true
+    UnlockWallet:
+      Path: "/path/to/stateroot.wallet.json"
+      Password: "knowyouare"
+```
+
+### Operation
+
+To run state validation service on your network you need to:
+ * set state validation node keys in `RoleManagement` contract
+ * configure and run appropriate number of state validation nodes with keys
+   specified in `RoleManagement` contract
+
+
+## StateRootInHeader option
+
+NeoGo also supports protocol extension to include state root hashes right into
+header blocks. It's not compatible with regular Neo N3 state validation
+service and it's not compatible with public Neo N3 networks, but you can use
+it on private networks if there is a need to.
+
+The option is `StateRootInHeader` and it's specified in
+`ProtocolConfiguration` section, set it to true and run your network with it
+(whole network needs to be configured this way then).