@agoric/deploy-script-support 0.10.4-dev-fe77bfe.0.fe77bfe → 0.10.4-dev-6ce1cfd.0.6ce1cfd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-dev-fe77bfe.0.fe77bfe",
+  "version": "0.10.4-dev-6ce1cfd.0.6ce1cfd",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
@@ -34,25 +34,33 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/ertp": "0.16.3-dev-fe77bfe.0.fe77bfe",
-    "@agoric/import-manager": "0.3.12-dev-fe77bfe.0.fe77bfe",
-    "@agoric/internal": "0.3.3-dev-fe77bfe.0.fe77bfe",
-    "@agoric/notifier": "0.6.3-dev-fe77bfe.0.fe77bfe",
-    "@agoric/pola-io": "0.1.1-dev-fe77bfe.0.fe77bfe",
-    "@agoric/store": "0.9.3-dev-fe77bfe.0.fe77bfe",
-    "@agoric/time": "0.3.3-dev-fe77bfe.0.fe77bfe",
-    "@agoric/zoe": "0.26.3-dev-fe77bfe.0.fe77bfe",
+    "@agoric/client-utils": "0.1.1-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/ertp": "0.16.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/import-manager": "0.3.12-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/internal": "0.3.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/notifier": "0.6.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/orchestration": "0.1.1-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/pola-io": "0.1.1-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/portfolio-api": "0.1.1-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/smart-wallet": "0.5.4-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/store": "0.9.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/time": "0.3.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/zoe": "0.26.3-dev-6ce1cfd.0.6ce1cfd",
+    "@agoric/zone": "0.2.3-dev-6ce1cfd.0.6ce1cfd",
     "@endo/base64": "^1.0.12",
     "@endo/bundle-source": "^4.1.2",
     "@endo/errors": "^1.2.13",
+    "@endo/eventual-send": "^1.3.4",
     "@endo/far": "^1.1.14",
     "@endo/marshal": "^1.8.0",
     "@endo/nat": "^5.1.3",
+    "@endo/pass-style": "^1.6.3",
+    "@endo/patterns": "^1.7.0",
     "@endo/promise-kit": "^1.1.13",
     "@endo/zip": "^1.0.11"
   },
   "devDependencies": {
-    "@agoric/vats": "0.15.2-dev-fe77bfe.0.fe77bfe",
+    "@agoric/vats": "0.15.2-dev-6ce1cfd.0.6ce1cfd",
     "@endo/init": "^1.1.12",
     "ava": "^6.4.1",
     "import-meta-resolve": "^4.1.0"
@@ -75,5 +83,5 @@
   "typeCoverage": {
     "atLeast": 84.46
   },
-  "gitHead": "fe77bfe6dd676c5538e17e61cb618750f0f5aac0"
+  "gitHead": "6ce1cfd05fd9608126491636eb6658078d91cba9"
 }

package/src/control/attenuated-deposit.core.js

@@ -0,0 +1,55 @@
+/**
+ * @file Get a promise for a deposit facet without
+ * access to all of namesByAddressAdmin.
+ */
+
+import { E } from '@endo/eventual-send';
+
+const trace = (...args) => console.log('---- AttD', ...args);
+
+/**
+ * @import {DepositFacet} from '@agoric/ertp';
+ * @import {BootstrapPowers, PromiseSpaceOf} from '@agoric/vats/src/core/types.js';
+ */
+const depositFacetKey = 'depositFacet';
+
+/**
+ * XXX move this into BootstrapPowers
+ * @typedef {PromiseSpaceOf<{
+ *   getDepositFacet: (addr: string, debugName?: string) => Promise<DepositFacet>
+ * }>} AttenuatedDepositPowers
+ */
+
+/**
+ * @param {BootstrapPowers & AttenuatedDepositPowers} powers
+ */
+export const produceAttenuatedDeposit = powers => {
+  powers.produce.getDepositFacet.reset();
+  const { namesByAddress, namesByAddressAdmin } = powers.consume;
+
+  /**
+   *
+   * @param {string} addr
+   * @param {string} [debugName]
+   */
+  const getDepositFacet = async (addr, debugName = 'party') => {
+    trace('reserve nameHub for', debugName, addr);
+    await E(namesByAddressAdmin).reserve(addr);
+    trace('lookup depositFacet for', debugName, addr);
+    const df = await E(namesByAddress).lookup(addr, depositFacetKey);
+    trace('got depositFacet for', debugName, addr);
+    return df;
+  };
+  harden(getDepositFacet);
+
+  powers.produce.getDepositFacet.resolve(getDepositFacet);
+};
+
+export const getManifestForAttenuatedDeposit = () => ({
+  manifest: {
+    [produceAttenuatedDeposit.name]: {
+      consume: { namesByAddress: true, namesByAddressAdmin: true },
+      produce: { getDepositFacet: true },
+    },
+  },
+});

package/src/control/chain-info.core.js

