@stacks/rendezvous 0.1.3 → 0.2.0

package/README.md

@@ -28,16 +28,11 @@ root
 
 ### Installation
 
----
-
-**Install the package locally**
-
 ```
-npm install "https://github.com/stacks-network/rendezvous.git"
-npm run build
+npm install @stacks/rendezvous
 ```
 
-Run the fuzzer locally:
+### Usage
 
 ```
 npx rv <path-to-clarinet-project> <contract-name> <type>
@@ -45,22 +40,6 @@ 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:**

package/dist/citizen.js

@@ -87,7 +87,7 @@ const groupContractsByEpochFromSimnetPlan = (simnetPlan) => {
 exports.groupContractsByEpochFromSimnetPlan = groupContractsByEpochFromSimnetPlan;
 /**
  * Deploy the contracts to the simnet in the correct order.
- * @param simnet - The simnet instance.
+ * @param simnet The simnet instance.
  * @param contractsByEpoch - The record of contracts by epoch.
  * @param getContractSourceFn - The function to retrieve the contract source.
  */

package/dist/invariant.js

@@ -9,6 +9,7 @@ const transactions_1 = require("@stacks/transactions");
 const heatstroke_1 = require("./heatstroke");
 const fast_check_1 = __importDefault(require("fast-check"));
 const ansicolor_1 = require("ansicolor");
+const traits_1 = require("./traits");
 const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
     // 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
@@ -18,37 +19,54 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
     // arrays of their invariant functions. This map will be used to access the
     // invariant functions for each Rendezvous contract afterwards.
     const rendezvousInvariantFunctions = filterInvariantFunctions(rendezvousAllFunctions);
+    // The Rendezvous identifier is the first one in the list. Only one contract
+    // can be fuzzed at a time.
+    const rendezvousContractId = rendezvousList[0];
+    const traitReferenceSutFunctions = rendezvousSutFunctions
+        .get(rendezvousContractId)
+        .filter((fn) => (0, traits_1.isTraitReferenceFunction)(fn));
+    const traitReferenceInvariantFunctions = rendezvousInvariantFunctions
+        .get(rendezvousContractId)
+        .filter((fn) => (0, traits_1.isTraitReferenceFunction)(fn));
+    const projectTraitImplementations = (0, traits_1.extractProjectTraitImplementations)(simnet);
+    if (Object.entries(projectTraitImplementations).length === 0 &&
+        (traitReferenceSutFunctions.length > 0 ||
+            traitReferenceInvariantFunctions.length > 0)) {
+        const foundTraitReferenceMessage = traitReferenceSutFunctions.length > 0 &&
+            traitReferenceInvariantFunctions.length > 0
+            ? "public functions and invariants"
+            : traitReferenceSutFunctions.length > 0
+                ? "public functions"
+                : "invariants";
+        radio.emit("logMessage", (0, ansicolor_1.red)(`\nFound ${foundTraitReferenceMessage} referencing traits, but no trait implementations were found in the project.
+\nNote: You can add contracts implementing traits either as project contracts or as Clarinet requirements. For more details, visit: https://www.hiro.so/clarinet/.
+\n`));
+        return;
+    }
+    const enrichedSutFunctionsInterfaces = traitReferenceSutFunctions.length > 0
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousSutFunctions.get(rendezvousContractId)), rendezvousSutFunctions.get(rendezvousContractId), rendezvousContractId)
+        : rendezvousSutFunctions;
+    const enrichedInvariantFunctionsInterfaces = traitReferenceInvariantFunctions.length > 0
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousInvariantFunctions.get(rendezvousContractId)), rendezvousInvariantFunctions.get(rendezvousContractId), rendezvousContractId)
+        : rendezvousInvariantFunctions;
     // Set up local context to track SUT function call counts.
-    const localContext = (0, exports.initializeLocalContext)(rendezvousSutFunctions);
+    const localContext = (0, exports.initializeLocalContext)(enrichedSutFunctionsInterfaces);
     // Set up context in simnet by initializing state for SUT.
-    (0, exports.initializeClarityContext)(simnet, rendezvousSutFunctions);
+    (0, exports.initializeClarityContext)(simnet, enrichedSutFunctionsInterfaces);
     radio.emit("logMessage", `\nStarting invariant testing type for the ${sutContractName} contract...\n`);
     const simnetAccounts = simnet.getAccounts();
     const eligibleAccounts = new Map([...simnetAccounts].filter(([key]) => key !== "faucet"));
     const simnetAddresses = Array.from(simnetAccounts.values());
-    // The Rendezvous identifier is the first one in the list. Only one contract
-    // can be fuzzed at a time.
-    const rendezvousContractId = rendezvousList[0];
-    const functions = (0, shared_1.getFunctionsListForContract)(rendezvousSutFunctions, rendezvousContractId);
-    const invariantFunctions = (0, shared_1.getFunctionsListForContract)(rendezvousInvariantFunctions, rendezvousContractId);
+    const functions = (0, shared_1.getFunctionsListForContract)(enrichedSutFunctionsInterfaces, rendezvousContractId);
+    const invariants = (0, shared_1.getFunctionsListForContract)(enrichedInvariantFunctionsInterfaces, rendezvousContractId);
     if ((functions === null || functions === void 0 ? void 0 : functions.length) === 0) {
         radio.emit("logMessage", (0, ansicolor_1.red)(`No public functions found for the "${sutContractName}" contract. Without public functions, no state transitions can happen inside the contract, and the invariant test is not meaningful.\n`));
         return;
     }
-    if ((invariantFunctions === null || invariantFunctions === void 0 ? void 0 : invariantFunctions.length) === 0) {
+    if ((invariants === null || invariants === void 0 ? void 0 : invariants.length) === 0) {
         radio.emit("logMessage", (0, ansicolor_1.red)(`No invariant functions found for the "${sutContractName}" contract. Beware, for your contract may be exposed to unforeseen issues.\n`));
         return;
     }
-    const eligibleFunctions = functions.filter((fn) => !(0, shared_1.isTraitReferenceFunction)(fn));
-    const eligibleInvariants = invariantFunctions.filter((fn) => !(0, shared_1.isTraitReferenceFunction)(fn));
-    if (eligibleFunctions.length === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No eligible public functions found for the "${sutContractName}" contract. Note: trait references are not supported.\n`));
-        return;
-    }
-    if (eligibleInvariants.length === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No eligible invariant functions found for the "${sutContractName}" contract. Note: trait references are not supported.\n`));
-        return;
-    }
     const radioReporter = (runDetails) => {
         (0, heatstroke_1.reporter)(runDetails, radio, "invariant");
     };
@@ -64,14 +82,14 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
     })
         .chain((r) => fast_check_1.default
         .record({
-        selectedFunction: fast_check_1.default.constantFrom(...eligibleFunctions),
-        selectedInvariant: fast_check_1.default.constantFrom(...eligibleInvariants),
+        selectedFunction: fast_check_1.default.constantFrom(...functions),
+        selectedInvariant: fast_check_1.default.constantFrom(...invariants),
     })
         .map((selectedFunctions) => (Object.assign(Object.assign({}, r), selectedFunctions))))
         .chain((r) => fast_check_1.default
         .record({
-        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedFunction, simnetAddresses)),
-        invariantArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedInvariant, simnetAddresses)),
+        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedFunction, simnetAddresses, projectTraitImplementations)),
+        invariantArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedInvariant, simnetAddresses, projectTraitImplementations)),
     })
         .map((args) => (Object.assign(Object.assign({}, r), args))))
         .chain((r) => fast_check_1.default

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stacks/rendezvous",
-    "version": "0.1.3",
+    "version": "0.2.0",
     "description": "Meet your contract's vulnerabilities head-on.",
     "main": "app.js",
     "bin": {
@@ -8,7 +8,7 @@
     },
     "scripts": {
         "build": "npx -p typescript tsc --project tsconfig.json && node -e \"if (process.platform !== 'win32') require('fs').chmodSync('./dist/app.js', 0o755);\"",
-        "test": "npx tsc --project tsconfig.json && npx jest",
+        "test": "npx jest",
         "test:coverage": "npx tsc --project tsconfig.json && npx jest --coverage"
     },
     "keywords": [

package/dist/property.js

@@ -9,11 +9,27 @@ const transactions_1 = require("@stacks/transactions");
 const heatstroke_1 = require("./heatstroke");
 const shared_1 = require("./shared");
 const ansicolor_1 = require("ansicolor");
+const traits_1 = require("./traits");
 const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
+    const testContractId = rendezvousList[0];
     // A map where the keys are the test contract identifiers and the values are
     // arrays of their test functions. This map will be used to access the test
     // functions for each test contract in the property-based testing routine.
     const testContractsTestFunctions = filterTestFunctions(rendezvousAllFunctions);
+    const traitReferenceFunctions = testContractsTestFunctions
+        .get(testContractId)
+        .filter((fn) => (0, traits_1.isTraitReferenceFunction)(fn));
+    const projectTraitImplementations = (0, traits_1.extractProjectTraitImplementations)(simnet);
+    if (Object.entries(projectTraitImplementations).length === 0 &&
+        traitReferenceFunctions.length > 0) {
+        radio.emit("logMessage", (0, ansicolor_1.red)(`\nFound test functions referencing traits, but no trait implementations were found in the project.
+\nNote: You can add contracts implementing traits either as project contracts or as Clarinet requirements. For more details, visit: https://www.hiro.so/clarinet/.
+\n`));
+        return;
+    }
+    const enrichedTestFunctionsInterfaces = traitReferenceFunctions.length > 0
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(testContractsTestFunctions.get(testContractId)), testContractsTestFunctions.get(testContractId), testContractId)
+        : testContractsTestFunctions;
     radio.emit("logMessage", `\nStarting property testing type for the ${sutContractName} contract...\n`);
     // Search for discard functions, for each test function. This map will
     // be used to pair the test functions with their corresponding discard
@@ -43,17 +59,11 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
     const simnetAccounts = simnet.getAccounts();
     const eligibleAccounts = new Map([...simnetAccounts].filter(([key]) => key !== "faucet"));
     const simnetAddresses = Array.from(simnetAccounts.values());
-    const testContractId = rendezvousList[0];
-    const testFunctions = (0, shared_1.getFunctionsListForContract)(testContractsTestFunctions, testContractId);
+    const testFunctions = (0, shared_1.getFunctionsListForContract)(enrichedTestFunctionsInterfaces, testContractId);
     if ((testFunctions === null || testFunctions === void 0 ? void 0 : testFunctions.length) === 0) {
         radio.emit("logMessage", (0, ansicolor_1.red)(`No test functions found for the "${sutContractName}" contract.\n`));
         return;
     }
-    const eligibleTestFunctions = testFunctions.filter((fn) => !(0, shared_1.isTraitReferenceFunction)(fn));
-    if (eligibleTestFunctions.length === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No eligible test functions found for the "${sutContractName}" contract. Note: trait references are not supported.\n`));
-        return;
-    }
     const radioReporter = (runDetails) => {
         (0, heatstroke_1.reporter)(runDetails, radio, "test");
     };
