Function debugSingleScenario

packages/cashscript/src/debugging.ts:66–193

(
  template: WalletTemplate, artifact: Artifact | undefined, unlockingScriptId: string, scenarioId: string,
)

};

const debugSingleScenario = (
  template: WalletTemplate, artifact: Artifact | undefined, unlockingScriptId: string, scenarioId: string,
): DebugResult => {
  const { vm, program } = createProgram(template, unlockingScriptId, scenarioId);

  const fullDebugSteps = vm.debug(program);

  // P2SH executions have 3 phases, we only want the last one (locking script execution)
  // https://libauth.org/types/AuthenticationVirtualMachine.html#__type.debug
  const lockingScriptDebugResult = fullDebugSteps.slice(findLastIndex(fullDebugSteps, (state) => state.ip === 0));

  // The controlStack determines whether the current debug step is in the executed branch
  // It also tracks loop / function usage, but for the purpose of determining whether a step was executed,
  // we only need to check that there are no 'false' items in the control stack.
  // https://libauth.org/types/AuthenticationProgramStateControlStack.html
  // https://github.com/bitjson/bch-loops#control-stack
  const executedDebugSteps = lockingScriptDebugResult
    .filter((debugStep) => debugStep.controlStack.every(item => item !== false));

  // P2PKH inputs do not have an artifact, so we skip the console.log handling
  if (artifact) {
    // Try to match each executed debug step to a log entry if it exists. Note that inside loops,
    // the same log statement may be executed multiple times in different debug steps
    // Also note that multiple log statements may exist for the same ip, so we need to handle all of them
    const executedLogs = executedDebugSteps
      .flatMap((debugStep, index) => {
        const logEntries = artifact.debug?.logs?.filter((log) => log.ip === debugStep.ip);
        if (!logEntries || logEntries.length === 0) return [];

        const reversedPriorDebugSteps = executedDebugSteps.slice(0, index + 1).reverse();

        return logEntries.map((logEntry) => {
          const decodedLogData = logEntry.data
            .map((dataEntry) => decodeLogDataEntry(dataEntry, reversedPriorDebugSteps, vm));
          return { logEntry, decodedLogData };
        });
      });

    for (const { logEntry, decodedLogData } of executedLogs) {
      const inputIndex = extractInputIndexFromScenario(scenarioId);
      logConsoleLogStatement(logEntry, decodedLogData, artifact.contractName, inputIndex);
    }
  }

  const lastExecutedDebugStep = executedDebugSteps[executedDebugSteps.length - 1];

  // If an error is present in the last step, that means a require statement in the middle of the function failed
  if (lastExecutedDebugStep.error) {
    // In Libauth any thrown error gets registered in the instruction that happens right *after* the instruction that
    // caused the error (in other words the OP_VERIFY). We need to decrement the instruction pointer to get the correct
    // failing instruction.
    const failingIp = lastExecutedDebugStep.ip - 1;
    const failingInstruction = lastExecutedDebugStep.instructions[failingIp];

    // With optimisations, the OP_CHECKSIG and OP_VERIFY instructions are merged into a single opcode (OP_CHECKSIGVERIFY).
    // However, for the final verify, the OP_VERIFY is not present. In most cases, the implicit final VERIFY is checked
    // later in the code. However, for NULLFAIL, the error is thrown in the OP_CHECKSIG opcode, rather than in the
    // implicit final VERIFY. The error message is registered in the next instruction, so we need to increment the