@@ -0,0 +1,187 @@
+import { makeTracer } from '@agoric/internal';
+import { registerChain } from '@agoric/orchestration/src/chain-info.js';
+import { Fail } from '@endo/errors';
+import { E, Far } from '@endo/far';
+import { makeMarshal } from '@endo/marshal';
+
+// TODO: refactor overlap with init-chain-info.js in orch pkg
+
+/**
+ * @import {Remote, ERemote} from '@agoric/internal';
+ * @import {ChainInfo} from '@agoric/orchestration';
+ * @import {NameHub, NameAdmin} from '@agoric/vats';
+ * @typedef {Record<string, { chainInfo: ChainInfo }>} AxelarChainConfigMap
+ * @import {ERef} from '@endo/eventual-send';
+ * @import {StorageNode} from '@agoric/internal/src/lib-chainStorage.js';
+ * @import {PromiseSpaceOf} from '@agoric/vats/src/core/types.js';
+ * @import {BootstrapPowers} from '@agoric/vats/src/core/types.js';
+ */
+
+const trace = makeTracer('ChainInfoCore', true);
+
+// chainInfo has no cap data but we need to marshal bigints
+const marshalData = makeMarshal(_val => Fail`data only`);
+
+// See also: exos/chain-hub. Consistency is enforced by test.
+export const HubName = {
+  Chain: 'chain',
+  ChainConnection: 'chainConnection',
+  ChainAssets: 'chainAssets',
+};
+
+/**
+ * Similar to publishAgoricNamesToChainStorage but publishes a node per chain
+ * instead of one list of entries
+ */
+
+/**
+ * For each HubName, provide a NameHubKit reflected into vstorage unless there's
+ * already an agorcNames key by that name.
+ *
+ * @param {ERef<NameAdmin>} agoricNamesAdmin
+ * @param {ERemote<StorageNode>} agoricNamesNode
+ * @param {ERef<NameHub>} agoricNames
+ */
+const publishChainInfoToChainStorage = async (
+  agoricNamesAdmin,
+  agoricNamesNode,
+  agoricNames,
+) => {
+  /**
+   * @param {string} subpath
+   */
+  const echoNameUpdates = async subpath => {
+    trace('reflecting', subpath, 'from agoricNames to vstorage');
+    const chainNamesNode = E(agoricNamesNode).makeChildNode(subpath);
+    const { nameAdmin } = await E(agoricNamesAdmin).provideChild(subpath);
+
+    /**
+     * Previous entries, to prevent redundant updates
+     *
+     * @type {Record<string, string>} chainName => stringified chainInfo
+     */
+    const prev = {};
+
+    // XXX cannot be changed until we upgrade vat-agoricNames to allow it
+    await E(nameAdmin).onUpdate(
+      // XXX will live on the heap in the bootstrap vat. When we upgrade or kill
+      // that this handler will sever and vat-agoricNames will need to be upgraded
+      // to allow changing the handler, or to use pubsub mechanics instead.
+      Far('chain info writer', {
+        write(entries) {
+          for (const [chainName, info] of entries) {
+            const value = JSON.stringify(marshalData.toCapData(info));
+            if (prev[chainName] === value) {
+              continue;
+            }
+            const chainNode = E(chainNamesNode).makeChildNode(chainName);
+            prev[chainName] = value;
+            void E(chainNode)
+              .setValue(value)
+              .catch(() => delete prev[chainName]);
+          }
+        },
+      }),
+    );
+  };
+  const existingKeys = await E(agoricNames).keys();
+  await Promise.all(
+    Object.values(HubName)
+      .filter(k => !existingKeys.includes(k))
+      .map(echoNameUpdates),
+  );
+};
+
+/**
+ * null chainStorage case is vestigial
+ *
+ * @typedef {{ consume: { chainStorage: Promise<Remote<StorageNode>> } }} ChainStoragePresent
+ */
+
+/**
+ * XXX move this into BootstrapPowers
+ * @typedef {PromiseSpaceOf<{
+ *   chainInfoPublished: unknown
+ * }>} ChainInfoPowers
+ */
+
+/**
+ * WARNING: prunes any data that was previously published
+ *
+ * @param {BootstrapPowers & ChainStoragePresent & ChainInfoPowers} powers
+ * @param {{
+ *   options: {
+ *     chainInfo?: Record<string, ChainInfo>;
+ *     axelarConfig: AxelarChainConfigMap;
+ *   };
+ * }} config
+ */
+export const publishChainInfo = async (
+  {
+    consume: { agoricNames, agoricNamesAdmin, chainStorage },
+    produce: { chainInfoPublished },
+  },
+  config,
+) => {
+  const { keys } = Object;
+  const { chainInfo = {} } = config.options;
+  trace('publishChainInfo', keys(chainInfo));
+
+  const agoricNamesNode = E(chainStorage).makeChildNode('agoricNames');
+
+  // Ensure updates go to vstorage
+  await publishChainInfoToChainStorage(
+    agoricNamesAdmin,
+    agoricNamesNode,
+    agoricNames,
+  );
+
+  for (const kind of Object.values(HubName)) {
+    const hub = E(agoricNames).lookup(kind);
+    /** @type {string[]} */
+    const oldKeys = await E(hub).keys();
+    trace('clearing old', kind, oldKeys);
+    if (!oldKeys.length) continue;
+
+    const admin = E(agoricNamesAdmin).lookupAdmin(kind);
+    await Promise.all(oldKeys.map(k => E(admin).delete(k)));
+    const node = E(agoricNamesNode).makeChildNode(kind);
+    // XXX setValue('') deletes a vstorage key (right?)
+    await Promise.all(
+      oldKeys.map(k =>
+        E(E(node).makeChildNode(k, { sequence: false })).setValue(''),
+      ),
+    );
+  }
+
+  const handledConnections = new Set();
+  for await (const [name, info] of Object.entries(chainInfo)) {
+    await registerChain(
+      agoricNamesAdmin,
+      name,
+      info,
+      trace,
+      handledConnections,
+    );
+    trace('@@@registered', name, info);
+  }
+  trace('@@@conn', ...handledConnections);
+
+  chainInfoPublished.resolve(true);
+  trace('publishChainInfo done');
+};
+harden(publishChainInfo);
+
+export const getManifestForChainInfo = (_u, { options }) => ({
+  manifest: {
+    [publishChainInfo.name]: {
+      consume: {
+        agoricNames: true,
+        agoricNamesAdmin: true,
+        chainStorage: true,
+      },
+      produce: { chainInfoPublished: true },
+    },
+  },
+  options,
+});

