Blocked on https://github.com/Agoric/cosmic-swingset/issues/71

(...) lots of back and forth. I wonder whether a github pull request is a good tool for this

Originally posted in #10 (comment)

It's not the first time i've come across this problem. A git/hub repo with markdown resources is cool for historicity, receiving pull requests for small changes, and easy publishing, but for a first draft with potentially lots of discussion, it seems inappropriate

Among other experiences, i've had this problem with a collective blog
One solution we came up with is to use Google Docs for the first draft, then transform to markdown when we're in agreement
As long as we don't create dozens of new pages a week, the cost of transforming manually a google docs to markdown is fairly small. It's also possible to automate this transformation (i started a project for this purpose with a friend as a concrete exercice for her to learn how to code) and turn the process from Google Docs to Pull Request on the proper repo into 1 click

This module is full of one-letter methods, and combined with no docs, it is very hard to dive into.

I may document this as I go, because I'm gradually chipping in, but opening an issue in case someone wants to quickly type up an answer key before I have to deduce it from source.

Some mysterious letters that I'm trying to decode:

• E() itself, which I think basically just lines up methods on the eventual result, but potentially remotely, using some messaging format?
• E.C(presence)
• E.C(presence).G
• E.C(presence.G[objectKey].M[methodName]
• E.C(presence).G[promiseKey].P

I'm also unclear to what degree pipelining works now. This issue suggests it is not added yet, but some aspect of it was merged soon after.

Some notes on how I'm testing capTP

As a very simple test, I'm experimenting whether I can send a message that says to a pizzeria presence "whatIsLargestPizzaSize().then(orderPizzaBySize)". This should be doable with a single round trip, and so that is my basic benchmark for the feature.

More realistically, I would want to ask pizzeria.getSizeList().then(pickLargestOption).then(orderPizza), where pickLargestOption could be a user-specified algorithm, which might require the .there() call that Mark described to me.

Anyways, once I get a deeper understanding here, I may contribute some of these features here instead of at capnode, if I can just get the developer ergonomics up to where I'd feel comfortable promoting them.

See https://github.com/Agoric/ERTP/issues/179#issuecomment-545207886

I'll probably add this somehow to the security properties section of the second tutorial

The only thing i could find was here https://github.com/Agoric/ERTP/blob/a7601a0fa1e26f4b2849e3c29d2026ab07331cfc/util/sameStructure.js#L32-L37
but it's used in lots of places (chainmail interfaces, comments, this documentation repo)

I also proposed to rename this API, see https://github.com/Agoric/ERTP/issues/206

https://github.com/Agoric/Documentation/blob/master/main/ertp/api/assay.md#assaygetunitops

function insist(asset, units) {
  !assay.getUnitOps().isEmpty(units);
  // no use rights present in units ${units}`;
}

This function does not really do anything (doesn't return, doesn't throw) and there is a possible typo between asset and assay

After Agoric/agoric-sdk#375 , things have changed quite a bit and the current doc does not really reflect it yet
Built-in extentOps (soon "amountMath") need to be there as well

• remove dead links at bottom
• add create-react-app repo link https://github.com/Agoric/agoric

Currently, contract installation is done by:

• creating a file in the middle of the cosmic-swingset repo (hacking the pixel demo, really)
• write the contract content in the file
• expose the contract source code as a property of home
• start scenario 3, 2 or 1 of cosmic-swingset

I think a nicer way is possible. Likely via home.uploads

A couple of questions i cannot answer yet:

• is {try(attempt){return attempt === 37 ? 'you win' : 'you lose'} a "valid" contract?
  • currently? eventually?
• is Swingset a requirement to run contracts?
• Do contracts need to be written in Jessie?
  • currently? eventually?

Currently it is just npm install and npm test. We should mention the Agoric ERTP package now that we have it, and perhaps a few more things.

agoric.com/documentation/ertp/guide/getting-started.html#installation

We made a change to the ERTP PR Agoric/agoric-sdk#523 such that AmountMath.coerce now only accepts amounts, not extents.

This has other effects: mint.mintPayments() only accepts amounts now. We will need to change our examples.

Two things that can help:

1. AmountMath is one of the values returned from produceIssuers now, so we have it already and can use AmountMath.make
2. We've started using a pattern of renaming AmountMath.make to roughly the allegedName of the assets: moola(3), bucks(50) etc. Eventually we may be able to return this option as part of ERTP proper.

Something is added to the redemption object

I haven't seen it in the doc

Asking @katelynsills for instance

My impression is that it adds a layer of complexity which does not seem to be worth its cost

See https://github.com/Agoric/ERTP/issues/215

What do keywords represent? Is it roles in the contract? Various "asset types"? Something else?

These were added in #22, but not reported before the merge of #23

We currently say something like the following in zoe.chainmail

   * To redeem an invite, the user normally provides a proposal (their rules for the
   * offer) as well as payments to be escrowed by Zoe.  If the proposal or payments are
   * undefined, the default is not to propose or pay (just to obtain the invite's seat).

Possibly bike shed the name 'redeem'

I think that all examples i have seen of ERTP either use natural numbers (1, 10, 1000, 32) or use objects to represent rights

Euros, dollars, bitcoins all use non-natural numbers in their usual representation

But JavaScript is notoriously inadequate for non-natural numbers (0.1 + 0.2 !== 0.3)

What is the approach recommanded by Agoric to model non-natural number assets?

(Attn @erights)

We need to update the Cosmic-Swingset README and move it to this documentation repo.

Cross posted to agoric-sdk repo as Agoric/agoric-sdk#548

David Bruant @DavidBruant pointed out in https://github.com/Agoric/ERTP/issues/220 that people who are unfamiliar with smart contract platforms like Ethereum won't immediately understand that smart contracts can "own" or hold digital assets themselves. Since this feature allows us to get rid of a number of third parties, it's an important concept to convey, so we should put it somewhere prominent in the documentation.

I'm trying to create a visual for the different parts created by agoric start (and the parts interacting with what's created)

Right now, i'm at:

I know i got the major parts more or less ok
i'm sure i got lots of minor parts super wrong, but i don't know in what way

@michaelfig @Chris-Hibbert (maybe others?), could you comment on this first draft and tell me how to improve this?

Thanks!

A couple questions to get started:

• are all vats run in the fake blockchain?
• when a contract is deployed, is a new vat created or is it eval'ed in an existing vat (and which?)

We should write up a description of the format and expectations for a zoe contract. We currently have a description of what contracts can expect from zoe, but not what zoe expects from contracts, and what choices contracts can make in their implementation

The starting point is that a zoe contract is a javascript file that can import other javascript code, including harden, Nat, zoeHelpers and anything else we make available. We should describe whether there's any limitation on what library code they can use, and how they can split their code across multiple files.

The file needs to export a makeContract function that takes zoe as a parameter, and return a record that contains at least invite:. We should describe the conventional use of the publicAPI: keyword and say whether there's any particular support for it. What else needs to be written up about makeContract's return value?

We should describe what you do to create an invite, and what's required/expected of the embedded seat. I think it makes sense to have sections describing the case where instantiating the contract hands out a particular seat that provides access to other seats versus contracts that expect all the seats to be handed out from the publicAPI, or something similar.

There's probably more. It might be worthwhile to provide a skeleton template if enough of this is always the same.

Dean asked for an example of a trivial contract entered into the cosmic-SwingSet Read-Eval-Print loop to show how contractHost and other facilities available from home can be experimented with there.

I started with this trivial contract:

/* global makePromise */
// Copyright (C) 2019 Agoric, under Apache License 2.0

import harden from '@agoric/harden';

const doubler = harden({
  start: (_, inviteMaker) => {
    const result = makePromise();
    const seat = harden({
      provide(n) { result.res(2*n); },
      result() { return result.p; },
    });

    return harden({
      seat: inviteMaker.make('multiplicand', seat),
    });
  },
});

const doublerSrcs = harden({ start: `${doubler.start}` });

export { doublerSrcs };

Ignoring false starts and dead-ends, I had this interaction with the REPL:

command[2] d1 = { start: (, inviteMaker) => { const result = makePromise(); const seat = harden({ provide(n) { result.res(2*n); }, result() { return result.p; }, }); return harden({ seat: inviteMaker.make('multiplicand', seat), }); }, }
history[2] {"start":[Function start]}
command[3] d1Srcs = { start: `${d1.start}` };
history[3] {"start":"(, inviteMaker) => {\n const result = makePromise();\n const seat = harden({\n provide(n) {\n result.res(2 * n);\n },\n\n result() {\n return result.p;\n }\n\n });\n return harden({\n seat: inviteMaker.make('multiplicand', seat)\n });\n }"}
command[4] triv1 = home.contractHost~.install(d1Srcs)
history[4] [Presence o-56]
command[5] triv1~.spawn({})
history[5] {"seat":[Presence o-57]}
command[6] home
history[6] {"gallery":[Presence o-50],"handoffService":[Presence o-51],"purse":[Presence o-52],"canvasStatePublisher":[Presence o-53],"contractHost":[Presence o-54],"handoff":[Presence o-55]}
command[8] home.purse~.getIssuer()
history[8] [Presence o-58]
command[17] iss = home.contractHost~.getInviteIssuer()
history[17] [Presence o-59]
command[18] iss~.claimAll(history[5].seat, "seat1")
history[18] [Presence o-60]
command[20] seat1P = home.contractHost~.redeem(history[18])
history[20] [Presence o-61]
command[21] seat1P~.provide(3)
history[21] undefined
command[22] seat1P~.result()
history[22] 6

Notice that line 2 drops const and the outer harden from the source file.

Milestone and issues for Zoe 0.3.0: https://github.com/Agoric/agoric-sdk/milestone/5

We should add more writeup of how the invites work. They're implied by ERTP and various things, but we don't explicitly discuss it anywhere.

Examples to follow

The current licence is Apache-2
However, it's not clear whether this licence appropriately addresses non-code contents (prose and images)

• MDN addresses this with code having a CC-0 licence and content having CC-BY-SA licence
• developers.google.com has its code in Apache 2 and content as CC-BY

Putting this in a more public place than my notebook. This is a living issue so I don't make n number of issues for every single one.

"Claim" an item by putting your name in front of it in bold and the status.

Homepage

• Update so CTA goes to Getting Started

ERTP

• Complete ERTP glossary

  • path: /ertp/glossary/README.md

• Move ExtentOps API into own file and place underneath UnitOps in the sidebar

• Pull Assay, Payments, Purse sections into own files

  • Assay
  • Payments
  • Purse

• Pull out definitions from UnitOps and place into /ertp/guide/. Makes much more sense to put it there. API should only contain the methods.

• Pull out 'Gotchas' from ERTP guide and put into own sections

• Complete any missing examples in ERTP

• Add the following methods to Payments API - A payment's balance can only fall, through the action of `depositExactly()`, `claimExactly()` or `burnExactly()`. Payments can be converted to Purses by getting a verified assay and calling `assay.makeEmptyPurse().depositAll(payment)`;

• BAR: starting Finish default-configuration file

• DOM: PR pending. Almost complete. Have questions/comments (see red text). ContractHost API [contractHost.chainmal)(https://github.com/Agoric/ERTP/blob/master/core/contractHost.chainmail)

• Finish unitOps.make(allegedExtent) params definition

• line 106 /ertp/api/contract-hosts.md - write and verify example - Chris

• line 128 /ertp/api/contract-hosts.md - verify description -Chris

Zoe

• KATE: STARTING Complete Zoe glossary
  • path: /zoe/glossary/README.md
• DOM: in progress zoe.chainmail -> Zoe API
• Check this: Zoe and ZoeContractFacet have some similar methods so those examples are the same. Those should be double-checked to make sure they are accurate in both locations. Methods: getInviteAssay, getEscrowReceiptAssay
• verify zcf.getSeatAssay() example - Couldn't find an example in the code, this needs checking.
• verify zoe.getInviteAssay()

Add Other Projects
Projects Reference
The most relevant of these project's documentation should be pulled out and placed into the site. The less relevant projects can have external links

• Add definitions for each project (maybe in like a master project list page? not sure yet)
• Make nested navbar

Site

• BAR: in process Add favicon

Proofreading:

• Add missing code markdowns
• Review for typos
• Verify links
• Verify navbar
• Verify sidebars

http://agoric.com/documentation/ertp/guide/#introduction

https://github.com/Agoric/Documentation/blob/master/main/ertp/api/assay.md#assaymakeunitsextent

import { setup } from '../setupBasicMints';

const { assays: originalAssays, mints, unitOps } = setup();

It's not clear to me where the '../setupBasicMints' module comes from

See https://github.com/Agoric/ERTP/issues/140

• blockchain
• solo node
• (Vat/SwingSet ?)
• ERTP/Contract host
  • contract source code (+Jessie)
  • terms and inviteMaker arguments
  • provided top-level variables

I notice that some of our own documentation is *.rst rather than *.md . Should we suggest that contributions can/should be *.rst ? How do we decide when to use which?

Originally posted by @erights in #11

Depending on the case, it can be transformed to .md or kept as is. We can see when the case comes

Edited by Kate:

README-agoric-dapp.md has been moved to dapps/README.md, but we should continue to improve it.

It's not clear to me from the existing doc and API what "(in)active" means. It's also unclear for me how to change a status from one to the other or when/why such a change happens

ping @katelynsills

make ERTP methods accept promises or payments:

Agoric/agoric-sdk#753

from Agoric presentation slide SF Defi Hackathon

Milestone and issues for ERTP 0.4.0: https://github.com/Agoric/agoric-sdk/milestone/6

Doing 2 things at once here:

• share knowledge about terms
• show how a person setting up the contract/game can share an invite with the player

I created a pull request and got this

I think that at this stage of the doc, this limitation is stronger than necessary

I'm merging my own pull request per a discussion we've had yesterday about typos being ok to go without PR or with self-merged PRs

I realized that we do not have the expected timer interface documented anywhere. For instance, Zoe requires it to have a method setWakeup. What else is expected?