Stateful property-tests for the error/failure paths in PoX-4

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox-4.stateful-prop.test.ts

@@ -16,6 +16,7 @@ import { StackingClient } from "@stacks/stacking";
 
 import fc from "fast-check";
 import { PoxCommands } from "./pox_Commands.ts";
+import { ErrCommands } from "./err_Commands.ts";
 
 import fs from "fs";
 import path from "path";
@@ -108,7 +109,8 @@ it("statefully interacts with PoX-4", async () => {
   // commands are run at least once.
   const statistics = fs.readdirSync(path.join(__dirname)).filter((file) =>
     file.startsWith("pox_") && file.endsWith(".ts") &&
-    file !== "pox_CommandModel.ts" && file !== "pox_Commands.ts"
+    file !== "pox_CommandModel.ts" && file !== "pox_Commands.ts" &&
+    !file.includes("_Err")
   ).map((file) => file.slice(4, -3)); // Remove "pox_" prefix and ".ts" suffix.
 
   // This is the initial state of the model.
@@ -143,17 +145,22 @@ it("statefully interacts with PoX-4", async () => {
 
   simnet.setEpoch("3.0");
 
+  const successPath = PoxCommands(model.wallets, model.stackers, sut.network);
+  const failurePath = ErrCommands(model.wallets, model.stackers, sut.network);
+
   fc.assert(
     fc.property(
-      PoxCommands(model.wallets, model.stackers, sut.network),
+      // More on size: https://github.com/dubzzz/fast-check/discussions/2978
+      // More on cmds: https://github.com/dubzzz/fast-check/discussions/3026
+      fc.commands(successPath.concat(failurePath), { size: "xsmall" }),
       (cmds) => {
         const initialState = () => ({ model: model, real: sut });
         fc.modelRun(initialState, cmds);
       },
     ),
     {
       // Defines the number of test iterations to run; default is 100.
-      numRuns: 1000,
+      numRuns: 20000,
       // Adjusts the level of detail in test reports. Default is 0 (minimal).
       // At level 2, reports include extensive details, helpful for deep
       // debugging. This includes not just the failing case and its seed, but

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_AllowContractCallerCommand.ts

@@ -77,7 +77,6 @@ export class AllowContractCallerCommand implements PoxCommand {
 
     const callerToAllow = model.stackers.get(this.allowanceTo.stxAddress)!;
     // Update model so that we know this wallet has authorized a contract-caller.
-    // If the caller is already allowed, there's no need to add it again.
     const callerToAllowIndexInAllowedList = wallet.allowedContractCallers
       .indexOf(this.allowanceTo.stxAddress);
 

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_CommandModel.ts

@@ -46,9 +46,49 @@ export class Stub {
 
   reportCommandRuns() {
     console.log("Command run method execution counts:");
-    this.statistics.forEach((count, commandName) => {
-      console.log(`${commandName}: ${count}`);
+    const orderedStatistics = Array.from(this.statistics.entries()).sort(
+      ([keyA], [keyB]) => {
+        return keyA.localeCompare(keyB);
+      },
+    );
+
+    this.logAsTree(orderedStatistics);
+  }
+
+  private logAsTree(statistics: [string, number][]) {
+    const tree: { [key: string]: any } = {};
+
+    statistics.forEach(([commandName, count]) => {
+      const split = commandName.split("_");
+      let root: string = split[0],
+        rest: string = "base";
+
+      if (split.length > 1) {
+        rest = split.slice(1).join("_");
+      }
+      if (!tree[root]) {
+        tree[root] = {};
+      }
+      tree[root][rest] = count;
     });
+
+    const printTree = (node: any, indent: string = "") => {
+      const keys = Object.keys(node);
+      keys.forEach((key, index) => {
+        const isLast = index === keys.length - 1;
+        const boxChar = isLast ? "└─ " : "├─ ";
+        if (key !== "base") {
+          if (typeof node[key] === "object") {
+            console.log(`${indent}${boxChar}${key}: ${node[key]["base"]}`);
+            printTree(node[key], indent + (isLast ? "    " : "│   "));
+          } else {
+            console.log(`${indent}${boxChar}${key}: ${node[key]}`);
+          }
+        }
+      });
+    };
+
+    printTree(tree);
   }
 
   refreshStateForNextRewardCycle(real: Real) {

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_Commands.ts

@@ -1,5 +1,5 @@
 import fc from "fast-check";
-import { Real, Stacker, Stub, StxAddress, Wallet } from "./pox_CommandModel";
+import { PoxCommand, Stacker, StxAddress, Wallet } from "./pox_CommandModel";
 import { GetStackingMinimumCommand } from "./pox_GetStackingMinimumCommand";
 import { GetStxAccountCommand } from "./pox_GetStxAccountCommand";
 import { StackStxSigCommand } from "./pox_StackStxSigCommand";
@@ -27,7 +27,7 @@ export function PoxCommands(
   wallets: Map<StxAddress, Wallet>,
   stackers: Map<StxAddress, Stacker>,
   network: Simnet,
-): fc.Arbitrary<Iterable<fc.Command<Stub, Real>>> {
+): fc.Arbitrary<PoxCommand>[] {
   const cmds = [
     // GetStackingMinimumCommand
     fc.record({
@@ -452,9 +452,7 @@ export function PoxCommands(
     ),
   ];
 
-  // More on size: https://github.com/dubzzz/fast-check/discussions/2978
-  // More on cmds: https://github.com/dubzzz/fast-check/discussions/3026
-  return fc.commands(cmds, { size: "xsmall" });
+  return cmds;
 }
 
 export const REWARD_CYCLE_LENGTH = 1050;
@@ -481,7 +479,7 @@ export const currentCycleFirstBlock = (network: Simnet) =>
     ).result,
   ));
 
-const nextCycleFirstBlock = (network: Simnet) =>
+export const nextCycleFirstBlock = (network: Simnet) =>
   Number(cvToValue(
     network.callReadOnlyFn(
       "ST000000000000000000002AMW42H.pox-4",

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_DelegateStackExtendCommand.ts

@@ -37,8 +37,9 @@ export class DelegateStackExtendCommand implements PoxCommand {
    * height as a Pool Operator on behalf of a Stacker.
    *
    * @param operator - Represents the Pool Operator's wallet.
-   * @param stacker - Represents the STacker's wallet.
-   * @param extendCount - Represents the cycles to be expended.
+   * @param stacker - Represents the Stacker's wallet.
+   * @param extendCount - Represents the number of cycles to extend
+   *                      the stack for.
    * @param currentCycle - Represents the current PoX reward cycle.
    */
   constructor(

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_DelegateStackExtendCommand_Err.ts

@@ -0,0 +1,96 @@
+import {
+  logCommand,
+  PoxCommand,
+  Real,
+  Stub,
+  Wallet,
+} from "./pox_CommandModel.ts";
+import { poxAddressToTuple } from "@stacks/stacking";
+import { expect } from "vitest";
+import { Cl } from "@stacks/transactions";
+
+type CheckFunc = (
+  this: DelegateStackExtendCommand_Err,
+  model: Readonly<Stub>,
+) => boolean;
+
+export class DelegateStackExtendCommand_Err implements PoxCommand {
+  readonly operator: Wallet;
+  readonly stacker: Wallet;
+  readonly extendCount: number;
+  readonly currentCycle: number;
+  readonly checkFunc: CheckFunc;
+  readonly errorCode: number;
+
+  /**
+   * Constructs a `DelegateStackExtendCommand_Err` to extend the unlock
+   * height as a Pool Operator on behalf of a Stacker.
+   *
+   * @param operator - Represents the Pool Operator's wallet.
+   * @param stacker - Represents the Stacker's wallet.
+   * @param extendCount - Represents the number of cycles to extend the stack for.
+   * @param currentCycle - Represents the current PoX reward cycle.
+   * @param checkFunc - A function to check constraints for running this command.
+   * @param errorCode - The expected error code when running this command.
+   */
+  constructor(
+    operator: Wallet,
+    stacker: Wallet,
+    extendCount: number,
+    currentCycle: number,
+    checkFunc: CheckFunc,
+    errorCode: number,
+  ) {
+    this.operator = operator;
+    this.stacker = stacker;
+    this.extendCount = extendCount;
+    this.currentCycle = currentCycle;
+    this.checkFunc = checkFunc;
+    this.errorCode = errorCode;
+  }
+
+  check = (model: Readonly<Stub>): boolean => this.checkFunc.call(this, model);
+
+  run(model: Stub, real: Real): void {
+    const stackerWallet = model.stackers.get(this.stacker.stxAddress)!;
+
+    // Act
+    const delegateStackExtend = real.network.callPublicFn(
+      "ST000000000000000000002AMW42H.pox-4",
+      "delegate-stack-extend",
+      [
+        // (stacker principal)
+        Cl.principal(this.stacker.stxAddress),
+        // (pox-addr { version: (buff 1), hashbytes: (buff 32) })
+        poxAddressToTuple(this.operator.btcAddress),
+        // (extend-count uint)
+        Cl.uint(this.extendCount),
+      ],
+      this.operator.stxAddress,
+    );
+
+    expect(delegateStackExtend.result).toBeErr(Cl.int(this.errorCode));
+
+    // Log to console for debugging purposes. This is not necessary for the
+    // test to pass but it is useful for debugging and eyeballing the test.
+    logCommand(
+      `₿ ${model.burnBlockHeight}`,
+      `✗ ${this.operator.label} Ӿ ${this.stacker.label}`,
+      "delegate-stack-extend",
+      "extend count",
+      this.extendCount.toString(),
+      "new unlock height",
+      stackerWallet.unlockHeight.toString(),
+    );
+
+    // Refresh the model's state if the network gets to the next reward cycle.
+    model.refreshStateForNextRewardCycle(real);
+  }
+
+  toString() {
+    // fast-check will call toString() in case of errors, e.g. property failed.
+    // It will then make a minimal counterexample, a process called 'shrinking'
+    // https://github.com/dubzzz/fast-check/issues/2864#issuecomment-1098002642
+    return `${this.operator.label} Ӿ ${this.stacker.label} delegate-stack-extend extend count ${this.extendCount}`;
+  }
+}

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_DelegateStackIncreaseCommand.ts

@@ -10,7 +10,7 @@ import { expect } from "vitest";
 import { Cl } from "@stacks/transactions";
 
 /**
- * The DelegateStackIncreaseCommand allows a pool operator to
+ * The `DelegateStackIncreaseCommand` allows a pool operator to
  * increase an active stacking lock, issuing a "partial commitment"
  * for the increased cycles.
  *
@@ -33,7 +33,7 @@ export class DelegateStackIncreaseCommand implements PoxCommand {
   readonly increaseBy: number;
 
   /**
-   * Constructs a DelegateStackIncreaseCommand to increase the uSTX amount
+   * Constructs a `DelegateStackIncreaseCommand` to increase the uSTX amount
    * previously locked on behalf of a Stacker.
    *
    * @param operator - Represents the Pool Operator's wallet.

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_DelegateStackIncreaseCommand_Err.ts

@@ -0,0 +1,95 @@
+import {
+  logCommand,
+  PoxCommand,
+  Real,
+  Stub,
+  Wallet,
+} from "./pox_CommandModel.ts";
+import { poxAddressToTuple } from "@stacks/stacking";
+import { expect } from "vitest";
+import { Cl } from "@stacks/transactions";
+
+type CheckFunc = (
+  this: DelegateStackIncreaseCommand_Err,
+  model: Readonly<Stub>,
+) => boolean;
+
+export class DelegateStackIncreaseCommand_Err implements PoxCommand {
+  readonly operator: Wallet;
+  readonly stacker: Wallet;
+  readonly increaseBy: number;
+  readonly checkFunc: CheckFunc;
+  readonly errorCode: number;
+
+  /**
+   * Constructs a `DelegateStackIncreaseCommand_Err` to increase the uSTX amount
+   * previously locked on behalf of a Stacker.
+   *
+   * @param operator - Represents the Pool Operator's wallet.
+   * @param stacker - Represents the Stacker's wallet.
+   * @param increaseBy - Represents the locked amount to be increased by.
+   * @param checkFunc - A function to check constraints for running this command.
+   * @param errorCode - The expected error code when running this command.
+   */
+  constructor(
+    operator: Wallet,
+    stacker: Wallet,
+    increaseBy: number,
+    checkFunc: CheckFunc,
+    errorCode: number,
+  ) {
+    this.operator = operator;
+    this.stacker = stacker;
+    this.increaseBy = increaseBy;
+    this.checkFunc = checkFunc;
+    this.errorCode = errorCode;
+  }
+
+  check = (model: Readonly<Stub>): boolean => this.checkFunc.call(this, model);
+
+  run(model: Stub, real: Real): void {
+    const stackerWallet = model.stackers.get(this.stacker.stxAddress)!;
+    const prevLocked = stackerWallet.amountLocked;
+    // Act
+    const delegateStackIncrease = real.network.callPublicFn(
+      "ST000000000000000000002AMW42H.pox-4",
+      "delegate-stack-increase",
+      [
+        // (stacker principal)
+        Cl.principal(this.stacker.stxAddress),
+        // (pox-addr { version: (buff 1), hashbytes: (buff 32) })
+        poxAddressToTuple(this.operator.btcAddress),
+        // (increase-by uint)
+        Cl.uint(this.increaseBy),
+      ],
+      this.operator.stxAddress,
+    );
+
+    // Assert
+    expect(delegateStackIncrease.result).toBeErr(Cl.int(this.errorCode));
+
+    // Log to console for debugging purposes. This is not necessary for the
+    // test to pass but it is useful for debugging and eyeballing the test.
+    logCommand(
+      `₿ ${model.burnBlockHeight}`,
+      `✗ ${this.operator.label} Ӿ ${this.stacker.label}`,
+      "delegate-stack-increase",
+      "increased by",
+      this.increaseBy.toString(),
+      "previously locked",
+      prevLocked.toString(),
+      "total locked",
+      stackerWallet.amountLocked.toString(),
+    );
+
+    // Refresh the model's state if the network gets to the next reward cycle.
+    model.refreshStateForNextRewardCycle(real);
+  }
+
+  toString() {
+    // fast-check will call toString() in case of errors, e.g. property failed.
+    // It will then make a minimal counterexample, a process called 'shrinking'
+    // https://github.com/dubzzz/fast-check/issues/2864#issuecomment-1098002642
+    return `${this.operator.label} delegate-stack-increase by ${this.increaseBy}`;
+  }
+}

contrib/boot-contracts-stateful-prop-tests/tests/pox-4/pox_DelegateStackStxCommand.ts

@@ -26,7 +26,7 @@ import { currentCycle } from "./pox_Commands.ts";
  *   `get-stacking-minimum` function at the time of this call.
  * - The Stacker cannot currently be engaged in another stacking operation.
  * - The Stacker has to currently be delegating to the Operator.
- * - The stacked STX amount should be less than or equal to the delegated
+ * - The stacked uSTX amount should be less than or equal to the delegated
  *   amount.
  * - The stacked uSTX amount should be less than or equal to the Stacker's
  *   balance.
@@ -47,7 +47,7 @@ export class DelegateStackStxCommand implements PoxCommand {
    * on behalf of a Stacker.
    *
    * @param operator - Represents the Pool Operator's wallet.
-   * @param stacker - Represents the STacker's wallet.
+   * @param stacker - Represents the Stacker's wallet.
    * @param period - Number of reward cycles to lock uSTX.
    * @param amountUstx - The uSTX amount stacked by the Operator on behalf
    *                     of the Stacker.