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

package/src/types.ts

@@ -1,48 +1,121 @@
-import type { ChainAddress } from '@agoric/orchestration';
-import type { IBCChannelID } from '@agoric/vats';
 import type { Amount } from '@agoric/ertp';
-import type { PendingTxStatus } from './constants.js';
+import type {
+  AccountId,
+  BaseChainInfo,
+  Bech32Address,
+  CaipChainId,
+  CosmosChainAddress,
+  CosmosChainInfo,
+  Denom,
+  DenomDetail,
+  KnownNamespace,
+} from '@agoric/orchestration';
+import type { IBCChannelID } from '@agoric/vats';
+import type { CopyRecord } from '@endo/pass-style';
+import type { PendingTxStatus, TxStatus } from './constants.js';
+import type { RepayAmountKWR } from './utils/fees.js';
+
+// XXX duped with Zoe contractSupport ambient types
+type Ratio = {
+  numerator: Amount<'nat'>;
+  denominator: Amount<'nat'>;
+};
 
+/**
+ * Block hash is calculated using the keccak256 algorithm that always results
+ * in 32 bytes (64 hex characters prepended by 0x) no matter the input length.
+ */
 export type EvmHash = `0x${string}`;
+/**
+ * An address is always the last 20 bytes (40 hex charaters prepended by 0x) of
+ * the public key hash.
+ */
+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: {
     forwardingChannel: IBCChannelID;
-    recipientAddress: ChainAddress['value'];
+    recipientAddress: CosmosChainAddress['value'] | AccountId;
   };
+  /** on the source chain (e.g. L1 Ethereum and L2s Arbitrum, Base) */
   blockHash: EvmHash;
+  /** height of blockHash on the source chain */
   blockNumber: bigint;
+  /**
+   * Seconds since Unix epoch. Not all CCTP source chains update time the same
+   * way but they all use Unix epoch and thus are approximately equal. (Within
+   * minutes apart.)
+   */
   blockTimestamp: bigint;
+  //
+  /**
+   * [Domain of values](https://chainid.network/) per [EIP-155](https://eips.ethereum.org/EIPS/eip-155)
+   * (We don't have [CCTP `domain`](https://developers.circle.com/stablecoins/supported-domains) )
+   */
   chainId: number;
   /** data covered by signature (aka txHash) */
   tx: {
     amount: bigint;
     forwardingAddress: NobleAddress;
+    sender: EvmAddress;
   };
   txHash: EvmHash;
 }
 
+export interface EvidenceWithRisk extends CopyRecord {
+  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;
+}
+
+/** the record in vstorage at the path of the contract's node */
+export interface ContractRecord extends CopyRecord {
+  nobleICA?: CosmosChainAddress['value'];
+  poolAccount: CosmosChainAddress['value'];
+  settlementAccount: CosmosChainAddress['value'];
+}
+
 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 fee charged for every advance, eligible for LP disbursement */
   flat: Amount<'nat'>;
+  /** proportion of advance kept as a fee, eligible for LP disbursement */
   variableRate: Ratio;
-  maxVariable: Amount<'nat'>;
+  /** proportion of `flat` and `variableRate` fees that goes to the contract (remaining goes to LPs) */
   contractRate: Ratio;
