@agoric/fast-usdc 0.2.0-u20.0 → 0.2.0-u21.0

package/README.md

@@ -23,5 +23,162 @@ Over time we can update our tooling to decouple this more from the `packages` di
 2. Export bootstrap testing utilities from `@aglocal/boot`, allowing this to be
     above `@aglocal/boot` in the package graph
 3. Update CI to support packages that aren't under `packages/`, eg. a top-level
-   `dapps` directory
+   `dapps` directory. `multichain-testing` does this now but not organized per contract.
 4. Move this package out of agoric-sdk
+
+# Funds flow
+
+```mermaid
+sequenceDiagram
+  actor User as User
+  participant NEA as User Wallet<br>[Browser]
+  participant ETH as CCTP Contract<br>[Ethereum]
+  participant NFA as Noble Forwarding Account<br/>[Noble]
+  participant NC as Noble Chain<br/>[Noble]
+  participant NAR as Noble-Agoric<br/>[IBC Relayer]
+  participant SA as Settlement Account<br/>[Agoric]
+  participant CFA as Contract Fee Account<br/>[Agoric]
+  participant DAR as Destination-Agoric<br/>[IBC Relayer]
+  participant EUD as End User Destination<br/>[Dest Chain]
+
+  autonumber
+  rect rgb(240, 248, 255)
+    User ->> NEA: Sign transaction<br/>(MintAmount, to NFA)
+    NEA ->> ETH: Submit USDC Burn Txn via CCTP
+  end
+  rect rgb(200, 255, 230)
+    FUC ->> P: Initiate PFM transfer(AdvanceAmount, EUD) from pool<br/>of Noble-Agoric tokens to EUD Chain
+    P ->> NC: PFM transfer(AdvanceAmount of Agoric USDC denom) to EUD
+    NC ->> EUD: deliver AdvanceAmount as final USDC denom
+  end
+  Note over User, EUD: User got their AdvanceAmountof IBC USDC<br/>UX COMPLETE
+  rect rgb(255, 200, 200)
+    Note over ETH, SA: Minting Process
+    Note over ETH: ~12 minutes for Ethereum finality
+    Note over NC: 1-6 minutes for CCTP<br/>to Mint on Noble
+    NC ->> NFA: Noble CCTP contract mints USDC<br/> into Noble Forwarding Address
+    NFA ->> NAR: Broadcast Forward MintAmount (as Agoric USDC Denom) to FU Account
+    NAR ->> SA: Relay    
+  end
+  rect rgb(255, 245, 230)
+    Note over FUC, CFA: Settlement Process
+    alt Advance was started:
+      FUC ->> SA: Initiate transfers out of settlement
+      SA ->> P: Deposit the AdvanceAmount + PoolFee (= MintAmount - ContractFee)
+      SA ->> CFA: Deposit ContractFee
+    else Advance for matched transaction that has not yet started:
+      P ->> NC: PFM transfer(MintAmount of Agoric USDC denom) to EUD
+      NC ->> EUD: deliver MintAmount as final USDC denom
+    else Settlement for unknown transaction:
+      Note over SA: Leave funds in SettlementAccount.
+      Note over SA: Wait for observation from watcher
+    end
+  end
+```
+
+Not pictured:
+- Circle Attestation Service
+- CCTP Relayer
+
+"Noble Forwarding Account" is also owned by the CCTP Relayer as they actually register it
+CCTP Relayer can be many parties, but only one when caller is specified
+
+
+# Transaction flow
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#f0f8ff',
+    'primaryTextColor': '#2c3e50',
+    'primaryBorderColor': '#7fb2e6',
+    'lineColor': '#7fb2e6',
+    'secondaryColor': '#f6f8fa',
+    'tertiaryColor': '#fff5e6'
+  }
+}}%%
+sequenceDiagram
+    title Fast USDC Transaction Process
+    autonumber
+    actor User
+    %% [Where it runs]
+    participant NEA as Noble Express app<br/>[Browser]
+    participant ETH as CCTP Contract<br/>[Ethereum]
+    participant NFA as Noble Forwarding Account<br/>[Noble]
+    participant NC as Noble Chain<br/>[Noble]
+    participant NAR as Noble-Agoric<br/>[Relayer]
+    participant OCW as Eth Watcher<br/>[Off-chain]
+    participant FUC as Fast USDC Contract<br/>[Agoric]
+    participant P as Pool<br/>[Agoric]
+    participant SA as Settlement Account<br/>[Agoric]
+    participant CFA as Contract Fee Account<br/>[Agoric]
+    participant DAR as Destination-Agoric<br/>[Relayer]
+    participant EUD as End User Destination<br/>[User]
+
+    %% Notation: --> for async, ->> for sync
+    rect rgb(240, 248, 255)
+        Note over User,OCW: User request
+        Note over NEA: App looks up fees and SettlementAccount address
+        User->>NEA: Input desired MintAmount and EUD
+        NEA->>User: Display fees and AdvanceAmount
+        Note over NEA: Calculate VirtualRecipient from (SettlementAccount, EUD)
+        Note over NEA: Calculate NFA address from (VirtualRecipient) using Signerless forwarding
+        %% Getting from here to the burn is mostly up to Noble
+        User->>NEA: Initiate transfer
+        NEA-->>NC: Register NFA
+        NEA->>User: Request signature
+        User->>NEA: Sign transaction<br/>(MintAmount, to NFA) 
+        NEA->>ETH: Submit USDC Burn Txn via CCTP
+        Note over ETH: Burn succeeds,<br/>implying mint to NFA will happen
+        OCW->>ETH: Query CCTP transactions to Noble
+        ETH-->>OCW: 1 block confirmed
+        OCW->>NC: Look up recipient of NFA<br/>by account query
+        NC->>OCW: RPC replies with account including `recipient` (LCA+EUD)
+    end
+
+    Note over OCW: Continue if recipient is over the Noble-Agoric channel
+    rect rgb(200, 255, 230)
+        Note over NC,EUD: Advancement Process
+        Note over OCW: Log proof of each confirmation
+        Note over OCW,FUC: Provide info needed by policy to make a decision
+        OCW->>FUC: Notify of each confirmation<br/>(dest=agoric1 recipient, amount,<br/>metadata=transaction-nonce,chain,block,timestamp)
+        Note over FUC: MM's policy decides whether to advance (e.g. 2 confirmations from Ethereum, 5 from Polygon)
+        Note over FUC: Syslog with sufficient detail to debug
+        Note over FUC: calculate AdvanceAmount = (MintAmount – PoolFee - ContractFee)<br/>based on fee rates at this moment, and record for future lookup
+        FUC->>P: Initiate PFM transfer(AdvanceAmount, EUD) from pool<br/>of Noble-Agoric tokens to EUD Chain
+        P->>NC: PFM transfer(AdvanceAmount of Agoric USDC denom) to EUD
+        NC->>EUD: deliver AdvanceAmount as final USDC denom
+        %% TODO do need epsilon tolerance on MintAmount for if Noble takes a small cut of the minted amount
+        %% TODO map out the event handling for these states: START: only-observed,advance-started,received-minted-unobserved, END: done
+        Note over SA: Wake up the settlement process to handle observed (key=EUD,MintAmount)
+
+    end
+    Note over User,EUD: User got their AdvanceAmountof IBC USDC<br/>UX COMPLETE
+
+    rect rgb(255, 200, 200)
+        Note over ETH,SA: Minting Process
+        Note over ETH: ~12 minutes for Ethereum finality
+        Note over NC: 1-6 minutes for CCTP<br/>to Mint on Noble
+        NC->>NFA: Noble CCTP contract mints USDC<br/> into Noble Forwarding Address
+        NFA->>SA: Forward MintAmount (as Agoric USDC Denom) to FU Account
+    end
+
+    rect rgb(255, 245, 230)
+        Note over FUC,CFA: Settlement Process
+        Note over FUC,SA: Tap on account reads MintAmount,<br/>parses EUD from virtual address recipient<br/>and looks up AdvanceAmount,PoolFee,ContractFee.<br/>Matches against an unsettled transaction (by EUD and approx amount).
+        %% Treat starting the advance as an atomic action. Assume it will complete once started.
+        alt Advance was started:
+            FUC->>SA: Initiate transfers out of settlement
+            SA->>P: Deposit the AdvanceAmount + PoolFee (= MintAmount - ContractFee)
+            SA->>CFA: Deposit ContractFee
+        else Advance for matched transaction that has not yet started:
+            P->>NC: PFM transfer(MintAmount of Agoric USDC denom) to EUD
+            NC->>EUD: deliver MintAmount as final USDC denom
+        else Settlement for unknown transaction:
+            %% Have not received notification of this Amount,EUD from the watcher
+            Note over SA: Leave funds in SettlementAccount.
+            Note over SA: Wait for observation from watcher
+        end
+    end
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/fast-usdc",
-  "version": "0.2.0-u20.0",
+  "version": "0.2.0-u21.0",
   "description": "CLI and library for Fast USDC product",
   "type": "module",
   "files": [
@@ -8,34 +8,32 @@
     "tools"
   ],
   "main": "src/main.js",
