@stacks/rendezvous 0.3.0 → 0.4.0

package/README.md

@@ -56,6 +56,8 @@ npx rv <path-to-clarinet-project> <contract-name> <type>
 - `--path` – The path to use for the replay functionality.
 - `--runs` – The number of test iterations to use for exercising the contracts.
   (default: `100`)
+- `--dial` – The path to a JavaScript file containing custom pre- and
+  post-execution functions (dialers).
 
 ---
 

package/dist/app.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getManifestFileName = void 0;
 exports.main = main;
 const path_1 = require("path");
 const events_1 = require("events");
@@ -19,13 +20,31 @@ const shared_1 = require("./shared");
 const citizen_1 = require("./citizen");
 const package_json_1 = require("./package.json");
 const ansicolor_1 = require("ansicolor");
+const fs_1 = require("fs");
+const dialer_1 = require("./dialer");
 const logger = (log, logLevel = "log") => {
     console[logLevel](log);
 };
+/**
+ * Gets the manifest file name for a Clarinet project.
+ * If a custom manifest exists (`Clarinet-<contract-name>.toml`), it is used.
+ * Otherwise, the default `Clarinet.toml` is returned.
+ * @param manifestDir The relative path to the Clarinet project directory.
+ * @param targetContractName The target contract name.
+ * @returns The manifest file name.
+ */
+const getManifestFileName = (manifestDir, targetContractName) => {
+    const isCustomManifest = (0, fs_1.existsSync)((0, path_1.resolve)(manifestDir, `Clarinet-${targetContractName}.toml`));
+    if (isCustomManifest) {
+        return `Clarinet-${targetContractName}.toml`;
+    }
+    return "Clarinet.toml";
+};
+exports.getManifestFileName = getManifestFileName;
 const helpMessage = `
   rv v${package_json_1.version}
   
-  Usage: rv <path-to-clarinet-project> <contract-name> <type> [--seed=<seed>] [--path=<path>] [--runs=<runs>]
+  Usage: rv <path-to-clarinet-project> <contract-name> <type> [--seed=<seed>] [--path=<path>] [--runs=<runs>] [--dial=<path-to-dialers-file>] [--help]
 
   Positional arguments:
     path-to-clarinet-project - The path to the Clarinet project.
@@ -36,6 +55,7 @@ const helpMessage = `
     --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.
