@agoric/fast-usdc 0.1.1-dev-02967de.0

package/src/util/file.js

@@ -0,0 +1,30 @@
+import { dirname } from 'path';
+
+/** @import { readFile as readAsync } from 'node:fs/promises' */
+/** @import { writeFile as writeAsync } from 'node:fs/promises' */
+/** @import { mkdirSync } from 'node:fs' */
+/** @import { existsSync } from 'node:fs' */
+
+export const makeFile = (
+  /** @type {string} */ path,
+  /** @type {readAsync} */ readFile,
+  /** @type {writeAsync} */ writeFile,
+  /** @type {mkdirSync} */ mkdir,
+  /** @type {existsSync} */ pathExists,
+) => {
+  const read = () => readFile(path, 'utf-8');
+
+  const write = async (/** @type {string} */ data) => {
+    const dir = dirname(path);
+    if (!pathExists(dir)) {
+      mkdir(dir);
+    }
+    await writeFile(path, data);
+  };
+
+  const exists = () => pathExists(path);
+
+  return { read, write, exists, path };
+};
+
+/** @typedef {ReturnType<typeof makeFile>} file */

package/src/util/noble.js

@@ -0,0 +1,110 @@
+/* global globalThis */
+
+import { DirectSecp256k1HdWallet, Registry } from '@cosmjs/proto-signing';
+import { AminoTypes, SigningStargateClient } from '@cosmjs/stargate';
+import { nobleAminoConverters, nobleProtoRegistry } from '@nick134-bit/noblejs';
+
+export const makeSigner = async (
+  /** @type {string} */ nobleSeed,
+  /** @type {string} */ nobleRpc,
+  out = console,
+) => {
+  const wallet = await DirectSecp256k1HdWallet.fromMnemonic(nobleSeed, {
+    prefix: 'noble',
+  });
+  out.log('got noble wallet from seed');
+  const accounts = await wallet.getAccounts();
+  const address = accounts[0].address;
+  const signer = await SigningStargateClient.connectWithSigner(
+    nobleRpc,
+    wallet,
+    {
+      aminoTypes: new AminoTypes({
+        ...nobleAminoConverters,
+      }),
+      registry: new Registry([...nobleProtoRegistry]),
+    },
+  );
+  return { address, signer };
+};
+
+const createMsgRegisterAccount = (
+  /** @type {string} */ signer,
+  /** @type {string} */ recipient,
+  /** @type {string} */ channel,
+) => {
+  return {
+    typeUrl: '/noble.forwarding.v1.MsgRegisterAccount',
+    value: {
+      signer,
+      recipient,
+      channel,
+    },
+  };
+};
+
+export const registerFwdAccount = async (
+  /** @type {SigningStargateClient} */ nobleSigner,
+  /** @type {string} */ nobleAddress,
+  /** @type {string} */ nobleToAgoricChannel,
+  /** @type {string} */ recipient,
+  out = console,
+) => {
+  out.log('registering fwd account on noble');
+  const msg = createMsgRegisterAccount(
+    nobleAddress,
+    recipient,
+    nobleToAgoricChannel,
+  );
+  const fee = {
+    amount: [
+      {
+        denom: 'uusdc',
+        amount: '20000',
+      },
+    ],
+    gas: '200000',
+  };
+  out.log('signing message', msg);
+  const txResult = await nobleSigner.signAndBroadcast(
+    nobleAddress,
+    [msg],
+    fee,
+    'Register Account Transaction',
+  );
+  if (txResult.code !== undefined && txResult.code !== 0) {
+    throw new Error(
+      `Transaction failed with code ${txResult.code}: ${txResult.events || ''}`,
+    );
+  }
+  return `Transaction successful with hash: ${txResult.transactionHash}`;
+};
+
+export const queryForwardingAccount = async (
+  /** @type {string} */ nobleApi,
+  /** @type {string} */ nobleToAgoricChannel,
+  /** @type {string} */ agoricAddr,
+  out = console,
+  fetch = globalThis.fetch,
+) => {
+  /**
+   * https://github.com/noble-assets/forwarding/blob/9d7657a/proto/noble/forwarding/v1/query.proto
+   * v2.0.0 10 Nov 2024
+   */
+  const query = `${nobleApi}/noble/forwarding/v1/address/${nobleToAgoricChannel}/${encodeURIComponent(agoricAddr)}/`;
+  out.log(`querying forward address details from noble api: ${query}`);
+  let forwardingAddressRes;
+  await null;
+  try {
+    forwardingAddressRes = await fetch(query).then(res => res.json());
+  } catch (e) {
+    out.error(`Error querying forwarding address from ${query}`);
+    throw e;
+  }
+  /** @type {{ address: string, exists: boolean }} */
+  const { address, exists } = forwardingAddressRes;
+  out.log(
+    `got forwarding address details: ${JSON.stringify(forwardingAddressRes)}`,
+  );
+  return { address, exists };
+};

package/src/utils/address.js

