@agoric/wallet-backend 0.13.5 → 0.13.6-dev-800c2bb.0

package/src/marshal-contexts.js

@@ -1,387 +0,0 @@
-// @ts-check
-import { makeScalarMap } from '@agoric/store';
-import { Far, makeMarshal, Remotable } from '@endo/marshal';
-import { HandledPromise } from '@endo/eventual-send'; // TODO: convince tsc this isn't needed
-
-const { details: X, quote: q } = assert;
-
-/**
- * For a value with a known id in the board, we can use
- * that board id as a slot to preserve identity when marshaling.
- *
- * @typedef {`board${Digits}`} BoardId
- */
-
-/**
- * @param {unknown} specimen
- * @returns {specimen is BoardId}
- */
-const isBoardId = specimen => {
-  return typeof specimen === 'string' && !!specimen.match(/^board[^:]/);
-};
-
-/**
- * When marshaling a purse, payment, etc. we partition the slots
- * using prefixes.
- *
- * @template {Record<string, IdTable<*,*>>} T
- * @typedef {`${string & keyof T}:${Digits}`} WalletSlot<T>
- */
-/**
- * @template {string} K
- * @typedef {`${K}:${Digits}`} KindSlot<K>
- */
-
-/**
- * @template {Record<string, IdTable<*,*>>} T
- * @param {T} _tables
- * @param {string & keyof T} kind
- * @param {number} id
- * @returns {WalletSlot<T>}
- */
-const makeWalletSlot = (_tables, kind, id) => {
-  const digits = /** @type {Digits} */ (`${id}`);
-  return `${kind}:${digits}`;
-};
-
-/**
- * @template {Record<string, IdTable<*,*>>} T
- * @param {T} record
- * @param {(value: string, index: number, obj: string[]) => boolean} predicate
- * @returns {string & keyof T | undefined}
- */
-const findKey = (record, predicate) => {
-  const key = Object.keys(record).find(predicate);
-  return key;
-};
-
-/**
- * @template {Record<string, IdTable<*,*>>} T
- * @param {T} tables
- * @param {string} slot
- * @returns {{ kind: undefined | string & keyof T, id: number }}
- */
-const parseWalletSlot = (tables, slot) => {
-  const kind = findKey(tables, k => slot.startsWith(`${k}:`));
-  const id = kind ? Number(slot.slice(kind.length + 1)) : NaN;
-  return { kind, id };
-};
-
-/**
- * Since KindSlots always include a colon and BoardIds never do,
- * we an mix them without confusion.
- *
- * @template {Record<string, IdTable<*,*>>} T
- * @typedef {WalletSlot<T> | BoardId} MixedSlot<T>
- */
-/**
- * @typedef {`1` | `12` | `123`} Digits - 1 or more digits.
- * NOTE: the typescript definition here is more restrictive than
- * actual usage.
- */
-
-/**
- * @template Slot
- * @template Val
- *
- * @typedef {{
- *   bySlot: MapStore<Slot, Val>,
- *   byVal: MapStore<Val, Slot>,
- * }} IdTable<Value>
- */
-
-/**
- * @template Slot
- * @template Val
- * @param {IdTable<Slot, Val>} table
- * @param {Slot} slot
- * @param {Val} val
- */
-const initSlotVal = (table, slot, val) => {
-  table.bySlot.init(slot, val);
-  table.byVal.init(val, slot);
-};
-
-/**
- * Make context for exporting wallet data where brands etc. can be recognized by boardId.
- * Export for use outside the smart wallet.
- *
- * When serializing wallet state for, there's a tension between
- *
- *  - keeping purses etc. closely held
- *  - recognizing identity of brands also referenced in the state of contracts such as the AMM
- *
- * `makeMarshal()` is parameterized by the type of slots. Here we use a disjoint union of
- *   - board ids for widely shared objects
- *   - kind:seq ids for closely held objects; for example purse:123
- */
-export const makeExportContext = () => {
-  const walletObjects = {
-    /** @type {IdTable<number, Purse>} */
-    purse: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-    /** @type {IdTable<number, Payment>} */
-    payment: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-    // TODO: offer, contact, dapp
-    /** @type {IdTable<number, unknown>} */
-    unknown: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-  };
-  /** @type {IdTable<BoardId, unknown>} */
-  const boardObjects = {
-    bySlot: makeScalarMap(),
-    byVal: makeScalarMap(),
-  };
-
-  /**
-   * Look up the slot in mappings from published data
-   * else try walletObjects that we have seen.
-   *
-   * @throws if not found (a slotToVal function typically
-   *         conjures a new identity)
-   *
-   * @param {MixedSlot<typeof walletObjects>} slot
-   * @param {string} _iface
-   */
-  const slotToVal = (slot, _iface) => {
-    if (isBoardId(slot) && boardObjects.bySlot.has(slot)) {
-      return boardObjects.bySlot.get(slot);
-    }
-    const { kind, id } = parseWalletSlot(walletObjects, slot);
-    assert(kind, X`bad slot kind: ${slot}`);
-    const val = walletObjects[kind].bySlot.get(id); // or throw
-    return val;
-  };
-
-  let unknownNonce = 0;
-
-  /**
-   * @param {unknown} val
-   * @returns {MixedSlot<typeof walletObjects>}
-   */
-  const valToSlot = val => {
-    if (boardObjects.byVal.has(val)) {
-      return boardObjects.byVal.get(val);
-    }
-    const kind = findKey(walletObjects, k => walletObjects[k].byVal.has(val));
-    if (kind) {
-      // @ts-expect-error has(val) above ensures val has the right type
-      const id = walletObjects[kind].byVal.get(val);
-      return makeWalletSlot(walletObjects, kind, id);
-    }
-    unknownNonce += 1;
-    const slot = makeWalletSlot(walletObjects, 'unknown', unknownNonce);
-    initSlotVal(walletObjects.unknown, unknownNonce, val);
-    return slot;
-  };
-
-  /**
-   * @template V
-   * @param {string & keyof typeof walletObjects} kind
-   * @param {IdTable<number, V>} table
-   */
-  const makeSaver = (kind, table) => {
-    let nonce = 0;
-    /** @param {V} val */
-    const saver = val => {
-      nonce += 1;
-      initSlotVal(table, nonce, val);
-    };
-    return saver;
-  };
-
-  return harden({
-    savePurseActions: makeSaver('purse', walletObjects.purse),
-    savePaymentActions: makeSaver('payment', walletObjects.payment),
-    /**
-     * @param {number} id
-     * @param {Purse} purse
-     */
-    initPurseId: (id, purse) => {
-      initSlotVal(walletObjects.purse, id, purse);
-    },
-    purseEntries: walletObjects.purse.bySlot.entries,
-    /**
-     * @param {BoardId} id
-     * @param {unknown} val
-     */
-    initBoardId: (id, val) => {
-      initSlotVal(boardObjects, id, val);
-    },
-    /**
-     * @param {BoardId} id
-     * @param {unknown} val
-     */
-    ensureBoardId: (id, val) => {
-      if (boardObjects.byVal.has(val)) {
-        assert.equal(boardObjects.byVal.get(val), id);
-        return;
-      }
-      initSlotVal(boardObjects, id, val);
-    },
-    ...makeMarshal(valToSlot, slotToVal),
-  });
-};
-
-const defaultMakePresence = iface => {
-  const severed = `SEVERED: ${iface.replace(/^Alleged: /, '')}`;
-  return Far(severed, {});
-};
-
-/**
- * Make context for marshalling wallet or board data.
- * To be imported into the client, which never exports objects.
- *
- * @param {(iface: string) => unknown} [makePresence]
- */
-export const makeImportContext = (makePresence = defaultMakePresence) => {
-  const walletObjects = {
-    /** @type {IdTable<number, unknown>} */
-    purse: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-    /** @type {IdTable<number, unknown>} */
-    payment: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-    /** @type {IdTable<number, unknown>} */
-    unknown: {
-      bySlot: makeScalarMap(),
-      byVal: makeScalarMap(),
-    },
-  };
-  /** @type {IdTable<BoardId, unknown>} */
-  const boardObjects = {
-    bySlot: makeScalarMap(),
-    byVal: makeScalarMap(),
-  };
-
-  /**
-   * @template Slot
-   * @template Val
-   * @param {IdTable<Slot, Val>} table
-   * @param {Slot} slot
-   * @param {string} iface
-   */
-  const provideVal = (table, slot, iface) => {
-    if (table.bySlot.has(slot)) {
-      return table.bySlot.get(slot);
-    }
-    const val = makePresence(iface);
-    initSlotVal(table, slot, val);
-    return val;
-  };
-
-  const slotToVal = {
-    /**
-     * @param {string} slot
-     * @param {string} iface
-     */
-    fromBoard: (slot, iface) => {
-      assert(isBoardId(slot), X`bad board slot ${q(slot)}`);
-      return provideVal(boardObjects, slot, iface);
-    },
-
-    /**
-     * @param {string} slot
-     * @param {string} iface
-     */
-    fromMyWallet: (slot, iface) => {
-      if (!slot) {
-        // Empty or null slots are neither in the wallet nor the board.
-        return makePresence(`${slot}`);
-      }
-      const { kind, id } = parseWalletSlot(walletObjects, slot);
-      return kind
-        ? provideVal(walletObjects[kind], id, iface)
-        : slotToVal.fromBoard(slot, iface);
-    },
-  };
-
-  const valToSlot = {
-    fromBoard: val => boardObjects.byVal.get(val),
-    /** @param {unknown} val */
-    fromMyWallet: val => {
-      const kind = findKey(walletObjects, k => walletObjects[k].byVal.has(val));
-      assert(kind, X`cannot serialize unregistered ${val}`);
-
-      const id = walletObjects[kind].byVal.get(val);
-      return makeWalletSlot(walletObjects, kind, id);
-    },
-  };
-
-  const marshal = {
-    fromBoard: makeMarshal(valToSlot.fromBoard, slotToVal.fromBoard, {
-      marshalName: 'fromBoard',
-    }),
-    fromMyWallet: makeMarshal(valToSlot.fromMyWallet, slotToVal.fromMyWallet, {
-      marshalName: 'fromMyWallet',
-    }),
-  };
-
-  return harden({
-    /**
-     * @param {BoardId} id
-     * @param {unknown} val
-     */
-    initBoardId: (id, val) => {
-      initSlotVal(boardObjects, id, val);
-    },
-    /**
-     * @param {BoardId} id
-     * @param {unknown} val
-     */
-    ensureBoardId: (id, val) => {
-      if (boardObjects.byVal.has(val)) {
-        assert.equal(boardObjects.byVal.get(val), id);
-        return;
-      }
-      initSlotVal(boardObjects, id, val);
-    },
-    fromMyWallet: Far('wallet marshaller', { ...marshal.fromMyWallet }),
-    fromBoard: Far('board marshaller', { ...marshal.fromBoard }),
-  });
-};
-
-/**
- * @param {string} iface
- * @param {{
- *   applyMethod: (target: unknown, method: string | symbol, args: unknown[]) => void,
- *   applyFunction: (target: unknown, args: unknown[]) => void,
- * }} handler
- */
-const makePresence = (iface, handler) => {
-  let obj;
-  // eslint-disable-next-line no-new
-  new HandledPromise((resolve, reject, resolveWithPresence) => {
-    obj = resolveWithPresence(handler);
-  });
-  assert(obj);
-  return Remotable(iface, undefined, obj);
-};
-
-/**
- * @param {string} iface
- * @param {(parts: unknown[]) => void} log
- */
-export const makeLoggingPresence = (iface, log) => {
-  /** @type {any} */ // TODO: solve types puzzle
-  const it = makePresence(iface, {
-    applyMethod: (target, method, args) => {
-      log(harden(['applyMethod', target, method, args]));
-    },
-    applyFunction: (target, args) => {
-      log(harden(['applyFunction', target, args]));
-    },
-  });
-  return it;
-};

