@agoric/portfolio-api 0.1.1-dev-159ee8a.0.159ee8a → 0.1.1-dev-6deecfc.0.6deecfc

package/README.md

@@ -1,3 +1,41 @@
 # Portfolio management API
 
 API shared between on-chain contract and external clients
+
+## YDS Target Balances
+
+The YMax Data Service (YDS) should import the shared target-balance helper and
+production network data from this public package. `@agoric/portfolio-api`
+participates in the repo's after-merge canary publish flow, so production
+network changes can propagate without waiting for `@aglocal/portfolio-contract`
+packaging.
+
+```js
+import { computeTargetBalances } from '@agoric/portfolio-api/src/target-balances.js';
+import { PROD_NETWORK } from '@agoric/portfolio-api/src/network/prod-network.js';
+
+const changedTargets = computeTargetBalances({
+  brand: usdcBrand,
+  currentBalances,
+  balanceDelta,
+  targetAllocation,
+  network: PROD_NETWORK,
+  depositFromChain,
+});
+```
+
+`changedTargets` contains only balances that need to change. Use signed
+minor-unit deltas: positive for deposits, negative for withdrawals, and `0n` for
+rebalances.
+
+Relevant explicit `package.json` subpath exports are:
+
+- `./src/target-balances.js`
+- `./src/network/prod-network.js`
+- `./src/network/network-spec.js`
+- `./src/places.js`
+- `./src/type-guards.js`
+- `./src/evm-wallet/eip712-messages.js`
+- `./src/evm-wallet/message-handler-helpers.js`
+
+Keep importing the `.js` subpaths so the same source works after packaging.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/portfolio-api",
-  "version": "0.1.1-dev-159ee8a.0.159ee8a",
+  "version": "0.1.1-dev-6deecfc.0.6deecfc",
   "description": "API for Portfolio management",
   "repository": {
     "type": "git",
@@ -12,6 +12,20 @@
     "tools"
   ],
   "main": "src/main.js",
+  "exports": {
+    ".": "./src/main.js",
+    "./src/constants.js": "./src/constants.js",
+    "./src/evm-wallet/eip712-messages.js": "./src/evm-wallet/eip712-messages.js",
+    "./src/evm-wallet/message-handler-helpers.js": "./src/evm-wallet/message-handler-helpers.js",
+    "./src/network/network-spec.js": "./src/network/network-spec.js",
+    "./src/network/prod-network.js": "./src/network/prod-network.js",
+    "./src/places.js": "./src/places.js",
+    "./src/portfolio-constants.js": "./src/portfolio-constants.js",
+    "./src/resolver.js": "./src/resolver.js",
+    "./src/target-balances.js": "./src/target-balances.js",
+    "./src/type-guards.js": "./src/type-guards.js",
+    "./package.json": "./package.json"
+  },
   "bin": "./src/cli/bin.js",
   "scripts": {
     "build": "exit 0",
@@ -31,8 +45,8 @@
     "generate:ymax-machine": "npx tsx scripts/gen-ymax-machine.mts"
   },
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-159ee8a.0.159ee8a",
-    "@agoric/orchestration": "0.1.1-dev-159ee8a.0.159ee8a",
+    "@agoric/internal": "0.3.3-dev-6deecfc.0.6deecfc",
+    "@agoric/orchestration": "0.1.1-dev-6deecfc.0.6deecfc",
     "@endo/common": "^1.2.13",
     "@endo/errors": "^1.2.13",
     "@endo/patterns": "^1.7.0"
@@ -73,5 +87,5 @@
   "engines": {
     "node": "^20.9 || ^22.11"
   },
-  "gitHead": "159ee8acf8ecd2c46a15d34a46b344de65f7e099"
+  "gitHead": "6deecfc17452ceb1faae9290b8f76112cc4f26a1"
 }

package/src/main.d.ts

@@ -1,6 +1,8 @@
 export * from "./constants.js";
 export * from "./instruments.js";
+export * from "./network/prod-network.js";
 export * from "./resolver.js";
+export * from "./target-balances.js";
 export * from "./type-guards.js";
 export * from "./types-index.js";
 //# sourceMappingURL=main.d.ts.map

package/src/main.js