@@ -0,0 +1,71 @@
+import { makeError, q } from '@endo/errors';
+import { M, mustMatch } from '@endo/patterns';
+
+/**
+ * @import {Pattern} from '@endo/patterns';
+ */
+
+/**
+ * Default pattern matcher for `getQueryParams`.
+ * Does not assert keys exist, but ensures existing keys are strings.
+ */
+const QueryParamsShape = M.splitRecord(
+  {},
+  {},
+  M.recordOf(M.string(), M.string()),
+);
+
+/**
+ * Very minimal 'URL query string'-like parser that handles:
+ *  - Query string delimiter (?)
+ *  - Key-value separator (=)
+ *  - Query parameter separator (&)
+ *
+ * Does not handle:
+ * - Subpaths (`agoric1bech32addr/opt/account?k=v`)
+ * - URI encoding/decoding (`%20` -> ` `)
+ *    - note: `decodeURIComponent` seems to be available in XS
+ * - Multiple question marks (foo?bar=1?baz=2)
+ * - Empty parameters (foo=)
+ * - Array parameters (`foo?k=v1&k=v2` -> k: [v1, v2])
+ * - Parameters without values (foo&bar=2)
+ */
+export const addressTools = {
+  /**
+   * @param {string} address
+   * @returns {boolean}
+   */
+  hasQueryParams: address => {
+    try {
+      const params = addressTools.getQueryParams(address);
+      return Object.keys(params).length > 0;
+    } catch {
+      return false;
+    }
+  },
+  /**
+   * @param {string} address
+   * @param {Pattern} [shape]
+   * @returns {Record<string, string>}
+   * @throws {Error} if the address cannot be parsed or params do not match `shape`
+   */
+  getQueryParams: (address, shape = QueryParamsShape) => {
+    const parts = address.split('?');
+    if (parts.length !== 2) {
+      throw makeError(`Unable to parse query params: ${q(address)}`);
+    }
+    /** @type {Record<string, string>} */
+    const result = {};
+    const paramPairs = parts[1].split('&');
+    for (const pair of paramPairs) {
+      const [key, value] = pair.split('=');
+      if (!key || !value) {
+        throw makeError(`Invalid parameter format in pair: ${q(pair)}`);
+      }
+      result[key] = value;
+    }
+    harden(result);
+    mustMatch(result, shape);
+    return result;
+  },
+};

package/src/utils/config-marshal.js

