Initial release.
[robmyers:dogecode.git] / doc / dogecode-whitepaper.html
1 <h1 id="dogecode-white-paper-v0.1">Dogecode White Paper v0.1</h1>
2 <p><strong>Rob Myers <script type="text/javascript">
3 <!--
4 h='&#114;&#x6f;&#98;&#x6d;&#x79;&#x65;&#114;&#x73;&#46;&#x6f;&#114;&#x67;';a='&#64;';n='&#114;&#x6f;&#98;';e=n+a+h;
5 document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'">'+e+'<\/'+'a'+'>');
6 // -->
7 </script><noscript>&#114;&#x6f;&#98;&#32;&#x61;&#116;&#32;&#114;&#x6f;&#98;&#x6d;&#x79;&#x65;&#114;&#x73;&#32;&#100;&#x6f;&#116;&#32;&#x6f;&#114;&#x67;</noscript></strong></p>
8 <p><strong>23-12-2014</strong></p>
9 <h1 id="overview">Overview</h1>
10 <p>Dogecode (name to be finalized) is a system for representing computer programs using sequences of Dogeparty tokens in order to store, send, and execute their code via the Dogecoin blockchain.</p>
11 <h1 id="tokens">Tokens</h1>
12 <p>The encoding for programs is a minor variant of the &quot;Brainfuck&quot; programming language, chosen for its minimalism:</p>
13 <p><a href="http://en.wikipedia.org/wiki/Brainfuck">http://en.wikipedia.org/wiki/Brainfuck</a></p>
14 <p>Each Brainfuck programming language command is represented by an indivisible Dogeparty asset.</p>
15 <p>A single occurrence of a command in a program is represented by the sending of a single token, e.g. + is represented by sending 1 INCB tokens .</p>
16 <p>Multiple occurrences are represented by sending multiple tokens in a single transfer, e.g. +++++ is represented by sending 5 INCB tokens.</p>
17 <p>The order and quantities of sends are significant, not the total number of tokens held by an address or account.</p>
18 <h2 id="currently-used-tokens">Currently Used Tokens</h2>
19 <p>Reading bytes into the pointer (the &quot;,&quot; command in Brainfuck) isn't currently supported. To enter data, use &quot;+&quot; and &quot;&gt;&quot;.</p>
20 <p>INCP - &gt; (Increment pointer)</p>
21 <p>DECP - &lt; (Decrement pointer)</p>
22 <p>INCB - + (Increment byte at pointer)</p>
23 <p>DECB - - (Decrement byte at pointer)</p>
24 <p>PUTB - . (Write byte at pointer)</p>
25 <p>JFOR - [ (Jump forward if byte at pointer is not zero)</p>
26 <p>JBAK - ] (Jump back if byte at pointer is not zero)</p>
27 <h2 id="reserved-tokens">Reserved Tokens</h2>
28 <p>These tokens are reserved to support future functionality.</p>
29 <p>GETB - , (Read byte into pointer)</p>
30 <p>IDAT - (Identify data to be read by READ. See Input/Output below.)</p>
31 <p>RUNC - (This section of the code is complete, run it.)</p>
32 <p>BADC - (This section of the code has a problem, do not run.)</p>
33 <h1 id="encoding-of-programs">Encoding Of Programs</h1>
34 <p>Programs are represented as a sequence of quantities of Dogecode tokens sent from a single address. Order, quantity and sending address are all significant to the system.</p>
35 <p>Ideally, programs would be represented as multiple sends in a single transaction. Until this is implemented, programs must be sent as an uninterrupted sequence of Dogecode tokens from a single address (no other tokens from the same address may interrupt the send).</p>
36 <h2 id="single-program-addresses">Single Program Addresses</h2>
37 <p>Single program addresses represent programs as a newly created Dogeparty address holding only the tokens sent to it in sequence that represent that single program's code.</p>
38 <p>No additional programs may be stored using that address.</p>
39 <p>If transferring the tokens fails or the program is found to be incorrect before it runs, a new address must be created and the correct sequence of tokens sent to it.</p>
40 <h2 id="program-queue-addresses-not-yet-implemented">Program Queue Addresses (Not Yet Implemented)</h2>
41 <p>Programs queued on an address for exection consist of a sequence of quantities of Dogecode tokens sent from a single address.</p>
42 <p>Since programs cannot be sent as multiple tokens in a single transaction two addresses may send programs at (approximately) the same time, leading to program token sends from two or more addresses becoming interleaved. This requires sorting token sends by address as well as by time when fetching programs to run.</p>
43 <h1 id="inputoutput">Input/Output</h1>
44 <h2 id="input-via">Input Via +/&gt;</h2>
45 <p>Data can be entered into memory using the + and &gt; commands. This is currently the only supported method for entering data into a program.</p>
46 <h2 id="input-via-idat-token-not-yet-implemented">Input Via IDAT Token (Not Yet Implemented)</h2>
47 <p>Details forthcoming.</p>
48 <h2 id="output-for-single-program-addresses">Output For Single Program Addresses</h2>
49 <p>Output is determined by running the program locally.</p>
50 <h2 id="output-for-program-queue-address-runner-not-yet-implemented">Output For Program Queue Address Runner (Not Yet Implemented)</h2>
51 <p>Output is provided via broadcast messages on the Program Queue Address (details forthcoming).</p>
52 <h1 id="running-programs">Running Programs</h1>
53 <h2 id="single-program-addresses-1">Single Program Addresses</h2>
54 <p>To execute the program, the system fetches all sends to the address in order and converts their token amounts to runs of Brainfuck commands. It then passes the resulting string to a Brainfuck interpreter. This will provide the final state and output of the program.</p>
55 <h2 id="program-queue-address-not-yet-implemented">Program Queue Address (Not Yet Implemented)</h2>
56 <p>Programs can be sent to an address that you control in order to be run in a queue.</p>
57 <p>Transactions from other addresses are ignored.</p>
58 <p>Used tokens can be returned to the sending address or, if the queue address is also the sending address, kept for re-use.</p>
59 <p>The runner polls the send table for new sends to the queue address. Sequences of tokens sent from a single address constitute programs to be executed. Programs are terminated with a RUNN token to trigger their execution, or an ERRR token if they should not be executed because (e.g.) a bug was found or the upload was corrupted.</p>
60 <p>The output of the program can either be recorded locally or output via broadcast messages from the runner address (details forthcoming).</p>
61 <p>To prevent programs that do not complete in a reasonable amount of time from disrupting the operation of the queue, programs should be run on a thread with a short timeout (details forthcoming).</p>
62 <h2 id="program-queue-address-as-a-service-not-yet-implemented">Program Queue Address As A Service (Not Yet Implemented)</h2>
63 <p>For Dogecode as a service, a program queue address that you control can execute Dogecode programs sent from addresses that others control in return for payment.</p>
64 <p>Tokens sent to the runner address are not returned, they constitute part of the payment for the service. Additional payment is sent as a Dogecoin transaction following the program tokens.</p>
65 <p>This system does not use RUNN/ERRR tokens to control execution. Receiving the Dogecoin payment acts as the command to execute the program. Should the payment not be sent within two minutes the program is not run and the tokens are forfeit - unsuccessful or erronious program uploads can have their execution cancelled by not sending payment. Should the incorrect amount of payment be sent, it can be corrected by sending a supplementary payment before any further Dogecode tokens are sent. If a supplement is not sent within two minutes, the tokens and incorrect payment are forfeited to the runner account.</p>
66 <p>The output of the program is output via broadcast messages from the runner address (details forthcoming).</p>
67 <p>To prevent programs that do not complete in a reasonable amount of time from disrupting the operation of the queue, programs should be run on a thread with a short timeout. The length of the timeout can be extended by the sender incorporating an additional supplement into the Dogecoin fee that triggers execution (details forthcoming).</p>
68 <p>Dogecoin prices for running are announced by the runner account on its broadcast message feed (details forthcoming).</p>
69 <h1 id="token-transfer-speed">Token Transfer Speed</h1>
70 <p>Dogecode programs must be sent as ordered sequences of individual Dogeparty asset &quot;send&quot; commands. To ensure that the token sends are incorporated into the blockchain in order, each send is performed only after the previous one is confirmed. This means that it can take minutes for each token run to be sent to the receiving account.</p>
71 <p>Multiple sends from the same account in the same block could be enabled by having multiple inputs available to it, this does not ensure ordering however.</p>
72 <p>Ideally, Dogeparty would be extended to allow multi-token sends in a single Dogecoin transaction. This would solve both confirmation and ordering.</p>