package/test/attestationExample.js

@@ -1,65 +0,0 @@
-// @ts-check
-import '@agoric/zoe/exported.js';
-import { AmountMath } from '@agoric/ertp';
-import { E } from '@endo/eventual-send';
-import { Far } from '@endo/marshal';
-
-/** @param {ZCF} zcf */
-export const start = async zcf => {
-  const mint = await zcf.makeZCFMint('Attestation');
-  const { brand } = await mint.getIssuerRecord();
-  const callHistory = {
-    /** @type Array<string> */
-    wantProposals: [],
-    /** @type Array<string> */
-    wantAllocations: [],
-    /** @type Array<string> */
-    returnProposals: [],
-    /** @type Array<string> */
-    returnAllocations: [],
-  };
-
-  const mintAttestation = ({ value }) => {
-    const { userSeat, zcfSeat } = zcf.makeEmptySeatKit();
-    mint.mintGains({ Attestation: AmountMath.make(brand, value) }, zcfSeat);
-    zcfSeat.exit();
-    return E(userSeat).getPayout('Attestation');
-  };
-
-  const handleWantAtt = seat => {
-    const proposal = seat.getProposal();
-    callHistory.wantProposals.push(proposal);
-    callHistory.wantAllocations.push(seat.getCurrentAllocation());
-    mint.mintGains(
-      { Attestation: AmountMath.make(brand, proposal.want.Attestation.value) },
-      seat,
-    );
-    seat.exit();
-    return 'good job';
-  };
-
-  const handleReturnAtt = seat => {
-    const proposal = seat.getProposal();
-    callHistory.returnProposals.push(proposal);
-    callHistory.returnAllocations.push(seat.getCurrentAllocation());
-    seat.exit();
-    return 'thank you for that';
-  };
-
-  const makeWantAttInvitation = () =>
-    zcf.makeInvitation(handleWantAtt, 'WantAtt');
-
-  const makeReturnAttInvitation = () =>
-    zcf.makeInvitation(handleReturnAtt, 'ReturnAtt');
-
-  const getCallHistory = () => callHistory;
-
-  const publicFacet = Far('attestation public facet', {
-    mintAttestation,
-    makeWantAttInvitation,
-    makeReturnAttInvitation,
-    getCallHistory,
-  });
-
-  return harden({ publicFacet });
-};

