Orch api factoring

.github/workflows/test-all-packages.yml

@@ -48,9 +48,23 @@ jobs:
       - name: Install graphviz
         run: sudo apt install -y graphviz
 
+      # This is now redundant with Lerna's --reject-cycles but keep it here so we have
+      # test coverage of this script we use for visualizing the dep graph.
       - name: Check for cycles
         run: scripts/check-dependency-cycles.sh
 
+      # install node_modules
+      - uses: ./.github/actions/restore-node
+
+      # Releasing SDK builds all packages in this order during `lerna publish`.
+      # Due to ambient types, certain build orders (from the dependency graph)
+      # may break the type resolution. Run this in the PR to find out before
+      # attempting to merge to master. This takes about 1min locally and since
+      # this job is about 30s in CI doing it here doesn't add to wall wait
+      # for CI resolution.
+      - name: Pack packages
+        run: yarn lerna exec --reject-cycles --concurrency 1 "npm pack"
+
   ##################
   # Lint tests
   # We run per package bc of https://github.com/typescript-eslint/typescript-eslint/issues/1192

packages/inter-protocol/package.json

@@ -11,7 +11,7 @@
     "build": "yarn build:bundles",
     "build:bundles": "node ./scripts/build-bundles.js",
     "prepack": "tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' src/types.js",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:xs": "exit 0",

packages/notifier/package.json

@@ -10,7 +10,7 @@
   "scripts": {
     "build": "exit 0",
     "prepack": "tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' src/types.js",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:xs": "exit 0",

packages/orchestration/index.js

@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/export
 export * from './src/types.js';
 export * from './src/service.js';
 export * from './src/typeGuards.js';

packages/orchestration/package.json

@@ -10,6 +10,8 @@
   },
   "scripts": {
     "build": "exit 0",
+    "prepack": "tsc --build tsconfig.build.json",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:xs": "exit 0",
     "lint": "run-s --continue-on-error lint:*",

packages/orchestration/src/chain-info.ts

@@ -0,0 +1,64 @@
+/**
+ * @file static declaration of known chain types will allow type support for
+ * additional chain-specific operations like `liquidStake`
+ */
+
+import type {
+  CosmosChainInfo,
+  EthChainInfo,
+  IcaAccount,
+  ICQConnection,
+  LiquidStakingMethods,
+  StakingAccountActions,
+  StakingAccountQueries,
+} from './types.js';
+
+// TODO generate this automatically with a build script drawing on data sources such as https://github.com/cosmos/chain-registry
+
+// XXX methods ad-hoc and not fully accurate
+export type KnownChains = {
+  stride: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries &
+      LiquidStakingMethods;
+  };
+  cosmos: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+  agoric: {
+    info: CosmosChainInfo;
+    methods: {
+      // TODO reference type from #8624 `packages/vats/src/localchain.js`
+      /**
+       * Register a hook to intercept an incoming IBC Transfer and handle it.
+       * Calling without arguments will unregister the hook.
+       */
+      interceptTransfer: (tap?: {
+        upcall: (args: any) => Promise<any>;
+      }) => Promise<void>;
+    };
+  };
+  celestia: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+  osmosis: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+};
+
+export type ChainInfo = CosmosChainInfo | EthChainInfo;

packages/orchestration/src/cosmos-api.ts