package/src/control/contract-control.build.js

@@ -0,0 +1,27 @@
+/**
+ * @import { CoreEvalBuilder, DeployScriptFunction } from '@agoric/deploy-script-support/src/externalTypes.js';
+ */
+
+import { makeHelpers } from '../helpers.js';
+import { getManifestForDeliverContractControl } from './contract-control.core.js';
+
+const sourceSpec = './contract-control.core.js';
+
+/**
+ * @satisfies {CoreEvalBuilder}
+ */
+const defaultProposalBuilder = async () => {
+  return harden({
+    sourceSpec,
+    getManifestCall: [getManifestForDeliverContractControl.name],
+  });
+};
+
+/** @type {DeployScriptFunction} */
+const build = async (homeP, endowments) => {
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+
+  await writeCoreEval('eval-contract-control', () => defaultProposalBuilder());
+};
+harden(build);
+export default build;

package/src/control/contract-control.contract.js

@@ -0,0 +1,386 @@
+/**
+ * @file contract-control: install, upgrade, terminate, reset chain-storage,
+ * for a contract in a branch of agoricNames / chain-storage.
+ */
+
+import { makeTracer } from '@agoric/internal/src/debug.js';
+import { Fail, q } from '@endo/errors';
+import { E, passStyleOf } from '@endo/far';
+import { M, objectMap } from '@endo/patterns';
+
+const trace = makeTracer('CCtrl');
+
+/**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {ContractStartFunction, StartResult} from '@agoric/zoe/src/zoeService/utils.js';
+ * @import {Installation, Instance, IssuerKeywordRecord, ZoeService} from '@agoric/zoe';
+ * @import {Remote} from '@agoric/internal';
+ * @import {StorageNode} from '@agoric/internal/src/lib-chainStorage.js';
+ * @import {Board, NameHubKit} from '@agoric/vats';
+ * @import {ERef} from '@agoric/vow';
+ * @import {StartedInstanceKitWithLabel, StartUpgradable} from '@agoric/vats/src/core/types.js';
+ * @import {StartedInstanceKit} from '@agoric/vats/src/core/types.js';
+ */
+
+/**
+ * @typedef {<SF extends ContractStartFunction>(instance: Instance<SF>, privateArgs: Parameters<SF>[1]) => void} UpdatePrivateArgs
+ */
+
+const IssuerShape = M.remotable('Issuer');
+const InstallationShape = M.remotable('Installation');
+const PublicParts = harden({
+  label: M.string(),
+  instance: M.remotable('Instance'),
+  publicFacet: M.remotable('publicFacet'),
+});
+const BundleIdShape = M.string();
+const VatUpgradeResultsShape = M.splitRecord({ incarnationNumber: M.number() });
+const IssuersShape = M.recordOf(M.string(), IssuerShape);
+const PrivateArgsOverridesShape = M.record();
+
+const iface = M.interface('ContractControl', {
+  install: M.callWhen(M.string()).returns({
+    boardId: M.string(),
+    installation: InstallationShape,
+  }),
+  start: M.callWhen(
+    M.splitRecord(
+      { installation: InstallationShape },
+      {
+        issuers: IssuersShape,
+        privateArgsOverrides: PrivateArgsOverridesShape,
+      },
+      {}, // Refuse unsupported options
+    ),
+  ).returns(PublicParts),
+  installAndStart: M.callWhen(
+    M.splitRecord(
+      { bundleId: BundleIdShape },
+      {
+        issuers: IssuersShape,
+        privateArgsOverrides: PrivateArgsOverridesShape,
+      },
+      {}, // Refuse unsupported options
+    ),
+  ).returns(PublicParts),
+  getPublicFacet: M.call().returns(M.remotable('publicFacet')),
+  getCreatorFacet: M.call().returns(M.remotable('creatorFacet')),
+  upgrade: M.callWhen(
+    M.or(
+      BundleIdShape, // Backward compat with old signature
+      M.splitRecord(
+        { bundleId: BundleIdShape },
+        {
+          privateArgsOverrides: PrivateArgsOverridesShape,
+        },
+        {}, // Refuse unsupported options
+      ),
+    ),
+  ).returns(VatUpgradeResultsShape),
+  terminate: M.callWhen()
+    .optional(
+      M.splitRecord(
+        {},
+        { message: M.string(), target: M.string(), revoke: M.boolean() },
+        {}, // Refuse unsupported options
+      ),
+    )
+    .returns(),
+  pruneChainStorage: M.callWhen(
+    M.recordOf(M.string(), M.arrayOf(M.string())),
+  ).returns(M.number()),
+  revoke: M.call().returns(),
+});
+
+/**
+ * @param {Zone} zone
+ * @param {{
+ *   agoricNamesAdmin: ERef<NameHubKit['nameAdmin']>,
+ *   board: ERef<Board>,
+ *   zoe: ERef<ZoeService>,
+ *   startUpgradable: ERef<StartUpgradable>,
+ *   updatePrivateArgs: ERef<UpdatePrivateArgs>
+ * }} svcs
+ */
+export const prepareContractControl = (zone, svcs) => {
+  /** @template {ContractStartFunction} SF */
+  const makeMaker = () =>
+    zone.exoClass(
+      'ContractControl',
+      iface,
+      /**
+       * Install by bundleId and publish to (the board and) agoricNames,
+       * replacing anything that was there before.
+       *
+       * Former installations can be reached from the board.
+       *
+       * @param {ContractControlOpts} initial
+       */
+      initial => ({
+        initialPrivateArgs:
+          initial.initialPrivateArgs || initial.kit?.privateArgs,
+        kit: undefined,
+        ...initial,
+        revoked: false,
+      }),
+      {
+        /** @param {string} bundleId */
+        async install(bundleId) {
+          const { name, revoked } = this.state;
+          trace(name, 'install', bundleId);
+          !revoked || Fail`revoked`;
+          const { zoe, board, agoricNamesAdmin } = svcs;
+          const installation = await E(zoe).installBundleID(bundleId);
+          const installationAdmin =
+            E(agoricNamesAdmin).lookupAdmin('installation');
+          await E(installationAdmin).update(name, installation);
+          const boardId = await E(board).getId(installation);
+          trace(name, 'installed', { bundleId, installation, boardId });
+          return { boardId, installation };
+        },
+
+        /**
+         * Start the contract; publish the instance to (the board and) agoricNames.
+         *
+         * @throws if already running
+         * @param {object} opts
+         * @param {Installation<SF>} opts.installation
+         * @param {IssuerKeywordRecord} [opts.issuers]
+         * @param {Partial<Parameters<SF>[1]>} [opts.privateArgsOverrides]
+         */
+        async start({ installation, issuers, privateArgsOverrides }) {
+          const { name, storageNode, revoked, initialPrivateArgs } = this.state;
+          !revoked || Fail`revoked`;
+          !this.state.kit || Fail`${name} already started`;
+          const { startUpgradable, board } = svcs;
+          const installationId = await E(board).getId(installation);
+          trace(name, 'startUpgradable', { installation, installationId });
+          const privateArgs = harden({
+            ...initialPrivateArgs,
+            storageNode,
+            ...privateArgsOverrides,
+          });
+          const kit = await E(startUpgradable)({
+            label: name,
+            installation,
+            issuerKeywordRecord: issuers,
+            //   terms: customTerms,
+            privateArgs,
+          });
+          /** @type {StartedInstanceKitWithLabel<SF>} */
+          const fullKit = harden({ ...kit, privateArgs });
+          trace(name, 'started', objectMap(fullKit, passStyleOf));
+          this.state.kit = fullKit;
+
+          const { agoricNamesAdmin } = svcs;
+          const instanceAdmin = E(agoricNamesAdmin).lookupAdmin('instance');
+          await E(instanceAdmin).update(name, kit.instance);
+          const boardId = await E(board).getId(kit.instance);
+          trace(name, 'published', { boardId, installationId });
+
+          return harden({
+            label: name,
+            instance: kit.instance,
+            publicFacet: kit.publicFacet,
+          });
+        },
+
+        /**
+         * @param {object} opts
+         * @param {string} opts.bundleId
+         * @param {IssuerKeywordRecord} [opts.issuers]
+         * @param {Partial<Parameters<SF>[1]>} [opts.privateArgsOverrides]
+         */
+        async installAndStart({ bundleId, issuers, privateArgsOverrides }) {
+          trace(this.state.name, 'installAndStart');
+          !this.state.revoked || Fail`revoked`;
+          const { self } = this;
+          const { installation } = await self.install(bundleId);
+          return self.start({
+            installation,
+            issuers,
+            privateArgsOverrides,
+          });
+        },
+
+        /** @returns {StartResult<SF>['publicFacet']} */
+        getPublicFacet() {
+          const { name, revoked, kit } = this.state;
+          trace(name, 'getPublicFacet');
+          !revoked || Fail`revoked`;
+          if (!kit) throw Fail`${q(name)}: no StartedInstanceKit`;
+          return kit.publicFacet;
+        },
+
+        /** @returns {StartResult<SF>['creatorFacet']} */
+        getCreatorFacet() {
+          const { name, revoked, kit } = this.state;
+          trace(name, 'getCreatorFacet');
+          !revoked || Fail`revoked`;
+          if (!kit) throw Fail`${q(name)}: no StartedInstanceKit`;
+          return kit.creatorFacet;
+        },
+
+        /** @param {string | {bundleId: string; privateArgsOverrides?: Partial<Parameters<SF>[1]>; }} opts */
+        async upgrade(opts) {
+          if (typeof opts === 'string') opts = { bundleId: opts };
+          const { bundleId, privateArgsOverrides = {} } = opts;
+
+          const { updatePrivateArgs } = svcs;
+
+          const { name, revoked, kit, initialPrivateArgs } = this.state;
+          trace(name, 'upgrade', bundleId);
+          !revoked || Fail`revoked`;
+          if (!kit) throw Fail`${q(name)}: no StartedInstanceKit`;
+          const { privateArgs: previousPrivateArgs } = kit;
+          const privateArgs = {
+            ...initialPrivateArgs,
+            ...previousPrivateArgs,
+            ...privateArgsOverrides,
+          };
+          const result = await E(kit.adminFacet).upgradeContract(
+            bundleId,
+            privateArgs,
+          );
+          const newKit = harden({ ...kit, privateArgs });
+          trace(name, 'upgrade result', result);
+          this.state.kit = newKit;
+          await E(updatePrivateArgs)(kit.instance, privateArgs);
+          return result;
+        },
+
+        /**
+         * @param {object} opts
+         * @param {string} [opts.target] boardId to confirm is current
+         * @param {string} [opts.message] for termination error
+         * @param {boolean} [opts.revoke] neuter this object
+         */
+        async terminate(opts = {}) {
+          const { name, kit, revoked } = this.state;
+          trace(name, 'terminate', kit?.adminFacet, opts);
+          !revoked || Fail`revoked`;
+          const { target, message = 'terminated', revoke } = opts;
+          if (!kit) {
+            if (revoke) {
+              trace(name, 'revoked');
+              this.state.revoked = true;
+              return;
+            }
+            throw Fail`${q(name)}: no StartedInstanceKit`;
+          }
+
+          await null;
+          if (target) {
+            const current = await E(svcs.board).getId(kit.instance);
+            assert.equal(current, target);
+          }
+
+          try {
+            await E(kit.adminFacet).terminateContract(harden(Error(message)));
+          } catch (err) {
+            console.error('terminateContract failed; forgetting kit', err);
+          }
+          this.state.kit = undefined;
+          if (revoke) {
+            trace(name, 'revoked');
+            this.state.revoked = true;
+          }
+          const { agoricNamesAdmin } = svcs;
+          const instanceAdmin = E(agoricNamesAdmin).lookupAdmin('instance');
+          await E(instanceAdmin).delete(name);
+        },
+
+        /** @param {Record<string, string[]>} parentToChildren */
+        async pruneChainStorage(parentToChildren) {
+          const { name, storageNode, revoked } = this.state;
+          trace(
+            name,
+            'pruneChainStorage',
+            Object.keys(parentToChildren).length,
+          );
+          !revoked || Fail`revoked`;
+
+          /** @param {string[]} path */
+          const makePathNode = path => {
+            /** @type {Promise<Remote<StorageNode>>} */
+            let node = Promise.resolve(storageNode);
+            for (const segment of path) {
+              node = E(node).makeChildNode(segment);
+            }
+            return node;
+          };
+
+          const prefix = await E(storageNode).getPath();
+          for (const parent of Object.keys(parentToChildren)) {
+            parent.startsWith(prefix) ||
+              Fail`${parent} must start with ${prefix}`;
+          }
+
+          let qty = 0;
+          for (const [parent, children] of Object.entries(parentToChildren)) {
+            trace(name, 'pruning', parent, children);
+            const suffix = parent.slice(prefix.length + '.'.length);
+            const segments = suffix ? suffix.split('.') : [];
+            const parentNode = makePathNode(segments);
+            // on failure, trace rather than aborting the whole job
+            await Promise.allSettled(
+              children.map(async k => {
+                await null;
+                try {
+                  await E(
+                    E(parentNode).makeChildNode(k, { sequence: false }),
+                  ).setValue('');
+                  qty += 1;
+                } catch (err) {
+                  trace('rejected:', parent, k, err);
+                }
+              }),
+            );
+          }
+          trace('done');
+          return qty;
+        },
+
+        revoke() {
+          const { name, kit, revoked } = this.state;
+          trace(name, 'revoke', kit?.adminFacet);
+          !revoked || Fail`revoked`;
+
+          trace(name, 'revoked');
+          this.state.revoked = true;
+        },
+      },
+    );
+
+  /**
+   * @template {ContractStartFunction} [SF=ContractStartFunction]
+   * @typedef {ReturnType<ReturnType<typeof makeMaker<SF>>>} ContractControl
+   */
+
+  /** @type {<SF extends ContractStartFunction>(initial: ContractControlOpts<SF>) => ContractControl<SF>} */
+  const makeContractControl = makeMaker();
+
+  return makeContractControl;
+};
+harden(prepareContractControl);
+
+/**
+ * @template {ContractStartFunction} [SF=ContractStartFunction]
+ * @typedef {object} ContractControlOpts
+ * @property {string} name contractName
+ * @property {Remote<StorageNode>} storageNode
+ * @property {StartedInstanceKit<SF> & { privateArgs?: Parameters<SF>[1] }} [kit]
+ * @property {Partial<Parameters<SF>[1]>} [initialPrivateArgs]
+ */
+
+/** @typedef {ReturnType<typeof prepareContractControl>} MakeContractControl */
+
+// Hack to allow extracting the generic result of MakeContractControl
+// See https://github.com/microsoft/TypeScript/issues/62524
+// eslint-disable-next-line
+const maker = /** @type {MakeContractControl} */ (
+  /** @type {unknown} */ (undefined)
+);
+harden(maker);
+
+/** @template {ContractStartFunction} [SF=ContractStartFunction] @typedef {ReturnType<typeof maker<SF>>} ContractControl */

