Web3.py: Better documentation for signing and sending transactions

[kclowes]

What was wrong?

There are three different ways to sign and send transactions:

1. a user can use an unlocked account and then w3.eth.sendTransaction,
2. Building a transaction, manually sign, then send with w3.eth.sendRawTransaction.
3. The sign_and_send_middleware.

It would be nice to detail the steps to use each one and list reasons for using it over the others

[marcgarreau]

don't think I know when best to use each yet, but will take a stab at this.

[pipermerriam]

This is by no means exhaustive but it should be an adequate starting point. I suspect there is a visualization that could make the data below easier to ingest and understand. Maybe something as simple as a table showing the various methods and their strengths/weaknesses

send_and_sign_middleware

• benefits:
  
  
  
  • Concise code and minimal boilerplate.
  
  
  • Ability to use same code for both cases of having key available locally or unlocked key being managed by RPC prodiver
  
  
• drawbacks:
  
  
  
  • Must have private key available locally.
  
  

w3.eth.sendTransaction(...)
contract.functions.myFunction().transact(...)

w3.eth.sendTransaction

• benefits
  
  
  
  • Simplest way that delegates key management to the RPC node
  
  
• drawbacks
  
  
  
  • Account unlocking complexity:
  
  
  • Bad security if account always unlocked
  
  
  • Worse UX if you have to constantly unlock the account before sending.
  
  

w3.eth.sendRawTransaction

• benefits
  
  
  
  • Most flexible. Allows signing by things like hardware wallets. Facilitates advanced use cases.
  
  
  • Facilitates broadcasting via centralized providers like infura (could be used for anonymous txn broadcasting).
  
  
• drawbacks
  
  
  
  • Confusing if you don't understand the mechanics well.
  
  
  • Boilerplate heavy and has multiple steps where users can make mistakes.
  
  

[marcgarreau]

Spitballed a couple ideas (including a table view), but as a user, I think I most want to know when to reach for each. Looking for some clarity on the middleware, though. Current idea is to add something like this to the Examples page:

Making transactions
-------------------

There are a few options for making transactions, each with trade-offs.

1. ``w3.eth.sendTransaction``(docs link)
   Use this method when: 
   - you want to send Ether from one account to another.

2. ``w3.eth.sendRawTransaction``(docs link)
   Use this method when: 
   - you want to sign the transaction elsewhere, e.g., a hardware wallet.
   - you want to broadcast a transaction through another provider, e.g., Infura.
   - you have some other advanced use case that requires more flexibility.

3. ``send_and_sign_middleware``(docs link)
   Use this method when: 
   - TODO
   - <how often do you manually interact with this middleware?>
   - <it gets applied to sendTransaction and contract method executions?>

I anticipate adding a note on each method about whether keys must be located locally or not.