+    --dial – The path to a JavaScript file containing custom pre- and post-execution functions (dialers).
     --help - Show the help message.
   `;
 const parseOptionalArgument = (argName) => {
@@ -74,8 +94,11 @@ function main() {
             radio.emit("logMessage", helpMessage);
             return;
         }
-        /** The relative path to `Clarinet.toml`. */
-        const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+        /**
+         * The relative path to the manifest file, either `Clarinet.toml` or
+         * `Clarinet-<contract-name>.toml`. If the latter exists, it is used.
+         */
+        const manifestPath = (0, path_1.join)(manifestDir, (0, exports.getManifestFileName)(manifestDir, sutContractName));
         radio.emit("logMessage", `Using manifest path: ${manifestPath}`);
         radio.emit("logMessage", `Target contract: ${sutContractName}`);
         const seed = parseInt(parseOptionalArgument("seed"), 10) || undefined;
@@ -90,7 +113,24 @@ function main() {
         if (runs !== undefined) {
             radio.emit("logMessage", `Using runs: ${runs}`);
         }
-        const simnet = yield (0, citizen_1.issueFirstClassCitizenship)(manifestDir, sutContractName);
+        /**
+         * The path to the dialer file. The dialer file allows the user to register
+         * custom pre and post-execution JavaScript functions to be executed before
+         * and after the public function calls during invariant testing.
+         */
+        const dialPath = parseOptionalArgument("dial") || undefined;
+        if (dialPath !== undefined) {
+            radio.emit("logMessage", `Using dial path: ${dialPath}`);
+        }
+        /**
+         * The dialer registry, which is used to keep track of all the custom dialers
+         * registered by the user using the `--dial` flag.
+         */
+        const dialerRegistry = dialPath !== undefined ? new dialer_1.DialerRegistry(dialPath) : undefined;
+        if (dialerRegistry !== undefined) {
+            dialerRegistry.registerDialers();
+        }
+        const simnet = yield (0, citizen_1.issueFirstClassCitizenship)(manifestDir, manifestPath, sutContractName);
         /**
          * The list of contract IDs for the SUT contract names, as per the simnet.
          */
@@ -101,7 +141,7 @@ function main() {
         // If "test", call `checkProperties` for property-based testing.
         switch (type) {
             case "invariant": {
-                (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio);
+                yield (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, dialerRegistry, radio);
                 break;
             }
             case "test": {

package/dist/citizen.js

@@ -27,12 +27,12 @@ const clarinet_sdk_1 = require("@hirosystems/clarinet-sdk");
  *   to the simnet.
  *
  * @param manifestDir The relative path to the manifest directory.
+ * @param manifestPath The absolute path to the manifest file.
  * @param sutContractName The target contract name.
  * @returns The initialized simnet instance with all contracts deployed, with
  * the test contract treated as a first-class citizen of the target contract.
  */
-const issueFirstClassCitizenship = (manifestDir, sutContractName) => __awaiter(void 0, void 0, void 0, function* () {
-    const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+const issueFirstClassCitizenship = (manifestDir, manifestPath, sutContractName) => __awaiter(void 0, void 0, void 0, function* () {
     // 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.
@@ -152,8 +152,8 @@ const buildRendezvousData = (simnetPlan, contractName, manifestDir) => {
             rendezvousContractName: contractName,
         };
     }
-    catch (e) {
-        throw new Error(`Error processing "${contractName}" contract: ${e.message}`);
+    catch (error) {
+        throw new Error(`Error processing "${contractName}" contract: ${error.message}`);
     }
 };
 exports.buildRendezvousData = buildRendezvousData;
@@ -204,8 +204,8 @@ const getTestContractSource = (simnetPlan, sutContractName, manifestDir) => {
             encoding: "utf-8",
         }).toString();
     }
-    catch (e) {
-        throw new Error(`Error retrieving the corresponding test contract for the "${sutContractName}" contract. ${e.message}`);
+    catch (error) {
+        throw new Error(`Error retrieving the corresponding test contract for the "${sutContractName}" contract. ${error.message}`);
     }
 };
 exports.getTestContractSource = getTestContractSource;

package/dist/dialer.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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.PostDialerError = exports.PreDialerError = exports.DialerRegistry = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// In telephony, a registry is used for maintaining a known set of handlers,
+// devices, or processes. This aligns with this class's purpose. Dialers are
+// loaded/stored and run in a structured way, so "registry" fits both telephony
+// and DI semantics.
+class DialerRegistry {
+    constructor(dialPath) {
+        this.preDialers = [];
+        this.postDialers = [];
+        this.dialPath = dialPath;
+    }
+    registerPreDialer(dialer) {
+        this.preDialers.push(dialer);
+    }
+    registerPostDialer(dialer) {
+        this.postDialers.push(dialer);
+    }
+    registerDialers() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resolvedDialPath = (0, path_1.resolve)(this.dialPath);
+            if (!(0, fs_1.existsSync)(resolvedDialPath)) {
+                console.error(`Error: Dialer file not found: ${resolvedDialPath}`);
+                process.exit(1);
+            }
+            try {
+                const userModule = yield Promise.resolve(`${resolvedDialPath}`).then(s => __importStar(require(s)));
+                Object.entries(userModule).forEach(([key, fn]) => {
+                    if (typeof fn === "function") {
+                        if (key.startsWith("pre")) {
+                            this.registerPreDialer(fn);
+                        }
+                        else if (key.startsWith("post")) {
+                            this.registerPostDialer(fn);
+                        }
+                    }
+                });
+            }
+            catch (error) {
+                console.error(`Failed to load dialers:`, error);
+                process.exit(1);
+            }
+        });
+    }
+    executePreDialers(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.preDialers.length === 0) {
+                return;
+            }
+            for (const dial of this.preDialers) {
+                yield dial(context);
+            }
+        });
+    }
+    executePostDialers(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.postDialers.length === 0) {
+                return;
+            }
+            for (const dial of this.postDialers) {
+                yield dial(context);
+            }
+        });
+    }
+}
+exports.DialerRegistry = DialerRegistry;
+class PreDialerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Pre-dialer error";
+    }
+}
+exports.PreDialerError = PreDialerError;
+class PostDialerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Post-dialer error";
+    }
+}
+exports.PostDialerError = PostDialerError;

package/dist/dialer.types.js

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

package/dist/invariant.js

@@ -1,4 +1,13 @@
 "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 };
 };
@@ -10,6 +19,7 @@ const heatstroke_1 = require("./heatstroke");
 const fast_check_1 = __importDefault(require("fast-check"));
 const ansicolor_1 = require("ansicolor");
 const traits_1 = require("./traits");
+const dialer_1 = require("./dialer");
 /**
  * Runs invariant testing on the target contract and logs the progress. Reports
  * the test results through a custom reporter.
@@ -21,10 +31,11 @@ const traits_1 = require("./traits");
  * @param seed The seed for reproducible invariant testing.
  * @param path The path for reproducible invariant testing.
  * @param runs The number of test runs.
+ * @param dialerRegistry The custom dialer registry.
  * @param radio The custom logging event emitter.
  * @returns void
  */
-const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
+const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, dialerRegistry, radio) => __awaiter(void 0, void 0, void 0, function* () {
     // A map where the keys are the Rendezvous identifiers and the values are
     // arrays of their SUT (System Under Test) functions. This map will be used
     // to access the SUT functions for each Rendezvous contract afterwards.
@@ -84,7 +95,7 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
     const radioReporter = (runDetails) => {
         (0, heatstroke_1.reporter)(runDetails, radio, "invariant");
     };
-    fast_check_1.default.assert(fast_check_1.default.property(fast_check_1.default
+    yield fast_check_1.default.assert(fast_check_1.default.asyncProperty(fast_check_1.default
         .record({
         // The target contract identifier. It is a constant value equal
         // to the first contract in the list. The arbitrary is still needed,
@@ -126,10 +137,10 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                 })
             : fast_check_1.default.constant(0),
     })
-        .map((burnBlocks) => (Object.assign(Object.assign({}, r), burnBlocks)))), (r) => {
+        .map((burnBlocks) => (Object.assign(Object.assign({}, r), burnBlocks)))), (r) => __awaiter(void 0, void 0, void 0, function* () {
         const selectedFunctionsArgsCV = r.selectedFunctions.map((selectedFunction, index) => (0, shared_1.argsToCV)(selectedFunction, r.selectedFunctionsArgsList[index]));
         const selectedInvariantArgsCV = (0, shared_1.argsToCV)(r.selectedInvariant, r.invariantArgs);
-        r.selectedFunctions.forEach((selectedFunction, index) => {
+        for (const [index, selectedFunction] of r.selectedFunctions.entries()) {
             const [sutCallerWallet, sutCallerAddress] = r.sutCallers[index];
             const printedFunctionArgs = r.selectedFunctionsArgsList[index]
                 .map((arg) => {
@@ -144,8 +155,20 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
             })
                 .join(" ");
             try {
-                const { result: functionCallResult } = simnet.callPublicFn(r.rendezvousContractId, selectedFunction.name, selectedFunctionsArgsCV[index], sutCallerAddress);
-                const functionCallResultJson = (0, transactions_1.cvToJSON)(functionCallResult);
+                if (dialerRegistry !== undefined) {
+                    yield dialerRegistry.executePreDialers({
+                        selectedFunction: selectedFunction,
+                        functionCall: undefined,
+                        clarityValueArguments: selectedFunctionsArgsCV[index],
+                    });
+                }
+            }
+            catch (error) {
+                throw new dialer_1.PreDialerError(error.message);
+            }
+            try {
+                const functionCall = simnet.callPublicFn(r.rendezvousContractId, selectedFunction.name, selectedFunctionsArgsCV[index], sutCallerAddress);
+                const functionCallResultJson = (0, transactions_1.cvToJSON)(functionCall.result);
                 if (functionCallResultJson.success) {
                     localContext[r.rendezvousContractId][selectedFunction.name]++;
                     simnet.callPublicFn(r.rendezvousContractId, "update-context", [
@@ -158,6 +181,18 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                         `${targetContractName} ` +
                         `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
                         printedFunctionArgs);
