@agoric/fast-usdc 0.1.1-other-dev-3eb1a1d.0 → 0.2.0-u18.0

package/src/type-guards.js

@@ -6,7 +6,7 @@ import { PendingTxStatus } from './constants.js';
  * @import {TypedPattern} from '@agoric/internal';
  * @import {FastUsdcTerms} from './fast-usdc.contract.js';
  * @import {USDCProposalShapes} from './pool-share-math.js';
- * @import {CctpTxEvidence, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy} from './types.js';
+ * @import {CctpTxEvidence, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy, AddressHook, EvmAddress, EvmHash, RiskAssessment, EvidenceWithRisk} from './types.js';
  */
 
 /**
@@ -21,7 +21,7 @@ export const makeProposalShapes = ({ PoolShares, USDC }) => {
   /** @type {TypedPattern<USDCProposalShapes['deposit']>} */
   const deposit = M.splitRecord(
     { give: { USDC: makeNatAmountShape(USDC, 1n) } },
-    { want: { PoolShare: makeNatAmountShape(PoolShares) } },
+    { want: M.splitRecord({}, { PoolShare: makeNatAmountShape(PoolShares) }) },
   );
   /** @type {TypedPattern<USDCProposalShapes['withdraw']>} */
   const withdraw = M.splitRecord({
@@ -36,12 +36,28 @@ export const FastUSDCTermsShape = harden({
   usdcDenom: M.string(),
 });
 
-/** @type {TypedPattern<string>} */
+/** @type {TypedPattern<EvmAddress>} */
+export const EvmAddressShape = M.string({
+  // 0x + 40 hex digits
+  stringLengthLimit: 42,
+});
+harden(EvmAddressShape);
+
+/** @type {TypedPattern<EvmHash>} */
 export const EvmHashShape = M.string({
   stringLengthLimit: 66,
 });
 harden(EvmHashShape);
 
+/** @type {TypedPattern<RiskAssessment>} */
+export const RiskAssessmentShape = M.splitRecord(
+  {},
+  {
+    risksIdentified: M.arrayOf(M.string()),
+  },
+);
+harden(RiskAssessmentShape);
+
 /** @type {TypedPattern<CctpTxEvidence>} */
 export const CctpTxEvidenceShape = {
   aux: {
@@ -49,17 +65,24 @@ export const CctpTxEvidenceShape = {
     recipientAddress: M.string(),
   },
   blockHash: EvmHashShape,
-  blockNumber: M.bigint(),
-  blockTimestamp: M.bigint(),
+  blockNumber: M.nat(),
   chainId: M.number(),
   tx: {
-    amount: M.bigint(),
+    amount: M.nat(),
     forwardingAddress: M.string(),
+    sender: EvmAddressShape,
   },
   txHash: EvmHashShape,
 };
 harden(CctpTxEvidenceShape);
 
+/** @type {TypedPattern<EvidenceWithRisk>} */
+export const EvidenceWithRiskShape = {
+  evidence: CctpTxEvidenceShape,
+  risk: RiskAssessmentShape,
+};
+harden(EvidenceWithRiskShape);
+
 /** @type {TypedPattern<PendingTx>} */
 // @ts-expect-error TypedPattern not recognized as record
 export const PendingTxShape = {
@@ -68,10 +91,12 @@ export const PendingTxShape = {
 };
 harden(PendingTxShape);
 
-export const EudParamShape = {
-  EUD: M.string(),
+/** @type {TypedPattern<AddressHook>} */
+export const AddressHookShape = {
+  baseAddress: M.string(),
+  query: { EUD: M.string() },
 };
-harden(EudParamShape);
+harden(AddressHookShape);
 
 const NatAmountShape = { brand: BrandShape, value: M.nat() };
 /** @type {TypedPattern<FeeConfig>} */
@@ -95,16 +120,13 @@ export const PoolMetricsShape = {
 harden(PoolMetricsShape);
 
 /** @type {TypedPattern<ChainPolicy>} */
-export const ChainPoliciesShape = M.splitRecord(
-  {
-    nobleContractAddress: EvmHashShape,
-    cctpTokenMessengerAddress: EvmHashShape,
-    confirmations: M.number(),
-    chainId: M.number(),
-  },
-  { chainType: M.number() },
-);
-harden(ChainPoliciesShape);
+export const ChainPolicyShape = {
+  attenuatedCttpBridgeAddress: EvmHashShape,
+  cctpTokenMessengerAddress: EvmHashShape,
+  confirmations: M.number(),
+  chainId: M.number(),
+};
+harden(ChainPolicyShape);
 
 /**
  * @type {TypedPattern<FeedPolicy>}
@@ -116,7 +138,7 @@ export const FeedPolicyShape = M.splitRecord(
   {
     nobleDomainId: M.number(),
     nobleAgoricChannelId: M.string(),
-    chainPolicies: M.recordOf(M.string(), ChainPoliciesShape),
+    chainPolicies: M.recordOf(M.string(), ChainPolicyShape),
   },
   { eventFilter: M.string() },
 );

package/src/types.ts

@@ -1,13 +1,26 @@
-import type { ChainAddress } from '@agoric/orchestration';
+import type {
+  ChainAddress,
+  CosmosChainInfo,
+  Denom,
+  DenomDetail,
+} from '@agoric/orchestration';
 import type { IBCChannelID } from '@agoric/vats';
 import type { Amount } from '@agoric/ertp';
-import type { PendingTxStatus } from './constants.js';
+import type { CopyRecord, Passable } from '@endo/pass-style';
+import type { PendingTxStatus, TxStatus } from './constants.js';
+import type { FastUsdcTerms } from './fast-usdc.contract.js';
+import type { RepayAmountKWR } from './exos/liquidity-pool.js';
 
 export type EvmHash = `0x${string}`;
+export type EvmAddress = `0x${string & { length: 40 }}`;
 export type NobleAddress = `noble1${string}`;
 export type EvmChainID = number;
 export type EvmChainName = string;
 
+export interface RiskAssessment {
+  risksIdentified?: string[];
+}
+
 export interface CctpTxEvidence {
   /** from Noble RPC */
   aux: {
@@ -16,28 +29,38 @@ export interface CctpTxEvidence {
   };
   blockHash: EvmHash;
   blockNumber: bigint;
-  blockTimestamp: bigint;
   chainId: number;
   /** data covered by signature (aka txHash) */
   tx: {
     amount: bigint;
     forwardingAddress: NobleAddress;
+    sender: EvmAddress;
   };
   txHash: EvmHash;
 }
 
+export interface EvidenceWithRisk {
+  evidence: CctpTxEvidence;
+  risk: RiskAssessment;
+}
+
+/**
+ * 'evidence' only available when it's first observed and not in subsequent
+ * updates.
+ */
+export interface TransactionRecord extends CopyRecord {
+  evidence?: CctpTxEvidence;
+  split?: RepayAmountKWR;
+  risksIdentified?: string[];
+  status: TxStatus;
+}
+
 export type LogFn = (...args: unknown[]) => void;
 
 export interface PendingTx extends CctpTxEvidence {
   status: PendingTxStatus;
 }
 
-/** internal key for `StatusManager` exo */
-export type PendingTxKey = `pendingTx:${string}`;
-
-/** internal key for `StatusManager` exo */
-export type SeenTxKey = `seenTx:${string}`;
-
 export type FeeConfig = {
   flat: Amount<'nat'>;
   variableRate: Ratio;
@@ -58,11 +81,14 @@ export interface PoolMetrics extends PoolStats {
 }
 
 export interface ChainPolicy {
-  nobleContractAddress: EvmHash;
+  /** `msg.sender` of DepositAndBurn to TokenMessenger must be an attenuated wrapper contract that does not contain `replaceDepositForBurn` */
+  attenuatedCttpBridgeAddress: EvmHash;
+  /** @see {@link https://developers.circle.com/stablecoins/evm-smart-contracts} */
   cctpTokenMessengerAddress: EvmHash;
-  confirmations: number;
+  /** e.g., `1` for ETH mainnet 42161 for Arbitrum One. @see {@link https://chainlist.org/} */
   chainId: EvmChainID;
-  chainType?: number;
+  /** the number of block confirmations to observe before reporting */
+  confirmations: number;
 }
 
 export interface FeedPolicy {
@@ -72,4 +98,24 @@ export interface FeedPolicy {
   eventFilter?: string;
 }
 
+export type FastUSDCConfig = {
+  terms: FastUsdcTerms;
+  oracles: Record<string, string>;
+  feeConfig: FeeConfig;
+  feedPolicy: FeedPolicy & Passable;
+  noNoble: boolean; // support a3p-integration, which has no noble chain
+  chainInfo: Record<string, CosmosChainInfo & Passable>;
+  assetInfo: [Denom, DenomDetail & { brandKey?: string }][];
+} & CopyRecord;
+
+/** decoded address hook parameters */
+export type AddressHook = {
+  baseAddress: string;
+  query: {
+    /** end user destination address */
+    EUD: string;
+  };
+};
+
 export type * from './constants.js';
+export type { LiquidityPoolKit } from './exos/liquidity-pool.js';

package/src/util/agoric.js

@@ -5,7 +5,7 @@ export const queryFastUSDCLocalChainAccount = async (
   out = console,
 ) => {
   const agoricAddr = await vstorage.readLatest(
-    'published.fastUSDC.settlementAccount',
+    'published.fastUsdc.settlementAccount',
   );
   out.log(`Got Fast USDC Local Chain Account ${agoricAddr}`);
   return agoricAddr;

package/src/util/bank.js

@@ -0,0 +1,12 @@
+export const queryUSDCBalance = async (
+  /** @type {string} */ address,
+  /** @type {string} */ api,
+  /** @type {string} */ denom,
+  /** @type {typeof globalThis.fetch} */ fetch,
+) => {
+  const query = `${api}/cosmos/bank/v1beta1/balances/${address}`;
+  const json = await fetch(query).then(res => res.json());
+  const amount = json.balances?.find(b => b.denom === denom)?.amount ?? '0';
+
+  return BigInt(amount);
+};

package/src/util/cctp.js

@@ -67,5 +67,5 @@ export const depositForBurn = async (
 
   out.log('Transaction confirmed in block', receipt.blockNumber);
   out.log('Transaction hash:', receipt.hash);
-  out.log('USDC transfer initiated successfully, our work here is done.');
+  out.log('USDC transfer initiated successfully');
 };

package/src/util/file.js

@@ -27,4 +27,4 @@ export const makeFile = (
   return { read, write, exists, path };
 };
 
-/** @typedef {ReturnType<typeof makeFile>} file */
+/** @typedef {ReturnType<typeof makeFile>} File */

package/src/utils/deploy-config.js

@@ -0,0 +1,166 @@
+import { denomHash, withChainCapabilities } from '@agoric/orchestration';
+import fetchedChainInfo from '@agoric/orchestration/src/fetched-chain-info.js';
+
+/**
+ * @import {FastUSDCConfig} from '@agoric/fast-usdc/src/types.js'
+ * @import {Passable} from '@endo/marshal';
+ * @import {CosmosChainInfo, Denom, DenomDetail} from '@agoric/orchestration';
+ */
+
+/** @type {[Denom, DenomDetail & { brandKey?: string}][]} */
+export const defaultAssetInfo = [
+  [
+    'uusdc',
+    {
+      baseName: 'noble',
+      chainName: 'noble',
+      baseDenom: 'uusdc',
+    },
+  ],
+  [
+    `ibc/${denomHash({ denom: 'uusdc', channelId: fetchedChainInfo.agoric.connections['noble-1'].transferChannel.channelId })}`,
+    {
+      baseName: 'noble',
+      chainName: 'agoric',
+      baseDenom: 'uusdc',
+      brandKey: 'USDC',
+    },
+  ],
+  [
+    `ibc/${denomHash({ denom: 'uusdc', channelId: fetchedChainInfo.osmosis.connections['noble-1'].transferChannel.channelId })}`,
+    {
+      baseName: 'noble',
+      chainName: 'osmosis',
+      baseDenom: 'uusdc',
+    },
+  ],
+];
+harden(defaultAssetInfo);
+
+const agoricAssetInfo = defaultAssetInfo.filter(
+  ([_d, i]) => i.chainName === 'agoric',
+);
+
+/**
+ * @type {Record<string, Pick<FastUSDCConfig, 'oracles' | 'feedPolicy' | 'chainInfo' | 'assetInfo' >>}
+ *
+ * TODO: determine OCW operator addresses
+ * meanwhile, use price oracle addresses (from updatePriceFeeds.js).
+ */
+export const configurations = {
+  /**
+   * NOTE: The a3p-integration runtime does _not_ include
+   * a noble chain; this limits functionality to advancing
+   * to the Agoric chain.
+   */
+  A3P_INTEGRATION: {
+    oracles: {
+      gov1: 'agoric1ee9hr0jyrxhy999y755mp862ljgycmwyp4pl7q',
+      gov2: 'agoric1wrfh296eu2z34p6pah7q04jjuyj3mxu9v98277',
+      gov3: 'agoric1ydzxwh6f893jvpaslmaz6l8j2ulup9a7x8qvvq',
+    },
+    feedPolicy: {
+      nobleAgoricChannelId: 'channel-does-not-exist',
+      nobleDomainId: 4,
+      chainPolicies: {
+        Arbitrum: {
+          attenuatedCttpBridgeAddress:
+            '0xe298b93ffB5eA1FB628e0C0D55A43aeaC268e347',
+          cctpTokenMessengerAddress:
+            '0x19330d10D9Cc8751218eaf51E8885D058642E08A',
+          chainId: 42161,
+          confirmations: 2,
+        },
+      },
+    },
+    chainInfo: /** @type {Record<string, CosmosChainInfo & Passable>} */ (
+      withChainCapabilities({
+        agoric: fetchedChainInfo.agoric,
+        // registering USDC-on-agoric requires registering the noble chain
+        noble: fetchedChainInfo.noble,
+      })
+    ),
+    assetInfo: agoricAssetInfo,
+  },
+  MAINNET: {
+    oracles: {
+      '01node': 'agoric19uscwxdac6cf6z7d5e26e0jm0lgwstc47cpll8',
+      'Simply Staking': 'agoric1krunjcqfrf7la48zrvdfeeqtls5r00ep68mzkr',
+      P2P: 'agoric1n4fcxsnkxe4gj6e24naec99hzmc4pjfdccy5nj',
+    },
+    feedPolicy: {
+      nobleAgoricChannelId: 'channel-21',
+      nobleDomainId: 4,
+      chainPolicies: {
+        Arbitrum: {
+          attenuatedCttpBridgeAddress:
+            '0xe298b93ffB5eA1FB628e0C0D55A43aeaC268e347',
+          cctpTokenMessengerAddress:
+            '0x19330d10D9Cc8751218eaf51E8885D058642E08A',
+          chainId: 42161,
+          confirmations: 2,
+        },
+      },
+    },
+    chainInfo: /** @type {Record<string, CosmosChainInfo & Passable>} */ (
+      withChainCapabilities(fetchedChainInfo)
+    ),
+    assetInfo: defaultAssetInfo,
+  },
+  DEVNET: {
+    oracles: {
+      DSRV: 'agoric1lw4e4aas9q84tq0q92j85rwjjjapf8dmnllnft',
+      Stakin: 'agoric1zj6vrrrjq4gsyr9lw7dplv4vyejg3p8j2urm82',
+      '01node': 'agoric1ra0g6crtsy6r3qnpu7ruvm7qd4wjnznyzg5nu4',
+      'Simply Staking': 'agoric1qj07c7vfk3knqdral0sej7fa6eavkdn8vd8etf',
+      P2P: 'agoric10vjkvkmpp9e356xeh6qqlhrny2htyzp8hf88fk',
+    },
+    feedPolicy: {
+      nobleAgoricChannelId: 'TODO',
+      nobleDomainId: 4,
+      chainPolicies: {
+        Arbitrum: {
+          attenuatedCttpBridgeAddress: '0xTODO',
+          cctpTokenMessengerAddress: '0xTODO',
+          chainId: 421614,
+          confirmations: 2,
+        },
+      },
+    },
+    chainInfo: /** @type {Record<string, CosmosChainInfo & Passable>} */ (
+      withChainCapabilities(fetchedChainInfo) // TODO: use devnet values
+    ),
+    assetInfo: defaultAssetInfo, // TODO: use emerynet values
+  },
+  EMERYNET: {
+    oracles: {
+      gov1: 'agoric1ldmtatp24qlllgxmrsjzcpe20fvlkp448zcuce',
+      gov2: 'agoric140dmkrz2e42ergjj7gyvejhzmjzurvqeq82ang',
+    },
+    feedPolicy: {
+      nobleAgoricChannelId: 'TODO',
+      nobleDomainId: 4,
+      chainPolicies: {
+        Arbitrum: {
+          attenuatedCttpBridgeAddress: '0xTODO',
+          cctpTokenMessengerAddress: '0xTODO',
+          chainId: 421614,
+          confirmations: 2,
+        },
+      },
+    },
+    chainInfo: /** @type {Record<string, CosmosChainInfo & Passable>} */ (
+      withChainCapabilities(fetchedChainInfo) // TODO: use emerynet values
+    ),
+    assetInfo: defaultAssetInfo, // TODO: use emerynet values
+  },
+};
+harden(configurations);
+
+// Constraints on the configurations
+const MAINNET_EXPECTED_ORACLES = 3;
+assert(
+  new Set(Object.values(configurations.MAINNET.oracles)).size ===
+    MAINNET_EXPECTED_ORACLES,
+  `Mainnet must have exactly ${MAINNET_EXPECTED_ORACLES} oracles`,
+);

package/tools/cli-tools.ts

@@ -0,0 +1,9 @@
+export const flags = (
+  record: Record<string, string | number | bigint | undefined>,
+): string[] => {
+  // @ts-expect-error undefined is filtered out
+  const skipUndef: [string, string][] = Object.entries(record).filter(
+    ([_k, v]) => v !== undefined,
+  );
+  return skipUndef.map(([k, v]) => [`--${k}`, `${v}`]).flat();
+};

package/tools/mock-io.ts

@@ -0,0 +1,14 @@
+import type { Writable } from 'node:stream';
+
+/**
+ * mock stdout / stderr, for example
+ *
+ * @param buf - caller-provided buffer for written data
+ */
+export const mockStream = <T extends Writable>(buf: string[]): T =>
+  ({
+    write: txt => {
+      buf.push(txt);
+      return true;
+    },
+  }) as T;

package/src/exos/README.md

@@ -1,26 +0,0 @@
-##   **StatusManager** state diagram, showing different transitions
-
-
-### Contract state diagram
-
-*Transactions are qualified by the OCW and EventFeed before arriving to the Advancer.*
-
-```mermaid
-stateDiagram-v2
-  [*] --> Advanced: Advancer .advance()
-  Advanced --> Settled: Settler .settle() after fees
-  [*] --> Observed: Advancer .observed()
-  Observed --> Settled: Settler .settle() sans fees
-  Settled --> [*]
-```
-
-### Complete state diagram (starting from OCW)
-
-```mermaid
-stateDiagram-v2
-  Observed --> Qualified
-  Observed --> Unqualified
-  Qualified --> Advanced
-  Advanced --> Settled
-  Qualified --> Settled
-```

package/src/utils/address.js

@@ -1,71 +0,0 @@
-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;
-  },
-};