search

btcpayserver / btcpayserver-doc

BTCPay Server Official Documentation
https://docs.btcpayserver.org
386 stars 261 forks source link

BTCPay Architecture #145

Closed pavlenex closed 5 years ago

pavlenex commented 5 years ago

While there is progress for #81 which covers BTCPay in generic and playful way (targets merchants, users), I would like to see if there is someone familiar with very simple video animation who'd like to work with me on a highly technical but simply explained video on what happens in the background.

I feel like there's a gap between users who want to understand the concept and the ones who would like to know what happens in the background without having to be a developer or reading technical documentation on each part of BTCPay.

pavlenex commented 5 years ago

The goal is to explain everything that happens from use creating an invoice, to BTCPay pushing the order in WooCommerce. Unfortunately I don't think I have enough technical knowledge to cover this. So if anyone wants to help by sketching and expanding this graph feel free to

architecture

Actually now that I think about it, if done well, it can be merged into one video "What is BTCPay and how it works".

britttttk commented 5 years ago

@bitcoinshirt I love this idea. These diagrams are the most clear to me as to what BTCPay is/does and in my experience, people have been very receptive to them. I can work with you to explain it. I would also like to explain docker architecture too. I know nothing about video making or editing but I can write up some content for you or someone else to put in a video.

image

pavlenex commented 5 years ago

Yes, the graph you posted is much better. However, it's from a developers perspective, I'd like us to create one from a user perspective.

  1. Buyer comes to the store and buys the item.
  2. BTCPay Generates the invoice (how it generates the invoice)
  3. The customer selects the coin and pays the item (he can pay the invoice in one currency or more)
  4. In WooCommerce merchant sees that order
  5. Coins are in Bitcoin wallet
  6. BTCPay tracks the payment through NBXplorer and alerts the seller.
  7. NBXPlorer tells merchant when the invoice is fully paid and updates the status in BTCPay which then alerts the store owner that the item is ready to be shipped.

This above pretty simplified, but you get the point. Let's work on this one together then.

britttttk commented 5 years ago
  1. Buyer comes to the store and buys the item.

Buyer presses the pay button, which tells the merchant's BTCPay to produce an invoice for the sale.

  1. BTCPay Generates the invoice (how it generates the invoice)

BTCPay generates an invoice from the user's selection (total cost of the sale) and from the merchant's store settings. The store settings specify payment tolerances, invoice expiration time, coin types accepted and confirmation settings, etc.

BTCPay creates an unused address, derived from the merchant's receiving wallet xpub and displays it in the invoice, as a QR code (or text). BTCPay stores this address with the associated network as a ScriptPubKey. It stores this in the merchant's database with the associated invoice Id.

  1. The customer selects the coin and pays the item (he can pay the invoice in one currency or more)

User pays the invoice by sending coins to the invoice address (transaction is sent over the P2P network).

  1. BTCPay tracks the payment through NBXplorer and alerts the seller about the payment status.

The merchant's node is a member of the P2P network. It receives transaction information as soon as it has been propagated to the merchant's node from the rest of the network.

BTCPay uses it's own internal blockchain explorer called NBXplorer, to look for transactions in the blockchain which send payments to the merchant's xpub derived addresses. NBXplorer verifies a matching payment by checking the associated ScriptSig, Witness and ScriptPubKey.

NBXplorer tells BTCPay that the requested payment associated with the Invoice Id has been paid. The invoice appears as paid to the buyer.

  1. In WooCommerce merchant sees that order

BTCPay notifies WooCommerce that the invoice status is paid. I'm not positive on where this step is. If you see it before the tx conf requirement has been met, then it's here, else it's below step 7.

  1. Coins are in Bitcoin wallet

NBXplorer tells BTCPay that the coins associated with the Invoice Id now belong to the merchant. The coins appear in the merchant's wallet. I'm not positive on where this step is. If you see it before the tx conf requirement has been met, then it's here, else it's below step 7.

  1. NBXplorer tells the merchant when the invoice is fully paid and updates the status in BTCPay which then alerts the store owner that the item is ready to be shipped.

The merchant chooses the number of confirmations which are required for the payment to be considered complete. This usually ranges between 1 and 6 confirmations, depending on merchant preferences. BTCPay is notified by NBXplorer when the payment is associated with a Block Id with the desired number of confirmations.

BTCPay changes the payment status from Paid to Confirmed. The merchant can see the status of all invoice payments under their admin account. When the status of the invoice is Confirmed, the item is ready to be shipped.

(It's from the perspective of the user being the merchant.)

Eskyee commented 5 years ago

Very clear and simple to understand!! Great job britkelly 🙌bitcoinshirt !!

pavlenex commented 5 years ago

Great overview @britttttk I'll begin working on animating the architecture, then we'll tackle the rest accordingly.

pavlenex commented 5 years ago

Hm, well in all honesty, our how to video will include some basics about architecture behind BTCPay and there's now a new video which goes down the rabbit hole, so I'm closing it, since any further effort will be duplication of work.