+                    try {
+                        if (dialerRegistry !== undefined) {
+                            yield dialerRegistry.executePostDialers({
+                                selectedFunction: selectedFunction,
+                                functionCall: functionCall,
+                                clarityValueArguments: selectedFunctionsArgsCV[index],
+                            });
+                        }
+                    }
+                    catch (error) {
+                        throw new dialer_1.PostDialerError(error.message);
+                    }
                 }
                 else {
                     radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
@@ -169,17 +204,23 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                 }
             }
             catch (error) {
-                // If the function call fails with a runtime error, log a dimmed
-                // message. Since the public function result is ignored, there's
-                // no need to throw an error.
-                radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
-                    `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
-                    `${sutCallerWallet}        ` +
-                    `${targetContractName} ` +
-                    `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
-                    printedFunctionArgs));
+                if (error instanceof dialer_1.PreDialerError ||
+                    error instanceof dialer_1.PostDialerError) {
+                    throw error;
+                }
+                else {
+                    // If the function call fails with a runtime error, log a dimmed
+                    // message. Since the public function result is ignored, there's
+                    // no need to throw an error.
+                    radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
+                        `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
+                        `${sutCallerWallet}        ` +
+                        `${targetContractName} ` +
+                        `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
+                        printedFunctionArgs));
+                }
             }
-        });
+        }
         const printedInvariantArgs = r.invariantArgs
             .map((arg) => {
             try {
@@ -226,14 +267,14 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
         if (r.canMineBlocks) {
             simnet.mineEmptyBurnBlocks(r.burnBlocks);
         }
-    }), {
+    })), {
         verbose: true,
         reporter: radioReporter,
         seed: seed,
         path: path,
         numRuns: runs,
     });
-};
+});
 exports.checkInvariants = checkInvariants;
 /**
  * Initializes the local context, setting the number of times each function

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stacks/rendezvous",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "Meet your contract's vulnerabilities head-on.",
     "main": "app.js",
     "bin": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacks/rendezvous",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Meet your contract's vulnerabilities head-on.",
   "main": "app.js",
   "bin": {