@agoric/orchestration 0.1.1-dev-6b5e706.0 → 0.1.1-dev-2dc53d7.0

package/src/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["facade.js"],"names":[],"mappings":"AAmBO;;;SALG,IAAI,CAAC,GAAG,CAAC;iBACD,IAAI,CAAC,WAAW,CAAC;;;;;;;;;;IAoB/B;;;;;;;OAOG;gBAFkC,OAAO,EACrB,IAAI,6BAHhB,MAAM,OAEoB,OAAO,AAD1B,gCACmB,OAAO,WACrB,IAAI,AADgC,KAAK,MAAM,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC;EAOnD;kCAEa,UAAU,CAAC,OAAO,uBAAuB,CAAC;0BA/CjC,cAAc;kCACN,cAAc;kCAEd,YAAY"}

package/src/facade.js

@@ -1,11 +1,10 @@
-// @ts-check
 /** @file Orchestration service */
 
 /**
  * @import {Zone} from '@agoric/zone';
  * @import {TimerService} from '@agoric/time';
  * @import {OrchestrationService} from './service.js';
- * @import {OrchestrationHandlerMaker} from './types.js';
+ * @import {Orchestrator} from './types.js';
  */
 
 /**
@@ -35,7 +34,12 @@ export const makeOrchestrationFacade = ({
 
   return {
     /**
-     * @type {OrchestrationHandlerMaker}
+     * @template Context
+     * @template {any[]} Args
+     * @param {string} durableName
+     * @param {Context} ctx
+     * @param {(orc: Orchestrator, ctx2: Context, ...args: Args) => object} fn
+     * @returns {(...args: Args) => Promise<unknown>}
      */
     orchestrate(durableName, ctx, fn) {
       console.log('orchestrate got', durableName, ctx, fn);

package/src/orchestration-api.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @file General API of orchestration
+ * - must not have chain-specific types without runtime narrowing by chain id
+ * - should remain relatively stable.
+ */
+import type { Amount, Brand, NatAmount, Payment } from '@agoric/ertp/exported.js';
+import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
+import type { Timestamp } from '@agoric/time';
+import type { KnownChains } from './types.js';
+/**
+ * A denom that designates a path to a token type on some blockchain.
+ *
+ * Multiple denoms may designate the same underlying base denom (e.g., `uist`,
+ * `uatom`) on different Chains or on the same Chain via different paths. On
+ * Cosmos chains, all but the base denom are IBC style denoms, but that may vary
+ * across other chains. All the denoms that designate the same underlying base
+ * denom form an equivalence class, along with the unique Brand on the local
+ * Chain. Some operations accept any member of the equivalence class to
+ * effectively designate the corresponding token type on the target chain.
+ */
+export type Denom = string;
+/**
+ * In many cases, either a denom string or a local Brand can be used to
+ * designate a remote token type.
+ */
+export type DenomArg = Denom | Brand;
+/**
+ * Count of some fungible token on some blockchain.
+ *
+ * @see {@link Orchestrator.asAmount} to convert to an Amount surjectively
+ */
+export type DenomAmount = {
+    denom: Denom;
+    value: bigint;
+};
+/** Amounts can be provided as pure data using denoms or as native Amounts */
+export type AmountArg = DenomAmount | Amount;
+/** An address on some blockchain, e.g., cosmos, eth, etc. */
+export type ChainAddress = {
+    /** e.g. 1 for Ethereum, agoric-3 for Agoric, cosmoshub-4 for Cosmos */
+    chainId: string;
+    address: string;
+    addressEncoding: 'bech32' | 'ethereum';
+};
+export type OrchestrationAccount<C extends keyof KnownChains> = OrchestrationAccountI & KnownChains[C]['methods'];
+/**
+ * An object for access the core functions of a remote chain.
+ *
+ * Note that "remote" can mean the local chain; it's just that
+ * accounts are treated as remote/arms length for consistency.
+ */
+export interface Chain<C extends keyof KnownChains> {
+    getChainInfo: () => Promise<KnownChains[C]['info']>;
+    /**
+     * Creates a new account on the remote chain.
+     * @returns an object that controls a new remote account on Chain
+     */
+    makeAccount: () => Promise<OrchestrationAccount<C>>;
+}
+/**
+ * Provided in the callback to `orchestrate()`.
+ */
+export interface Orchestrator {
+    getChain: <C extends keyof KnownChains>(chainName: C) => Promise<Chain<C>>;
+    makeLocalAccount: () => Promise<LocalChainAccount>;
+    /**
+     * For a denom, return information about a denom including the equivalent
+     * local Brand, the Chain on which the denom is held, and the Chain that
+     * issues the corresponding asset.
+     * @param denom
+     */
+    getBrandInfo: <HoldingChain extends keyof KnownChains, IssuingChain extends keyof KnownChains>(denom: Denom) => {
+        /** The well-known Brand on Agoric for the direct asset */
+        brand?: Brand;
+        /** The Chain at which the argument `denom` exists (where the asset is currently held) */
+        chain: Chain<HoldingChain>;
+        /** The Chain that is the issuer of the underlying asset */
+        base: Chain<IssuingChain>;
+        /** the Denom for the underlying asset on its issuer chain */
+        baseDenom: Denom;
+    };
+    /**
+     * Convert an amount described in native data to a local, structured Amount.
+     * @param amount - the described amount
+     * @returns the Amount in local structuerd format
+     */
+    asAmount: (amount: DenomAmount) => NatAmount;
+}
+/**
+ * An object that supports high-level operations for an account on a remote chain.
+ */
+export interface OrchestrationAccountI {
+    /**
+     * @returns the address of the account on the remote chain
+     */
+    getAddress: () => ChainAddress;
+    /** @returns an array of amounts for every balance in the account. */
+    getBalances: () => Promise<DenomAmount[]>;
+    /** @returns the balance of a specific denom for the account. */
+    getBalance: (denom: DenomArg) => Promise<DenomAmount>;
+    /**
+     * Transfer amount to another account on the same chain. The promise settles when the transfer is complete.
+     * @param toAccount - the account to send the amount to. MUST be on the same chain
+     * @param amount - the amount to send
+     * @returns void
+     */
+    send: (toAccount: ChainAddress, amount: AmountArg) => Promise<void>;
+    /**
+     * Transfer an amount to another account, typically on another chain.
+     * The promise settles when the transfer is complete.
+     * @param amount - the amount to transfer.
+     * @param destination - the account to transfer the amount to.
+     * @param memo - an optional memo to include with the transfer, which could drive custom PFM behavior
+     * @returns void
+     *
+     * TODO document the mapping from the address to the destination chain.
+     */
+    transfer: (amount: AmountArg, destination: ChainAddress, memo?: string) => Promise<void>;
+    /**
+     * Transfer an amount to another account in multiple steps. The promise settles when
+     * the entire path of the transfer is complete.
+     * @param amount - the amount to transfer
+     * @param msg - the transfer message, including follow-up steps
+     * @returns void
+     */
+    transferSteps: (amount: AmountArg, msg: TransferMsg) => Promise<void>;
+    /**
+     * deposit payment from zoe to the account. For remote accounts,
+     * an IBC Transfer will be executed to transfer funds there.
+     */
+    deposit: (payment: Payment) => Promise<void>;
+}
+/**
+ * Internal structure for TransferMsgs.
+ * The type must be able to express transfers across different chains and transports.
+ *
+ * NOTE Expected to change, so consider an opaque structure.
+ */
+export type TransferMsg = {
+    toAccount: ChainAddress;
+    timeout?: Timestamp;
+    next?: TransferMsg;
+    data?: object;
+};
+export type AfterAction = {
+    destChain: string;
+    destAddress: ChainAddress;
+};
+export type SwapExact = {
+    amountIn: Amount;
+    amountOut: Amount;
+};
+export type SwapMaxSlippage = {
+    amountIn: Amount;
+    brandOut: Brand;
+    slippage: number;
+};
+//# sourceMappingURL=orchestration-api.d.ts.map

package/src/orchestration-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-api.d.ts","sourceRoot":"","sources":["orchestration-api.ts"],"names":[],"mappings":"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"}

package/src/orchestration-api.ts

@@ -0,0 +1,195 @@
+/* eslint-disable no-use-before-define */
+/**
+ * @file General API of orchestration
+ * - must not have chain-specific types without runtime narrowing by chain id
+ * - should remain relatively stable.
+ */
+import type {
+  Amount,
+  Brand,
+  NatAmount,
+  Payment,
+} from '@agoric/ertp/exported.js';
+import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
+import type { Timestamp } from '@agoric/time';
+import type { KnownChains } from './types.js';
+
+/**
+ * A denom that designates a path to a token type on some blockchain.
+ *
+ * Multiple denoms may designate the same underlying base denom (e.g., `uist`,
+ * `uatom`) on different Chains or on the same Chain via different paths. On
+ * Cosmos chains, all but the base denom are IBC style denoms, but that may vary
+ * across other chains. All the denoms that designate the same underlying base
+ * denom form an equivalence class, along with the unique Brand on the local
+ * Chain. Some operations accept any member of the equivalence class to
+ * effectively designate the corresponding token type on the target chain.
+ */
+export type Denom = string; // ibc/... or uist
+
+// ??? when multiple Denoms provide paths to the same remote token type,
+// should the brand be 1:1 with that equivalence class or each Denom?
+/**
+ * In many cases, either a denom string or a local Brand can be used to
+ * designate a remote token type.
+ */
+export type DenomArg = Denom | Brand;
+
+/**
+ * Count of some fungible token on some blockchain.
+ *
+ * @see {@link Orchestrator.asAmount} to convert to an Amount surjectively
+ */
+export type DenomAmount = {
+  denom: Denom;
+  value: bigint; // Nat
+};
+
+/** Amounts can be provided as pure data using denoms or as native Amounts */
+export type AmountArg = DenomAmount | Amount;
+
+/** An address on some blockchain, e.g., cosmos, eth, etc. */
+export type ChainAddress = {
+  /** e.g. 1 for Ethereum, agoric-3 for Agoric, cosmoshub-4 for Cosmos */
+  chainId: string;
+  address: string;
+  // TODO what's the right way to scope the address? it's not chainId
+  addressEncoding: 'bech32' | 'ethereum';
+};
+
+export type OrchestrationAccount<C extends keyof KnownChains> =
+  OrchestrationAccountI & KnownChains[C]['methods'];
+
+/**
+ * An object for access the core functions of a remote chain.
+ *
+ * Note that "remote" can mean the local chain; it's just that
+ * accounts are treated as remote/arms length for consistency.
+ */
+export interface Chain<C extends keyof KnownChains> {
+  getChainInfo: () => Promise<KnownChains[C]['info']>;
+
+  // "makeAccount" suggests an operation within a vat
+  /**
+   * Creates a new account on the remote chain.
+   * @returns an object that controls a new remote account on Chain
+   */
+  makeAccount: () => Promise<OrchestrationAccount<C>>;
+  // FUTURE supply optional port object; also fetch port object
+
+  // TODO provide a way to get the local denom/brand/whatever for this chain
+}
+
+/**
+ * Provided in the callback to `orchestrate()`.
+ */
+export interface Orchestrator {
+  // TODO we need a way to work with a chain its native way vs generic way
+  // E.g. an Osmosis delegate that looks Cosmos-y or no different from an Ethereum delegate
+  getChain: <C extends keyof KnownChains>(chainName: C) => Promise<Chain<C>>;
+
+  makeLocalAccount: () => Promise<LocalChainAccount>;
+  /**
+   * For a denom, return information about a denom including the equivalent
+   * local Brand, the Chain on which the denom is held, and the Chain that
+   * issues the corresponding asset.
+   * @param denom
+   */
+  getBrandInfo: <
+    HoldingChain extends keyof KnownChains,
+    IssuingChain extends keyof KnownChains,
+  >(
+    denom: Denom,
+  ) => {
+    /** The well-known Brand on Agoric for the direct asset */
+    brand?: Brand;
+    /** The Chain at which the argument `denom` exists (where the asset is currently held) */
+    chain: Chain<HoldingChain>;
+    /** The Chain that is the issuer of the underlying asset */
+    base: Chain<IssuingChain>;
+    /** the Denom for the underlying asset on its issuer chain */
+    baseDenom: Denom;
+  };
+  // TODO preload the mapping so this can be synchronous
+  /**
+   * Convert an amount described in native data to a local, structured Amount.
+   * @param amount - the described amount
+   * @returns the Amount in local structuerd format
+   */
+  asAmount: (amount: DenomAmount) => NatAmount;
+}
+
+/**
+ * An object that supports high-level operations for an account on a remote chain.
+ */
+export interface OrchestrationAccountI {
+  /**
+   * @returns the address of the account on the remote chain
+   */
+  getAddress: () => ChainAddress;
+
+  /** @returns an array of amounts for every balance in the account. */
+  getBalances: () => Promise<DenomAmount[]>;
+
+  /** @returns the balance of a specific denom for the account. */
+  getBalance: (denom: DenomArg) => Promise<DenomAmount>;
+
+  /**
+   * Transfer amount to another account on the same chain. The promise settles when the transfer is complete.
+   * @param toAccount - the account to send the amount to. MUST be on the same chain
+   * @param amount - the amount to send
+   * @returns void
+   */
+  send: (toAccount: ChainAddress, amount: AmountArg) => Promise<void>;
+
+  /**
+   * Transfer an amount to another account, typically on another chain.
+   * The promise settles when the transfer is complete.
+   * @param amount - the amount to transfer.
+   * @param destination - the account to transfer the amount to.
+   * @param memo - an optional memo to include with the transfer, which could drive custom PFM behavior
+   * @returns void
+   *
+   * TODO document the mapping from the address to the destination chain.
+   */
+  transfer: (
+    amount: AmountArg,
+    destination: ChainAddress,
+    memo?: string,
+  ) => Promise<void>;
+
+  /**
+   * Transfer an amount to another account in multiple steps. The promise settles when
+   * the entire path of the transfer is complete.
+   * @param amount - the amount to transfer
+   * @param msg - the transfer message, including follow-up steps
+   * @returns void
+   */
+  transferSteps: (amount: AmountArg, msg: TransferMsg) => Promise<void>;
+  /**
+   * deposit payment from zoe to the account. For remote accounts,
+   * an IBC Transfer will be executed to transfer funds there.
+   */
+  deposit: (payment: Payment) => Promise<void>;
+}
+
+/**
+ * Internal structure for TransferMsgs.
+ * The type must be able to express transfers across different chains and transports.
+ *
+ * NOTE Expected to change, so consider an opaque structure.
+ */
+export type TransferMsg = {
+  toAccount: ChainAddress;
+  timeout?: Timestamp;
+  next?: TransferMsg;
+  data?: object;
+};
+
+export type AfterAction = { destChain: string; destAddress: ChainAddress };
+export type SwapExact = { amountIn: Amount; amountOut: Amount };
+export type SwapMaxSlippage = {
+  amountIn: Amount;
+  brandOut: Brand;
+  slippage: number;
+};