# treejer/contract architecture

> Architecture diagram of the GitHub repository treejer/contract, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/treejer/contract
- Repository: https://github.com/treejer/contract

## Overview

1. **What this repo is**
   - This is a **Solidity smart-contract system** for the **Treejer Protocol** on **Polygon**.
   - It is not an application backend; the core architecture is **on-chain contracts** plus **deployment/test tooling** around them.

2. **Core protocol boundary**
   - The main production contracts live under `contracts/` and are organized by domain:
     - `tree`, `treeAttribute`, `treeBox`, `treeFactory`
     - `planter`, `planterFund`
     - `regularSale`, `incrementalSale`, `auction`, `communityGifts`
     - `allocation`, `treasury`, `daiFund`, `wethFund`
     - `accessRestriction`, `honoraryTree`
   - These form the protocol’s business logic for **minting trees, managing metadata, handling planters, selling trees, and distributing funds**.

3. **Tree lifecycle subsystem**
   - `tree` is the central asset contract for minting/owning trees.
   - `treeAttribute` manages tree properties/metadata separate from ownership.
   - `treeFactory` is the creation/orchestration layer for tree-related contracts or instances.
   - `treeBox` appears as an additional tree-related product/claim container, with its own deployment and tests.

4. **Identity and permissions**
   - `accessRestriction` is the protocol’s authorization boundary.
   - It likely governs which addresses can mint, sell, allocate, or administer protocol actions.
   - `honoraryTree` is a specialized tree path, probably representing non-standard issuance or privileged minting.

5. **Sales and distribution flow**
   - `auction`, `regularSale`, and `incrementalSale` are the main market-facing sale mechanisms.
   - `communityGifts` covers non-sale distribution.
   - The sale contracts are separated by sale mode rather than being one monolith, which suggests different pricing/issuance rules per path.

6. **Funds and treasury subsystem**
   - `treasury`, `allocation`, `daiFund`, `wethFund`, and `planterFund` handle how incoming value is split and stored.
   - These are the financial settlement contracts: sale proceeds flow into allocation logic, then into purpose-specific funds.
   - The presence of both `daiFund` and `wethFund` indicates support for multiple asset types, not just one native payment token.

7. **Planter subsystem**
   - `planter` stores planter-related data and likely acts as the protocol’s identity/profile layer for growers.
   - `planterFund` is a dedicated fund contract tied to planter economics or rewards.
   - This separation suggests planter data and planter economics are intentionally decoupled.

8. **Gasless / meta-transaction support**
   - `contracts/gsn` plus `contracts/external/gsn` indicate **OpenGSN-style relayed transactions**.
   - `whiteListPaymaster` and `whiteListPaymasterTreeBox` are paymaster contracts that sponsor gas under policy controls.
   - This creates an important boundary between **user intent** and **who pays gas**, enabling gasless user actions.

9. **External protocol integrations**
   - `contracts/external/uniswap`, `v2-core`, `v2-periphery`, and `miniUniswap` show embedded Uniswap-related code.
   - This repo likely uses Uniswap components for local testing, pricing, swaps, or liquidity-dependent flows.
   - `contracts/external/echidnaTest` contains fuzzing harnesses/configuration for property-based security testing.

10. **Deployment and initialization pipeline**
   - The numbered `migrations/` scripts show a **sequential Truffle deployment flow**.
   - Early migrations deploy core primitives; later ones run setup methods, transfer ownership, adjust admin roles, and configure paymasters/funds.
   - This indicates the protocol is not just deployed once; it requires **post-deployment initialization** across multiple contracts.

11. **Testing architecture**
   - `test/` contains contract-level tests grouped by subsystem: access, auction, sale flows, funds, tree logic, GSN, paymasters, and arithmetic/helpers.
   - `test/common.js`, `test/config.js`, `test/math.js`, and `test/enumes.js` act as shared test utilities/supporting fixtures.
   - The test layout mirrors the contract boundaries, which is helpful for diagramming interactions.

12. **Tooling and execution environment**
   - The repo is built around **Truffle** (`truffle-config.js`), with scripts for Ganache, coverage, gas reporting, and GSN testing.
   - Docker and CI are first-class: `.circleci`, `.github/workflows`, `.travis.yml`, `Dockerfile`, `docker-compose.yml`.
   - `scripts/run_echidna.sh` and `scripts/run_gsn.sh` show dedicated automation for security and relayer-related flows.

13. **How to think about the system diagram**
   - A good architecture diagram would place **sale/auction contracts** as the entry point for user interactions.
   - Those contracts flow into **tree minting / planter state / fund allocation** contracts.
   - **Access control** and **GSN paymasters** sit as cross-cutting boundaries.
   - **Uniswap and external vendored contracts** are supporting infrastructure, not the protocol’s primary business logic.

