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

# Smart contract architecture

> How the GoldToken, GoldFaucet, OwnaFarmNFT, and OwnaFarmVault contracts work together to power trustless invoice financing on Mantle.

OwnaFarm's smart contracts form the trustless backbone that handles all financial transactions.

## Contract ecosystem

```mermaid theme={null}
graph TB
    FAUCET[GoldFaucet] -->|distributes| GOLD[GoldToken<br/>ERC-20]
    GOLD -->|payment| NFT[OwnaFarmNFT<br/>ERC-1155]
    NFT -->|claims from| VAULT[OwnaFarmVault]
    GOLD -->|funds| VAULT
```

## Contract summary

### GoldToken (ERC-20)

Platform currency for all transactions.

| Property       | Value         |
| -------------- | ------------- |
| Name           | OwnaFarm Gold |
| Symbol         | GOLD          |
| Decimals       | 18            |
| Initial supply | 100,000,000   |

### GoldFaucet

Testnet token distribution.

| Property     | Value       |
| ------------ | ----------- |
| Claim amount | 10,000 GOLD |
| Cooldown     | 24 hours    |

### OwnaFarmNFT (ERC-1155)

Core contract for invoices and investments.

| Feature             | Description                 |
| ------------------- | --------------------------- |
| Invoice submission  | Farmers submit for approval |
| Investment tracking | Per-investor records        |
| Harvest settlement  | Automated claims            |

### OwnaFarmVault

Yield reserve management.

| Feature       | Description             |
| ------------- | ----------------------- |
| Yield deposit | Admin deposits reserves |
| Withdrawal    | Only by OwnaFarmNFT     |
| Emergency     | Owner recovery function |

## Invoice status flow

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending: submitInvoice()
    Pending --> Approved: approveInvoice()
    Pending --> Rejected: rejectInvoice()
    Approved --> Funded: invest() 100%
    Funded --> Completed: all harvested
```

| Status    | Code | Can invest | Can harvest          |
| --------- | ---- | ---------- | -------------------- |
| Pending   | 0    | No         | No                   |
| Approved  | 1    | Yes        | No                   |
| Rejected  | 2    | No         | No                   |
| Funded    | 3    | No         | Yes (after maturity) |
| Completed | 4    | No         | No                   |

## Access control

```text Roles theme={null}
Owner (deployer)
  - GoldToken: mint()
  - GoldFaucet: setClaimAmount(), setCooldown()
  - OwnaFarmVault: emergencyWithdraw()

Admin role
  - OwnaFarmNFT: approveInvoice(), rejectInvoice()
  - OwnaFarmVault: depositYield()

Public
  - GoldFaucet: claim()
  - OwnaFarmNFT: submitInvoice(), invest(), harvest()
```

## Yield calculation

```text Example theme={null}
Principal = Investment amount
Yield = Principal x (yieldBps / 10000)
Total Return = Principal + Yield

Principal = 1000 GOLD
yieldBps = 1500 (15%)
Yield = 1000 x (1500 / 10000) = 150 GOLD
Total = 1150 GOLD
```

## Development

| Item      | Detail           |
| --------- | ---------------- |
| Framework | Foundry          |
| Language  | Solidity ^0.8.24 |
| Network   | Mantle Sepolia   |
| Chain ID  | 5003             |