@ledgerhq/coin-framework 0.0.2

package/src/bot/specs.ts

@@ -0,0 +1,275 @@
+// helpers for spec
+import invariant from "invariant";
+import { log } from "@ledgerhq/logs";
+import expect from "expect";
+import sample from "lodash/sample";
+import { isAccountEmpty } from "../account";
+import type {
+  DeviceAction,
+  DeviceActionArg,
+  TransactionDestinationTestInput,
+} from "./types";
+import { Account, TransactionCommon } from "@ledgerhq/types-live";
+import { botTest } from "./bot-test-context";
+import { CryptoCurrency, TokenCurrency } from "@ledgerhq/types-cryptoassets";
+import BigNumber from "bignumber.js";
+
+export { botTest };
+
+const stepValueTransformDefault = (s: string) => s.trim();
+
+// TODO should weight the choice to favorize accounts with small amounts
+export function pickSiblings(siblings: Account[], maxAccount = 5): Account {
+  const withoutEmpties = siblings.filter((a) => a.used);
+
+  if (withoutEmpties.length >= maxAccount) {
+    // we are no longer creating accounts
+    const maybeAccount = sample(withoutEmpties);
+    if (!maybeAccount) {
+      throw new Error(
+        "at least one non-empty sibling account exists. maxAccount=" +
+          maxAccount
+      );
+    }
+    return maybeAccount;
+  }
+
+  // we are only keeping empty account that have smaller index to favorize creation of non created derivation modes
+  let empties = siblings.filter(isAccountEmpty);
+  empties.sort((a, b) => a.index - b.index);
+
+  if (empties.length > 0) {
+    empties = empties.filter((e) => e.index === empties[0].index);
+  }
+
+  const maybeAccount = sample(withoutEmpties.concat(empties));
+  if (!maybeAccount) {
+    throw new Error(
+      "at least one sibling account exists. maxAccount=" + maxAccount
+    );
+  }
+  return maybeAccount;
+}
+
+type State<T extends TransactionCommon> = {
+  finalState: boolean;
+  stepTitle: string;
+  stepValue: string;
+  acc: Array<{
+    title: string;
+    value: string;
+  }>;
+  currentStep: Step<T> | null | undefined;
+};
+
+export enum SpeculosButton {
+  LEFT = "Ll",
+  RIGHT = "Rr",
+  BOTH = "LRlr",
+}
+
+type Step<T extends TransactionCommon> = {
+  title: string;
+  stepValueTransform?: (s: string) => string;
+  expectedValue?: (
+    arg0: DeviceActionArg<T, State<T>>,
+    acc: Array<{
+      title: string;
+      value: string;
+    }>
+  ) => string;
+  ignoreAssertionFailure?: boolean;
+  trimValue?: boolean;
+  button?: SpeculosButton;
+  // action to apply in term of button press
+  final?: boolean; // tells if there is no step after that and action should terminate all further action (hack to do deboncing)
+  maxY?: number; // check if text is bellow a certains Y coordinate on the screen, it happened that two text have the same content but different positions
+};
+type FlowDesc<T extends TransactionCommon> = {
+  steps: Array<Step<T>>;
+  fallback?: (arg0: DeviceActionArg<T, State<T>>) => Step<T> | null | undefined;
+};
+// generalized logic of device actions
+export function deviceActionFlow<T extends TransactionCommon>(
+  description: FlowDesc<T>
+): DeviceAction<T, State<T>> {
+  return (arg: DeviceActionArg<T, State<T>>) => {
+    invariant(
+      arg.appCandidate.model === "nanoS",
+      "FIXME: stepper logic is only implemented for Nano S"
+    );
+    const { transport, event, state, disableStrictStepValueValidation } = arg;
+    let { finalState, stepTitle, stepValue, acc, currentStep } = state || {
+      finalState: false,
+      stepTitle: "",
+      stepValue: "",
+      acc: [],
+      currentStep: null,
+    };
+
+    function runStep(step: Step<T>) {
+      const { final, title, button } = step;
+
+      if (stepValue && step.title !== stepTitle) {
+        // there were accumulated text and we are on new step, we need to release it and compare to expected
+        if (currentStep && currentStep.expectedValue) {
+          const { expectedValue, ignoreAssertionFailure } = currentStep;
+          const stepValueTransform =
+            currentStep.stepValueTransform || stepValueTransformDefault;
+
+          if (!ignoreAssertionFailure && !disableStrictStepValueValidation) {
+            botTest("deviceAction confirm step '" + stepTitle + "'", () =>
+              expect({
+                [stepTitle]: stepValueTransform(stepValue),
+              }).toMatchObject({
+                [stepTitle]: expectedValue(arg, acc).trim(),
+              })
+            );
+          }
+        }
+
+        acc = acc.concat({
+          title: stepTitle,
+          value: stepValue,
+        });
+        // a new step reset back the value for the next
+        stepValue = "";
+      }
+
+      if (button) {
+        // some step trigger navigation action
+        transport.button(button);
+      }
+
+      // text is the title of the step. we assume screen event starts / ends.
+      stepTitle = title;
+      currentStep = step;
+
+      if (final) {
+        finalState = true;
+      }
+    }
+
+    if (!finalState) {
+      let possibleKnownStep: Step<T> | null | undefined =
+        description.steps.find((s) => {
+          if (s.maxY) {
+            return event.text.startsWith(s.title) && event.y < s.maxY;
+          }
+          return event.text.startsWith(s.title);
+        });
+
+      // if there is a fallback provided, we will run it to try to detect another possible known step
+      if (!possibleKnownStep && description.fallback) {
+        possibleKnownStep = description.fallback(arg);
+      }
+
+      if (possibleKnownStep) {
+        // a step title was recognized. run it as a new step
+        runStep(possibleKnownStep);
+      } else if (currentStep) {
+        // there is a current ongoing step so we need to accumulate all text we see
+        let { text } = event;
+        if (currentStep.trimValue) text = text.trim();
+        stepValue += text;
+      }
+    }
+
+    log("bot/flow", `'${event.text}' ~> ${stepTitle}: ${stepValue}`);
+    return {
+      finalState,
+      stepTitle,
+      stepValue,
+      acc,
+      currentStep,
+    };
+  };
+}
+
+type DeviceAmountFormatOptions = {
+  // the ticker of the coin is AFTER the amount on the device (e.g. "600.1 USDT")
+  postfixCode: boolean;
+  // the device shows "42" as "42.0"
+  forceFloating: boolean;
+  // device don't even display the code (unit ticker)
+  hideCode: boolean;
+  // force the visibility of all digits of the amount
+  showAllDigits: boolean;
+};
+const defaultFormatOptions: DeviceAmountFormatOptions = {
+  postfixCode: false,
+  forceFloating: false,
+  hideCode: false,
+  showAllDigits: false,
+};
+
+const sep = " ";
+export function formatDeviceAmount(
+  currency: CryptoCurrency | TokenCurrency,
+  value: BigNumber,
+  options: Partial<DeviceAmountFormatOptions> = defaultFormatOptions
+): string {
+  const [unit] = currency.units;
+  let code = unit.code;
+  if (currency.type === "CryptoCurrency") {
+    const { deviceTicker } = currency;
+    if (deviceTicker) code = deviceTicker;
+  }
+  const fValue = value.div(new BigNumber(10).pow(unit.magnitude));
+  let v = options.showAllDigits
+    ? fValue.toFixed(unit.magnitude)
+    : fValue.toString(10);
+  if (options.forceFloating) {
+    if (!v.includes(".")) {
+      // if the value is pure integer, in the app it will automatically add an .0
+      v += ".0";
+    }
+  }
+  if (options.hideCode) return v;
+  return options.postfixCode ? v + sep + code : code + sep + v;
+}
+
+// this function throw if the portion of undelegated funds is smaller than the threshold
+// where threshold is a value from 0.0 to 1.0, percentage of the total amount of funds
+// Usage: put these in your spec, on the mutation transaction functions that intend to do more "delegations"
+export function expectSiblingsHaveSpendablePartGreaterThan(
+  siblings: Account[],
+  threshold: number
+): void {
+  const spendableTotal = siblings.reduce(
+    (acc, a) => acc.plus(a.spendableBalance),
+    new BigNumber(0)
+  );
+  const total = siblings.reduce(
+    (acc, a) => acc.plus(a.balance),
+    new BigNumber(0)
+  );
+  invariant(
+    spendableTotal.div(total).gt(threshold),
+    "the spendable part of accounts is sufficient (threshold: %s)",
+    threshold
+  );
+}
+
+export const genericTestDestination = <T>({
+  destination,
+  operation,
+  destinationBeforeTransaction,
+  sendingOperation,
+}: TransactionDestinationTestInput<T>): void => {
+  const amount = sendingOperation.value.minus(sendingOperation.fee);
+  botTest("account balance increased with transaction amount", () =>
+    expect(destination.balance.toString()).toBe(
+      destinationBeforeTransaction.balance.plus(amount).toString()
+    )
+  );
+  botTest("operation amount is consistent with sendingOperation", () =>
+    expect({
+      type: operation.type,
+      amount: operation.value.toString(),
+    }).toMatchObject({
+      type: "IN",
+      amount: amount.toString(),
+    })
+  );
+};