@@ -1,6 +1,8 @@
 export * from './constants.js';
 export * from './instruments.js';
+export * from './network/prod-network.js';
 export * from './resolver.js';
+export * from './target-balances.js';
 export * from './type-guards.js';
 
 // eslint-disable-next-line import/export -- just types

package/src/network/network-spec.d.ts

@@ -0,0 +1,88 @@
+import type { NatValue } from '@agoric/ertp';
+import type { SupportedChain, YieldProtocol } from '../constants.js';
+import type { InstrumentId } from '../instruments.js';
+import type { AssetPlaceRef } from '../types.js';
+export type ControlProtocol = 'ibc' | 'axelar' | 'local';
+export type TransferProtocol = 'ibc' | 'fastusdc' | 'cctpFromNoble' | 'cctpToNoble' | 'cctpV2' | 'local';
+/**
+ * Link to Factory and Wallet contracts:
+ * https://github.com/agoric-labs/agoric-to-axelar-local/blob/cd6087fa44de3b019b2cdac6962bb49b6a2bc1ca/packages/axelar-local-dev-cosmos/src/__tests__/contracts/Factory.sol
+ *
+ * Steps submitted to the contract are expected to include fee/gas payment
+ * details which vary by the traversed link.
+ * - toUSDN: transferring into USDN transfer reduces the *payload* (e.g., $10k
+ *   might get reduced to $9995)
+ * - makeEvmAccount: the fee for executing the Factory contract to create a new
+ *   remote wallet
+ * - evmToNoble: the fee for running the tx to send tokens from the remote
+ *   wallet to Noble
+ * - evmToPool: the fee for sending and executing a tx on the Wallet contract
+ *   to supply tokens to a specified pool
+ * - poolToEvm: the fee for sending and executing a tx on the Wallet contract
+ *   to withdraw tokens from a specified pool
+ */
+export type FeeMode = 'toUSDN' | 'makeEvmAccount' | 'evmToNoble' | 'evmToPool' | 'poolToEvm' | 'evmToEvm';
+export interface ChainSpec {
+    readonly name: SupportedChain;
+    /** how agoric reaches this chain: 'ibc' (noble) or 'axelar' (EVM) or 'local' */
+    readonly control: ControlProtocol;
+    /** minimum delta amount for planned moves involving this chain */
+    readonly deltaSoftMin?: NatValue;
+}
+type BlockWithdrawReason = 'LOW_LIQUIDITY';
+type BlockDepositReason = BlockWithdrawReason | 'AT_CAPACITY';
+export type PoolKey = InstrumentId;
+export interface PoolSpec {
+    readonly pool: PoolKey;
+    /** host chain of the corresponding instrument */
+    readonly chain: SupportedChain;
+    /** protocol of the corresponding instrument */
+    readonly protocol: YieldProtocol;
+    /** when increases are unavailable, the (primary) reason why */
+    readonly blockDepositReason?: BlockDepositReason;
+    /** when decreases are unavailable, the (primary) reason why */
+    readonly blockWithdrawReason?: BlockWithdrawReason;
+}
+/**
+ * A +agoric local account or <Deposit>/<Cash> Agoric blockchain contract seat.
+ */
+export interface LocalPlaceSpec {
+    readonly id: '<Deposit>' | '<Cash>' | '+agoric';
+    readonly chain: 'agoric';
+}
+/**
+ * A directed edge from one place to another, usually having at least one hub
+ * endpoint.
+ */
+export interface LinkSpec {
+    readonly src: AssetPlaceRef;
+    readonly dest: AssetPlaceRef;
+    /**
+     * variable transfer fee in basis points to be applied against the transferred
+     * amount of major units (e.g., USDC)
+     */
+    readonly variableFeeBps: number;
+    /** flat-rate transfer fee in minor units (e.g., uusdc) */
+    readonly flatFee?: NatValue;
+    /** expected transfer settlement time in seconds */
+    readonly timeSec: number;
+    /** inclusive maximum transfer amount in minor units (e.g., uusdc) */
+    readonly capacity?: NatValue;
+    /** inclusive minimum transfer amount in minor units (e.g., uusdc) */
+    readonly min?: NatValue;
+    /** mechanism by which the transfer occurs */
+    readonly transfer: TransferProtocol;
+    /** designator for how fees apply to transactions over this link */
+    readonly feeMode?: FeeMode;
+}
+/** Details of how chains/pools/etc. and how they connect. */
+export interface NetworkSpec {
+    readonly debug?: boolean;
+    readonly environment?: 'dev' | 'test' | 'prod';
+    readonly chains: ChainSpec[];
+    readonly pools: PoolSpec[];
+    readonly localPlaces?: LocalPlaceSpec[];
+    readonly links: LinkSpec[];
+}
+export {};
+//# sourceMappingURL=network-spec.d.ts.map

