Add stateful property tests for SIP-031

Added `sip-031.stateful.prop.test.ts`, with initial command set:
Claim, ClaimErr, Mint, MintInitial, MineBlocks, UpdateRecipient,
UpdateRecipientErr.

Tests use fast-check's `modelRun` to verify sip-031.clar against
a tracked model.

Based on:
- https://github.com/stacks-network/stacks-core/tree/a5587d13c51829f49a7645d9484469e5ca891e29/contrib/boot-contracts-stateful-prop-tests/tests/pox-4
- https://blog.nikosbaxevanis.com/2022/03/15/clarity-clarity-model-based-testing-primer/
- https://github.com/moodmosaic/counter-invariant-tests/tree/99c9987c446c74feb1acf970993214c7b2350b53/tests/counter

!!! NOT A COMPLETE TEST SUITE !!!

Author: moodmosaic

contrib/core-contract-tests/tests/sip-031/commands/Claim.ts

@@ -0,0 +1,36 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { calculateClaimable, logCommand, trackCommandRun } from "./utils";
+import { expect } from "vitest";
+import { txOk } from "@clarigen/test";
+
+export const Claim = (accounts: Real["accounts"]) =>
+  fc.record({
+    sender: fc.constantFrom(
+      ...Object.values(accounts).map((x) => x.address),
+    ),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => {
+      const claimable = calculateClaimable(model);
+      return model.initialized === true && model.recipient === r.sender &&
+        claimable > 0n;
+    },
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "claim");
+
+      const expectedClaim = calculateClaimable(model);
+      const receipt = txOk(real.contracts.sip031.claim(), r.sender);
+      expect(receipt.value).toBe(expectedClaim);
+
+      model.balance -= expectedClaim;
+      model.totalClaimed += expectedClaim;
+
+      logCommand({
+        sender: r.sender,
+        status: "ok",
+        action: "claim",
+        value: `amount ${expectedClaim}`,
+      });
+    },
+    toString: () => `claim`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/ClaimErr.ts

@@ -0,0 +1,45 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { calculateClaimable, logCommand, trackCommandRun } from "./utils";
+import { expect } from "vitest";
+import { txErr } from "@clarigen/test";
+
+export const ClaimErr = (accounts: Real["accounts"]) =>
+  fc.record({
+    sender: fc.constantFrom(
+      ...Object.values(accounts).map((x) => x.address),
+    ),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => {
+      if (model.initialized !== true) {
+        return false;
+      }
+
+      if (model.recipient !== r.sender) {
+        return true;
+      }
+
+      const claimable = calculateClaimable(model);
+      return claimable === 0n;
+    },
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "claim-err");
+
+      const expectedError = model.recipient !== r.sender
+        ? model.constants.ERR_NOT_ALLOWED
+        : model.constants.ERR_NOTHING_TO_CLAIM;
+      const receipt = txErr(real.contracts.sip031.claim(), r.sender);
+      expect(receipt.value).toBe(expectedError);
+
+      const errString = expectedError === model.constants.ERR_NOT_ALLOWED
+        ? "ERR_NOT_ALLOWED"
+        : "ERR_NOTHING_TO_CLAIM";
+      logCommand({
+        sender: r.sender,
+        status: "err",
+        action: "claim-err",
+        error: errString,
+      });
+    },
+    toString: () => `claim-err as ${r.sender}`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/MineBlocks.ts

