Skip to content

Commit 1d27206

Browse files
committed
docs docs docs
1 parent 7a2bee6 commit 1d27206

17 files changed

+663
-357
lines changed

docs/chain.api.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. _chain-api:
2+
3+
Chain API
4+
=========
5+
6+
.. module:: populus.chain.base
7+
8+
.. py:class:: BaseChain
9+
10+
All chain objects inherit from the :class:`populus.chain.base.BaseChain` base
11+
class and expose the following API.
12+
13+
14+
.. py:attribute:: web3
15+
16+
Provides access to the :class:`~web3.Web3` instance that this chain is
17+
configured to use.
18+
19+
20+
.. py:attribute:: wait
21+
22+
Accessor for to the :ref:`Wait API <chain-wait>`.
23+
24+
25+
.. py:attribute:: store
26+
27+
Accessor for to the :ref:`Store API <chain-store>`.
28+
29+
30+
.. py:attribute:: registrar
31+
32+
Accessor for to the :ref:`Registrar API <chain-registrar>`.
33+
34+
35+
.. py:attribute:: provider
36+
37+
Accessor for to the :ref:`Provider API <chain-provider>`.

docs/chain.contracts.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. _chain-contracts:
2+
3+
4+
Introduction to Chains
5+
======================
6+

docs/chain.introduction.rst

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
.. _chain-introduction:
2+
3+
Introduction to Chains
4+
======================
5+
6+
.. contents:: :local:
7+
8+
9+
Introduction
10+
------------
11+
12+
Populus has the ability to run and/or connect to a variety of blockchains for
13+
you, both programatically and from the command line.
14+
15+
16+
Transient Chains
17+
^^^^^^^^^^^^^^^^
18+
19+
Populus can run two types of transient chains.
20+
21+
* ``tester``
22+
23+
A test EVM backed blockchain.
24+
25+
26+
* ``testrpc``
27+
28+
Runs the ``eth-testrpc`` chain which implements the full JSON-RPC interface
29+
backed by a test EVM.
30+
31+
32+
* ``temp``
33+
34+
Runs a blockchain backed by the go-ethereum ``geth`` client. This chain
35+
will use a temporary directory for it's chain data which will be cleaned up
36+
and removed when the chain shuts down.
37+
38+
39+
Local Chains
40+
^^^^^^^^^^^^
41+
42+
Local chains can be setup within your ``populus.json`` file. Each local chain
43+
stores its chain data in the ``populus.Project.blockchains_dir``
44+
and persists it's data between runs.
45+
46+
Local chains are backed by the go-ethereum ``geth`` client.
47+
48+
49+
Public Chains
50+
^^^^^^^^^^^^^
51+
52+
Populus can run both the main and ropsten public chains.
53+
54+
* ``mainnet``
55+
56+
With ``$ populus chain run mainnet`` populus will run the the go-ethereum
57+
client for you connected to the main public ethereum network.
58+
59+
60+
* ``ropsten``
61+
62+
With ``$ populus chain run ropsten`` populus will run the the go-ethereum
63+
client for you connected to the ropsten testnet public ethereum network.
64+
65+
66+
Running from the command line
67+
-----------------------------
68+
69+
The ``$ populus chain`` command handles running chains from the command line.
70+
71+
.. code-block:: bash
72+
73+
$ populus chain
74+
Usage: populus chain [OPTIONS] COMMAND [ARGS]...
75+
76+
Manage and run ethereum blockchains.
77+
78+
Options:
79+
-h, --help Show this message and exit.
80+
81+
Commands:
82+
reset Reset a chain removing all chain data and...
83+
run Run the named chain.
84+
85+
86+
Running programatically from code
87+
---------------------------------
88+
89+
The ``populus.Project.get_chain(chain_name, chain_config=None)`` method returns
90+
a ``populus.chain.Chain`` instance that can be used within your code to run any
91+
populus chain.
92+
93+
Lets look at a basic example of using the ``temp`` chain.
94+
95+
.. code-block:: python
96+
97+
>>> from populus import Project
98+
>>> project = Project()
99+
>>> with project.get_chain('temp') as chain:
100+
... print('coinbase:', chain.web3.eth.coinbase)
101+
...
102+
...
103+
coinbase: 0x16e11a86ca5cc6e3e819efee610aa77d78d6e075
104+
>>>
105+
>>> with project.get_chain('temp') as chain:
106+
... print('coinbase:', chain.web3.eth.coinbase)
107+
...
108+
...
109+
coinbase: 0x64e49c86c5ad1dd047614736a290315d415ef28e
110+
111+
112+
You can see that each time a ``temp`` chain is instantiated it creates a new
113+
data directory and generates new keys.
114+
115+
The ``testrpc`` chain operates in a similar manner in that each time you run
116+
the chain the EVM data is fully reset. The benefit of the ``testrpc`` server
117+
is that it starts quicker, and has mechanisms for manually resetting the chain.
118+
119+
120+
Here is an example of running the ``tester`` blockchain.
121+
122+
123+
.. code-block:: python
124+
125+
>>> from populus import Project
126+
>>> project = Project()
127+
>>> with project.get_chain('tester') as chain:
128+
... print('coinbase:', chain.web3.eth.coinbase)
129+
... print('blockNumber:', chain.web3.eth.blockNumber)
130+
... chain.mine()
131+
... print('blockNumber:', chain.web3.eth.blockNumber)
132+
... snapshot_id = chain.snapshot()
133+
... print('Snapshot:', snapshot_id)
134+
... chain.mine()
135+
... chain.mine()
136+
... print('blockNumber:', chain.web3.eth.blockNumber)
137+
... chain.revert(snapshot_id)
138+
... print('blockNumber:', chain.web3.eth.blockNumber)
139+
...
140+
coinbase: 0x82a978b3f5962a5b0957d9ee9eef472ee55b42f1
141+
blockNumber: 1
142+
blockNumber: 2
143+
Snapshot: 0
144+
blockNumber: 4
145+
blockNumber: 2
146+
147+
The ``testrpc`` chain can be run in the same manner.

