Signatures and Multisig
This section details signing non-smart contract transactions. For auth related to smart contract transactions, see authorization
Signatures are authorization for transactions on the network. Transactions always need authorization from at least one public key to be valid and generally, the signature comes from the source account. Sometimes transactions require more signatures, which we’ll get into in the multisig section.
Transaction signatures are created by signing the transaction object contents with a secret key. Stellar uses the ed25519 signature scheme, but there is also a mechanism for adding additional types of public and private key schemes. A transaction with an attached signature is considered to have authorization from that public key.
Thresholds
Each operation falls under a specific threshold category: low, medium, or high with a number level between 0-255 (to read more about this see our section on Operations and Transactions). This threshold determines what signature weight is needed to authorize an operation.
To view each operation’s threshold, see our List of Operations section.
Accounts can set their own signature weight, threshold values, and additional signing keys with the Set Options operation. By default, all operation threshold levels are set to 0, and the master key is set to weight 1. For most cases, it is recommended to set thresholds such that low <= medium <= high.
If the master key’s weight is set at 0, it cannot be used to sign transactions, even for operations with a threshold value of 0. Be very careful setting your master key weight to 0. Doing so may permanently lock you out of your account (although if there are other signers listed on the account, they can still continue to sign transactions.)
Authorization
To determine if a transaction has the necessary authorization to run, the weights of all the signatures in the transaction envelope are added up. If this sum is equal to or greater than the threshold for that operation type, then the operation is authorized.
This scheme is very flexible. You can require many signers to authorize payments from a particular account. You can have an account that any number of people can authorize for. You can have a master key that grants access or revokes access from others. It supports any m of n setup.
Multisig
In some cases, a transaction may need more than one signature:
- If the transaction has operations with multiple source accounts, it requires the source account signature for each operation
- Additional signatures are required if the account associated with the transaction has multiple public keys
Each additional signer beyond the master key increases the account’s minimum balance by one base reserve. Up to 20 signatures can be attached to one transaction. Once a signature threshold is met, if there are leftover signatures, the transaction will fail. For example, if your transaction requires three signatures, providing more than three signatures, even if they are all valid, will result in a failed transaction error: TX_BAD_AUTH_EXTRA. This design is because unnecessary signature verification has a large effect on performance before accepting transactions in consensus.
Alternate signature types
To enable some advanced smart contract features there are a couple of additional signature types. These signature types also have weights and can be added and removed similarly to normal signature types. But rather than check a cryptographic signature for authorization they have a different method of proving validity to the network.
Pre-authorized Transaction
It is possible for an account to pre-authorize a particular transaction by adding the hash of the future transaction as a signer on the account. To do that, you need to prepare the transaction beforehand with the proper sequence number. Then you can obtain the hash of this transaction and add it as a signer to the account.
Signers of this type are automatically removed from the account when a matching transaction is applied, regardless of whether the transaction succeeds or fails. In case a matching transaction is never submitted, the signer remains, and must be manually removed using the Set Options operation.
This type of signer is especially useful in escrow accounts. You can pre-authorize two different transactions. Both could have the same sequence number but different destinations. This means that only one of them can be executed.
Hash(x)
Hash(x) signing is a different concept from transaction hashes. Transaction hashes are unique identifiers generated by applying a cryptographic hash function to the data of a transaction in a blockchain. They serve as a digital fingerprint and allow users to verify and reference transactions on the network. Hash(x) is a signature type.
Adding a signature of type hash(x) allows anyone who knows x to sign the transaction. This type of signer is especially useful in atomic cross-chain swaps which are needed for inter-blockchain protocols like lightning networks.
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: Anchors
- Example 2: Joint accounts
- Example 3: Expense accounts
- Example 4: Company accounts
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 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:
- Example
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:
- Example
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:
- Example
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 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:
- Example
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