Update signature documentation (#1188)

doc/operators/start_network.rst

@@ -9,18 +9,20 @@ Starting a New Network
 Starting the First Node
 -----------------------
 
-To create a new CCF network, the first node of the network should be started with the ``start`` option:
+To create a new CCF network, the first node of the network should be invoked with the ``start`` option:
 
 .. code-block:: bash
 
     $ cchost
     --enclave-file /path/to/enclave_library
-    --node-address node_ip:node_port
     --rpc-address <ccf-node-address>
+    --node-address <ccf-node-to-node-address>
     --public-rpc-address <ccf-node-public-address>
     [--domain domain]
     --ledger-file /path/to/ledger
     --node-cert-file /path/to/node_certificate
+    [--sig-max-tx number_of_transactions]
+    [--sig-max-ms number_of_milliseconds]
     start
     --network-cert-file /path/to/network_certificate
     --network-enc-pubk-file /path/to/network_encryption_pubk
@@ -28,22 +30,44 @@ To create a new CCF network, the first node of the network should be started wit
     [--member-info /path/to/member2_cert,/path/to/member2_enc_pub ...]
     --gov-script /path/to/lua/governance_script
 
-CCF nodes can be started by using IP Addresses (both IPv4 and IPv6 are supported) or by specifying domain names. If domain names are to be used then ``--domain`` should be passed to the node at startup. Once a DNS has been setup it will be possible to connect to the node over TLS by using the node's domain name.
-
-.. note:: To start a CCF node in `virtual` mode, operators should run ``$ cchost.virtual --enclave-file /path/to/virtual_enclave_library ...``
+CCF nodes can be started by using IP Addresses (both IPv4 and IPv6 are supported) or by specifying a fully qualified domain name. If an FQDN is used then ``--domain`` should be passed to the node at startup. Once a DNS has been setup it will be possible to connect to the node over TLS by using the node's domain name.
 
 When starting up, the node generates its own key pair and outputs the certificate associated with its public key at the location specified by ``--node-cert-file``. The certificate of the freshly-created CCF network is also output at the location specified by ``--network-cert-file`` as well as the network encryption public key used by members during recovery via ``--network-enc-pubk-file``.
 
-.. note:: The network certificate should be distributed to users and members to be used as the certificate authority (CA) when establishing a TLS connection with any of the nodes part of the CCF network. When using curl, this is passed as the ``--cacert`` argument.
-
 The certificates and recovery public keys of initial members of the consortium are specified via ``--member-info``. For example, if 3 members should be added to CCF, operators should specify ``--member-info member1_cert.pem,member1_enc_pub.pem``, ``--member-info member2_cert.pem,member2_enc_pub.pem``, ``--member-info member3_cert.pem,member3_enc_pub.pem``.
 
 The :term:`Constitution`, as defined by the initial members, should be passed via the ``--gov-script`` option.
 
-The network is now in its opening state and any new nodes can join the network without being trusted by members.
+The network is now in its opening state and new nodes can join the network. :ref:`members can add other members and users via governance <members/open_network:Opening a Network>`.
 
-.. note:: Once a CCF network is started, :ref:`members can add other members and users via governance <members/open_network:Opening a Network>`.
-.. note:: If starting up the network with PBFT enabled as the consensus protocol, be sure to add the ``--consensus pbft`` CLI argument  when starting up the node. For more info on the provided consensus protocols please see :ref:`here <developers/consensus:Consensus Protocols>`
+Network Identity
+~~~~~~~~~~~~~~~~
+
+The network certificate should be distributed to users and members to be used as the certificate authority (CA) when establishing a TLS connection with any of the nodes part of the CCF network. When using curl, this is passed as the ``--cacert`` argument.
+
+Virtual Mode
+~~~~~~~~~~~~
+
+To start a CCF node in `virtual` mode, operators should run ``$ cchost.virtual --enclave-file /path/to/virtual_enclave_library ...``.
+
+.. warning:: Nodes started in virtual mode provide no security guarantees. They should never be used for production purposes.
+
+PBFT
+~~~~
+
+To use the PBFT consensus protocol, pass ``--consensus pbft``. Please see :ref:`here <developers/consensus:Consensus Protocols>` for more information.
+
+Signature Interval
+~~~~~~~~~~~~~~~~~~
+
+Transaction commit latency in a CCF network is primarily a function of signature frequency. A network emitting signatures more frequently will be able to commit transactions faster,
+but will spend a larger proportion of its execution resources creating and verifying signatures. Setting signature frequency is a trade-off between transaction
+latency and throughput.
+
+Two options are provided to that end:
+
+- ``--sig-max-tx``: maximum number of transactions between two signatures
+- ``--sig-max-ms``: maximum time in milliseconds between two signatures.
 
 Adding a New Node to the Network
 --------------------------------
@@ -54,8 +78,8 @@ To add a new node to an existing opening network, other nodes should be started
 
     $ cchost
     --enclave-file /path/to/enclave_library
-    --node-address node_ip:node_port
     --rpc-address <ccf-node-address>
+    --node-address <ccf-node-to-node-address>
     --public-rpc-address <ccf-node-public-address>
     --ledger-file /path/to/ledger
     --node-cert-file /path/to/node_certificate
@@ -82,9 +106,9 @@ Using a Configuration File
     enclave-file = <enclave-file>
     enclave-type = debug
     consensus = raft
-    node-address = <node-address>
-    rpc-address = <rpc-address>
-    public-rpc-address = <public-rpc-address>
+    rpc-address = <node-address>
+    public-rpc-address = <node-public-address>
+    node-address = <ccf-node-to-node-address>
 
     [<subcommand, one of [start, join, recover]>]
     network-cert-file = <network-cert-file-name>
@@ -97,9 +121,9 @@ Using a Configuration File
     enclave-file = <enclave-file>
     enclave-type = debug
     consensus = raft
-    node-address = <node-address>
-    rpc-address = <rpc-address>
-    public-rpc-address = <public-rpc-address>
+    rpc-address = <node-address>
+    public-rpc-address = <node-public-address>
+    node-address = <node-to-node-address>
 
     [<subcommand, one of [start, join, recover]>]
     network-cert-file = <network-cert-file-name>