reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos #579

dckc · 2021-11-26T03:02:11Z

builds on #580

trial deployment:
https://ag-docs-org.netlify.app/documentation/guides/js-programming/

Reorganize "Agoric JavaScript Programming" as:
- JavaScript Framework (aka Secure Distributed Computing in JavaScript, inviting readers to watch part 1 of the the protocol labs talk series)
  - Hardened JavaScript
    - using the Counter Example from part 2 of the protocol labs talk series
    - building up to the 8 minute presentation of the 30 line makeMint core of ERTP
  - Eventual Send
    - subsumes vats
    - toward the end, invites readers to watch Warner's talk on reentrancy hazards
  - Far, marshaling
Note BigInt under ERTP Amounts but otherwise leave it to MDN etc.
Demote SES details; learning to write smart contracts need not involve learning how to build an ocap platform with stuff like lockdown(); just how to use one.

todo:

clean up git history a bit (squash down to fewer commits)

dckc · 2021-11-26T04:50:41Z

aha... the /documentation/ top level was the issue with my netlify deployment: https://ag-docs-org.netlify.app/documentation/

dckc · 2021-11-28T05:38:52Z

Here's hoping for time to discuss this with @kennyrowe, @michaelfig , @erights , and @rowgraus

trial deployment:
https://ag-docs-org.netlify.app/documentation/guides/js-programming/

todo:

clean up git history a bit (squash down to fewer commits)

dckc · 2021-11-30T21:52:13Z

some feedback from @erights (MM) and @Chris-Hibbert (CH) in discussion:

introduction diagram needs some tweaks
likewise eventual send diagram (get rid of the other half circle)
incr and decr methods can be more concise
in "Pass Style, harden(), and Remote Identity", the mutation example is good but identity is the wrong notion
"Secure Distributed Computing in JavaScript" doesn't match "JavaScript Framework" in the nav / TOC bar...
- I tried that, but it's long enough to wrap, so it's a little awkward. I'm OK with changing it, though.
- "Secure Distributed Computing in JavaScript" = endo, eventually?

We also discussed some stuff that's out of scope of this PR:

stores are missing

Reference / Specification material

MM: thoughts on where to put it?
DC: for SES, in the proposal to TC39
MM: perhaps write up other stuff in that style?

MM: a "Hardened JS API" section seems on target

MM: we have api docs and we have jsdoc in sources... reconcile? generate?
DC: yes, ideally generate
CH: but our .md process supports excerpting from tested code

MM: move API docs to agoric-sdk repo?
DC: I like it
CH: doesn't automatically get us more docs
DC: of course; but friction looks / seems lower, to me

Interactive examples #582

MM: how about examples linked to live fiddles?
DC: yes; Agoric/agoric-sdk#7032 zero install could-hosted IDE is in that direction, but it's too heavy for fiddle style
DC: current yarn install builds C code and stuff that doesn't likely fit fiddle platforms. but it should be doable with some work

main/guides/js-programming/hardened-js.md

michaelfig

Brilliant! I'd like to see this land on the doc site as soon as you consider it not to contain any glaring omissions.

main/ertp/api/amount-math.md

main/ertp/guide/amounts.md

main/glossary/README.md

main/guides/js-programming/README.md

main/zoe/guide/contract-requirements.md

erights · 2021-12-04T00:19:13Z

At #579 (comment) @michaelfig suggests

A Number, num that doesn't satisfy Number.isSafeInteger(num) will have rounding errors when you pass it to BigInt(num)

I do not believe that it true. If the number exactly represents an integer beyond the safe range, then BigInt will still convert it exactly. However, prior to conversion it may have resulted from roundoff and so should not be considered to reliably represent the integer it exactly represents. (I stated this badly. But since this suggestion won't be taken in this PR anyway, I won't bother further clarifying. If we do need to explain this well, please let me know.)

erights

Comments so far. Not done yet, but don't wait for my further comments before merging. I probably won't get back to this before Monday.

erights · 2021-12-01T20:28:47Z

main/.vuepress/config.js

