improve sidekick README
This commit is contained in:
+31
-94
@@ -4,38 +4,22 @@ Sidekick is a simple JavaScript library for talking to an Aeternity
|
||||
browser wallet extension such as Jaeck Russell or Superhero from the document
|
||||
context of a webpage.
|
||||
|
||||
> One of the most important things for designing a computer, which I
|
||||
> think most designers don't do, is you study the problem you want to
|
||||
> solve. And then use what you learn from studying the problem you
|
||||
> want to solve to put in the mechanisms needed to solve it in the
|
||||
> computer you're building. No more, no less.
|
||||
|
||||
— Gerald Jay Sussman
|
||||
|
||||
|
||||
|
||||
# Build Prereqs
|
||||
|
||||
Assuming Ubuntu 18.04. Adapt these instructions for your own system.
|
||||
|
||||
You need
|
||||
|
||||
- `npm` to build TypeScript
|
||||
- `npm` to build TypeScript (and TypeDoc if you want to build the
|
||||
documentation)
|
||||
- `tsc` to compile
|
||||
- [`jx`][jx] to orchestrate the build properly
|
||||
- Python 3.6 or later to run `jx`
|
||||
- [jex](../utils/jex/) to facilitate the build
|
||||
|
||||
[jx]: https://gitlab.com/pharpend/jx/-/tree/master/#jx-secure-typescript-package-manager
|
||||
|
||||
Steps
|
||||
Steps:
|
||||
|
||||
sudo snap refresh
|
||||
sudo snap install node --channel 18/stable
|
||||
npm install -g typescript
|
||||
wget https://gitlab.com/pharpend/jx/-/raw/master/jx -O ~/.local/bin/jx
|
||||
chmod u+x ~/.local/bin/jx
|
||||
|
||||
|
||||
|
||||
## Protip: avoid using `sudo npm install -g`
|
||||
|
||||
@@ -53,84 +37,37 @@ NPM_PACKAGES="${HOME}/.npm-packages"
|
||||
export PATH=$NPM_PACKAGES/bin:$PATH
|
||||
```
|
||||
|
||||
# Build Steps
|
||||
|
||||
## 1. Build dependencies
|
||||
|
||||
# Build
|
||||
|
||||
make
|
||||
|
||||
|
||||
# Examples
|
||||
|
||||
There is a repository of examples at https://gitlab.com/pharpend/sidekick_examples.git
|
||||
|
||||
# What sidekick is NOT
|
||||
|
||||
Sidekick is **not** ideal if you operate in the Node/NPM ecosystem. If you are
|
||||
working in the Node/NPM ecosystem, you probably want the [Aeternity JavaScript
|
||||
SDK](https://github.com/aeternity/aepp-sdk-js/). Every single
|
||||
Aeternity-related thing you could ever possibly want to do is possible to
|
||||
accomplish with the SDK.
|
||||
|
||||
All that Sidekick knows how to do is talk to a browser wallet extension. In an
|
||||
application, there is a great deal of necessary functionality (e.g. forming
|
||||
transactions for the wallet to sign) which sidekick assumes your server-side
|
||||
code has already handled.
|
||||
|
||||
In all software there is a tradeoff between simplicity and number of features.
|
||||
Sidekick is very simple: 2300 lines of TypeScript, including comments, with no
|
||||
dependencies. Therefore Sidekick intentionally only has a very limited set of
|
||||
features.
|
||||
|
||||
|
||||
|
||||
# Where is the NPM package or the webpack bundle?
|
||||
|
||||
There isn't one.
|
||||
|
||||
## Why?
|
||||
|
||||
Sidekick is a library that deals with cryptocurrency. The security
|
||||
model is based on transparency and trust. A user must be able to
|
||||
inspect code that is running on his hardware handling his money.
|
||||
|
||||
We don't support NPM because of the security issues that NPM
|
||||
introduces. Briefly, the code can change at any time under the
|
||||
developer's nose without the developer knowing. The [leftpad
|
||||
debacle][lpad] and the [RIAEvangelist debacle][ria] are good examples
|
||||
of the types of vulnerabilities that package managers like NPM
|
||||
enable.
|
||||
|
||||
[lpad]: https://archive.ph/Qsh7j
|
||||
[ria]: https://archive.ph/OF5I9
|
||||
|
||||
We don't use something like webpack because that introduces an opaque
|
||||
rewrite using an untrusted tool. Webpack could plausibly alter the
|
||||
runtime behavior of the program, and we would have no way to detect
|
||||
that. Even if we trusted webpack, how do we obtain webpack? NPM.
|
||||
So.
|
||||
|
||||
It is debatable whether or not we should trust the TypeScript
|
||||
compiler (TSC). On the whole, TSC probably makes Sidekick more
|
||||
secure, simply by virtue of increasing overall code quality and
|
||||
eliminating the largest categories of potential bugs. Moreover, the
|
||||
output that TSC produces is human-readable, and has a very
|
||||
straightforward mapping to the original source code. A human can
|
||||
easily read the TSC-generated JavaScript tree, even without the aid
|
||||
of the source map, and have a high degree of faith that the code is
|
||||
trustworthy and that TSC is behaving as promised.
|
||||
|
||||
|
||||
|
||||
|
||||
Source: https://github.com/sindresorhus/guides/blob/main/npm-global-without-sudo.md
|
||||
|
||||
|
||||
# How to build and view documentation
|
||||
The examples require `parasite` as a dependency, but sidekick itself does not.
|
||||
|
||||
```
|
||||
make build_docs
|
||||
make serve_docs
|
||||
~/src/vanillae $ cd libs/awcp
|
||||
~/src/vanillae/libs/awcp $ jex dwim+
|
||||
~/src/vanillae/libs/awcp $ cd ../parasite
|
||||
~/src/vanillae/libs/parasite $ jex dwim+
|
||||
```
|
||||
|
||||
## 2. Build sidekick
|
||||
|
||||
```
|
||||
~/src/vanillae/libs/parasite $ cd ../../sidekick
|
||||
~/src/vanillae/sidekick $ jex dwim+
|
||||
```
|
||||
|
||||
## 3. Build examples
|
||||
|
||||
Note the `-`, not the `+`. The difference is that `-` just builds the project,
|
||||
but does not package it.
|
||||
|
||||
```
|
||||
~/src/vanillae/sidekick $ cd examples
|
||||
~/src/vanillae/sidekick/examples $ jex dwim-
|
||||
~/src/vanillae/sidekick/examples $ python3 -m http.server 8000
|
||||
```
|
||||
|
||||
Navigate to `http://localhost:8000/` in your browser to see the examples
|
||||
|
||||
The examples are the best documentation, for now.
|
||||
|
||||
Reference in New Issue
Block a user