MvA Developer Guide

Who is this guide for?

This guide is for developers implementing methodology rules for the Carrot Network. It covers how to build a Methodology Verification Application (MvA) — the software that evaluates MassID documents against a Methodology Verification Framework (MvF) specification.

Prerequisites

• Proficiency with the monorepo's programming language and tooling
• Understanding of serverless function patterns
• Familiarity with the dMRV concepts and the MvF specification you are implementing
• Knowledge of the Carrot dMRV Standard requirements for MvA developers

Repository and tooling

The methodology rules are implemented in an open-source monorepo:

• Repository: github.com/carrot-foundation/methodology-rules
• License: LGPL-3.0

Refer to the repository README for setup instructions, dependency installation, and local development configuration.

Architecture overview

The codebase follows a two-layer architecture:

• Shared rule libraries — Contain the actual verification logic. Shared rule processors are reused across all BOLD methodologies. Each rule is an independent module with its own tests.
• Methodology application wrappers — Thin deployment layers that wrap shared libraries as serverless functions. Each methodology deploys its own set of rules, including any methodology-specific rules.

This separation means common rules (such as actor identification, weighing, or geolocation) are implemented once and reused, while methodology-specific rules (such as emissions calculations) are isolated to their target methodology.

Implementing a rule

Step 1: Create the project

Each rule lives in its own project directory with a standard file structure. The project metadata includes tags for discoverability and categorization within the monorepo.

Step 2: Implement the processor

Every rule implements the rule processor pattern — a standardized interface with five methods:

1. process() — Entry point that orchestrates the evaluation.
2. generateDocumentQuery() — Builds the query to fetch the MassID document and related data.
3. collectDocuments() — Fetches the documents needed for evaluation.
4. getRuleSubject() — Extracts the specific data elements the rule needs to evaluate.
5. evaluateResult() — Applies the verification logic and returns PASSED or FAILED with an explanation.

The explanation in evaluateResult() is critical — it must state what was verified and why the result is PASSED or FAILED. These explanations form the audit trail.

Step 3: Write tests

Every rule must have comprehensive test coverage:

• Unit tests — Test individual methods and edge cases.
• Integration tests with seed documents — Test the full evaluation flow with realistic MassID documents.
• End-to-end tests — Test the deployed function in an environment that mirrors production.

Step 4: Create the app wrapper

For each methodology that uses the rule, create a thin application wrapper that instantiates the shared library processor and exports it as a serverless function.

Design principles

All rule implementations must follow these principles:

• Fidelity — The code must faithfully implement every rule in the MvF specification. The logic in evaluateResult() must match the specification exactly.
• Traceability — Every PASSED or FAILED result must reference the specific data that was evaluated, enabling independent verification of the outcome.
• Determinism — The same input must always produce the same output. No randomness, no dependence on external state that could change between runs.

Testing requirements

Before a rule can be deployed to production:

• All unit tests must pass
• Integration tests must cover the main PASSED and FAILED scenarios
• End-to-end tests must demonstrate the rule works in a production-like environment
• The rule must match the corresponding MvF specification entry in the traceability matrix

Deployment

Rules are deployed as serverless functions through the monorepo's build and deployment pipeline. Each methodology defines which rules are included in its deployment configuration.

See the repository documentation for deployment procedures and environment configuration.

Learn about MvA · Learn about the MvF Author Guide