package/src/network/network-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-spec.d.ts","sourceRoot":"","sources":["network-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,gBAAgB,GACxB,KAAK,GACL,UAAU,GACV,eAAe,GACf,aAAa,GACb,QAAQ,GACR,OAAO,CAAC;AACZ;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,WAAW,GACX,UAAU,CAAC;AAGf,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;CAClC;AAID,KAAK,mBAAmB,GAAG,eAAe,CAAC;AAC3C,KAAK,kBAAkB,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAE9D,MAAM,MAAM,OAAO,GAAG,YAAY,CAAC;AAGnC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,+DAA+D;IAC/D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAE5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;IAExB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAE/C,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;CAC5B"}

package/src/network/network-spec.js

@@ -0,0 +1,115 @@
+                                             
+                                                                     
+                                                      
+                                                 
+
+// Control and transfer planes
+                                                         
+                              
+         
+              
+                   
+                                                    
+            
+            
+/**
+ * Link to Factory and Wallet contracts:
+ * https://github.com/agoric-labs/agoric-to-axelar-local/blob/cd6087fa44de3b019b2cdac6962bb49b6a2bc1ca/packages/axelar-local-dev-cosmos/src/__tests__/contracts/Factory.sol
+ *
+ * Steps submitted to the contract are expected to include fee/gas payment
+ * details which vary by the traversed link.
+ * - toUSDN: transferring into USDN transfer reduces the *payload* (e.g., $10k
+ *   might get reduced to $9995)
+ * - makeEvmAccount: the fee for executing the Factory contract to create a new
+ *   remote wallet
+ * - evmToNoble: the fee for running the tx to send tokens from the remote
+ *   wallet to Noble
+ * - evmToPool: the fee for sending and executing a tx on the Wallet contract
+ *   to supply tokens to a specified pool
+ * - poolToEvm: the fee for sending and executing a tx on the Wallet contract
+ *   to withdraw tokens from a specified pool
+ */
+                     
+            
+                    
+                
+               
+               
+               
+
+// Chains (hubs)
+                            
+                                
+                                                                                  
+                                    
+                                                                    
+                                   
+ 
+
+// Any reason to block withdrawal is by extension also a reason to block
+// deposit.
+                                           
+                                                              
+
+                                   
+
+// Pools (leaves)
+                           
+                         
+                                                   
+                                 
+                                                 
+                                   
+                                                                 
+                                                   
+                                                                 
+                                                     
+ 
+
+/**
+ * A +agoric local account or <Deposit>/<Cash> Agoric blockchain contract seat.
+ */
+                                 
+                                                  
+                           
+ 
+
+/**
+ * A directed edge from one place to another, usually having at least one hub
+ * endpoint.
+ */
+                           
+                              
+                               
+
+     
+                                                                                
+                                       
+     
+                                  
+                                                            
+                              
+
+                                                     
+                           
+                                                                       
+                               
+                                                                       
+                          
+
+                                               
+                                      
+                                                                     
+                             
+ 
+
+/** Details of how chains/pools/etc. and how they connect. */
+                              
+                           
+                                                 
+
+                               
+                             
+                                          
+                             
+ 

package/src/network/prod-network.d.ts

@@ -0,0 +1,4 @@
+import type { NetworkSpec } from './network-spec.js';
+export declare const PROD_NETWORK: NetworkSpec;
+export default PROD_NETWORK;
+//# sourceMappingURL=prod-network.d.ts.map

package/src/network/prod-network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prod-network.d.ts","sourceRoot":"","sources":["prod-network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAerD,eAAO,MAAM,YAAY,EAAE,WA6XzB,CAAC;AAEH,eAAe,YAAY,CAAC"}