@stacks/rendezvous 0.1.2

package/README.md

@@ -0,0 +1,127 @@
+<div align="center">
+<img width="304" src="https://raw.githubusercontent.com/moodmosaic/nikosbaxevanis.com/gh-pages/images/rv.png" />
+</div>
+
+## Rendezvous `rv`: The Clarity Fuzzer
+
+Rendezvous `rv` is a Clarity fuzzer designed to cut through your smart contract's defenses with precision. Uncover vulnerabilities with unmatched power and intensity. Get ready to meet your contract's vulnerabilities head-on.
+
+### Prerequisites
+
+- **Node.js**: Supported versions include 18, 20, and 22. Other versions may work, but they are untested.
+
+### Inspiration
+
+The `rv` fuzzer, inspired by John Hughes' paper _"Testing the Hard Stuff and Staying Sane"_[^1], ensures contract robustness with Clarity invariants and tests.
+
+### Example Directory Structure
+
+```
+root
+├── Clarinet.toml
+├── contracts
+│   ├── contract.clar
+│   ├── contract.tests.clar
+└── settings
+    └── Devnet.toml
+```
+
+### Installation
+
+---
+
+**Install the package locally**
+
+```
+npm install "https://github.com/stacks-network/rendezvous.git"
+```
+
+Run the fuzzer locally:
+
+```
+npx rv <path-to-clarinet-project> <contract-name> <type>
+```
+
+---
+
+**Install the package globally**
+
+```
+git clone https://github.com/stacks-network/rendezvous
+npm install
+npm install --global .
+```
+
+Run the fuzzer from anywhere on your system:
+
+```
+rv <path-to-clarinet-project> <contract-name> <type>
+```
+
+---
+
+### Configuration
+
+**Positional arguments:**
+
+- `path-to-clarinet-project` - Path to the root directory of the Clarinet project (where Clarinet.toml exists).
+- `contract-name` - Name of the contract to test, per Clarinet.toml.
+- `type` - Type of test to run. Options:
+  - `test` - Run property-based tests.
+  - `invariant` - Run invariant tests.
+
+**Options:**
+
+- `--seed` – The seed to use for the replay functionality.
+- `--path` – The path to use for the replay functionality.
+- `--runs` – The number of test iterations to use for exercising the contracts.
+  (default: `100`)
+
+---
+
+### Example (`test`)
+
+Here's an example of a test that checks reversing a list twice returns the original:
+
+```clarity
+(define-public (test-reverse-list (seq (list 127 uint)))
+  (begin
+    (asserts!
+      (is-eq seq
+        (reverse-uint
+          (reverse-uint seq)))
+      (err u999))
+    (ok true)))
+```
+
+You can run property-based tests using `rv` with the following command:
+
+```
+rv example reverse test
+```
+
+---
+
+### Example (`invariant`)
+
+Here's a Clarity invariant to detect a bug in the example counter contract:
+
+```clarity
+(define-read-only (invariant-counter-gt-zero)
+  (let
+      ((increment-num-calls (default-to u0 (get called (map-get? context "increment"))))
+       (decrement-num-calls (default-to u0 (get called (map-get? context "decrement")))))
+    (if (> increment-num-calls decrement-num-calls)
+        (> (var-get counter) u0)
+        true)))
+```
+
+You can run invariant tests using `rv` with the following command:
+
+```
+rv example counter invariant
+```
+
+---
+
+[^1]: Hughes, J. (2004). _Testing the Hard Stuff and Staying Sane_. In Proceedings of the ACM SIGPLAN Workshop on Haskell (Haskell '04).

package/dist/app.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const path_1 = require("path");
+const events_1 = require("events");
+const property_1 = require("./property");
+const invariant_1 = require("./invariant");
+const shared_1 = require("./shared");
+const citizen_1 = require("./citizen");
+const package_json_1 = require("./package.json");
+const ansicolor_1 = require("ansicolor");
+const logger = (log, logLevel = "log") => {
+    console[logLevel](log);
+};
+const helpMessage = `
+  rv v${package_json_1.version}
+  
+  Usage: ./rv <path-to-clarinet-project> <contract-name> <type> [--seed=<seed>] [--path=<path>] [--runs=<runs>]
+
+  Positional arguments:
+    path-to-clarinet-project - The path to the Clarinet project.
+    contract-name - The name of the contract to be fuzzed.
+    type - The type to use for exercising the contracts. Possible values: test, invariant.
+
+  Options:
+    --seed - The seed to use for the replay functionality.
+    --path - The path to use for the replay functionality.
+    --runs - The runs to use for iterating over the tests. Default: 100.
+    --help - Show the help message.
+  `;
+const parseOptionalArgument = (argName) => {
+    var _a;
+    return (_a = process.argv
+        .find((arg, idx) => idx >= 4 && arg.toLowerCase().startsWith(`--${argName}`))) === null || _a === void 0 ? void 0 : _a.split("=")[1];
+};
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const radio = new events_1.EventEmitter();
+        radio.on("logMessage", (log) => logger(log));
+        radio.on("logFailure", (log) => logger((0, ansicolor_1.red)(log), "error"));
+        const args = process.argv;
+        if (args.includes("--help")) {
+            radio.emit("logMessage", helpMessage);
+            return;
+        }
+        /** The relative path to the Clarinet project. */
+        const manifestDir = args[2];
+        if (!manifestDir || manifestDir.startsWith("--")) {
+            radio.emit("logMessage", (0, ansicolor_1.red)("\nNo path to Clarinet project provided. Supply it immediately or face the relentless scrutiny of your contract's vulnerabilities."));
+            radio.emit("logMessage", helpMessage);
+            return;
+        }
+        /** The target contract name. */
+        const sutContractName = args[3];
+        if (!sutContractName || sutContractName.startsWith("--")) {
+            radio.emit("logMessage", (0, ansicolor_1.red)("\nNo target contract name provided. Please provide the contract name to be fuzzed."));
+            radio.emit("logMessage", helpMessage);
+            return;
+        }
+        const type = (_a = args[4]) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+        if (!type || type.startsWith("--") || !["test", "invariant"].includes(type)) {
+            radio.emit("logMessage", (0, ansicolor_1.red)("\nInvalid type provided. Please provide the type of test to be executed. Possible values: test, invariant."));
+            radio.emit("logMessage", helpMessage);
+            return;
+        }
+        /** The relative path to `Clarinet.toml`. */
+        const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+        radio.emit("logMessage", `Using manifest path: ${manifestPath}`);
+        radio.emit("logMessage", `Target contract: ${sutContractName}`);
+        const seed = parseInt(parseOptionalArgument("seed"), 10) || undefined;
+        if (seed !== undefined) {
+            radio.emit("logMessage", `Using seed: ${seed}`);
+        }
+        const path = parseOptionalArgument("path") || undefined;
+        if (path !== undefined) {
+            radio.emit("logMessage", `Using path: ${path}`);
+        }
+        const runs = parseInt(parseOptionalArgument("runs"), 10) || undefined;
+        if (runs !== undefined) {
+            radio.emit("logMessage", `Using runs: ${runs}`);
+        }
+        const simnet = yield (0, citizen_1.issueFirstClassCitizenship)(manifestDir, sutContractName);
+        /**
+         * The list of contract IDs for the SUT contract names, as per the simnet.
+         */
+        const rendezvousList = Array.from((0, shared_1.getSimnetDeployerContractsInterfaces)(simnet).keys()).filter((deployedContract) => [sutContractName].includes((0, shared_1.getContractNameFromContractId)(deployedContract)));
+        const rendezvousAllFunctions = (0, shared_1.getFunctionsFromContractInterfaces)(new Map(Array.from((0, shared_1.getSimnetDeployerContractsInterfaces)(simnet)).filter(([contractId]) => rendezvousList.includes(contractId))));
+        // Select the testing routine based on `type`.
+        // If "invariant", call `checkInvariants` to verify contract invariants.
+        // If "test", call `checkProperties` for property-based testing.
+        switch (type) {
+            case "invariant": {
+                (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio);
+                break;
+            }
+            case "test": {
+                (0, property_1.checkProperties)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio);
+                break;
+            }
+        }
+    });
+}
+if (require.main === module) {
+    main();
+}

