feat: proposal for shortcuts (#69)

### Description

This is a proposal for adding support for shortcut hooks.

### Details

This is focusing on applying shortcuts to positions. But it could be
extended to support shortcuts for tokens or more generic actions.

It would support the following use cases
- claiming Good Dollar UBI
- claiming Ubeswap farm staking rewards

The shortcuts are defined in a new file under
`src/apps/{appId}/shortcuts.ts`. This is to give builders clear
visibility into what type of hooks are supported for a given app.
The plan is to rename `plugin.ts` to `positions.ts` to follow with this
new structure.

The positions are extended with a new `availableShortcutIds` property
which allows defining which shortcuts can be applied to them. Underlying
tokens get a new optional `category` property which allows giving more
meaning to what they are.
Specifically here, the `claimable` category tells the wallet the tokens
and amounts which can be claimed.

The wallet would fetch the shortcuts with a new route in `hooks-api`.
(Or we could also return both positions and shortcuts data in a single
call).

Using the new data in the returned positions, the wallet would be able
to fill the content of a new "Claim Rewards" screen.
Displaying details for the claimable tokens.
Tapping the button next to each of them would call the shortcut's
`onTrigger` function, via a new route in `hooks-api`.
It would return 0, 1 or more transaction to sign.

The wallet would take it from there and display the usual transaction
signing bottom sheet. Similar to what's happening when interacting with
dapps with WalletConnect.

### Future considerations

This could be extended to support other types of shortcuts related to
positions and requiring additional input parameters. For instance
adding/removing liquidity in Ubeswap pools. This would require a new
wallet UI to specify the amounts needed.

We could maybe think of pre-built UI elements that could be used and
defined by shortcuts so we don't have to build custom UIs in the wallet
to support them.

### Related linear task

Fixes RET-732

Author: jeanregisser

package.json

@@ -26,6 +26,8 @@
     "test:e2e": "jest --selectProjects e2e",
     "supercheck": "yarn format && yarn lint:fix && yarn typecheck && yarn test",
     "getPositions": "ts-node ./scripts/getPositions.ts",
+    "getShortcuts": "ts-node ./scripts/getShortcuts.ts",
+    "triggerShortcut": "ts-node ./scripts/triggerShortcut.ts",
     "release": "semantic-release"
   },
   "dependencies": {

scripts/getPositions.ts

@@ -65,6 +65,7 @@ void (async () => {
           balance: balance.toFixed(2),
           balanceUsd: balance.times(position.priceUsd).toFixed(2),
           breakdown: position.tokens.map(breakdownToken).join(', '),
+          availableShortcutIds: position.availableShortcutIds,
         }
       } else {
         return {
@@ -75,6 +76,7 @@ void (async () => {
           title: `${position.displayProps.title} (${position.displayProps.description})`,
           balanceUsd: new BigNumber(position.balanceUsd).toFixed(2),
           breakdown: position.tokens.map(breakdownToken).join(', '),
+          availableShortcutIds: position.availableShortcutIds,
         }
       }
     }),

scripts/getShortcuts.e2e.ts

@@ -0,0 +1,8 @@
+import * as $ from 'shelljs'
+
+describe('getShortcuts', () => {
+  it('should get shortcuts successfully', () => {
+    const result = $.exec('yarn getShortcuts')
+    expect(result.code).toBe(0)
+  })
+})

scripts/getShortcuts.ts

@@ -0,0 +1,27 @@
+// Helper script to get the shortcuts
+/* eslint-disable no-console */
+import yargs from 'yargs'
+import { getShortcuts } from '../src/getShortcuts'
+
+const argv = yargs(process.argv.slice(2))
+  .usage('Usage: $0 --apps app1[,app2]')
+  .options({
+    apps: {
+      alias: 'p',
+      describe: 'App IDs to get shortcuts for, defaults to all',
+      type: 'array',
+      default: [],
+      // Allows comma separated values
+      coerce: (array: string[]) => {
+        return array.flatMap((v) => v.split(','))
+      },
+    },
+  })
+  .parseSync()
+
+void (async () => {
+  const shortcuts = await getShortcuts(argv.apps)
+  console.log('shortcuts', JSON.stringify(shortcuts, null, ' '))
+
+  console.table(shortcuts)
+})()

scripts/triggerShortcut.e2e.ts

@@ -0,0 +1,10 @@
+import * as $ from 'shelljs'
+
+describe('triggerShortcut', () => {
+  it('should trigger a shortcut successfully', () => {
+    const result = $.exec(
+      'yarn triggerShortcut --network celo --address 0x2b8441ef13333ffa955c9ea5ab5b3692da95260d --app ubeswap --shortcut claim-reward --positionAddress 0x',
+    )
+    expect(result.code).toBe(0)
+  })
+})

scripts/triggerShortcut.ts

@@ -0,0 +1,70 @@
+// Helper script to trigger a shortcut
+/* eslint-disable no-console */
+import yargs from 'yargs'
+import { getShortcuts } from '../src/getShortcuts'
+
+const argv = yargs(process.argv.slice(2))
+  .usage(
+    'Usage: $0 --network <network> --address <address> --app <appId> --shortcut <shortcutId> --positionAddress <positionAddress>',
+  )
+  .options({
+    network: {
+      alias: 'n',
+      describe: 'Network to get positions for',
+      choices: ['celo', 'celoAlfajores'],
+      default: 'celo',
+    },
+    address: {
+      alias: 'a',
+      describe: 'Address to get positions for',
+      type: 'string',
+      demandOption: true,
+    },
+    app: {
+      alias: 'p',
+      describe: 'App ID of the shortcut to trigger',
+      type: 'string',
+      demandOption: true,
+    },
+    shortcut: {
+      alias: 's',
+      describe: 'Shortcut ID to trigger',
+      type: 'string',
+      demandOption: true,
+    },
+    positionAddress: {
+      describe: 'Position address to trigger the shortcut on',
+      type: 'string',
+      demandOption: true,
+    },
+  })
+  .parseSync()
+
+void (async () => {
+  const shortcuts = await getShortcuts([argv.app])
+
+  const shortcut = shortcuts.find((s) => s.id === argv.shortcut)
+  if (!shortcut) {
+    throw new Error(
+      `No shortcut found with id '${
+        argv.shortcut
+      }', available shortcuts: ${shortcuts.map((s) => s.id).join(', ')}`,
+    )
+  }
+
+  console.log(
+    `Triggering shortcut '${shortcut.id}' for app '${shortcut.appId}'`,
+    {
+      network: argv.network,
+      address: argv.address,
+      positionAddress: argv.positionAddress,
+    },
+  )
+  const result = await shortcut.onTrigger(
+    argv.network,
+    argv.address,
+    argv.positionAddress,
+  )
+
+  console.table(result)
+})()

src/apps/ubeswap/plugin.ts

@@ -196,6 +196,7 @@ async function getFarmPositionDefinitions(
           {
             address: farm.rewardsTokenAddress.toLowerCase(),
             network,
+            category: 'claimable',
           },
         ],
         displayProps: ({ resolvedTokens }) => {
@@ -208,7 +209,7 @@ async function getFarmPositionDefinitions(
             imageUrl: poolToken.displayProps.imageUrl,
           }
         },
-
+        availableShortcutIds: ['claim-reward'],
         balances: async ({ resolvedTokens }) => {
           const poolToken = resolvedTokens[farm.lpAddress.toLowerCase()]
           const share = new BigNumber(farm.balance.toString()).div(

src/apps/ubeswap/shortcuts.ts

@@ -0,0 +1,21 @@
+import { ShortcutsHook } from '../../shortcuts'
+
+const hook: ShortcutsHook = {
+  getShortcutDefinitions() {
+    return [
+      {
+        id: 'claim-reward',
+        name: 'Claim',
+        description: 'Claim rewards for staked liquidity',
+        networks: ['celo'],
+        category: 'claim',
+        async onTrigger(_network, _address, _positionAddress) {
+          // TODO: return the unsigned transaction to claim the reward
+          return []
+        },
+      },
+    ]
+  },
+}
+
+export default hook

src/getHooks.ts

@@ -0,0 +1,67 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import { AppPlugin } from './plugin'
+import { ShortcutsHook } from './shortcuts'
+
+type HookTypeName = 'positions' | 'shortcuts'
+
+type HookType<T> = T extends 'positions'
+  ? AppPlugin
+  : T extends 'shortcuts'
+  ? ShortcutsHook
+  : never
+
+const APP_ID_PATTERN = /^[a-zA-Z0-9-]+$/
+
+async function getAllAppIds(): Promise<string[]> {
+  // Read all folders from the "apps" folder
+  const files = await fs.readdir(path.join(__dirname, 'apps'), {
+    withFileTypes: true,
+  })
+  const folders = files.filter((file) => file.isDirectory())
+  // Check that all folders are valid app ids
+  for (const folder of folders) {
+    if (!APP_ID_PATTERN.test(folder.name)) {
+      throw new Error(
+        `Invalid app id: '${folder.name}', must match ${APP_ID_PATTERN}`,
+      )
+    }
+  }
+  return folders.map((folder) => folder.name)
+}
+
+export async function getHooks<T extends HookTypeName>(
+  appIds: string[],
+  hookType: T,
+): Promise<Record<string, HookType<T>>> {
+  const allAppIds = await getAllAppIds()
+  const plugins: Record<string, HookType<T>> = {}
+  const appIdsToLoad = appIds.length === 0 ? allAppIds : appIds
+  for (const appId of appIdsToLoad) {
+    if (!allAppIds.includes(appId)) {
+      throw new Error(
+        `No app with id '${appId}' found, available apps: ${allAppIds.join(
+          ', ',
+        )}`,
+      )
+    }
+
+    let plugin: any
+    try {
+      plugin = await import(`./apps/${appId}/${hookType}`)
+    } catch (e) {
+      if (appIds.includes(appId)) {
+        if ((e as any).code === 'MODULE_NOT_FOUND') {
+          throw new Error(
+            `No ${hookType} hook found for app '${appId}', make sure to export a default hook from 'src/apps/${appId}/${hookType}.ts'`,
+          )
+        }
+        throw e
+      }
+    }
+    if (plugin?.default) {
+      plugins[appId] = plugin.default
+    }
+  }
+  return plugins
+}

src/getPositions.ts

@@ -263,6 +263,7 @@ async function resolveAppTokenPosition(
     supply: toSerializedDecimalNumber(
       toDecimalNumber(totalSupply, positionTokenInfo.decimals),
     ),
+    availableShortcutIds: positionDefinition.availableShortcutIds ?? [],
   }
 
   return position
@@ -286,7 +287,10 @@ async function resolveContractPosition(
 
   const tokens = positionDefinition.tokens.map((token, i) =>
     tokenWithUnderlyingBalance(
-      resolvedTokens[token.address],
+      {
+        ...resolvedTokens[token.address],
+        ...(token.category && { category: token.category }),
+      },
       balances[i],
       new BigNumber(1) as DecimalNumber,
     ),
@@ -311,6 +315,7 @@ async function resolveContractPosition(
     displayProps,
     tokens: tokens,
     balanceUsd: toSerializedDecimalNumber(balanceUsd),
+    availableShortcutIds: positionDefinition.availableShortcutIds ?? [],
   }
 
   return position