Refactor: Forwarding Path

packages/connect-core/src/entities/ForwardingPath.ts

@@ -0,0 +1,77 @@
+import { ethers } from 'ethers'
+
+import App from './App'
+import Transaction from './Transaction'
+import {
+  AppOrAddress,
+  ForwardingPathData,
+  ForwardingPathDescriptionData,
+  PostProcessDescription,
+} from '../types'
+import { describeForwardingPath } from '../utils/description'
+
+export default class ForwardingPath {
+  #provider: ethers.providers.Provider
+  readonly apps: App[]
+  readonly destination: App
+  readonly transactions: Transaction[]
+
+  constructor(data: ForwardingPathData, provider: ethers.providers.Provider) {
+    this.#provider = provider
+    this.apps = data.apps
+    this.destination = data.destination
+    this.transactions = data.transactions
+  }
+
+  // Lets consumers pass a callback to sign any number of transactions.
+  // This is similar to calling transactions() and using a loop, but shorter.
+  // It returns the value returned by the library, usually a transaction receipt.
+  async sign<Receipt>(
+    callback: (tx: Transaction) => Promise<Receipt>
+  ): Promise<Receipt[]> {
+    return Promise.all(this.transactions.map(async (tx) => await callback(tx)))
+  }
+
+  // Return a description of the forwarding path, to be rendered.
+  async describe(): Promise<ForwardingPathDescription> {
+    // TODO: Make sure we are safe to only provide the apps on the path here
+    return describeForwardingPath(this.transactions, this.apps, this.#provider)
+  }
+
+  // Return a description of the forwarding path, as text.
+  // Shorthand for .describe().toString()
+  toString(): string {
+    return this.describe().toString()
+  }
+}
+
+type ForwardingPathDescriptionTreeEntry =
+  | AppOrAddress
+  | [AppOrAddress, ForwardingPathDescriptionTreeEntry[]]
+
+export type ForwardingPathDescriptionTree = ForwardingPathDescriptionTreeEntry[]
+
+export class ForwardingPathDescription {
+  readonly apps: App[]
+  readonly describeSteps: PostProcessDescription[]
+
+  constructor(data: ForwardingPathDescriptionData) {
+    this.apps = data.apps
+    this.describeSteps = data.describeSteps
+  }
+
+  // Return a tree that can get used to render the path.
+  tree(): ForwardingPathDescriptionTree {
+    // TODO:
+    return []
+  }
+
+  // Renders the forwarding path description as text
+  toString(): string {
+    return this.tree().toString()
+  }
+
+  // TBD: a utility that makes it easy to render the tree,
+  // e.g. as a nested list in HTML or React.
+  reduce(callback: Function): any {}
+}

packages/connect-core/src/entities/Organization.ts

@@ -6,9 +6,11 @@ import {
 } from '@aragon/connect-types'
 
 import { ConnectionContext } from '../types'
+import { decodeForwardingPath } from '../utils/description'
 import { toArrayEntry } from '../utils/misc'
 import App from './App'
 import Intent from './Intent'
+import { ForwardingPathDescription } from './ForwardingPath'
 import Permission from './Permission'
 
 // TODO
@@ -134,4 +136,10 @@ export default class Organization {
       this.connection.ethersProvider
     )
   }
+
+  //////// DESCRIPTIONS /////////
+
+  async describeScript(script: string): Promise<ForwardingPathDescription> {
+    return decodeForwardingPath(script, this.apps(), this.connection)
+  }
 }

packages/connect-core/src/types.ts

@@ -63,6 +63,17 @@ export interface AppData {
   version?: string
 }
 
