Restrict "burn" to describing operations that destroy assets #655

gibson042 · 2022-04-02T03:05:23Z

Fixes #654

Also includes general consistency/cleanup of affected pages. Probably best reviewed commit-by-commit.

netlify · 2022-04-02T03:05:28Z

✅ Deploy Preview for agoric-docs ready!

Name	Link
🔨 Latest commit	`2b6b500`
🔍 Latest deploy log	https://app.netlify.com/sites/agoric-docs/deploys/625474072cdfcc0008e85fc2
😎 Deploy Preview	https://deploy-preview-655--agoric-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

gibson042 · 2022-04-02T03:06:28Z

main/ertp/api/issuer.md

@@ -89,8 +89,7 @@ const quatloosIssuerAllegedName = quatloosIssuer.getAllegedName();
 ## `issuer.getAssetKind()`
 - Returns: `{AssetKind}`

-Get the kind of this `issuer`'s asset. It returns one of
-`AssetKind.NAT` (`nat`) or `AssetKind.SET` (`set`).
+Return the kind of the `issuer`'s asset; either `AssetKind.NAT` ("nat") or `AssetKind.SET` ("set").


To anticipate a request, I think we'll want to document AssetKind.COPY_SET and AssetKind.COPY_BAG here, as was done in 85fc794#diff-567699eff5882f854f56340cee0537815d3e363b61e098208212dc172190dd3dR43 . But I think that belongs in a followup.

Is there an issue?

erights

LGTM. Awesome to see these cleanups! Thanks much!!!

erights · 2022-04-09T00:42:31Z

main/ertp/api/brand.md

 An `issuer` uniquely identifies its `brand`. A `brand` **unreliably** identifies 
 its `issuer`. If `brand` B claims its `issuer` is A, but A doesn't agree 


That's not quite right. Either or both the issuer and the brand may be ill behaved, which we cannot in general defend against. They may also represent different interests. The issuer may claim that someone else's brand is its own brand. The brand may agree that someone else's issuer is its own issuer. What we need to verify, and what this protocol enables us to verify, is that this issuer and this brand each endorse the other. We need mutual agreement. This tells us that they at least represent one interest. Zoe does in fact verify this when she registers a new issuer.

main/ertp/api/issuer.md

erights · 2022-04-09T00:47:30Z

main/ertp/api/issuer.md

