add TSS doc for the new testnet

grimoria-testnet-2/tss.md

@@ -0,0 +1,144 @@
+# TSSigner
+
+The *`TSS`*(**Threshold Signature Scheme**) network is a key building block intended to perform Bitcoin signing in the distributed manner to facilitate the Bitcoin bridge on the [Side Chain](https://github.com/sideprotocol/side)
+
+The TSS signature network consists of twenty-one nodes which are a subset of the Side validators of well-known reputation.
+
+TSS nodes are mainly responsible for several tasks: *`DKG`*(**Distributed Key Generation**), `Signing` and `Relaying`.
+
+## DKG
+
+The DKG procedure is as follows:
+
+1. Initiate: The DKG initiation is proposed as a governance proposal on the Side chain. The proposal contains the DKG participant set and required  threshold for later signing.
+
+2. Vote: Community members and validators can vote for the proposal.
+
+3. Create: The DKG request is formally created on the Side chain when the proposal passed.
+
+4. Complete: TSS nodes will coordinate to complete the DKG request. All participants listed in the proposal must be connected to the TSS network in the phase.
+
+5. Re-DKG: This happen when some nodes want to quit the TSS network according to their operation demands. New signing keys will be generated by the steps above and all assets held by the previous keys will be transferred to the newly generated ones.
+
+## Signing
+
+Signing is the regular task for TSS nodes.
+
+1. Signing requests are fetched from the Side chain by the coordinator selected by the TSS network periodically.
+
+2. Sign the requests when signing requests received from the TSS network.
+
+## Relaying
+
+As the security guard, TSS nodes can contribute to the security of the bitcoin bridge by relaying the bitcoin block headers.
+
+At the same time, the bridge related transactions including deposit and withdrawal can be relayed to the Side chain by TSS nodes as well.
+
+## Get started
+
+### Build from source
+
+1. Install *Rust*
+
+```
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+2. Clone and install
+
+```
+git clone https://github.com/sideprotocol/tssigner.git
+cd tssigner
+cargo install --release
+```
+
+### Configure
+
+1. Initialize
+
+```
+shuttler --home ~/.shuttler init --network testnet --port 5158
+```
+
+The *home* directory and *port* can be replaced by your choice.
+
+The random port will be generated if *--port* not set
+
+2. Set the bootstrapping nodes
+
+```
+bootstrap_nodes = [<seed node addresses>]
+```
+
+The bootstrapping nodes are used to help connect to the TSS network when started.
+
+The public nodes can be used commonly.
+
+3. Set the validator key
+
+```
+priv_validator_key_path = "<validator key path>"
+```
+
+The validator key is required to participate the DKG.
+The item should be set to the correct location which is commonly the *.side/config/priv_validator_key.json* in the home directory.
+
+4. Set the Side gRPC
+
+```
+[side_chain]
+grpc = <gprc address>
+```
+
+If you run own Side node on the same server, the item can be set to `http://localhost:9090`. The value can be configured by the actual deployment or set to the public Side node which provides the gRPC server.
+
+5. Set the Bitcoin RPC
+
+```
+[bitcoin]
+rpc = <rpc address>
+user = <rpc username>
+password = <rpc password>
+```
+
+For signers and relayers, the bitcoin node rpc is required to send the signed transactions or sync the bitcoin block headers and the bridge related transactions to the Side chain.
+
+In the Side testnet phase 3, the corresponding bitcoin network is `testnet3`. The TSS node operator can deploy own bitcoin node or use the third-party server provider by demand.
+
+### Fund the relayer address
+
+The relayer(Side transaction sender) address can be viewed by the following command:
+
+```
+shuttler --home <home> addresses
+```
+
+**Note**: Before starting the TSS node, the sender address needs to be funded for sending the transactions to the Side chain.
+
+### Start
+
+The TSS node can be started by the different modes or roles: *`signer`* and *`relayer`*.
+
+1. Start as signer
+
+```
+shuttler --home <home> start --signer
+```
+
+2. Start as relayer
+
+```
+shuttler --home <home> start --relayer
+```
+
+3. Start as both signer and relayer
+
+```
+shuttler --home <home> start --signer --relayer
+```
+
+or start by default
+
+```
+shuttler --home <home> start
+```