package/src/control/contract-control.core.js

@@ -0,0 +1,138 @@
+/** @file core eval to deliver control of a contract to a smartWallet */
+
+import { makeTracer } from '@agoric/internal/src/debug.js';
+import { makeHeapZone } from '@agoric/zone';
+import { Fail } from '@endo/errors';
+import { E } from '@endo/eventual-send';
+import { YMAX_CONTROL_WALLET_KEY } from '@agoric/portfolio-api/src/portfolio-constants.js';
+import { prepareContractControl } from './contract-control.contract.js';
+
+/**
+ * @import {ContractStartFunction} from '@agoric/zoe/src/zoeService/utils.js';
+ * @import {ChainStoragePresent} from './chain-info.core.js'
+ * @import {PostalServiceBoot} from './postal-service.core.js';
+ * @import {AttenuatedDepositPowers} from './attenuated-deposit.core.js';
+ * @import {ContractControlOpts, ContractControl, UpdatePrivateArgs} from './contract-control.contract.js';
+ * @import {PromiseSpaceOf} from '@agoric/vats/src/core/types.js';
+ * @import {BootstrapPowers} from '@agoric/vats/src/core/types.js';
+ */
+
+/**
+ * @template {ContractStartFunction} SF
+ * @typedef {Omit<ContractControlOpts<SF>, 'storageNode'> & {controlAddress: string}} ContractControlDeliverOpts
+ */
+
+/**
+ * @typedef {<SF extends ContractStartFunction>(opts: ContractControlDeliverOpts<SF>) => Promise<{delivered: Promise<void>, contractControl: ContractControl<SF>}>} DeliverContractControl
+ */
+
+/**
+ * @typedef {PromiseSpaceOf<{ deliverContractControl: DeliverContractControl}>} ContractControlPowers
+ */
+
+/**
+ * @param {BootstrapPowers &
+ *  ChainStoragePresent &
+ *  PostalServiceBoot &
+ *  ContractControlPowers &
+ *  AttenuatedDepositPowers
+ * } permitted
+ */
+export const produceDeliverContractControl = async permitted => {
+  permitted.produce.deliverContractControl.reset();
+  await null;
+
+  const { consume } = permitted;
+
+  const { chainStorage, getDepositFacet, zoe } = consume;
+
+  const instancePrivateArgs = await consume.instancePrivateArgs;
+
+  const postalSvcPub = E.when(
+    permitted.instance.consume.postalService,
+    instance => E(zoe).getPublicFacet(instance),
+  );
+
+  /** @type {UpdatePrivateArgs} */
+  const updatePrivateArgs = (instance, privateArgs) => {
+    if (!instancePrivateArgs.has(instance)) {
+      Fail`instance doesn't have privateArgs`;
+    }
+    instancePrivateArgs.set(instance, privateArgs);
+  };
+
+  // Use a heap zone to avoid entanglement with old liveslots
+  const zone = makeHeapZone();
+  const makeContractControl = prepareContractControl(zone, {
+    agoricNamesAdmin: await consume.agoricNamesAdmin,
+    board: await consume.board,
+    startUpgradable: await consume.startUpgradable,
+    updatePrivateArgs,
+    zoe: await zoe,
+  });
+
+  /** @type {DeliverContractControl} */
+  const deliverContractControl = async ({
+    name: contractName,
+    controlAddress,
+    ...opts
+  }) => {
+    await null;
+
+    const trace = makeTracer(`CCtrlCore-${contractName}`);
+
+    trace('creating contract control and delivering to', controlAddress);
+
+    const contractControl = makeContractControl({
+      name: contractName,
+      storageNode: await E(chainStorage).makeChildNode(contractName),
+      ...opts,
+    });
+
+    trace('reserving', controlAddress);
+    // This can block if the wallet is not provisioned
+    await E(getDepositFacet)(controlAddress);
+
+    trace(`delivering control`, controlAddress, contractControl);
+    // don't block on the recipient's offer
+    const delivered = E.when(
+      E(postalSvcPub).deliverPrize(
+        controlAddress,
+        contractControl,
+        YMAX_CONTROL_WALLET_KEY,
+      ),
+      () => trace('control received'),
+    );
+
+    return harden({ delivered, contractControl });
+  };
+  harden(deliverContractControl);
+
+  permitted.produce.deliverContractControl.resolve(deliverContractControl);
+};
+
+export const getManifestForDeliverContractControl = () => ({
+  manifest: {
+    [produceDeliverContractControl.name]: {
+      consume: {
+        agoricNamesAdmin: true,
+        board: true,
+        chainStorage: true,
+        getDepositFacet: true,
+        instancePrivateArgs: true,
+        startUpgradable: true,
+        zoe: true,
+      },
+      produce: {
+        deliverContractControl: true,
+      },
+      instance: {
+        consume: { postalService: true },
+        // provide: true,
+      },
+      installation: {
+        // provide: true,
+      },
+    },
+  },
+});

