> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instruments

> Track renewable energy certificates (RECs) and renewable fuel certificates as inventory, and allocate them to production batches.

Instruments represent environmental attribute certificates, such as renewable energy credits (RECs) or renewable fuel certificates, that a project can claim against its emissions. Mangrove tracks these as inventory in dedicated system ledgers, with balance and consumption tracking to prevent double-counting.

## What are environmental instruments?

In carbon accounting, a **book-and-claim** model allows projects to purchase environmental certificates and apply them to reduce reported emissions, even when the renewable energy or fuel was not physically delivered to the project site.

**Renewable Energy Certificates (RECs)** represent proof that electricity was generated from a renewable source. A project that purchases RECs can claim its grid electricity consumption as renewable, reducing the grid emission factor applied in its LCA calculations.

**Renewable fuel certificates** represent the environmental benefit of using renewable fuel (such as biomethane or renewable diesel) instead of fossil fuel. These certificates track the carbon intensity reduction from the fuel substitution.

Both types must be tracked carefully to prevent **double-counting**. The same certificate cannot be claimed by multiple batches or projects. Mangrove's instrument ledgers enforce this through balance tracking and consumption accounting.

## Instrument types

Mangrove supports two instrument types, each tracked in its own system ledger:

|                     | Renewable Energy Credits (RECs)                                  | Renewable Fuel (RF)                                                        |
| ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Unit**            | kW\.h                                                            | kgCO₂e                                                                     |
| **Use case**        | Offset grid electricity emissions                                | Claim renewable fuel environmental benefit                                 |
| **Required fields** | Amount, External ID, Geography                                   | Amount, External ID                                                        |
| **Optional fields** | Generation tech (wind/solar/other), issuance date, purchase date | Mass of fuel (t), energy intensity (gCO₂e/MJ), lower heating value (MJ/kg) |
| **Validity dates**  | Valid from / valid to                                            | Valid from / valid to                                                      |

## How it works in Mangrove

Each project can have up to two instrument ledgers: one for RECs and one for Renewable Fuel. Each instrument entry represents a purchased certificate with an amount and a unique external identifier.

As instruments are allocated to production batches, the **consumed amount** increases and the **balance** decreases. The ledger prevents over-consumption: you cannot allocate more than the remaining balance.

```mermaid theme={null}
flowchart LR
    CERT["Purchase<br/>Certificate"] --> LEDGER["Add to<br/>Instrument Ledger"]
    LEDGER --> ALLOC["Allocate to<br/>Batches"]
    ALLOC --> BAL["Balance<br/>Decreases"]

    style CERT fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style LEDGER fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style ALLOC fill:#ffa726,stroke:#f57c00,stroke-width:2px,color:#000
    style BAL fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
```

## Add an instrument

<Steps>
  <Step title="Open the instrument ledger">
    Navigate to your project's ledger list and open either the **REC** or **Renewable Fuel BCU** ledger.
  </Step>

  <Step title="Create a new entry">
    Click **Add** to open the creation form.
  </Step>

  <Step title="Enter the external ID">
    Provide the certificate's **External ID**, the unique identifier from the issuing registry. This must be globally unique across all accounts.
  </Step>

  <Step title="Enter the amount">
    Enter the certificate **Amount** in the appropriate unit: kW\.h for RECs, kgCO₂e for Renewable Fuel.
  </Step>

  <Step title="Fill in type-specific fields">
    * **RECs:** Enter the **Geography** (required) and optionally the **Generation Technology** (Wind, Solar, or Other), **Issuance Date**, and **Purchase Date**.
    * **Renewable Fuel:** Optionally enter **Mass of Fuel** (t), **Energy Intensity** (gCO₂e/MJ), and **Lower Heating Value** (MJ/kg).
  </Step>

  <Step title="Set dates and evidence">
    Set **Valid From** and **Valid To** dates if applicable, and attach **evidence** such as certificate documents, purchase receipts, or registry URLs.
  </Step>

  <Step title="Save">
    Click **Add**. Mangrove creates the instrument entry and runs the initial model calculation.
  </Step>
</Steps>

<Note>
  The external ID must be globally unique because it represents a specific certificate. If you get a uniqueness error, verify the certificate hasn't already been registered in another project or account.
</Note>

## Track balance and consumption

Each instrument shows three key metrics in the ledger view:

* **Amount:** The original certificate value as entered
* **Consumed to date:** The total amount that has been allocated to production batches
* **Balance remaining:** What is left for future allocation

These metrics update automatically as batches are generated and instruments are consumed.

<Note>
  An instrument's amount cannot be reduced below its consumed-to-date value. If you need to correct an amount, you may need to regenerate affected batches first. An instrument with any allocations cannot be deleted. Remove the allocations before deleting the instrument.
</Note>

## Connect to your production model

To include instrument deductions in batch calculations, wire the instrument ledger into the production model.

<Steps>
  <Step title="Open the Model Editor">
    Navigate to your project's model and open the **Model Editor**.
  </Step>

  <Step title="Add an instrument input node">
    Add a node that references the instrument ledger's output data point type.
  </Step>

  <Step title="Connect to emissions calculation">
    Connect this node to your emissions calculation:

    * **RECs:** Typically deducted from grid electricity emissions (reducing the effective grid emission factor)
    * **Renewable Fuel:** Typically deducted from fuel-related emissions
  </Step>

  <Step title="Test with a batch">
    **Generate a test batch** to verify the instrument deduction appears correctly in the batch output and the instrument balance decreases.
  </Step>
</Steps>

## Evidence

Each instrument can have supporting evidence attached, including files or URLs that document the certificate's provenance. This creates an audit trail from reported batch values back to the original certificates.

Common evidence includes:

* Registry certificate documents
* Purchase receipts or invoices
* Transfer documentation
* Registry URLs linking to the certificate record

Evidence can be attached when creating the instrument or added later through the detail drawer.