+  /**
+   * if present, a fee required to relay (e.g. CCTP to EVM/Solana). Not
+   * considered for LP disbursement - goes to `contractSeat`.
+   */
+  relay?: Amount<'nat'>;
+  /** Optional destination-specific overrides. If present, must supersede base values. */
+  destinationOverrides?: Record<
+    CaipChainId,
+    Partial<Omit<FeeConfig, 'destinationOverrides'>>
+  >;
 };
 
 export interface PoolStats {
@@ -58,18 +131,66 @@ 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` */
+  attenuatedCttpBridgeAddresses: 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;
+  rateLimits: {
+    /** do not advance more than this amount for an individual transaction */
+    tx: bigint;
+    /** do not advance more than this amount per block window */
+    blockWindow: bigint;
+    /** the number of blocks to consider for `blockWindow` */
+    blockWindowSize: number;
+  };
 }
 
-export interface FeedPolicy {
+export type FeedPolicy = {
   nobleDomainId: number;
   nobleAgoricChannelId: string;
   chainPolicies: Record<EvmChainName, ChainPolicy>;
   eventFilter?: string;
+} & CopyRecord;
+
+export type FastUsdcTerms = {
+  usdcDenom: Denom;
+};
+
+export type FastUSDCConfig = {
+  terms: FastUsdcTerms;
+  oracles: Record<string, string>;
+  feeConfig: FeeConfig;
+  feedPolicy: FeedPolicy;
+  noNoble: boolean; // support a3p-integration, which has no noble chain
+  chainInfo: Record<string, ChainHubChainInfo>;
+  assetInfo: [Denom, DenomDetail & { brandKey?: string }][];
+} & CopyRecord;
+
+/** decoded address hook parameters */
+export type AddressHook = {
+  baseAddress: string;
+  query: {
+    /** end user destination address */
+    EUD: Bech32Address;
+  };
+};
+
+/**
+ * The shape of ChainInfo ChainHub is expecting for FUSDC.
+ *
+ * Note: this diverges from `CosmosChainInfo` and `BaseChainInfo` in that:
+ * - BaseChainInfo includes chainId for backwards compatibility with `CosmosChainInfoShapeV1`
+ */
+export type ChainHubChainInfo<N extends KnownNamespace = KnownNamespace> =
+  N extends 'cosmos' ? CosmosChainInfo : BaseChainInfoWithChainId<N>;
+
+interface BaseChainInfoWithChainId<N extends KnownNamespace = KnownNamespace>
+  extends BaseChainInfo<N> {
+  chainId: string;
 }
 
 export type * from './constants.js';

package/src/utils/fees.js

@@ -1,57 +1,142 @@
 import { AmountMath } from '@agoric/ertp';
-import { multiplyBy } from '@agoric/zoe/src/contractSupport/ratio.js';
+import { multiplyBy } from '@agoric/ertp/src/ratio.js';
 import { Fail } from '@endo/errors';
 import { mustMatch } from '@endo/patterns';
+import { chainOfAccount } from '@agoric/orchestration/src/utils/address.js';
 import { FeeConfigShape } from '../type-guards.js';
 
-const { add, isGTE, min, subtract } = AmountMath;
+const { add, isGTE, subtract, makeEmpty } = AmountMath;
 
 /**
- * @import {Amount} from '@agoric/ertp';
+ * @import {Amount, Payment} from '@agoric/ertp';
+ * @import {AccountId} from '@agoric/orchestration';
  * @import {FeeConfig} from '../types.js';
- * @import {RepayAmountKWR} from '../exos/liquidity-pool.js';
  */
 
-/** @param {FeeConfig} feeConfig */
+/**
+ * @typedef {{
+ *  Principal: Amount<'nat'>;
+ *  PoolFee: Amount<'nat'>;
+ *  ContractFee: Amount<'nat'>;
+ *  RelayFee: Amount<'nat'>;
+ * }} RepayAmountKWR
+ */
+
+/**
+ * @typedef {{
+ *  Principal: Payment<'nat'>;
+ *  PoolFee: Payment<'nat'>;
+ *  ContractFee: Payment<'nat'>;
+ *  RelayFee: Payment<'nat'>;
+ * }} RepayPaymentKWR
+ */
+
+/**
+ * @template {keyof Omit<FeeConfig, 'destinationOverrides'>} K
+ * @param {FeeConfig} feeConfig
+ * @param {K} key
+ * @param {AccountId} destination
+ * @returns {FeeConfig[K]}
+ */
+const getConfigValue = (feeConfig, key, destination) => {
+  const chainId = chainOfAccount(destination);
+  if (
+    feeConfig.destinationOverrides?.[chainId] &&
+    feeConfig.destinationOverrides[chainId][key] !== undefined
+  ) {
+    return feeConfig.destinationOverrides[chainId][key];
+  }
+  return feeConfig[key];
+};
+
+/**
+ * @param {FeeConfig} feeConfig
+ */
 export const makeFeeTools = feeConfig => {
   mustMatch(feeConfig, FeeConfigShape, 'Must provide feeConfig');
-  const { flat, variableRate, maxVariable } = feeConfig;
+  const emptyAmount = makeEmpty(feeConfig.flat.brand);
+
   const feeTools = harden({
     /**
-     * Calculate the net amount to advance after withholding fees.
+     * Calculate the base fee to charge for the advance (variable + flat).
+     * Will be shared between the pool and the contract based on
+     * {@link FeeConfig.contractRate}.
      *
      * @param {Amount<'nat'>} requested
-     * @throws {Error} if requested does not exceed fees
+     * @param {AccountId} destination
+     * @returns {Amount<'nat'>}
      */
-    calculateAdvance(requested) {
-      const fee = feeTools.calculateAdvanceFee(requested);
-      return subtract(requested, fee);
+    calculateBaseFee(requested, destination) {
+      const flat = getConfigValue(feeConfig, 'flat', destination);
+      const variableRate = getConfigValue(
+        feeConfig,
+        'variableRate',
+        destination,
+      );
+      return add(multiplyBy(requested, variableRate), flat);
+    },
+    /**
+     * Calculate the optional relay fee charged for certain destinations.
+     * Only disbursed to contract seat.
+     *
+     * @param {AccountId} destination
+     * @returns {Amount<'nat'>}
+     */
+    calculateRelayFee(destination) {
+      const relay = getConfigValue(feeConfig, 'relay', destination);
+      return relay || emptyAmount;
     },
     /**
      * Calculate the total fee to charge for the advance.
      *
      * @param {Amount<'nat'>} requested
+     * @param {AccountId} destination
      * @throws {Error} if requested does not exceed fees
      */
-    calculateAdvanceFee(requested) {
-      const variable = min(multiplyBy(requested, variableRate), maxVariable);
-      const fee = add(variable, flat);
+    calculateAdvanceFee(requested, destination) {
+      const baseFee = feeTools.calculateBaseFee(requested, destination);
+      const relayFee = feeTools.calculateRelayFee(destination);
+      const fee = add(baseFee, relayFee);
       !isGTE(fee, requested) || Fail`Request must exceed fees.`;
       return fee;
     },
+    /**
+     * Calculate the net amount to advance after withholding fees.
+     *
+     * @param {Amount<'nat'>} requested
+     * @param {AccountId} destination
+     * @throws {Error} if requested does not exceed fees
+     */
+    calculateAdvance(requested, destination) {
+      const fee = feeTools.calculateAdvanceFee(requested, destination);
+      return subtract(requested, fee);
+    },
     /**
      * Calculate the split of fees between pool and contract.
      *
+     * The `ContractFee` includes base fees plus the relay fee.
+     *
      * @param {Amount<'nat'>} requested
+     * @param {AccountId} destination
      * @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 });
+    calculateSplit(requested, destination) {
+      const baseFee = feeTools.calculateBaseFee(requested, destination);
+      const relayFee = feeTools.calculateRelayFee(destination);
+      const totalFee = add(baseFee, relayFee);
+      !isGTE(totalFee, requested) || Fail`Request must exceed fees.`;
+
+      const contractRate = getConfigValue(
+        feeConfig,
+        'contractRate',
+        destination,
+      );
+      const Principal = subtract(requested, totalFee);
+      const ContractFee = multiplyBy(baseFee, contractRate);
+      const PoolFee = subtract(baseFee, ContractFee);
+
+      return harden({ Principal, PoolFee, ContractFee, RelayFee: relayFee });
     },
   });
   return feeTools;

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-evidence.ts

@@ -0,0 +1,205 @@
+import { encodeAddressHook } from '@agoric/cosmic-proto/address-hooks.js';
+import type { Bech32Address, CosmosChainAddress } from '@agoric/orchestration';
+import type { CctpTxEvidence, EvmAddress } from '../src/types.js';
+
+export type MockScenario =
+  | 'AGORIC_PLUS_OSMO'
+  | 'AGORIC_PLUS_DYDX'
+  | 'AGORIC_PLUS_AGORIC'
+  | 'AGORIC_NO_PARAMS'
+  | 'AGORIC_UNKNOWN_EUD'
+  | 'AGORIC_PLUS_ETHEREUM'
+  | 'AGORIC_PLUS_NOBLE'
+  | 'AGORIC_PLUS_NOBLE_B32EUD';
+
+export const Senders = {
+  default: '0xDefaultFakeEthereumAddress',
+} as unknown as Record<string, EvmAddress>;
+
+const blockTimestamp = 1632340000n;
+
+export const MockCctpTxEvidences: Record<
+  MockScenario,
+  (receiverAddress?: Bech32Address) => CctpTxEvidence
+> = {
+  AGORIC_PLUS_OSMO: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x90d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee665',
+    blockNumber: 21037663n,
+    blockTimestamp,
+    txHash:
+      '0xc81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff387552761702',
+    tx: {
+      amount: 150000000n,
+      forwardingAddress: 'noble1x0ydg69dh6fqvr27xjvp6maqmrldam6yfelqkd',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'osmo183dejcnmkka5dzcu9xw6mywq0p2m5peks28men',
+        }),
+    },
+    chainId: 1,
+  }),
+  AGORIC_PLUS_DYDX: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x80d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee699',
+    blockNumber: 21037669n,
+    blockTimestamp,
+    txHash:
+      '0xd81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff387552761799',
+    tx: {
+      amount: 300000000n,
+      forwardingAddress: 'noble1x0ydg69dh6fqvr27xjvp6maqmrldam6yfelktz',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'dydx183dejcnmkka5dzcu9xw6mywq0p2m5peks28men',
+        }),
+    },
+    chainId: 1,
+  }),
+  AGORIC_PLUS_AGORIC: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x80d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee6z9',
+    blockNumber: 21037600n,
+    blockTimestamp,
+    txHash:
+      '0xd81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff3875527617z9',
+    tx: {
+      amount: 250000000n,
+      forwardingAddress: 'noble17ww3rfusv895d92c0ncgj0fl9trntn70jz7hd5',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'agoric13rj0cc0hm5ac2nt0sdup2l7gvkx4v9tyvgq3h2',
+        }),
+    },
+    chainId: 1,
+  }),
+  AGORIC_NO_PARAMS: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x70d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee699',
+    blockNumber: 21037669n,
+    blockTimestamp,
+    txHash:
+      '0xa81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff387552761799',
+    tx: {
+      amount: 200000000n,
+      forwardingAddress: 'noble1x0ydg69dh6fqvr27xjvp6maqmrldam6yfelyyy',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress: receiverAddress || settlementAddress.value,
+    },
+    chainId: 1,
+  }),
+  AGORIC_UNKNOWN_EUD: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x70d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee699',
+    blockNumber: 21037669n,
+    blockTimestamp,
+    txHash:
+      '0xa81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff387552761799',
+    tx: {
+      amount: 200000000n,
+      forwardingAddress: 'noble1x0ydg69dh6fqvr27xjvp6maqmrldam6yfelyyy',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'random1addr',
+        }),
+    },
+    chainId: 1,
+  }),
+  AGORIC_PLUS_ETHEREUM: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x80d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee6z9',
+    blockNumber: 21037600n,
+    blockTimestamp,
+    txHash:
+      '0xe81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff3875527617z9',
+    tx: {
+      amount: 950000000n,
+      forwardingAddress: 'noble17ww3rfusv895d92c0ncgj0fl9trntn70jz7ee5',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'eip155:1:0x1234567890123456789012345678901234567890',
+        }),
+    },
+    chainId: 8453,
+  }),
+  AGORIC_PLUS_NOBLE: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x80d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee6z9',
+    blockNumber: 21037600n,
+    blockTimestamp,
+    txHash:
+      '0xe81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff3875527617z9',
+    tx: {
+      amount: 950000000n,
+      forwardingAddress: 'noble17ww3rfusv895d92c0ncgj0fl9trntn70jz7ee5',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'cosmos:noble-1:noble1u2l9za2wa7wvffhtekgyuvyvum06lwhqxfyr5d',
+        }),
+    },
+    chainId: 8453,
+  }),
+  /** Identical to AGORIC_PLUS_NOBLE, but the EUD is a bare bech32 */
+  AGORIC_PLUS_NOBLE_B32EUD: (receiverAddress?: Bech32Address) => ({
+    blockHash:
+      '0x80d7343e04f8160892e94f02d6a9b9f255663ed0ac34caca98544c8143fee6z9',
+    blockNumber: 21037600n,
+    blockTimestamp,
+    txHash:
+      '0xe81bc6105b60a234c7c50ac17816ebcd5561d366df8bf3be59ff3875527617z9',
+    tx: {
+      amount: 950000000n,
+      forwardingAddress: 'noble17ww3rfusv895d92c0ncgj0fl9trntn70jz7ee5',
+      sender: Senders.default,
+    },
+    aux: {
+      forwardingChannel: 'channel-21',
+      recipientAddress:
+        receiverAddress ||
+        encodeAddressHook(settlementAddress.value, {
+          EUD: 'noble1u2l9za2wa7wvffhtekgyuvyvum06lwhqxfyr5d',
+        }),
+    },
+    chainId: 8453,
+  }),
+};
+
+export const settlementAddress: CosmosChainAddress = harden({
+  chainId: 'agoric-3',
+  encoding: 'bech32' as const,
+  // Random value, copied from tests of address hooks
+  value: 'agoric16kv2g7snfc4q24vg3pjdlnnqgngtjpwtetd2h689nz09lcklvh5s8u37ek',
+});

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
-```