package/test/test-wallet-marshal.js

@@ -1,184 +0,0 @@
-// @ts-check
-import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
-// eslint-disable-next-line import/no-extraneous-dependencies
-import { Far } from '@endo/far';
-import { makeBoard } from '@agoric/vats/src/lib-board.js';
-import { makeHandle } from '@agoric/zoe/src/makeHandle.js';
-import {
-  makeExportContext,
-  makeImportContext,
-} from '../src/marshal-contexts.js';
-
-/** @param {ReturnType<typeof makeBoard>} board */
-const makeAMM = board => {
-  const atom = Far('ATOM brand', {});
-  const pub = board.getPublishingMarshaller();
-  return harden({ getMetrics: () => pub.serialize(harden([atom])) });
-};
-
-/** @param {ReturnType<typeof makeBoard>} board */
-const makeOnChainWallet = board => {
-  const context = makeExportContext();
-  let brand;
-  return harden({
-    suggestIssuer: (name, boardId) => {
-      brand = board.getValue(boardId);
-      const purse = Far(`${name} purse`, {
-        getCurrentAmount: () => harden({ brand, value: 100 }),
-      });
-      // only for private brands
-      //   context.initBrandId(boardId, brand);
-      context.initBoardId(boardId, brand);
-      // @ts-expect-error mock purse
-      context.initPurseId(name, purse); // TODO: strong id rather than name?
-    },
-    publish: () =>
-      context.serialize(
-        harden(
-          [...context.purseEntries()].map(([name, purse], id) => ({
-            meta: { id },
-            // displayInfo
-            // brandBoardId,
-            purse,
-            brand,
-            currentAmount: purse.getCurrentAmount(),
-            // actions
-            brandPetname: name,
-            pursePetname: `${name} purse`,
-          })),
-        ),
-      ),
-  });
-};
-
-test('makeImportContext preserves identity across AMM and wallet', t => {
-  const context = makeImportContext();
-
-  const board = makeBoard(0, { prefix: 'board' });
-  const amm = makeAMM(board);
-  const ammMetricsCapData = amm.getMetrics();
-
-  t.deepEqual(ammMetricsCapData, {
-    body: JSON.stringify([
-      { '@qclass': 'slot', iface: 'Alleged: ATOM brand', index: 0 },
-    ]),
-    slots: ['board011'],
-  });
-
-  /** @type {Brand[]} */
-  const [b1] = context.fromBoard.unserialize(ammMetricsCapData);
-  /** @type {Brand[]} */
-  const [b2] = context.fromBoard.unserialize(amm.getMetrics());
-  t.is(b1, b2, 'unserialization twice from same source');
-
-  const myWallet = makeOnChainWallet(board);
-  myWallet.suggestIssuer('ATOM', 'board011');
-  const walletCapData = myWallet.publish();
-  t.deepEqual(walletCapData, {
-    body: JSON.stringify([
-      {
-        brand: { '@qclass': 'slot', iface: 'Alleged: ATOM brand', index: 0 },
-        brandPetname: 'ATOM',
-        currentAmount: { brand: { '@qclass': 'slot', index: 0 }, value: 100 },
-        meta: { id: 0 },
-        purse: { '@qclass': 'slot', iface: 'Alleged: ATOM purse', index: 1 },
-        pursePetname: 'ATOM purse',
-      },
-    ]),
-    slots: ['board011', 'purse:ATOM'],
-  });
-
-  const walletState = context.fromMyWallet.unserialize(walletCapData);
-  t.is(walletState[0].brand, b1, 'unserialization across sources');
-
-  t.throws(
-    () => context.fromBoard.unserialize(walletCapData),
-    { message: /bad board slot/ },
-    'AMM cannot refer to purses',
-  );
-
-  t.throws(
-    () => context.fromMyWallet.serialize(Far('widget', {})),
-    {
-      message: /unregistered/,
-    },
-    'import context never exports unregistered objects',
-  );
-});
-
-test('ensureBoardId allows re-registration; initBoardId does not', t => {
-  const brandM = Far('Moola brand', {});
-  const brandS = Far('Semolean brand', {});
-
-  const context = makeExportContext();
-  context.initBoardId('board1', brandM);
-  t.throws(() => context.initBoardId('board1', brandM));
-  context.ensureBoardId('board1', brandM);
-  t.throws(() => context.ensureBoardId('board12', brandM));
-  context.ensureBoardId('board12', brandS);
-  t.throws(() => context.initBoardId('board12', brandM));
-});
-
-test('makeExportContext.serialize handles unregistered identites', t => {
-  const brand = Far('Zoe invitation brand', {});
-  const instance = Far('amm instance', {});
-  const invitationAmount = harden({ brand, value: [{ instance }] });
-
-  const context = makeExportContext();
-  context.initBoardId('board1', brand);
-  const actual = context.serialize(invitationAmount);
-
-  t.deepEqual(actual, {
-    body: JSON.stringify({
-      brand: {
-        '@qclass': 'slot',
-        iface: 'Alleged: Zoe invitation brand',
-        index: 0,
-      },
-      value: [
-        {
-          instance: {
-            '@qclass': 'slot',
-            iface: 'Alleged: amm instance',
-            index: 1,
-          },
-        },
-      ],
-    }),
-    slots: ['board1', 'unknown:1'],
-  });
-
-  t.deepEqual(context.unserialize(actual), invitationAmount);
-
-  const myPayment = /** @type {Payment} */ (
-    Far('payment', { getAllegedBrand: () => assert.fail('no impl') })
-  );
-  context.savePaymentActions(myPayment);
-  const cap2 = context.serialize(myPayment);
-  t.deepEqual(cap2, {
-    body: JSON.stringify({
-      '@qclass': 'slot',
-      iface: 'Alleged: payment',
-      index: 0,
-    }),
-    slots: ['payment:1'],
-  });
-  t.deepEqual(context.unserialize(cap2), myPayment);
-});
-
-test('fromBoard.serialize requires board ids', t => {
-  const context = makeImportContext();
-
-  const unpassable = harden({
-    instance: makeHandle('Instance'),
-  });
-  t.throws(() => context.fromBoard.serialize(unpassable), {
-    message: '"key" not found: "[Alleged: InstanceHandle]"',
-  });
-
-  context.ensureBoardId('board123', unpassable.instance);
-  t.deepEqual(context.fromBoard.serialize(unpassable), {
-    body: '{"instance":{"@qclass":"slot","iface":"Alleged: InstanceHandle","index":0}}',
-    slots: ['board123'],
-  });
-});