diff --git a/docs/protocol/Multisig.md b/docs/protocol/Multisig.md index 92562922..aad95236 100644 --- a/docs/protocol/Multisig.md +++ b/docs/protocol/Multisig.md @@ -1,27 +1,35 @@ # Multisig -The multisig is represented on chain by the `Multisig` contract. +Multisigs are confirmed on-chain by the `Multisig` contract. While the processor +does create the multisig, and sign for it, making it irrelevant to the chain, +confirming it on-chain solves the question of if the multisig was successfully +created or not. If each processor simply asked all other processors for +confirmation, votes lost to the network would create an inconsistent view. This +is a form of the Byzantine Generals Problem, which can be resolved by placing +votes within a BFT system. + +Confirmation requires all participants confirm the new set of keys. While this +isn't BFT, despite the voting process being BFT, it avoids the scenario where +only t (where t is the BFT threshold, as used in the t-of-n multisig) +successfully generated shares, actually creating a t-of-t multisig in practice, +which is not BFT. This does mean a single node can delay a churn, which is +expected to be handled via a combination of slashing, and if necessary, removal. + +Validators are allowed to vote multiple times across sets of keys, with the +first set to be confirmed becoming the set of keys for that validator set. These +keys remain valid for the validator set until it is changed. If a validator set +remains consistent despite the global validator set updating, their keys carry. +If a validator set adds a new member, and then loses them, their historical keys +are not reused. + +Once new keys are confirmed for a given validator set, they become tracked and +the recommended set of keys for incoming funds. The old keys are still eligible +to receive funds for a provided grace period, requiring the current validator +set to track both sets of keys. The old keys are also still used to handle all +outgoing payments as well, until the end of the grace period, at which point +they're no longer eligible to receive funds and they forward all of their funds +to the new set of keys. ### `vote(keys: Vec>)` -Lets a validator vote on a set of keys. Once all validators have voted on these -keys, it becomes the tracked set of keys for incoming funds. - -The old keys are eligible to still receive transactions for a provided grace -period. This means nodes are expected to track and oraclize incoming -transactions for both sets of keys. At the end of the grace period, the old keys -are dropped from consideration, and all funds are forwarded to the new keys at -the next transaction interval for a given chain. - -The old keys are expected to process outbounds until they forward their funds, -at which point the new keys are expected to process outbounds. - -Unlike transactions in, which is confirmed as part of the BFT process, a 100% -vote is used here. While the BFT process would confirm that keys were generated -and enough nodes acknowledge them the wallet would be spendable from, it does -not confirm fault tolerance. If the other 33% of nodes failed to receive their -key shares somehow, the multisig which is intended to be t-of-n would instead be -t-of-t. - -Accordingly, validators are allowed to vote multiple times, and the first key -set to receive the necessary votes becomes the new key set. +Lets a validator vote on a set of keys for their validator set.