@@ -0,0 +1,199 @@
+import type { AnyJson } from '@agoric/cosmic-proto';
+import type {
+  Delegation,
+  Redelegation,
+  UnbondingDelegation,
+} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
+import type { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
+import type { Brand, Payment, Purse } from '@agoric/ertp/exported.js';
+import type { Port } from '@agoric/network';
+import type {
+  LocalIbcAddress,
+  RemoteIbcAddress,
+} from '@agoric/vats/tools/ibc-utils.js';
+import type { AmountArg, ChainAddress, DenomAmount } from './types.js';
+
+/** A helper type for type extensions. */
+export type TypeUrl = string;
+
+// TODO move into cosmic-proto
+export type Proto3JSONMsg = {
+  '@type': TypeUrl;
+  value: Record<string, unknown>;
+};
+
+/** An address for a validator on some blockchain, e.g., cosmos, eth, etc. */
+export type CosmosValidatorAddress = ChainAddress & {
+  // TODO document why this is the format
+  address: `${string}valoper${string}`;
+  addressEncoding: 'bech32';
+};
+
+/**
+ * Info for a Cosmos-based chain.
+ */
+export type CosmosChainInfo = {
+  chainId: string;
+  ibcConnectionInfo: {
+    id: string; // e.g. connection-0
+    client_id: string; // '07-tendermint-0'
+    state: 'OPEN' | 'TRYOPEN' | 'INIT' | 'CLOSED';
+    counterparty: {
+      client_id: string;
+      connection_id: string;
+      prefix: {
+        key_prefix: string;
+      };
+    };
+    versions: { identifier: string; features: string[] }[];
+    delay_period: bigint;
+  };
+  icaEnabled: boolean;
+  icqEnabled: boolean;
+  pfmEnabled: boolean;
+  ibcHooksEnabled: boolean;
+  /**
+   *
+   */
+  allowedMessages: TypeUrl[];
+  allowedQueries: TypeUrl[];
+};
+
+export interface StakingAccountQueries {
+  /**
+   * @returns all active delegations from the account to any validator (or [] if none)
+   */
+  getDelegations: () => Promise<Delegation[]>;
+
+  /**
+   * @returns the active delegation from the account to a specific validator. Return an
+   * empty Delegation if there is no delegation.
+   */
+  getDelegation: (validator: CosmosValidatorAddress) => Promise<Delegation>;
+
+  /**
+   * @returns the unbonding delegations from the account to any validator (or [] if none)
+   */
+  getUnbondingDelegations: () => Promise<UnbondingDelegation[]>;
+
+  /**
+   * @returns the unbonding delegations from the account to a specific validator (or [] if none)
+   */
+  getUnbondingDelegation: (
+    validator: CosmosValidatorAddress,
+  ) => Promise<UnbondingDelegation>;
+
+  getRedelegations: () => Promise<Redelegation[]>;
+
+  getRedelegation: (
+    srcValidator: CosmosValidatorAddress,
+    dstValidator?: CosmosValidatorAddress,
+  ) => Promise<Redelegation>;
+
+  /**
+   * Get the pending rewards for the account.
+   * @returns the amounts of the account's rewards pending from all validators
+   */
+  getRewards: () => Promise<DenomAmount[]>;
+
+  /**
+   * Get the rewards pending with a specific validator.
+   * @param validator - the validator address to query for
+   * @returns the amount of the account's rewards pending from a specific validator
+   */
+  getReward: (validator: CosmosValidatorAddress) => Promise<DenomAmount[]>;
+}
+export interface StakingAccountActions {
+  /**
+   * Delegate an amount to a validator. The promise settles when the delegation is complete.
+   * @param validator - the validator to delegate to
+   * @param amount  - the amount to delegate
+   * @returns void
+   */
+  delegate: (
+    validator: CosmosValidatorAddress,
+    amount: AmountArg,
+  ) => Promise<void>;
+
+  /**
+   * Redelegate from one delegator to another.
+   * Settles when the redelegation is established, not 21 days later.
+   * @param srcValidator - the current validator for the delegation.
+   * @param dstValidator - the validator that will receive the delegation.
+   * @param amount - how much to redelegate.
+   * @returns
+   */
+  redelegate: (
+    srcValidator: CosmosValidatorAddress,
+    dstValidator: CosmosValidatorAddress,
+    amount: AmountArg,
+  ) => Promise<void>;
+
+  /**
+   * Undelegate multiple delegations (concurrently). To delegate independently, pass an array with one item.
+   * Resolves when the undelegation is complete and the tokens are no longer bonded. Note it may take weeks.
+   * The unbonding time is padded by 10 minutes to account for clock skew.
+   * @param {Delegation[]} delegations - the delegation to undelegate
+   */
+  undelegate: (delegations: Delegation[]) => Promise<void>;
+
+  /**
+   * Withdraw rewards from all validators. The promise settles when the rewards are withdrawn.
+   * @returns The total amounts of rewards withdrawn
+   */
+  withdrawRewards: () => Promise<DenomAmount[]>;
+
+  /**
+   * Withdraw rewards from a specific validator. The promise settles when the rewards are withdrawn.
+   * @param validator - the validator to withdraw rewards from
+   * @returns
+   */
+  withdrawReward: (validator: CosmosValidatorAddress) => Promise<DenomAmount[]>;
+}
+
+/**
+ * Low level object that supports queries and operations for an account on a remote chain.
+ */
+export interface IcaAccount {
+  /**
+   * @returns the address of the account on the remote chain
+   */
+  getAddress: () => ChainAddress;
+
+  /**
+   * Submit a transaction on behalf of the remote account for execution on the remote chain.
+   * @param msgs - records for the transaction
+   * @returns acknowledgement string
+   */
+  executeTx: (msgs: Proto3JSONMsg[]) => Promise<string>;
+  /**
+   * Submit a transaction on behalf of the remote account for execution on the remote chain.
+   * @param {AnyJson[]} msgs - records for the transaction
+   * @param {Partial<Omit<TxBody, 'messages'>>} [opts] - optional parameters for the Tx, like `timeoutHeight` and `memo`
+   * @returns acknowledgement string
+   */
+  executeEncodedTx: (
+    msgs: AnyJson[],
+    opts?: Partial<Omit<TxBody, 'messages'>>,
+  ) => Promise<string>;
+  /** deposit payment from zoe to the account*/
+  deposit: (payment: Payment) => Promise<void>;
+  /** get Purse for a brand to .withdraw() a Payment from the account */
+  getPurse: (brand: Brand) => Promise<Purse>;
+  /**
+   * Close the remote account
+   */
+  close: () => Promise<void>;
+  /* transfer account to new holder */
+  prepareTransfer: () => Promise<Invitation>;
+  /** @returns the address of the remote channel */
+  getRemoteAddress: () => RemoteIbcAddress;
+  /** @returns the address of the local channel */
+  getLocalAddress: () => LocalIbcAddress;
+  /** @returns the port the ICA channel is bound to */
+  getPort: () => Port;
+}
+
+export type LiquidStakingMethods = {
+  liquidStake: (amount: AmountArg) => Promise<void>;
+};

packages/orchestration/src/ethereum-api.ts

@@ -0,0 +1,7 @@
+/**
+ * Info for an Ethereum-based chain.
+ */
+export type EthChainInfo = {
+  chainId: string;
+  allegedName: string;
+};

packages/orchestration/src/examples/stakeAtom.contract.js

@@ -1,4 +1,3 @@
-// @ts-check
 /**
  * @file Example contract that uses orchestration
  */

packages/orchestration/src/examples/stakeBld.contract.js

@@ -1,4 +1,3 @@
-// @ts-check
 /**
  * @file Stake BLD contract
  *

packages/orchestration/src/examples/swapExample.contract.js

@@ -1,4 +1,3 @@
-// @ts-check
 import { Fail } from '@agoric/assert';
 import { AmountMath, AmountShape } from '@agoric/ertp';
 import { E, Far } from '@endo/far';
@@ -7,7 +6,7 @@ import { makeOrchestrationFacade } from '../facade.js';
 import { orcUtils } from '../utils/orc.js';
 
 /**
- * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
  * @import {TimerService} from '@agoric/time';
  * @import {ERef} from '@endo/far'
  * @import {OrchestrationService} from '../service.js';
@@ -35,7 +34,7 @@ export const start = async (zcf, privateArgs) => {
   });
 
   /** deprecated historical example */
-  /** @type {OfferHandler} */
+  /** @type {OfferHandler<unknown, {staked: Amount<'nat'>, validator: CosmosValidatorAddress}>} */
   const swapAndStakeHandler = orchestrate(
     'LSTTia',
     { zcf },

packages/orchestration/src/examples/unbondExample.contract.js

@@ -1,12 +1,11 @@
-// @ts-check
 import { Fail } from '@agoric/assert';
 import { AmountMath, AmountShape } from '@agoric/ertp';
 import { Far } from '@endo/far';
 import { M } from '@endo/patterns';
 import { makeOrchestrationFacade } from '../facade.js';
 
 /**
- * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
  * @import {TimerService} from '@agoric/time';
  * @import {ERef} from '@endo/far'
  * @import {OrchestrationService} from '../service.js';

packages/orchestration/src/exos/chainAccountKit.js

@@ -1,4 +1,3 @@
-// @ts-check
 /** @file ChainAccount exo */
 
 // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512

packages/orchestration/src/exos/icqConnectionKit.js

@@ -1,4 +1,3 @@
-// @ts-check
 /** @file ICQConnection Exo */
 import { NonNullish } from '@agoric/assert';
 import { makeTracer } from '@agoric/internal';

packages/orchestration/src/exos/localchainAccountKit.js

@@ -1,4 +1,3 @@
-// @ts-check
 /** @file Use-object for the owner of a localchain account */
 import { typedJson } from '@agoric/cosmic-proto/vatsafe';
 import { AmountShape } from '@agoric/ertp';