docs/chain.legacy.rst

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
Legacy Chain API
2+
================
3+
4+
Previously, chain objects provided an API for accessing your contract compile
5+
and deploy artifacts. This API was moved to the :ref:`Provider API <chain-provider>`
6+
in the :ref:`1.6.0 Release <v1.6.0-release-notes>`.
7+
8+
Access To Contracts
9+
-------------------
10+
11+
All chain objects present the following API for interacting with your project
12+
contracts.
13+
14+
.. warning::
15+
The ``Chain.get_contract_factory`` API has moved to the :ref:`Provider API
16+
<chain-provider>`. This function will be removed in subsequent releases.
17+
18+
- ``get_contract_factory(contract_name, link_dependencies=None, validate_bytecode=True)``
19+
20+
Returns the contract factory for the contract indicated by
21+
``contract_name`` from the chain's ``compiled_contracts``.
22+
23+
If provided, ``link_dependencies`` should be a dictionary that maps library
24+
names to their on chain addresses that will be used during bytecode
25+
linking.
26+
27+
If truthy (the default), ``validate_bytecode`` indicates whether the
28+
bytecode for any library dependencies for the given contract should be
29+
validated to match the on chain bytecode.
30+
31+
If your project has no project migrations then the data used for these
32+
contract factories will come directly from the compiled project contracts.
33+
34+
If your project has migrations then the data used to build your contract
35+
factories will be populutated as follows.:
36+
37+
#. The newest migration that has been run which deploys the requested
38+
contract.
39+
#. The newest migration which contains this contract in it's
40+
``compiled_contracts`` property
41+
#. The compiled project contracts.
42+
43+
44+
.. warning::
45+
The ``Chain.get_contract`` API has moved to the :ref:`Provider API
46+
<chain-provider>`. This function will be removed in subsequent releases.
47+
48+
- ``get_contract(contract_name, link_dependencies=None, validate_bytecode=True)``
49+
50+
Returns the contract instance indicated by the ``contract_name`` from the
51+
chain's ``compiled_contracts``.
52+
53+
The ``link_dependencies`` argument behaves the same was as specified in the
54+
``get_contract_factory`` method.
55+
56+
The ``validate_bytecode`` argument behaves the same way as specified in the
57+
``get_contract_factory`` with the added condition that the bytecode for the
58+
requested contract will also be checked.
59+
60+
.. note::
61+
62+
When using a ``TestRPCChain`` the ``get_contract`` method will lazily
63+
deploy your contracts for you. This lazy deployment will only work for
64+
simple contracts which do not require constructor arguments.
65+
66+
67+
.. warning::
68+
The ``Chain.is_contract_available`` API has moved to the :ref:`Provider API
69+
<chain-provider>`. This function will be removed in subsequent releases.
70+
71+
- ``is_contract_available(contract_name, link_dependencies=None, validate_bytecode=True, raise_on_error=False)``
72+
73+
Returns ``True`` or ``False`` as to whether the contract indicated by
74+
``contract_name`` from the chain's ``compiled_contracts`` is available
75+
through the ``Chain.get_contract`` API.
76+
77+
The ``link_dependencies`` argument behaves the same was as specified in the
78+
``get_contract_factory`` method.
79+
80+
The ``validate_bytecode`` argument behaves the same way as specified in the
81+
``get_contract_factory`` with the added condition that the bytecode for the
82+
requested contract will also be checked.
83+
84+
If ``raise_on_error`` is truthy, then the method will raise an exception
85+
instead of returning ``False`` for any of the failure cases.

docs/chain.provider.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. _chain-provider:

0 commit comments

Comments
 (0)