Improve docs.

CHANGES

@@ -3,6 +3,7 @@ Version xxxx
 
 * rewrite of ecdsa package
 * change how ScriptNullData works (arbitrary data now allowed after OP_RETURN)
+* API moved under pycoin.symbols.*.network
 
 
 Version 0.80

README.md

@@ -5,28 +5,25 @@
 pycoin -- Python Cryptocoin Utilities
 =====================================
 
-This is an implementation of a bunch of utility routines that may be useful when dealing with bitcoin and some
+The pycoin library implements many utilities useful when dealing with bitcoin and some bitcoin-like
 alt-coins. It has been tested with Python 2.7, 3.6 and 3.7.
 
 See also [pycoinnet](http://github.com/richardkiss/pycoinnet/) for a library that speaks the bitcoin protocol.
 
 Documentation at [readthedocs](http://pycoin.readthedocs.io/en/latest/)
 
 
-High Level
-==========
-
 Networks
 --------
 
-As of 0.9, pycoin supports many coins to various degrees via the "network" class. Since many features
+As of 0.9, pycoin supports many coins to various degrees via the "network" class. Since specifications
 vary based on the network (for example, bitcoin mainnet addresses start with a "1", but testnet
 addresses start with an "m" or "n"), all API descends from a network object. Everything related to a
 particular network is scoped under this class.
 
 Bitcoin has the highest level of support, including keys, transactions, validation of signed transactions, and
-signing unsigned transactions, including partial signing of multisig. These are in level of increasing
-difficulty, so features for other coins will likely be supported in that order.
+signing unsigned transactions, including partial signing of multisig transactions. These are in level of
+increasing complexity, so features for other coins will likely be supported in that order.
 
 There are two main ways to get a network:
 
@@ -38,17 +35,18 @@ OR
 
 ```
 from pycoin.networks.registry import network_for_netcode
-
 network = network_for_netcode("BTC")
 ```
 
 
 Keys
 ----
 
-You can create a new private key.
+You can create a private key and get the corresponding address.
 
 ```
+from pycoin.symbols.btc import network
+
 key = network.keys.private(secret_exponent=1)  # this is a terrible key because it's very guessable
 print(key.wif())
 print(key.sec())
@@ -59,53 +57,39 @@ same_key = network.parse.private(key.wif())
 print(same_key.address())
 ```
 
+
 BIP32
 -----
 
 You can create a BIP32 key.
 
 ```
 key = network.keys.bip32_seed(b"foo")  # this is a terrible key because it's very guessable
+print(key.hwif(as_private=1))
 print(key.hwif())
 print(key.wif())
 print(key.sec())
 print(key.address())
 ```
 
+You can parse a BIP32 key.
 
-The class pycoin.key.Key contains a convenience Key class that will parse the base58 representation of a BIP 32
-wallet [BIP0032] or a WIF or a bitcoin (or altcoin) address, and convert downwards.
+```
+key = network.parse.bip32("xprv9s21ZrQH143K31AgNK5pyVvW23gHnkBq2wh5aEk6g1s496M"
+      "8ZMjxncCKZKgb5jZoY5eSJMJ2Vbyvi2hbmQnCuHBujZ2WXGTux1X2k9Krdtq")
+print(key.hwif(as_private=1))
+print(key.hwif())
+print(key.wif())
+print(key.sec())
+print(key.address())
+```
 
 WARNING: be extremely careful giving out public wallet keys. If someone has access to a private wallet key P, of
 course they have access to all descendent wallet keys of P. But if they also have access to a public wallet key K
 where P is a subkey of K, you can actually work your way up the tree to determine the private key that corresponds
 to the public wallet key K (unless private derivation was used at some point between the two keys)! Be sure you
 understand this warning before giving out public wallet keys!
 
-`pycoin.key.Key`
----------------
-
-```
-Key(hierarchical_wallet=None, 
-    secret_exponent=None,
-    public_pair=None, 
-    hash160=None, 
-    prefer_uncompressed=None, 
-    is_compressed=True, 
-    netcode)
-```
-
-Specify one of "hierarchical_wallet, secret_exponent, public_pair or hash160" to create a `Key`.
-
-Or
-
-`Key.from_text(b58_text)` accepts an address (bitcoin or other), a WIF, or a BIP32 wallet string and yield a Key.
-
-`Key.from_sec(sec)` creates a Key from the SEC bytestream encoding of a public pair.
-
-
-pycoin.key.BIP32Node (formerly pycoin.wallet.Wallet) provides a BIP32 hierarchical wallet.
-
 Much of this API is exposed in the `ku` command-line utility. See also [COMMAND-LINE-TOOLS.md](./COMMAND-LINE-TOOLS.md).
 
 See [BIP32.txt](./BIP32.txt) for more information.
@@ -114,12 +98,6 @@ See [BIP32.txt](./BIP32.txt) for more information.
 Transactions
 ------------
 
-pycoin.tx.Tx is a class that wraps a bitcoin transaction. You can create, edit, sign, or validate a transaction using
-methods in this class.
-
-You can also use `pycoin.tx.tx_utils` which has `create_tx` and `create_signed_tx`, which gives you a
-very easy way to create signed transactions.
-
 The command-line utility `tx` is a Swiss Army knife of transaction utilities. See also [COMMAND-LINE-TOOLS.md](./COMMAND-LINE-TOOLS.md).
 
 
@@ -151,9 +129,6 @@ The command-line utility `block` will dump a block in a human-readable format. F
 `pycoin.block`, which includes the object `Block` which will parse and stream the binary format of a block.
 
 
-Low Level
-=========
-
 ECDSA Signing and Verification
 ------------------------------
 
@@ -166,38 +141,12 @@ There are a handful of functions: you can do things like create a signature, ver
 pair from the secret exponent, and flush out the public pair from just the x value (there are two possible values
 for y of opposite even/odd parity, so you include a flag indicating which value for y you want).
 
+The `pycoin.ecdsa.native` module looks for both OpenSSL and libsecp256k1 (with hints from
+`PYCOIN_LIBCRYPTO_PATH` and `PYCOIN_LIBSECP256K1_PATH`) and calls out to these libraries if
+they are present to accelerate ecdsa operations. Set `PYCOIN_NATIVE` to `openssl`,
+`secp256k1` or `none` to tweak this.
 
-Encoding
---------
-
-The `pycoin.encoding` module declares some conversion utilities useful when dealing with Bitcoin. Important
-structures include:
-
-* base58 (the encoding used for Bitcoin addresses)
-* hashed base58 (with a standard checksum)
-* Bitcoin hashes (double sha256, ripemd160/sha256, known as "hash160")
-* Bitcoin addresses
-* WIF (Wallet import format)
-* SEC (the gross internal format of public keys used by OpenSSL), both compressed and uncompressed
-
-
-Users
------
-
-Here's a partial list of users of pycoin:
-
- * [GreenAddress](https://greenaddress.it/)
- * [Coinkite](https://coinkite.com/)
- * [Wall of Coins](https://wallofcoins.com/)
- * [Blockonomics](https://www.blockonomics.co/)
-
-Email me at him@richardkiss.com to be added to this list.
-
-
-Too Slow?
----------
-As of v0.60, there is experimental code that will call into OpenSSL for two slow functions.
-To enable this, set (and export) environment variable PYCOIN_NATIVE=openssl. Example:
+Example:
 
 ```
 $ PYCOIN_NATIVE=openssl

TESTING.txt

@@ -1,8 +1,6 @@
-The pycoin library uses tox https://testrun.org/tox/latest/ to test rapidly on different versions of python.
+Although pycoin has no dependencies, if you want to hack on it, it's recommended that you to install py.test in your development virtualenv.
 
-Although pycoin has no dependencies, if you want to hack on it, it's recommended that you to install py.test and tox in your development virtualenv.
-
-$ pip install tox pytest
+$ pip install pytest
 
 To run just a subset of tests for features under development do something like:
 

docs/api.rst

@@ -0,0 +1,62 @@
+pycoin API
+==========
+
+Note
+
+    pycoin started out as a loose collection of utilities, and is slowly evolving to be
+    a more cohesive API.
+
+
+Networks
+--------
+
+A "network" is a particular coin, such as Bitcoin Mainnet or Bitcoin Testnet. There
+are two main ways to fetch a network::
+
+    from pycoin.symbols.btc import network
+
+or ::
+
+    from pycoin.networks.registry import network_for_netcode
+    network = network_for_netcode("BTC")
+
+These are the starting points. Nearly all API for a network can be accessed by drilling down
+below the network object.
+
+Some useful network attributes include:
+
+    network.Tx
+        the class for a transaction
+
+    network.Block
+        the class for a block
+
+    network.message
+        message api, to pack and parse messages used by bitcoin's peer-to-peer protocol
+
+    network.keychain
+        an object to aggregate private key information, useful for signing transactions
+
+    network.parse
+        api for parsing human-readable items like keys, WIFs, addresses
+
+    network.contract
+        api for creating standard scripts in bitcoin
+
+    network.address
+        includes for_script API for turning a TxOut puzzle script into an address
+
+    network.keys
+        api for creating private keys, public keys, and hierarchical keys, both BIP32 and Electrum
+
+    network.msg
+        api for signing messages and verifying signed messages
+
+    network.validator
+        api for validating whether or not transactions are correctly signed
+
+    network.tx_utils
+        shortcuts for building and signing transactions
+
+    network.who_signed
+        utilities to determine which public keys have signed partially signed multisig transactions