From c9f2365aa16425c1645f7de131b3a9e5c9e998a2 Mon Sep 17 00:00:00 2001 From: Peter Harpending Date: Fri, 11 Aug 2023 14:37:09 -0600 Subject: [PATCH] [wip] reorganize README --- README.md | 151 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 111 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index ae4c136..44c66f6 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,130 @@ # Vanillae -Vanillae is an Aeternity tool suite meant for small business use cases. Focus -is placed on ease-of-use, simplicity, code quality, and good documentation. +## How to use this project -You can read the [grant -proposal](https://forum.aeternity.com/t/active-application-vanillae/10638) for -more information about what this project is. -Vanillae is (intentionally) a very minimal toolset that only covers the most -common Aeternity use cases. We also do not have any tooling for the Node/NPM -ecosystem. If you have a more complicated use case or live in the Node/NPM -ecosystem, you want the [Aeternity JavaScript -SDK](https://github.com/aeternity/aepp-sdk-js). The SDK is a Swiss Army Knife. -Vanillae is just a knife. +## Downloads -Vanillae grew out of [Aegora.jp](https://aegora.jp). We made a simple + +## Quick Links + +- [Vanillae Grant Proposal][grant-proposal] +- [Vanillae Files][vanillae-files], miscellaneous explainers mostly for + things that should take 1 hour to learn but in practice take 11 hours + because information has to be synthesized from multiple sources + +- Video content + - [Vanillae Rumble Channel](https://rumble.com/c/c-3509606) + - [Vanillae Odysee Channel](https://odysee.com/@VanillaeProject:0) + - [Vanillae YouTube Channel](https://www.youtube.com/@vanillaeproject) +- Miscellany: + - [Aegora.jp][aegora], original impetus for product + - [Aeternity JS SDK][aesdk], which you want for more complicated use cases + +## About this project + +Aeternity is a high-performance open-source decentralized payment network. +Vanillae is a tool suite for using Aeternity. There is both developer-facing +tooling and user-facing tooling. There is also miscellaneous documentation, and +explainers etc. + +The two developers are Craig Everett (@zxq9) and Peter Harpending (@pharpend). +Vanillae grew out of [Aegora.jp][aegora]. We made a simple e-commerce store using Aeternity as the payment system. We encountered a lot -of rough edges in Aeternity's tooling, and so developed our own, and -open-sourced it. That became this project +of rough edges in Aeternity's tooling, so developed our own, and +open-sourced it. The Aeternity Foundation chose to pay us to grow out our +toolset, and that became this project. You can read the [grant +proposal][grant-proposal] for more information. -Our tooling is grouped according to the project that spawned it +Often during this process we ran into some thing that really should take 1 hour +to learn about, but in practice takes 11 hours because you have to synthesize +information from 100 different sources. In many of those cases, we went to the +trouble to write it all out in one place (that's the [Vanillae +Files][vanillae-files]), and in some cases there are videos on our +YT/Rumble/Odysee channels. -- [Sidekick](./sidekick/) +The goal is to write an explainer doc and have one or more videos for each +instance of information synthesis paralysis. - We needed the ability to talk to Superhero (the standard Aeternity browser - wallet extension) from our page script. Sidekick is a simple library to do - just that. +Generally, we write tools that we want to use. So - - [Sidekick Examples](./sidekick_examples/) illustrate how to use sidekick +- Functionality tends to be pretty minimal. +- The only usage cases covered are those we have actually encountered. +- When we encounter a tradeoff between simplicity and flexibility, we + generally have chosen simplicity. +- Our primary deployment target is the [zx/zomp ecosystem][zx-zomp], not the + Node/NPM ecosystem - - [AWCP](./libs/awcp/): the aepp/waellet communication protocol + For instance, this means that our JS/TS code is meant to run inside a + browser, and we don't give any thought to running it as server-side JS, + because that's not something we would ever do ourselves. - This is the definition of the messaging protocol between the page - script and the wallet. Sidekick implements one half of this protocol. + We're happy to support the Node/NPM ecosystem on a case-by-case basis as + long as it doesn't force us to reduce the quality of our product. - - [jex](./utils/jex/) +If you have a more complicated use case or live in the Node/NPM ecosystem, you +want the [Aeternity JavaScript SDK][aesdk] The SDK is a Swiss Army Knife. +Vanillae is just a set of knives, each of which was designed for a specific +cutting task. - We encountered packaging as an obvious problem to solve, and NPM is - simply a terrible way to solve it. Jex is a TypeScript/JavaScript - package manager that avoids most of the NPM-related security issues. -- [Vanillae Erlang Bindings](./bindings/erlang) +## Directory Structure - Our server backend is written in Erlang. We needed to talk to the - blockchain from our server backend. Vanillae.erl is an Erlang application - that does that. +``` +art/ Project icons, etc +bindings/ FLAGSHIP: APIs to talk to the AE blockchain from app backend + erlang/ [ERL] Erlang Vanillae Bindings +docs/ Explainer docs + baseN/ Base64 versus Base58 (they are fundamentally different ideas!) + ecc/ Elliptic Curve Cryptography + jex/ Jex: our TS/JS packaging tool we use instead of NPM + kek/ The Keccak/SHA-3 Algorithm explained + npm-misc/ How to install NPM on Linux such that you never have to use `sudo npm` + rlp/ Ethereum's Recursive-Length-Prefix codec explained + seed-phrases/ How seed phrase recovery works + sk-awcp/ How to use Sidekick and AWCP +jrx/ [TS] FLAGSHIP: the Jack Russell browser wallet extension +libs/ Miscellaneous (non-flagship) libraries + awcp/ [TS] Aepp-Waellet Communication Protocol: types for messages sent between page scripts and browser extension wallets + parasite/ [TS] Function library for talking to public aeternity nodes (do not use please) + tweetnacl/ [TS] Jex-packaged clone of public domain TweetNaCL library + vdk_aeser/ [TS] Serializer/deserializer library for AE data structures + vdk_base58/ [TS] Base 58 encode/decode library + vdk_base64/ [TS] Base 64 encode/decode library + vdk_binary/ [TS] Miscellaneous binary functions that should exist in the stdlib but don't + vdk_colors/ [TS] Assigns a color to arbitrary byte array (for color-coding keys in JR) + vdk_faert/ [TS] Fast AEternity Recovery Text: a replacement for the Bitcoin seed phrase standard + vdk_names/ [TS] Assigns a human readable name to a byte array (for naming keys in JR) + vdk_rlp/ [TS] Ethereum RLP standard TypeScript library + vdk_safe/ [TS] Equivalent of Haskell's Either type + vdk_tests/ [TS] Test/example suite for VDK + vdk_tests_cases/ [TS] Randomly generated test cases for some VDK packages (e.g. checking our RLP agrees with Ethereum's) + vrlp/ [ERL] Ethereum RLP library in Erlang +sidekick/ [TS] FLAGSHIP: TS library to talk to browser wallet extension (e.g. Superhero, hence name) from page script +sidekick_examples/ [TS] Example/test suite for sidekick +site/ Website for the vanillae project (soon to be deprecated/deleted) +utils/ Miscellaneous utilities + jex/ [ERL] Simple TS/JS packaging utility, our alternative to NPM + vlogd/ [ERL] Simple HTTP server that just logs input data, for demoing sidekick's HTTP logging functionality + vw/ [ERL] Vanillae Wallet: scratchpad for working out complicated wallet stuff (e.g. seed phrase recovery) in saner environment +``` - It is designed in such a way that you could write say a Vanillae Go - library with an identical API but totally different internals. Ultimately - the idea here is to create a language-agnostic API for talking to the - Aeternity blockchain from the +## Flagship products -- [Jaeck Russell](./jrx/): this is a (work-in-progress) simpler wallet than - Superhero +### Vanillae Bindings -- [Vanillae Files](./docs/): any time where we encountered some weird thing - that is like 1 hour of information but takes 15 hours to understand because - it's poorly documented, we tried to document it here. +### Jack Russell + +### Sidekick + +## Miscellaneous products of note + +### Vanillae Files + +### Jex + +[aegora]: https://aegora.jp +[aesdk]: https://github.com/aeternity/aepp-sdk-js +[grant-proposal]: https://forum.aeternity.com/t/active-application-vanillae/10638 +[vanillae-files]: ./docs/ +[zx-zomp]: http://zxq9.com/projects/zomp/