Skip to content

Commit

Permalink
chore: adopt prettier-plugin-jsdoc (ERTP)
Browse files Browse the repository at this point in the history
  • Loading branch information
@turadg
turadg committed Jul 19, 2023
1 parent 4f47224 commit fc69584
Show file tree
Hide file tree
Showing 10 changed files with 423 additions and 522 deletions.
1 change: 1 addition & 0 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
"overrides": [
{
"files": [
"packages/ERTP/**/*.{js,ts}",
"packages/inter-protocol/**/*.{js,ts}",
"packages/vats/**/*.{js,ts}"
],
Expand Down
120 changes: 57 additions & 63 deletions packages/ERTP/src/amountMath.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,12 @@ const { quote: q, Fail } = assert;
/**
* Constants for the kinds of assets we support.
*
* @type {{ NAT: 'nat', SET: 'set', COPY_SET: 'copySet', COPY_BAG: 'copyBag' }}
* @type {{
* NAT: 'nat';
* SET: 'set';
* COPY_SET: 'copySet';
* COPY_BAG: 'copyBag';
* }}
*/
const AssetKind = harden({
NAT: 'nat',
Expand All @@ -21,52 +26,45 @@ const AssetKind = harden({
});
const assetKindNames = harden(Object.values(AssetKind).sort());

/**
* @param {AssetKind} allegedAK
*/
/** @param {AssetKind} allegedAK */
const assertAssetKind = allegedAK => {
assetKindNames.includes(allegedAK) ||
Fail`The assetKind ${allegedAK} must be one of ${q(assetKindNames)}`;
};
harden(assertAssetKind);

/**
* Amounts describe digital assets. From an amount, you can learn the
* brand of digital asset as well as "how much" or "how many". Amounts
* have two parts: a brand (loosely speaking, the type of digital
* asset) and the value (the answer to "how much"). For example, in
* the phrase "5 bucks", "bucks" takes the role of the brand and the
* value is 5. Amounts can describe fungible and non-fungible digital
* assets. Amounts are pass-by-copy and can be made by and sent to
* anyone.
* Amounts describe digital assets. From an amount, you can learn the brand of
* digital asset as well as "how much" or "how many". Amounts have two parts: a
* brand (loosely speaking, the type of digital asset) and the value (the answer
* to "how much"). For example, in the phrase "5 bucks", "bucks" takes the role
* of the brand and the value is 5. Amounts can describe fungible and
* non-fungible digital assets. Amounts are pass-by-copy and can be made by and
* sent to anyone.
*
* The issuer is the authoritative source of the amount in payments
* and purses. The issuer must be able to do things such as add
* digital assets to a purse and withdraw digital assets from a purse.
* To do so, it must know how to add and subtract digital assets.
* Rather than hard-coding a particular solution, we chose to
* parameterize the issuer with a collection of polymorphic functions,
* which we call `AmountMath`. These math functions include concepts
* The issuer is the authoritative source of the amount in payments and purses.
* The issuer must be able to do things such as add digital assets to a purse
* and withdraw digital assets from a purse. To do so, it must know how to add
* and subtract digital assets. Rather than hard-coding a particular solution,
* we chose to parameterize the issuer with a collection of polymorphic
* functions, which we call `AmountMath`. These math functions include concepts
* like addition, subtraction, and greater than or equal to.
*
* We also want to make sure there is no confusion as to what kind of
* asset we are using. Thus, AmountMath includes checks of the
* `brand`, the unique identifier for the type of digital asset. If
* the wrong brand is used in AmountMath, an error is thrown and the
* operation does not succeed.
* We also want to make sure there is no confusion as to what kind of asset we
* are using. Thus, AmountMath includes checks of the `brand`, the unique
* identifier for the type of digital asset. If the wrong brand is used in
* AmountMath, an error is thrown and the operation does not succeed.
*
* AmountMath uses mathHelpers to do most of the work, but then adds
* the brand to the result. The function `value` gets the value from
* the amount by removing the brand (amount -> value), and the
* function `make` adds the brand to produce an amount (value ->
* amount). The function `coerce` takes an amount and checks it,
* returning an amount (amount -> amount).
* AmountMath uses mathHelpers to do most of the work, but then adds the brand
* to the result. The function `value` gets the value from the amount by
* removing the brand (amount -> value), and the function `make` adds the brand
* to produce an amount (value -> amount). The function `coerce` takes an amount
* and checks it, returning an amount (amount -> amount).
*
* Each issuer of digital assets has an associated brand in a
* one-to-one mapping. In untrusted contexts, such as in analyzing
* payments and amounts, we can get the brand and find the issuer
* which matches the brand. The issuer and the brand mutually validate
* each other.
* Each issuer of digital assets has an associated brand in a one-to-one
* mapping. In untrusted contexts, such as in analyzing payments and amounts, we
* can get the brand and find the issuer which matches the brand. The issuer and
* the brand mutually validate each other.
*/

const helpers = {
Expand Down Expand Up @@ -137,7 +135,7 @@ const optionalBrandCheck = (allegedBrand, brand) => {
* @param {Amount<K>} leftAmount
* @param {Amount<K>} rightAmount
* @param {Brand<K> | undefined} brand
* @returns {MathHelpers<*>}
* @returns {MathHelpers<any>}
*/
const checkLRAndGetHelpers = (leftAmount, rightAmount, brand = undefined) => {
assertRecord(leftAmount, 'leftAmount');
Expand Down Expand Up @@ -172,11 +170,11 @@ const coerceLR = (h, leftAmount, rightAmount) => {
};

/**
* Returns true if the leftAmount is greater than or equal to the
* rightAmount. The notion of "greater than or equal to" depends
* on the kind of amount, as defined by the MathHelpers. For example,
* whether rectangle A is greater than rectangle B depends on whether rectangle
* A includes rectangle B as defined by the logic in MathHelpers.
* Returns true if the leftAmount is greater than or equal to the rightAmount.
* The notion of "greater than or equal to" depends on the kind of amount, as
* defined by the MathHelpers. For example, whether rectangle A is greater than
* rectangle B depends on whether rectangle A includes rectangle B as defined by
* the logic in MathHelpers.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -194,9 +192,8 @@ const isGTE = (leftAmount, rightAmount, brand = undefined) => {
*
* Amounts are the canonical description of tradable goods. They are manipulated
* by issuers and mints, and represent the goods and currency carried by purses
* and
* payments. They can be used to represent things like currency, stock, and the
* abstract right to participate in a particular exchange.
* and payments. They can be used to represent things like currency, stock, and
* the abstract right to participate in a particular exchange.
*/
const AmountMath = {
/**
Expand All @@ -215,8 +212,8 @@ const AmountMath = {
return harden({ brand, value });
},
/**
* Make sure this amount is valid enough, and return a corresponding
* valid amount if so.
* Make sure this amount is valid enough, and return a corresponding valid
* amount if so.
*
* @template {AssetKind} K
* @param {Brand<K>} brand
Expand All @@ -242,8 +239,8 @@ const AmountMath = {
*/
getValue: (brand, amount) => AmountMath.coerce(brand, amount).value,
/**
* Return the amount representing an empty amount. This is the
* identity element for MathHelpers.add and MatHelpers.subtract.
* Return the amount representing an empty amount. This is the identity
* element for MathHelpers.add and MatHelpers.subtract.
*
* @type {{
* (brand: Brand): Amount<'nat'>;
Expand All @@ -257,8 +254,8 @@ const AmountMath = {
return harden({ brand, value });
},
/**
* Return the amount representing an empty amount, using another
* amount as the template for the brand and assetKind.
* Return the amount representing an empty amount, using another amount as the
* template for the brand and assetKind.
*
* @template {AssetKind} K
* @param {Amount<K>} amount
Expand Down Expand Up @@ -289,8 +286,8 @@ const AmountMath = {
},
isGTE,
/**
* Returns true if the leftAmount equals the rightAmount. We assume
* that if isGTE is true in both directions, isEqual is also true
* Returns true if the leftAmount equals the rightAmount. We assume that if
* isGTE is true in both directions, isEqual is also true
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -306,8 +303,8 @@ const AmountMath = {
* Returns a new amount that is the union of both leftAmount and rightAmount.
*
* For fungible amount this means adding the values. For other kinds of
* amount, it usually means including all of the elements from both
* left and right.
* amount, it usually means including all of the elements from both left and
* right.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -321,12 +318,11 @@ const AmountMath = {
return harden({ brand: leftAmount.brand, value });
},
/**
* Returns a new amount that is the leftAmount minus the rightAmount
* (i.e. everything in the leftAmount that is not in the
* rightAmount). If leftAmount doesn't include rightAmount
* (subtraction results in a negative), throw an error. Because the
* left amount must include the right amount, this is NOT equivalent
* to set subtraction.
* Returns a new amount that is the leftAmount minus the rightAmount (i.e.
* everything in the leftAmount that is not in the rightAmount). If leftAmount
* doesn't include rightAmount (subtraction results in a negative), throw an
* error. Because the left amount must include the right amount, this is NOT
* equivalent to set subtraction.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand Down Expand Up @@ -374,9 +370,7 @@ const AmountMath = {
};
harden(AmountMath);

/**
* @param {Amount} amount
*/
/** @param {Amount} amount */
const getAssetKind = amount => {
assertRecord(amount, 'amount');
const { value } = amount;
Expand Down
108 changes: 51 additions & 57 deletions packages/ERTP/src/issuerKit.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ import './types-ambient.js';
* @template {AssetKind} K
* @param {IssuerRecord<K>} issuerRecord
* @param {Baggage} issuerBaggage
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails
* in the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some
* larger unit of computation, like the enclosing vat, can be shutdown
* before anything else is corrupted by that corrupted state.
* See https://github.com/Agoric/agoric-sdk/issues/3434
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
* the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some larger
* unit of computation, like the enclosing vat, can be shutdown before
* anything else is corrupted by that corrupted state. See
* https://github.com/Agoric/agoric-sdk/issues/3434
* @returns {IssuerKit<K>}
*/
const setupIssuerKit = (
Expand Down Expand Up @@ -80,13 +80,13 @@ const INSTANCE_KEY = 'issuer';
/**
* @template {AssetKind} K
* @param {Baggage} issuerBaggage
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails
* in the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some
* larger unit of computation, like the enclosing vat, can be shutdown
* before anything else is corrupted by that corrupted state.
* See https://github.com/Agoric/agoric-sdk/issues/3434
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
* the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some larger
* unit of computation, like the enclosing vat, can be shutdown before
* anything else is corrupted by that corrupted state. See
* https://github.com/Agoric/agoric-sdk/issues/3434
* @returns {IssuerKit<K>}
*/
export const prepareIssuerKit = (
Expand All @@ -99,43 +99,39 @@ export const prepareIssuerKit = (
harden(prepareIssuerKit);

/**
* Does baggage already have an issuer from prepareIssuerKit()?
* That is: does it have the relevant keys defined?
* Does baggage already have an issuer from prepareIssuerKit()? That is: does it
* have the relevant keys defined?
*
* @param {Baggage} baggage
*/
export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);

/**
* @typedef {Partial<{elementShape: Pattern}>} IssuerOptionsRecord
*/
/** @typedef {Partial<{ elementShape: Pattern }>} IssuerOptionsRecord */

/**
* @template {AssetKind} K
* The name becomes part of the brand in asset descriptions.
* The name is useful for debugging and double-checking
* assumptions, but should not be trusted wrt any external namespace.
* For example, anyone could create a new issuer kit with name 'BTC', but
* it is not bitcoin or even related. It is only the name according
* to that issuer and brand.
* @template {AssetKind} K The name becomes part of the brand in asset
* descriptions. The name is useful for debugging and double-checking
* assumptions, but should not be trusted wrt any external namespace. For
* example, anyone could create a new issuer kit with name 'BTC', but it is
* not bitcoin or even related. It is only the name according to that issuer
* and brand.
*
* The assetKind will be used to import a specific mathHelpers
* from the mathHelpers library. For example, natMathHelpers, the
* default, is used for basic fungible tokens.
*
* `displayInfo` gives information to the UI on how to display the amount.
* The assetKind will be used to import a specific mathHelpers from the
* mathHelpers library. For example, natMathHelpers, the default, is used for
* basic fungible tokens.
*
* `displayInfo` gives information to the UI on how to display the amount.
* @param {Baggage} issuerBaggage
* @param {string} name
* @param {K} [assetKind=AssetKind.NAT]
* @param {AdditionalDisplayInfo} [displayInfo={}]
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails
* in the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some
* larger unit of computation, like the enclosing vat, can be shutdown
* before anything else is corrupted by that corrupted state.
* See https://github.com/Agoric/agoric-sdk/issues/3434
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
* the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some larger
* unit of computation, like the enclosing vat, can be shutdown before
* anything else is corrupted by that corrupted state. See
* https://github.com/Agoric/agoric-sdk/issues/3434
* @param {IssuerOptionsRecord} [options]
* @returns {IssuerKit<K>}
*/
Expand All @@ -155,30 +151,28 @@ export const makeDurableIssuerKit = (
harden(makeDurableIssuerKit);

/**
* @template {AssetKind} [K='nat']
* The name becomes part of the brand in asset descriptions.
* The name is useful for debugging and double-checking
* assumptions, but should not be trusted wrt any external namespace.
* For example, anyone could create a new issuer kit with name 'BTC', but
* it is not bitcoin or even related. It is only the name according
* to that issuer and brand.
*
* The assetKind will be used to import a specific mathHelpers
* from the mathHelpers library. For example, natMathHelpers, the
* default, is used for basic fungible tokens.
* @template {AssetKind} [K='nat'] The name becomes part of the brand in asset
* descriptions. The name is useful for debugging and double-checking
* assumptions, but should not be trusted wrt any external namespace. For
* example, anyone could create a new issuer kit with name 'BTC', but it is
* not bitcoin or even related. It is only the name according to that issuer
* and brand.
*
* `displayInfo` gives information to the UI on how to display the amount.
* The assetKind will be used to import a specific mathHelpers from the
* mathHelpers library. For example, natMathHelpers, the default, is used for
* basic fungible tokens.
*
* `displayInfo` gives information to the UI on how to display the amount.
* @param {string} name
* @param {K} [assetKind='nat']
* @param {AdditionalDisplayInfo} [displayInfo={}]
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails
* in the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some
* larger unit of computation, like the enclosing vat, can be shutdown
* before anything else is corrupted by that corrupted state.
* See https://github.com/Agoric/agoric-sdk/issues/3434
* @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
* the middle of an atomic action (which btw should never happen), it
* potentially leaves its ledger in a corrupted state. If this function was
* provided, then the failed atomic action will call it, so that some larger
* unit of computation, like the enclosing vat, can be shutdown before
* anything else is corrupted by that corrupted state. See
* https://github.com/Agoric/agoric-sdk/issues/3434
* @param {IssuerOptionsRecord} [options]
* @returns {IssuerKit<K>}
*/
Expand Down
Loading

0 comments on commit fc69584

Please sign in to comment.