diff --git a/docs/jex/README.md b/docs/jex/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/sk-awcp/README.md b/docs/sk-awcp/README.md index c407dd6..44bc556 100644 --- a/docs/sk-awcp/README.md +++ b/docs/sk-awcp/README.md @@ -13,21 +13,21 @@ extension and a wallet. Sidekick implements this from the perspective of a page script (the "Æpp"). Jex is my homemade alternative to NPM. It is currently super confusing and -unusable, but I maintain it is significantly better than NPM. +borderline unusable, but it is significantly superior to NPM. The motivation was [Aegora.jp](https://aegora.jp/), which is a basic e-commerce -site where items are priced in Aeternity cryptocurrency. +site where items are priced in Aeternity. We (Craig and Peter) started working on Aegora around January of 2022, and launched on December 8, 2022. -Our first task was quite simple: discover if the user has a wallet installed. -If so, make the page background green; if not, make it red. +Our first task was to discover if the user has a wallet installed. If so, make +the page background green; if not, make it red. -This seemingly simple task was absurdly difficult with the Aeternity JavaScript -SDK, at least in its state as of early 2022. The SDK has been improved -significantly since that time, but it is still nowhere near production quality. -To this day, I would have no idea how to do that task. +This seemingly simple task was (is) absurdly difficult with the Aeternity +JavaScript SDK, at least in its state as of early 2022. The SDK has been +improved significantly since that time, but it is still nowhere near production +quality. To this day, I would have no idea how to accomplish that task. Here is how to do it with Sidekick: @@ -36,18 +36,36 @@ Here is how to do it with Sidekick: let maybe_wallet = await sk.detect(sk.TIMEOUT_DEF_DETECT_MS, // timeout "failed to detect wallet", // error if timeout logger); // logger +// returns a 'Safe' type +// if the call "worked", it will be +// {ok: true, result: } +// if not, it will be +// {ok: false, error: } +// so, we can branch on maybe_wallet.ok to see if the wallet is there or not + +if (maybe_wallet.ok) + document.body.style.background = 'green'; +else + document.body.style.background = 'red'; ``` -You have to pass in a logger to each call. You probably want `sk.cl()` which -is the console logger. Sidekick exports a few other loggers, as well as the -`sk.Logger` interface if you want to write a custom one. For instance, maybe -you want to log the page script/wallet conversation on your own server, so if -something goes wrong, you hear about it. You can write your own logger which -`POST`s the logs back to your own server, and just pass it in as an argument. +This is the basic pattern in sidekick: +- there is a sequence of steps to talk to the wallet (`detect`, `connect`, + `address`, and then either `msg_sign` or `tx_sign_noprop`). +- each step returns this `Safe` type +- your code ends up being + - do step N + - if step N worked, proceed to step N+1 + - otherwise, display an error message -Anyway, back in Februaryish of 2022, I ended up going to work trying to figure -out how the SDK was communicating with Superhero. It turns out there's an -event bus available to both the document and extension context, and posting +Everything in sidekick works pretty much exactly the way you would expect. +There's no crazy wizardry, or situations where you touch thing A and it changes +things B, C, and D behind your back. Sidekick doesn't try to outsmart you or +guess what you are trying to do. + +So, backstory: back in Februaryish of 2022, I ended up going to work trying to +figure out how the SDK was communicating with Superhero. It turns out there's +an event bus available to both the document and extension context, and posting messages in said event bus is how the two communicate. Sidekick started at this time as just a scratch project to figure out what the @@ -61,18 +79,28 @@ perfectly, was easy to use, and was entirely self-contained (i.e. no external dependencies, could be wrapped up in a tarball and dropped on the server). And maybe we should just use that. So we did. -By the way, the tooling to do "just wrap it up in a tarball and drop it on a -server" is Jex. +The tooling to do "just wrap it up in a tarball and drop it on a server" is +Jex. ## Annotated example: Aegora log-in code -Background: we don't use passwords to do login at Aegora (we don't store *any* -private information about our users). Instead, we have your wallet -cryptographically sign a random message, and then verify the signature. +I mentioned that the entire pattern of sidekick is: + +- do step N +- branch on whether or not it worked +- if so proceed +- if not error + +Let us see a real-world example + Here is the page script for the Aegora log in page, annotated. You can follow along reading . +We don't use passwords to do login at Aegora (we don't store *any* private +information about our users). Instead, we have your wallet cryptographically +sign a random message, and then verify the signature. + The first thing we do is import sidekick ```js @@ -147,14 +175,14 @@ type Safe ``` This allows you to use an `if` statement to ask the simple question "did it -work or not"? The pattern here is: +work or not"? Again, the pattern here is: 1. Perform a step -2. Use an `if` statement to tell if it worked or not. (The user rejecting a request from the page counts as "not working"). +2. Use an `if` statement to tell if it worked or not. (The user rejecting a request from your script counts as "not working"). 3. If it worked, proceed to the next step 4. If it didn't, show an error message -You might want to re-read the `detect` function, and then let's continue with `connect`: +You might want to re-read the `detect` function above, and then let's continue with `connect`: ```js @@ -272,3 +300,26 @@ async function sign_mess(pk, logger) } } ``` + +And, that's it. + +## Jex + +Using strange code from NPM is an unacceptable risk in a high-security context +(i.e. handling people's money). This risk is not hypothetical. There are +countless examples of NPM dependencies being used as an attack vector. +However, we do run into the same basic problems that something NPM-like solves: + +1. We want to share code across multiple projects. + + For instance, sidekick's test suite obviously depends on sidekick. +2. Automating builds +3. Making distribution tarballs. + +Jex solves these problems, but in a much saner way than NPM. + +Jex was originally a Python script, which has since evolved into an escript. It +will eventually become a full-blown Erlang application. The "inspiration" is +Craig's Erlang package manager, zx. + +