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 :py:class:`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.

#. Cherrypy http://www.cherrypy.org (for webserver). To install::
        
       sudo easy_install cherrypy

#. 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 :ref:`servercom`)

.. _servercom:

Instructor only server commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The examples assume the following:

#. 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
   :py:func:`coinexplorer.check_password` for more info on how to change
   the default password.  

#. 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
--------

#. Walk through the data structures in :py:mod:`coins`. Have
   the students write their private key as a :py:class:`coins.PrivateKey`

#. Use the RSA keys from Thursday to implement the function
   :py:func:`coins.tx_sig` to sign a transaction.

#. Create a :py:class:`coins.Block` (in local) with junk information and
   explain how mining works.

#. Mine as instructor the genesis block.

#. Have the groups mine one or two blocks to get some coins.

#. Stop the server (or put in readonly mode)

#. 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.

#. 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)

#. Start the server. Change the difficulty to something higher, maybe 5,
   to avoid having groups do only mining and no transactions!

#. Have fun mining, buy/sell stuff using coins!