# Smart Contract Architecture

Pencil Finance is built with modular, secure, and upgradeable smart contracts to manage decentralized investment, token issuance, repayment, and interest distribution within student loan bundles. Below is a breakdown of the core contract system.

### **📦 BundleManager Contract**

**Purpose**: Handles creation and configuration of loan bundles by lending partners.

#### **Functions:**

* createBundle(...): Initializes a new bundle with parameters (loan amount, tranche ratios, interest rates, lock-up period).
* updateBundleMetadata(...): Allows lending company to update documents, announcements.
* setStatus(...): Changes bundle status (e.g., Upcoming → Raising → Sold Out→ Staking → Redemption).
* uploadReport(...): Uploads repayment or performance updates for investors.

### **💰 SeniorPool Contract**

**Purpose**: Manages deposits and redemptions for **Senior Tranche (Grow Token)** investors.

#### **Functions:**

* deposit(amount): Accepts USDC, mints Grow Tokens.
* redeem(tokenAmount): Burns Grow Tokens and returns USDC, subject to withdrawal logic.
* queueWithdrawal(amount): Enters a withdrawal queue if liquidity is locked.
* processWithdrawalQueue(): Automatically fulfills withdrawals when capital is available.
* calculateInterest(...): Computes interest at maturity based on bundle terms.

### **🧩 JuniorPool Contract**

**Purpose**: Manages capital raised through **Junior Tranche (NFT)**.

#### **Functions:**

* mintNFT(investor, amount, rate): Mints an ERC-721 NFT representing ownership in the Junior Pool.
* claimInterest(nftId): Withdraws available interest tied to the NFT.
* redeemNFT(nftId): Withdraws final interest + principal at maturity.
* calculateShare(nftId): Calculates proportional ownership and payouts for NFT holders.

### **🔁 RepaymentVault Contract （MVP: no defaults）**

**Purpose**: Handles fund flows from lending companies and allocates repayments to tranches.

#### **Functions:**

* depositRepayment(bundleId, amount): Lending company repays capital + interest into the vault.
* allocateFunds(): Automatically distributes funds across Senior/Junior pools based on:
  * Repayment ratio
  * Outstanding principal
  * Priority rules (e.g., first pay Senior interest, then Junior)
* markOverdue(bundleId, amount): Tracks overdue loans if repayment is delayed.

### **🧠 Governance Contract - PEN DAO (Pending)**

**Purpose**: Enables decentralized protocol governance using the PEN token.

#### **Functions:**

* propose(change): Create a new governance proposal.
* vote(proposalId, support): Cast votes using PEN tokens.
* execute(proposalId): Executes passed governance changes (e.g., fee updates, emission adjustments).
* delegate(address): Delegate voting power to another wallet.

### **🔒 AccessControl & Security Modules (Pending)**

**Modules & Patterns**:

* **Role-based permissions** for lending companies, DAO, and protocol operators.
* **OpenZeppelin libraries** for ERC-20, ERC-721, SafeMath, Pausable, and Ownable.
* **Upgradable Proxies** via UUPS pattern (if needed for flexibility).
* **Auditing hooks** and **emergency pause** functions to manage platform risk.

### **🛡️ Security & Best Practices (Pending)**

* **External audits** before mainnet deployment.
* **Formal verification** of interest calculations, queue processing.
* **Testnet simulations** for bundle lifecycle and edge cases (e.g., partial repayments, investor overflows).
* **Bug bounty program** planned at mainnet launch to incentivize white-hat contributions.