package/dist/citizen.js

@@ -0,0 +1,231 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTestContractSource = exports.buildRendezvousData = exports.getContractSource = exports.groupContractsByEpochFromSimnetPlan = exports.issueFirstClassCitizenship = void 0;
+exports.scheduleRendezvous = scheduleRendezvous;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = __importDefault(require("yaml"));
+const clarinet_sdk_1 = require("@hirosystems/clarinet-sdk");
+/**
+ * Prepares the simnet environment and assures the target contract is treated
+ * as a first-class citizen, by combining it with its tests. This function
+ * handles:
+ * - Contract sorting by epoch based on the deployment plan.
+ * - Combining the target contract with its tests and deploying all contracts
+ *   to the simnet.
+ *
+ * @param manifestDir - The relative path to the manifest directory.
+ * @param sutContractName - The target contract name.
+ * @returns The initialized simnet instance with all contracts deployed, with
+ * the target contract treated as a first-class citizen.
+ */
+const issueFirstClassCitizenship = (manifestDir, sutContractName) => __awaiter(void 0, void 0, void 0, function* () {
+    const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+    // Initialize the simnet, to generate the simnet plan and instance. The empty
+    // session will be set up, and contracts will be deployed in the correct
+    // order based on the simnet plan a few lines below.
+    const simnet = yield (0, clarinet_sdk_1.initSimnet)(manifestPath);
+    const simnetPlan = yaml_1.default.parse((0, fs_1.readFileSync)((0, path_1.join)(manifestDir, "deployments", "default.simnet-plan.yaml"), {
+        encoding: "utf-8",
+    }));
+    const sortedContractsByEpoch = (0, exports.groupContractsByEpochFromSimnetPlan)(simnetPlan);
+    yield simnet.initEmptySession();
+    // Combine the target contract with its tests into a single contract. The
+    // resulting contract will replace the target contract in the simnet. This
+    // map stores the contract name and its corresponding source code.
+    const rendezvousSources = new Map([sutContractName]
+        .map((contractName) => (0, exports.buildRendezvousData)(simnetPlan, contractName, manifestDir))
+        .map((rendezvousContractData) => [
+        rendezvousContractData.rendezvousContractName,
+        rendezvousContractData.rendezvousSource,
+    ]));
+    // Deploy the contracts to the simnet in the correct order.
+    yield deployContracts(simnet, sortedContractsByEpoch, (name, props) => (0, exports.getContractSource)([sutContractName], rendezvousSources, name, props, manifestDir));
+    return simnet;
+});
+exports.issueFirstClassCitizenship = issueFirstClassCitizenship;
+/**
+ * Groups contracts by epoch from the simnet plan.
+ * @param simnetPlan - The simnet plan.
+ * @returns A record of contracts grouped by epoch. The record key is the epoch
+ * string, and the value is an array of contracts. Each contract is represented
+ * as a record with the contract name as the key and a record containing the
+ * contract path and clarity version as the value.
+ */
+const groupContractsByEpochFromSimnetPlan = (simnetPlan) => {
+    return simnetPlan.plan.batches.reduce((acc, batch) => {
+        const epoch = batch.epoch;
+        const contracts = batch.transactions
+            .filter((tx) => tx["emulated-contract-publish"])
+            .map((tx) => {
+            const contract = tx["emulated-contract-publish"];
+            return {
+                [contract["contract-name"]]: {
+                    path: contract.path,
+                    clarity_version: contract["clarity-version"],
+                },
+            };
+        });
+        if (contracts.length > 0) {
+            acc[epoch] = (acc[epoch] || []).concat(contracts);
+        }
+        return acc;
+    }, {});
+};
+exports.groupContractsByEpochFromSimnetPlan = groupContractsByEpochFromSimnetPlan;
+/**
+ * Deploy the contracts to the simnet in the correct order.
+ * @param simnet - The simnet instance.
+ * @param contractsByEpoch - The record of contracts by epoch.
+ * @param getContractSourceFn - The function to retrieve the contract source.
+ */
+const deployContracts = (simnet, contractsByEpoch, getContractSourceFn) => __awaiter(void 0, void 0, void 0, function* () {
+    for (const [epoch, contracts] of Object.entries(contractsByEpoch)) {
+        // Move to the next epoch and deploy the contracts in the correct order.
+        simnet.setEpoch(epoch);
+        for (const contract of contracts.flatMap(Object.entries)) {
+            const [name, props] = contract;
+            const source = getContractSourceFn(name, props);
+            // For requirement contracts, use the original sender. The sender address
+            // is included in the path:
+            // "./.cache/requirements/<address>.contract-name.clar".
+            const sender = props.path.includes(".cache")
+                ? props.path.split("requirements")[1].slice(1).split(".")[0]
+                : simnet.deployer;
+            simnet.deployContract(name, source, { clarityVersion: props.clarity_version }, sender);
+        }
+    }
+});
+/**
+ * Conditionally retrieve the contract source based on whether the contract is
+ * a SUT contract or not.
+ * @param sutContractNames - The list of SUT contract names.
+ * @param rendezvousMap - The rendezvous map.
+ * @param contractName - The contract name.
+ * @param contractProps - The contract properties.
+ * @param manifestDir - The relative path to the manifest directory.
+ * @returns The contract source.
+ */
+const getContractSource = (sutContractNames, rendezvousMap, contractName, contractProps, manifestDir) => {
+    if (sutContractNames.includes(contractName)) {
+        const contractSource = rendezvousMap.get(contractName);
+        if (!contractSource) {
+            throw new Error(`Contract source not found for ${contractName}`);
+        }
+        return contractSource;
+    }
+    else {
+        return (0, fs_1.readFileSync)((0, path_1.join)(manifestDir, contractProps.path), {
+            encoding: "utf-8",
+        });
+    }
+};
+exports.getContractSource = getContractSource;
+/**
+ * Build the Rendezvous data.
+ * @param simnetPlan The parsed simnet plan.
+ * @param contractName The contract name.
+ * @param manifestDir The relative path to the manifest directory.
+ * @returns The Rendezvous data representing an object. The returned object
+ * contains the Rendezvous source code and the Rendezvous contract name.
+ */
+const buildRendezvousData = (simnetPlan, contractName, manifestDir) => {
+    try {
+        const sutContractSource = getSimnetPlanContractSource(simnetPlan, manifestDir, contractName);
+        const testContractSource = (0, exports.getTestContractSource)(simnetPlan, contractName, manifestDir);
+        const rendezvousSource = scheduleRendezvous(sutContractSource, testContractSource);
+        return {
+            rendezvousSource: rendezvousSource,
+            rendezvousContractName: contractName,
+        };
+    }
+    catch (e) {
+        throw new Error(`Error processing "${contractName}" contract: ${e.message}`);
+    }
+};
+exports.buildRendezvousData = buildRendezvousData;
+/**
+ * Get the contract source code from the simnet plan.
+ * @param simnetPlan The parsed simnet plan.
+ * @param manifestDir The relative path to the manifest directory.
+ * @param sutContractName The target contract name.
+ * @returns The contract source code.
+ */
+const getSimnetPlanContractSource = (simnetPlan, manifestDir, sutContractName) => {
+    var _a;
+    // Filter for transactions that contain "emulated-contract-publish".
+    const contractInfo = (_a = simnetPlan.plan.batches
+        .flatMap((batch) => batch.transactions)
+        .find((transaction) => transaction["emulated-contract-publish"] &&
+        transaction["emulated-contract-publish"]["contract-name"] ===
+            sutContractName)) === null || _a === void 0 ? void 0 : _a["emulated-contract-publish"];
+    if (contractInfo == undefined) {
+        throw new Error(`"${sutContractName}" contract not found in Clarinet.toml.`);
+    }
+    return (0, fs_1.readFileSync)((0, path_1.join)(manifestDir, contractInfo.path), {
+        encoding: "utf-8",
+    }).toString();
+};
+/**
+ * Get the test contract source code.
+ * @param simnetPlan The parsed simnet plan.
+ * @param sutContractName The target contract name.
+ * @param manifestDir The relative path to the manifest directory.
+ * @returns The test contract source code.
+ */
+const getTestContractSource = (simnetPlan, sutContractName, manifestDir) => {
+    var _a;
+    const contractInfo = (_a = simnetPlan.plan.batches
+        .flatMap((batch) => batch.transactions)
+        .find((transaction) => transaction["emulated-contract-publish"] &&
+        transaction["emulated-contract-publish"]["contract-name"] ===
+            sutContractName)) === null || _a === void 0 ? void 0 : _a["emulated-contract-publish"];
+    const sutContractPath = contractInfo.path;
+    const extension = ".clar";
+    if (!sutContractPath.endsWith(extension)) {
+        throw new Error(`Invalid contract extension for the "${sutContractName}" contract.`);
+    }
+    const testContractPath = sutContractPath.replace(extension, `.tests${extension}`);
+    try {
+        return (0, fs_1.readFileSync)((0, path_1.join)(manifestDir, testContractPath), {
+            encoding: "utf-8",
+        }).toString();
+    }
+    catch (e) {
+        throw new Error(`Error retrieving the corresponding test contract for the "${sutContractName}" contract. ${e.message}`);
+    }
+};
+exports.getTestContractSource = getTestContractSource;
+/**
+ * Schedule a Rendezvous between the System Under Test (`SUT`) and the
+ * invariants.
+ * @param sutContractSource The SUT contract source code.
+ * @param invariants The invariants contract source code.
+ * @returns The Rendezvous source code.
+ */
+function scheduleRendezvous(sutContractSource, invariants) {
+    /**
+     * The `context` map tracks how many times each function has been called.
+     * This data can be useful for invariant tests to check behavior over time.
+     */
+    const context = `(define-map context (string-ascii 100) {
+    called: uint
+    ;; other data
+  })
+
+  (define-public (update-context (function-name (string-ascii 100)) (called uint))
+    (ok (map-set context function-name {called: called})))`;
+    return `${sutContractSource}\n\n${context}\n\n${invariants}`;
+}

