How treejer/contract works
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: tree Tree · migrations Migrations · test Tests · auction Auction
Components 23
Protocol contracts
Core on-chain business logic for trees, sales, planters, and funds.
- Tree · Core tree ownership and minting contract.
contracts/tree - Tree attrs · Separates tree properties and metadata from ownership state.
- Tree factory · Creates and wires tree-related contracts or instances.
- Tree box · Tree-related boxed product or claim path.
contracts/treeBox - Planter · Stores planter identity and protocol-facing planter state.
contracts/planter - Planter fund · Dedicated fund or reward pool tied to planter economics.
- Auction · Auction-based tree sale mechanism.
contracts/auction - Regular sale · Standard fixed-price sale path.
contracts/regularSale - Incremental sale · Sale mechanism with changing pricing or issuance rules.
contracts/incrementalSale - Community gifts · Non-sale distribution path for tree issuance or rewards.
- Allocation · Splits incoming value into protocol-specific buckets.
contracts/treasury - Treasury · Main treasury boundary for protocol-held value.
contracts/treasury - DAI fund · Treasury sub-fund for DAI-denominated flows.
contracts/treasury - WETH fund · Treasury sub-fund for WETH-denominated flows.
contracts/treasury
Cross-cutting
Authorization and meta-transaction boundaries used across protocol actions.
- Access control · Authorization layer for privileged protocol actions.
contracts/access - Honorary tree · Special tree issuance path for privileged or non-standard minting.
contracts/honoraryTree - GSN paymaster · Sponsors gas for approved actions under whitelist policy.
contracts/gsn
Vendored external
Embedded third-party protocol code and security-testing harnesses.
Deployment and test
Migration, testing, and automation workflow around the contracts.
- Migrations · Sequential Truffle deployment and initialization scripts.
migrations - Tests · Subsystem-aligned test suite for protocol logic and integrations.
test - Scripts · Helper scripts for Ganache, GSN, coverage, and test execution.
scripts - Truffle config · Primary Truffle configuration for compilation and networks.
truffle-config.js
Connections 39
- 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.