diff --git a/books/architecture/README.md b/books/architecture/README.md index e487843..88e86eb 100644 --- a/books/architecture/README.md +++ b/books/architecture/README.md @@ -1,4 +1,4 @@ -## Cuprate's architecture (implementation) book +## Cuprate's architecture book This book documents Cuprate's architecture and implementation. See: diff --git a/books/architecture/book.toml b/books/architecture/book.toml index 76724aa..996f7fe 100644 --- a/books/architecture/book.toml +++ b/books/architecture/book.toml @@ -1,19 +1,17 @@ [book] -authors = ["hinto-janai"] +authors = ["Cuprate Contributors"] language = "en" multilingual = false src = "src" title = "Cuprate Architecture" git-repository-url = "https://github.com/Cuprate/architecture-book" -# TODO: fix after importing real files. -# -# [preprocessor.last-changed] -# command = "mdbook-last-changed" -# renderer = ["html"] -# -# [output.html] -# default-theme = "ayu" -# preferred-dark-theme = "ayu" -# git-repository-url = "https://github.com/hinto-janai/cuprate-architecture" -# additional-css = ["last-changed.css"] +[preprocessor.last-changed] +command = "mdbook-last-changed" +renderer = ["html"] + +[output.html] +default-theme = "ayu" +preferred-dark-theme = "ayu" +git-repository-url = "https://github.com/Cuprate/architecture-book" +additional-css = ["last-changed.css"] diff --git a/books/architecture/last-changed.css b/books/architecture/last-changed.css new file mode 100644 index 0000000..a9abae5 --- /dev/null +++ b/books/architecture/last-changed.css @@ -0,0 +1,7 @@ +footer { + font-size: 0.8em; + text-align: center; + border-top: 1px solid; + margin-top: 4%; + padding: 5px 0; +} \ No newline at end of file diff --git a/books/architecture/src/SUMMARY.md b/books/architecture/src/SUMMARY.md index 2b8615c..74ecda6 100644 --- a/books/architecture/src/SUMMARY.md +++ b/books/architecture/src/SUMMARY.md @@ -1,3 +1,124 @@ # Summary -- [TODO](todo.md) +[Cuprate Architecture](cuprate-architecture.md) +[🟡 Foreword](foreword.md) + +--- + +- [🟠 Intro](intro/intro.md) + - [🟡 Who this book is for](intro/who-this-book-is-for.md) + - [🔴 Required knowledge](intro/required-knowledge.md) + - [🔴 How to use this book](intro/how-to-use-this-book.md) + +--- + +- [⚪️ Bird's eye view](birds-eye-view/intro.md) + - [⚪️ Map](birds-eye-view/map.md) + - [⚪️ Components](birds-eye-view/components.md) + +--- + +- [⚪️ Formats, protocols, types](formats-protocols-types/intro.md) + - [⚪️ monero_serai](formats-protocols-types/monero-serai.md) + - [⚪️ cuprate_types](formats-protocols-types/cuprate-types.md) + - [⚪️ cuprate_helper](formats-protocols-types/cuprate-helper.md) + - [⚪️ Epee](formats-protocols-types/epee.md) + - [⚪️ Levin](formats-protocols-types/levin.md) + +--- + +- [⚪️ Storage](storage/intro.md) + - [⚪️ Database abstraction](storage/database-abstraction.md) + - [⚪️ Blockchain](storage/blockchain.md) + - [⚪️ Transaction pool](storage/transaction-pool.md) + - [⚪️ Pruning](storage/pruning.md) + +--- + +- [🔴 RPC](rpc/intro.md) + - [⚪️ Types](rpc/types/intro.md) + - [⚪️ JSON](rpc/types/json.md) + - [⚪️ Binary](rpc/types/binary.md) + - [⚪️ Other](rpc/types/other.md) + - [⚪️ Interface](rpc/interface.md) + - [⚪️ Router](rpc/router.md) + - [⚪️ Handler](rpc/handler.md) + - [⚪️ Methods](rpc/methods/intro.md) + +--- + +- [⚪️ ZMQ](zmq/intro.md) + - [⚪️ TODO](zmq/todo.md) + +--- + +- [⚪️ Consensus](consensus/intro.md) + - [⚪️ Verifier](consensus/verifier.md) + - [⚪️ TODO](consensus/todo.md) + +--- + +- [⚪️ Networking](networking/intro.md) + - [⚪️ P2P](networking/p2p.md) + - [⚪️ Dandelion++](networking/dandelion.md) + - [⚪️ Proxy](networking/proxy.md) + - [⚪️ Tor](networking/tor.md) + - [⚪️ i2p](networking/i2p.md) + - [⚪️ IPv4/IPv6](networking/ipv4-ipv6.md) + +--- + +- [🔴 Instrumentation](instrumentation/intro.md) + - [⚪️ Logging](instrumentation/logging.md) + - [⚪️ Data collection](instrumentation/data-collection.md) + +--- + +- [⚪️ Binary](binary/intro.md) + - [⚪️ CLI](binary/cli.md) + - [⚪️ Config](binary/config.md) + - [⚪️ Logging](binary/logging.md) + +--- + +- [⚪️ Resource model](resource-model/intro.md) + - [⚪️ File system](resource-model/file-system.md) + - [⚪️ Sockets](resource-model/sockets.md) + - [⚪️ Memory](resource-model/memory.md) + - [🟡 Concurrency and parallelism](resource-model/concurrency-and-parallelism/intro.md) + - [⚪️ Map](resource-model/concurrency-and-parallelism/map.md) + - [⚪️ The RPC server](resource-model/concurrency-and-parallelism/the-rpc-server.md) + - [⚪️ The database](resource-model/concurrency-and-parallelism/the-database.md) + - [⚪️ The block downloader](resource-model/concurrency-and-parallelism/the-block-downloader.md) + - [⚪️ The verifier](resource-model/concurrency-and-parallelism/the-verifier.md) + - [⚪️ Thread exit](resource-model/concurrency-and-parallelism/thread-exit.md) + +--- + +- [⚪️ External Monero libraries](external-monero-libraries/intro.md) + - [⚪️ Cryptonight](external-monero-libraries/cryptonight.md) + - [🔴 RandomX](external-monero-libraries/randomx.md) + - [🔴 monero_serai](external-monero-libraries/monero_serai.md) + +--- + +- [⚪️ Benchmarking](benchmarking/intro.md) + - [⚪️ Criterion](benchmarking/criterion.md) + - [⚪️ Harness](benchmarking/harness.md) +- [⚪️ Testing](testing/intro.md) + - [⚪️ Monero data](testing/monero-data.md) + - [⚪️ RPC client](testing/rpc-client.md) + - [⚪️ Spawning `monerod`](testing/spawning-monerod.md) +- [⚪️ Known issues and tradeoffs](known-issues-and-tradeoffs/intro.md) + - [⚪️ Networking](known-issues-and-tradeoffs/networking.md) + - [⚪️ RPC](known-issues-and-tradeoffs/rpc.md) + - [⚪️ Storage](known-issues-and-tradeoffs/storage.md) + +--- + +- [⚪️ Appendix](appendix/intro.md) + - [🔴 Contributing](appendix/contributing.md) + - [🔴 Crate documentation](appendix/crate-documentation.md) + - [🔴 Build targets](appendix/build-targets.md) + - [🔴 Protocol book](appendix/protocol-book.md) + - [⚪️ User book](appendix/user-book.md) \ No newline at end of file diff --git a/books/architecture/src/appendix/build-targets.md b/books/architecture/src/appendix/build-targets.md new file mode 100644 index 0000000..495a3d6 --- /dev/null +++ b/books/architecture/src/appendix/build-targets.md @@ -0,0 +1,7 @@ +# Build targets +- x86 +- ARM64 +- Windows +- Linux +- macOS +- FreeBSD(?) diff --git a/books/architecture/src/appendix/contributing.md b/books/architecture/src/appendix/contributing.md new file mode 100644 index 0000000..675937a --- /dev/null +++ b/books/architecture/src/appendix/contributing.md @@ -0,0 +1,2 @@ +# Contributing + \ No newline at end of file diff --git a/books/architecture/src/appendix/crate-documentation.md b/books/architecture/src/appendix/crate-documentation.md new file mode 100644 index 0000000..0f4d96d --- /dev/null +++ b/books/architecture/src/appendix/crate-documentation.md @@ -0,0 +1,4 @@ +# Crate documentation +```bash +cargo doc --package $CUPRATE_CRATE +``` \ No newline at end of file diff --git a/books/architecture/src/appendix/intro.md b/books/architecture/src/appendix/intro.md new file mode 100644 index 0000000..fad5ae4 --- /dev/null +++ b/books/architecture/src/appendix/intro.md @@ -0,0 +1 @@ +# Appendix diff --git a/books/architecture/src/appendix/protocol-book.md b/books/architecture/src/appendix/protocol-book.md new file mode 100644 index 0000000..a855b73 --- /dev/null +++ b/books/architecture/src/appendix/protocol-book.md @@ -0,0 +1,2 @@ +# Protocol book + \ No newline at end of file diff --git a/books/architecture/src/appendix/user-book.md b/books/architecture/src/appendix/user-book.md new file mode 100644 index 0000000..0f12476 --- /dev/null +++ b/books/architecture/src/appendix/user-book.md @@ -0,0 +1 @@ +# ⚪️ User book diff --git a/books/architecture/src/benchmarking/criterion.md b/books/architecture/src/benchmarking/criterion.md new file mode 100644 index 0000000..e9d61e6 --- /dev/null +++ b/books/architecture/src/benchmarking/criterion.md @@ -0,0 +1 @@ +# ⚪️ Criterion diff --git a/books/architecture/src/benchmarking/harness.md b/books/architecture/src/benchmarking/harness.md new file mode 100644 index 0000000..6f82b52 --- /dev/null +++ b/books/architecture/src/benchmarking/harness.md @@ -0,0 +1 @@ +# ⚪️ Harness diff --git a/books/architecture/src/benchmarking/intro.md b/books/architecture/src/benchmarking/intro.md new file mode 100644 index 0000000..f043a0b --- /dev/null +++ b/books/architecture/src/benchmarking/intro.md @@ -0,0 +1 @@ +# ⚪️ Benchmarking diff --git a/books/architecture/src/binary/cli.md b/books/architecture/src/binary/cli.md new file mode 100644 index 0000000..1c515f4 --- /dev/null +++ b/books/architecture/src/binary/cli.md @@ -0,0 +1 @@ +# ⚪️ CLI diff --git a/books/architecture/src/binary/config.md b/books/architecture/src/binary/config.md new file mode 100644 index 0000000..c9582d0 --- /dev/null +++ b/books/architecture/src/binary/config.md @@ -0,0 +1 @@ +# ⚪️ Config diff --git a/books/architecture/src/binary/intro.md b/books/architecture/src/binary/intro.md new file mode 100644 index 0000000..dea12fa --- /dev/null +++ b/books/architecture/src/binary/intro.md @@ -0,0 +1 @@ +# ⚪️ Binary diff --git a/books/architecture/src/binary/logging.md b/books/architecture/src/binary/logging.md new file mode 100644 index 0000000..c7c88a3 --- /dev/null +++ b/books/architecture/src/binary/logging.md @@ -0,0 +1 @@ +# ⚪️ Logging diff --git a/books/architecture/src/birds-eye-view/components.md b/books/architecture/src/birds-eye-view/components.md new file mode 100644 index 0000000..19a17e2 --- /dev/null +++ b/books/architecture/src/birds-eye-view/components.md @@ -0,0 +1 @@ +# ⚪️ Components diff --git a/books/architecture/src/birds-eye-view/intro.md b/books/architecture/src/birds-eye-view/intro.md new file mode 100644 index 0000000..5ee2eb3 --- /dev/null +++ b/books/architecture/src/birds-eye-view/intro.md @@ -0,0 +1 @@ +# ⚪️ Bird's eye view diff --git a/books/architecture/src/birds-eye-view/map.md b/books/architecture/src/birds-eye-view/map.md new file mode 100644 index 0000000..1bde994 --- /dev/null +++ b/books/architecture/src/birds-eye-view/map.md @@ -0,0 +1 @@ +# ⚪️ Map diff --git a/books/architecture/src/consensus/intro.md b/books/architecture/src/consensus/intro.md new file mode 100644 index 0000000..32013b6 --- /dev/null +++ b/books/architecture/src/consensus/intro.md @@ -0,0 +1 @@ +# ⚪️ Consensus diff --git a/books/architecture/src/consensus/todo.md b/books/architecture/src/consensus/todo.md new file mode 100644 index 0000000..460d445 --- /dev/null +++ b/books/architecture/src/consensus/todo.md @@ -0,0 +1 @@ +# ⚪️ TODO diff --git a/books/architecture/src/consensus/verifier.md b/books/architecture/src/consensus/verifier.md new file mode 100644 index 0000000..128a3b0 --- /dev/null +++ b/books/architecture/src/consensus/verifier.md @@ -0,0 +1 @@ +# ⚪️ Verifier diff --git a/books/architecture/src/cuprate-architecture.md b/books/architecture/src/cuprate-architecture.md new file mode 100644 index 0000000..3c6c073 --- /dev/null +++ b/books/architecture/src/cuprate-architecture.md @@ -0,0 +1,22 @@ +# Cuprate Architecture +WIP + +[Cuprate](https://github.com/Cuprate/cuprate)'s architecture book. + +Sections are notated with colors indicating how complete they are: + +| Color | Meaning | +|-------|---------| +| ⚪️ | Empty +| 🔴 | Severely lacking information +| 🟠 | Lacking some information +| 🟡 | Almost ready +| 🟢 | OK + +--- + +Continue to the next chapter by clicking the right `>` button, or by selecting it on the left side. + +All chapters are viewable by clicking the top-left `☰` button. + +The entire book can searched by clicking the top-left 🔍 button. \ No newline at end of file diff --git a/books/architecture/src/external-monero-libraries/cryptonight.md b/books/architecture/src/external-monero-libraries/cryptonight.md new file mode 100644 index 0000000..80647b0 --- /dev/null +++ b/books/architecture/src/external-monero-libraries/cryptonight.md @@ -0,0 +1 @@ +# ⚪️ Cryptonight diff --git a/books/architecture/src/external-monero-libraries/intro.md b/books/architecture/src/external-monero-libraries/intro.md new file mode 100644 index 0000000..440a344 --- /dev/null +++ b/books/architecture/src/external-monero-libraries/intro.md @@ -0,0 +1 @@ +# ⚪️ External Monero libraries diff --git a/books/architecture/src/external-monero-libraries/monero_serai.md b/books/architecture/src/external-monero-libraries/monero_serai.md new file mode 100644 index 0000000..f1567b1 --- /dev/null +++ b/books/architecture/src/external-monero-libraries/monero_serai.md @@ -0,0 +1,2 @@ +# monero_serai + diff --git a/books/architecture/src/external-monero-libraries/randomx.md b/books/architecture/src/external-monero-libraries/randomx.md new file mode 100644 index 0000000..7705151 --- /dev/null +++ b/books/architecture/src/external-monero-libraries/randomx.md @@ -0,0 +1,2 @@ +# RandomX + \ No newline at end of file diff --git a/books/architecture/src/foreword.md b/books/architecture/src/foreword.md new file mode 100644 index 0000000..c85f18b --- /dev/null +++ b/books/architecture/src/foreword.md @@ -0,0 +1,36 @@ +# Foreword +Monero[^1] is a large software project, coming in at 329k lines of C++, C, headers, and make files.[^2] It is directly responsible for 2.6 billion dollars worth of value.[^3] It has had over 400 contributors, more if counting unnamed contributions.[^4] It has over 10,000 node operators and a large active userbase.[^5] + +The project wasn't always this big, but somewhere in the midst of contributors coming and going, various features being added, bugs being fixed, and celebrated cryptography being implemented - there was an aspect that was lost by the project that it could not easily gain again: **maintainability**. + +Within large and complicated software projects, there is an important transfer of knowledge that must occur for long-term survival. Much like an organism that must eventually pass the torch onto the next generation, projects must do the same for future contributors. + +However, newcomers often lack experience, past contributors might not be around, and current maintainers may be too busy. For whatever reason, this transfer of knowledge is not always smooth. + +There is a solution to this problem: **documentation**. + +The activity of writing the what, where, why, and how of the solutions to technical problems can be done in an author's lonesome. + +The activity of reading these ideas can be done by future readers at any time without permission. + +These readers may be new prospective contributors, it may be the current maintainers, it may be researchers, it may be users of various scale. Whoever it may be, documentation acts as the link between the past and present; a bottle of wisdom thrown into the river of time for future participants to open. + +This book is the manifestation of this will, for Cuprate[^6], an alternative Monero node. It documents Cuprate's implementation from head-to-toe such that in the case of a contributor's untimely disappearance, the project can continue. + +People come and go, documentation is forever. + +— hinto-janai + +--- + +[^1]: [`monero-project/monero`](https://github.com/monero-project/monero) + +[^2]: `git ls-files | grep "\.cpp$\|\.h$\|\.c$\|CMake" | xargs cat | wc -l` on [`cc73fe7`](https://github.com/monero-project/monero/tree/cc73fe71162d564ffda8e549b79a350bca53c454) + +[^3]: 2024-05-24: $143.55 USD * 18,151,608 XMR = $2,605,663,258 + +[^4]: `git log --all --pretty="%an" | sort -u | wc -l` on [`cc73fe7`](https://github.com/monero-project/monero/tree/cc73fe71162d564ffda8e549b79a350bca53c454) + +[^5]: + +[^6]: \ No newline at end of file diff --git a/books/architecture/src/formats-protocols-types/cuprate-helper.md b/books/architecture/src/formats-protocols-types/cuprate-helper.md new file mode 100644 index 0000000..6227829 --- /dev/null +++ b/books/architecture/src/formats-protocols-types/cuprate-helper.md @@ -0,0 +1 @@ +# ⚪️ cuprate_helper diff --git a/books/architecture/src/formats-protocols-types/cuprate-types.md b/books/architecture/src/formats-protocols-types/cuprate-types.md new file mode 100644 index 0000000..1069ce5 --- /dev/null +++ b/books/architecture/src/formats-protocols-types/cuprate-types.md @@ -0,0 +1 @@ +# ⚪️ cuprate_types diff --git a/books/architecture/src/formats-protocols-types/epee.md b/books/architecture/src/formats-protocols-types/epee.md new file mode 100644 index 0000000..4c0b17e --- /dev/null +++ b/books/architecture/src/formats-protocols-types/epee.md @@ -0,0 +1 @@ +# ⚪️ Epee diff --git a/books/architecture/src/formats-protocols-types/intro.md b/books/architecture/src/formats-protocols-types/intro.md new file mode 100644 index 0000000..77052fd --- /dev/null +++ b/books/architecture/src/formats-protocols-types/intro.md @@ -0,0 +1 @@ +# ⚪️ Formats, protocols, types diff --git a/books/architecture/src/formats-protocols-types/levin.md b/books/architecture/src/formats-protocols-types/levin.md new file mode 100644 index 0000000..72a88cc --- /dev/null +++ b/books/architecture/src/formats-protocols-types/levin.md @@ -0,0 +1 @@ +# ⚪️ Levin diff --git a/books/architecture/src/formats-protocols-types/monero-serai.md b/books/architecture/src/formats-protocols-types/monero-serai.md new file mode 100644 index 0000000..139af8e --- /dev/null +++ b/books/architecture/src/formats-protocols-types/monero-serai.md @@ -0,0 +1 @@ +# ⚪️ monero_serai diff --git a/books/architecture/src/instrumentation/data-collection.md b/books/architecture/src/instrumentation/data-collection.md new file mode 100644 index 0000000..7ea3d9f --- /dev/null +++ b/books/architecture/src/instrumentation/data-collection.md @@ -0,0 +1 @@ +# ⚪️ Data collection diff --git a/books/architecture/src/instrumentation/intro.md b/books/architecture/src/instrumentation/intro.md new file mode 100644 index 0000000..33640dd --- /dev/null +++ b/books/architecture/src/instrumentation/intro.md @@ -0,0 +1,2 @@ +# Instrumentation +Cuprate is built with [instrumentation](https://en.wikipedia.org/wiki/Instrumentation) in mind. \ No newline at end of file diff --git a/books/architecture/src/instrumentation/logging.md b/books/architecture/src/instrumentation/logging.md new file mode 100644 index 0000000..c7c88a3 --- /dev/null +++ b/books/architecture/src/instrumentation/logging.md @@ -0,0 +1 @@ +# ⚪️ Logging diff --git a/books/architecture/src/intro.md b/books/architecture/src/intro.md new file mode 100644 index 0000000..c708d61 --- /dev/null +++ b/books/architecture/src/intro.md @@ -0,0 +1,4 @@ +# Systems +Cuprate is made up of multiple distinct internal systems that work together. + +This section provides informal specifications and implementation details about each. \ No newline at end of file diff --git a/books/architecture/src/intro/how-to-use-this-book.md b/books/architecture/src/intro/how-to-use-this-book.md new file mode 100644 index 0000000..7664e04 --- /dev/null +++ b/books/architecture/src/intro/how-to-use-this-book.md @@ -0,0 +1,5 @@ +# How to use this book + +## Maintainers +## Contributors +## Researchers \ No newline at end of file diff --git a/books/architecture/src/intro/intro.md b/books/architecture/src/intro/intro.md new file mode 100644 index 0000000..db2603c --- /dev/null +++ b/books/architecture/src/intro/intro.md @@ -0,0 +1,15 @@ +# Intro +[Cuprate](https://github.com/Cuprate/cuprate) is an alternative [Monero](https://getmonero.org) node implementation. + +This book describes Cuprate's architecture, ranging from small things like database pruning to larger meta-components like the networking stack. + +A brief overview of some aspects covered within this book: +- Component designs +- Implementation details +- File location and purpose +- Design decisions and tradeoffs +- Things in relation to `monerod` +- Dependency usage + +## Source code +The source files for this book can be found on at: . \ No newline at end of file diff --git a/books/architecture/src/intro/required-knowledge.md b/books/architecture/src/intro/required-knowledge.md new file mode 100644 index 0000000..3262f05 --- /dev/null +++ b/books/architecture/src/intro/required-knowledge.md @@ -0,0 +1,28 @@ +# Required knowledge + +## General +- Rust +- Monero +- System design + +## Components +### Storage +- Embedded databases +- LMDB +- redb + +### RPC +- `axum` +- `tower` +- `async` +- JSON-RPC 2.0 +- Epee + +### Networking +- `tower` +- `tokio` +- `async` +- Levin + +### Instrumentation +- `tracing` diff --git a/books/architecture/src/intro/who-this-book-is-for.md b/books/architecture/src/intro/who-this-book-is-for.md new file mode 100644 index 0000000..4b5be2b --- /dev/null +++ b/books/architecture/src/intro/who-this-book-is-for.md @@ -0,0 +1,31 @@ +# Who this book is for + +## Maintainers +As mentioned in [`Foreword`](../foreword.md), the group of people that benefit from this book's value the most by far are the current and future Cuprate maintainers. + +Cuprate's system design is documented in this book such that if you were ever to build it again from scratch, you would have an excellent guide on how to do such, and also where improvements could be made. + +Practically, what that means for maintainers is that it acts as _the_ reference. During maintenance, it is quite valuable to have a book that contains condensed knowledge on the behavior of components, or how certain code works, or why it was built a certain way. + +## Contributors +Contributors also have access to the inner-workings of Cuprate via this book, which helps when making larger contributions. + +Design decisions and implementation details notated in this book helps answer questions such as: +- Why is it done this way? +- Why can it _not_ be done this way? +- Were other methods attempted? + +Cuprate's testing and benchmarking suites, unknown to new contributors, are also documented within this book. + +## Researchers +This book contains the why, where, and how of the _implementation_ of formal research. + +Although it is an informal specification, this book still acts as a more accessible overview of Cuprate compared to examining the codebase itself. + +## Operators & users +This book is not a practical guide for using Cuprate itself. + +For configuration, data collection (also important for researchers), and other practical usage, see [Cuprate's user book](https://user.cuprate.org). + +## Observers +Anyone curious enough is free to learn the inner-workings of Cuprate via this book, and maybe even contribute someday. \ No newline at end of file diff --git a/books/architecture/src/known-issues-and-tradeoffs/intro.md b/books/architecture/src/known-issues-and-tradeoffs/intro.md new file mode 100644 index 0000000..20ab7b5 --- /dev/null +++ b/books/architecture/src/known-issues-and-tradeoffs/intro.md @@ -0,0 +1 @@ +# ⚪️ Known issues and tradeoffs diff --git a/books/architecture/src/known-issues-and-tradeoffs/networking.md b/books/architecture/src/known-issues-and-tradeoffs/networking.md new file mode 100644 index 0000000..20487cb --- /dev/null +++ b/books/architecture/src/known-issues-and-tradeoffs/networking.md @@ -0,0 +1 @@ +# ⚪️ Networking diff --git a/books/architecture/src/known-issues-and-tradeoffs/rpc.md b/books/architecture/src/known-issues-and-tradeoffs/rpc.md new file mode 100644 index 0000000..3337f37 --- /dev/null +++ b/books/architecture/src/known-issues-and-tradeoffs/rpc.md @@ -0,0 +1 @@ +# ⚪️ RPC diff --git a/books/architecture/src/known-issues-and-tradeoffs/storage.md b/books/architecture/src/known-issues-and-tradeoffs/storage.md new file mode 100644 index 0000000..214cf15 --- /dev/null +++ b/books/architecture/src/known-issues-and-tradeoffs/storage.md @@ -0,0 +1 @@ +# ⚪️ Storage diff --git a/books/architecture/src/networking/dandelion.md b/books/architecture/src/networking/dandelion.md new file mode 100644 index 0000000..30916b7 --- /dev/null +++ b/books/architecture/src/networking/dandelion.md @@ -0,0 +1 @@ +# ⚪️ Dandelion++ diff --git a/books/architecture/src/networking/i2p.md b/books/architecture/src/networking/i2p.md new file mode 100644 index 0000000..986ab2a --- /dev/null +++ b/books/architecture/src/networking/i2p.md @@ -0,0 +1 @@ +# ⚪️ i2p diff --git a/books/architecture/src/networking/intro.md b/books/architecture/src/networking/intro.md new file mode 100644 index 0000000..20487cb --- /dev/null +++ b/books/architecture/src/networking/intro.md @@ -0,0 +1 @@ +# ⚪️ Networking diff --git a/books/architecture/src/networking/ipv4-ipv6.md b/books/architecture/src/networking/ipv4-ipv6.md new file mode 100644 index 0000000..07339b4 --- /dev/null +++ b/books/architecture/src/networking/ipv4-ipv6.md @@ -0,0 +1 @@ +# ⚪️ IPv4/IPv6 diff --git a/books/architecture/src/networking/p2p.md b/books/architecture/src/networking/p2p.md new file mode 100644 index 0000000..11b2015 --- /dev/null +++ b/books/architecture/src/networking/p2p.md @@ -0,0 +1 @@ +# ⚪️ P2P diff --git a/books/architecture/src/networking/proxy.md b/books/architecture/src/networking/proxy.md new file mode 100644 index 0000000..bd9e5f7 --- /dev/null +++ b/books/architecture/src/networking/proxy.md @@ -0,0 +1 @@ +# ⚪️ Proxy diff --git a/books/architecture/src/networking/tor.md b/books/architecture/src/networking/tor.md new file mode 100644 index 0000000..cc0a809 --- /dev/null +++ b/books/architecture/src/networking/tor.md @@ -0,0 +1 @@ +# ⚪️ Tor diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/intro.md b/books/architecture/src/resource-model/concurrency-and-parallelism/intro.md new file mode 100644 index 0000000..2cca180 --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/intro.md @@ -0,0 +1,32 @@ +# Concurrency and parallelism +It is incumbent upon software like Cuprate to take advantage of today's highly parallel hardware as much as practically possible. + +With that said, programs must setup guardrails when operating in a concurrent and parallel manner, [for correctness and safety](https://en.wikipedia.org/wiki/Concurrency_(computer_science)). + +There are "synchronization primitives" that help with this, common ones being: +- [Locks](https://en.wikipedia.org/wiki/Lock_(computer_science)) +- [Channels](https://en.wikipedia.org/wiki/Channel_(programming)) +- [Atomics](https://en.wikipedia.org/wiki/Linearizability#Primitive_atomic_instructions) + +These tools are relatively easy to use in isolation, but trickier to do so when considering the entire system. It is not uncommon for _the_ bottleneck to be the [poor orchastration](https://en.wikipedia.org/wiki/Starvation_(computer_science)) of these primitives. + +## Analogy +A common analogy for a parallel system is an intersection. + +Like a parallel computer system, an intersection contains: +1. **Parallelism:** multiple individual units that want to move around (cars, pedestrians, etc) +1. **Synchronization primitives:** traffic lights, car lights, walk signals + +In theory, the amount of "work" the units can do is only limited by the speed of the units themselves, but in practice, the slow cascading reaction speeds between all units, the frequent hiccups that can occur, and the synchronization primitives themselves become bottlenecks far before the maximum speed of any unit is reached. + +A car that hogs the middle of the intersection on the wrong light is akin to a system thread holding onto a lock longer than it should be - it degrades total system output. + +Unlike humans however, computer systems at least have the potential to move at lightning speeds, but only if the above synchronization primitives are used correctly. + +## Goal +To aid the long-term maintenance of highly concurrent and parallel code, this section documents: +1. All system threads spawned and maintained +1. All major sections where synchronization primitives are used +1. The asynchronous behavior of some components + +and how these compose together efficiently in Cuprate. \ No newline at end of file diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/map.md b/books/architecture/src/resource-model/concurrency-and-parallelism/map.md new file mode 100644 index 0000000..1bde994 --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/map.md @@ -0,0 +1 @@ +# ⚪️ Map diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/the-block-downloader.md b/books/architecture/src/resource-model/concurrency-and-parallelism/the-block-downloader.md new file mode 100644 index 0000000..c0dccba --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/the-block-downloader.md @@ -0,0 +1 @@ +# ⚪️ The block downloader diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/the-database.md b/books/architecture/src/resource-model/concurrency-and-parallelism/the-database.md new file mode 100644 index 0000000..32e4b62 --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/the-database.md @@ -0,0 +1 @@ +# ⚪️ The database diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/the-rpc-server.md b/books/architecture/src/resource-model/concurrency-and-parallelism/the-rpc-server.md new file mode 100644 index 0000000..cd654cf --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/the-rpc-server.md @@ -0,0 +1 @@ +# ⚪️ The RPC server diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/the-verifier.md b/books/architecture/src/resource-model/concurrency-and-parallelism/the-verifier.md new file mode 100644 index 0000000..eeaedc6 --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/the-verifier.md @@ -0,0 +1 @@ +# ⚪️ The verifier diff --git a/books/architecture/src/resource-model/concurrency-and-parallelism/thread-exit.md b/books/architecture/src/resource-model/concurrency-and-parallelism/thread-exit.md new file mode 100644 index 0000000..3925975 --- /dev/null +++ b/books/architecture/src/resource-model/concurrency-and-parallelism/thread-exit.md @@ -0,0 +1 @@ +# ⚪️ Thread exit diff --git a/books/architecture/src/resource-model/file-system.md b/books/architecture/src/resource-model/file-system.md new file mode 100644 index 0000000..b67ca07 --- /dev/null +++ b/books/architecture/src/resource-model/file-system.md @@ -0,0 +1 @@ +# ⚪️ File system diff --git a/books/architecture/src/resource-model/intro.md b/books/architecture/src/resource-model/intro.md new file mode 100644 index 0000000..28d1dd6 --- /dev/null +++ b/books/architecture/src/resource-model/intro.md @@ -0,0 +1 @@ +# ⚪️ Resource model diff --git a/books/architecture/src/resource-model/memory.md b/books/architecture/src/resource-model/memory.md new file mode 100644 index 0000000..e3624b5 --- /dev/null +++ b/books/architecture/src/resource-model/memory.md @@ -0,0 +1 @@ +# ⚪️ Memory diff --git a/books/architecture/src/resource-model/sockets.md b/books/architecture/src/resource-model/sockets.md new file mode 100644 index 0000000..0d590ca --- /dev/null +++ b/books/architecture/src/resource-model/sockets.md @@ -0,0 +1 @@ +# ⚪️ Sockets diff --git a/books/architecture/src/rpc/handler.md b/books/architecture/src/rpc/handler.md new file mode 100644 index 0000000..fffa45f --- /dev/null +++ b/books/architecture/src/rpc/handler.md @@ -0,0 +1 @@ +# ⚪️ Handler diff --git a/books/architecture/src/rpc/interface.md b/books/architecture/src/rpc/interface.md new file mode 100644 index 0000000..541b744 --- /dev/null +++ b/books/architecture/src/rpc/interface.md @@ -0,0 +1 @@ +# ⚪️ Interface diff --git a/books/architecture/src/rpc/intro.md b/books/architecture/src/rpc/intro.md new file mode 100644 index 0000000..dcfc82b --- /dev/null +++ b/books/architecture/src/rpc/intro.md @@ -0,0 +1,3 @@ +# RPC +- +- \ No newline at end of file diff --git a/books/architecture/src/rpc/methods/intro.md b/books/architecture/src/rpc/methods/intro.md new file mode 100644 index 0000000..d4a3a15 --- /dev/null +++ b/books/architecture/src/rpc/methods/intro.md @@ -0,0 +1 @@ +# ⚪️ Methods diff --git a/books/architecture/src/rpc/router.md b/books/architecture/src/rpc/router.md new file mode 100644 index 0000000..1827dd3 --- /dev/null +++ b/books/architecture/src/rpc/router.md @@ -0,0 +1 @@ +# ⚪️ Router diff --git a/books/architecture/src/rpc/types/binary.md b/books/architecture/src/rpc/types/binary.md new file mode 100644 index 0000000..dea12fa --- /dev/null +++ b/books/architecture/src/rpc/types/binary.md @@ -0,0 +1 @@ +# ⚪️ Binary diff --git a/books/architecture/src/rpc/types/intro.md b/books/architecture/src/rpc/types/intro.md new file mode 100644 index 0000000..22e430c --- /dev/null +++ b/books/architecture/src/rpc/types/intro.md @@ -0,0 +1 @@ +# ⚪️ Types diff --git a/books/architecture/src/rpc/types/json.md b/books/architecture/src/rpc/types/json.md new file mode 100644 index 0000000..0bf9351 --- /dev/null +++ b/books/architecture/src/rpc/types/json.md @@ -0,0 +1 @@ +# ⚪️ JSON diff --git a/books/architecture/src/rpc/types/other.md b/books/architecture/src/rpc/types/other.md new file mode 100644 index 0000000..49a36cc --- /dev/null +++ b/books/architecture/src/rpc/types/other.md @@ -0,0 +1 @@ +# ⚪️ Other diff --git a/books/architecture/src/storage/blockchain.md b/books/architecture/src/storage/blockchain.md new file mode 100644 index 0000000..6046687 --- /dev/null +++ b/books/architecture/src/storage/blockchain.md @@ -0,0 +1 @@ +# ⚪️ Blockchain diff --git a/books/architecture/src/storage/database-abstraction.md b/books/architecture/src/storage/database-abstraction.md new file mode 100644 index 0000000..b21a192 --- /dev/null +++ b/books/architecture/src/storage/database-abstraction.md @@ -0,0 +1 @@ +# ⚪️ Database abstraction diff --git a/books/architecture/src/storage/intro.md b/books/architecture/src/storage/intro.md new file mode 100644 index 0000000..214cf15 --- /dev/null +++ b/books/architecture/src/storage/intro.md @@ -0,0 +1 @@ +# ⚪️ Storage diff --git a/books/architecture/src/storage/pruning.md b/books/architecture/src/storage/pruning.md new file mode 100644 index 0000000..cfeee69 --- /dev/null +++ b/books/architecture/src/storage/pruning.md @@ -0,0 +1 @@ +# ⚪️ Pruning diff --git a/books/architecture/src/storage/transaction-pool.md b/books/architecture/src/storage/transaction-pool.md new file mode 100644 index 0000000..4eb139b --- /dev/null +++ b/books/architecture/src/storage/transaction-pool.md @@ -0,0 +1 @@ +# ⚪️ Transaction pool diff --git a/books/architecture/src/testing/intro.md b/books/architecture/src/testing/intro.md new file mode 100644 index 0000000..397ae90 --- /dev/null +++ b/books/architecture/src/testing/intro.md @@ -0,0 +1 @@ +# ⚪️ Testing diff --git a/books/architecture/src/testing/monero-data.md b/books/architecture/src/testing/monero-data.md new file mode 100644 index 0000000..915af28 --- /dev/null +++ b/books/architecture/src/testing/monero-data.md @@ -0,0 +1 @@ +# ⚪️ Monero data diff --git a/books/architecture/src/testing/rpc-client.md b/books/architecture/src/testing/rpc-client.md new file mode 100644 index 0000000..5a373c2 --- /dev/null +++ b/books/architecture/src/testing/rpc-client.md @@ -0,0 +1 @@ +# ⚪️ RPC client diff --git a/books/architecture/src/testing/spawning-monerod.md b/books/architecture/src/testing/spawning-monerod.md new file mode 100644 index 0000000..1552266 --- /dev/null +++ b/books/architecture/src/testing/spawning-monerod.md @@ -0,0 +1 @@ +# ⚪️ Spawning monerod diff --git a/books/architecture/src/zmq/intro.md b/books/architecture/src/zmq/intro.md new file mode 100644 index 0000000..0b668b3 --- /dev/null +++ b/books/architecture/src/zmq/intro.md @@ -0,0 +1 @@ +# ⚪️ ZMQ diff --git a/books/architecture/src/todo.md b/books/architecture/src/zmq/todo.md similarity index 100% rename from books/architecture/src/todo.md rename to books/architecture/src/zmq/todo.md