FamaMonetae

About
-----

FamaMonetae encodes/decodes data via the Bitcoin protocol.

FamaMonetae depends on the python-bitcoinlib and python-bitcoinrpc
libraries.

Execution
---------

FamaMonetae provides the several functions to encode and decode data
via the Bitcoin protocol. Bitcoin transactions can be interpreted as
data encoded as Bitcoin output addresses.

The hearRumor function takes three string arguments: the Bitcoin
transaction ID, the url to an HTTP JSON-RPC Bitcoin server, and the
filepath to store the decoded data.

For example, suppose the choosen Bitcoin transaction ID is
"8881a937a437ff6ce83be3a89d77ea88ee12315f37f7ef0dd3742c30eef92dba" and
the decoded data should be saved to a file called "rumor.dat" in the
current directory; a local HTTP JSON-RPC Bitcoin server is located at
127.0.0.1 on port 8332 and accessed using "user" as the username and
"pass" as the password. The following Python script will do:

        import famamonetae

        txid = ("8881a937a437ff6ce83be3a89d77ea88"
                "ee12315f37f7ef0dd3742c30eef92dba")
        service_url = "http://user:[email protected]:8332"
        rumor_file = "rumor.dat"

        famamonetae.hearRumor(txid, service_url, rumor_file)

After executing the Python script, the file "rumor.dat" will contain the
decoded data.

The speakRumor function takes a single string argument: the filepath to
data for encoding.

For example, suppose the desired data for encoding is stored in a file
called "rumor.dat" in the current directory. The following Python script
will do:

        import famamonetae

        famamonetae.speakRumor("rumor.dat")

After executing the Python script, the standard output should display a
list of Bitcoin addresses which represent the data in the "rumor.dat"
file. Submitting a Bitcoin transaction with those Bitcoin addresses as
output addresses will store the encoded data in the Bitcoin blockchain.

It is important to note that the Bitcoin protocol expects an exactly
20-byte wide payload for each Bitcoin address. Since not all data sizes
are multiples of 20, FamaMonetae will pad the final payload with null
bytes if necessary; this means trailing null bytes not part of the
original data may be present when decoding a Bitcoin transaction.

Licensing
---------

FamaMonetae is free software released under version 3 of the GNU Affero
General Public License.

See the file COPYING for copying conditions.

Contact
-------

William Breathitt Gray <[email protected]>