diff --git a/docs/encyclopedia/signatures-multisig.mdx b/docs/encyclopedia/signatures-multisig.mdx index c3e5dc473..3c61990f1 100644 --- a/docs/encyclopedia/signatures-multisig.mdx +++ b/docs/encyclopedia/signatures-multisig.mdx @@ -44,43 +44,86 @@ Adding a signature of type hash(x) allows anyone who knows x to sign the transac First, create a random 256-bit value, which we call x. The SHA256 hash of that value can be added as a signer of type hash(x). Then in order to authorize a transaction, x is added as one of the signatures of the transaction. Keep in mind that x will be known to the world as soon as a transaction is submitted to the network with x as a signature. This means anyone will be able to sign for that account with the hash(x) signer at that point. Often you want there to be additional signers so someone must have a particular secret key and know x in order to reach the weight threshold required to authorize transactions on the account. ## Examples -- Example 1: Asset issuers +- Example 1: Anchors - Example 2: Joint accounts - Example 3: Expense accounts - Example 4: Company accounts -- Example 5: Include a recovery signer -### Example 1: Asset Issuers -You issue an asset, and would like to keep its issuing key offline to reduce the likelihood that a bad actor gets ahold of the key and starts issuing credit improperly. However, for compliance reasons, your asset is auth required, and you need to authorize holders with the Set Trust Line Flags operation. Before you issue credit to an account, you need to verify that account is OK. +### Example 1: Anchors +You run an anchor that would like to keep its issuing key offline. That way, it's less likely a bad actor can get ahold of the anchor's key and start issuing credit improperly. However, your anchor needs to authorize people holding credit by running the `Set Trust Line Flags` operation. Before you issue credit to an account, you need to verify that account is OK. -Multisig allows you to do all of this without exposing the master key of your issuing account. You can add another signing key to your account with the operation Set Options. This additional key should have a weight below your issuing account’s medium threshold. Since Set Trust Line Flags is a low-threshold operation, this extra key authorizes users to hold your asset. But, since Payment is a medium-threshold operation, this key does not allow anyone who compromises your issuing account to issue credit. +Multisig allows you to do all of this without exposing the master key of your anchor. You can add another signing key to your account with the operation `Set Options`. This additional key should have a weight below your anchor account's medium threshold. Since `Set Trust Line Flags` is a low-threshold operation, this extra key authorizes users to hold your anchor's credit. But, since `Payment` is a medium-threshold operation, this key does not allow anyone who compromises your anchor to issue credit. Your account setup: -[insert code] + +``` + Master Key Weight: 2 + Additional Signing Key Weight: 1 + Low Threshold: 0 + Medium Threshold: 2 + High Threshold: 2 +``` + + + ### Example 2: Joint accounts You want to set up a joint account with Bilal and Carina such that any of you can authorize a payment. You also want to set up the account so that, if you choose to change signers (e.g., remove or add someone), a high-threshold operation, all 3 of you must agree. You add Bilal and Carina as signers to the joint account. You also ensure that it takes all of your key weights to clear the high threshold but only one to clear the medium threshold. Joint account setup: -[insert code] + + +``` + Master Key Weight: 1 + Low Threshold: 0 + Medium Threshold: 0 + High Threshold: 3 + Bilal's Signing Key Weight: 1 + Carina's Signing Key Weight: 1 +``` + + ### Example 3: Expense accounts You fully control an expense account, but you want your two coworkers Diyuan and Emil to be able to authorize transactions from this account. You add Diyuan and Emil’s signing keys to the expense account. If either Diyuan or Emil leave the company, you can remove their signing key, a high-threshold operation. Expense account setup: -[insert code] + + +``` + Master Key Weight: 3 + Low Threshold: 0 + Medium Threshold: 0 + High Threshold: 3 + Diyuan's Key Weight: 1 + Emil's Key Weight: 1 +``` + + ### Example 4: Company accounts -Warning: this example involves setting the master key weight of an account to 0. Be very, very careful if you decide to do that: that key will no longer be able to sign any kind of transaction, so you are in danger of permanently locking yourself out of your account. Make sure you’ve thought carefully about what you’re doing, that you understand the implications, and that you change weights in the correct order. +**Warning**: this example involves setting the master key weight of an account to 0. Be very careful if you decide to do that: that key will no longer be able to sign any kind of transaction, so you are in danger of permanently locking yourself out of your account. Make sure you’ve thought carefully about what you’re doing, that you understand the implications, and that you change weights in the correct order. Your company wants to set up an account that requires 3 of 6 employees to agree to any transaction from that account. Company account setup: -[insert code] - -### Example 5: Include a recovery signer -This example will walk through what to do if an individual loses their private key without providing any third-party control of the account. The user of the wallet will preregister the account and a phone number, email, or other form of authentication with one or more servers implementing the protocol and add those servers as signers of the account. If two or more servers are used with appropriate signer configuration, no individual server will have control of the account, but collectively, they may help the individual recover access to the account. This also enables individuals to pass control of a Stellar account to another individual. + + +``` + Master Key Weight: 0 (Turned off so this account can't do anything without an employee.) + Low Threshold: 3 + Medium Threshold: 3 + High Threshold: 3 + Employee 1 Key Weight: 1 + Employee 2 Key Weight: 1 + Employee 3 Key Weight: 1 + Employee 4 Key Weight: 1 + Employee 5 Key Weight: 1 + Employee 6 Key Weight: 1 +``` + +