@agoric/ertp 0.16.3-other-dev-8f8782b.0 → 0.16.3-other-dev-fbe72e7.0.fbe72e7

package/src/safeMath.js

@@ -0,0 +1,50 @@
+import { Nat } from '@endo/nat';
+
+/** @typedef {(x: number | bigint, y: number | bigint) => bigint} NatOp */
+
+/**
+ * These operations should be used for calculations with the values of basic
+ * fungible tokens.
+ *
+ * natSafeMath is designed to be used directly, and so it needs to validate the
+ * inputs, as well as the outputs when necessary.
+ */
+export const natSafeMath = harden({
+  /** @type {NatOp} */
+  // BigInts don't observably overflow
+  add: (x, y) => Nat(x) + Nat(y),
+  /** @type {NatOp} */
+  subtract: (x, y) => Nat(Nat(x) - Nat(y)),
+  /** @type {NatOp} */
+  multiply: (x, y) => Nat(x) * Nat(y),
+  /** @type {NatOp} */
+  floorDivide: (x, y) => Nat(x) / Nat(y),
+  /** @type {NatOp} */
+  ceilDivide: (x, y) => {
+    y = Nat(y);
+    return Nat(Nat(x) + y - 1n) / y;
+  },
+  /**
+   * Divide using half-to-even (aka Banker's Rounding) as in IEEE 774 default
+   * rounding
+   *
+   * @type {NatOp}
+   */
+  bankersDivide: (a, b) => {
+    a = Nat(a);
+    b = Nat(b);
+
+    const div = a / b;
+    const rem = a % b;
+    // if remainder > half divisor, should have rounded up instead of down, so add 1
+    if (rem * 2n > b) {
+      return div + 1n;
+    } else if (rem * 2n === b) {
+      // Add 1 if result is odd to get an even return value
+      if (div % 2n === 1n) return div + 1n;
+    }
+    return div;
+  },
+  /** @type {(x: number | bigint, y: number | bigint) => boolean} */
+  isGTE: (x, y) => Nat(x) >= Nat(y),
+});

package/src/transientNotifier.d.ts

@@ -1,5 +1,5 @@
 export function makeTransientNotifierKit(): {
-    provideNotifier: (key: any) => Notifier<any>;
+    provideNotifier: (key: any) => import("@agoric/notifier").Notifier<any>;
     update: (key: any, newValue: any) => void;
 };
 //# sourceMappingURL=transientNotifier.d.ts.map

package/src/transientNotifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transientNotifier.d.ts","sourceRoot":"","sources":["transientNotifier.js"],"names":[],"mappings":"AAQO;;;EAoBN"}
+{"version":3,"file":"transientNotifier.d.ts","sourceRoot":"","sources":["transientNotifier.js"],"names":[],"mappings":"AAaO;;;EAoBN"}

package/src/transientNotifier.js

@@ -4,6 +4,11 @@ import { makeScalarBigWeakMapStore } from '@agoric/vat-data';
 import { provideLazy } from '@agoric/store';
 import { makeNotifierKit } from '@agoric/notifier';
 
