1  # Start Here
  2  
  3  ## Directory Structure
  4  
  5  DarkFi loosely follows the standardized Unix directory structure.
  6  
  7  * All bundled applications are contained in `bin/` subdirectory.
  8  * Random scripts and helpers such as build artifacts, node deployment
  9    or syntax highlighting is in `contrib/`.
 10  * Documentation is in `doc/`.
 11  * Example codes are in `example/`.
 12  * Script utilities are in `script/`.
 13    See also the large `script/research/` subdir.
 14  * All core library code is contained in `src/`.
 15    See [Architecture Overview](arch/overview.md) for a detailed
 16    description.
 17      * The `src/sdk/` crate is used by WASM contracts and core code.
 18        It contains essential primitives and code shared between them.
 19      * `src/serial/` is a crate containing the binary serialization code.
 20      * `src/contract/` contains our native bundled contracts. It's worth
 21        looking at these to familiarize yourself with what contracts on
 22        DarkFi are like.
 23  
 24  ## Using DarkFi
 25  
 26  Refer to the main [README](../index.html) file for instructions on how
 27  to install Rust and necessary dependencies.
 28  
 29  Then proceed to the [Running a Node](testnet/node.md) guide.
 30  
 31  ## Join the Community
 32  
 33  Although we have a Telegram, we don't believe in centralized
 34  proprietary apps, and our core community organizes through our own
 35  fully anonymous p2p chat system which has support for Tor and i2p.
 36  
 37  Every Monday at 14:00 UTC (DST) or 15:00 UTC (ST) in #dev we have our
 38  main project meeting.
 39  
 40  See the guide on [darkirc](misc/darkirc/darkirc.md) for instructions
 41  on joining the chat.
 42  
 43  ## Contributing as a Dev
 44  
 45  Check out the [contributor's guide](dev/contrib/contrib.md) for where
 46  to find tasks and submitting patches to the project.
 47  
 48  If you're not a dev but wish to learn then take a look at the
 49  [agorism hackers study guide](dev/learn.md).
 50  
 51  Lastly familiarize yourself with the
 52  [project architecture](arch/arch.md). The book also contains a
 53  cryptography section with a helpful
 54  [ZK explainer](crypto/zk_explainer.md).
 55  
 56  DarkFi also has a [project spec](spec/crypto-schemes.md) and
 57  a [DEP](dep/0001.md) (DarkFi Enhancement Proposals) system.
 58  
 59  ## Detailed Overview
 60  
 61  Source code is under `src/` subdirectory. Main interesting modules are:
 62  
 63  * `net/` is our own p2p network. There are sessions such as incoming or
 64    outgoing that have channels (connections). Protocols are attached to
 65    channels depending on the session. The p2p network is also
 66    multi-transport with support for TCP (+TLS), Tor and i2p. So you can
 67    access the p2p fully anonymously (network level privacy).
 68  * `event_graph/` which is a DAG sync protocol used for ensuring
 69    eventual consistency of data, such as with chat systems (you don't
 70    drop any messages).
 71  * `runtime/` is the WASM smart contract engine. We separate computation
 72    into several stages which is checks-effects-interactions paradigm in
 73    solidity but enforced in the smart contract explicitly. For example
 74    in the `exec()` phase, you can only read, whereas writes must occur
 75    in the `apply(update)` phase.
 76  * `blockchain/` and `validator/` is the blockchain and consensus algos.
 77  * `zk/` is the ZK VM, which is simply loads bytecode which is used to
 78    build the circuits. It's a very simple model rather than the TinyRAM
 79    computation models. We opted for this because we prefer simplicity in
 80    systems design.
 81  * `sdk/` contains a crypto SDK usable in smart contracts and
 82    applications. There are also Python bindings here, useful for making
 83    utilities or small apps.
 84  * `serial/` contains our own serialization because we don't trust Rust
 85    serialization libs like serde. We also have async serialization and
 86    deserialization which is good for network code.
 87  * `tx/` is the tx we use. Note signatures are not in the calldata as
 88    having this outside it allows more efficient verification (since you
 89    can do it in parallel and so on).
 90      * All DarkFi calls are precomputed ahead of time which is needed
 91        for ZK. Normally in ETH or other smart contract chains, the
 92        calldata is calculated where the function is invoked. Whereas in
 93        DarkFi the entire callgraph and calldata is bundled since ZK
 94        proofs must be computed ahead of time. This also improves things
 95        like static analysis and security (limiting call depth is easy
 96        to check before verification).
 97      * Verifying sigs or call depth ahead of time helps make the chain
 98        more attack resistant.
 99  * `contract/` contains our native smart contracts. Namely:
100      * `money`, which is multi-asset anonymous transfers, anonymous
101        swaps and token issuance. The token issuance is programmatic.
102        When creating a token, it commits to a smart contract which
103        specifies how the token is allowed to be issued.
104      * `deploy` for deploying smart contracts.
105      * `dao`, which is a fully anonymous DAO. All the DAOs on chain are
106        anonymous, including the amounts and activity of the treasury.
107        All participants are anonymous, proposals are anonymous and votes
108        are anonymous including the token weighted vote amount, and user
109        identity. You cannot see who is in the DAO.
110  
111  NOTE: We try to minimize external dependencies in our code as much as
112  possible. We even try to limit dependencies within submodules.
113  
114  Inside `bin/` contains utilities and applications:
115  
116  * `darkfid/` is the main daemon and `drk/` is the wallet.
117  * `dnet/` is a viewer to see the p2p traffic of nodes, and `deg/` is a
118    viewer for the event graph data. We use these as debugging and
119    monitoring tools.
120  * `dhtd/` is a distributed hash table, like IPFS, for transferring
121    static data and large files around. Currently just a prototype but
122    we'll use this later for images in the chat or other static content
123    like seller pages on the marketplace.
124  * `tau/` is an anon p2p task manager which we use. We don't use Github
125    issues, and seek to minimize our dependence on centralized services.
126    Eventually we want to be fully p2p and attack resistant.
127  * `darkirc/` is our main community chat. It uses [RLN](crypto/rln.md);
128    you stake money and if you post twice in an epoch then you get
129    slashed which prevents spam. There is a free tier. It uses the
130    `event_graph` for synchronizing the history. You can attach any IRC
131    frontend to use it.
132  * `zkas/` is our ZK compiler.
133  * `zkrunner/` contains our ZK debugger (run `zkrunner` with `--trace`),
134    and `zkrender` which renders a graphic of the circuit layout.
135  * `lilith/` is a universal seed node. Eventually we will add swarming
136    support to our p2p network which is an easy addon.
137  
138  Lastly worth taking a look is `script/research/` and
139  `script/research/zk/` which contains impls of most major ZK algos.
140  `bench/` contains benchmarks. `script/escrow.sage` is a utility for
141  doing escrow. We'll integrate it in the wallet later.
142  
143  Our design philosophy and simplicity oriented approach to systemd dev:
144  
145  * [Suckless Philosophy: software that sucks less](https://suckless.org/philosophy/)
146  * [How to Design Perfect (Software) Products  by Pieter Hintjens](http://hintjens.com/blog:19/noredirect/true)
147  
148  Recent crypto code audit: [ZK Security DarkFi Code Audit](https://dark.fi/zksecurity-audit-q124.pdf)
149  
150  Useful link on [our ZK toolchain](zkas/writing-zk-proofs.md)
151  
152  For proof files, see `proof/` and `src/contract/*/proof/` subdirs.