14. **Overall shape**
   - The repo is a **modular on-chain protocol** with:
     - asset contracts,
     - sale mechanisms,
     - financial settlement,
     - permissions,
     - meta-transaction support,
     - and a substantial testing/deployment harness.
   - The strongest architectural theme is **separation by responsibility**, with each business capability isolated into its own contract family.

Main entry points: [`contracts/tree`](https://github.com/treejer/contract/tree/main/contracts/tree) (Tree), [`migrations`](https://github.com/treejer/contract/tree/main/migrations) (Migrations), [`test`](https://github.com/treejer/contract/tree/main/test) (Tests), [`contracts/auction`](https://github.com/treejer/contract/tree/main/contracts/auction) (Auction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol contracts"]
  node_tree["Tree<br/>asset contract"]
  node_tree_attribute["Tree attrs<br/>metadata contract"]
  node_tree_factory["Tree factory<br/>orchestration contract"]
  node_tree_box["Tree box<br/>claim container"]
  node_planter["Planter<br/>profile contract"]
  node_planter_fund[("Planter fund<br/>fund contract")]
  node_auction["Auction<br/>sale contract"]
  node_regular_sale["Regular sale<br/>sale contract"]
  node_incremental_sale["Incremental sale<br/>sale contract"]
  node_community_gifts["Community gifts<br/>distribution contract"]
  node_allocation["Allocation<br/>settlement contract"]
  node_treasury[("Treasury<br/>funds contract")]
  node_dai_fund[("DAI fund<br/>asset fund")]
  node_weth_fund[("WETH fund<br/>asset fund")]
end

subgraph group_crosscutting["Cross-cutting"]
  node_access_restriction{{"Access control<br/>permission boundary"}}
  node_honorary_tree["Honorary tree<br/>special issuance"]
  node_gsn_paymaster{{"GSN paymaster<br/>meta-tx sponsor"}}
end

subgraph group_external["Vendored external"]
  node_uniswap_ext["Uniswap<br/>external AMM code"]
  node_echidna_ext["Echidna<br/>fuzz harness"]
end

subgraph group_ops["Deployment and test"]
  node_migrations["Migrations<br/>deployment pipeline"]
  node_tests["Tests"]
  node_scripts["Scripts<br/>automation"]
  node_truffle_config["Truffle config<br/>tooling config<br/>[truffle-config.js]"]
end

node_auction -->|"mints"| node_tree
node_regular_sale -->|"mints"| node_tree
node_incremental_sale -->|"mints"| node_tree
node_community_gifts -->|"issues"| node_tree
node_honorary_tree -->|"special mint"| node_tree
node_tree_factory -->|"creates"| node_tree
node_tree_factory -->|"wires"| node_tree_attribute
node_tree -.->|"reads metadata"| node_tree_attribute
node_tree_box -->|"claims tree"| node_tree
node_auction -->|"routes funds"| node_allocation
node_regular_sale -->|"routes funds"| node_allocation
node_incremental_sale -->|"routes funds"| node_allocation
node_community_gifts -->|"settles"| node_treasury
node_allocation -->|"splits to"| node_treasury
node_treasury -->|"allocates"| node_dai_fund
node_treasury -->|"allocates"| node_weth_fund
node_planter -->|"supports"| node_planter_fund
node_access_restriction -.->|"guards"| node_auction
node_access_restriction -.->|"guards"| node_regular_sale
node_access_restriction -.->|"guards"| node_incremental_sale
node_access_restriction -.->|"guards"| node_tree_factory
node_gsn_paymaster -.->|"sponsors"| node_auction
node_gsn_paymaster -.->|"sponsors"| node_regular_sale
node_gsn_paymaster -.->|"sponsors"| node_tree_box
node_migrations -->|"deploys"| node_access_restriction
node_migrations -->|"deploys"| node_auction
node_migrations -->|"configures"| node_tree_factory
node_migrations -->|"funds/configures"| node_gsn_paymaster
node_migrations -->|"deploys"| node_tree_box
node_tests -.->|"verifies"| node_tree
node_tests -.->|"verifies"| node_auction
node_tests -.->|"verifies"| node_allocation
node_tests -.->|"verifies"| node_gsn_paymaster
node_scripts -.->|"drives"| node_migrations
node_scripts -.->|"drives"| node_tests
node_uniswap_ext -.->|"supports pricing"| node_auction
node_echidna_ext -.->|"fuzzes"| node_tests
node_truffle_config -.->|"configures"| node_migrations
node_truffle_config -.->|"configures"| node_tests

click node_tree "https://github.com/treejer/contract/tree/main/contracts/tree"
click node_tree_box "https://github.com/treejer/contract/tree/main/contracts/treeBox"
click node_planter "https://github.com/treejer/contract/tree/main/contracts/planter"
click node_auction "https://github.com/treejer/contract/tree/main/contracts/auction"
click node_regular_sale "https://github.com/treejer/contract/tree/main/contracts/regularSale"
click node_incremental_sale "https://github.com/treejer/contract/tree/main/contracts/incrementalSale"
click node_allocation "https://github.com/treejer/contract/tree/main/contracts/treasury"
click node_treasury "https://github.com/treejer/contract/tree/main/contracts/treasury"
click node_dai_fund "https://github.com/treejer/contract/tree/main/contracts/treasury"
click node_weth_fund "https://github.com/treejer/contract/tree/main/contracts/treasury"
click node_access_restriction "https://github.com/treejer/contract/tree/main/contracts/access"
click node_honorary_tree "https://github.com/treejer/contract/tree/main/contracts/honoraryTree"
click node_gsn_paymaster "https://github.com/treejer/contract/tree/main/contracts/gsn"
click node_uniswap_ext "https://github.com/treejer/contract/tree/main/contracts/external/uniswap"
click node_echidna_ext "https://github.com/treejer/contract/tree/main/contracts/external/echidnaTest"
click node_migrations "https://github.com/treejer/contract/tree/main/migrations"
click node_tests "https://github.com/treejer/contract/tree/main/test"
click node_scripts "https://github.com/treejer/contract/tree/main/scripts"
click node_truffle_config "https://github.com/treejer/contract/blob/main/truffle-config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tree,node_tree_attribute,node_tree_factory,node_tree_box,node_planter,node_planter_fund,node_auction,node_regular_sale,node_incremental_sale,node_community_gifts,node_allocation,node_treasury,node_dai_fund,node_weth_fund toneBlue
class node_access_restriction,node_honorary_tree,node_gsn_paymaster toneAmber
class node_uniswap_ext,node_echidna_ext toneMint
class node_migrations,node_tests,node_scripts,node_truffle_config toneRose
```

## Components

### Protocol contracts

Core on-chain business logic for trees, sales, planters, and funds.

- [Tree](https://github.com/treejer/contract/tree/main/contracts/tree): asset contract · Core tree ownership and minting contract. · `contracts/tree`
- **Tree attrs**: metadata contract · Separates tree properties and metadata from ownership state.
- **Tree factory**: orchestration contract · Creates and wires tree-related contracts or instances.
- [Tree box](https://github.com/treejer/contract/tree/main/contracts/treeBox): claim container · Tree-related boxed product or claim path. · `contracts/treeBox`
- [Planter](https://github.com/treejer/contract/tree/main/contracts/planter): profile contract · Stores planter identity and protocol-facing planter state. · `contracts/planter`
- **Planter fund**: fund contract · Dedicated fund or reward pool tied to planter economics.
- [Auction](https://github.com/treejer/contract/tree/main/contracts/auction): sale contract · Auction-based tree sale mechanism. · `contracts/auction`
- [Regular sale](https://github.com/treejer/contract/tree/main/contracts/regularSale): sale contract · Standard fixed-price sale path. · `contracts/regularSale`
- [Incremental sale](https://github.com/treejer/contract/tree/main/contracts/incrementalSale): sale contract · Sale mechanism with changing pricing or issuance rules. · `contracts/incrementalSale`
- **Community gifts**: distribution contract · Non-sale distribution path for tree issuance or rewards.
- [Allocation](https://github.com/treejer/contract/tree/main/contracts/treasury): settlement contract · Splits incoming value into protocol-specific buckets. · `contracts/treasury`
- [Treasury](https://github.com/treejer/contract/tree/main/contracts/treasury): funds contract · Main treasury boundary for protocol-held value. · `contracts/treasury`
- [DAI fund](https://github.com/treejer/contract/tree/main/contracts/treasury): asset fund · Treasury sub-fund for DAI-denominated flows. · `contracts/treasury`
- [WETH fund](https://github.com/treejer/contract/tree/main/contracts/treasury): asset fund · Treasury sub-fund for WETH-denominated flows. · `contracts/treasury`

### Cross-cutting

Authorization and meta-transaction boundaries used across protocol actions.

- [Access control](https://github.com/treejer/contract/tree/main/contracts/access): permission boundary · Authorization layer for privileged protocol actions. · `contracts/access`
- [Honorary tree](https://github.com/treejer/contract/tree/main/contracts/honoraryTree): special issuance · Special tree issuance path for privileged or non-standard minting. · `contracts/honoraryTree`
- [GSN paymaster](https://github.com/treejer/contract/tree/main/contracts/gsn): meta-tx sponsor · Sponsors gas for approved actions under whitelist policy. · `contracts/gsn`

### Vendored external

Embedded third-party protocol code and security-testing harnesses.

- [Uniswap](https://github.com/treejer/contract/tree/main/contracts/external/uniswap): external AMM code · Vendored Uniswap components used as supporting infrastructure. · `contracts/external/uniswap`
- [Echidna](https://github.com/treejer/contract/tree/main/contracts/external/echidnaTest): fuzz harness · Property-based testing harness and configs for security testing. · `contracts/external/echidnaTest`

### Deployment and test

Migration, testing, and automation workflow around the contracts.

- [Migrations](https://github.com/treejer/contract/tree/main/migrations): deployment pipeline · Sequential Truffle deployment and initialization scripts. · `migrations`
- [Tests](https://github.com/treejer/contract/tree/main/test): contract tests · Subsystem-aligned test suite for protocol logic and integrations. · `test`
- [Scripts](https://github.com/treejer/contract/tree/main/scripts): automation · Helper scripts for Ganache, GSN, coverage, and test execution. · `scripts`
- [Truffle config](https://github.com/treejer/contract/blob/main/truffle-config.js): tooling config · Primary Truffle configuration for compilation and networks. · `truffle-config.js`

## Connections

- Auction → Tree: mints · Auction sales ultimately issue trees.
- Regular sale → Tree: mints · Fixed-price sales issue trees.
- Incremental sale → Tree: mints · Incremental pricing sales issue trees.
- Community gifts → Tree: issues · Non-sale distribution path for trees.
- Honorary tree → Tree: special mint · Privileged issuance path into the main tree asset.
- Tree factory → Tree: creates · Factory orchestrates tree-related deployment or instantiation.
- Tree factory → Tree attrs: wires · Factory connects tree metadata/attribute management.
- Tree → Tree attrs: reads metadata · Ownership and metadata are separated but linked.
- Tree box → Tree: claims tree · Tree box is an alternate tree-related product path.
- Auction → Allocation: routes funds · Sale proceeds flow into allocation logic.
- Regular sale → Allocation: routes funds · Sale proceeds flow into allocation logic.
- Incremental sale → Allocation: routes funds · Sale proceeds flow into allocation logic.
- Community gifts → Treasury: settles · Distribution paths may still interact with treasury accounting.
- Allocation → Treasury: splits to · Allocation distributes funds into treasury and sub-funds.
- Treasury → DAI fund: allocates · Treasury manages DAI-specific funds.
- Treasury → WETH fund: allocates · Treasury manages WETH-specific funds.
- Planter → Planter fund: supports · Planter identity links to planter economics.
- Access control → Auction: guards · Authorization boundary for privileged market actions.
- Access control → Regular sale: guards · Authorization boundary for privileged market actions.
- Access control → Incremental sale: guards · Authorization boundary for privileged market actions.
- Access control → Tree factory: guards · Controls creation and admin operations.
- GSN paymaster → Auction: sponsors · Meta-transaction support for user actions.
- GSN paymaster → Regular sale: sponsors · Meta-transaction support for user actions.
- GSN paymaster → Tree box: sponsors · Special paymaster path for tree box actions.
- Migrations → Access control: deploys · Deployment pipeline initializes core permissions.
- Migrations → Auction: deploys · Deployment pipeline includes market contracts.
- Migrations → Tree factory: configures · Later migrations run setup and ownership transfer.
- Migrations → GSN paymaster: funds/configures · Deployment scripts set up gas sponsor contracts.
- Migrations → Tree box: deploys · Separate migration flow for tree box functionality.
- Tests → Tree: verifies · Contract tests cover asset behavior.
- Tests → Auction: verifies · Contract tests cover auction flow.
- Tests → Allocation: verifies · Contract tests cover settlement and fund splitting.
- Tests → GSN paymaster: verifies · Tests cover meta-transaction and paymaster behavior.
- Scripts → Migrations: drives · Automation executes deployment and initialization flows.
- Scripts → Tests: drives · Automation runs test, coverage, and gas-reporting workflows.
- Uniswap → Auction: supports pricing · Vendored AMM code supports protocol market behavior.
- Echidna → Tests: fuzzes · Security harness complements the standard test suite.
- Truffle config → Migrations: configures · Truffle settings define deployment and network behavior.
- Truffle config → Tests: configures · Truffle settings drive test execution.