+/**
+ * @import {Purse} from './types.js';
+ * @import {NotifierRecord} from '@agoric/notifier';
+ */
+
 // Note: Virtual for high cardinality, but *not* durable, and so
 // broken across an upgrade.
 export const makeTransientNotifierKit = () => {

package/src/typeGuards.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @import {AmountValue, Ratio} from './types.js'
+ * @import {TypedPattern} from '@agoric/internal'
+ * @import {CopyBag, CopySet, Pattern} from '@endo/patterns';
+ */
 export const BrandShape: import("@endo/patterns").Matcher;
 export const IssuerShape: import("@endo/patterns").Matcher;
 export const PaymentShape: import("@endo/patterns").Matcher;
@@ -9,14 +14,24 @@ export namespace AmountShape {
     export { BrandShape as brand };
     export { AmountValueShape as value };
 }
-export namespace RatioShape {
-    export { AmountShape as numerator };
-    export { AmountShape as denominator };
-}
-export function isNatValue(value: AmountValue): value is bigint;
-export function isCopySetValue(value: AmountValue): value is CopySet<any>;
+/**
+ * To be used to guard an amount pattern argument, i.e., an argument which is a
+ * pattern that can be used to test amounts. Since amounts are keys, anywhere an
+ * amount pattern is expected, an amount can be provided and will match only
+ * that concrete amount, i.e., amounts that are `keyEQ` to that amount.
+ *
+ * The `AmountShape` guard above is an amount pattern. But not all amount
+ * patterns are like `AmountShape`. For example, `M.any()` is a valid amount
+ * pattern that will admit any amount, but is does not resemble the
+ * `AmountShape` pattern above.
+ */
+export const AmountPatternShape: import("@endo/patterns").Matcher;
+/** @type {TypedPattern<Ratio>} */
+export const RatioShape: TypedPattern<Ratio>;
+export function isNatValue(value: AmountValue): value is import("./types.js").NatValue;
+export function isCopySetValue(value: AmountValue): value is CopySet;
 export function isSetValue(value: AmountValue): value is SetValue;
-export function isCopyBagValue(value: AmountValue): value is CopyBag<any>;
+export function isCopyBagValue(value: AmountValue): value is CopyBag;
 export const MAX_ABSOLUTE_DECIMAL_PLACES: 100;
 export const AssetKindShape: import("@endo/patterns").Matcher;
 export const DisplayInfoShape: import("@endo/patterns").Matcher;
@@ -27,16 +42,52 @@ export namespace IssuerKitShape {
     export { IssuerShape as issuer };
     export { DisplayInfoShape as displayInfo };
 }
-export const BrandI: import("@endo/patterns").InterfaceGuard;
+export const BrandI: import("@endo/patterns").InterfaceGuard<{
+    isMyIssuer: import("@endo/patterns").MethodGuard;
+    getAllegedName: import("@endo/patterns").MethodGuard;
+    getDisplayInfo: import("@endo/patterns").MethodGuard;
+    getAmountShape: import("@endo/patterns").MethodGuard;
+}>;
 export function makeIssuerInterfaces(brandShape?: Pattern, assetKindShape?: Pattern, amountShape?: Pattern): {
-    IssuerI: import("@endo/patterns").InterfaceGuard;
-    MintI: import("@endo/patterns").InterfaceGuard;
-    PaymentI: import("@endo/patterns").InterfaceGuard;
+    IssuerI: import("@endo/patterns").InterfaceGuard<{
+        getBrand: import("@endo/patterns").MethodGuard;
+        getAllegedName: import("@endo/patterns").MethodGuard;
+        getAssetKind: import("@endo/patterns").MethodGuard;
+        getDisplayInfo: import("@endo/patterns").MethodGuard;
+        makeEmptyPurse: import("@endo/patterns").MethodGuard;
+        isLive: import("@endo/patterns").MethodGuard;
+        getAmountOf: import("@endo/patterns").MethodGuard;
+        burn: import("@endo/patterns").MethodGuard;
+    }>;
+    MintI: import("@endo/patterns").InterfaceGuard<{
+        getIssuer: import("@endo/patterns").MethodGuard;
+        mintPayment: import("@endo/patterns").MethodGuard;
+    }>;
+    PaymentI: import("@endo/patterns").InterfaceGuard<{
+        getAllegedBrand: import("@endo/patterns").MethodGuard;
+    }>;
     PurseIKit: {
-        purse: import("@endo/patterns").InterfaceGuard;
-        depositFacet: import("@endo/patterns").InterfaceGuard;
+        purse: import("@endo/patterns").InterfaceGuard<{
+            getAllegedBrand: import("@endo/patterns").MethodGuard;
+            getCurrentAmount: import("@endo/patterns").MethodGuard;
+            getCurrentAmountNotifier: import("@endo/patterns").MethodGuard;
+            deposit: import("@endo/patterns").MethodGuard;
+            getDepositFacet: import("@endo/patterns").MethodGuard;
+            withdraw: import("@endo/patterns").MethodGuard;
+            getRecoverySet: import("@endo/patterns").MethodGuard;
+            recoverAll: import("@endo/patterns").MethodGuard;
+        }>;
+        depositFacet: import("@endo/patterns").InterfaceGuard<{
+            receive: import("@endo/patterns").MethodGuard;
+        }>;
     };
 };
 declare const AmountValueShape: import("@endo/patterns").Matcher;
+import type { Ratio } from './types.js';
+import type { TypedPattern } from '@agoric/internal';
+import type { AmountValue } from './types.js';
+import type { CopySet } from '@endo/patterns';
+import type { CopyBag } from '@endo/patterns';
+import type { Pattern } from '@endo/patterns';
 export {};
 //# sourceMappingURL=typeGuards.d.ts.map

package/src/typeGuards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["typeGuards.js"],"names":[],"mappings":"AAIA,0DAA+C;AAC/C,2DAAiD;AACjD,4DAAmD;AACnD,0DAA+C;AAC/C,iEAA6D;AAC7D,6DAAqD;AACrD,yDAA6C;;;;;;;;;AAqFtC,kCAHI,WAAW,mBAG0C;AASzD,sCAHI,WAAW,yBAGkD;AAYjE,kCAHI,WAAW,qBAG0C;AASzD,sCAHI,WAAW,yBAGkD;AAIxE,8CAA+C;AAE/C,8DAAuE;AAEvE,gEAaE;;;;;;;;AAYF,6DAKG;AAOI,kDAJI,OAAO,mBACP,OAAO,gBACP,OAAO;;;;;;;;EAkEjB;AAlKD,iEAKE"}
+{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["typeGuards.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,0DAA+C;AAC/C,2DAAiD;AACjD,4DAAmD;AACnD,0DAA+C;AAC/C,iEAA6D;AAC7D,6DAAqD;AACrD,yDAA6C;;;;;AAkE7C;;;;;;;;;;GAUG;AACH,kEAA8C;AAE9C,kCAAkC;AAClC,yBADW,aAAa,KAAK,CAAC,CACiD;AASxE,kCAHI,WAAW,GACT,KAAK,IAAI,OAAO,YAAY,EAAE,QAAQ,CAEa;AASzD,sCAHI,WAAW,GACT,KAAK,IAAI,OAAO,CAE2C;AAYjE,kCAHI,WAAW,GACT,KAAK,IAAI,QAAQ,CAEkC;AASzD,sCAHI,WAAW,GACT,KAAK,IAAI,OAAO,CAE2C;AAIxE,0CAA2C,GAAG,CAAC;AAE/C,8DAAuE;AAEvE,gEAaE;;;;;;;;AAaF;;;;;GAKG;AAOI,kDAJI,OAAO,mBACP,OAAO,gBACP,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqEjB;AAhLD,iEAKE;2BAxEmC,YAAY;kCAClB,kBAAkB;iCADZ,YAAY;6BAEL,gBAAgB;6BAAhB,gBAAgB;6BAAhB,gBAAgB"}

package/src/typeGuards.js

@@ -1,6 +1,11 @@
 // @jessie-check
 
-import { M, matches } from '@agoric/store';
+import { M, matches, getInterfaceGuardPayload } from '@endo/patterns';
+/**
+ * @import {AmountValue, Ratio} from './types.js'
+ * @import {TypedPattern} from '@agoric/internal'
+ * @import {CopyBag, CopySet, Pattern} from '@endo/patterns';
+ */
 
 export const BrandShape = M.remotable('Brand');
 export const IssuerShape = M.remotable('Issuer');
@@ -11,62 +16,56 @@ export const NotifierShape = M.remotable('Notifier');
 export const MintShape = M.remotable('Mint');
 
 /**
- * When the AmountValue of an Amount fits the NatValueShape, i.e., when it is
- * a non-negative bigint, then it represents that many units of the
- * fungible asset represented by that amount. The brand of that amount
- * should indeed represent a kind of asset consisting of a countable
- * set of fungible units.
+ * When the AmountValue of an Amount fits the NatValueShape, i.e., when it is a
+ * non-negative bigint, then it represents that many units of the fungible asset
+ * represented by that amount. The brand of that amount should indeed represent
+ * a kind of asset consisting of a countable set of fungible units.
  */
 const NatValueShape = M.nat();
 
 /**
  * When the AmountValue of an Amount fits the CopySetValueShape, i.e., when it
- * is a CopySet, then it represents the set of those
- * keys, where each key represents some individual non-fungible
- * item, like a concert ticket, from the non-fungible asset class
- * represented by that amount's brand. The amount itself represents
- * the set of these items, as opposed to any of the other items
- * from the same asset class.
+ * is a CopySet, then it represents the set of those keys, where each key
+ * represents some individual non-fungible item, like a concert ticket, from the
+ * non-fungible asset class represented by that amount's brand. The amount
+ * itself represents the set of these items, as opposed to any of the other
+ * items from the same asset class.
  *
- * If a given value class represents concert tickets, it seems bizarre
- * that we can form amounts of any key. The hard constraint is that
- * the code that holds the mint for that asset class---the one associated
- * with that brand, only mints the items representing the real units
- * of that asset class as defined by it. Anyone else can put together
- * an amount expressing, for example, that they "want" some items that
- * will never be minted. That want will never be satisfied.
- * "You can't always get..."
+ * If a given value class represents concert tickets, it seems bizarre that we
+ * can form amounts of any key. The hard constraint is that the code that holds
+ * the mint for that asset class---the one associated with that brand, only
+ * mints the items representing the real units of that asset class as defined by
+ * it. Anyone else can put together an amount expressing, for example, that they
+ * "want" some items that will never be minted. That want will never be
+ * satisfied. "You can't always get..."
  */
 const CopySetValueShape = M.set();
 
 /**
- * When the AmountValue of an Amount fits the SetValueShape, i.e., when it
- * is a CopyArray of passable Keys. This representation is deprecated.
+ * When the AmountValue of an Amount fits the SetValueShape, i.e., when it is a
+ * CopyArray of passable Keys. This representation is deprecated.
  *
  * @deprecated Please change from using array-based SetValues to CopySet-based
- * CopySetValues.
+ *   CopySetValues.
  */
 const SetValueShape = M.arrayOf(M.key());
 
 /**
  * When the AmountValue of an Amount fits the CopyBagValueShape, i.e., when it
- * is a CopyBag, then it represents the bag (multiset) of those
- * keys, where each key represents some individual semi-fungible
- * item, like a concert ticket, from the semi-fungible asset class
- * represented by that amount's brand. The number of times that key
- * appears in the bag is the number of fungible units of that key.
- * The amount itself represents
- * the bag of these items, as opposed to any of the other items
- * from the same asset class.
+ * is a CopyBag, then it represents the bag (multiset) of those keys, where each
+ * key represents some individual semi-fungible item, like a concert ticket,
+ * from the semi-fungible asset class represented by that amount's brand. The
+ * number of times that key appears in the bag is the number of fungible units
+ * of that key. The amount itself represents the bag of these items, as opposed
+ * to any of the other items from the same asset class.
  *
- * If a given value class represents concert tickets, it seems bizarre
- * that we can form amounts of any key. The hard constraint is that
- * the code that holds the mint for that asset class---the one associated
- * with that brand, only mints the items representing the real units
- * of that asset class as defined by it. Anyone else can put together
- * an amount expressing, for example, that they "want" some items that
- * will never be minted. That want will never be satisfied.
- * "You can't always get..."
+ * If a given value class represents concert tickets, it seems bizarre that we
+ * can form amounts of any key. The hard constraint is that the code that holds
+ * the mint for that asset class---the one associated with that brand, only
+ * mints the items representing the real units of that asset class as defined by
+ * it. Anyone else can put together an amount expressing, for example, that they
+ * "want" some items that will never be minted. That want will never be
+ * satisfied. "You can't always get..."
  */
 const CopyBagValueShape = M.bag();
 
@@ -77,15 +76,25 @@ const AmountValueShape = M.or(
   CopyBagValueShape,
 );
 
-export const AmountShape = harden({
-  brand: BrandShape,
-  value: AmountValueShape,
-});
+export const AmountShape = { brand: BrandShape, value: AmountValueShape };
+harden(AmountShape);
 
-export const RatioShape = harden({
-  numerator: AmountShape,
-  denominator: AmountShape,
-});
+/**
+ * To be used to guard an amount pattern argument, i.e., an argument which is a
+ * pattern that can be used to test amounts. Since amounts are keys, anywhere an
+ * amount pattern is expected, an amount can be provided and will match only
+ * that concrete amount, i.e., amounts that are `keyEQ` to that amount.
+ *
+ * The `AmountShape` guard above is an amount pattern. But not all amount
+ * patterns are like `AmountShape`. For example, `M.any()` is a valid amount
+ * pattern that will admit any amount, but is does not resemble the
+ * `AmountShape` pattern above.
+ */
+export const AmountPatternShape = M.pattern();
+
+/** @type {TypedPattern<Ratio>} */
+export const RatioShape = { numerator: AmountShape, denominator: AmountShape };
+harden(RatioShape);
 
 /**
  * Returns true if value is a Nat bigint.
@@ -106,11 +115,11 @@ export const isCopySetValue = value => matches(value, CopySetValueShape);
 harden(isCopySetValue);
 
 /**
- * Returns true if value is a pass by copy array structure. Does not
- * check for duplicates. To check for duplicates, use setMathHelpers.coerce.
+ * Returns true if value is a pass by copy array structure. Does not check for
+ * duplicates. To check for duplicates, use setMathHelpers.coerce.
  *
  * @deprecated Please change from using array-based SetValues to CopySet-based
- * CopySetValues.
+ *   CopySetValues.
  * @param {AmountValue} value
  * @returns {value is SetValue}
  */
@@ -146,13 +155,14 @@ export const DisplayInfoShape = M.splitRecord(
   },
 );
 