@@ -106,17 +106,15 @@ module.exports = {
          ]
        },
        {
-          title: 'JavaScript Programming',
+          title: 'JavaScript Framework',


Confusing that the title in the side panel is "JavaScript Framework" but in the main panel it is "Secure Distributed Computing in JavaScript". I understand that the second is too long for the side panel, but that means we need something shorter that both can agree on. Also, this section is (will be) about "Endo", so perhaps we should start using that name now.

I'm trying out "JavaScript Framework for Secure Distributed Computing" in the main panel.

erights · 2021-12-01T20:30:54Z

main/.vuepress/themeConfig/nav.js

+        text: 'JavaScript Framework',
+        ariaLabel: 'JavaScript Framework',


See above re title of this section

main/ertp/guide/amount-math.md

main/zoe/api/zoe.md

main/guides/js-programming/README.md

erights · 2021-12-04T01:03:06Z

main/guides/js-programming/hardened-js.md

+
+<<< @/snippets/test-hardened-js.js#exploit
+
+Our goal is **defensive correctness**: a program is _defensively correct_ if it remains correct despite arbitrary behavior on the part of its clients. _For further discussion, see [Concurrency Among Strangers](http://erights.org/talks/promises/paper/tgc05.pdf) and other [Agoric papers on Robust Composition](https://papers.agoric.com/papers/#robust-composition)_.


I don't understand why, but the tg05 url works manually, but not when I click on it in the rendered text.

Hm. I can't seem to reproduce the problem.

main/guides/js-programming/hardened-js.md

- add to TOC - add JS talk video; follow makeCounter to makeMint from talk - jessie tools how-to - freeze intrinsics, ocaps/POLA - examples of std globals - Navigating the Attack Surface video - link TimerService as alternative to setTimeout under limiting globals - briefly note localStorage alternatives orthogonal persistence, `@agoric/store` - unpack counter example: stateless objects and makers; code animation - document `bundleSource` with deployment - use ses wiki link to fill out frozen globals tip - migrate debugger note - shim limitations are already documented in ses-guide.md - never mind Jessie reference - postpone XS, Intl docs (see Agoric#581) - refine Introduction diagram per conventions suggested by MarkM - fix playlist context of youtube links - let menger video play embeded as well - don't mix E with guard example - `bob` -> Bob per narrator's privilege - never mind Airbnb in eslint tools section Also, the line breaking issue goes away with the more concise method syntax. - concise incr/decr in animation too - avoid "closes over" jargon - fix: strict mode example was bogus

- Take care that non-fungible values are always referred to as _arrays_ of strings/object, not just objects. - and document `set` amounts as `copyArray` Co-authored-by: Michael FIG <michael+github@fig.org> Co-authored-by: Mark S. Miller <erights@users.noreply.github.com>

- define vat as queue + stack + heap, borrowing from MDN's event loop article; - subsume vats page - document vat-per-contract under startInstance - punt "agoric start starts several vats" until we reorg the REPL / home / solo / chain services stuff - enumerate the steps in an eventual send Use `then` rather than `await` in example code, which also matches MDN `fetch` example. - hark to `fetch()` to introduce "asynchronous" - fix: "`E()` takes a presence as an argument" it can take a local object too; or a promise - don't assume reader knows that a method call is sending a message. Use "message" only for things in vat queues. - fix: fwd ref deploy script - fix: redundancy: "non-local objects in different vats" - cite How Agoric Solves Reentrancy Hazards (Nov 2020) - I considered integrating the pubSub example, but this page is about _using_ eventual send, and since the platform forces contract writers to do it, they don't necessarily need to learn the alternatives and why avoid them. - JavaScript Programming -> JavaScript Framework - add video - roads not taken: Distributed Objects, Distributed Computing, (hides "JavaScript", which is a big part of our brand) Secure Distributed Computing (too long) - eventual send comes before `Far` - eventual-send: troubleshooting: try E(obj).method() - far: clarify distributed object semantics - build on `makeCounter()` example - use tested snippets for code examples - illustrate remotable / presence with diagram - cap arrow tail inside A with ball - incr method offset - motivate harden() by way of distributed identity - move accessor prohibition into Far API section - document PassStyles, including - `copyArray` for use in ERTP AmountMath API - avoid various bits of redundancy - demote ses (WIP) - notifiers: clean up some incoming links Co-authored-by: Michael FIG <michael+github@fig.org> Co-authored-by: Mark S. Miller <erights@users.noreply.github.com> - start heading with "JavaScript Framework ..." to match nav - never mind date qualifier for contract-per-vat - fix playlist context of youtube links - don't imply that only the Far end is remotable docs(far): avoid "identity" in pass-by-copy discussion

The scope of this page should evolve from "Contract Requirements" to "using bundleSource". It should be linked - from deploying.md by way of documenting deployPowers - from E(Zoe).install(bundle)

copy .vuepress/dist to .vuepress/dist-root/documentation/ to reify the root URL structure on disk. This fits conventions for static site hosting such as netlify.

MM said I should proceed in his comment

dckc closed this Nov 26, 2021

This comment has been minimized.

Sign in to view

dckc reopened this Nov 26, 2021

dckc force-pushed the js-guide branch from 02a8c45 to 5171f3b Compare November 26, 2021 17:34

dckc changed the title ~~integrate videos; reorg hardened js; focus on learning to write zoe smart contracts (WIP)~~ reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos (WIP) Nov 26, 2021

dckc force-pushed the js-guide branch 6 times, most recently from 001afe9 to a8cf682 Compare November 27, 2021 19:55

dckc mentioned this pull request Nov 28, 2021

cite XS conformance, Intl handling #581

Open

dckc force-pushed the js-guide branch from 9a4e83c to 4e80192 Compare November 28, 2021 05:35

dckc requested review from michaelfig and erights November 28, 2021 05:36

dckc changed the title ~~reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos (WIP)~~ reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos Nov 28, 2021

dckc marked this pull request as ready for review November 28, 2021 05:37

dckc requested a review from rowgraus November 28, 2021 05:37

dckc force-pushed the js-guide branch 2 times, most recently from 3710f0b to b3d66a1 Compare November 30, 2021 03:00

dckc commented Nov 30, 2021

View reviewed changes

main/guides/js-programming/hardened-js.md Outdated Show resolved Hide resolved

dckc force-pushed the js-guide branch from b3d66a1 to 60d8a9b Compare December 1, 2021 19:33

michaelfig approved these changes Dec 2, 2021

View reviewed changes

dckc mentioned this pull request Dec 2, 2021

document Nat and differences from BigInt coercion #586

Open

erights previously requested changes Dec 4, 2021

View reviewed changes

dckc force-pushed the js-guide branch from 3c62942 to 6599370 Compare December 4, 2021 17:30

dckc mentioned this pull request Dec 4, 2021

Tracking issue for getting 3rd party packages more SES friendly endojs/endo#576

Closed

dckc force-pushed the js-guide branch from 4a10abe to 24bb3b6 Compare December 4, 2021 20:56

dckc and others added 5 commits December 4, 2021 15:03

docs(contract-requirements): start documenting bundleSource

e5f529d

The scope of this page should evolve from "Contract Requirements" to "using bundleSource". It should be linked - from deploying.md by way of documenting deployPowers - from E(Zoe).install(bundle)

build(docs): docs:re-root for documentation/ root

e02ccb7

copy .vuepress/dist to .vuepress/dist-root/documentation/ to reify the root URL structure on disk. This fits conventions for static site hosting such as netlify.

dckc force-pushed the js-guide branch from 24bb3b6 to e02ccb7 Compare December 4, 2021 21:04

dckc requested a review from erights December 4, 2021 21:05

dckc merged commit 7470dd3 into Agoric:main Dec 4, 2021

dckc mentioned this pull request Mar 6, 2022

docs: draft: Intro to Hardened JS #540

Closed

5 tasks

dckc mentioned this pull request Dec 22, 2023

Revise the Javascript Framework docs #753

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos #579

reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos #579

dckc commented Nov 26, 2021 •

edited

Loading

dckc commented Nov 26, 2021

This comment has been minimized.

dckc commented Nov 28, 2021 •

edited

Loading

dckc commented Nov 30, 2021 •

edited

Loading

michaelfig left a comment

erights commented Dec 4, 2021

erights left a comment

erights Dec 1, 2021

dckc Dec 4, 2021

erights Dec 1, 2021

erights Dec 4, 2021

dckc Dec 4, 2021

		text: 'JavaScript Framework',
		ariaLabel: 'JavaScript Framework',


		<<< @/snippets/test-hardened-js.js#exploit

		Our goal is defensive correctness: a program is _defensively correct_ if it remains correct despite arbitrary behavior on the part of its clients. _For further discussion, see [Concurrency Among Strangers](http://erights.org/talks/promises/paper/tgc05.pdf) and other [Agoric papers on Robust Composition](https://papers.agoric.com/papers/#robust-composition)_.

reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos #579

reorg JS stuff as Secure Distributed Computing in JavaScript; integrate videos #579

Conversation

dckc commented Nov 26, 2021 • edited Loading

dckc commented Nov 26, 2021

This comment has been minimized.

dckc commented Nov 28, 2021 • edited Loading

dckc commented Nov 30, 2021 • edited Loading

Reference / Specification material

Interactive examples #582

michaelfig left a comment

Choose a reason for hiding this comment

erights commented Dec 4, 2021

erights left a comment

Choose a reason for hiding this comment

erights Dec 1, 2021

Choose a reason for hiding this comment

dckc Dec 4, 2021

Choose a reason for hiding this comment

erights Dec 1, 2021

Choose a reason for hiding this comment

erights Dec 4, 2021

Choose a reason for hiding this comment

dckc Dec 4, 2021

Choose a reason for hiding this comment

dckc commented Nov 26, 2021 •

edited

Loading

dckc commented Nov 28, 2021 •

edited

Loading

dckc commented Nov 30, 2021 •

edited

Loading