package/src/bot/types.ts

@@ -0,0 +1,224 @@
+import { BigNumber } from "bignumber.js";
+import Transport from "@ledgerhq/hw-transport";
+import type { DeviceModelId } from "@ledgerhq/devices";
+import {
+  Account,
+  AccountBridge,
+  AccountRaw,
+  Operation,
+  SignedOperation,
+  SignOperationEvent,
+  TransactionCommon,
+  TransactionStatusCommon,
+} from "@ledgerhq/types-live";
+import type { CryptoCurrency } from "@ledgerhq/types-cryptoassets";
+
+// Type coming from live-common/src/load/speculos.ts
+export type AppCandidate = {
+  path: string;
+  model: DeviceModelId;
+  firmware: string;
+  appName: string;
+  appVersion: string;
+};
+export type DeviceActionEvent = {
+  text: string;
+  x: number;
+  y: number;
+};
+export type TransactionTestInput<T> = {
+  account: Account;
+  accountBeforeTransaction: Account;
+  transaction: T;
+  status: TransactionStatusCommon;
+  optimisticOperation: Operation;
+  operation: Operation;
+};
+export type TransactionDestinationTestInput<T> = {
+  sendingAccount: Account;
+  sendingOperation: Operation;
+  destinationBeforeTransaction: Account;
+  operation: Operation;
+  destination: Account;
+  transaction: T;
+  status: TransactionStatusCommon;
+};
+export type DeviceActionArg<T extends TransactionCommon, S> = {
+  appCandidate: AppCandidate;
+  account: Account;
+  transaction: T;
+  status: TransactionStatusCommon;
+  transport: Transport & {
+    button: (arg0: string) => void;
+  };
+  event: DeviceActionEvent;
+  state: S;
+  disableStrictStepValueValidation?: boolean;
+};
+export type DeviceAction<T extends TransactionCommon, S> = (
+  arg0: DeviceActionArg<T, S>
+) => S | null | undefined;
+export type TransactionArg<T extends TransactionCommon> = {
+  appCandidate: AppCandidate;
+  account: Account;
+  siblings: Account[];
+  bridge: AccountBridge<T>;
+  maxSpendable: BigNumber;
+  preloadedData: any;
+};
+export type TransactionRes<T extends TransactionCommon> = {
+  transaction: T;
+  updates: Array<Partial<T> | null | undefined>;
+  destination?: Account;
+};
+export type MutationSpec<T extends TransactionCommon> = {
+  // Name what this mutation is doing
+  name: string;
+  // The maximum number of times to execute this mutation for a given test run
+  maxRun: number;
+  // Express the transaction to be done
+  // it returns either a transaction T, or an array with T and a list of patch to apply to it
+  transaction: (arg: TransactionArg<T>) => TransactionRes<T>;
+  // if there is a status errors/warnings of the defined transaction, this function, if define, can try to recover from it
+  recoverBadTransactionStatus?: (arg0: {
+    transaction: T;
+    status: TransactionStatusCommon;
+    account: Account;
+    bridge: AccountBridge<T>;
+  }) => T | null | undefined;
+  // express what are the status warnings to express on a given transaction
+  expectStatusWarnings?: (arg0: {
+    transaction: T;
+    status: TransactionStatusCommon;
+    account: Account;
+    bridge: AccountBridge<T>;
+  }) => { [_: string]: Error } | undefined;
+  // Express the device actions to do (buttons,..) and validate the device screen. overrides genericDeviceAction
+  deviceAction?: DeviceAction<T, any>;
+  // how much time to wait in maximum to reach the final state
+  testTimeout?: number;
+  // Implement a test that runs after the operation is applied to the account
+  test?: (input: TransactionTestInput<T>) => void;
+  // Implement a second test that allows to test the effect of the transaction on the DESTINATION account (matched by recipient)
+  testDestination?: (input: TransactionDestinationTestInput<T>) => void;
+};
+
+export type AppSpec<T extends TransactionCommon> = {
+  // allows to disable completely spec from running
+  disabled?: boolean;
+  // an arbitrary name to identify the bot spec
+  name: string;
+  // which crypto currency will the bot scan accounts with
+  currency: CryptoCurrency;
+  // how much time in ms does the test need to wait the operation to appear
+  testTimeout?: number;
+  // how much should we retry scan accounts if an error occurs
+  scanAccountsRetries?: number;
+  // if define, will run the mutations {multipleRuns} times in order to cover 2 txs in the same run and detect possible issues at the "second tx time"
+  multipleRuns?: number;
+  // define the frequency of exporting/importing back the account to simulate mobile export
+  crossAccountFrequency?: number;
+  // if the nano app depends on an app, name of this app
+  dependency?: string;
+  // a query to select one nano app. the most up to date version is selected when fields aren't set.
+  appQuery: {
+    model?: DeviceModelId;
+    appName?: string;
+    firmware?: string;
+    appVersion?: string;
+  };
+  // all the possible scenarios of these spec to consider doing transactions with
+  mutations: MutationSpec<T>[];
+  // can implement generic invariants for a mutation transaction to be possible
+  transactionCheck?: (arg: TransactionArg<T>) => void;
+  // Implement a test that also runs on each mutation after the operation is applied to the account
+  // this allows to verify the effect of the transaction is correctly applied on the account
+  test?: (arg0: TransactionTestInput<T>) => void;
+  // Express the device actions to do (buttons,..) and validate the device screen
+  genericDeviceAction: DeviceAction<T, any>;
+  // typically for 'botTransfer' we need to be able to override the preferred way to transfer a sub account
+  genericDeviceActionForSubAccountTransfers?: DeviceAction<T, any>;
+  // indicates to the engine what's the generally minimal amount we use to opt out from doing a transaction
+  // NB: at the moment it's purely informative and help inferring good "hints", but we could eventually automate it
+  minViableAmount?: BigNumber;
+  // global timeout to consider the run due date for the spec. (since a seed could have theorically an infinite amount of accounts and mutation could take a lot of time to validate transactions, we need a way to limit the run time)
+  skipMutationsTimeout?: number;
+  // do not expect an account to always be found (Hedera case)
+  allowEmptyAccounts?: boolean;
+};
+export type SpecReport<T extends TransactionCommon> = {
+  spec: AppSpec<T>;
+  appPath?: string;
+  scanDuration?: number;
+  preloadDuration?: number;
+  accountsBefore?: Account[];
+  accountsAfter?: Account[];
+  mutations?: MutationReport<T>[];
+  fatalError?: Error;
+  // express hints for the spec developers on things that could be improved
+  hintWarnings: string[];
+  skipMutationsTimeoutReached: boolean;
+};
+export type MutationReport<T extends TransactionCommon> = {
+  resyncAccountsDuration: number;
+  spec: AppSpec<T>;
+  appCandidate: AppCandidate;
+  account?: Account;
+  maxSpendable?: BigNumber;
+  unavailableMutationReasons?: Array<{
+    error: Error;
+    mutation: MutationSpec<T>;
+  }>;
+  mutation?: MutationSpec<T>;
+  mutationTime?: number;
+  destination?: Account;
+  transaction?: T;
+  status?: TransactionStatusCommon;
+  statusTime?: number;
+  recoveredFromTransactionStatus?: {
+    transaction: T;
+    status: TransactionStatusCommon;
+  };
+  latestSignOperationEvent?: SignOperationEvent;
+  signedOperation?: SignedOperation;
+  signedTime?: number;
+  optimisticOperation?: Operation;
+  broadcastedTime?: number;
+  operation?: Operation;
+  confirmedTime?: number;
+  finalAccount?: Account;
+  testDuration?: number;
+  destinationConfirmedTime?: number;
+  finalDestination?: Account;
+  finalDestinationOperation?: Operation;
+  testDestinationDuration?: number;
+  error?: Error;
+  errorTime?: number;
+  hintWarnings: string[];
+};
+
+export type MinimalSerializedMutationReport = {
+  appCandidate: AppCandidate;
+  mutationName: string | undefined;
+  accountId: string | undefined;
+  destinationId: string | undefined;
+  operationId: string | undefined;
+  error: string | undefined;
+};
+
+export type MinimalSerializedSpecReport = {
+  // spec.name
+  specName: string;
+  // minified version of accounts (we remove transactions from them)
+  accounts: AccountRaw[] | undefined;
+  fatalError: string | undefined;
+  mutations: MinimalSerializedMutationReport[] | undefined;
+  existingMutationNames: string[];
+  hintWarnings: string[];
+};
+
+export type MinimalSerializedReport = {
+  results: Array<MinimalSerializedSpecReport>;
+  environment: string | undefined;
+  seedHash: string;
+};

