An example how to manage local private key using env (#2380)

* An example how to manage local private key using env

How to manage private keys using environment variable, how to generate them, and some security warnings.

* Fix extra period

Inserted by the editor?

* add content tweaks and newsfragment

Co-authored-by: Marc Garreau <[email protected]>

Author: miohtama

docs/web3.eth.account.rst

@@ -39,7 +39,7 @@ Hosted Private Key
   not your Ether" in the wise words of Andreas Antonopoulos.
 
 Some Common Uses for Local Private Keys
--------------------------------------------
+---------------------------------------
 
 A very common reason to work with local private keys is to interact
 with a hosted node.
@@ -55,6 +55,59 @@ Using private keys usually involves ``w3.eth.account`` in one way or another. Re
 or see a full list of things you can do in the docs for
 :class:`eth_account.Account <eth_account.account.Account>`.
 
+Read a private key from an environment variable
+-----------------------------------------------
+
+In this example we pass the private key to our Python application in an 
+`environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_.
+This private key is then added to the transaction signing keychain 
+with ``Signing`` middleware.
+
+If unfamiliar, note that you can `export your private keys from Metamask and other wallets <https://metamask.zendesk.com/hc/en-us/articles/360015289632-How-to-Export-an-Account-Private-Key>`_.
+
+.. warning ::
+
+  - **Never** share your private keys.
+  - **Never** put your private keys in source code.
+  - **Never** commit private keys to a Git repository.
+
+Example ``account_test_script.py``
+
+.. code-block:: python
+
+    import os 
+    from eth_account import Account
+    from eth_account.signers.local import LocalAccount
+    from web3.auto import w3
+    from web3.middleware import construct_sign_and_send_raw_middleware
+    
+    private_key = os.environ.get("PRIVATE_KEY")
+    assert private_key is not None, "You must set PRIVATE_KEY environment variable"
+    assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"
+    
+    account: LocalAccount = Account.from_key(private_key)
+    w3.middleware_onion.add(construct_sign_and_send_raw_middleware(account))
+    
+    print(f"Your hot wallet address is {account.address}")
+    
+Example how to run this in UNIX shell:
+
+.. code-block:: shell
+ 
+    # Generate a new 256-bit random integer using openssl UNIX command that acts as a private key.
+    # You can also do:
+    # python -c "from web3 import Web3; w3 = Web3(); acc = w3.eth.account.create(); print(f'private key={w3.toHex(acc.key)}, account={acc.address}')"
+    # Store this in a safe place, like in your password manager.
+    export PRIVATE_KEY=0x`openssl rand -hex 32` 
+    
+    # Run our script
+    python account_test_script.py
+    
+This will print::
+
+    Your hot wallet address is 0x27C8F899bb69E1501BBB96d09d7477a2a7518918
+
+  
 .. _extract_geth_pk:
 
 Extract private key from geth keyfile

newsfragments/2380.doc.rst

@@ -0,0 +1 @@
+Document reading private keys from environment variables