@@ -66,7 +66,7 @@ const combinedProperty = AmountMath.make(propertyTitleBrand, ['1292826', '102839
 ## `issuer.getAllegedName()`
 - Returns: `{allegedName}`

-Returns the `allegedName` for this `issuer`.
+Return the `allegedName` for the `issuer` (the non-trusted human-readable name of its associated `brand`).


I think it's work having an example here, like how anyone can create a new issuer whose allegedName is BTC.

erights · 2022-04-09T00:47:54Z

main/ertp/api/issuer.md

@@ -89,8 +89,7 @@ const quatloosIssuerAllegedName = quatloosIssuer.getAllegedName();
 ## `issuer.getAssetKind()`
 - Returns: `{AssetKind}`

-Get the kind of this `issuer`'s asset. It returns one of
-`AssetKind.NAT` (`nat`) or `AssetKind.SET` (`set`).
+Return the kind of the `issuer`'s asset; either `AssetKind.NAT` ("nat") or `AssetKind.SET` ("set").


Is there an issue?

erights · 2022-04-09T00:51:08Z

main/ertp/api/issuer.md

+Describe the `payment`'s balance as an Amount. Because `payment` cannot
+be trusted to provide its own true value, `issuer` must be used to validate
+the `payment`'s `brand` and report how much it contains.


I don't like this explanation. The mistrust we have in payments is not due to some intrinsic feature of the payment. It is due to the expected use pattern, where Bob might receive one from Alice, who he doesn't trust. Since Bob doesn't trust Alice, he must consider the possibility that Alice might have sent him something else in the payment position.

erights · 2022-04-09T01:00:27Z

main/ertp/api/purse.md

@@ -74,7 +74,7 @@ const checkNotifier = async () => {
 - `optAmount` `{Amount}` - Optional. 
 - Returns: `{Amount}`

-Deposit all the contents of `payment` into this `purse`, returning an `amount` describing the
+Deposit all the contents of `payment` into `purse`, returning an `amount` describing the
 `payment`'s digital assets (i.e. the deposit amount). If the optional argument `optAmount` does not equal the balance of


Suggested change

`payment`'s digital assets (i.e. the deposit amount). If the optional argument `optAmount` does not equal the balance of

`payment`'s digital assets (i.e. the deposited amount). If the optional argument `optAmount` does not equal the balance of

erights · 2022-04-09T01:01:02Z

main/ertp/api/purse.md

@@ -74,7 +74,7 @@ const checkNotifier = async () => {
 - `optAmount` `{Amount}` - Optional. 
 - Returns: `{Amount}`

-Deposit all the contents of `payment` into this `purse`, returning an `amount` describing the
+Deposit all the contents of `payment` into `purse`, returning an `amount` describing the
 `payment`'s digital assets (i.e. the deposit amount). If the optional argument `optAmount` does not equal the balance of
 `payment`, or if `payment` is an unresolved promise, it throws an error.


Important:

Suggested change

`payment`, or if `payment` is an unresolved promise, it throws an error.

`payment`, or if `payment` is a promise, it throws an error.

erights · 2022-04-09T01:04:14Z

main/ertp/guide/issuers-and-mints.md

 - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAllegedName
 - [`issuer.getAssetKind()`](/ertp/api/issuer.md#issuer-getassetkind)
- - Get the kind of asset for this `issuer`, either `AssetKind.NAT` (`nat`),
- or `AssetKind.SET` (`set`).
+ - Return the kind of the `issuer`'s asset; either `AssetKind.NAT` ("nat") or `AssetKind.SET` ("set").


Here too ;)

erights · 2022-04-09T01:05:27Z

main/ertp/guide/issuers-and-mints.md

- - Returns a new empty `purse` for the `brand` associated with the `issuer`. The `purse` only accepts valid 
- deposits of its associated `brand`, so you can retroactively identify a valid `payment` of that `brand`
- by successfully depositing it into this `purse`.
+ - Make and return an empty `purse` that holds assets of the `brand` associated with the `issuer`.


Suggested change

- Make and return an empty `purse` that holds assets of the `brand` associated with the `issuer`.

- Make and return an empty `purse` for holding assets of the `brand` associated with the `issuer`.

Since it is empty, I think this is slightly better.

erights · 2022-04-09T01:07:22Z

main/ertp/guide/issuers-and-mints.md

@@ -135,11 +86,11 @@ API Reference](/ertp/api/#ertp-api).
 the `mint`, `brand` or `purse` are associated with it, then they're invalid. These methods help you find 
 the right `issuer`, but aren't authoritative.


Feel free to rewrite this paragraph!

Agoric#655

…I documentation

…TP API documentation

…ptions Purses and Payments

…yments Aligns with the same list in Payment API documentation

…ptions Issuers and Mints

…ints

Agoric#655

gibson042 requested a review from erights April 2, 2022 03:05

gibson042 self-assigned this Apr 2, 2022

gibson042 commented Apr 2, 2022

View reviewed changes

gibson042 mentioned this pull request Apr 4, 2022

style: Cleanup ERTP Guide #660

Merged

erights approved these changes Apr 9, 2022

View reviewed changes

gibson042 mentioned this pull request Apr 11, 2022

Audit method signature documentation for accuracy, especially w.r.t. promises #666

Open

gibson042 added a commit to gibson042/Agoric-documentation that referenced this pull request Apr 11, 2022

style: Accept suggestions

81f20bc

Agoric#655

gibson042 added 12 commits April 11, 2022 14:31

fix: Update the Glossary definition of "burn"

3b75d7c

fix: Replace incorrect use of "burn" in ERTP Introduction

75dc6cb

fix: Replace incorrect use of "burn" in issuer API documentation

3f397e0

chore: Use consistent language to describe promise handing in ERTP AP…

45224c7

…I documentation

chore: Differentiate payment parameters from the Payment type in ER…

6b8ed57

…TP API documentation

chore: Clarify Brand matching requirements in ERTP API documentation

21d824b

fix: Replace incorrect use of "burn" in payment API documentation

43dcab0

chore: Better align ERTP API method references with their full descri…

508de20

…ptions Purses and Payments

chore: Alphabetize Payment-related method references in Purses and Pa…

120d282

…yments Aligns with the same list in Payment API documentation

chore: Better align ERTP API method references with their full descri…

a8cbd7c

…ptions Issuers and Mints

chore: Alphabetize Payment-related method references in Issuers and M…

bef00a6

…ints

style: Accept suggestions

2b6b500

Agoric#655

gibson042 force-pushed the gh-654-burn branch from 81f20bc to 2b6b500 Compare April 11, 2022 18:31

gibson042 merged commit 4bd0b16 into Agoric:main Apr 11, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restrict "burn" to describing operations that destroy assets #655

Restrict "burn" to describing operations that destroy assets #655

gibson042 commented Apr 2, 2022

netlify bot commented Apr 2, 2022 •

edited

Loading

gibson042 Apr 2, 2022

erights Apr 9, 2022

gibson042 Apr 11, 2022

erights left a comment

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

erights Apr 9, 2022

		An `issuer` uniquely identifies its `brand`. A `brand` unreliably identifies
		its `issuer`. If `brand` B claims its `issuer` is A, but A doesn't agree

	`payment`'s digital assets (i.e. the deposit amount). If the optional argument `optAmount` does not equal the balance of
	`payment`'s digital assets (i.e. the deposited amount). If the optional argument `optAmount` does not equal the balance of

	`payment`, or if `payment` is an unresolved promise, it throws an error.
	`payment`, or if `payment` is a promise, it throws an error.

	- Make and return an empty `purse` that holds assets of the `brand` associated with the `issuer`.
	- Make and return an empty `purse` for holding assets of the `brand` associated with the `issuer`.

		@@ -135,11 +86,11 @@ API Reference](/ertp/api/#ertp-api).
		the `mint`, `brand` or `purse` are associated with it, then they're invalid. These methods help you find
		the right `issuer`, but aren't authoritative.

Restrict "burn" to describing operations that destroy assets #655

Restrict "burn" to describing operations that destroy assets #655

Conversation

gibson042 commented Apr 2, 2022

netlify bot commented Apr 2, 2022 • edited Loading

✅ Deploy Preview for agoric-docs ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erights left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Apr 2, 2022 •

edited

Loading