@agoric/ertp 0.16.3-u19.2 → 0.16.3-u21.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@agoric/ertp",
-  "version": "0.16.3-u19.2",
+  "version": "0.16.3-u21.0",
   "description": "Electronic Rights Transfer Protocol (ERTP). A smart contract framework for exchanging electronic rights",
   "type": "module",
   "main": "src/index.js",
   "engines": {
-    "node": "^18.12 || ^20.9"
+    "node": "^20.9 || ^22.11"
   },
   "scripts": {
     "build": "exit 0",
-    "prepack": "tsc --build tsconfig.build.json",
+    "prepack": "yarn run -T tsc --build tsconfig.build.json",
     "postpack": "git clean -f '*.d.ts*' '*.tsbuildinfo'",
     "test": "ava",
     "test:c8": "c8 --all $C8_OPTIONS ava",
@@ -17,9 +17,9 @@
     "test:xs-unit": "exit 0",
     "test:xs-worker": "SWINGSET_WORKER_TYPE=xs-worker ava -c 2 test/swingsetTests",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint": "run-s --continue-on-error lint:*",
-    "lint:eslint": "eslint .",
-    "lint:types": "tsc"
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:eslint": "yarn run -T eslint .",
+    "lint:types": "yarn run -T tsc"
   },
   "repository": {
     "type": "git",
@@ -39,21 +39,22 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/notifier": "^0.7.0-u19.2",
-    "@agoric/store": "^0.9.3-u19.0",
-    "@agoric/vat-data": "^0.5.3-u19.2",
-    "@agoric/zone": "^0.3.0-u19.2",
-    "@endo/errors": "^1.2.9",
-    "@endo/eventual-send": "^1.3.0",
-    "@endo/far": "^1.1.10",
-    "@endo/marshal": "^1.6.3",
-    "@endo/nat": "^5.0.14",
-    "@endo/patterns": "^1.4.8",
-    "@endo/promise-kit": "^1.1.9"
+    "@agoric/notifier": "workspace:*",
+    "@agoric/store": "workspace:*",
+    "@agoric/vat-data": "workspace:*",
+    "@agoric/zone": "workspace:*",
+    "@endo/errors": "^1.2.10",
+    "@endo/eventual-send": "^1.3.1",
+    "@endo/far": "^1.1.11",
+    "@endo/marshal": "^1.6.4",
+    "@endo/nat": "^5.1.0",
+    "@endo/patterns": "^1.5.0",
+    "@endo/promise-kit": "^1.1.10"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "^0.33.0-u19.2",
-    "@endo/bundle-source": "^3.5.1",
+    "@agoric/swingset-vat": "workspace:*",
+    "@agoric/xsnap": "workspace:*",
+    "@endo/bundle-source": "^4.0.0",
     "@fast-check/ava": "^1.1.5",
     "ava": "^5.3.0",
     "tsd": "^0.31.1"
@@ -77,7 +78,7 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 91.77
+    "atLeast": 93.1
   },
-  "gitHead": "f0ae74b84cb6de3724bfdcd18b4bea7e8199dee1"
+  "gitHead": "e4dd46857133403d584bcf822a81817b355532f9"
 }

package/src/amountMath.d.ts

@@ -9,9 +9,9 @@ export namespace AssetKind {
     let COPY_BAG: "copyBag";
 }
 export function assertAssetKind(allegedAK: AssetKind): void;