-export const IssuerKitShape = harden({
+export const IssuerKitShape = {
   brand: BrandShape,
   mint: MintShape,
   mintRecoveryPurse: PurseShape,
   issuer: IssuerShape,
   displayInfo: DisplayInfoShape,
-});
+};
+harden(IssuerKitShape);
 
 // //////////////////////// Interfaces /////////////////////////////////////////
 
@@ -183,7 +193,7 @@ export const makeIssuerInterfaces = (
     isLive: M.callWhen(M.await(PaymentShape)).returns(M.boolean()),
     getAmountOf: M.callWhen(M.await(PaymentShape)).returns(amountShape),
     burn: M.callWhen(M.await(PaymentShape))
-      .optional(M.pattern())
+      .optional(AmountPatternShape)
       .returns(amountShape),
   });
 
@@ -210,7 +220,9 @@ export const makeIssuerInterfaces = (
     // `srcPayment` is a remotable, leaving it
     // to this raw method to validate that this remotable is actually
     // a live payment of the correct brand with sufficient funds.
-    deposit: M.call(PaymentShape).optional(M.pattern()).returns(amountShape),
+    deposit: M.call(PaymentShape)
+      .optional(AmountPatternShape)
+      .returns(amountShape),
     getDepositFacet: M.call().returns(DepositFacetShape),
     withdraw: M.call(amountShape).returns(PaymentShape),
     getRecoverySet: M.call().returns(M.setOf(PaymentShape)),
@@ -218,13 +230,14 @@ export const makeIssuerInterfaces = (
   });
 
   const DepositFacetI = M.interface('DepositFacet', {
-    receive: PurseI.methodGuards.deposit,
+    receive: getInterfaceGuardPayload(PurseI).methodGuards.deposit,
   });
 
-  const PurseIKit = harden({
+  const PurseIKit = {
     purse: PurseI,
     depositFacet: DepositFacetI,
-  });
+  };
+  harden(PurseIKit);
 
   return harden({
     IssuerI,

package/src/types-index.d.ts

@@ -0,0 +1,2 @@
+// Export all the types this package provides
+export type * from './types.js';

package/src/types-index.js

@@ -0,0 +1,2 @@
+// Empty JS file to correspond with its .d.ts twin
+export {};