Some notes about the first page ”first_btc_tx”

[furszy]

Hey, reviewed the first page. Cool stuff. Leaving my two cents here:

I don’t think that should start the tutorial mentioning the protocol upgrades nor why they were done in a specific non-natural manner. The reader does not have context at that point to understand them (nor know how a tx generally works).

I would start this page differently; would go incrementally.
First, present how transactions generally work by comparing them to how we spend physical bills; without mentioning any protocol related stuff. E.g. Carol has 2 bills on her pocket, 5 and 10 usd, and she wants to send 12 usd to Bob. Show how that looks like in the real world, and how that looks like in the Bitcoin Blockchain. Making clear from start that (conceptually speaking at a very basic level) the Bitcoin Blockchain actually mimics how we transact in the real world with physical money. You could show in this way what the “change” and “fee” concepts area and how they looks like etc. (Adding a small picture of this flow wouldn’t be bad neither).

Then, after this general introduction, would move to introduce what transaction outputs are and how they are built (showing how it's connected to Bob's address).
Then, explain how Carol can transfer certain coins to Bob by linking an unspent output (defining what an unspent output is). Which will force you to define what a tx input is, which will make you define what locking and unlocking scripts are etc.

In this way, at least for myself, the reading process feels more natural and fluid (right now, I feel it like several notes chained one after the other instead of something that drives me from one end to the other).

[DariusParvin]

Hey furczy, thanks a lot for your feedback!

I don’t think that should start the tutorial mentioning the protocol upgrades nor why they were done in a specific non-natural manner. The reader does not have context at that point to understand them (nor know how a tx generally works).

I was thinking that this tutorial would be aimed at someone who is already familiar with how bitcoin works, at least on a high level. This is for two reasons:
1 - The detail in this tutorial would probably be too deep
2 - There'd be a few other things to understand first, like blocks and mining, and why those are necessary.

The kind of person it'd be suitable for would be: someone who wants to work on wallet software, contribute to core, or have a better low level understanding of bitcoin transactions.

This should definitely be made clearer in the repo. I'll add a prerequisite section suggesting 'Mastering Bitcoin' and having a basic understanding of some of the data types and cryptographic primitives used in bitcoin.

I would start this page differently; would go incrementally.
First, present how transactions generally work by comparing them to how we spend physical bills; without mentioning any protocol related stuff. E.g. Carol has 2 bills on her pocket, 5 and 10 usd, and she wants to send 12 usd to Bob. Show how that looks like in the real world, and how that looks like in the Bitcoin Blockchain. Making clear from start that (conceptually speaking at a very basic level) the Bitcoin Blockchain actually mimics how we transact in the real world with physical money. You could show in this way what the “change” and “fee” concepts area and how they looks like etc. (Adding a small picture of this flow wouldn’t be bad neither).

Even with some assumed prerequisite knowledge, I agree that having a basic level diagram and overview of transactions would be helpful as a starting point.

I'm also thinking to move some of the stuff in 'chapter 2' (elliptic curve math review, hash functions...) to an 'appendix' since they can be skipped if the reader is familiar with them.

Then, after this general introduction, would move to introduce what transaction outputs are and how they are built (showing how it's connected to Bob's address).

I like this idea. It is somewhat covered in Addresses.ipynb, but maybe it should be renamed to 'Outputs and addresses'. Then the rest of the notebooks on legacy, segwit, taproot would be based on spending those outputs.

In this way, at least for myself, the reading process feels more natural and fluid (right now, I feel it like several notes chained one after the other instead of something that drives me from one end to the other).

Yes I agree. Hopefully with a better ordering it'll make it easier to write a bit more of a narrative around it so that it flows better.

Below is a todo list for myself. Let me know if that covers your feedback or if you had any other ideas!

To do:

• add a section on prerequisite knowledge
• add a page for page for transactions at a basic level with a diagram
• move some material from 'chapter 2' to an appendix
• edit the 'addresses' notebook to cover 'outputs and addresses'

[DariusParvin]

I'm going to leave the second TODO - 'add a page for page for transactions at a basic level with a diagram' for now since there are some higher priority TODOs from the other feedback in the other issues. Hopefully the prerequisite section makes it a bit clearer what the required knowledge is going in.

The main priority for now is getting the notebooks to use TestShell rather than bitcoin-cli. There's also some more polishing for the other notebooks too which is probably a higher priority.