blockchan/SPECS at master · balayette/blockchan · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
DISCLAIMER :
The development of this project is chaotic.

There are a few (very) bad code paths in the project (performance-wise),
that I am aware of. Most of the time, those code paths were left unchecked not
by laziness but by choosing the most naive implementations to ease development
and readability.
Should performance issues arise, I will be the first to consider rewriting such
hot paths.

OCaml experts, be warned : I am merely a beginner and started this project as a
learning experience. You are very likely to see code that you won't be able to
unsee.


BASIC OVERVIEW :

blockchan_data/
---> blockchan.json [0]
---> blocks/ [1]
---> ---> 0.json [2]
---> ---> 1.json
---> ---> 2.json
---> ---> ...
---> ---> x.json
---> blockchan [3]
---> ---> boards/ [4]
---> ---> ---> g/ [5]
---> ---> ---> ---> thread_hash_1/ [6]
---> ---> ---> ---> ---> 0 [7]
---> ---> ---> ---> ---> 1
---> ---> ---> ---> ---> ...
---> ---> ---> ---> ---> x
---> ---> ---> ---> thread_hash_2/
---> ---> ---> ---> ...
---> ---> ---> ---> thread_hash_x/
---> ---> ---> cg/
---> ---> ---> ...
---> ---> ---> b/

[0] : blockchain.json is a very simple json file that stores little
metadata about the blockchain. (See I).

[1] : blocks/ is a subdirectory of blockchan_data/ where all the blocks
are stored. (See II).

[2] : Each [number].json file written to the disk represents the block with
ID [number] (See III).

[3] Directory that stores the imageboard in a human readable / easily parsed
format

[4] Home of the boards

[5] Each board gets a folder, that is completely independant from the others.

[6] Each subdirectory of each board directory is a thread. The directory name
is the hash of thread.

[7] There is no board wide post id. All posts are stored as plain text files in
their thread's directory, indexed by time, starting from 0.

I) blockchain.json

I aim to keep this file as simple as possible. At the moment, the file only
lists the number of blocks and the timestamp the blockchain was last updated.

II) The blockchain
blocks/ is the local storage of the blockchain. All blocks are stored and
downloaded in json format, starting with the genesis block (ID 0).

This allows for easy block lookup.

Each block is stored as a json file that encodes the data associated with
the block.
Blocks are created at regular intervals if transactions have been made.

Each block contains a version numnber, an id, the hash of the previous block,
a list of transactions, the timestamp of the creation of the block and the hash
of the block.

A transaction is a data structure that contains the timestamp of its creation,
its hash and associated data.

The transaction data is what specifies the outcome of the transaction.


III) The server

The server listens for requests on a set of URIs.

- GET /get?id=x -> The server will respond with the block with id x in json
format. If the response is empty, then no block with this id exists on the
server

- POST /transaction {transaction_data=x} -> The server will process the json encoded
transaction_data x and add it to the next block, if it is valid.

Other URIs and methods will be ignored.


IV) The client

The client periodically sends a request to the server to retrieve the latest
blocks, and then processes them and writes them to the filesystem.
That's all.