@@ -0,0 +1,130 @@
+import { Fail } from '@endo/errors';
+import { makeMarshal } from '@endo/marshal';
+import { mustMatch } from '@endo/patterns';
+
+// TODO(#7309): move to make available beyond fast-usdc.
+
+/**
+ * @import {Marshal, CapData, Passable} from '@endo/marshal';
+ * @import { RemotableBrand } from '@endo/eventual-send';
+ * @import {TypedPattern} from '@agoric/internal'
+ */
+const { entries } = Object;
+
+/**
+ * To configure amounts such as terms or ratios,
+ * we need to refer to objects such as brands.
+ *
+ * If parties agree on names, any party that doesn't have
+ * an actual presence for an object can make one up:
+ *
+ * const remotes = { USDC: Far('USDC Brand') };
+ *
+ * and use it in local computation:
+ *
+ * const terms = { fee1: AmountMath.make(remotes.USDC, 1234n) }
+ *
+ * Then we can pass references across using marshal conventions, using
+ * the names as slots.
+ *
+ * @param {Record<string, Passable>} slotToVal a record that gives names to stand-ins for objects in another vat
+ * @returns {Marshal<string>}
+ */
+export const makeMarshalFromRecord = slotToVal => {
+  const convertSlotToVal = slot => {
+    slot in slotToVal || Fail`unknown slot ${slot}`;
+    return slotToVal[slot];
+  };
+  const valToSlot = new Map(entries(slotToVal).map(([k, v]) => [v, k]));
+  const convertValToSlot = v => {
+    valToSlot.has(v) || Fail`unknown value: ${v}`;
+    return valToSlot.get(v);
+  };
+  return makeMarshal(convertValToSlot, convertSlotToVal, {
+    serializeBodyFormat: 'smallcaps',
+  });
+};
+
+/**
+ * @typedef {`\$${number}${string}`} SmallCapsSlotRef
+ */
+
+/**
+ * @template T
+ * @typedef {{ [KeyType in keyof T]: T[KeyType] } & {}} Simplify flatten the
+ *   type output to improve type hints shown in editors
+ *   https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+
+/**
+ * @template T
+ * @template R
+ * @typedef {T extends R
+ *     ? SmallCapsSlotRef
+ *     : T extends {}
+ *       ? Simplify<SmallCapsStructureOf<T, R>>
+ *       : Awaited<T>} SmallCapsStructureOf
+ */
+
+/**
+ * The smallCaps body is a string, which simplifies some usage.
+ * But it's hard to read and write.
+ *
+ * The parsed structure makes a convenient notation for configuration etc.
+ *
+ * @template {Passable} [T=Passable]
+ * @template [R=RemotableBrand]
+ * @typedef {{
+ *   structure: SmallCapsStructureOf<T, R>;
+ *   slots: string[];
+ * }} LegibleCapData
+ */
+
+/**
+ * @template {Passable} [T=Passable]
+ * @template [R=RemotableBrand]
+ * @param {CapData<string>} capData
+ * @returns {LegibleCapData<T, R>}
+ */
+export const toLegible = ({ body, slots }) =>
+  harden({ structure: JSON.parse(body.replace(/^#/, '')), slots });
+
+/**
+ * @template {Passable} [T=Passable]
+ * @template [R=RemotableBrand]
+ * @param {LegibleCapData<T,R>} legible
+ * @returns {CapData<string>}
+ */
+export const fromLegible = ({ structure, slots }) =>
+  harden({ body: `#${JSON.stringify(structure)}`, slots });
+
+/**
+ * @template {Passable} [T=Passable]
+ * @template [R=RemotableBrand]
+ * @param {T} config
+ * @param {Record<string, Passable>} context
+ * @param {TypedPattern<T>} [shape]
+ * @returns {LegibleCapData<T,R>}
+ */
+export const toExternalConfig = (config, context, shape) => {
+  if (shape) {
+    mustMatch(config, shape);
+  }
+  return toLegible(makeMarshalFromRecord(context).toCapData(config));
+};
+
+/**
+ * @template {Passable} [T=Passable]
+ * @template [R=RemotableBrand]
+ * @param {LegibleCapData<T,R>} repr
+ * @param {Record<string, Passable>} context
+ * @param {TypedPattern<T>} [shape]
+ * @returns {T}
+ */
+export const fromExternalConfig = (repr, context, shape) => {
+  const config = makeMarshalFromRecord(context).fromCapData(fromLegible(repr));
+  if (shape) {
+    mustMatch(config, shape);
+  }
+  return config;
+};

package/src/utils/fees.js

@@ -0,0 +1,58 @@
+import { AmountMath } from '@agoric/ertp';
+import { multiplyBy } from '@agoric/zoe/src/contractSupport/ratio.js';
+import { Fail } from '@endo/errors';
+import { mustMatch } from '@endo/patterns';
+import { FeeConfigShape } from '../type-guards.js';
+
+const { add, isGTE, min, subtract } = AmountMath;
+
+/**
+ * @import {Amount} from '@agoric/ertp';
+ * @import {FeeConfig} from '../types.js';
+ * @import {RepayAmountKWR} from '../exos/liquidity-pool.js';
+ */
+
+/** @param {FeeConfig} feeConfig */
+export const makeFeeTools = feeConfig => {
+  mustMatch(feeConfig, FeeConfigShape, 'Must provide feeConfig');
+  const { flat, variableRate, maxVariable } = feeConfig;
+  const feeTools = harden({
+    /**
+     * Calculate the net amount to advance after withholding fees.
+     *
+     * @param {Amount<'nat'>} requested
+     * @throws {Error} if requested does not exceed fees
+     */
+    calculateAdvance(requested) {
+      const fee = feeTools.calculateAdvanceFee(requested);
+      return subtract(requested, fee);
+    },
+    /**
+     * Calculate the total fee to charge for the advance.
+     *
+     * @param {Amount<'nat'>} requested
+     * @throws {Error} if requested does not exceed fees
+     */
+    calculateAdvanceFee(requested) {
+      const variable = min(multiplyBy(requested, variableRate), maxVariable);
+      const fee = add(variable, flat);
+      !isGTE(fee, requested) || Fail`Request must exceed fees.`;
+      return fee;
+    },
+    /**
+     * Calculate the split of fees between pool and contract.
+     *
+     * @param {Amount<'nat'>} requested
+     * @returns {RepayAmountKWR} an {@link AmountKeywordRecord}
+     * @throws {Error} if requested does not exceed fees
+     */
+    calculateSplit(requested) {
+      const fee = feeTools.calculateAdvanceFee(requested);
+      const Principal = subtract(requested, fee);
+      const ContractFee = multiplyBy(fee, feeConfig.contractRate);
+      const PoolFee = subtract(fee, ContractFee);
+      return harden({ Principal, PoolFee, ContractFee });
+    },
+  });
+  return feeTools;
+};

package/src/utils/zoe.js

@@ -0,0 +1,28 @@
+import { makeTracer } from '@agoric/internal';
+
+const trace = makeTracer('ZoeUtils');
+
+/**
+ * Used for "continuing offer" invitations in which the caller does not need
+ * anything in return. In those cases there is no Zoe offer safety and the
+ * invitation making function can perform the request itself.
+ *
+ * But smart-wallet expects an invitation maker to make an invitation, so this
+ * function abstracts making such an inert invitation and logs consistently when
+ * it is used.
+ *
+ * When this is used by an invitation maker that performs the operation, receiving
+ * one of these invitations is evidence that the operation took place.
+ *
+ * @param {ZCF} zcf
+ * @param {string} description @see {@link ZCF.makeInvitation}
+ * @returns {() => Promise<Invitation>} an arg-less invitation maker
+ */
+export const defineInertInvitation = (zcf, description) => {
+  return () =>
+    zcf.makeInvitation(seat => {
+      trace(`ℹ️ An offer was made on an inert invitation for ${description}`);
+      seat.exit();
+      return 'inert; nothing should be expected from this offer';
+    }, description);
+};