-  "bin": {
-    "fast-usdc": "./src/cli/bin.js"
-  },
+  "bin": "./src/cli/bin.js",
   "scripts": {
     "build": "exit 0",
     "test": "ava",
     "test:c8": "c8 --all $C8_OPTIONS ava",
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc",
-    "lint:eslint": "eslint ."
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:eslint": "yarn run -T eslint .",
+    "lint:types": "yarn run -T tsc"
   },
   "devDependencies": {
     "@fast-check/ava": "^2.0.1",
     "ava": "^5.3.0",
-    "c8": "^10.1.2",
-    "nano-spawn": "^0.2.0",
-    "ts-blank-space": "^0.4.4"
+    "c8": "^10.1.3",
+    "nano-spawn": "^1.0.2",
+    "ts-blank-space": "^0.6.1"
   },
   "dependencies": {
-    "@agoric/client-utils": "^0.2.0-u20.0",
-    "@agoric/cosmic-proto": "^0.5.0-u20.0",
-    "@agoric/ertp": "^0.16.3-u20.0",
-    "@agoric/internal": "^0.4.0-u20.0",
-    "@agoric/notifier": "^0.7.0-u20.0",
-    "@agoric/orchestration": "^0.2.0-u20.0",
-    "@agoric/zoe": "^0.27.0-u20.0",
+    "@agoric/client-utils": "workspace:*",
+    "@agoric/cosmic-proto": "workspace:*",
+    "@agoric/ertp": "workspace:*",
+    "@agoric/internal": "workspace:*",
+    "@agoric/notifier": "workspace:*",
+    "@agoric/orchestration": "workspace:*",
+    "@agoric/zoe": "workspace:*",
     "@cosmjs/proto-signing": "^0.33.0",
     "@cosmjs/stargate": "^0.33.0",
     "@endo/base64": "^1.0.9",
@@ -75,5 +73,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8e4207fa19dabf76c1f91f8779b5b5b93570ecea"
+  "gitHead": "e4dd46857133403d584bcf822a81817b355532f9"
 }