package/src/control/get-upgrade-kit.build.js

@@ -0,0 +1,28 @@
+/**
+ * @import { CoreEvalBuilder, DeployScriptFunction } from '@agoric/deploy-script-support/src/externalTypes.js';
+ */
+
+import { makeHelpers } from '../helpers.js';
+import { getManifestForGetUpgradeKit } from './get-upgrade-kit.core.js';
+
+const sourceSpec =
+  '@agoric/deploy-script-support/src/control/get-upgrade-kit.core.js';
+
+/**
+ * @satisfies {CoreEvalBuilder}
+ */
+const defaultProposalBuilder = async () => {
+  return harden({
+    sourceSpec,
+    getManifestCall: [getManifestForGetUpgradeKit.name],
+  });
+};
+
+/** @type {DeployScriptFunction} */
+const build = async (homeP, endowments) => {
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+
+  await writeCoreEval('eval-get-upgrade-kit', () => defaultProposalBuilder());
+};
+
+export default build;

package/src/control/get-upgrade-kit.core.js

@@ -0,0 +1,83 @@
+/**
+ * @file Get a contract upgrade kit by name.
+ */
+
+import { E } from '@endo/eventual-send';
+
+/**
+ * @import {ContractStartFunction, Instance} from '@agoric/zoe/src/zoeService/utils.js';
+ * @import {StartedInstanceKit, StartedInstanceKitWithLabel} from '@agoric/vats/src/core/types.js';
+ * @import {PromiseSpaceOf} from '@agoric/vats/src/core/types.js';
+ * @import {BootstrapPowers} from '@agoric/vats/src/core/types.js';
+ */
+
+const trace = (...args) => console.log('---- GetUpgradeKit', ...args);
+
+/**
+ * Similar to StartedInstanceKit, but with label and optional privateArgs
+ * managed by ContractControl.
+ *
+ * @template {ContractStartFunction} SF
+ * @typedef {StartedInstanceKit<SF> & {
+ *   label: string;
+ *   privateArgs?: Parameters<SF>[1];
+ * }} UpgradeKit
+ */
+
+/**
+ * `getUpgradeKit` is a power allowing to retrieve a contract upgrade kit by
+ * the contract's name, without giving full access to the underlying stores.
+ *
+ * @typedef {PromiseSpaceOf<{
+ *   getUpgradeKit: <SF extends ContractStartFunction>(name: string) => Promise<StartedInstanceKitWithLabel<SF>>
+ * }>} GetUpgradeKitPowers
+ */
+
+/**
+ * @param {BootstrapPowers & GetUpgradeKitPowers} powers
+ */
+export const produceGetUpgradeKit = async powers => {
+  powers.produce.getUpgradeKit.reset();
+  const { consume } = powers;
+
+  const agoricNames = await consume.agoricNames;
+  const contractKits = await consume.contractKits;
+  const instancePrivateArgs = await consume.instancePrivateArgs;
+
+  /**
+   * @template {ContractStartFunction} SF
+   * @param {string} name
+   * @returns {Promise<StartedInstanceKitWithLabel<SF>>}
+   */
+  const getUpgradeKit = async name => {
+    trace('getting instance for', name);
+    /** @type {Instance<SF>} */
+    const instance = await E(agoricNames).lookup('instance', name);
+
+    trace('getting contract kit for', name);
+    const kit = /** @type {UpgradeKit<SF>} */ (contractKits.get(instance));
+
+    trace('getting privateArgs for', name);
+    const privateArgs = instancePrivateArgs.has(instance)
+      ? /** @type {Parameters<SF>[1]} */ (instancePrivateArgs.get(instance))
+      : undefined;
+
+    return { ...kit, privateArgs };
+  };
+  harden(getUpgradeKit);
+
+  powers.produce.getUpgradeKit.resolve(getUpgradeKit);
+};
+
+export const getManifestForGetUpgradeKit = () => ({
+  manifest: {
+    [produceGetUpgradeKit.name]: {
+      consume: {
+        agoricNames: true,
+        contractKits: true,
+        instancePrivateArgs: true,
+      },
+      produce: { getUpgradeKit: true },
+    },
+  },
+});