-export function assertValueGetHelpers<V>(value: V): MathHelpers<V>;
+export function assertValueGetHelpers<V extends AmountValue>(value: V): MathHelpers<V>;
 export namespace AmountMath {
-    export function make<B extends Brand, V extends NatValue | CopySet | CopyBag | SetValue>(brand: B, allegedValue: V): B extends Brand<"nat"> ? NatAmount : V extends NatValue ? NatAmount : V extends CopySet ? CopySetAmount<V["payload"][0]> : V extends CopyBag ? CopyBagAmount<V["payload"][0][0]> : V extends SetValue ? SetAmount<V[0]> : never;
+    export function make<B extends Brand<any>, V extends NatValue | CopySet | CopyBag | SetValue>(brand: B, allegedValue: V): B extends Brand<"nat"> ? NatAmount : V extends NatValue ? NatAmount : V extends CopySet ? CopySetAmount<V["payload"][0]> : V extends CopyBag ? CopyBagAmount<V["payload"][0][0]> : V extends SetValue ? SetAmount<V[0]> : never;
     export function coerce<A extends Amount>(brand: Brand, allegedAmount: A): A;
     export function getValue<A extends Amount>(brand: Brand, amount: A): A["value"];
     export let makeEmpty: {
@@ -27,7 +27,8 @@ export namespace AmountMath {
     export function min<A extends Amount>(x: A, y: A, brand?: Brand): A;
     export function max<A extends Amount>(x: A, y: A, brand?: Brand): A;
 }
-export function getAssetKind(amount: Amount): "copySet" | "set" | "nat" | "copyBag";
+export function getAssetKind(amount: Amount): "copySet" | "copyBag" | "set" | "nat";
+import type { AmountValue } from './types.js';
 import type { MathHelpers } from './types.js';
 import type { Brand } from './types.js';
 import type { NatValue } from './types.js';

package/src/amountMath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"amountMath.d.ts","sourceRoot":"","sources":["amountMath.js"],"names":[],"mappings":";;;wBAkBU,CAAC,OAAO,SAAS,EAAE,MAAM,OAAO,SAAS,CAAC;;;;;;;AAY7C,2CADK,SAAS,QAIpB;AA8EM,sCAJM,CAAC,SACH,CAAC,GACC,YAAY,CAAC,CAAC,CAIc;;IAsGjC,qBAhBe,CAAC,SAAT,KAAO,EACmC,CAAC,SAA1C,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAS,SAC3C,CAAC,gBACD,CAAC,GACC,CAAC,SAAS,MAAM,KAAK,CAAC,GAC1B,SAAS,GACT,CAAC,SAAS,QAAQ,GAChB,SAAS,GACT,CAAC,SAAS,OAAO,GACf,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,CAAC,SAAS,OAAO,GACf,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjC,CAAC,SAAS,QAAQ,GAChB,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GACf,KAAK,CAQrB;IAUO,uBALc,CAAC,SAAV,MAAQ,SACV,KAAK,iBACL,CAAC,GACC,CAAC,CAWb;IASS,yBALY,CAAC,SAAV,MAAQ,SACV,KAAK,UACL,CAAC,GACC,CAAC,CAAC,OAAO,CAAC,CAE4C;0BAKzD;QACT,CAAK,KAAK,EAAE,KAAK,GAAG,OAAO,KAAK,CAAC,CAAC;QAClC,CAAK,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;KACjE;IAiBiB,oCAJC,CAAC,SAAV,MAAQ,UACV,CAAC,GACC,CAAC,CAQb;IAQQ,gCAJE,MAAM,UACN,KAAK,GACH,OAAO,CASnB;;IAYQ,wBANa,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,OAAO,CAKnB;IAcI,oBANiB,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,CAAC,CAOb;IAeS,yBAPY,CAAC,SAAV,MAAQ,EACC,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAOnC;IAUI,oBANiB,CAAC,SAAV,MAAQ,KACV,CAAC,KACD,CAAC,UACD,KAAK,GACH,CAAC,CAQ8B;IAUvC,oBANiB,CAAC,SAAV,MAAQ,KACV,CAAC,KACD,CAAC,UACD,KAAK,GACH,CAAC,CAQ8B;;AAKvC,qCADK,MAAM,yCAKjB;iCA3XuI,YAAY;2BAAZ,YAAY;8BAAZ,YAAY;6BADjH,gBAAgB;6BAAhB,gBAAgB;8BACqF,YAAY;+BAAZ,YAAY;mCAAZ,YAAY;mCAAZ,YAAY;+BAAZ,YAAY;4BAAZ,YAAY;AA0JpJ;;;;;;;;;;;;GAYG;AACH,uBANyB,CAAC,SAAZ,SAAU,cACb,OAAO,CAAC,CAAC,eACT,OAAO,CAAC,CAAC,UACT,MAAM,CAAC,CAAC,GACN,OAAO,CAKnB"}
+{"version":3,"file":"amountMath.d.ts","sourceRoot":"","sources":["amountMath.js"],"names":[],"mappings":";;;wBAkBU,CAAC,OAAO,SAAS,EAAE,MAAM,OAAO,SAAS,CAAC;;;;;;;AAY7C,2CADK,SAAS,QAIpB;AA8EM,sCAJoB,CAAC,SAAf,WAAa,SACf,CAAC,GACC,YAAY,CAAC,CAAC,CAIc;;IAwGjC,qBAhBoB,CAAC,SAAd,MAAO,GAAG,CAAE,EAC8B,CAAC,SAA1C,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAS,SAC3C,CAAC,gBACD,CAAC,GACC,CAAC,SAAS,MAAM,KAAK,CAAC,GAC1B,SAAS,GACT,CAAC,SAAS,QAAQ,GAChB,SAAS,GACT,CAAC,SAAS,OAAO,GACf,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,CAAC,SAAS,OAAO,GACf,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjC,CAAC,SAAS,QAAQ,GAChB,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GACf,KAAK,CAQrB;IAUO,uBALc,CAAC,SAAV,MAAQ,SACV,KAAK,iBACL,CAAC,GACC,CAAC,CAWb;IASS,yBALY,CAAC,SAAV,MAAQ,SACV,KAAK,UACL,CAAC,GACC,CAAC,CAAC,OAAO,CAAC,CAE4C;0BAKzD;QACT,CAAK,KAAK,EAAE,KAAK,GAAG,OAAO,KAAK,CAAC,CAAC;QAClC,CAAK,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;KACjE;IAiBiB,oCAJC,CAAC,SAAV,MAAQ,UACV,CAAC,GACC,CAAC,CAQb;IAQQ,gCAJE,MAAM,UACN,KAAK,GACH,OAAO,CASnB;;IAYQ,wBANa,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,OAAO,CAKnB;IAcI,oBANiB,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,CAAC,CAOb;IAeS,yBAPY,CAAC,SAAV,MAAQ,EACC,CAAC,SAAV,MAAQ,cACV,CAAC,eACD,CAAC,UACD,KAAK,GACH,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAOnC;IAUI,oBANiB,CAAC,SAAV,MAAQ,KACV,CAAC,KACD,CAAC,UACD,KAAK,GACH,CAAC,CAQ8B;IAUvC,oBANiB,CAAC,SAAV,MAAQ,KACV,CAAC,KACD,CAAC,UACD,KAAK,GACH,CAAC,CAQ8B;;AAKvC,qCADK,MAAM,yCAKjB;iCA7XoJ,YAAY;iCAAZ,YAAY;2BAAZ,YAAY;8BAAZ,YAAY;6BAD9H,gBAAgB;6BAAhB,gBAAgB;8BACkG,YAAY;+BAAZ,YAAY;mCAAZ,YAAY;mCAAZ,YAAY;+BAAZ,YAAY;4BAAZ,YAAY;AA4JjK;;;;;;;;;;;;GAYG;AACH,uBANyB,CAAC,SAAZ,SAAU,cACb,OAAO,CAAC,CAAC,eACT,OAAO,CAAC,CAAC,UACT,MAAM,CAAC,CAAC,GACN,OAAO,CAKnB"}

package/src/amountMath.js

@@ -9,7 +9,7 @@ import { copyBagMathHelpers } from './mathHelpers/copyBagMathHelpers.js';
 
 /**
  * @import {CopyBag, CopySet} from '@endo/patterns';
- * @import {Amount, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ * @import {Amount, AmountValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
  */
 
 // NB: AssetKind is both a constant for enumerated values and a type for those values.
@@ -105,7 +105,7 @@ const assertValueGetAssetKind = value => {
  *
  * Made available only for testing, but it is harmless for other uses.
  *
- * @template V
+ * @template {AmountValue} V
  * @param {V} value
  * @returns {MathHelpers<V>}
  */
@@ -113,7 +113,9 @@ export const assertValueGetHelpers = value =>
   // @ts-expect-error cast
   helpers[assertValueGetAssetKind(value)];
 
-/** @type {(allegedBrand: Brand, brand?: Brand) => void} */
+/**
+ * @type {(allegedBrand: Brand<any>, brand?: Brand<any>) => void}
+ */
 const optionalBrandCheck = (allegedBrand, brand) => {
   if (brand !== undefined) {
     assertRemotable(brand, 'brand');
@@ -156,7 +158,7 @@ const checkLRAndGetHelpers = (leftAmount, rightAmount, brand = undefined) => {
  * @param {MathHelpers<AssetValueForKind<K>>} h
  * @param {Amount<K>} leftAmount
  * @param {Amount<K>} rightAmount
- * @returns {[K, K]}
+ * @returns {[AssetValueForKind<K>, AssetValueForKind<K>]}
  */
 const coerceLR = (h, leftAmount, rightAmount) => {
   // @ts-expect-error could be arbitrary subtype
@@ -197,7 +199,7 @@ export const AmountMath = {
    *
    * Does not verify that the Brand's AssetKind matches the value's.
    *
-   * @template {Brand} B
+   * @template {Brand<any>} B
    * @template {NatValue | CopySet | CopyBag | SetValue} V
    * @param {B} brand
    * @param {V} allegedValue

package/src/issuerKit.d.ts

@@ -1,8 +1,8 @@
-export function upgradeIssuerKit<K extends AssetKind>(issuerBaggage: import("@agoric/vat-data").Baggage, optShutdownWithFailure?: ShutdownWithFailure, recoverySetsOption?: RecoverySetsOption): IssuerKit<K>;
-export function hasIssuer(baggage: import("@agoric/vat-data").Baggage): boolean;
-export function makeDurableIssuerKit<K extends AssetKind>(issuerBaggage: import("@agoric/vat-data").Baggage, name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, { elementShape, recoverySetsOption }?: IssuerOptionsRecord): IssuerKit<K>;
-export function prepareIssuerKit<O extends IssuerOptionsRecord, K extends AssetKind>(issuerBaggage: import("@agoric/vat-data").Baggage, name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, options?: O): O["elementShape"] extends TypedPattern<infer T> ? IssuerKit<K, T> : IssuerKit<K>;
-export function makeIssuerKit<K extends AssetKind = "nat", O extends IssuerOptionsRecord = {}>(name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, { elementShape, recoverySetsOption }?: O): O["elementShape"] extends TypedPattern<infer T> ? IssuerKit<K, T> : IssuerKit<K>;
+export function upgradeIssuerKit<K extends AssetKind>(issuerBaggage: Baggage, optShutdownWithFailure?: ShutdownWithFailure, recoverySetsOption?: RecoverySetsOption): IssuerKit<K>;
+export function hasIssuer(baggage: Baggage): boolean;
+export function makeDurableIssuerKit<K extends AssetKind>(issuerBaggage: Baggage, name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, { elementShape, recoverySetsOption }?: IssuerOptionsRecord): IssuerKit<K>;
+export function prepareIssuerKit<O extends IssuerOptionsRecord, K extends AssetKind>(issuerBaggage: Baggage, name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, options?: O): O["elementShape"] extends TypedPattern<infer T extends Key> ? IssuerKit<K, T> : IssuerKit<K>;
+export function makeIssuerKit<K extends AssetKind = "nat", O extends IssuerOptionsRecord = {}>(name: string, assetKind?: K, displayInfo?: AdditionalDisplayInfo, optShutdownWithFailure?: ShutdownWithFailure, { elementShape, recoverySetsOption }?: O): O["elementShape"] extends TypedPattern<infer T extends Key> ? IssuerKit<K, T> : IssuerKit<K>;
 export type IssuerRecord<K extends AssetKind> = {
     name: string;
     assetKind: K;
@@ -28,9 +28,12 @@ export type IssuerOptionsRecord = Partial<{
     recoverySetsOption: RecoverySetsOption;
 }>;
 import { AssetKind } from './amountMath.js';
+import type { Baggage } from '@agoric/vat-data';
 import type { ShutdownWithFailure } from '@agoric/swingset-vat';
 import type { RecoverySetsOption } from './types.js';
 import type { IssuerKit } from './types.js';
 import type { AdditionalDisplayInfo } from './types.js';
+import type { Key } from '@endo/patterns';
 import type { TypedPattern } from '@agoric/internal';
+import type { Pattern } from '@endo/patterns';
 //# sourceMappingURL=issuerKit.d.ts.map

package/src/issuerKit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issuerKit.d.ts","sourceRoot":"","sources":["issuerKit.js"],"names":[],"mappings":"AA+GO,iCAbkB,CAAC,SAAZ,SAAU,iBACb,OAAO,kBAAkB,EAAE,OAAO,2BAClC,mBAAmB,uBAOnB,kBAAkB,GAEhB,UAAU,CAAC,CAAC,CA4BxB;AAQM,mCAFI,OAAO,kBAAkB,EAAE,OAAO,WAEgB;AAoDtD,qCA1BkB,CAAC,SAAZ,SAAU,iBAYb,OAAO,kBAAkB,EAAE,OAAO,QAClC,MAAM,cACN,CAAC,gBACD,qBAAqB,2BACrB,mBAAmB,yCAOnB,mBAAmB,GACjB,UAAU,CAAC,CAAC,CA2BxB;AAoCM,iCA7B4B,CAAC,SAAtB,mBAAoB,EACT,CAAC,SAAZ,SAAU,iBAYb,OAAO,kBAAkB,EAAE,OAAO,QAClC,MAAM,cACN,CAAC,gBACD,qBAAqB,2BACrB,mBAAmB,YAOnB,CAAC,GACC,CAAC,CAAC,cAAc,CAAC,SAAS,aAAa,MAAM,CAAC,CAAC,GACnD,UAAU,CAAC,EAAE,CAAC,CAAC,GACf,UAAU,CAAC,CAAC,CAyCpB;AAqCM,8BAzBmB,CAAC,SAAb,SAAU,UACY,CAAC,SAAvB,mBAAoB,aACvB,MAAM,cAMN,CAAC,gBAGD,qBAAqB,2BAErB,mBAAmB,yCAOnB,CAAC,GACC,CAAC,CAAC,cAAc,CAAC,SAAS,aAAa,MAAM,CAAC,CAAC,GACnD,UAAU,CAAC,EAAE,CAAC,CAAC,GACf,UAAU,CAAC,CAAC,CAmBlB;yBA7UsB,CAAC,SAAZ,SAAU;UAEV,MAAM;eACN,CAAC;iBACD,qBAAqB;kBACrB,OAAO;;;;;;;;;;;;;;;;kCA0IR,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,kBAAkB,CAAC;CACxC,CAAC;0BA7JsC,iBAAiB;yCAMtB,sBAAsB;wCAD0B,YAAY;+BAAZ,YAAY;2CAAZ,YAAY;kCAEnE,kBAAkB"}
+{"version":3,"file":"issuerKit.d.ts","sourceRoot":"","sources":["issuerKit.js"],"names":[],"mappings":"AAkHO,iCAbkB,CAAC,SAAZ,SAAU,iBACb,OAAO,2BACP,mBAAmB,uBAOnB,kBAAkB,GAEhB,UAAU,CAAC,CAAC,CA4BxB;AAQM,mCAFI,OAAO,WAE2C;AAoDtD,qCA1BkB,CAAC,SAAZ,SAAU,iBAYb,OAAO,QACP,MAAM,cACN,CAAC,gBACD,qBAAqB,2BACrB,mBAAmB,yCAOnB,mBAAmB,GACjB,UAAU,CAAC,CAAC,CA2BxB;AAoCM,iCA7B4B,CAAC,SAAtB,mBAAoB,EACT,CAAC,SAAZ,SAAU,iBAYb,OAAO,QACP,MAAM,cACN,CAAC,gBACD,qBAAqB,2BACrB,mBAAmB,YAOnB,CAAC,GACC,CAAC,CAAC,cAAc,CAAC,SAAS,aAAa,MAAM,CAAC,SAAS,GAAG,CAAC,GAC/D,UAAU,CAAC,EAAE,CAAC,CAAC,GACf,UAAU,CAAC,CAAC,CAyCpB;AAqCM,8BAzBmB,CAAC,SAAb,SAAU,UACY,CAAC,SAAvB,mBAAoB,aACvB,MAAM,cAMN,CAAC,gBAGD,qBAAqB,2BAErB,mBAAmB,yCAOnB,CAAC,GACC,CAAC,CAAC,cAAc,CAAC,SAAS,aAAa,MAAM,CAAC,SAAS,GAAG,CAAC,GAC/D,UAAU,CAAC,EAAE,CAAC,CAAC,GACf,UAAU,CAAC,CAAC,CAmBlB;yBA7UsB,CAAC,SAAZ,SAAU;UAEV,MAAM;eACN,CAAC;iBACD,qBAAqB;kBACrB,OAAO;;;;;;;;;;;;;;;;kCA0IR,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,kBAAkB,CAAC;CACxC,CAAC;0BAhKsC,iBAAiB;6BASlC,kBAAkB;yCAFN,sBAAsB;wCAG0B,YAAY;+BAAZ,YAAY;2CAAZ,YAAY;yBALnE,gBAAgB;kCAGhB,kBAAkB;6BAHlB,gBAAgB"}

package/src/issuerKit.js

@@ -10,9 +10,12 @@ import { coerceDisplayInfo } from './displayInfo.js';
 import { preparePaymentLedger } from './paymentLedger.js';
 
 /**
- * @import {AdditionalDisplayInfo, RecoverySetsOption, IssuerKit, PaymentLedger} from './types.js';
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {Zone} from '@agoric/base-zone';
  * @import {ShutdownWithFailure} from '@agoric/swingset-vat';
  * @import {TypedPattern} from '@agoric/internal';
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {AdditionalDisplayInfo, RecoverySetsOption, IssuerKit, PaymentLedger} from './types.js';
  */
 
 /**
@@ -29,7 +32,7 @@ import { preparePaymentLedger } from './paymentLedger.js';
  *
  * @template {AssetKind} K
  * @param {IssuerRecord<K>} issuerRecord
- * @param {import('@agoric/zone').Zone} issuerZone
+ * @param {Zone} issuerZone
  * @param {RecoverySetsOption} recoverySetsState Omitted from issuerRecord
  *   because it was added in an upgrade.
  * @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
@@ -97,7 +100,7 @@ const RECOVERY_SETS_STATE = 'recoverySetsState';
  * make a new one.
  *
  * @template {AssetKind} K
- * @param {import('@agoric/vat-data').Baggage} issuerBaggage
+ * @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
@@ -141,7 +144,7 @@ harden(upgradeIssuerKit);
 /**
  * Does baggage already have an issuerKit?
  *
- * @param {import('@agoric/vat-data').Baggage} baggage
+ * @param {Baggage} baggage
  */
 export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
 
@@ -181,7 +184,7 @@ export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
  *   basic fungible tokens.
  *
  *   `displayInfo` gives information to the UI on how to display the amount.
- * @param {import('@agoric/vat-data').Baggage} issuerBaggage
+ * @param {Baggage} issuerBaggage
  * @param {string} name
  * @param {K} [assetKind]
  * @param {AdditionalDisplayInfo} [displayInfo]
@@ -240,7 +243,7 @@ harden(makeDurableIssuerKit);
  *   basic fungible tokens.
  *
  *   `displayInfo` gives information to the UI on how to display the amount.
- * @param {import('@agoric/vat-data').Baggage} issuerBaggage
+ * @param {Baggage} issuerBaggage
  * @param {string} name
  * @param {K} [assetKind]
  * @param {AdditionalDisplayInfo} [displayInfo]
@@ -252,7 +255,7 @@ harden(makeDurableIssuerKit);
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @param {O} [options]
- * @returns {O['elementShape'] extends TypedPattern<infer T>
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
  *     ? IssuerKit<K, T>
  *     : IssuerKit<K>}
  */
@@ -328,7 +331,7 @@ harden(prepareIssuerKit);
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @param {O} [options]
- * @returns {O['elementShape'] extends TypedPattern<infer T>
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
  *     ? IssuerKit<K, T>
  *     : IssuerKit<K>}
  */

package/src/legacy-payment-helpers.d.ts

@@ -7,5 +7,6 @@ import type { Key } from '@endo/patterns';
 import type { Purse } from './types.js';
 import type { ERef } from '@endo/far';
 import type { Payment } from './types.js';
+import type { Pattern } from '@endo/patterns';
 import type { Amount } from './types.js';
 //# sourceMappingURL=legacy-payment-helpers.d.ts.map

package/src/legacy-payment-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-payment-helpers.d.ts","sourceRoot":"","sources":["legacy-payment-helpers.js"],"names":[],"mappings":"AAmCO,sBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,eACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,mBACnB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAWlC;AAkBM,wBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,iBACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBACrB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CA8BlC;AAgBM,sBANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAChB,OAAO,CAAC,CAAC,GACP,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAYjC;AAgBM,0BANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,WAChB,OAAO,CAAC,CAAC,EAAE,GACT,OAAO,CAAC,OAAO,EAAE,CAAC,CAoB9B;+BA5ImD,YAAY;yBAD1C,gBAAgB;2BACc,YAAY;0BAFzC,WAAW;6BAEkB,YAAY;4BAAZ,YAAY"}
+{"version":3,"file":"legacy-payment-helpers.d.ts","sourceRoot":"","sources":["legacy-payment-helpers.js"],"names":[],"mappings":"AAmCO,sBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,eACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,mBACnB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAWlC;AAkBM,wBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,iBACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBACrB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CA8BlC;AAgBM,sBANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAChB,OAAO,CAAC,CAAC,GACP,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAYjC;AAgBM,0BANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,WAChB,OAAO,CAAC,CAAC,EAAE,GACT,OAAO,CAAC,OAAO,EAAE,CAAC,CAoB9B;+BA5ImD,YAAY;yBADjC,gBAAgB;2BACK,YAAY;0BAFzC,WAAW;6BAEkB,YAAY;6BADjC,gBAAgB;4BACK,YAAY"}

package/src/legacy-payment-helpers.js

@@ -7,7 +7,7 @@ import { AmountMath } from './amountMath.js';
 
 /**
  * @import {ERef} from '@endo/far';
- * @import {Key} from '@endo/patterns';
+ * @import {Key, Pattern} from '@endo/patterns';
  * @import {Amount, AssetKind, Payment, Purse} from './types.js';
  */
 

package/src/paymentLedger.d.ts

@@ -1,6 +1,8 @@
-export function preparePaymentLedger<K extends AssetKind>(issuerZone: import("@agoric/zone").Zone, name: string, assetKind: K, displayInfo: DisplayInfo<K>, elementShape: Pattern, recoverySetsState: RecoverySetsOption, optShutdownWithFailure?: ShutdownWithFailure): PaymentLedger<K>;
+export function preparePaymentLedger<K extends AssetKind>(issuerZone: Zone, name: string, assetKind: K, displayInfo: DisplayInfo<K>, elementShape: Pattern, recoverySetsState: RecoverySetsOption, optShutdownWithFailure?: ShutdownWithFailure): PaymentLedger<K>;
 import type { AssetKind } from './types.js';
+import type { Zone } from '@agoric/base-zone';
 import type { DisplayInfo } from './types.js';
+import type { Pattern } from '@endo/patterns';
 import type { RecoverySetsOption } from './types.js';
 import type { ShutdownWithFailure } from '@agoric/swingset-vat';
 import type { PaymentLedger } from './types.js';

package/src/paymentLedger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paymentLedger.d.ts","sourceRoot":"","sources":["paymentLedger.js"],"names":[],"mappings":"AAqFO,qCAVkB,CAAC,SAAb,SAAW,cACb,OAAO,cAAc,EAAE,IAAI,QAC3B,MAAM,aACN,CAAC,eACD,YAAY,CAAC,CAAC,gBACd,OAAO,qBACP,kBAAkB,2BAClB,mBAAmB,GACjB,cAAc,CAAC,CAAC,CAyT5B;+BA9XwH,YAAY;iCAAZ,YAAY;wCAAZ,YAAY;yCAC/F,sBAAsB;mCAD6D,YAAY"}
+{"version":3,"file":"paymentLedger.d.ts","sourceRoot":"","sources":["paymentLedger.js"],"names":[],"mappings":"AAuFO,qCAVkB,CAAC,SAAb,SAAW,cACb,IAAI,QACJ,MAAM,aACN,CAAC,eACD,YAAY,CAAC,CAAC,gBACd,OAAO,qBACP,kBAAkB,2BAClB,mBAAmB,GACjB,cAAc,CAAC,CAAC,CAyT5B;+BA5XwH,YAAY;0BAJ9G,mBAAmB;iCAI+E,YAAY;6BALtG,gBAAgB;wCAK0E,YAAY;yCAF/F,sBAAsB;mCAE6D,YAAY"}

package/src/paymentLedger.js

@@ -2,19 +2,21 @@
 
 /// <reference types="@agoric/store/exported.js" />
 
-import { X, q, Fail, annotateError } from '@endo/errors';
+import { q, Fail, annotateError, X } from '@endo/errors';
 import { isPromise } from '@endo/promise-kit';
-import { mustMatch, M, keyEQ } from '@agoric/store';
+import { mustMatch, M, keyEQ } from '@endo/patterns';
 import { AmountMath } from './amountMath.js';
 import { preparePaymentKind } from './payment.js';
 import { preparePurseKind } from './purse.js';
-
 import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 
 /**
- * @import {Amount, AssetKind, DisplayInfo, PaymentLedger, Payment, Brand, RecoverySetsOption, Purse, Issuer, Mint} from './types.js'
- * @import {ShutdownWithFailure} from '@agoric/swingset-vat'
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {Zone} from '@agoric/base-zone';
  * @import {TypedPattern} from '@agoric/internal';
+ * @import {ShutdownWithFailure} from '@agoric/swingset-vat';
+ * @import {AmountStore} from './amountStore.js';
+ * @import {Amount, AssetKind, DisplayInfo, PaymentLedger, Payment, Brand, RecoverySetsOption, Purse, Issuer, Mint} from './types.js';
  */
 
 /**
@@ -74,7 +76,7 @@ const amountShapeFromElementShape = (brand, assetKind, elementShape) => {
  * minting and transfer authority originates here.
  *
  * @template {AssetKind} K
- * @param {import('@agoric/zone').Zone} issuerZone
+ * @param {Zone} issuerZone
  * @param {string} name
  * @param {K} assetKind
  * @param {DisplayInfo<K>} displayInfo
@@ -239,7 +241,7 @@ export const preparePaymentLedger = (
   /**
    * Used by the purse code to implement purse.deposit
    *
-   * @param {import('./amountStore.js').AmountStore} balanceStore
+   * @param {AmountStore} balanceStore
    * @param {Payment} srcPayment
    * @param {Pattern} [optAmountShape]
    * @returns {Amount}
@@ -273,7 +275,7 @@ export const preparePaymentLedger = (
   /**
    * Used by the purse code to implement purse.withdraw
    *
-   * @param {import('./amountStore.js').AmountStore} balanceStore
+   * @param {AmountStore} balanceStore
    * @param {Amount} amount - the amount to be withdrawn
    * @param {SetStore<Payment>} [recoverySet]
    * @returns {Payment}

package/src/purse.d.ts

@@ -7,14 +7,14 @@ export function preparePurseKind(issuerZone: import("@agoric/zone").Zone, name:
 }, recoverySetsState: RecoverySetsOption, paymentRecoverySets: WeakMapStore<Payment, SetStore<Payment>>): () => import("@endo/exo").Guarded<{
     deposit(srcPayment: any, optAmountShape?: undefined): any;
     withdraw(amount: any): any;
-    getCurrentAmount(): import("./types.js").NatAmount | import("./types.js").CopySetAmount<import("@endo/patterns").Key> | import("./types.js").SetAmount<import("@endo/patterns").Key> | import("./types.js").CopyBagAmount<import("@endo/patterns").Key>;
+    getCurrentAmount(): import("./types.js").NatAmount | import("./types.js").CopySetAmount<import("@endo/patterns").Key> | import("./types.js").CopyBagAmount<import("@endo/patterns").Key> | import("./types.js").SetAmount<import("@endo/patterns").Key>;
     getCurrentAmountNotifier(): import("@agoric/notifier").Notifier<any>;
     getAllegedBrand(): Brand;
     getDepositFacet(): import("@endo/exo").Guarded<{
         receive(...args: any[]): any;
     }>;
     getRecoverySet(): import("@endo/patterns").CopySet<any>;
-    recoverAll(): import("./types.js").NatAmount | import("./types.js").CopySetAmount<import("@endo/patterns").Key> | import("./types.js").SetAmount<import("@endo/patterns").Key> | import("./types.js").CopyBagAmount<import("@endo/patterns").Key>;
+    recoverAll(): import("./types.js").NatAmount | import("./types.js").CopySetAmount<import("@endo/patterns").Key> | import("./types.js").CopyBagAmount<import("@endo/patterns").Key> | import("./types.js").SetAmount<import("@endo/patterns").Key>;
 }>;
 import type { AssetKind } from './types.js';
 import type { Brand } from './types.js';

package/src/ratio.d.ts

@@ -0,0 +1,48 @@
+export function assertIsRatio(ratio: any): void;
+export function makeRatio(numerator: bigint, numeratorBrand: Brand, denominator?: bigint, denominatorBrand?: Brand): Ratio;
+export function makeRatioFromAmounts(numeratorAmount: Amount, denominatorAmount: Amount): Ratio;
+/** @type {ScaleAmount} */
+export const floorMultiplyBy: ScaleAmount;
+/** @type {ScaleAmount} */
+export const ceilMultiplyBy: ScaleAmount;
+/** @type {ScaleAmount} */
+export const multiplyBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, truncating the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const floorDivideBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, rounding up the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const ceilDivideBy: ScaleAmount;
+/**
+ * Divide the amount by the ratio, rounding to nearest with ties to even (aka
+ * Banker's Rounding) as in IEEE 754 default rounding.
+ *
+ * @type {ScaleAmount}
+ */
+export const divideBy: ScaleAmount;
+export function invertRatio(ratio: Ratio): Ratio;
+export function addRatios(left: Ratio, right: Ratio): Ratio;
+export function subtractRatios(left: Ratio, right: Ratio): Ratio;
+export function multiplyRatios(left: Ratio, right: Ratio): Ratio;
+export function oneMinus(ratio: Ratio): Ratio;
+export function ratioGTE(left: Ratio, right: Ratio): boolean;
+export function ratiosSame(left: Ratio, right: Ratio): boolean;
+export function quantize(ratio: Ratio, newDen: bigint): Ratio;
+export function parseRatio(numeric: ParsableNumber, numeratorBrand: Brand<"nat">, denominatorBrand?: Brand<"nat">): Ratio;
+export function assertParsableNumber(specimen: unknown): asserts specimen is ParsableNumber;
+export function ratioToNumber(ratio: Ratio): number;
+export type Ratio = {
+    numerator: Amount<"nat">;
+    denominator: Amount<"nat">;
+};
+export type ScaleAmount = (amount: Amount<"nat">, ratio: Ratio) => Amount<"nat">;
+export type ParsableNumber = bigint | number | string;
+import type { Brand } from '@agoric/ertp';
+import type { Amount } from '@agoric/ertp';
+//# sourceMappingURL=ratio.d.ts.map

package/src/ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratio.d.ts","sourceRoot":"","sources":["ratio.js"],"names":[],"mappings":"AAwDO,gDAcN;AASM,qCANI,MAAM,kBACN,KAAK,gBACL,MAAM,qBACN,KAAK,GACH,KAAK,CAejB;AAOM,sDAJI,MAAM,qBACN,MAAM,GACJ,KAAK,CAYjB;AA2BD,0BAA0B;AAC1B,8BADW,WAAW,CAGpB;AAEF,0BAA0B;AAC1B,6BADW,WAAW,CAGpB;AAEF,0BAA0B;AAC1B,yBADW,WAAW,CAGpB;AA2BF;;;;GAIG;AACH,4BAFU,WAAW,CAInB;AAEF;;;;GAIG;AACH,2BAFU,WAAW,CAInB;AAEF;;;;;GAKG;AACH,uBAFU,WAAW,CAInB;AAMK,mCAHI,KAAK,GACH,KAAK,CAWjB;AAOM,gCAJI,KAAK,SACL,KAAK,GACH,KAAK,CAwBjB;AAOM,qCAJI,KAAK,SACL,KAAK,GACH,KAAK,CAmBjB;AAOM,qCAJI,KAAK,SACL,KAAK,GACH,KAAK,CA8BjB;AAQM,gCAHI,KAAK,GACH,KAAK,CAcjB;AAOM,+BAJI,KAAK,SACL,KAAK,GACH,OAAO,CAkBnB;AAUM,iCAJI,KAAK,SACL,KAAK,GACH,OAAO,CAOnB;AAWM,gCAJI,KAAK,UACL,MAAM,GACJ,KAAK,CAiBjB;AAaM,oCALI,cAAc,kBACd,MAAM,KAAK,CAAC,qBACZ,MAAM,KAAK,CAAC,GACV,KAAK,CAmBjB;AAMM,+CAHI,OAAO,GACL,QAAQ,QAAQ,IAAI,cAAc,CAK9C;AAQM,qCAHI,KAAK,GACH,MAAM,CAMlB;;eAxaa,OAAO,KAAK,CAAC;iBACb,OAAO,KAAK,CAAC;;mCAKhB,OAAO,KAAK,CAAC,SACb,KAAK,KACH,OAAO,KAAK,CAAC;6BAgXZ,MAAM,GAAG,MAAM,GAAG,MAAM;2BAhYkB,cAAc;4BAAd,cAAc"}

package/src/ratio.js

@@ -0,0 +1,441 @@
+import { q, Fail } from '@endo/errors';
+import { assertRecord } from '@endo/marshal';
+import { isNat } from '@endo/nat';
+
+import { AmountMath } from './amountMath.js';
+import { natSafeMath } from './safeMath.js';
+
+/**
+ * @import {Amount, Brand, Issuer, Payment, Purse} from '@agoric/ertp';
+ */
+
+const { multiply, floorDivide, ceilDivide, bankersDivide, add, subtract } =
+  natSafeMath;
+
+/**
+ * @typedef {object} Ratio
+ * @property {Amount<'nat'>} numerator
+ * @property {Amount<'nat'>} denominator
+ */
+
+/**
+ * @callback ScaleAmount
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @returns {Amount<'nat'>}
+ */
+
+// make a Ratio, which represents a fraction. It is a pass-by-copy record.
+//
+// The natural syntax for the most common operations we want to support
+// are Amount * Ratio and Amount / Ratio. Since the operations want to adhere to
+// the ratio rather than the amount, we settled on a calling convention of
+// [ceil|floor]MultiplyBy(Amount, Ratio) and [ceil|floor]DivideBy(Amount, Ratio)
+//
+// The most common kind of Ratio can be applied to Amounts of a particular
+// brand, and produces results of the same brand. This represents a multiplier
+// that is only applicable to that brand. The less common kind of Ratio can be
+// applied to one particular brand of amounts, and produces results of another
+// particular brand. This represents some kind of exchange rate. The
+// brand-checking helps us ensure that normal Ratios aren't applied to amounts
+// of the wrong brand, and that exchange rates are only used in the appropriate
+// direction.
+//
+// Since the ratios are represented by a numerator and a denominator, every
+// multiplication or division operation that produces an amount ends with a
+// division of the underlying bigints, and integer division requires a mode
+// of [rounding to integer](https://en.wikipedia.org/wiki/Rounding#Rounding_to_integer).
+// Because `Ratio` only work with Natural numbers, just three modes suffice:
+//   - floor rounds down
+//   - ceil rounds up
+//   - default (without prefix) minimizes bias by rounding half to even
+
+const PERCENT = 100n;
+
+const ratioPropertyNames = ['numerator', 'denominator'];
+
+export const assertIsRatio = ratio => {
+  assertRecord(ratio, 'ratio');
+  const keys = Object.keys(ratio);
+  keys.length === 2 || Fail`Ratio ${ratio} must be a record with 2 fields.`;
+  for (const name of keys) {
+    ratioPropertyNames.includes(name) ||
+      Fail`Parameter must be a Ratio record, but ${ratio} has ${q(name)}`;
+  }
+  const numeratorValue = ratio.numerator.value;
+  const denominatorValue = ratio.denominator.value;
+  isNat(numeratorValue) ||
+    Fail`The numerator value must be a NatValue, not ${numeratorValue}`;
+  isNat(denominatorValue) ||
+    Fail`The denominator value must be a NatValue, not ${denominatorValue}`;
+};
+
+/**
+ * @param {bigint} numerator
+ * @param {Brand} numeratorBrand
+ * @param {bigint} [denominator] The default denominator is 100
+ * @param {Brand} [denominatorBrand] The default is to reuse the numeratorBrand
+ * @returns {Ratio}
+ */
+export const makeRatio = (
+  numerator,
+  numeratorBrand,
+  denominator = PERCENT,
+  denominatorBrand = numeratorBrand,
+) => {
+  denominator > 0n ||
+    Fail`No infinite ratios! Denominator was 0 ${q(denominatorBrand)}`;
+
+  return harden({
+    numerator: AmountMath.make(numeratorBrand, numerator),
+    denominator: AmountMath.make(denominatorBrand, denominator),
+  });
+};
+
+/**
+ * @param {Amount} numeratorAmount
+ * @param {Amount} denominatorAmount
+ * @returns {Ratio}
+ */
+export const makeRatioFromAmounts = (numeratorAmount, denominatorAmount) => {
+  AmountMath.coerce(numeratorAmount.brand, numeratorAmount);
+  AmountMath.coerce(denominatorAmount.brand, denominatorAmount);
+  return makeRatio(
+    // @ts-expect-error value can be any AmountValue but makeRatio() supports only bigint
+    numeratorAmount.value,
+    numeratorAmount.brand,
+    denominatorAmount.value,
+    denominatorAmount.brand,
+  );
+};
+
+/**
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @param {any} divideOp
+ * @returns {Amount<'nat'>}
+ */
+const multiplyHelper = (amount, ratio, divideOp) => {
+  AmountMath.coerce(amount.brand, amount);
+  assertIsRatio(ratio);
+  amount.brand === ratio.denominator.brand ||
+    Fail`amount's brand ${q(amount.brand)} must match ratio's denominator ${q(
+      ratio.denominator.brand,
+    )}`;
+
+  return /** @type {Amount<'nat'>} */ (
+    AmountMath.make(
+      ratio.numerator.brand,
+      divideOp(
+        multiply(amount.value, ratio.numerator.value),
+        ratio.denominator.value,
+      ),
+    )
+  );
+};
+
+/** @type {ScaleAmount} */
+export const floorMultiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, floorDivide);
+};
+
+/** @type {ScaleAmount} */
+export const ceilMultiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, ceilDivide);
+};
+
+/** @type {ScaleAmount} */
+export const multiplyBy = (amount, ratio) => {
+  return multiplyHelper(amount, ratio, bankersDivide);
+};
+
+/**
+ * @param {Amount<'nat'>} amount
+ * @param {Ratio} ratio
+ * @param {any} divideOp
+ * @returns {Amount<'nat'>}
+ */
+const divideHelper = (amount, ratio, divideOp) => {
+  AmountMath.coerce(amount.brand, amount);
+  assertIsRatio(ratio);
+  amount.brand === ratio.numerator.brand ||
+    Fail`amount's brand ${q(amount.brand)} must match ratio's numerator ${q(
+      ratio.numerator.brand,
+    )}`;
+
+  return /** @type {Amount<'nat'>} */ (
+    AmountMath.make(
+      ratio.denominator.brand,
+      divideOp(
+        multiply(amount.value, ratio.denominator.value),
+        ratio.numerator.value,
+      ),
+    )
+  );
+};
+
+/**
+ * Divide the amount by the ratio, truncating the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const floorDivideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, floorDivide);
+};
+
+/**
+ * Divide the amount by the ratio, rounding up the remainder.
+ *
+ * @type {ScaleAmount}
+ */
+export const ceilDivideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, ceilDivide);
+};
+
+/**
+ * Divide the amount by the ratio, rounding to nearest with ties to even (aka
+ * Banker's Rounding) as in IEEE 754 default rounding.
+ *
+ * @type {ScaleAmount}
+ */
+export const divideBy = (amount, ratio) => {
+  return divideHelper(amount, ratio, bankersDivide);
+};
+
+/**
+ * @param {Ratio} ratio
+ * @returns {Ratio}
+ */
+export const invertRatio = ratio => {
+  assertIsRatio(ratio);
+
+  return makeRatio(
+    ratio.denominator.value,
+    ratio.denominator.brand,
+    ratio.numerator.value,
+    ratio.numerator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const addRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+  left.numerator.brand === right.numerator.brand ||
+    Fail`numerator brands must match: ${q(left)} ${q(right)}`;
+  left.denominator.brand === right.denominator.brand ||
+    Fail`denominator brands must match: ${q(left)} ${q(right)}`;
+
+  // Simplifying the expression:
+  //  (and + bnd) / y d**2
+  //  (a + b) nd / y d**2
+  //  ((a + b) n / y d) * (d / d)
+  //  (a + b) n / yd
+  return makeRatio(
+    add(
+      multiply(left.numerator.value, right.denominator.value), // a nd
+      multiply(left.denominator.value, right.numerator.value), // b nd
+    ), // (a + b) nd
+    left.numerator.brand,
+    multiply(left.denominator.value, right.denominator.value), // y d**2
+    left.denominator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const subtractRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+  left.numerator.brand === right.numerator.brand ||
+    Fail`numerator brands must match: ${q(left)} ${q(right)}`;
+  left.denominator.brand === right.denominator.brand ||
+    Fail`denominator brands must match: ${q(left)} ${q(right)}`;
+
+  return makeRatio(
+    subtract(
+      multiply(left.numerator.value, right.denominator.value), // a nd
+      multiply(left.denominator.value, right.numerator.value), // b nd
+    ), // (a - b) nd
+    left.numerator.brand,
+    multiply(left.denominator.value, right.denominator.value), // y d**2
+    left.denominator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {Ratio}
+ */
+export const multiplyRatios = (left, right) => {
+  assertIsRatio(right);
+  assertIsRatio(left);
+
+  const getRemainingBrands = () => {
+    // Prefer results that have the same brand as the left operand.
+    if (right.numerator.brand === right.denominator.brand) {
+      return [left.numerator.brand, left.denominator.brand];
+    }
+    if (right.numerator.brand === left.denominator.brand) {
+      return [left.numerator.brand, right.denominator.brand];
+    }
+    if (left.numerator.brand === right.denominator.brand) {
+      return [right.numerator.brand, left.denominator.brand];
+    }
+    if (left.numerator.brand === left.denominator.brand) {
+      return [right.numerator.brand, right.denominator.brand];
+    }
+    throw Fail`at least one brand must cancel out: ${q(left)} ${q(right)}`;
+  };
+
+  const [numeratorBrand, denominatorBrand] = getRemainingBrands();
+  return makeRatio(
+    multiply(left.numerator.value, right.numerator.value),
+    numeratorBrand,
+    multiply(left.denominator.value, right.denominator.value),
+    denominatorBrand,
+  );
+};
+
+/**
+ * If ratio is between 0 and 1, subtract from 1.
+ *
+ * @param {Ratio} ratio
+ * @returns {Ratio}
+ */
+export const oneMinus = ratio => {
+  assertIsRatio(ratio);
+  ratio.numerator.brand === ratio.denominator.brand ||
+    Fail`oneMinus only supports ratios with a single brand, but ${ratio.numerator.brand} doesn't match ${ratio.denominator.brand}`;
+  ratio.numerator.value <= ratio.denominator.value ||
+    Fail`Parameter must be less than or equal to 1: ${ratio.numerator.value}/${ratio.denominator.value}`;
+  return makeRatio(
+    subtract(ratio.denominator.value, ratio.numerator.value),
+    ratio.numerator.brand,
+    ratio.denominator.value,
+    ratio.numerator.brand,
+  );
+};
+
+/**
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {boolean}
+ */
+export const ratioGTE = (left, right) => {
+  if (left.numerator.brand === right.numerator.brand) {
+    left.denominator.brand === right.denominator.brand ||
+      Fail`numerator brands match, but denominator brands don't: ${q(left)} ${q(
+        right,
+      )}`;
+  } else if (left.numerator.brand === left.denominator.brand) {
+    right.numerator.brand === right.denominator.brand ||
+      Fail`lefthand brands match, but righthand brands don't: ${q(left)} ${q(
+        right,
+      )}`;
+  }
+  return natSafeMath.isGTE(
+    multiply(left.numerator.value, right.denominator.value),
+    multiply(right.numerator.value, left.denominator.value),
+  );
+};
+
+/**
+ * True iff the ratios are the same values (equal or equivalant may return
+ * false)
+ *
+ * @param {Ratio} left
+ * @param {Ratio} right
+ * @returns {boolean}
+ */
+export const ratiosSame = (left, right) => {
+  return (
+    AmountMath.isEqual(left.numerator, right.numerator) &&
+    AmountMath.isEqual(left.denominator, right.denominator)
+  );
+};
+
+/**
+ * Make a new ratio with a smaller denominator that approximates the ratio. If
+ * the proposed denominator is larger than the current one, return the
+ * original.
+ *
+ * @param {Ratio} ratio
+ * @param {bigint} newDen
+ * @returns {Ratio}
+ */
+export const quantize = (ratio, newDen) => {
+  const oldDen = ratio.denominator.value;
+  const oldNum = ratio.numerator.value;
+  if (newDen > oldDen) {
+    return ratio;
+  }
+
+  const newNum =
+    newDen === oldDen ? oldNum : bankersDivide(oldNum * newDen, oldDen);
+  return makeRatio(
+    newNum,
+    ratio.numerator.brand,
+    newDen,
+    ratio.denominator.brand,
+  );
+};
+
+const NUMERIC_RE = /^(\d\d*)(?:\.(\d*))?$/;
+/** @typedef {bigint | number | string} ParsableNumber */
+
+/**
+ * Create a ratio from a given numeric value.
+ *
+ * @param {ParsableNumber} numeric
+ * @param {Brand<'nat'>} numeratorBrand
+ * @param {Brand<'nat'>} [denominatorBrand]
+ * @returns {Ratio}
+ */
+export const parseRatio = (
+  numeric,
+  numeratorBrand,
+  denominatorBrand = numeratorBrand,
+) => {
+  const match = `${numeric}`.match(NUMERIC_RE);
+  if (!match) {
+    throw Fail`Invalid numeric data: ${numeric}`;
+  }
+
+  const [_, whole, part = ''] = match;
+  return makeRatio(
+    BigInt(`${whole}${part}`),
+    numeratorBrand,
+    10n ** BigInt(part.length),
+    denominatorBrand,
+  );
+};
+
+/**
+ * @param {unknown} specimen
+ * @returns {asserts specimen is ParsableNumber}
+ */
+export const assertParsableNumber = specimen => {
+  const match = `${specimen}`.match(NUMERIC_RE);
+  match || Fail`Invalid numeric data: ${specimen}`;
+};
+
+/**
+ * Ratios might be greater or less than one.
+ *
+ * @param {Ratio} ratio
+ * @returns {number}
+ */
+export const ratioToNumber = ratio => {
+  const n = Number(ratio.numerator.value);
+  const d = Number(ratio.denominator.value);
+  return n / d;
+};

package/src/safeMath.d.ts

@@ -0,0 +1,11 @@
+export namespace natSafeMath {
+    let add: NatOp;
+    let subtract: NatOp;
+    let multiply: NatOp;
+    let floorDivide: NatOp;
+    let ceilDivide: NatOp;
+    let bankersDivide: NatOp;
+    let isGTE: (x: number | bigint, y: number | bigint) => boolean;
+}
+export type NatOp = (x: number | bigint, y: number | bigint) => bigint;
+//# sourceMappingURL=safeMath.d.ts.map

package/src/safeMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeMath.d.ts","sourceRoot":"","sources":["safeMath.js"],"names":[],"mappings":";aAYa,KAAK;kBAGL,KAAK;kBAEL,KAAK;qBAEL,KAAK;oBAEL,KAAK;uBASN,KAAK;eAiBJ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO;;oBA7ClD,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM"}

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/typeGuards.d.ts

@@ -1,6 +1,7 @@
 /**
  * @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;
@@ -85,5 +86,8 @@ 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":"AAGA;;;GAGG;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;2BAvEmC,YAAY;kCAClB,kBAAkB;iCADZ,YAAY"}
+{"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

@@ -4,6 +4,7 @@ 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');