From ef0051afed5563e6378d638c45fc678732fc8bf4 Mon Sep 17 00:00:00 2001 From: ImTiaan Date: Tue, 20 Oct 2020 16:08:06 +0200 Subject: [PATCH 1/3] Update content-guidelines.md - Minor copy fixes (typos, grammar etc) --- guide/content-guidelines.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/guide/content-guidelines.md b/guide/content-guidelines.md index 3d1dcce6b..626fc0f3b 100644 --- a/guide/content-guidelines.md +++ b/guide/content-guidelines.md @@ -6,7 +6,7 @@ nav_order: # Content guidelines -Thank your for helping shape the Bitcoin Design Guide. We have many different authors with different ideas and voices. To ensure a coherent and consistent experience for readers, we collected a few tips on writing here. +Thank your for helping shape the Bitcoin Design Guide. We have many different authors with different ideas and voices. To ensure a coherent and consistent experience for readers, we assembled the below guidelines to help. #### Know your reader @@ -14,29 +14,31 @@ The guide is primarily meant as a tool for people who work on open-source, non-c #### Speak to the reader -Address the reader directly via "you". +Address the reader directly with "you". #### Use simple language -Bitcoin is meant for a global audience, so you need to assume that many readers are not native English speakers. Many speech writers intentionally write for a 6 to 8th grade proficiency level. This allows a wider audience to understand the content (including non-native speakers), and it forces them to clarify their thinking. You can take advantage of readability tools like [Hemingway](http://www.hemingwayapp.com). They analyze text, provide a readability score, and suggest ways to simplify the writing. +Bitcoin is meant for a global audience, so you need to assume that many readers are not native English speakers. Many speechwriters intentionally write for a 6 to 8th grade proficiency level. This lets a wider audience understand the content (including non-native speakers), and it forces them to clarify their thinking. -Note that simple language does not mean "dumbing things down". There are also some specific topics that require more complex language. A good guidelines is that the deeper a reader gets into a topic, the more complex the language can be (it does not have to be). +Readability tools like [Hemingway](http://www.hemingwayapp.com) are very useful since they analyze text, provide a readability score, and suggest ways to simplify the writing. + +Note that simple language does not mean "dumbing things down". There are specific topics that require more complex language. A good rule of thumb is that the deeper a reader gets into a topic, the more complex the language can be (it does not have to be). #### Be precise -Focus on the information that will be the most useful to your reader. If a page gets too long, split it up into multiple pages. If you want to allow users to dive deeper into a topic that is not core to the guide, see if there are third-party resources you can link to. +Focus on the information that will be the most useful to your reader. If a page gets too long, split it up into multiple pages. If you want to allow users to dive deeper into a topic that is not core to the guide, please try to link to a third party for readers. #### Give practical tips, but don't be overly prescriptive -Provide recommendations and best practices but do not force specific solutions on readers. The project the reader is working on may require something slightly or completely different because of unique context. +Provide recommendations and best practices but do not force specific solutions on readers. The project the reader is working on may require something slightly or completely different because of a unique context. #### Get the reader involved -You can consider asking questions directly to the user before giving answers. You can also use work-sheets, to-do lists, do's and don'ts or other formats to get readers hands-on. +You can consider asking questions directly to the user before giving answers. You can also use worksheets, to-do lists, do's and dont's or other formats to get readers hands-on. #### Use the right medium -One picture can say more than one thousand words. Plus, we can use videos, interactive prototypes, diagrams, and more. Take advantage of these different media and their strengths at communicating differen types of information. If you'd like help creating this type of content, ask in the community. +One picture can say more than one thousand words. Plus, we can use videos, interactive prototypes, diagrams, and more. Take advantage of these different media and their strengths at communicating different types of information. If you'd like help creating this type of content, ask in the community. #### Show examples @@ -48,7 +50,7 @@ The guide is a work in progress and needs to evolve to stay relevant. What we wr #### Write in the open if you can -It is healthy to get early feedback as it may prevent you from going into a wrong direction for too long. There is a whole community around you to help you create better content that helps more people. +It is healthy to get early feedback as it may prevent you from going in the wrong direction for too long. There is a whole community around you to help you create better content that helps more people. From 8cf2e6e708d2db6f77bde3ceb375a36f6060e093 Mon Sep 17 00:00:00 2001 From: ImTiaan Date: Tue, 20 Oct 2020 16:14:28 +0200 Subject: [PATCH 2/3] Update glossary.md alphabetising the glossary --- guide/glossary.md | 169 +++++++++++++++------------------------------- 1 file changed, 56 insertions(+), 113 deletions(-) diff --git a/guide/glossary.md b/guide/glossary.md index 42998863d..acbba47b6 100644 --- a/guide/glossary.md +++ b/guide/glossary.md @@ -7,17 +7,26 @@ nav_order: 2 # Glossary {: .no_toc } -## Wallet +### Account -This term is often used interchangeably for very different things. A user can “download a bitcoin wallet” in the app store, and then the app may offer the option to “create a new wallet” on the home screen. A software wallet may allow for browsing and sending transactions, while a hardware wallet may be limited to key storage and signing functionality. +Just like wallet, the term account can also be used for very different things. In bitcoin wallets that follow the hierarchy described in BIP 44, a bitcoin wallet can have multiple accounts, with each one having its own addresses. However, account is also oftentimes used for accounts with third-party service providers. -### Hardware wallet +Differentiate between -A hardware device used to manage a bitcoin wallet. +- Bitcoin wallet account +- Service account -### Software wallet +### Address -An application used to manage a bitcoin wallet. +### Archival node + +### Bech32 + +### Bitcoin Core + +### Bitcoin Core GUI + +### Bitcoin / bitcoin ### Bitcoin wallet @@ -31,158 +40,92 @@ All bitcoin-related data derived from and associated with a single recovery phra - [Bitcoin Optech style guide](https://github.com/bitcoinops/bitcoinops.github.io/blob/master/STYLE.md){:target="_blank"} - [Bitcoin Optech topics](https://bitcoinops.org/en/topics/){:target="_blank"} -## Vault - -A term sometimes used for multi signature wallets. - -## Account +### Change address -Just like wallet, the term account can also be used for very different things. In bitcoin wallets that follow the hierarchy described in BIP 44, a bitcoin wallet can have multiple accounts, with each one having its own addresses. However, account is also oftentimes used for accounts with third-party service providers. - -Differentiate between +### Coin control -- Bitcoin wallet account -- Service account +### CoinJoin -## Address +### Descriptors -## Change address +### Extended private key (XPRIV) -## Key - -## Private key - -## Public key - -## Recovery phrase - -_Also referred to as Seed, Mnemonic, and Backup phrase._ - -A list of 12, 18 or 24 words from which all bitcoin wallet keys and addresses are derived from. - -## Extended private key (XPRIV) - -## Extended public key (XPUB, YPUB, ZPUB) +### Extended public key (XPUB, YPUB, ZPUB) The master public key of a bitcoin account. All public addresses are generated from it. Explain how this is used for multisig and view-only wallets. -### YPUB - -Same as XPUB however the Y denotes that this ‘xpub’ belongs to a wallet that is following the BIP49 standard. BIP49 details the derivation scheme from wrapped-segwit addresses (P2WPKH-nested-in-P2SH). - -### ZPUB +### Full node -Same as YPUB though the Z denotes it is an extended public key from a segregated witness enabled wallet following BIP49. +### Hardware wallet -## Multi signature wallet (Multisig) +A hardware device used to manage a bitcoin wallet. -## Transaction +### Initial block download (IBD) -## Input +### Input When an address receives bitcoin from another address, this is called an input. Transactions can include multiple inputs. -## Output -The opposite of an input, an output is when an address sends bitcoin to another address. Transactions can include multiple inputs. - -## Unspent transaction output (UTXO) -An output that has not been sent to another address. The bitcoin wallet balance is calculated from adding up unspent outputs. - -Partially signed bitcoin transaction (PSBT) -A file format for bitcoin transactions that are not fully signed yet. Allows for passing around a transaction to other software or devices for signing, for example in a multi signature wallet setup. - -**References:** - -- [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki){:target="_blank"}: Partially Signed Bitcoin Transaction Format - -## Bitcoin improvement proposal (BIP) - -A standardized design document format for suggesting improvements to Bitcoin. They are hosted on Github [here](https://github.com/bitcoin/bips){:target="_blank"}. Some important proposals to be aware of: - -- [BIP 39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki){:target="_blank"}: Mnemonic code for generating deterministic keys -- [BIP 44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki){:target="_blank"}: Multi-Account Hierarchy for Deterministic Wallets -- [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki){:target="_blank"}: Partially Signed Bitcoin Transaction Format - - -## Bitcoin / bitcoin - -## Bitcoin Core - -## Bitcoin Core GUI - -## Segregated witness (SegWit) +### Key -## Bech32 +### Miniscript -## Replace by fee (RBF) +### Multi signature wallet (Multisig) -## Miniscript +### MuSig -## Schnorr signatures +### Node -## Taproot +### Output -## Descriptors +### PayJoin (P2EP) -## Node - -Node refers to software that participates in the bitcoin network. It exchanges transaction data with other nodes, stores some or all of it, and verifies that transactions are valid. - -### Full node - -A node that fully verifies all of the rules of the Bitcoin network. +### Private key ### Pruned full node -A node that fully verifies all of the rules of the Bitcoin network with a much smaller storage capacity because it only stores transactions relevant to the users wallet. +### Public key -### Archival node - -A full node that has not only verified all data, but also provides it to other nodes on the work. +### Recovery phrase -## Initial block download (IBD) - -To fully verify that all transactions on the bitcoin network are valid, a full node needs to download and examine a large amount of data. This is called the initial block download, after which the node has caught up with the latest transaction activity. This can take several hours, and only after it is complete can wallets linked to the node be used. +_Also referred to as Seed, Mnemonic, and Backup phrase._ -## Simplified payment verification (SPV) +A list of 12, 18 or 24 words from which all bitcoin wallet keys and addresses are derived from. -## CoinJoin +### Replace by fee (RBF) - Allow for combining multiple payments from multiple spenders into a single transaction to make it harder to determine which spender paid which recipient(s). +### Schnorr signature -**References:** +### Schnorr signatures -- [WabiSabi](https://github.com/zkSNACKs/WabiSabi/blob/master/explainer.md){:target="_blank"} -- [Bitcoin wiki](https://en.bitcoin.it/wiki/CoinJoin){:target="_blank"} +### Segregated witness (SegWit) -## PayJoin (P2EP) +### Simplified payment verification (SPV) -A type of CoinJoin for direct transactions between two parties that makes it harder to understand the ownership of the inputs included in the transaction. The sender creates a partial transaction that the recipient adds another input to. Then the sender broadcasts the transaction. The same amount of bitcoin is transferred as in a simple bitcoin transaction. However, the additional input from the recipient makes it harder to analyze from the outside what happened in the transaction. +### Software wallet -## Coin control +An application used to manage a bitcoin wallet. -The act of choosing which coins (really unspent outputs (UTXOs)) to forward to another address in a transaction. Wallet can automatically choose these, but sometimes users may want to manually choose coins to send. +### Taproot -Fees are based on transaction size, which is based on the number of outputs included. So choosing fewer outputs can reduce fees. +### Transaction -As it is possible to trace the history of coins and see how they were previously spent, it may sometimes be warranted to not send certain coins because the recipient may be able to deduct personal information. +### Unspent transaction output (UTXO) -## Schnorr signature +### Vault -An algorithm to generate cryptographic signatures. One of the benefits is that the size of multi signature transactions can be reduced (see MuSig). The code for this improvement was merged in Bitcoin Core in September 2020. +A term sometimes used for multi signature wallets. -**References:** +### Wallet -- [Wikipedia](https://en.wikipedia.org/wiki/Schnorr_signature){:target="_blank"} -- [Bitcoin wiki](){:target="_blank"} -- [BIP 340](){:target="_blank"} +This term is often used interchangeably for very different things. A user can “download a bitcoin wallet” in the app store, and then the app may offer the option to “create a new wallet” on the home screen. A software wallet may allow for browsing and sending transactions, while a hardware wallet may be limited to key storage and signing functionality. -## MuSig +### YPUB -A standard for multisignature that uses Schnorr signatures. Previously, the more signers participated in a transaction, the size of the transaction got larger and took more time to verify. It was also possible to see the number of signers in the final transaction. MuSig addresses both issues. It hides the number of signers for better privacy. MuSig also improves scalability by reducing the size of transactions and being more efficient to verify. +Same as XPUB however the Y denotes that this ‘xpub’ belongs to a wallet that is following the BIP49 standard. BIP49 details the derivation scheme from wrapped-segwit addresses (P2WPKH-nested-in-P2SH). -**References:** +### ZPUB -- [Proposal](https://eprint.iacr.org/2018/068){:target="_blank"} in the Cryptology ePrint archive \ No newline at end of file +Same as YPUB though the Z denotes it is an extended public key from a segregated witness enabled wallet following BIP49. \ No newline at end of file From 127ad298bfb21ee4e56274779a77bc6ea7b00047 Mon Sep 17 00:00:00 2001 From: ImTiaan Date: Tue, 20 Oct 2020 16:33:08 +0200 Subject: [PATCH 3/3] Update glossary.md completed alphabetising the glossary --- guide/glossary.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/guide/glossary.md b/guide/glossary.md index acbba47b6..3090c8924 100644 --- a/guide/glossary.md +++ b/guide/glossary.md @@ -20,6 +20,8 @@ Differentiate between ### Archival node +A full node that has not only verified all data, but also provides it to other nodes on the work. + ### Bech32 ### Bitcoin Core @@ -44,8 +46,21 @@ All bitcoin-related data derived from and associated with a single recovery phra ### Coin control +The act of choosing which coins (really unspent outputs (UTXOs)) to forward to another address in a transaction. Wallet can automatically choose these, but sometimes users may want to manually choose coins to send. + +Fees are based on transaction size, which is based on the number of outputs included. So choosing fewer outputs can reduce fees. + +As it is possible to trace the history of coins and see how they were previously spent, it may sometimes be warranted to not send certain coins because the recipient may be able to deduct personal information. + ### CoinJoin +Allow for combining multiple payments from multiple spenders into a single transaction to make it harder to determine which spender paid which recipient(s). + +**References:** + +- [WabiSabi](https://github.com/zkSNACKs/WabiSabi/blob/master/explainer.md){:target="_blank"} +- [Bitcoin wiki](https://en.bitcoin.it/wiki/CoinJoin){:target="_blank"} + ### Descriptors ### Extended private key (XPRIV) @@ -58,12 +73,16 @@ Explain how this is used for multisig and view-only wallets. ### Full node +A node that fully verifies all of the rules of the Bitcoin network. + ### Hardware wallet A hardware device used to manage a bitcoin wallet. ### Initial block download (IBD) +To fully verify that all transactions on the bitcoin network are valid, a full node needs to download and examine a large amount of data. This is called the initial block download, after which the node has caught up with the latest transaction activity. This can take several hours, and only after it is complete can wallets linked to the node be used. + ### Input When an address receives bitcoin from another address, this is called an input. Transactions can include multiple inputs. @@ -76,16 +95,34 @@ When an address receives bitcoin from another address, this is called an input. ### MuSig +A standard for multisignature that uses Schnorr signatures. Previously, the more signers participated in a transaction, the size of the transaction got larger and took more time to verify. It was also possible to see the number of signers in the final transaction. MuSig addresses both issues. It hides the number of signers for better privacy. MuSig also improves scalability by reducing the size of transactions and being more efficient to verify. + +**References:** + +- [Proposal](https://eprint.iacr.org/2018/068){:target="_blank"} in the Cryptology ePrint archive + ### Node +Node refers to software that participates in the bitcoin network. It exchanges transaction data with other nodes, stores some or all of it, and verifies that transactions are valid. + ### Output +The opposite of an input, an output is when an address sends bitcoin to another address. Transactions can include multiple inputs. + +### Partially signed bitcoin transaction (PSBT) + +A file format for bitcoin transactions that are not fully signed yet. Allows for passing around a transaction to other software or devices for signing, for example in a multi signature wallet setup. + ### PayJoin (P2EP) +A type of CoinJoin for direct transactions between two parties that makes it harder to understand the ownership of the inputs included in the transaction. The sender creates a partial transaction that the recipient adds another input to. Then the sender broadcasts the transaction. The same amount of bitcoin is transferred as in a simple bitcoin transaction. However, the additional input from the recipient makes it harder to analyze from the outside what happened in the transaction. + ### Private key ### Pruned full node +A node that fully verifies all of the rules of the Bitcoin network with a much smaller storage capacity because it only stores transactions relevant to the users wallet. + ### Public key ### Recovery phrase @@ -98,7 +135,13 @@ A list of 12, 18 or 24 words from which all bitcoin wallet keys and addresses ar ### Schnorr signature -### Schnorr signatures +An algorithm to generate cryptographic signatures. One of the benefits is that the size of multi signature transactions can be reduced (see MuSig). The code for this improvement was merged in Bitcoin Core in September 2020. + +**References:** + +- [Wikipedia](https://en.wikipedia.org/wiki/Schnorr_signature){:target="_blank"} +- [Bitcoin wiki](){:target="_blank"} +- [BIP 340](){:target="_blank"} ### Segregated witness (SegWit) @@ -114,6 +157,8 @@ An application used to manage a bitcoin wallet. ### Unspent transaction output (UTXO) +An output that has not been sent to another address. The bitcoin wallet balance is calculated from adding up unspent outputs. + ### Vault A term sometimes used for multi signature wallets.