package/src/control/postal-service.core.js

@@ -0,0 +1,59 @@
+import { E } from '@endo/eventual-send';
+import { passStyleOf } from '@endo/pass-style';
+import { objectMap } from '@endo/patterns';
+import { makeTracer } from '@agoric/internal/src/debug.js';
+
+const contractName = 'postalService';
+
+const trace = makeTracer('CCtrlCore');
+
+/**
+ * @import {Installation} from '@agoric/zoe';
+ * @import {Instance} from '@agoric/zoe';
+ * @import {PromiseSpaceOf} from '@agoric/vats/src/core/types.js';
+ * @import {BootstrapPowers} from '@agoric/vats/src/core/types.js';
+ * @import {start} from '@aglocal/portfolio-deploy/src/control/postal-service.contract.js';
+ */
+/**
+ * @typedef {typeof start} PostalServiceStartFn
+ *
+ * @typedef {{
+ *   installation: PromiseSpaceOf<{ postalService: Installation<PostalServiceStartFn>}>;
+ *   instance: PromiseSpaceOf<{ postalService: Instance<PostalServiceStartFn>}>;
+ * }} PostalServiceBoot
+ */
+
+/** @param {BootstrapPowers & PostalServiceBoot} permitted */
+export const deployPostalService = async permitted => {
+  permitted.instance.produce.postalService.reset();
+  const { startUpgradable, namesByAddress } = permitted.consume;
+  const { postalService: installationP } = permitted.installation.consume;
+  trace('await: installation.postalService');
+  const installation = await installationP;
+  trace('await: namesByAddress');
+  const privateArgs = harden({
+    namesByAddress: await namesByAddress,
+  });
+  trace('await: startUpgradable(...)');
+  const kit = await E(startUpgradable)({
+    label: contractName,
+    installation,
+    privateArgs,
+  });
+  trace('kit', objectMap(kit, passStyleOf));
+  permitted.instance.produce.postalService.resolve(kit.instance);
+};
+
+export const getManifestForPostalService = (
+  { restoreRef },
+  { installKeys },
+) => ({
+  manifest: {
+    [deployPostalService.name]: {
+      consume: { startUpgradable: true, namesByAddress: true },
+      installation: { consume: { postalService: true } },
+      instance: { produce: { postalService: true } },
+    },
+  },
+  installations: { postalService: restoreRef(installKeys.postalService) },
+});

