Skip to content
Permalink
Browse files

Improve docs.

  • Loading branch information
richardkiss committed Apr 29, 2019
1 parent 1e8d0d9 commit de525455007a566df1bcf22a3b76efa1a2234d97
@@ -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
@@ -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
@@ -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:

@@ -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

0 comments on commit de52545

Please sign in to comment.
You can’t perform that action at this time.