@@ -0,0 +1,23 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { logCommand, trackCommandRun } from "./utils";
+
+export const MineBlocks = () =>
+  fc.record({
+    blocks: fc.integer({ min: 1, max: 100 }),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => model.initialized === true,
+    run: (model: Model, _real: Real) => {
+      trackCommandRun(model, "mine-blocks");
+
+      simnet.mineEmptyBlocks(r.blocks);
+
+      logCommand({
+        sender: undefined,
+        status: "ok",
+        action: "mine-blocks",
+        value: `${r.blocks}`,
+      });
+    },
+    toString: () => `mine-blocks ${r.blocks}`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/Mint.ts

@@ -0,0 +1,32 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { txOk } from "@clarigen/test";
+import { logCommand, trackCommandRun } from "./utils";
+
+export const Mint = () =>
+  fc.record({
+    amount: fc.bigInt(1n, 100000000n),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => model.initialized === true,
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "mint");
+
+      txOk(
+        real.contracts.sip031Indirect.transferStx(
+          r.amount,
+          real.contracts.sip031.identifier,
+        ),
+        real.accounts.wallet_4.address,
+      );
+
+      model.balance += r.amount;
+
+      logCommand({
+        sender: undefined,
+        status: "ok",
+        action: "mint",
+        value: `amount ${r.amount}`,
+      });
+    },
+    toString: () => `mint ${r.amount}`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/MintInitial.ts

@@ -0,0 +1,52 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { txOk } from "@clarigen/test";
+import { logCommand, trackCommandRun } from "./utils";
+
+export const MintInitial = (accounts: Real["accounts"]) =>
+  fc.record({}).map(() => ({
+    check: (model: Readonly<Model>) => model.initialized === false,
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "mint-initial");
+
+      const contracts = real.contracts;
+      const indirect = contracts.sip031Indirect;
+      const sip031 = contracts.sip031;
+
+      // Split initial mint into two transfers to wallet_4 from wallet_5 and wallet_6.
+      txOk(
+        indirect.transferStx(
+          sip031.constants.INITIAL_MINT_AMOUNT / 2n,
+          accounts.wallet_4.address,
+        ),
+        accounts.wallet_5.address,
+      );
+      txOk(
+        indirect.transferStx(
+          sip031.constants.INITIAL_MINT_AMOUNT / 2n,
+          accounts.wallet_4.address,
+        ),
+        accounts.wallet_6.address,
+      );
+
+      // Forward full amount from wallet_4 into the SIP-031 contract.
+      txOk(
+        indirect.transferStx(
+          sip031.constants.INITIAL_MINT_AMOUNT,
+          sip031.identifier,
+        ),
+        accounts.wallet_4.address,
+      );
+
+      model.initialized = true;
+      model.balance = sip031.constants.INITIAL_MINT_AMOUNT;
+
+      logCommand({
+        sender: undefined,
+        status: "ok",
+        action: "setup-initial-funding",
+        value: `amount ${sip031.constants.INITIAL_MINT_AMOUNT}`,
+      });
+    },
+    toString: () => `setup-initial-funding`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/UpdateRecipient.ts

@@ -0,0 +1,40 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { expect } from "vitest";
+import { txOk } from "@clarigen/test";
+import { logCommand, trackCommandRun } from "./utils";
+
+export const UpdateRecipient = (accounts: Real["accounts"]) =>
+  fc.record({
+    sender: fc.constantFrom(
+      ...Object.values(accounts).map((x) => x.address),
+    ),
+    newRecipient: fc.constantFrom(
+      ...Object.values(accounts as Record<string, { address: string }>).map((
+        acc,
+      ) => acc.address),
+    ),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => {
+      return model.initialized === true && model.recipient === r.sender;
+    },
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "update-recipient");
+
+      const receipt = txOk(
+        real.contracts.sip031.updateRecipient(r.newRecipient),
+        r.sender,
+      );
+      expect(receipt.value).toBe(true);
+
+      model.recipient = r.newRecipient;
+
+      logCommand({
+        sender: r.sender,
+        status: "ok",
+        action: "update-recipient",
+        value: `to ${r.newRecipient}`,
+      });
+    },
+    toString: () => `update-recipient to ${r.newRecipient}`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/UpdateRecipientErr.ts

@@ -0,0 +1,36 @@
+import fc from "fast-check";
+import type { Model, Real } from "./types";
+import { expect } from "vitest";
+import { txErr } from "@clarigen/test";
+import { logCommand, trackCommandRun } from "./utils";
+
+export const UpdateRecipientErr = (accounts: Real["accounts"]) =>
+  fc.record({
+    sender: fc.constantFrom(
+      ...Object.values(accounts).map((x) => x.address),
+    ),
+    newRecipient: fc.constantFrom(
+      ...Object.values(accounts).map((x) => x.address),
+    ),
+  }).map((r) => ({
+    check: (model: Readonly<Model>) => {
+      return model.initialized === true && model.recipient !== r.sender;
+    },
+    run: (model: Model, real: Real) => {
+      trackCommandRun(model, "update-recipient-err");
+
+      const receipt = txErr(
+        real.contracts.sip031.updateRecipient(r.newRecipient),
+        r.sender,
+      );
+      expect(receipt.value).toBe(model.constants.ERR_NOT_ALLOWED);
+
+      logCommand({
+        sender: r.sender,
+        status: "err",
+        action: "update-recipient-err",
+        error: "ERR_NOT_ALLOWED",
+      });
+    },
+    toString: () => `update-recipient-err as ${r.sender}`,
+  }));

contrib/core-contract-tests/tests/sip-031/commands/types.ts

@@ -0,0 +1,20 @@
+import { accounts, project } from "../../clarigen-types";
+import { projectFactory } from "@clarigen/core";
+
+const contracts = projectFactory(project, "simnet");
+
+export type Real = {
+  accounts: typeof accounts;
+  contracts: typeof contracts;
+};
+
+export interface Model {
+  balance: bigint;
+  blockHeight: bigint;
+  constants: typeof contracts.sip031.constants;
+  deployBlockHeight: bigint;
+  initialized: boolean;
+  recipient: string;
+  totalClaimed: bigint;
+  statistics: Map<string, number>;
+}

contrib/core-contract-tests/tests/sip-031/commands/utils.ts

@@ -0,0 +1,99 @@
+import type { Model } from "./types";
+
+export function calculateClaimable(model: Readonly<Model>): bigint {
+  const c = model.constants;
+
+  const max = c.INITIAL_MINT_VESTING_ITERATIONS;
+  const amt = c.INITIAL_MINT_VESTING_AMOUNT;
+  const per = c.STX_PER_ITERATION;
+  const step = c.INITIAL_MINT_VESTING_ITERATION_BLOCKS;
+
+  // If before deployment, nothing vested yet.
+  const diff = model.blockHeight < model.deployBlockHeight
+    ? 0n
+    : model.blockHeight - model.deployBlockHeight;
+
+  const iter = diff / step;
+  const vest = iter >= max ? amt : per * iter;
+
+  const total = c.INITIAL_MINT_IMMEDIATE_AMOUNT + vest;
+  const reserved = c.INITIAL_MINT_AMOUNT - total;
+
+  return model.balance > reserved ? model.balance - reserved : 0n;
+}
+
+export function logCommand({
+  sender,
+  status,
+  action,
+  value,
+  error,
+}: {
+  sender?: string;
+  status: "ok" | "err";
+  action: string;
+  value?: string | number | bigint;
+  error?: string;
+}) {
+  const senderStr = (sender ?? "system").padEnd(41, " ");
+  const statusStr = status === "ok" ? "✓" : "✗";
+  const actionStr = action.padEnd(22, " ");
+
+  let msg = `Ӿ ${senderStr} ${statusStr} ${actionStr}`;
+  if (value !== undefined) msg += ` ${String(value)}`;
+  if (error !== undefined) msg += ` error ${error}`;
+
+  console.log(msg);
+}
+
+export function trackCommandRun(model: Model, commandName: string) {
+  const count = model.statistics.get(commandName) || 0;
+  model.statistics.set(commandName, count + 1);
+}
+
+export function reportCommandRuns(model: Model) {
+  console.log("\nCommand execution counts:");
+  const orderedStatistics = Array.from(model.statistics.entries()).sort(
+    ([keyA], [keyB]) => {
+      return keyA.localeCompare(keyB);
+    },
+  );
+
+  logAsTree(orderedStatistics);
+}
+
+function 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}: x${node[key]["base"]}`);
+          printTree(node[key], indent + (isLast ? "    " : "│   "));
+        } else {
+          console.log(`${indent}${boxChar}${key}: ${node[key]}`);
+        }
+      }
+    });
+  };
+
+  printTree(tree);
+}