package/src/wallet-utils.js

@@ -0,0 +1,150 @@
+/* global globalThis */
+/**
+ * @file Reusable wallet utilities for portfolio contract testing and operations
+ *
+ * This module consolidates wallet-related utilities that were previously
+ * duplicated across multichain-testing and a3p-integration.
+ */
+
+import { retryUntilCondition } from '@agoric/client-utils';
+import { YMAX_CONTROL_WALLET_KEY } from '@agoric/portfolio-api/src/portfolio-constants.js';
+
+/**
+ * @import {UpdateRecord} from '@agoric/smart-wallet/src/smartWallet.js';
+ * @import {RetryOptions} from '@agoric/client-utils';
+ * @import {SigningSmartWalletKit} from '@agoric/client-utils';
+ * @import {Instance} from '@agoric/zoe';
+ * @import {BridgeAction} from '@agoric/smart-wallet/src/smartWallet.js';
+ */
+
+/**
+ * Helper to wait for specific wallet updates
+ *
+ * This provides a higher-level API over retryUntilCondition for common
+ * wallet update patterns.
+ *
+ * @param {() => Promise<UpdateRecord>} getLastUpdate
+ * @param {RetryOptions & {
+ *   log: (...args: unknown[]) => void;
+ *   setTimeout: typeof globalThis.setTimeout;
+ * }} retryOpts
+ */
+export const walletUpdates = (getLastUpdate, retryOpts) => {
+  return harden({
+    /**
+     * Wait for an invocation to complete
+     * @param {string | number} id
+     */
+    invocation: async id => {
+      const done = /** @type {UpdateRecord & { updated: 'invocation' }} */ (
+        await retryUntilCondition(
+          getLastUpdate,
+          update =>
+            update.updated === 'invocation' &&
+            update.id === id &&
+            !!(update.result || update.error),
+          `${id}`,
+          retryOpts,
+        )
+      );
+      if (done.error) throw Error(done.error);
+      return done.result;
+    },
+
+    /**
+     * Wait for an offer to complete
+     * @param {string | number} id
+     */
+    offerResult: async id => {
+      const done = await retryUntilCondition(
+        getLastUpdate,
+        update =>
+          // walletAction implies an error, so also stop on that
+          update.updated === 'walletAction' ||
+          // if it's offerStatus, it can be in progress until result or error
+          (update.updated === 'offerStatus' &&
+            update.status.id === id &&
+            (!!update.status.result || !!update.status.error)),
+        `${id}`,
+        retryOpts,
+      );
+      switch (done.updated) {
+        case 'walletAction':
+          throw Error(`walletAction failure: ${done.status.error}`);
+        case 'offerStatus':
+          if (done.status.error) {
+            throw Error(`offerStatus failure: ${done.status.error}`);
+          }
+          if (!done.status.result) {
+            throw Error(`offerStatus missing result`);
+          }
+          return done.status.result;
+        default:
+          throw Error(`unexpected update type ${done.updated}`);
+      }
+    },
+  });
+};
+
+/**
+ * Redeem the ymaxControl invitation from the postal service
+ *
+ * This is a common pattern in ymax testing where we need to redeem
+ * the control facet invitation delivered via postal service.
+ *
+ * @param {{
+ *   sig: SigningSmartWalletKit;
+ *   postalServiceInstance: Instance;
+ *   fresh: () => string | number;
+ *   log?: (...args: unknown[]) => void;
+ * }} options
+ * @returns {Promise<void>}
+ */
+export const redeemYmaxControlInvitation = async ({
+  sig,
+  postalServiceInstance,
+  fresh,
+  log = () => {},
+}) => {
+  const id = `redeem-${YMAX_CONTROL_WALLET_KEY}-${fresh()}`;
+  log('Redeeming ymaxControl invitation', id);
+
+  /** @type {BridgeAction} */
+  const redeemAction = harden({
+    method: 'executeOffer',
+    offer: {
+      id,
+      invitationSpec: {
+        source: 'purse',
+        instance: postalServiceInstance,
+        description: `deliver ${YMAX_CONTROL_WALLET_KEY}`,
+      },
+      proposal: {},
+      saveResult: { name: YMAX_CONTROL_WALLET_KEY, overwrite: true },
+    },
+  });
+
+  const tx = await sig.sendBridgeAction(redeemAction);
+  if (tx.code !== 0) {
+    throw Error(`Failed to redeem invitation: ${tx.rawLog}`);
+  }
+
+  const wup = walletUpdates(sig.query.getLastUpdate, {
+    setTimeout: globalThis.setTimeout,
+    log,
+  });
+
+  await wup.offerResult(id);
+  log('ymaxControl invitation redeemed successfully');
+};
+
+/**
+ * Helper to create action IDs with a consistent format
+ *
+ * @param {string} description
+ * @param {() => string | number} [fresh]
+ * @returns {string}
+ */
+export const makeActionId = (description, fresh = () => Date.now()) => {
+  return `${description}.${fresh()}`;
+};