From 3b75d7cc6fb983a0e2f2d0768f51a2c583cfbe09 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 16:11:31 -0400
Subject: [PATCH 01/12] fix: Update the Glossary definition of "burn"

---
 main/glossary/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/main/glossary/README.md b/main/glossary/README.md
index 897fbec1c..1e836d191 100644
--- a/main/glossary/README.md
+++ b/main/glossary/README.md
@@ -137,7 +137,9 @@ unzip bundle.zip
 
 ## Burn
 
-Destroy all digital assets in a payment, for example as part of consuming it in an exchange. See [`issuer.burn(payment, optAmount)`](/ertp/api/issuer.md#issuer-burn-payment-optamount).
+Destroy digital assets. Burning a [payment](#payment) additionally makes it
+unavailable for later use. See
+[`issuer.burn(payment, optAmount)`](/ertp/api/issuer.md#issuer-burn-payment-optamount).
 
 ## Comparable
 

From 75dc6cbdf83c8d4e6923941178dddf08f3592416 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 16:13:29 -0400
Subject: [PATCH 02/12] fix: Replace incorrect use of "burn" in ERTP
 Introduction

---
 main/getting-started/ertp-introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/main/getting-started/ertp-introduction.md b/main/getting-started/ertp-introduction.md
index 5655b55c8..9b917eb76 100644
--- a/main/getting-started/ertp-introduction.md
+++ b/main/getting-started/ertp-introduction.md
@@ -48,7 +48,7 @@ If everything passes the checks, the assets move from the `payment` to
 the `purse`. If there's a problem, it throws an error.
 
 After a successful deposit, ERTP guarantees:
-- The `payment` is burned (i.e. destroyed).
+- The `payment` is consumed and unavailable for later use.
 - The `purse` contains the total of what it held before plus the `payment`'s full content.
   - For example, deposit of a 3 Quatloos `payment` into a `purse` that already has 7 Quatloos
     updates the purse's balance to 10 Quatloos.

From 3f397e085bfe9fa2539860ba736590dddf489520 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 17:19:44 -0400
Subject: [PATCH 03/12] fix: Replace incorrect use of "burn" in issuer API
 documentation

---
 main/ertp/api/issuer.md | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index 4cc32283e..a64e9d01a 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -149,8 +149,9 @@ const quatloosPurse = quatloosIssuer.makeEmptyPurse();
 - `optAmount` `{Amount}` - Optional
 - Returns: `{Amount}`
 
-Burn (destroy) all of the digital assets in the `payment`
-and return an `amount` of what was burned. 
+Destroy all of the digital assets in the `payment`,
+make it unavailable for later use,
+and return an Amount of what was burned.
 
 `optAmount` is optional. If `optAmount` is present, 
 the code insists the `payment` balance is equal to `optAmount`, to prevent sending the wrong `payment`
@@ -174,9 +175,8 @@ const burntAmount = quatloosIssuer.burn(paymentToBurn, amountToBurn);
 - `optAmount` `{Amount}` 
 - Returns: `{Payment}` 
 
-Transfer all digital assets from `payment` to a new `payment` and burn the
-original. This allows the owner to be sure no other references to this
-payment survive, so they are the exclusive owner. 
+Transfer all digital assets from `payment` to a new Payment and consume the
+original, making it unavailable for later use.
 
 `optAmount` is optional. 
 If `optAmount` is present, `payment`'s balance must be
@@ -201,9 +201,9 @@ const newPayment = quatloosIssuer.claim(originalPayment, amountToTransfer);
 - `optTotalAmount` `{Amount}` - Optional.
 - Returns: `{Payment}`
 
-Combines multiple `payments` into one `payment`.  If any `payment` in `paymentsArray` is 
+Combine multiple Payments into one new Payment. If any `payment` in `paymentsArray` is
 a `promise`, the operation proceeds after all the `payments`
-resolve. The `payments` in `paymentsArray` are burned.
+resolve. All Payments in `paymentsArray` are consumed and made unavailable for later use.
 
 If the optional `optTotalAmount` is present, the total of all the `payment` `amounts` in the
 array must equal `optTotalAmount` or it throws an error.
@@ -240,11 +240,11 @@ const badPayment = quatloosIssuer.combine(payments);
 - `paymentAmountA` `{Amount}`
 - Returns: `{Array <Payment>}`
 
-Split a single `payment` into two new `payments`, A and B, according to `paymentAmountA`. 
+Split a single `payment` into two new `payments`, A and B, according to `paymentAmountA`.
 For example, if the `payment` is for 10 Quatloos, and `paymentAmountA` is 3 Quatloos,
 it returns an array of two `payments` with balances of 3 Quatloos and 7 Quatloos.
 
-The original `payment` is burned. 
+The original `payment` is consumed and made unavailable for later use.
 
 If the original `payment` is a `promise` for a `payment`, the operation will 
 proceed after the `promise` resolves. Since you might also have a `promise` returned,
@@ -262,9 +262,10 @@ const [paymentA, paymentB] = quatloosIssuer.split(oldPayment, AmountMath.make(qu
 - `amountArray` `{Array <Amount>}`
 - Returns: `{Array <Payment>}`
 
-Split a single `payment` into multiple `payments`. The resulting array of `payments` is
+Split a single `payment` into multiple Payments. The resulting array of `payments` is
 as long as `amountArray`, and the `payments` will have `amounts` corresponding to 
-the `amountArray` contents. The original `payment` is burned. If the original `payment` 
+the `amountArray` contents. The original `payment` is consumed and made unavailable
+for later use. If the original `payment` 
 is a `promise`, the operation proceeds after the `promise` resolves.  If the `amounts` 
 in `amountArray` don't add up to the value of `payment`, the operation fails. The `brands`
 of the `amountArray` `amounts` must all be the same as the `payment` `brand`.
@@ -291,5 +292,5 @@ quatloosIssuer.splitMany(payment, badAmounts);
 - `payment` `{Payment}`
 - Returns: `{Boolean}`
 
-Returns `true` if the `payment` was created by the issuer and has not yet been destroyed.
+Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 If `payment` is a promise, the operation proceeds upon resolution.

From 45224c768dbc5aa1c0f6b196a0b79b7ef4f0c29a Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 18:02:40 -0400
Subject: [PATCH 04/12] chore: Use consistent language to describe promise
 handing in ERTP API documentation

---
 main/ertp/api/issuer.md | 24 ++++++++----------------
 1 file changed, 8 insertions(+), 16 deletions(-)

diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index a64e9d01a..3180827ce 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -157,8 +157,7 @@ and return an Amount of what was burned.
 the code insists the `payment` balance is equal to `optAmount`, to prevent sending the wrong `payment`
 and other confusion.  
 
-If `payment` is a `promise` for a `payment`, the operation proceeds after the
-`promise` resolves.
+If `payment` is a promise, the operation proceeds after it resolves to a Payment.
 
 ```js
 const { issuer: quatloosIssuer, mint: quatloosMint, brand: quatloosBrand } = 
@@ -184,9 +183,7 @@ equal to `optAmount`, to prevent sending the wrong `payment` and other confusion
 If `optAmount` does not equal the balance in the original `payment`
 then it throws an error.  
 
-If a `payment` is a `promise` for a `payment`, the operation will 
-proceed after the `promise` resolves. Since you might also have a `promise` returned,
-it might take a bit of time for the whole operation to resolve.
+If `payment` is a promise, the operation proceeds after it resolves to a Payment.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand } = makeIssuerKit('quatloos');
@@ -202,15 +199,12 @@ const newPayment = quatloosIssuer.claim(originalPayment, amountToTransfer);
 - Returns: `{Payment}`
 
 Combine multiple Payments into one new Payment. If any `payment` in `paymentsArray` is
-a `promise`, the operation proceeds after all the `payments`
-resolve. All Payments in `paymentsArray` are consumed and made unavailable for later use.
+a promise, the operation proceeds after each such promise resolves to a Payment.
+All Payments in `paymentsArray` are consumed and made unavailable for later use.
 
 If the optional `optTotalAmount` is present, the total of all the `payment` `amounts` in the
 array must equal `optTotalAmount` or it throws an error.
 
-If a `payment` is a `promise` for a `payment`, the operation will 
-proceed after the `promise` resolves. Since you might also have a `promise` returned,
-it might take a bit of time for the whole operation to resolve.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand } = makeIssuerKit('quatloos');
@@ -246,9 +240,7 @@ it returns an array of two `payments` with balances of 3 Quatloos and 7 Quatloos
 
 The original `payment` is consumed and made unavailable for later use.
 
-If the original `payment` is a `promise` for a `payment`, the operation will 
-proceed after the `promise` resolves. Since you might also have a `promise` returned,
-it might take a bit of time for the whole operation to resolve.
+If `payment` is a promise, the operation proceeds after it resolves to a Payment.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand } = makeIssuerKit('quatloos');
@@ -265,8 +257,8 @@ const [paymentA, paymentB] = quatloosIssuer.split(oldPayment, AmountMath.make(qu
 Split a single `payment` into multiple Payments. The resulting array of `payments` is
 as long as `amountArray`, and the `payments` will have `amounts` corresponding to 
 the `amountArray` contents. The original `payment` is consumed and made unavailable
-for later use. If the original `payment` 
-is a `promise`, the operation proceeds after the `promise` resolves.  If the `amounts` 
+for later use. If `payment`
+is a promise, the operation proceeds after it resolves to a Payment. If the `amounts`
 in `amountArray` don't add up to the value of `payment`, the operation fails. The `brands`
 of the `amountArray` `amounts` must all be the same as the `payment` `brand`.
 
@@ -293,4 +285,4 @@ quatloosIssuer.splitMany(payment, badAmounts);
 - Returns: `{Boolean}`
 
 Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
-If `payment` is a promise, the operation proceeds upon resolution.
+If `payment` is a promise, the operation proceeds after it resolves to a Payment.

From 6b8ed5764a61ba674923c271f264b51d5af8ca32 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 18:21:00 -0400
Subject: [PATCH 05/12] chore: Differentiate `payment` parameters from the
 Payment type in ERTP API documentation

---
 main/ertp/api/issuer.md | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index 3180827ce..df62f0df0 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -198,12 +198,12 @@ const newPayment = quatloosIssuer.claim(originalPayment, amountToTransfer);
 - `optTotalAmount` `{Amount}` - Optional.
 - Returns: `{Payment}`
 
-Combine multiple Payments into one new Payment. If any `payment` in `paymentsArray` is
+Combine multiple Payments into one new Payment. If any item in `paymentsArray` is
 a promise, the operation proceeds after each such promise resolves to a Payment.
 All Payments in `paymentsArray` are consumed and made unavailable for later use.
 
-If the optional `optTotalAmount` is present, the total of all the `payment` `amounts` in the
-array must equal `optTotalAmount` or it throws an error.
+If the optional `optTotalAmount` is present, the total value of all Payments in `paymentsArray`
+must equal `optTotalAmount` or it throws an error.
 
 
 ```js
@@ -218,7 +218,7 @@ for (let i = 0; i < 100; i += 1) {
 const combinedPayment = quatloosIssuer.combine(payments);
 ```
 
-**Note**: You **cannot** combine `payments` from different `mints` (as they are of different `brands`):
+**Note**: You **cannot** combine Payments from different `mints` (as they are of different `brands`):
 
 ```js
 const { mint: otherMint, issuer: otherIssuer, brand: otherBrand } = makeIssuerKit('other');
@@ -234,9 +234,9 @@ const badPayment = quatloosIssuer.combine(payments);
 - `paymentAmountA` `{Amount}`
 - Returns: `{Array <Payment>}`
 
-Split a single `payment` into two new `payments`, A and B, according to `paymentAmountA`.
+Split a single `payment` into two new Payments, A and B, according to `paymentAmountA`.
 For example, if the `payment` is for 10 Quatloos, and `paymentAmountA` is 3 Quatloos,
-it returns an array of two `payments` with balances of 3 Quatloos and 7 Quatloos.
+it returns an array of two Payments with respective balances of 3 Quatloos and 7 Quatloos.
 
 The original `payment` is consumed and made unavailable for later use.
 
@@ -254,13 +254,12 @@ const [paymentA, paymentB] = quatloosIssuer.split(oldPayment, AmountMath.make(qu
 - `amountArray` `{Array <Amount>}`
 - Returns: `{Array <Payment>}`
 
-Split a single `payment` into multiple Payments. The resulting array of `payments` is
-as long as `amountArray`, and the `payments` will have `amounts` corresponding to 
-the `amountArray` contents. The original `payment` is consumed and made unavailable
-for later use. If `payment`
-is a promise, the operation proceeds after it resolves to a Payment. If the `amounts`
-in `amountArray` don't add up to the value of `payment`, the operation fails. The `brands`
-of the `amountArray` `amounts` must all be the same as the `payment` `brand`.
+Split a single `payment` into multiple Payments.
+The returned array includes a Payment item corresponding to each Amount of `amounts`, in order.
+The original `payment` is consumed and made unavailable for later use.
+If `payment` is a promise, the operation proceeds after it resolves to a Payment.
+If the Amounts in `amountArray` don't add up to the value of `payment`, the operation fails.
+The `brands` of the `amountArray` `amounts` must all be the same as the `payment` `brand`.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand} = makeIssuerKit('quatloos');

From 21d824bb8f4c3ce28a6cc6d225790e028d0d3f92 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 18:23:17 -0400
Subject: [PATCH 06/12] chore: Clarify Brand matching requirements in ERTP API
 documentation

---
 main/ertp/api/issuer.md | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index df62f0df0..536dcc0b9 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -205,6 +205,7 @@ All Payments in `paymentsArray` are consumed and made unavailable for later use.
 If the optional `optTotalAmount` is present, the total value of all Payments in `paymentsArray`
 must equal `optTotalAmount` or it throws an error.
 
+Each Payment in `paymentsArray` must be associated with the same Brand as `issuer`.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand } = makeIssuerKit('quatloos');
@@ -218,17 +219,6 @@ for (let i = 0; i < 100; i += 1) {
 const combinedPayment = quatloosIssuer.combine(payments);
 ```
 
-**Note**: You **cannot** combine Payments from different `mints` (as they are of different `brands`):
-
-```js
-const { mint: otherMint, issuer: otherIssuer, brand: otherBrand } = makeIssuerKit('other');
-const otherPayment = otherMint.mintPayment(AmountMath.make(otherBrand, 10n));
-payments.push(otherPayment); // using the payments array from the above code
-
-// throws error
-const badPayment = quatloosIssuer.combine(payments);
-```
-
 ## `issuer.split(payment, paymentAmountA)`
 - `payment` `{Payment}`
 - `paymentAmountA` `{Amount}`
@@ -242,6 +232,8 @@ The original `payment` is consumed and made unavailable for later use.
 
 If `payment` is a promise, the operation proceeds after it resolves to a Payment.
 
+`payment` and `paymentAmountA` must both be associated with the same Brand as `issuer`.
+
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand } = makeIssuerKit('quatloos');
 const oldPayment = quatloosMint.mintPayment(AmountMath.make(quatloosBrand, 20n));
@@ -256,10 +248,13 @@ const [paymentA, paymentB] = quatloosIssuer.split(oldPayment, AmountMath.make(qu
 
 Split a single `payment` into multiple Payments.
 The returned array includes a Payment item corresponding to each Amount of `amounts`, in order.
+
 The original `payment` is consumed and made unavailable for later use.
+
 If `payment` is a promise, the operation proceeds after it resolves to a Payment.
+
 If the Amounts in `amountArray` don't add up to the value of `payment`, the operation fails.
-The `brands` of the `amountArray` `amounts` must all be the same as the `payment` `brand`.
+`payment` and each Amount in `amountArray` must be associated with the same Brand as `issuer`.
 
 ```js
 const { mint: quatloosMint, issuer: quatloosIssuer, brand: quatloosBrand} = makeIssuerKit('quatloos');

From 43dcab02f3befc45d63a4032736e6fe6745815f4 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 19:24:54 -0400
Subject: [PATCH 07/12] fix: Replace incorrect use of "burn" in payment API
 documentation

---
 main/ertp/api/payment.md | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/main/ertp/api/payment.md b/main/ertp/api/payment.md
index ddb817417..680e9c043 100644
--- a/main/ertp/api/payment.md
+++ b/main/ertp/api/payment.md
@@ -11,7 +11,8 @@ take out, say, 3 Quatloos from it, leaving the `payment` with 7 Quatloos.
 
 However, you can split a `payment` into multiple `payments`, for example 
 into two new `payments` of 3 Quatloos and 7 Quatloos.
-The `split()` operation *burns* (destroys) the original 10 Quatloos `payment`.
+The `split()` operation consumes the original 10 Quatloos `payment`,
+making it unavailable for later use.
 
 `Payments` are often received from other actors. Since they are not self-verifying,
 you cannot trust `payments`. To get the verified balance of a `payment`, use the `issuer` 
@@ -22,7 +23,8 @@ To convert a `payment` into a new `purse`:
 2. Use the `issuer` to create an empty `purse` for that `brand`.
 3. Deposit the `payment` into the new `purse`. 
 
-`purse.deposit(payment)` burns the `payment`.
+`purse.deposit(payment)` consumes the `payment`,
+making it unavailable for later use.
 
 ## `payment.getAllegedBrand()`
 - Returns: `{Brand}`
@@ -44,16 +46,16 @@ on or return a `payment`. While a brief description is given for each,
 you should click through to a method's main documentation entry for 
 full details on what it does and how to use it.
 
-- [`issuer.burn(payment, optAmount)`](./issuer.md#issuer-burn-payment-optamount) 
-  - Burn (destroy) all of the digital assets in the `payment`.
-- [`issuer.claim(payment, optAmount)`](./issuer.md#issuer-claim-payment-optamount) 
-  - Transfer all assets from the `payment` to a returned new `payment` and burn the original.
+- [`issuer.burn(payment, optAmount)`](./issuer.md#issuer-burn-payment-optamount)
+  - Destroy all of the digital assets in the `payment`.
+- [`issuer.claim(payment, optAmount)`](./issuer.md#issuer-claim-payment-optamount)
+  - Transfer all digital assets from `payment` to a new Payment.
 - [`issuer.combine(paymentsArray)`](./issuer.md#issuer-combine-paymentsarray-opttotalamount) 
   - Combine multiple `payments` into one, returned, `payment`.
 - [`issuer.getAmountOf(payment)`](./issuer.md#issuer-getamountof-payment) 
   - Get a description of a `payment` balance as an `amount`. 
-- [`issuer.isLive(payment)`](./issuer.md#issuer-islive-payment) 
-  - Returns `true` if the `issuer` says the `payment` exists (i.e. it's been created and hasn't been burned).
+- [`issuer.isLive(payment)`](./issuer.md#issuer-islive-payment)
+  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`issuer.split(payment, paymentAmountA)`](./issuer.md#issuer-split-payment-paymentamounta) 
   - Split one `payment` into two new ones.
 - [`issuer.splitMany(payment, amountArray)`](./issuer.md#issuer-splitmany-payment-amountarray) 

From 508de208bff7384a26e996787df536d8dc3886eb Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 19:40:16 -0400
Subject: [PATCH 08/12] chore: Better align ERTP API method references with
 their full descriptions

Purses and Payments
---
 main/ertp/api/issuer.md                |  6 +--
 main/ertp/api/payment.md               | 32 +++++++-------
 main/ertp/api/purse.md                 | 10 ++---
 main/ertp/guide/purses-and-payments.md | 60 ++++++--------------------
 4 files changed, 37 insertions(+), 71 deletions(-)

diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index 536dcc0b9..535884f82 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -110,9 +110,9 @@ moolaIssuer.getAssetKind(); // Returns 'set', also known as 'AssetKind.SET`
 - `payment` `{Payment}`
 - Returns: `{Amount}`
 
-Get the `payment`'s balance. Because the `payment` is not trusted, we cannot
-trust it to provide its true value, and must rely on the `issuer` to validate
-the `payment`'s `brand` and tell us how much it contains.
+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.
 
 ```js
 const { issuer: quatloosIssuer, mint: quatloosMint, brand: quatloosBrand} = makeIssuerKit('quatloos');
diff --git a/main/ertp/api/payment.md b/main/ertp/api/payment.md
index 680e9c043..d4339c883 100644
--- a/main/ertp/api/payment.md
+++ b/main/ertp/api/payment.md
@@ -42,7 +42,7 @@ const allegedBrand = payment.getAllegedBrand();
 ## Related Methods
 
 The following methods on other ERTP components either operate
-on or return a `payment`. While a brief description is given for each, 
+on or return a Payment. While a brief description is given for each,
 you should click through to a method's main documentation entry for 
 full details on what it does and how to use it.
 
@@ -50,21 +50,21 @@ full details on what it does and how to use it.
   - Destroy all of the digital assets in the `payment`.
 - [`issuer.claim(payment, optAmount)`](./issuer.md#issuer-claim-payment-optamount)
   - Transfer all digital assets from `payment` to a new Payment.
-- [`issuer.combine(paymentsArray)`](./issuer.md#issuer-combine-paymentsarray-opttotalamount) 
-  - Combine multiple `payments` into one, returned, `payment`.
-- [`issuer.getAmountOf(payment)`](./issuer.md#issuer-getamountof-payment) 
-  - Get a description of a `payment` balance as an `amount`. 
+- [`issuer.combine(paymentsArray)`](./issuer.md#issuer-combine-paymentsarray-opttotalamount)
+  - Combine multiple Payments into one new Payment.
+- [`issuer.getAmountOf(payment)`](./issuer.md#issuer-getamountof-payment)
+  - Describe the `payment`'s balance as an Amount.
 - [`issuer.isLive(payment)`](./issuer.md#issuer-islive-payment)
   - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
-- [`issuer.split(payment, paymentAmountA)`](./issuer.md#issuer-split-payment-paymentamounta) 
-  - Split one `payment` into two new ones.
-- [`issuer.splitMany(payment, amountArray)`](./issuer.md#issuer-splitmany-payment-amountarray) 
-  - Split `payment` into multiple `payments`, returned as an array.
-- [`mint.mintPayment(newAmount)`](./mint.md#mint-mintpayment-newamount) 
-  - Returns a new `payment` containing the newly minted assets corresponding to the `newAmount` argument. 
-- [`purse.deposit(payment, optAmount`)`](./purse.md#purse-deposit-payment-optamount) 
-  - Deposit all of `payment` into this `purse`.
+- [`issuer.split(payment, paymentAmountA)`](./issuer.md#issuer-split-payment-paymentamounta)
+  - Split a single `payment` into two new Payments.
+- [`issuer.splitMany(payment, amountArray)`](./issuer.md#issuer-splitmany-payment-amountarray)
+  - Split a single `payment` into multiple Payments.
+- [`mint.mintPayment(newAmount)`](./mint.md#mint-mintpayment-newamount)
+  - Create new digital assets of the `mint`'s associated `brand`.
+- [`purse.deposit(payment, optAmount)`](./purse.md#purse-deposit-payment-optamount)
+  - Deposit all the contents of `payment` into `purse`.
 - [`purse.getDepositFacet()`](./purse.md#purse-getdepositfacet)
-  - Creates a deposit-only facet on the `purse` that can be given to other parties to deposit `payments` in.
-- [`purse.withdraw(amount)`](./purse.md#purse-withdraw-amount) 
-  - Returns a new `payment` whose balance is described by the `amount` argument. 
+  - Create and return a new deposit-only facet of the `purse` that allows arbitrary other parties to deposit Payments into `purse`.
+- [`purse.withdraw(amount)`](./purse.md#purse-withdraw-amount)
+  - Withdraw the `amount` of specified digital assets from `purse` into a new `payment`.
diff --git a/main/ertp/api/purse.md b/main/ertp/api/purse.md
index fe607c50f..928f129c7 100644
--- a/main/ertp/api/purse.md
+++ b/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.
 
@@ -106,10 +106,10 @@ const depositAmountB = quatloosPurse.deposit(secondPayment, quatloos123);
 ```
 
 ## `purse.getDepositFacet()`
+- Returns: `{DepositFacet}`
 
-Returns a deposit-only facet on the `purse`. This is an object you can give to other parties
-that lets them deposit `payments` to your `purse` without being able to withdraw assets from or check
-the balance of the `purse`. This makes it a safe way to let other people send you `payments`.
+Create and return a new deposit-only facet of the `purse` that allows arbitrary other parties to deposit `payments` into `purse` without the ability to check its balance or withdraw from it.
+This makes it a safe way to let other people send you `payments`.
 
 You can only deposit a `payment` into a deposit facet that's the same `brand` as the original `purse`
 takes.
@@ -152,7 +152,7 @@ depositOnlyFacet.receive(payment);
 - `amount` `{Amount}`
 - Returns: `{Payment}`
 
-Withdraw the `amount` specified digital assets from this `purse` into a new `payment`.
+Withdraw the `amount` of specified digital assets from `purse` into a new `payment`.
 
 If the call succeeds, it immediately extracts the value into a new `payment`. 
 The caller won't get the new `payment` until a later turn, since the call is (nearly always) remote.
diff --git a/main/ertp/guide/purses-and-payments.md b/main/ertp/guide/purses-and-payments.md
index d8dfb2a93..fd15e6498 100644
--- a/main/ertp/guide/purses-and-payments.md
+++ b/main/ertp/guide/purses-and-payments.md
@@ -152,75 +152,41 @@ API Reference](/ertp/api/#ertp-api).
    the result when you use it. Any successful operation by 
    the `issuer` for that `brand` done on the `payment` verifies the `payment`.
 
-Other objects' `payment`-related methods:
+### Other objects' Payment-related methods:
 
 - [`issuer.getAmountOf(payment)`](../api/issuer.md#issuer-getamountof-payment)
-  - Get the amount of digital assets in the `payment` as an `amount`. 
-    The `payment` itself is not trusted, so you must use the `issuer` method associated
-    with its `brand` to be sure of getting the true value. 
+  - Describe the `payment`'s balance as an Amount.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
 - [`issuer.burn(payment, optAmount)`](../api/issuer.md#issuer-burn-payment-optamount)
-  - Burn all of the digital assets in the `payment`. `optAmount` is
-    optional but if present, the `payment` balance must be equal to
-    it. If `payment` is a promise, the operation proceeds after it resolves. 
+  - Destroy all of the digital assets in the `payment`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#burn
 - [`issuer.claim(payment, optAmount)`](../api/issuer.md#issuer-claim-payment-optamount)
-  - Transfer all assets from the `payment` to a returned new `payment`
-    and delete the original from the `issuer`'s records. Any references to the old
-    `payment` outside the `issuer` will still exist, but if anyone attempts to use the
-    old `payment`, an error is thrown.  
-    
-    If `optAmount` is
-    present, the `payment` balance must be equal to it or it throws
-    an error. If `payment` is a promise, the operation proceeds after it resolves. 
+  - Transfer all digital assets from `payment` to a new Payment.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#claim
 - [`issuer.combine(paymentsArray)`](../api/issuer.md#issuer-combine-paymentsarray-opttotalamount)
-  - Combine multiple `payments` into one, returned, `payment`. If any `payment` in
-  the array is a promise, the operation proceeds after every `payment`
-  resolves. All `payments` in the array are burned on successful completion.
+  - Combine multiple Payments into one new Payment.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#combine
 - [`issuer.split(payment, paymentAmountA)`](../api/issuer.md#issuer-split-payment-paymentamounta)
-  - Split one `payment` into two new ones, A and B, returned in
-    an array. `paymentAmountA` determines A's value, and whatever is
-    left of the original `payment` after subtracting A is B's value. 
-    If `paymentAmountA` has a larger `value` than `payment`, it throws an error.
-    
-    The `payment` argument is deleted from the issuer's records. If `payment` is
-    a promise, the operation proceeds after the promise for a payment resolves. 
+  - Split a single `payment` into two new Payments.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#split
 - [`issuer.splitMany(payment, amountArray)`](../api/issuer.md#issuer-splitmany-payment-amountarray)
-  - Split `payment` into multiple `payments`, returned as an array the
-    same length as `amountArray` and with its `payments` having the
-    same values as specified for `amountArray`'s elements. If `payment`
-    is a promise for a payment, the operation proceeds after it resolves. If
-    the `payment` value is not equal to the sum of `amountArray`'s
-    values, the operation fails. On success, the original `payment` is 
-    deleted from the issuer's records.
+  - Split a single `payment` into multiple Payments.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#splitManyConcise
 - [`issuer.isLive(payment)`](../api/issuer.md#issuer-islive-payment)
-  - Returns `true` if `payment` has value. If `payment` is a promise for payment,
-    the operation proceeds upon resolution.
+  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`mint.mintPayment(newAmount)`](/ertp/api/mint.md#mint-mintpayment-newamount)
-  - Returns a new `payment` containing the newly minted assets corresponding to the `newAmount` argument. Note
-    that unlike creating a new `payment` by withdrawing existing assets from a `purse`,
-    this creates new digital assets of the specified in `newAmount` `brand`.
+  - Create new digital assets of the `mint`'s associated `brand`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#mintMintPayment
 - [`purse.deposit(payment, optAmount)`](../api/purse.md#purse-deposit-payment-optamount)
-  - Deposit all of `payment` into this `purse`, returning the deposit
-    `amount` description. If optional `optAmount` does not equal the `payment`'s balance
-     or if `payment` is an unresolved promise, it throws an error.
+  - Deposit all the contents of `payment` into `purse`.
   - <<< @/snippets/ertp/guide/test-purses-and-payments.js#deposit
 - [`purse.withdraw(amount)`](../api/purse.md#purse-withdraw-amount)
-  - Withdraw the assets described by `amount` from this `purse` into a new
-    `payment`. Returns the new `payment`.
+  - Withdraw the `amount` of specified digital assets from `purse` into a new `payment`.
   - <<< @/snippets/ertp/guide/test-purses-and-payments.js#withdraw
 - [`purse.getDepositFacet()`](../api/purse.md#purse-getdepositfacet)
-  - Creates a deposit-only facet on the `purse` that can be given to
-    other parties that lets them deposit a `payment` (but not
-    withdraw) into the `purse`. Note that you add a payment via a
-    deposit facet by calling `depositFacet.receive(payment)` instead of
-    `deposit()`. 
+  - Create and return a new deposit-only facet of the `purse` that allows arbitrary other parties to deposit Payments into `purse`.
   - <<< @/snippets/ertp/guide/test-purses-and-payments.js#getDepositFacet
+
 ## `purse` and `payment` example
 
 The following code creates a new `purse` for the `quatloos` brand, deposits

From 120d282167a43d8070af396b663bd00e07a9f892 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 19:44:36 -0400
Subject: [PATCH 09/12] chore: Alphabetize Payment-related method references in
 Purses and Payments

Aligns with the same list in Payment API documentation
---
 main/ertp/guide/purses-and-payments.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/main/ertp/guide/purses-and-payments.md b/main/ertp/guide/purses-and-payments.md
index fd15e6498..87bd7fd49 100644
--- a/main/ertp/guide/purses-and-payments.md
+++ b/main/ertp/guide/purses-and-payments.md
@@ -154,9 +154,6 @@ API Reference](/ertp/api/#ertp-api).
 
 ### Other objects' Payment-related methods:
 
-- [`issuer.getAmountOf(payment)`](../api/issuer.md#issuer-getamountof-payment)
-  - Describe the `payment`'s balance as an Amount.
-  - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
 - [`issuer.burn(payment, optAmount)`](../api/issuer.md#issuer-burn-payment-optamount)
   - Destroy all of the digital assets in the `payment`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#burn
@@ -166,26 +163,29 @@ API Reference](/ertp/api/#ertp-api).
 - [`issuer.combine(paymentsArray)`](../api/issuer.md#issuer-combine-paymentsarray-opttotalamount)
   - Combine multiple Payments into one new Payment.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#combine
+- [`issuer.getAmountOf(payment)`](../api/issuer.md#issuer-getamountof-payment)
+  - Describe the `payment`'s balance as an Amount.
+  - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
+- [`issuer.isLive(payment)`](../api/issuer.md#issuer-islive-payment)
+  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`issuer.split(payment, paymentAmountA)`](../api/issuer.md#issuer-split-payment-paymentamounta)
   - Split a single `payment` into two new Payments.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#split
 - [`issuer.splitMany(payment, amountArray)`](../api/issuer.md#issuer-splitmany-payment-amountarray)
   - Split a single `payment` into multiple Payments.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#splitManyConcise
-- [`issuer.isLive(payment)`](../api/issuer.md#issuer-islive-payment)
-  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`mint.mintPayment(newAmount)`](/ertp/api/mint.md#mint-mintpayment-newamount)
   - Create new digital assets of the `mint`'s associated `brand`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#mintMintPayment
 - [`purse.deposit(payment, optAmount)`](../api/purse.md#purse-deposit-payment-optamount)
   - Deposit all the contents of `payment` into `purse`.
   - <<< @/snippets/ertp/guide/test-purses-and-payments.js#deposit
-- [`purse.withdraw(amount)`](../api/purse.md#purse-withdraw-amount)
-  - Withdraw the `amount` of specified digital assets from `purse` into a new `payment`.
-  - <<< @/snippets/ertp/guide/test-purses-and-payments.js#withdraw
 - [`purse.getDepositFacet()`](../api/purse.md#purse-getdepositfacet)
   - Create and return a new deposit-only facet of the `purse` that allows arbitrary other parties to deposit Payments into `purse`.
   - <<< @/snippets/ertp/guide/test-purses-and-payments.js#getDepositFacet
+- [`purse.withdraw(amount)`](../api/purse.md#purse-withdraw-amount)
+  - Withdraw the `amount` of specified digital assets from `purse` into a new `payment`.
+  - <<< @/snippets/ertp/guide/test-purses-and-payments.js#withdraw
 
 ## `purse` and `payment` example
 

From a8cbd7c4533da4aa5aef90a6086e059b3e5df1d9 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 22:55:59 -0400
Subject: [PATCH 10/12] chore: Better align ERTP API method references with
 their full descriptions

Issuers and Mints
---
 main/ertp/api/brand.md                 |  2 +-
 main/ertp/api/issuer.md                | 11 ++-
 main/ertp/api/mint.md                  |  2 +-
 main/ertp/api/payment.md               |  2 +-
 main/ertp/guide/issuers-and-mints.md   | 97 ++++++--------------------
 main/ertp/guide/purses-and-payments.md |  2 +-
 6 files changed, 30 insertions(+), 86 deletions(-)

diff --git a/main/ertp/api/brand.md b/main/ertp/api/brand.md
index 7475c06e3..7efda4d48 100644
--- a/main/ertp/api/brand.md
+++ b/main/ertp/api/brand.md
@@ -20,7 +20,7 @@ other `mint` or `issuer`.
 - `issuer` `{Issuer}`
 - Returns: `{Boolean}`
 
-Return `true` if `issuer` is this brand's `issuer`, `false` if not.
+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 
diff --git a/main/ertp/api/issuer.md b/main/ertp/api/issuer.md
index 535884f82..2249b7ebf 100644
--- a/main/ertp/api/issuer.md
+++ b/main/ertp/api/issuer.md
@@ -26,7 +26,7 @@ are ephemeral, so any object created there dies as soon as the script stops.
 - `issuer` `{Issuer}` 
 - `brand` `{Brand}`
 
-Makes a new `issuer` as well as its one-to-one associated ERTP objects; a `mint` and a `brand`. 
+Create and return a new `issuer` and its associated `mint` and `brand`.
 All are in unchangeable one-to-one relationships with each other. 
 
 The `allegedName` becomes part of the `brand` in asset descriptions. It
@@ -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`).
 
 An alleged name is a human-readable string name 
 of a kind of digital asset. An alleged name
@@ -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").
 
 The `assetKind` value specifies what kind of values are used in amounts for this issuer. 
 `AmountMath` works for all the different kinds of values. 
@@ -123,7 +122,7 @@ quatloosIssuer.getAmountOf(quatloosPayment); // returns an amount of 100 Quatloo
 ## `issuer.getBrand()`
 - Returns: `{Brand}` 
 
-Returns the `brand` for this `issuer`. The `brand` indicates the kind of digital asset
+Return the `brand` for the `issuer`. The `brand` indicates the kind of digital asset
 and is the same for the `issuer`'s associated `mint`, and any `purses` and `payments` of this particular
 kind. The `brand` is not closely held, so this function should not be trusted to identify
 an `issuer` alone. Fake digital assets and amounts can use another `issuer's` `brand`.
@@ -278,5 +277,5 @@ quatloosIssuer.splitMany(payment, badAmounts);
 - `payment` `{Payment}`
 - Returns: `{Boolean}`
 
-Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
+Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 If `payment` is a promise, the operation proceeds after it resolves to a Payment.
diff --git a/main/ertp/api/mint.md b/main/ertp/api/mint.md
index e301fd217..f7aaf7484 100644
--- a/main/ertp/api/mint.md
+++ b/main/ertp/api/mint.md
@@ -19,7 +19,7 @@ See [here](/ertp/api/issuer.md#makeissuerkit-allegedname-assetkind-displayinfo)
 ## `mint.getIssuer()`
 - Returns: `{Issuer}`
 
-Get the `Issuer` associated with this `mint`. From their creation, a `mint` is always
+Return the `issuer` uniquely associated with the `mint`. From their creation, a `mint` is always
 in an unchangeable one-to-one relationship with an `issuer`. 
 
 ```js
diff --git a/main/ertp/api/payment.md b/main/ertp/api/payment.md
index d4339c883..887a4bd54 100644
--- a/main/ertp/api/payment.md
+++ b/main/ertp/api/payment.md
@@ -55,7 +55,7 @@ full details on what it does and how to use it.
 - [`issuer.getAmountOf(payment)`](./issuer.md#issuer-getamountof-payment)
   - Describe the `payment`'s balance as an Amount.
 - [`issuer.isLive(payment)`](./issuer.md#issuer-islive-payment)
-  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
+  - Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`issuer.split(payment, paymentAmountA)`](./issuer.md#issuer-split-payment-paymentamounta)
   - Split a single `payment` into two new Payments.
 - [`issuer.splitMany(payment, amountArray)`](./issuer.md#issuer-splitmany-payment-amountarray)
diff --git a/main/ertp/guide/issuers-and-mints.md b/main/ertp/guide/issuers-and-mints.md
index 01a8e11eb..5a4b09005 100644
--- a/main/ertp/guide/issuers-and-mints.md
+++ b/main/ertp/guide/issuers-and-mints.md
@@ -38,94 +38,45 @@ API Reference](/ertp/api/#ertp-api).
 
 - **Create issuer operation**
   - [`makeIssuerKit(allegedName, assetKind, displayInfo=)`](/ertp/api/issuer.md#makeissuerkit-allegedname-assetkind-displayinfo)
-  - Makes an `issuer` and its related `mint` and `brand`.
-    Returns ` { mint, issuer, brand }` The `mint` and
-    `brand` are in unchangeable one-to-one relationships with the `issuer`
-    and each other. 
-    
-    The `allegedName` is available from the `brand` to describe assets, but should not
-    be trusted. 
-    
-    `assetKind` specifies if the associated asset is of kind `AssetKind.NAT` (`nat`) 
-    (the default value) or `AssetKind.SET` (`set`);
-    see the [`AmountMath` page](./amount-math.md) for details. 
-    
-    `displayInfo` is the number of places to the right of the decimal point to display of any
-    `values` associated with the created `brand`. It defaults to `undefined`
-    
+    - Create and return a new `issuer` and its associated `mint` and `brand`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#import
       <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeIssuerKit
 - **Get information about the issuer operations**
   - [`issuer.getBrand()`](/ertp/api/issuer.md#issuer-getbrand)
-    - Returns the `brand` the `issuer` is in a one-to-one relationship with. The `brand` is not closely
-      held, so it can be used by fake digital assets and `amounts`. Do
-      not trust this method alone to ensure the `issuer` has the right `brand`.
+    - Return the `brand` for the `issuer`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getBrand
   - [`issuer.getAllegedName()`](/ertp/api/issuer.md#issuer-getallegedname)
-    - Returns the `issuer`/`mint`'s
-      [`allegedName`](/glossary/#allegedname),
-	the non-trusted human-readable name of the `issuer`'s associated `brand`.
+    - Return the `allegedName` for the `issuer` (the non-trusted human-readable name of its associated `brand`).
     - <<< @/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").
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAssetKind
 - **Purse operation**
   - [`issuer.makeEmptyPurse()`](/ertp/api/issuer.md#issuer-makeemptypurse)
-    - 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`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeEmptyPurse
 - **Payment operations**
   - [`issuer.getAmountOf(payment)`](/ertp/api/issuer.md#issuer-getamountof-payment)
-    -  Returns the `payment` balance, an `amount`. Using the `issuer` rather than the `payment` lets us trust
-      the result even if someone we do not trust sent us the `payment`.
+    - Describe the `payment`'s balance as an Amount.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
   - [`issuer.burn(payment, optAmount)`](/ertp/api/issuer.md#issuer-burn-payment-optamount)
-    - Burns (destroys) all of the `payment` argument's digital assets and deletes all mention of the `payment` from the `issuer`.
-       If optional argument `optAmount` is present, the `payment`
-       balance must be equal to `optAmount`'s value.  If `payment` is a promise, the operation 
-       happens after the promise resolves. Returns the value of the burned `payment`.
+    - Destroy all of the digital assets in the `payment`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#burn
   - [`issuer.claim(payment, optAmount)`](/ertp/api/issuer.md#issuer-claim-payment-optamount)
-    - Transfer all digital assets from the `payment` argument to a new `payment` and
-      burn the original so no other references to this `payment` survive. Returns the new `payment`
-      If optional argument `optAmount` is present, the `payment` balance
-      must be equal to `optAmount`'s balance, otherwise it throws an error. If `payment`
-      is a promise for a payment, the operation happens after the promise resolves.
+    - Transfer all digital assets from `payment` to a new Payment.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#claim
   - [`issuer.combine(paymentsArray)`](/ertp/api/issuer.md#issuer-combine-paymentsarray-opttotalamount)
-    - Combine multiple `payments` into one `payment`. If any `payment`
-      in `paymentsArray` is a promise for a payment, the operation happens after all
-      promises resolve. Every `payment` is burned except for the
-      returned one. If you try to combine `payments` of different `brands`,
-      it throws an exception and each `payment` is unaffected.
+    - Combine multiple Payments into one new Payment.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#combine
 
   - [`issuer.split(payment, paymentAmountA)`](/ertp/api/issuer.md#issuer-split-payment-paymentamounta)
-    - Split a single `payment` into two new `payments`, A and B, according
-      to the `paymentAmountA` argument's value. In other words, the result
-      has A equal to `paymentAmountA` and B equal to the original `payment`
-      minus `paymentAmountA`. 
-      The original `payment` argument is burned. If the original
-      `payment` is a promise, the operation happens when the promise
-      resolves. 
+    - Split a single `payment` into two new Payments.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#split
-   - [`issuer.splitMany(payment, paymentAmountArray)`](/ertp/api/issuer.md#issuer-splitmany-payment-amountarray)
-     - Returns multiple `payments` in an array from splitting its single
-       `payment` argument. The resulting number of `payments` is
-       specified as the length of the `paymentAmountArray` argument,
-       with the newly split `payments` having `amounts` corresponding
-       to those in `paymentAmountArray`. If the `paymentAmountArray`
-       argument `amounts` don't add up to the `value` of the `payment`
-       argument, the operation fails. If the operation is successful,
-       the original `payment` is burned. If the operation fails, the
-       original `payment` is *not* burned.
-     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#splitMany
+  - [`issuer.splitMany(payment, paymentAmountArray)`](/ertp/api/issuer.md#issuer-splitmany-payment-amountarray)
+    - Split a single `payment` into multiple Payments.
+    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#splitMany
   - [`issuer.isLive(payment)`](/ertp/api/issuer.md#issuer-islive-payment)
-    - Returns `true` if the `payment` argument is still active
-      (i.e. has not been used or burned and was issued by this `issuer`). If `payment` is a promise,
-      the operation happens on its resolution.
+    - Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#isLive
 
 
@@ -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.
 
-- [`mint.getIssuer()`](/ertp/api/mint.md#mint-getissuer) 
-  - Return the associated `issuer` for the `mint`.
+- [`mint.getIssuer()`](/ertp/api/mint.md#mint-getissuer)
+  - Return the `issuer` uniquely associated with the `mint`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#mintGetIssuer
-- [`brand.isMyIssuer(issuer)`](/ertp/api/brand.md#brand-ismyissuer-issuer) 
-  - Returns `true` if the `brand` comes from this `issuer`.
+- [`brand.isMyIssuer(issuer)`](/ertp/api/brand.md#brand-ismyissuer-issuer)
+  - Return `true` if `issuer` is the brand's `issuer`, `false` if not.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#isMyIssuer
 
 ## Mints
@@ -166,18 +117,12 @@ So a Quatloos `mint` can never become a Moola `mint`, or any other non-Quatloos
 There are two `mint` methods, and the method that creates new mints. Click the method's name to go to its entry in the [ERTP
 API Reference](/ertp/api/#ertp-api).
 - [`mint.getIssuer()`](/ertp/api/mint.md#mint-getissuer)
-  - Returns the `issuer` uniquely associated with the `mint`.
+  - Return the `issuer` uniquely associated with the `mint`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#mintGetIssuer
 - [`mint.mintPayment(newAmount)`](/ertp/api/mint.md#mint-mintpayment-newamount)
-  - Returns a new `payment` containing newly minted assets with a balance equal to `newAmount`. In other words,
-    it mints `newAmount` of digital assets and creates a `payment` to hold those new assets. The assets are of
-    the `mint`'s associated `brand`.
-    
-    **Important**: `mint.mintPayment()` is the only way in ERTP to create new digital assets. There is no other way.
-    The Zoe Contract Facet (`zcf`) can also create a mint in Zoe that can create new digital assets.
+  - Create new digital assets of the `mint`'s associated `brand`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#mintMintPayment
 - [`makeIssuerKit(allegedName, assetKind, displayInfo)`](/ertp/api/issuer.md#makeissuerkit-allegedname-assetkind-displayinfo)
-  - While not a method called on a `mint`, clearly you should know how to create a new `mint`. `makeIssuerKit()` returns
-    a new `issuer`, `mint`, and `brand`. 
+  - Create and return a new `issuer` and its associated `mint` and `brand`.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeIssuerKitMint
 
diff --git a/main/ertp/guide/purses-and-payments.md b/main/ertp/guide/purses-and-payments.md
index 87bd7fd49..a32e51373 100644
--- a/main/ertp/guide/purses-and-payments.md
+++ b/main/ertp/guide/purses-and-payments.md
@@ -167,7 +167,7 @@ API Reference](/ertp/api/#ertp-api).
   - Describe the `payment`'s balance as an Amount.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
 - [`issuer.isLive(payment)`](../api/issuer.md#issuer-islive-payment)
-  - Returns `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
+  - Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
 - [`issuer.split(payment, paymentAmountA)`](../api/issuer.md#issuer-split-payment-paymentamounta)
   - Split a single `payment` into two new Payments.
   - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#split

From bef00a6e41b93be8e2b8e8b58123abcddfdcaf67 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Fri, 1 Apr 2022 22:59:57 -0400
Subject: [PATCH 11/12] chore: Alphabetize Payment-related method references in
 Issuers and Mints

---
 main/ertp/guide/issuers-and-mints.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/main/ertp/guide/issuers-and-mints.md b/main/ertp/guide/issuers-and-mints.md
index 5a4b09005..f54495d84 100644
--- a/main/ertp/guide/issuers-and-mints.md
+++ b/main/ertp/guide/issuers-and-mints.md
@@ -42,23 +42,20 @@ API Reference](/ertp/api/#ertp-api).
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#import
       <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeIssuerKit
 - **Get information about the issuer operations**
-  - [`issuer.getBrand()`](/ertp/api/issuer.md#issuer-getbrand)
-    - Return the `brand` for the `issuer`.
-    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getBrand
   - [`issuer.getAllegedName()`](/ertp/api/issuer.md#issuer-getallegedname)
     - Return the `allegedName` for the `issuer` (the non-trusted human-readable name of its associated `brand`).
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAllegedName
   - [`issuer.getAssetKind()`](/ertp/api/issuer.md#issuer-getassetkind)
     - Return the kind of the `issuer`'s asset; either `AssetKind.NAT` ("nat") or `AssetKind.SET` ("set").
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAssetKind
+  - [`issuer.getBrand()`](/ertp/api/issuer.md#issuer-getbrand)
+    - Return the `brand` for the `issuer`.
+    - <<< @/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`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#makeEmptyPurse
 - **Payment operations**
-  - [`issuer.getAmountOf(payment)`](/ertp/api/issuer.md#issuer-getamountof-payment)
-    - Describe the `payment`'s balance as an Amount.
-    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
   - [`issuer.burn(payment, optAmount)`](/ertp/api/issuer.md#issuer-burn-payment-optamount)
     - Destroy all of the digital assets in the `payment`.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#burn
@@ -69,15 +66,18 @@ API Reference](/ertp/api/#ertp-api).
     - Combine multiple Payments into one new Payment.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#combine
 
+  - [`issuer.getAmountOf(payment)`](/ertp/api/issuer.md#issuer-getamountof-payment)
+    - Describe the `payment`'s balance as an Amount.
+    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#getAmountOf
+  - [`issuer.isLive(payment)`](/ertp/api/issuer.md#issuer-islive-payment)
+    - Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
+    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#isLive
   - [`issuer.split(payment, paymentAmountA)`](/ertp/api/issuer.md#issuer-split-payment-paymentamounta)
     - Split a single `payment` into two new Payments.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#split
   - [`issuer.splitMany(payment, paymentAmountArray)`](/ertp/api/issuer.md#issuer-splitmany-payment-amountarray)
     - Split a single `payment` into multiple Payments.
     - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#splitMany
-  - [`issuer.isLive(payment)`](/ertp/api/issuer.md#issuer-islive-payment)
-    - Return `true` if the `payment` was created by the issuer and is available for use (has not been consumed or burned).
-    - <<< @/snippets/ertp/guide/test-issuers-and-mints.js#isLive
 
 
 **Related Methods:**

From 2b6b500956f7df2f83f655fdb8b64c22deed85e3 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Mon, 11 Apr 2022 14:30:33 -0400
Subject: [PATCH 12/12] 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`.