diff --git a/main/glossary/README.md b/main/glossary/README.md index 5808289c0..34ed95bee 100644 --- a/main/glossary/README.md +++ b/main/glossary/README.md @@ -39,7 +39,7 @@ by [issuers](#issuer) and [mints](#mint), and represent the goods and currency c [purses](#purse) and [payments](#payment). They represent things like currency, stock, and the abstract right to participate in a particular exchange. -An amount is comprised of a [brand](#brand) with a [value](#value). For example, "4 Quatloos" +An amount is comprised of a [brand](#brand) with a [value](#amountvalue). For example, "4 Quatloos" is an amount with a value of "4" and a brand of the imaginary currency "Quatloos". **Important**: Amounts are *descriptions* of digital assets, not the actual assets. They have no @@ -71,7 +71,7 @@ five tickets is performed by set union rather than by arithmetic. - `AssetKind.COPY_SET`: Used with [non-fungible](#non-fungible) assets. Each amount value is a set of [Key](#key) values (strings, numbers, objects, etc.). - Values cannot include promises (they aren't keys), and should not + Amount values cannot include promises (they aren't keys), and should not include privileged objects such as payments and purses. - `AssetKind.COPY_BAG`: Used with [semi-fungible](#semi-fungible) assets. Each amount value is a [multiset](https://en.wikipedia.org/wiki/Multiset) @@ -81,9 +81,16 @@ five tickets is performed by set union rather than by arithmetic. For more information, see the [ERTP documentation's AmountMath section](/guides/ertp/amount-math.md) and the [ERTP API's AmountMath section](/reference/ertp-api/amount-math.md). + +## AmountValue +An AmountValue is the part of an [Amount](#amount) that describes the value of something +that can be owned or shared: how much, how many, or a description of a unique asset, such as +$3, Pixel(3,2), or “Seat J12 for the show September 27th at 9:00pm”. +For a [fungible](#fungible) Amount, the AmountValue is usually a non-negative **BigInt** such as `10n` or `137n`. +For a [non-fungible](#non-fungible) Amount, the AmountValue might be a [CopySet](/guides/js-programming/far.md#pass-styles-and-harden) containing strings naming particular rights or objects representing the rights directly. - +For more information, see the [ERTP documentation's AmountValue section](/guides/ertp/amounts.md#amountvalues). ## AssetHolder @@ -350,7 +357,7 @@ If either side of the comparison contains promises and/or errors, equality is in If both are fulfilled down to [presences](#presence) and local state, then either they're the same all the way down, or they represent different objects. -Keys can be used as elements of CopySets and CopyBags and as keys of CopyMaps (see [AmountMath](#amountmath)). [Values](#value) must be Keys. +Keys can be used as elements of CopySets and CopyBags and as keys of CopyMaps (see [AmountMath](#amountmath)). [AmountValues](#amountvalue) must be Keys. ## Keyword @@ -556,16 +563,6 @@ they provide terms applicable only to that instance. For some instances of the auction, they want the minimum bid set at $1000. At other instances, they'd like it set at $10. They can specify the instance's minimum bid amount in its terms. -## Value - -A value is the part of an [Amount](#amount) that describes the value of something -that can be owned or shared: how much, how many, or a description of a unique asset, such as -$3, Pixel(3,2), or “Seat J12 for the show September 27th at 9:00pm”. -For a [fungible](#fungible) Amount, the Value is usually a non-negative **BigInt** such as `10n` or `137n`. -For a [non-fungible](#non-fungible) Amount, the Value might be a [CopySet](/guides/js-programming/far.md#pass-styles-and-harden) containing strings naming particular rights or objects representing the rights directly. - -For more information, see the [ERTP documentation's Value section](/guides/ertp/amounts.md#values). - ## Vat A vat is a unit of isolation. diff --git a/main/guides/ertp/README.md b/main/guides/ertp/README.md index cb2b3a7eb..ec28bf280 100644 --- a/main/guides/ertp/README.md +++ b/main/guides/ertp/README.md @@ -41,7 +41,7 @@ and Balcony sections, where a holder may sit in any seat of the respective secti Assets are described by **[Amount](./amounts.md)** records consisting of a `brand` and a `value`. - **[Brand](./amounts.md#brands)**: An asset's type. You can think of this as the answer to the question "What is it?" about an asset. -- **[Value](./amounts.md#values)**: An asset's size. +- **[AmountValue](./amounts.md#amountvalues)**: An asset's size. You can think of this as the answer to the questions "how many?" or "how much?" about an asset. **Important**: Amounts are *descriptions* of digital assets, not the actual assets. They have no diff --git a/main/guides/ertp/amounts.md b/main/guides/ertp/amounts.md index 9a187d33b..07e9fd2eb 100644 --- a/main/guides/ertp/amounts.md +++ b/main/guides/ertp/amounts.md @@ -84,11 +84,12 @@ return a `brand`. that it's genuine. - <<< @/snippets/ertp/guide/test-amounts.js#depositSomewhere -## Values + +## AmountValues ![Value methods](./assets/value.svg) -Values are the "how many" part of an `amount`. +AmountValues are the "how many" part of an `amount`. Note that number values (for fungible assets) are represented as `BigInt`s and not `Number`s. Write `10n` rather than `10`. diff --git a/main/reference/ertp-api/README.md b/main/reference/ertp-api/README.md index 6e9eafdbd..5ac6fcc2e 100644 --- a/main/reference/ertp-api/README.md +++ b/main/reference/ertp-api/README.md @@ -25,7 +25,7 @@ The ERTP API introduces and uses the following data types: | --- | --- | | [Amount](./ertp-data-types.md#amount) | Describes digital assets, specifying the number and **[Brand](./brand.md)** of assets. Note that **Amounts** can describe either fungible or non-fungible assets. | | [AmountShape](./ertp-data-types.md#amountshape) | Describes digital assets, specifying the properties and **[Brand](./brand.md)** of assets. | -| [Value](./ertp-data-types.md#value) | Describes how much of something there is. | +| [AmountValue](./ertp-data-types.md#amountvalue) | Describes how much of something there is. | | [AssetKind](./ertp-data-types.md#assetkind) | Specifies whether an **Amount** is fungible or non-fungible. | | [DisplayInfo](./ertp-data-types.md#displayinfo) | Specifies how to display a **Brand**'s **Amounts**. | diff --git a/main/reference/ertp-api/amount-math.md b/main/reference/ertp-api/amount-math.md index 1815ec62f..b14b8b0fb 100644 --- a/main/reference/ertp-api/amount-math.md +++ b/main/reference/ertp-api/amount-math.md @@ -19,10 +19,10 @@ not equal, an error is thrown and no changes are made. ## AmountMath.make(brand, allegedValue) - **brand**: **[Brand](./brand.md)** -- **allegedValue**: **[Value](./ertp-data-types.md#value)** +- **allegedValue**: **[AmountValue](./ertp-data-types.md#amountvalue)** - Returns: **[Amount](./ertp-data-types.md#amount)** -Creates an **Amount** from a given **Value** and a **Brand**. +Creates an **Amount** from a given **Brand** and **AmountValue**. ```js // amount837 = { brand: quatloosBrand, value: 837n } @@ -46,9 +46,9 @@ const verifiedAmount = AmountMath.coerce(quatloosBrand, allegedAmount); ## AmountMath.getValue(brand, amount) - **brand**: **[Brand](./brand.md)** - **amount**: **[Amount](./ertp-data-types.md#amount)** -- Returns: **[Value](./ertp-data-types.md#amount)** +- Returns: **[AmountValue](./ertp-data-types.md#amountvalue)** -Returns the **Value** from the given **Amount**. +Returns the **AmountValue** from the given **Amount**. ```js const quatloos123 = AmountMath.make(quatloosBrand, 123n); @@ -63,7 +63,7 @@ const myValue = AmountMath.getValue(quatloosBrand, quatloos123); Returns the **Amount** representing an empty **Amount** for the *brand* parameter's **Brand**. This is the identity element for **AmountMath.add()** -and **AmountMath.subtract()**. The empty **Value** depends +and **AmountMath.subtract()**. The empty **AmountValue** depends on whether the *assetKind* is **AssetKind.NAT** (`0n`), **AssetKind.COPY_SET** (`[]`), or **AssetKind.COPY_BAG** (`[]`). ```js @@ -78,7 +78,7 @@ const empty = AmountMath.makeEmpty(quatloosBrand, AssetKind.NAT); - Returns: **Amount** Returns the **Amount** representing an empty **Amount**, using another -**Amount** as the template for the **[Brand](./brand.md)** and **[Value](./ertp-data-types.md#value)**. +**Amount** as the template for the **[Brand](./brand.md)** and **[AmountValue](./ertp-data-types.md#amountvalue)**. ```js // quatloosAmount837 = { brand: quatloos, value: 837n } @@ -113,13 +113,13 @@ const result = AmountMath.isEmpty(quatloos1); - **brand**: **[Brand](./brand.md)** - Optional, defaults to **undefined**. - Returns: **Boolean** -Returns **true** if the **[Value](./ertp-data-types.md#value)** of *leftAmount* is greater than or equal to -the **Value** of *rightAmount*. Both **Amount** arguments must have the same +Returns **true** if the **[AmountValue](./ertp-data-types.md#amountvalue)** of *leftAmount* is greater than or equal to +the **AmountValue** of *rightAmount*. Both **Amount** arguments must have the same **Brand**. If the optional *brand* argument doesn't match the **Amount**s' **Brand**, an error is thrown. -For non-fungible **Values**, what "greater than or equal to" is depends on the +For non-fungible **AmountValues**, what "greater than or equal to" is depends on the kind of **AmountMath**. For example, { 'seat 1', 'seat 2' } is considered greater than { 'seat 2' } because the former both contains all of the latter's content and has additional elements. @@ -147,13 +147,13 @@ AmountMath.isGTE(quatloos5, quatloos5); - **brand**: **[Brand](./brand.md)** - Optional, defaults to **undefined**. - Returns: **Boolean** -Returns **true** if the **[Value](./ertp-data-types.md#value)** of *leftAmount* is equal to -the **Value** of *rightAmount*. Both **Amount** arguments must have the same +Returns **true** if the **[AmountValue](./ertp-data-types.md#amountvalue)** of *leftAmount* is equal to +the **AmountValue** of *rightAmount*. Both **Amount** arguments must have the same **Brand**. If the optional *brand* argument doesn't match the **Amount**s' **Brand**, an error is thrown. -For non-fungible **Values**, "equal to" depends on the value of the +For non-fungible **AmountValues**, "equal to" depends on the value of the **Brand's** **[AssetKind](./ertp-data-types.md#assetkind)**. For example, { 'seat 1', 'seat 2' } is considered @@ -188,7 +188,7 @@ arguments must be of the same **Brand**. If the optional *brand* argument doesn't match the **Amount**s' **Brand**, an error is thrown. -For fungible **Amounts** this means adding their **[Values](./ertp-data-types.md#value)**. For non-fungible +For fungible **Amounts** this means adding their **[AmountValues](./ertp-data-types.md#amountvalue)**. For non-fungible **Amounts**, it usually means including all of the elements from *leftAmount* and *rightAmount*. diff --git a/main/reference/ertp-api/ertp-data-types.md b/main/reference/ertp-api/ertp-data-types.md index edca2b55e..ec39da884 100644 --- a/main/reference/ertp-api/ertp-data-types.md +++ b/main/reference/ertp-api/ertp-data-types.md @@ -5,7 +5,7 @@ ERTP introduces and uses several data types. ## Amount An **Amount** is a description of digital assets, answering the -questions "how much?" and "of what kind?". It is a **[Value](#value)** ("how much?") +questions "how much?" and "of what kind?". It is an **[AmountValue](#amountvalue)** ("how much?") labeled with a **[Brand](./brand.md)** ("of what kind?"). The **[AmountMath](./amount-math.md)** object introduces a library of methods that can be used to manipulate and analyze **Amounts**. @@ -34,23 +34,24 @@ someAmountShape: { } ``` -## Value + +## AmountValue -A **Value** is the part of an [Amount](#amount) that describes the value of something +An **AmountValue** is the part of an [Amount](#amount) that describes the value of something that can be owned or shared: how much, how many, or a description of a unique asset, such as $3, Pixel(3,2), or “Seat J12 for the show September 27th at 9:00pm”. -For a fungible **Amount**, the **Value** is usually a non-negative **BigInt** such as `10n` or `137n`. -For a non-fungible **Amount**, the **Value** might be a [CopySet](/guides/js-programming/far.md#pass-styles-and-harden) containing strings naming particular rights or objects representing the rights directly. -Values must be [Keys](/glossary/#key). +For a fungible **Amount**, the **AmountValue** is usually a non-negative **BigInt** such as `10n` or `137n`. +For a non-fungible **Amount**, the **AmountValue** might be a [CopySet](/guides/js-programming/far.md#pass-styles-and-harden) containing strings naming particular rights or objects representing the rights directly. +AmountValues must be [Keys](/glossary/#key). ## AssetKind There are several kinds of Assets. -- **AssetKind.NAT** : Used with fungible assets. **Values** are natural numbers using the JavaScript [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) type to avoid overflow risks from using the usual JavaScript **Number** type. +- **AssetKind.NAT** : Used with fungible assets. **AmountValues** are natural numbers using the JavaScript [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) type to avoid overflow risks from using the usual JavaScript **Number** type. - **AssetKind.SET** : Deprecated. -- **AssetKind.COPY_SET** : Used with non-fungible assets where there can't be duplicates (e.g., assigned seats in a stadium). **Values** are arrays of objects. -- **AssetKind.COPY_BAG** : Used with non-fungible assets where there can be duplicates. (e.g., weapons in a computer game). **Values** are arrays of objects. +- **AssetKind.COPY_SET** : Used with non-fungible assets where there can't be duplicates (e.g., assigned seats in a stadium). **AmountValues** are arrays of objects. +- **AssetKind.COPY_BAG** : Used with non-fungible assets where there can be duplicates. (e.g., weapons in a computer game). **AmountValues** are arrays of objects. Even though very different mathematical processes are performed, **[AmountMath](./amount-math.md)** methods work for all kinds of assets. diff --git a/main/reference/ertp-api/purse.md b/main/reference/ertp-api/purse.md index d15fe0301..706b4bb71 100644 --- a/main/reference/ertp-api/purse.md +++ b/main/reference/ertp-api/purse.md @@ -36,7 +36,7 @@ send the **Payment** to another party. - Returns: **[Amount](./ertp-data-types.md#amount)** Returns the **Purse**'s current balance as an **Amount**. -The returned **Amount** **[Value](./ertp-data-types.md#value)** might be empty, and might be different the next time you +The returned **Amount** **[AmountValue](./ertp-data-types.md#amountvalue)** might be empty, and might be different the next time you call **aPurse.getCurrentAmount()** on the same **Purse** if assets have been deposited or withdrawn in the interim. diff --git a/main/reference/zoe-api/ratio-math.md b/main/reference/zoe-api/ratio-math.md index 852f909a6..fdcbdbe9f 100644 --- a/main/reference/zoe-api/ratio-math.md +++ b/main/reference/zoe-api/ratio-math.md @@ -342,8 +342,8 @@ aren't identical. Returns **true** if the *left* and *right* **Ratios** are the same, **false** otherwise. Note that for the two **Ratios** to be considered the same, the -**[Value](/reference/ertp-api/ertp-data-types.md#value)** and **[Brand](/reference/ertp-api/brand.md)** -of both the *numerator* and *denominator* of one **Ratio** must be identical to the **Value** and +**[AmountValue](/reference/ertp-api/ertp-data-types.md#amountvalue)** and **[Brand](/reference/ertp-api/brand.md)** +of both the *numerator* and *denominator* of one **Ratio** must be identical to the **AmountValue** and **Brand** of the *numerator* and *denominator* of the other **Ratio**. diff --git a/main/reference/zoe-api/zoe-data-types.md b/main/reference/zoe-api/zoe-data-types.md index 46159fad4..b3e8a0ddc 100644 --- a/main/reference/zoe-api/zoe-data-types.md +++ b/main/reference/zoe-api/zoe-data-types.md @@ -127,7 +127,7 @@ const { quoteAmount, quotePayment } = priceQuote; **Ratios** are pass-by-value records that consist of a *numerator* and a *denominator*. Both of these consist of a -**[Value](/reference/ertp-api/ertp-data-types.md#value)** and a **[Brand](/reference/ertp-api/brand.md)**, +**[AmountValue](/reference/ertp-api/ertp-data-types.md#amountvalue)** and a **[Brand](/reference/ertp-api/brand.md)**, just like **[Amounts](/reference/ertp-api/ertp-data-types.md#amount)**. A **Ratio** cannot have a denominator value of 0.