+export interface ForwardingPathData {
+  apps: App[]
+  destination: App
+  transactions: Transaction[]
+}
+
+export interface ForwardingPathDescriptionData {
+  apps: App[]
+  describeSteps: PostProcessDescription[]
+}
+
 export interface IntentData {
   appAddress: string
   functionName: string

packages/connect-core/src/utils/description.ts

@@ -0,0 +1,94 @@
+import { ethers } from 'ethers'
+
+import { isCallScript, decodeCallScript } from './callScript'
+import { isValidForwardCall, parseForwardCall } from './forwarding'
+import App from '../entities/App'
+import Transaction from '../entities/Transaction'
+import {
+  ForwardingPathDescription,
+  ForwardingPathDescriptionTree,
+} from '../entities/ForwardingPath'
+import {
+  tryEvaluatingRadspec,
+  postprocessRadspecDescription,
+} from './radspec/index'
+import { PostProcessDescription } from '../types'
+
+export async function describeStep(
+  transaction: Transaction,
+  apps: App[],
+  provider: ethers.providers.Provider
+): Promise<PostProcessDescription> {
+  if (!transaction.to) {
+    throw new Error(`Could not describe transaction: missing 'to'`)
+  }
+  if (!transaction.data) {
+    throw new Error(`Could not describe transaction: missing 'data'`)
+  }
+
+  let description, annotatedDescription
+  try {
+    description = await tryEvaluatingRadspec(transaction, apps, provider)
+
+    if (description) {
+      const processed = await postprocessRadspecDescription(description, apps)
+      annotatedDescription = processed.annotatedDescription
+      description = processed.description
+    }
+  } catch (err) {
+    throw new Error(`Could not describe transaction: ${err}`)
+  }
+
+  return {
+    description,
+    annotatedDescription,
+  }
+}
+
+/**
+ * Use radspec to create a human-readable description for each step in the given `path`
+ *
+ */
+export async function describeForwardingPath(
+  path: Transaction[],
+  apps: App[],
+  provider: ethers.providers.Provider
+): Promise<ForwardingPathDescription> {
+  const describeSteps = await Promise.all(
+    path.map((step) => describeStep(step, apps, provider))
+  )
+  return new ForwardingPathDescription({ describeSteps, apps })
+}
+
+/**
+ * Decodes an EVM callscript and returns the forwarding path it description.
+ *
+ * @return An array of Ethereum transactions that describe each step in the path
+ */
+export function decodeForwardingPath(
+  script: string
+): ForwardingPathDescriptionTree {
+  // In the future we may support more EVMScripts, but for now let's just assume we're only
+  // dealing with call scripts
+  if (!isCallScript(script)) {
+    throw new Error(`Script could not be decoded: ${script}`)
+  }
+
+  const path = decodeCallScript(script)
+
+  return path.reduce((decodeSegments, segment) => {
+    const { data } = segment
+
+    let children
+    if (isValidForwardCall(data)) {
+      const forwardedEvmScript = parseForwardCall(data)
+
+      try {
+        children = decodeForwardingPath(forwardedEvmScript)
+        // eslint-disable-next-line no-empty
+      } catch (err) {}
+    }
+
+    return decodeSegments.concat({ ...segment, children })
+  }, [] as ForwardingPathDescriptionTree)
+}

packages/connect-core/src/utils/index.ts

@@ -1,4 +1,4 @@
-// export * from './descriptions'
+export * from './description'
 export * from './misc'
 export * from './network'
 export * from './app-connectors'

packages/connect-core/src/utils/radspec/index.ts

@@ -69,7 +69,4 @@ export async function tryEvaluatingRadspec(
   return evaluatedNotice
 }
 
-export {
-  postprocessRadspecDescription,
-  PostProcessDescription,
-} from './postprocess'
+export { postprocessRadspecDescription } from './postprocess'

packages/connect-core/src/utils/radspec/postprocess.ts

@@ -2,12 +2,7 @@ import { addressesEqual, ANY_ENTITY } from '../address'
 import { getKernelNamespace } from '../kernel'
 import App from '../../entities/App'
 import Role from '../../entities/Role'
-import { Annotation } from '../../types'
-
-export interface PostProcessDescription {
-  description: string
-  annotatedDescription?: Annotation[]
-}
+import { Annotation, PostProcessDescription } from '../../types'
 
 interface CompiledTokens {
   description: string[]