package/src/cli/cli.js

@@ -12,7 +12,7 @@ import {
 import { addConfigCommands } from './config-commands.js';
 import { addOperatorCommands } from './operator-commands.js';
 import * as configLib from './config.js';
-import transferLib from './transfer.js';
+import * as transferLib from './transfer.js';
 import { makeFile } from './util/file.js';
 import { addLPCommands } from './lp-commands.js';
 

package/src/cli/transfer.js

@@ -21,7 +21,7 @@ import { queryUSDCBalance } from './util/bank.js';
 /** @import { SigningStargateClient } from '@cosmjs/stargate' */
 /** @import { JsonRpcProvider as ethProvider } from 'ethers' */
 
-const transfer = async (
+export const transfer = async (
   /** @type {File} */ configFile,
   /** @type {string} */ amount,
   /** @type {string} */ EUD,
@@ -137,5 +137,3 @@ const transfer = async (
   }
   await execute(config);
 };
-
-export default { transfer };

package/src/cli/util/agoric.js

@@ -4,9 +4,8 @@ export const queryFastUSDCLocalChainAccount = async (
   /** @type {VStorage} */ vstorage,
   out = console,
 ) => {
-  const agoricAddr = await vstorage.readLatest(
-    'published.fastUsdc.settlementAccount',
-  );
-  out.log(`Got Fast USDC Local Chain Account ${agoricAddr}`);
-  return agoricAddr;
+  const { value } = await vstorage.readLatest('published.fastUsdc');
+  const { settlementAccount } = JSON.parse(JSON.parse(value).values[0]);
+  out.log(`settlementAccount: ${settlementAccount}`);
+  return settlementAccount;
 };

package/src/constants.js

@@ -16,6 +16,8 @@ export const TxStatus = /** @type {const} */ ({
   AdvanceSkipped: 'ADVANCE_SKIPPED',
   /** settlement for matching advance received and funds disbursed */
   Disbursed: 'DISBURSED',
+  /** No route, forward not attempted */
+  ForwardedSkipped: 'FORWARD_SKIPPED',
   /** fallback: do not collect fees */
   Forwarded: 'FORWARDED',
   /** failed to forward to EUD */
@@ -36,8 +38,6 @@ export const TerminalTxStatus = {
  * @enum {(typeof PendingTxStatus)[keyof typeof PendingTxStatus]}
  */
 export const PendingTxStatus = /** @type {const} */ ({
-  /** tx was observed but not advanced */
-  Observed: 'OBSERVED',
   /** IBC transfer is initiated */
   Advancing: 'ADVANCING',
   /** IBC transfer failed (timed out) */

package/src/type-guards.js

@@ -110,6 +110,7 @@ harden(AddressHookShape);
 
 const NatAmountShape = { brand: BrandShape, value: M.nat() };
 
+/** @type {TypedPattern<FeeConfig['destinationOverrides']>} */
 export const DestinationOverridesShape = M.recordOf(
   M.string(),
   M.splitRecord(

package/src/types.ts

@@ -1,17 +1,17 @@
+import type { Amount } from '@agoric/ertp';
 import type {
   AccountId,
-  CosmosChainAddress,
+  BaseChainInfo,
   Bech32Address,
+  CaipChainId,
+  CosmosChainAddress,
   CosmosChainInfo,
   Denom,
   DenomDetail,
-  BaseChainInfo,
   KnownNamespace,
-  CaipChainId,
 } from '@agoric/orchestration';
 import type { IBCChannelID } from '@agoric/vats';
-import type { Amount } from '@agoric/ertp';
-import type { CopyRecord, Passable } from '@endo/pass-style';
+import type { CopyRecord } from '@endo/pass-style';
 import type { PendingTxStatus, TxStatus } from './constants.js';
 import type { RepayAmountKWR } from './utils/fees.js';
 
@@ -70,7 +70,7 @@ export interface CctpTxEvidence {
   txHash: EvmHash;
 }
 
-export interface EvidenceWithRisk {
+export interface EvidenceWithRisk extends CopyRecord {
   evidence: CctpTxEvidence;
   risk: RiskAssessment;
 }

package/tools/mock-evidence.ts

@@ -2,18 +2,15 @@ import { encodeAddressHook } from '@agoric/cosmic-proto/address-hooks.js';
 import type { Bech32Address, CosmosChainAddress } from '@agoric/orchestration';
 import type { CctpTxEvidence, EvmAddress } from '../src/types.js';
 
-const mockScenarios = [
-  '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',
-] as const;
-
-export type MockScenario = (typeof mockScenarios)[number];
+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',