package/src/bridge/getAddressWrapper.ts

@@ -0,0 +1,40 @@
+import Transport from "@ledgerhq/hw-transport";
+import {
+  DeviceAppVerifyNotSupported,
+  UserRefusedAddress,
+} from "@ledgerhq/errors";
+import { log } from "@ledgerhq/logs";
+import type { Result, GetAddressOptions } from "../derivation";
+
+export type Resolver = (
+  transport: Transport,
+  addressOpt: GetAddressOptions
+) => Promise<Result>;
+
+const getAddressWrapper =
+  (getAddressFn: Resolver) =>
+  (transport: Transport, opts: GetAddressOptions) => {
+    const { currency, path, verify } = opts;
+    return getAddressFn(transport, opts)
+      .then((result) => {
+        log("hw", `getAddress ${currency.id} on ${path}`, result);
+        return result;
+      })
+      .catch((e) => {
+        log("hw", `getAddress ${currency.id} on ${path} FAILED ${String(e)}`);
+
+        if (e && e.name === "TransportStatusError") {
+          if (e.statusCode === 0x6b00 && verify) {
+            throw new DeviceAppVerifyNotSupported();
+          }
+
+          if (e.statusCode === 0x6985 || e.statusCode === 0x5501) {
+            throw new UserRefusedAddress();
+          }
+        }
+
+        throw e;
+      });
+  };
+
+export default getAddressWrapper;