drand.py¶
Python client to query a drand network for publicly verifiable, unbiased, and unpredictable random values.
To learn more about drand see drand’s documentation.
WARNING: This software is currently only, strictly, and purely for experimental purposes. It was developed for prototyping and experimenting with the drand network, which is itself still experimental!
IMPORTANT: Currently only works with the drand server code
from the master
branch (as of March 8, 2020). To query the drand
test network (e.g.: League of Entropy) using Python you may try
drb-client.
Usage¶
Prerequisite: Run a local drand network¶
First, run a local drand network. See devnet/README.md for more details.
$ cd devnet
$ ./run.sh
Get the addresses of the drand servers
from drand.utils import get_addresses_from_group_file
group_file = 'devnet/data/group.toml'
addresses = get_addresses_from_group_file(group_file)
>>> addresses
['172.15.238.2:8084',
'172.15.238.3:8081',
'172.15.238.4:8080',
'172.15.238.6:8082',
'172.15.238.5:8083']
Query a drand server¶
import drand
Get the public key of the network (/api/info/distkey)¶
Each node has a public share of this group key.
distkey = await drand.get_distkey(addresses[0], tls=False)
>>> distkey
'9509e2c2a5d04776bedce40839341375c89aa34a0372a1db273f562d89050b4ae54a76a276a26580166b0cd91e63f909'
Get and verify a random value (/api/public)¶
The verification means verifying that the “randomness” value is the hash of the signature, and that the signature is valid for the public key (distkey) and the the message (round + previous)
res = await drand.get_and_verify(
addresses[3], distkey=distkey, tls=False,
)
>>> res
{'round': 73,
'previous': 'b894ccc3859d1fb6d2ce6722b7195d359fbe6b0a387a3693e539e4957f1c69025936919fff3bd89a303ccfbcb929aae10eb68172997bdc84ccc6295dd21903a77994a116e203514935e9e25bf3f830cb00e6546470260f9beab65a5e389050bd',
'signature': '817254f9267e5345f5160a794ad5ffca0a9a2295cbfedc8c3d19215f91c8ccd07faa8354564d18159905477757c21f8a05140761ab5eb7b1d622ef5b62d64cdecf7f5c1e3d06d7ac016e16c4bfaddc4b27985625d32cd73e650e8fb7ea8dccf0',
'randomness': '66c3554bc0927a4ccbfdd73856071be792e3ddec7c27193d2f2f4d482c78b6b2'}
Get a random value for round 5
res = await drand.get_and_verify(
addresses[3], distkey=distkey, tls=False, round_=5
)
>>> res
{'round': 5,
'previous': 'aab94951afa626c26af5e08baa111fb98b1f5300556dc472f5e976a1ca4ccb074ecb7778cf18e08272fb40e1421a630914fe178ff1353d1247f58ecf4b82c417a55b8867e1f6eca4ca4bc548db2c2d1ce31c52e34f97c7f001774dc3fb6f22d5',
'signature': 'ad3e4f0bf0ef93c2ced95c12e1e7b5d0adbc4791e5592a83ce6119e0b610b7de40786e639861aa62df9d3a01b0ac50f90c84b1b20c5cc0662774c324f03fda0a69f0625a54a0c4c066f3b441cb33a8782f88d53861a5d4d8035a96488e340141',
'randomness': 'baee3fd77cd09349325794f766c0c81c887987907ec2834ac09a8a46c2193747'}
Get random values for a range of rounds
import asyncio
from aiohttp import ClientSession
async def get_rands(rounds):
async with ClientSession() as session:
tasks = []
for r in rounds:
tasks.append(
drand.get_and_verify(
addresses[4],
distkey=distkey,
session=session,
tls=False,
round_=r,
)
)
rands = await asyncio.gather(*tasks)
return rands
>>> asyncio.run(get_rands(range(2, 5)))
[{'round': 2,
'previous': 'b816229db70d3d7ab727bf0dc8ae3de27c354b066d5d931d3b6fb14d2fcf2433cd72f0271a9c47e7448de7c9589de2250d85ad444175cb616ca6fa0f6f0d376e608378c3688ee528631132c3c7928dfcec9f302a91daac51f1e87c98ebff78d5',
'signature': 'a515fe873dc18810d3aa446614786aa63567930f888c82b1edf66ea1e0f604c46948863dc349320219eba7d11a784813152719f0d6d471a08227c27393d14eb02a8df7c18cb48f5df6918510948e6170922ad5164da0965c47b63ba80ee7a682',
'randomness': '185963dba81d25158bb60bc0bc16823b7687a87cca739a6a9e4a2bccac16c5f0'},
{'round': 3,
'previous': 'a515fe873dc18810d3aa446614786aa63567930f888c82b1edf66ea1e0f604c46948863dc349320219eba7d11a784813152719f0d6d471a08227c27393d14eb02a8df7c18cb48f5df6918510948e6170922ad5164da0965c47b63ba80ee7a682',
'signature': '81d3a98e63e8480d61e64ef7126dea5f83cc98303d43c66221f15edab8dc4e02d7c229a645f107ee76e0de11673569810f18fc6fd5d27e5a50aa0cbf95e90f1d6c750715a9e4b79ec8a5982421e2a324864d1471e36a0af3c773864923a3e3b4',
'randomness': '0b7d6c4a465b4cd6099f4a888ea355c2173a8108ad749a7790c64592a9c2ee9f'},
{'round': 4,
'previous': '81d3a98e63e8480d61e64ef7126dea5f83cc98303d43c66221f15edab8dc4e02d7c229a645f107ee76e0de11673569810f18fc6fd5d27e5a50aa0cbf95e90f1d6c750715a9e4b79ec8a5982421e2a324864d1471e36a0af3c773864923a3e3b4',
'signature': 'aab94951afa626c26af5e08baa111fb98b1f5300556dc472f5e976a1ca4ccb074ecb7778cf18e08272fb40e1421a630914fe178ff1353d1247f58ecf4b82c417a55b8867e1f6eca4ca4bc548db2c2d1ce31c52e34f97c7f001774dc3fb6f22d5',
'randomness': '2dcc3e4894c91d092cdbcbe6daf777c5cbe2e6948cf8a18693009762273d52aa'}]
Acknowledgments¶
The initial code interface for this package was based on the JavaScript client drandjs.
The devnet
directory under the root of the repo was taken
from the demo directory under the drand/drand repository, tree
with commit hash a40dc25e1aec6822a79c72b4aaca12e65c700f01. The
code was brought over using git-filter-repo in order to preserve the
commit history.
The original boilerplate for this package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
Thanks to IC3 (The Initiative For Cryptocurrencies & Contracts) for supporting this work.
Reminder & Future Work¶
This software is currently only, strictly, and purely for experimental purposes. It was developed for prototyping and experimenting with the drand network, which is itself still experimental!
The Github issue tracker will be used to plan and manage future work.