@@ -65,12 +75,12 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
     })
         .chain((r) => fast_check_1.default
         .record({
-        selectedTestFunction: fast_check_1.default.constantFrom(...eligibleTestFunctions),
+        selectedTestFunction: fast_check_1.default.constantFrom(...testFunctions),
     })
         .map((selectedTestFunction) => (Object.assign(Object.assign({}, r), selectedTestFunction))))
         .chain((r) => fast_check_1.default
         .record({
-        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedTestFunction, simnetAddresses)),
+        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedTestFunction, simnetAddresses, projectTraitImplementations)),
     })
         .map((args) => (Object.assign(Object.assign({}, r), args))))
         .chain((r) => fast_check_1.default

package/dist/shared.js

@@ -3,9 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getContractNameFromContractId = exports.isTraitReferenceFunction = exports.argsToCV = exports.hexaString = exports.functionToArbitrary = exports.getFunctionsListForContract = exports.getFunctionsFromContractInterfaces = exports.getSimnetDeployerContractsInterfaces = void 0;
+exports.getContractNameFromContractId = exports.argsToCV = exports.hexaString = exports.functionToArbitrary = exports.getFunctionsListForContract = exports.getFunctionsFromContractInterfaces = exports.getSimnetDeployerContractsInterfaces = void 0;
 const fast_check_1 = __importDefault(require("fast-check"));
 const transactions_1 = require("@stacks/transactions");
+const traits_1 = require("./traits");
 /**
  * Get the interfaces of contracts deployed by the specified deployer from the
  * simnet.
@@ -31,14 +32,14 @@ exports.getFunctionsListForContract = getFunctionsListForContract;
  * @param fn The function interface.
  * @returns Array of fast-check arbitraries.
  */
-const functionToArbitrary = (fn, addresses) => fn.args.map((arg) => parameterTypeToArbitrary(arg.type, addresses));
+const functionToArbitrary = (fn, addresses, projectTraitImplementations) => fn.args.map((arg) => parameterTypeToArbitrary(arg.type, addresses, projectTraitImplementations));
 exports.functionToArbitrary = functionToArbitrary;
 /**
  * For a given type, generate a fast-check arbitrary.
  * @param type The parameter type.
  * @returns Fast-check arbitrary.
  */
-const parameterTypeToArbitrary = (type, addresses) => {
+const parameterTypeToArbitrary = (type, addresses, projectTraitImplementations) => {
     if (typeof type === "string") {
         // The type is a base type.
         if (type === "principal") {
@@ -46,9 +47,6 @@ const parameterTypeToArbitrary = (type, addresses) => {
                 throw new Error("No addresses could be retrieved from the simnet instance!");
             return baseTypesToArbitrary.principal(addresses);
         }
-        else if (type === "trait_reference") {
-            throw new Error("Unsupported parameter type: trait_reference");
-        }
         else
             return baseTypesToArbitrary[type];
     }
@@ -64,16 +62,19 @@ const parameterTypeToArbitrary = (type, addresses) => {
             return complexTypesToArbitrary["string-utf8"](type["string-utf8"].length);
         }
         else if ("list" in type) {
-            return complexTypesToArbitrary["list"](type.list.type, type.list.length, addresses);
+            return complexTypesToArbitrary["list"](type.list.type, type.list.length, addresses, projectTraitImplementations);
         }
         else if ("tuple" in type) {
-            return complexTypesToArbitrary["tuple"](type.tuple, addresses);
+            return complexTypesToArbitrary["tuple"](type.tuple, addresses, projectTraitImplementations);
         }
         else if ("optional" in type) {
-            return complexTypesToArbitrary["optional"](type.optional, addresses);
+            return complexTypesToArbitrary["optional"](type.optional, addresses, projectTraitImplementations);
         }
         else if ("response" in type) {
-            return complexTypesToArbitrary.response(type.response.ok, type.response.error, addresses);
+            return complexTypesToArbitrary.response(type.response.ok, type.response.error, addresses, projectTraitImplementations);
+        }
+        else if ("trait_reference" in type) {
+            return complexTypesToArbitrary.trait_reference(type.trait_reference, projectTraitImplementations);
         }
         else {
             throw new Error(`Unsupported complex type: ${JSON.stringify(type)}`);
@@ -88,28 +89,7 @@ const baseTypesToArbitrary = {
     uint128: fast_check_1.default.nat(),
     bool: fast_check_1.default.boolean(),
     principal: (addresses) => fast_check_1.default.constantFrom(...addresses),
-    trait_reference: undefined,
 };
-/**
- * Custom hexadecimal string generator. The `hexaString` generator from
- * fast-check has been deprecated. This generator is implemented to precisely
- * match the behavior of the deprecated generator.
- *
- * @param constraints Fast-check string constraints.
- * @returns Fast-check arbitrary for hexadecimal strings.
- *
- * Reference for the proposed replacement of the deprecated `hexaString`
- * generator:
- * https://github.com/dubzzz/fast-check/commit/3f4f1203a8863c07d22b45591bf0de1fac02b948
- */
-const hexaString = (constraints = {}) => {
-    const hexa = () => {
-        const hexCharSet = "0123456789abcdef";
-        return fast_check_1.default.integer({ min: 0, max: 15 }).map((n) => hexCharSet[n]);
-    };
-    return fast_check_1.default.string(Object.assign(Object.assign({}, constraints), { unit: hexa() }));
-};
-exports.hexaString = hexaString;
 /**
  * Complex types to fast-check arbitraries mapping.
  */
@@ -125,23 +105,48 @@ const complexTypesToArbitrary = {
         maxLength: length,
     }),
     "string-utf8": (length) => fast_check_1.default.string({ maxLength: length }),
-    list: (type, length, addresses) => fast_check_1.default.array(parameterTypeToArbitrary(type, addresses), { maxLength: length }),
-    tuple: (items, addresses) => {
+    list: (type, length, addresses, projectTraitImplementations) => fast_check_1.default.array(parameterTypeToArbitrary(type, addresses, projectTraitImplementations), {
+        maxLength: length,
+    }),
+    tuple: (items, addresses, projectTraitImplementations) => {
         const tupleArbitraries = {};
         items.forEach((item) => {
-            tupleArbitraries[item.name] = parameterTypeToArbitrary(item.type, addresses);
+            tupleArbitraries[item.name] = parameterTypeToArbitrary(item.type, addresses, projectTraitImplementations);
         });
         return fast_check_1.default.record(tupleArbitraries);
     },
-    optional: (type, addresses) => fast_check_1.default.option(parameterTypeToArbitrary(type, addresses)),
-    response: (okType, errType, addresses) => fast_check_1.default.oneof(fast_check_1.default.record({
+    optional: (type, addresses, projectTraitImplementations) => fast_check_1.default.option(parameterTypeToArbitrary(type, addresses, projectTraitImplementations)),
+    response: (okType, errType, addresses, projectTraitImplementations) => fast_check_1.default.oneof(fast_check_1.default.record({
         status: fast_check_1.default.constant("ok"),
-        value: parameterTypeToArbitrary(okType, addresses),
+        value: parameterTypeToArbitrary(okType, addresses, projectTraitImplementations),
     }), fast_check_1.default.record({
         status: fast_check_1.default.constant("error"),
-        value: parameterTypeToArbitrary(errType, addresses),
+        value: parameterTypeToArbitrary(errType, addresses, projectTraitImplementations),
     })),
+    trait_reference: (traitData, projectTraitImplementations) => {
+        return fast_check_1.default.constantFrom(...(0, traits_1.getContractIdsImplementingTrait)(traitData, projectTraitImplementations));
+    },
+};
+/**
+ * Custom hexadecimal string generator. The `hexaString` generator from
+ * fast-check has been deprecated. This generator is implemented to precisely
+ * match the behavior of the deprecated generator.
+ *
+ * @param constraints Fast-check string constraints.
+ * @returns Fast-check arbitrary for hexadecimal strings.
+ *
+ * Reference for the proposed replacement of the deprecated `hexaString`
+ * generator:
+ * https://github.com/dubzzz/fast-check/commit/3f4f1203a8863c07d22b45591bf0de1fac02b948
+ */
+const hexaString = (constraints = {}) => {
+    const hexa = () => {
+        const hexCharSet = "0123456789abcdef";
+        return fast_check_1.default.integer({ min: 0, max: 15 }).map((n) => hexCharSet[n]);
+    };
+    return fast_check_1.default.string(Object.assign(Object.assign({}, constraints), { unit: hexa() }));
 };
+exports.hexaString = hexaString;
 /** The character set used for generating ASCII strings.*/
 const charSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~";
 /**
@@ -205,6 +210,9 @@ const argToCV = (arg, type) => {
             const responseValue = argToCV(arg.value, branchType);
             return complexTypesToCV.response(status, responseValue);
         }
+        else if ("trait_reference" in type) {
+            return complexTypesToCV.trait_reference(arg);
+        }
         else {
             throw new Error(`Unsupported complex parameter type: ${JSON.stringify(type)}`);
         }
@@ -241,45 +249,10 @@ const complexTypesToCV = {
         else
             throw new Error(`Unsupported response status: ${status}`);
     },
+    trait_reference: (traitImplementation) => (0, transactions_1.principalCV)(traitImplementation),
 };
 const isBaseType = (type) => {
     return ["int128", "uint128", "bool", "principal"].includes(type);
 };
-/**
- * Checks if any parameter of the function contains a `trait_reference` type.
- * @param fn The function interface.
- * @returns Boolean - true if the function contains a trait reference, false
- * otherwise.
- */
-const isTraitReferenceFunction = (fn) => {
-    const hasTraitReference = (type) => {
-        if (typeof type === "string") {
-            // The type is a base type.
-            return type === "trait_reference";
-        }
-        else {
-            // The type is a complex type.
-            if ("buffer" in type)
-                return false;
-            if ("string-ascii" in type)
-                return false;
-            if ("string-utf8" in type)
-                return false;
-            if ("list" in type)
-                return hasTraitReference(type.list.type);
-            if ("tuple" in type)
-                return type.tuple.some((item) => hasTraitReference(item.type));
-            if ("optional" in type)
-                return hasTraitReference(type.optional);
-            if ("response" in type)
-                return (hasTraitReference(type.response.ok) ||
-                    hasTraitReference(type.response.error));
-            // Default to false for unexpected types.
-            return false;
-        }
-    };
-    return fn.args.some((arg) => hasTraitReference(arg.type));
-};
-exports.isTraitReferenceFunction = isTraitReferenceFunction;
 const getContractNameFromContractId = (contractId) => contractId.split(".")[1];
 exports.getContractNameFromContractId = getContractNameFromContractId;

package/dist/traits.js

@@ -0,0 +1,388 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractProjectTraitImplementations = exports.isTraitReferenceFunction = exports.getContractIdsImplementingTrait = exports.buildTraitReferenceMap = exports.getTraitReferenceData = exports.enrichInterfaceWithTraitData = void 0;
+/**
+ * Enriches contract interface with trait reference data. Before enrichment,
+ * the contract interface lacks trait reference data for parameters. This
+ * function constructs a copy of the contract interface with trait reference
+ * data for parameters that are trait references.
+ * @param ast The contract AST.
+ * @param traitReferenceMap The map of function names to trait reference paths.
+ * @param functionInterfaceList The list of function interfaces for a contract.
+ * @param targetContractId The contract ID to enrich with trait reference data.
+ * @returns A map of contract IDs to a list of enriched contract interface
+ * functions.
+ */
+const enrichInterfaceWithTraitData = (ast, traitReferenceMap, functionInterfaceList, targetContractId) => {
+    const enriched = new Map();
+    const enrichArgs = (args, functionName, traitReferenceMap, path = []) => {
+        return args.map((arg) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            const listNested = !arg.name;
+            const currentPath = listNested ? path : [...path, arg.name];
+            if (arg.type && arg.type.tuple) {
+                return Object.assign(Object.assign({}, arg), { type: {
+                        tuple: enrichArgs(arg.type.tuple, functionName, listNested
+                            ? traitReferenceMap.tuple
+                            : (_a = traitReferenceMap[arg.name]) === null || _a === void 0 ? void 0 : _a.tuple, currentPath),
+                    } });
+            }
+            else if (arg.type && arg.type.list) {
+                return Object.assign(Object.assign({}, arg), { type: {
+                        list: enrichArgs([arg.type.list], functionName, listNested
+                            ? traitReferenceMap.list
+                            : (_b = traitReferenceMap[arg.name]) === null || _b === void 0 ? void 0 : _b.list, arg.type.list.type.tuple
+                            ? [...currentPath, "tuple"]
+                            : arg.type.list.type.response
+                                ? [...currentPath, "response"]
+                                : arg.type.list.type.optional
+                                    ? [...currentPath, "optional"]
+                                    : [...currentPath, "list"])[0],
+                    } });
+            }
+            else if (arg.type && arg.type.response) {
+                const okPath = listNested ? currentPath : [...currentPath, "ok"];
+                const errorPath = listNested ? currentPath : [...currentPath, "error"];
+                const okTraitReference = enrichArgs([{ name: "ok", type: arg.type.response.ok }], functionName, {
+                    ok: listNested
+                        ? (_c = traitReferenceMap.response) === null || _c === void 0 ? void 0 : _c.ok
+                        : (_e = (_d = traitReferenceMap[arg.name]) === null || _d === void 0 ? void 0 : _d.response) === null || _e === void 0 ? void 0 : _e.ok,
+                }, okPath)[0];
+                const errorTraitReference = enrichArgs([{ name: "error", type: arg.type.response.error }], functionName, {
+                    error: listNested
+                        ? (_f = traitReferenceMap.response) === null || _f === void 0 ? void 0 : _f.error
+                        : (_h = (_g = traitReferenceMap[arg.name]) === null || _g === void 0 ? void 0 : _g.response) === null || _h === void 0 ? void 0 : _h.error,
+                }, errorPath)[0];
+                return Object.assign(Object.assign({}, arg), { type: {
+                        response: {
+                            ok: okTraitReference.type,
+                            error: errorTraitReference.type,
+                        },
+                    } });
+            }
+            else if (arg.type && arg.type.optional) {
+                const optionalPath = [...currentPath, "optional"];
+                const optionalTraitReference = enrichArgs([{ name: "optional", type: arg.type.optional }], functionName, {
+                    optional: listNested
+                        ? traitReferenceMap.optional
+                        : (_j = traitReferenceMap[arg.name]) === null || _j === void 0 ? void 0 : _j.optional,
+                }, optionalPath)[0];
+                return Object.assign(Object.assign({}, arg), { type: {
+                        optional: optionalTraitReference.type,
+                    } });
+            }
+            else if (traitReferenceMap && traitReferenceMap[arg.name]) {
+                const [traitReferenceName, traitReferenceImport] = (0, exports.getTraitReferenceData)(ast, functionName, currentPath.filter((x) => x !== undefined));
+                if (traitReferenceName && traitReferenceImport) {
+                    return Object.assign(Object.assign({}, arg), { type: {
+                            trait_reference: {
+                                name: traitReferenceName,
+                                import: traitReferenceImport,
+                            },
+                        } });
+                }
+            }
+            else if (traitReferenceMap === "trait_reference") {
+                const [traitReferenceName, traitReferenceImport] = (0, exports.getTraitReferenceData)(ast, functionName, path);
+                if (traitReferenceName && traitReferenceImport) {
+                    return Object.assign(Object.assign({}, arg), { type: {
+                            trait_reference: {
+                                name: traitReferenceName,
+                                import: traitReferenceImport,
+                            },
+                        } });
+                }
+            }
+            return arg;
+        });
+    };
+    const enrichedFunctions = functionInterfaceList.map((f) => {
+        return Object.assign(Object.assign({}, f), { args: enrichArgs(f.args, f.name, traitReferenceMap.get(f.name)) });
+    });
+    enriched.set(targetContractId, enrichedFunctions);
+    return enriched;
+};
+exports.enrichInterfaceWithTraitData = enrichInterfaceWithTraitData;
+/**
+ * Searches for a trait reference in the contract AST, given the function name
+ * and the nesting path of the trait reference.
+ * @param ast The contract AST.
+ * @param functionName The name of the function to search for trait references
+ * import data.
+ * @param parameterPath The path to search for the trait reference. The path is
+ * an array of strings that represent the nested location of the trait
+ * reference in the contract AST.
+ * @returns A tuple containing the `trait reference name` and the `imported
+ * trait data` if the trait reference is found. Otherwise, returns a tuple of
+ * `undefined` values.
+ */
+const getTraitReferenceData = (ast, functionName, parameterPath) => {
+    /**
+     * Recursively searches for a trait reference import details in the contract
+     * parameter nodes, part of the contract AST.
+     * @param functionParameterNodes The list of function parameter nodes from
+     * the AST. This is the list of nodes following the function name node.
+     * @param path The path to search for the trait reference. The path is an
+     * array of strings that represent the nested location of the trait reference
+     * in the function parameter nodes.
+     * @returns A tuple containing the `trait reference name` and the `imported
+     * trait data` if the trait reference is found. Otherwise, returns a tuple of
+     * `undefined` values.
+     */
+    const findTraitReference = (functionParameterNodes, path) => {
+        for (const parameterNode of functionParameterNodes) {
+            // Check if the current parameter node is a trait reference in the first
+            // level of the function parameter nodes.
+            if (parameterNode.expr &&
+                parameterNode.expr.TraitReference) {
+                const [name, importData] = parameterNode.expr
+                    .TraitReference;
+                return [name, importData];
+            }
+            if (!parameterNode.expr || !parameterNode.expr.List) {
+                continue;
+            }
+            // The parameter name node is the first node in the parameter node list.
+            const parameterNameNode = parameterNode.expr.List[0];
+            if (!parameterNameNode || !parameterNameNode.expr.Atom) {
+                continue;
+            }
+            const currentParameterName = parameterNameNode.expr.Atom.toString();
+            // Check the first item in the path list to see if it matches the current
+            // parameter name. If it does, we are on the right track.
+            if (currentParameterName === path[0]) {
+                // If the path only has one item left, the trait reference should be
+                // right under our noses, in the next node.
+                if (path.length === 1) {
+                    const traitReferenceNode = parameterNode.expr.List[1];
+                    if (traitReferenceNode &&
+                        traitReferenceNode.expr.TraitReference) {
+                        const [name, importData] = traitReferenceNode.expr.TraitReference;
+                        return [name, importData];
+                    }
+                }
+                else {
+                    // If the path has more than one item left, we need to traverse down
+                    // the expression list to find the nested trait reference.
+                    if (parameterNode.expr.List[1] &&
+                        parameterNode.expr.List[1].expr) {
+                        const nestedParameterList = parameterNode.expr.List[1]
+                            .expr;
+                        if (nestedParameterList.TraitReference) {
+                            const [name, importData] = nestedParameterList
+                                .TraitReference;
+                            return [name, importData];
+                        }
+                        else {
+                            // Recursively search for the trait reference in the nested
+                            // parameter list.
+                            const result = findTraitReference(nestedParameterList.List, path.slice(1));
+                            if (result[0] !== undefined)
+                                return result;
+                        }
+                    }
+                }
+            }
+        }
+        return [undefined, undefined];
+    };
+    for (const node of ast.expressions) {
+        if (!node.expr || !node.expr.List) {
+            continue;
+        }
+        // Traverse down the expression.
+        const expressionList = node.expr.List;
+        // Extract the first atom in the expression list to determine if it is a
+        // function definition.
+        const potentialFunctionDefinitionAtom = expressionList[0];
+        // Check if the potential function definition atom is an actual function
+        // definition.
+        if (!potentialFunctionDefinitionAtom ||
+            !["define-public", "define-read-only"].includes(potentialFunctionDefinitionAtom.expr.Atom.toString())) {
+            continue;
+        }
+        // The current expression is a function definition. Extract the function
+        // name node, which is the second node in the expression list.
+        const functionNameNode = expressionList[1];
+        // Check if the function name node exists and if it is a list.
+        if (!functionNameNode || !functionNameNode.expr.List) {
+            continue;
+        }
+        // Extract the function definition list.
+        const functionDefinitionList = functionNameNode.expr.List;
+        const functionNameAtom = functionDefinitionList[0];
+        // Check if the function name atom exists.
+        if (!functionNameAtom || !functionNameAtom.expr.Atom) {
+            continue;
+        }
+        const currentFunctionName = functionNameAtom.expr.Atom.toString();
+        // Check if the current function name matches the function name we are
+        // looking for.
+        if (currentFunctionName !== functionName) {
+            continue;
+        }
+        // Bingo! Found the function definition. The function parameters are the
+        // nodes following the function name node.
+        const functionParameterNodes = functionDefinitionList.slice(1);
+        const traitReferenceImportData = findTraitReference(functionParameterNodes, parameterPath);
+        if (traitReferenceImportData[0] !== undefined)
+            return traitReferenceImportData;
+    }
+    return [undefined, undefined];
+};
+exports.getTraitReferenceData = getTraitReferenceData;
+/**
+ * Builds a map of function names to trait reference paths. The trait reference
+ * path is the path to the trait reference in the function parameter list.
+ * @param functionInterfaces The list of function interfaces for a contract.
+ * @returns A map of function names to trait reference paths.
+ */
+const buildTraitReferenceMap = (functionInterfaces) => {
+    const traitReferenceMap = new Map();
+    const findTraitReferences = (args) => {
+        const traitReferences = {};
+        args.forEach((arg) => {
+            if (arg.type && arg.type.tuple) {
+                const nestedTraitReferences = findTraitReferences(arg.type.tuple);
+                if (Object.keys(nestedTraitReferences).length > 0) {
+                    traitReferences[arg.name] = { tuple: nestedTraitReferences };
+                }
+            }
+            else if (arg.type && arg.type.list) {
+                const nestedTraitReferences = findTraitReferences([arg.type.list]);
+                if (Object.keys(nestedTraitReferences).length > 0) {
+                    traitReferences[arg.name] = {
+                        list: nestedTraitReferences["undefined"],
+                    };
+                }
+            }
+            else if (arg.type && arg.type.response) {
+                const okTraitReferences = findTraitReferences([arg.type.response.ok]);
+                const errorTraitReferences = findTraitReferences([
+                    arg.type.response.error,
+                ]);
+                const responseTraitReferences = {};
+                if (Object.keys(okTraitReferences).length > 0) {
+                    responseTraitReferences.ok =
+                        okTraitReferences[arg.name] || "trait_reference";
+                }
+                if (Object.keys(errorTraitReferences).length > 0) {
+                    responseTraitReferences.error =
+                        errorTraitReferences[arg.name] || "trait_reference";
+                }
+                if (Object.keys(responseTraitReferences).length > 0) {
+                    traitReferences[arg.name] = { response: responseTraitReferences };
+                }
+            }
+            else if (arg.type && arg.type.optional) {
+                const nestedTraitReferences = findTraitReferences([arg.type.optional]);
+                if (Object.keys(nestedTraitReferences).length > 0) {
+                    traitReferences[arg.name] = {
+                        optional: nestedTraitReferences[arg.name] || "trait_reference",
+                    };
+                }
+            }
+            else if (arg.type === "trait_reference") {
+                traitReferences[arg.name] = "trait_reference";
+            }
+            else if (arg === "trait_reference") {
+                traitReferences[arg.name] = "trait_reference";
+            }
+        });
+        return traitReferences;
+    };
+    functionInterfaces.forEach((fn) => {
+        const traitReferences = findTraitReferences(fn.args);
+        if (Object.keys(traitReferences).length > 0) {
+            traitReferenceMap.set(fn.name, traitReferences);
+        }
+    });
+    return traitReferenceMap;
+};
+exports.buildTraitReferenceMap = buildTraitReferenceMap;
+/**
+ * Retrieves the contract IDs that implement a given trait.
+ * @param trait The trait to search for.
+ * @param projectTraitImplementations The record of the project contract IDs to
+ * their implemented traits.
+ * @returns An array of contract IDs that implement the trait.
+ */
+const getContractIdsImplementingTrait = (trait, projectTraitImplementations) => {
+    const contracts = Object.keys(projectTraitImplementations);
+    const filteredContracts = contracts.filter((contractId) => {
+        var _a;
+        const traitImplemented = (_a = projectTraitImplementations[contractId]) === null || _a === void 0 ? void 0 : _a.some((implementedTrait) => {
+            var _a, _b;
+            const isTraitNamesMatch = implementedTrait.name === ((_a = trait.import.Imported) === null || _a === void 0 ? void 0 : _a.name);
+            const isTraitIssuersMatch = JSON.stringify(implementedTrait.contract_identifier.issuer) ===
+                JSON.stringify((_b = trait.import.Imported) === null || _b === void 0 ? void 0 : _b.contract_identifier.issuer);
+            return isTraitNamesMatch && isTraitIssuersMatch;
+        });
+        return traitImplemented;
+    });
+    return filteredContracts;
+};
+exports.getContractIdsImplementingTrait = getContractIdsImplementingTrait;
+/**
+ * Checks if any parameter of the function contains a `trait_reference` type.
+ * @param fn The function interface.
+ * @returns Boolean - true if the function contains a trait reference, false
+ * otherwise.
+ */
+const isTraitReferenceFunction = (fn) => {
+    const hasTraitReference = (type) => {
+        if (typeof type === "string") {
+            // The type is a base type.
+            return type === "trait_reference";
+        }
+        else {
+            // The type is a complex type.
+            if ("buffer" in type)
+                return false;
+            if ("string-ascii" in type)
+                return false;
+            if ("string-utf8" in type)
+                return false;
+            if ("list" in type)
+                return hasTraitReference(type.list.type);
+            if ("tuple" in type)
+                return type.tuple.some((item) => hasTraitReference(item.type));
+            if ("optional" in type)
+                return hasTraitReference(type.optional);
+            if ("response" in type)
+                return (hasTraitReference(type.response.ok) ||
+                    hasTraitReference(type.response.error));
+            // Default to false for unexpected types.
+            return false;
+        }
+    };
+    return fn.args.some((arg) => hasTraitReference(arg.type));
+};
+exports.isTraitReferenceFunction = isTraitReferenceFunction;
+/**
+ * Iterates over all project contracts's ASTs excluding the boot ones and
+ * extracts a record of contract IDs to their implemented traits.
+ * @param simnet The Simnet instance.
+ * @returns A record of contract IDs to their implemented traits.
+ */
+const extractProjectTraitImplementations = (simnet) => {
+    const allProjectContracts = [
+        ...simnet.getContractsInterfaces().keys(),
+    ].filter((contractId) => {
+        const contractDeployer = contractId.split(".")[0];
+        return ![
+            "SP000000000000000000002Q6VF78",
+            "ST000000000000000000002AMW42H",
+        ].includes(contractDeployer);
+    });
+    const projectTraitImplementations = allProjectContracts.reduce((acc, contractId) => {
+        const ast = simnet.getContractAST(contractId);
+        const implementedTraits = ast.implemented_traits;
+        if (implementedTraits.length > 0) {
+            acc[contractId] = implementedTraits;
+        }
+        return acc;
+    }, {});
+    return projectTraitImplementations;
+};
+exports.extractProjectTraitImplementations = extractProjectTraitImplementations;

package/dist/traits.types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacks/rendezvous",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Meet your contract's vulnerabilities head-on.",
   "main": "app.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "npx -p typescript tsc --project tsconfig.json && node -e \"if (process.platform !== 'win32') require('fs').chmodSync('./dist/app.js', 0o755);\"",
-    "test": "npx tsc --project tsconfig.json && npx jest",
+    "test": "npx jest",
     "test:coverage": "npx tsc --project tsconfig.json && npx jest --coverage"
   },
   "keywords": [