From 4bd0b16cbb6baf7c34374978c4d994752267189f Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Mon, 11 Apr 2022 14:30:33 -0400 Subject: [PATCH] style: Accept suggestions https://github.com/Agoric/documentation/pull/655 --- main/ertp/api/brand.md | 6 +++--- main/ertp/api/issuer.md | 14 +++++++------- main/ertp/api/purse.md | 4 ++-- main/ertp/guide/issuers-and-mints.md | 8 ++++---- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/main/ertp/api/brand.md b/main/ertp/api/brand.md index 7efda4d48..574a0bd72 100644 --- a/main/ertp/api/brand.md +++ b/main/ertp/api/brand.md @@ -22,9 +22,9 @@ other `mint` or `issuer`. Return `true` if `issuer` is the brand's `issuer`, `false` if not. -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 B is its `brand`, then the `brand` is unreliable. +Note that a `brand` from an untrusted source can misrepresent its association with +an `issuer`. The claim should be cross-checked against +[`issuer.getBrand()`](./issuer.md#issuer-getbrand) for mutual agreement. ```js const isIssuer = brand.isMyIssuer(issuer); diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md index 2249b7ebf..1e79c6b03 100644 --- a/main/ertp/api/issuer.md +++ b/main/ertp/api/issuer.md @@ -76,10 +76,10 @@ means there can be multiple issuers/mints/brands with the same alleged name, and thus the name by itself does not uniquely identify an issuer. Rather, the `brand` object does that. -To put it another way, nothing stops different people from creating -multiple `issuers` with the alleged name `Quatloos`...but that doesn't -make any of them **the** Quatloos `issuer`. The alleged name is just a -human readable version which is helpful for debugging. +To put it another way, nothing stops anyone from creating an `issuer` +with the alleged name "Quatloos" or even "BTC", regardless of whether +or not such a name is already in use. The alleged name is just a +human readable string which is helpful for debugging. ```js const { issuer: quatloosIssuer } = makeIssuerKit('quatloos'); const quatloosIssuerAllegedName = quatloosIssuer.getAllegedName(); @@ -109,9 +109,9 @@ moolaIssuer.getAssetKind(); // Returns 'set', also known as 'AssetKind.SET` - `payment` `{Payment}` - Returns: `{Amount}` -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. +Describe the `payment`'s balance as an Amount. Because a `payment` from an untrusted +source cannot be trusted to provide its own true value, `issuer` must be used to +validate its `brand` and report how much it contains. ```js const { issuer: quatloosIssuer, mint: quatloosMint, brand: quatloosBrand} = makeIssuerKit('quatloos'); diff --git a/main/ertp/api/purse.md b/main/ertp/api/purse.md index 928f129c7..d2d50d546 100644 --- a/main/ertp/api/purse.md +++ b/main/ertp/api/purse.md @@ -75,8 +75,8 @@ const checkNotifier = async () => { - Returns: `{Amount}` 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. +`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 a promise, it throws an error. While the above applies to local and remote `purses`, for remote `purses` there may be effects on this operation due to use of `promises` and asynchronicity. You diff --git a/main/ertp/guide/issuers-and-mints.md b/main/ertp/guide/issuers-and-mints.md index f54495d84..c077f124b 100644 --- a/main/ertp/guide/issuers-and-mints.md +++ b/main/ertp/guide/issuers-and-mints.md @@ -53,7 +53,7 @@ API Reference](/ertp/api/#ertp-api). - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getBrand - **Purse operation** - [`issuer.makeEmptyPurse()`](/ertp/api/issuer.md#issuer-makeemptypurse) - - 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`. - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeEmptyPurse - **Payment operations** - [`issuer.burn(payment, optAmount)`](/ertp/api/issuer.md#issuer-burn-payment-optamount) @@ -82,9 +82,9 @@ API Reference](/ertp/api/#ertp-api). **Related Methods:** -**Note**: None of these methods return a canonical result. If the `issuer` itself doesn't acknowledge that -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. +**Note**: These methods help you find the right `issuer`, but aren't authoritative. +A `mint`, `brand`, or `purse` is actually associated with an `issuer` only if +the `issuer` itself acknowledges the association. - [`mint.getIssuer()`](/ertp/api/mint.md#mint-getissuer) - Return the `issuer` uniquely associated with the `mint`.