Quickstart¶
Installation¶
This is the quickstart guide for Trinity. If you only care about running a Trinity node, this guide will help you to get things set up. If you plan to develop on top of Py-EVM or contribute to the project you may rather want to checkout the Contributing Guide which explains how to set everything up for development.
Installing on Ubuntu¶
Trinity requires Python 3.6 as well as some tools to compile its dependencies. On Ubuntu, the
python3.6-dev
package contains everything we need. Run the following command to install it.
apt-get install python3.6-dev
Trinity is installed through the pip package manager, if pip isn’t available on the system already,
we need to install the python3-pip
package through the following command.
apt-get install python3-pip
Note
Optional: Often, the best way to guarantee a clean Python 3 environment is with
virtualenv. If we don’t have virtualenv
installed
already, we first need to install it via pip.
pip install virtualenv
Then, we can initialize a new virtual environment venv
, like:
virtualenv -p python3 venv
This creates a new directory venv
where packages are installed isolated from any other global
packages.
To activate the virtual directory we have to source it
. venv/bin/activate
Trinity uses Snappy Compression and hence needs the Snappy Library to be pre-installed on the system. It can be installed through the following command.
apt-get install libsnappy-dev
Finally, we can install the trinity
package via pip.
pip3 install -U trinity
Installing on macOS¶
First, install LevelDB and the latest Python 3 with brew:
brew install python3 leveldb
Note
Optional: Often, the best way to guarantee a clean Python 3 environment is with
virtualenv. If we don’t have virtualenv
installed
already, we first need to install it via pip.
pip install virtualenv
Then, we can initialize a new virtual environment venv
, like:
virtualenv -p python3 venv
This creates a new directory venv
where packages are installed isolated from any other global
packages.
To activate the virtual directory we have to source it
. venv/bin/activate
Now, install Snappy Library with brew as follows:
brew install snappy
Finally, install the trinity
package via pip:
pip3 install -U trinity
Installing through Docker¶
Trinity can also be installed using Docker
which can be a lightweight alternative where no
changes need to be made to the host system apart from having Docker
itself installed.
Note
While we don’t officially support Windows just yet, running Trinity through Docker
is a great
way to bypass this current limitation as Trinity can run on any system that runs Docker
with
support for linux containers.
Using Docker
we have two different options to choose from.
1. Run an existing official image
This is the default way of running Trinity through Docker
. If all we care about is running
a Trinity node, using one of the latest released versions, this method is perfect.
Run:
docker run -it ethereum/trinity
Alternatively, we can run a specific image version, following the usual docker version schema.
docker run -it ethereum/trinity:0.1.0-alpha.13
2. Build your own image
Alternatively, we may want to try out a specific (unreleased) version. In that case, we can create our very own image directly from the source code.
make create-docker-image version=my-own-version
After the image has been successfully created, we can run it by invoking:
docker run -it ethereum/trinity:my-own-version
Running Trinity¶
After Trinity is installed we should have the trinity
command available to start it.
trinity
While it may take a couple of minutes before Trinity can start syncing against the Ethereum mainnet, it should print out some valuable information right away which should look something like this. If it doesn’t please file an issue to help us getting that bug fixed.
INFO 05-29 01:57:02 main
______ _ _ __
/_ __/____(_)___ (_) /___ __
/ / / ___/ / __ \/ / __/ / / /
/ / / / / / / / / / /_/ /_/ /
/_/ /_/ /_/_/ /_/_/\__/\__, /
/____/
INFO 05-29 01:57:02 main Trinity/0.1.0a4/linux/cpython3.6.5
INFO 05-29 01:57:02 main network: 1
INFO 05-29 01:57:02 ipc IPC started at: /root/.local/share/trinity/mainnet/jsonrpc.ipc
INFO 05-29 01:57:02 server Running server...
INFO 05-29 01:57:07 server enode://09d34ecb0de1806ab0e68cb2d822b967292dc021df06aab9a55aa4d2e1b2e04ae73560137407a48073286026e12dd60d265a1b1ae0505e44e60d55cea9c7b100@0.0.0.0:30303
INFO 05-29 01:57:07 server network: 1
INFO 05-29 01:57:07 peer Running PeerPool...
INFO 05-29 01:57:07 sync Starting fast-sync; current head: #0
Once Trinity successfully connected to other peers we should see it starting to sync the chain.
INFO 05-29 02:23:13 chain Starting sync with ETHPeer <Node(0xaff0@90.114.124.196)>
INFO 05-29 02:23:14 chain Imported chain segment in 0 seconds, new head: #191 (739b)
INFO 05-29 02:23:15 chain Imported chain segment in 0 seconds, new head: #383 (789c)
INFO 05-29 02:23:16 chain Imported chain segment in 0 seconds, new head: #575 (a1d0)
INFO 05-29 02:23:17 chain Imported chain segment in 0 seconds, new head: #767 (aeb6)
Running as a light client¶
Warning
It may take a very long time for Trinity to find an LES node with open slots. This is not a bug with trinity, but rather a shortage of nodes serving LES. Please consider running your own LES server to help improve the health of the network.
Use the --sync-mode=light
flag to instruct Trinity to run as a light node.
Ropsten vs Mainnet¶
Trinity currently only supports running against either the Ethereum Mainnet or
Ropsten testnet. Use --ropsten
to run against Ropsten.
trinity --ropsten
Connecting to preferred nodes¶
If you would like to have Trinity prioritize connecting to specific nodes, you
can use the --preferred-node
command line flag. This flag takes an enode
URI as a single argument and will instruct Trinity to prioritize connecting to
this node.
trinity --preferred-node enode://a41defa74e8d9d4152699cb9a0d195377da95833769ad6b386092ac3b16c184eb4ef4b4f02889e0b5097ff50fb5847ba99694d40b61f911cdea07b444b00e676@127.0.0.1:30304
Using --preferred-node
is a good way to ensure Trinity running in
sync-mode=light
mode connects to known peers who serve LES.
Retrieving Chain information via web3¶
While just running trinity
already causes the node to start syncing, it doesn’t let us interact
with the chain directly (apart from the JSON-RPC API).
However, we can attach an interactive shell to a running Trinity instance with the
attach
subcommand. The interactive ipython
shell binds a
web3 instance to the w3
variable.
trinity attach
Now that Trinity runs in an interactive shell mode, let’s try to get some information about the
latest block by calling w3.eth.getBlock('latest')
.
In [9]: w3.eth.getBlock('latest')
Out[9]:
AttributeDict({'difficulty': 743444339302,
'extraData': HexBytes('0x476574682f4c5649562f76312e302e302f6c696e75782f676f312e342e32'),
'gasLimit': 5000,
'gasUsed': 0,
'hash': HexBytes('0x1a8487dfb8de7ee27b9cca30b6f3f6c9676eae29c10eef39b86890ed15eeed01'),
'logsBloom': HexBytes('0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
'mixHash': HexBytes('0xf693b8e4bc30728600da40a0578c14ddb7ad08a64e329a19d9355d5665588aef'),
'nonce': HexBytes('0x7382884a72533c59'),
'number': 12479,
'parentHash': HexBytes('0x889c36c51463f100cf50ec2e2a92886aa7ebb3f99fa8c817343214a92f967a29'),
'receiptsRoot': HexBytes('0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'),
'sha3Uncles': HexBytes('0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'),
'stateRoot': HexBytes('0x6ad1ecb7d516c679e7c476956159051fa32848f3ba631a47c3fb72937ed86987'),
'timestamp': 1438368997,
'transactionsRoot': HexBytes('0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'),
'miner': '0xbb7B8287f3F0a933474a79eAe42CBCa977791171',
'totalDifficulty': 3961372514945562,
'uncles': [],
'size': 544,
'transactions': []})
You can attach to an existing Trinity process using the attach
comand.
trinity attach
For a list of JSON-RPC endpoints which are expected to work, see this issue: https://github.com/ethereum/py-evm/issues/178
Warning
Trinity is currently in public alpha. Keep in mind:
- It is expected to have bugs and is not meant to be used in production
- Things may be ridiculously slow or not work at all
- Only a subset of JSON-RPC API calls are currently supported