For instructors only

Here is the list of all Python files that are used on each day.

  • Monday: nothing
  • Tuesday: translit.py
  • Wednesday: nothing
  • Thursday: primes.py
  • Friday: primes.py, coins.py, coins_client.py, pubkeys.py. The pubkeys.py module is not provided. It defines a list pubkeys with elements being the public keys of all the groups (from Thursday) as objects of type coins.PublicKey. To find the index of the group in the table simply do i % 7 where i is the group number from 1 through 7 (so that Group 7’s public key is pubkeys.pubkeys[0]). A public key for the instructor may also be included as pubkeys.instructor.

The coinexplorer server

The purpose of this server is to display the blockchain, receive pending transactions, new blocks and report to clients which transactions are pending.

Required packages

Running the server requires to install a couple of things in python, and this usually requires administrator privileges. This is why these instructions are not (usually) for the students.

  1. Cherrypy http://www.cherrypy.org (for webserver). To install:

    sudo easy_install cherrypy

  2. Sphinx http://sphinx-doc.org (for documentation only). To install:

    sudo easy_install sphinx

    and you probably need to install the developper tools in Mac OS X (XCode) to have access to make. The doc can be generated by going to the directory doc and doing the command make html

Setting up the server

To run the server simply use the command:

python coinexplorer.py

The file crypto.conf specifies the host and port where the server is to run. The default is:

[global]
server.socket_host = "127.0.0.1"
server.socket_port = 8080
server.thread_pool = 10

which means that the server can be accessed through http://127.0.0.1:8080/

Depending on the network configuration at the port, this may mean that the server only accepts connections that originate at the host itself. This is fine for testing but will not work in a class environment. To fix this, simply change sever.socket_host to the actual external hostname or external IP you are running from. On Unix, the following could help to determine your hostname:

echo $HOST

Persistence

The server will by default save all blocks to disk into files named block0.txt, block1.txt, etc... So it is safe to kill the server and restart it. The default behavior is that server attempts to read all the blocks that are in the directory where it is run, until it runs out of blocks. So if the last block that was saved is OK, the blockchain is not completely lost.

Warning

All pending transactions are lost and the difficulty is set to the difficulty of the last block after a restart.

The default name of the blocks can be changed to something else. Let’s say that we want to save the blocks in the files ./blocks/b0.txt, ./blocks/b1.txt, ... This can be achieved by launching the server with the option --prefix:

python coinexplorer.py --prefix ./blocks/b

If some blocks need to be ignored on launch (say the blocks after and including block7.txt are bad for some reason) then one can achieve this by launching the server with the --nblocks option:

python coinexplorer.py --nblocks 7

which will load only the first 7 blocks: block0.txt, ... , block6.txt and ignore the rest.

Finally, it may be desirable to launch the server in readonly mode, to inspect the data and make sure everything is fine before someone posts a new transaction or block:

python coinexplorer.py --readonly

The readonly mode can be disabled once the server is running from a web browser (see Instructor only server commands)

Instructor only server commands

The examples assume the following:

  1. The password has been set to KoalaBear. The default password is different, but even if you do not know it, it is easy to change in the file coinexplorer.py. See coinexplorer.check_password() for more info on how to change the default password.
  2. The server address:port is 127.0.0.1:8080. This should just work from the machine that the server is run from.

Warning

The password protection is very weak. The password is not sent through encrypted channels and will appear in clear in the browser history. So don’t let the students see the screen where the server is running. It is possible to show the code to the students, since the code contains only the md5 hash of the password.

To erase all pending transactions:

http://127.0.0.1:8080/erasepending?passwd=KoalaBear

To ALLOW posting:

http://127.0.0.1:8080/readonly?passwd=KoalaBear&enabled=0

To set the server to READONLY mode:

http://127.0.0.1:8080/readonly?passwd=KoalaBear&enabled=1

To set the current difficulty to e.g. 3 (i.e. any blocks with a different difficulty than 3 will be rejected):

http://127.0.0.1:8080/setdifficulty?d=3&passwd=KoalaBear

Setting up the client

All that is need is to import coins_client and then set the string coins_client.base_url to the base url of the server. By the default this is set to "http://127.0.0.1:8080/"

Note: the URL should include the trailing slash.

For a sample conversation with the server see the file test_coinexplorer.py.

Workflow

  1. Walk through the data structures in coins. Have the students write their private key as a coins.PrivateKey
  2. Use the RSA keys from Thursday to implement the function coins.tx_sig() to sign a transaction.
  3. Create a coins.Block (in local) with junk information and explain how mining works.
  4. Mine as instructor the genesis block.
  5. Have the groups mine one or two blocks to get some coins.
  6. Stop the server (or put in readonly mode)
  7. Give away some small articles to each group (probably between 3 and 7 articles of the same kind per group). Having different kinds of articles should make the groups want to buy or sell their articles. It’s probably a good idea to assign the lots of articles at random to the groups.
  8. Explain how to get the wallet and create a new transaction. The students need to figure out how to sign it! This explains better how a transaction looks and why we need to allow for multiple inputs/outputs (and why a “change” transaction output is needed)
  9. Start the server. Change the difficulty to something higher, maybe 5, to avoid having groups do only mining and no transactions!
  10. Have fun mining, buy/sell stuff using coins!