package/dist/citizen.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/heatstroke.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Heatstrokes Reporter
+ *
+ * This reporter integrates with `fast-check` to provide detailed and formatted
+ * outputs for failed property-based tests. It captures key information such as
+ * the contract, functions, arguments, outputs, and the specific invariant that
+ * failed, enabling quick identification of issues.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = reporter;
+/**
+ * Reports the details of a failed property-based test run.
+ *
+ * This function provides a detailed report when a fuzzing test fails including
+ * the contract, functions, arguments, outputs, and the specific invariant that
+ * failed.
+ *
+ * @param runDetails - The details of the test run provided by fast-check.
+ * @property runDetails.failed - Indicates if the property test failed.
+ * @property runDetails.counterexample - The input that caused the failure.
+ * @property runDetails.numRuns - The number of test cases that were run.
+ * @property runDetails.seed - The seed used to generate the test cases.
+ * @property runDetails.path - The path to reproduce the failing test.
+ * @property runDetails.error - The error thrown during the test.
+ */
+const ansicolor_1 = require("ansicolor");
+const shared_1 = require("./shared");
+function reporter(
+//@ts-ignore
+runDetails, radio, type) {
+    var _a, _b;
+    if (runDetails.failed) {
+        // Report general run data.
+        const r = runDetails.counterexample[0];
+        radio.emit("logFailure", `\nError: Property failed after ${runDetails.numRuns} tests.`);
+        radio.emit("logFailure", `Seed : ${runDetails.seed}`);
+        if (runDetails.path) {
+            radio.emit("logFailure", `Path : ${runDetails.path}`);
+        }
+        switch (type) {
+            case "invariant": {
+                // Report specific run data for the invariant testing type.
+                radio.emit("logFailure", `\nCounterexample:`);
+                radio.emit("logFailure", `- Contract : ${(0, shared_1.getContractNameFromContractId)(r.rendezvousContractId)}`);
+                radio.emit("logFailure", `- Function : ${r.selectedFunction.name} (${r.selectedFunction.access})`);
+                radio.emit("logFailure", `- Arguments: ${JSON.stringify(r.functionArgsArb)}`);
+                radio.emit("logFailure", `- Caller   : ${r.sutCaller[0]}`);
+                radio.emit("logFailure", `- Outputs  : ${JSON.stringify(r.selectedFunction.outputs)}`);
+                radio.emit("logFailure", `- Invariant: ${r.selectedInvariant.name} (${r.selectedInvariant.access})`);
+                radio.emit("logFailure", `- Arguments: ${JSON.stringify(r.invariantArgsArb)}`);
+                radio.emit("logFailure", `- Caller   : ${r.invariantCaller[0]}`);
+                radio.emit("logFailure", `\nWhat happened? Rendezvous went on a rampage and found a weak spot:\n`);
+                const formattedError = `The invariant "${r.selectedInvariant.name}" returned:\n\n${(_a = runDetails.error) === null || _a === void 0 ? void 0 : _a.toString().split("\n").map((line) => "    " + line).join("\n")}\n`;
+                radio.emit("logFailure", formattedError);
+                break;
+            }
+            case "test": {
+                // Report specific run data for the property testing type.
+                radio.emit("logFailure", `\nCounterexample:`);
+                radio.emit("logFailure", `- Test Contract : ${(0, shared_1.getContractNameFromContractId)(r.testContractId)}`);
+                radio.emit("logFailure", `- Test Function : ${r.selectedTestFunction.name} (${r.selectedTestFunction.access})`);
+                radio.emit("logFailure", `- Arguments     : ${JSON.stringify(r.functionArgsArb)}`);
+                radio.emit("logFailure", `- Caller        : ${r.testCaller[0]}`);
+                radio.emit("logFailure", `- Outputs       : ${JSON.stringify(r.selectedTestFunction.outputs)}`);
+                radio.emit("logFailure", `\nWhat happened? Rendezvous went on a rampage and found a weak spot:\n`);
+                const formattedError = `The test function "${r.selectedTestFunction.name}" returned:\n\n${(_b = runDetails.error) === null || _b === void 0 ? void 0 : _b.toString().split("\n").map((line) => "    " + line).join("\n")}\n`;
+                radio.emit("logFailure", formattedError);
+                break;
+            }
+        }
+    }
+    else {
+        radio.emit("logMessage", (0, ansicolor_1.green)(`\nOK, ${type === "invariant" ? "invariants" : "properties"} passed after ${runDetails.numRuns} runs.\n`));
+    }
+}