Textile Protocol v2.1 Documentation

Welcome to the Textile Protocol v2.1 documentation! This directory contains guides for different audiences.

📚 Documentation Index

For Developers

Developer Guide

Quick start (5-minute setup)
Architecture overview
Code examples using viem/wagmi
Frontend and backend integration
Auto-interest compounding feature guide
The Graph subgraph setup
Event handling and error handling
Complete function reference
Audience: Frontend and backend developers

Upgradeability Guide

UUPS proxy pattern explained
Storage layout rules and best practices
Testing and verification procedures
Emergency procedures and rollback
Complete upgrade example code
Audience: Protocol admins, DevOps, security teams

For Security Auditors

Auditor Introduction

Complete architecture documentation
Access control and trust boundaries
Mathematical specifications
All core flows with sequence diagrams
Invariants and safety properties
Comprehensive audit checklist
Audience: Security auditors and protocol architects

For DevOps/Deployment

Deployment Guide (Available in protocol package)

Step-by-step deployment instructions
Local, testnet, and mainnet deployment
Environment variables reference
Post-deployment configuration
Troubleshooting guide
Audience: DevOps engineers, deployers
Location: packages/protocol/scripts/v2.1/README.md in the monorepo

🎨 Visual Documentation

Flow Diagrams

All major operations are documented with Mermaid diagrams in the flows/ directory:

Architecture Overview - Complete system diagram
Deposit Flow - LP deposit process
Drawdown Flow - Borrower capital deployment
Repayment Flow - Interest and principal repayment
Withdrawal Approval Flow - Three-step withdrawal
Factory Deployment Flow - Pool deployment sequence

Flow Diagrams README - How to view and use the diagrams

🏗️ Protocol Architecture

🔑 Critical: One Pool = One Borrower

Each pool in v2.1 serves exactly one borrower (designated at creation, immutable). This is a fundamental design choice:

Each StructuredPool has integrated credit line management for one borrower address
To support multiple borrowers, deploy multiple pools
Lenders can diversify by depositing into multiple pools

Core Components (8 Contracts)

Organized into logical subdirectories for better maintainability:

Core Pool & Tranche (contracts/v2.1/core/):

Contract	Purpose	Lines of Code	Upgradeable
StructuredPool	Coordinates pool operations & manages integrated credit line	~1,200	✅ BeaconProxy
Tranche	ERC4626 vault for lenders	~900	✅ BeaconProxy
Reserve	Immutable asset custody	~280	❌ Immutable

Infrastructure (contracts/v2.1/infrastructure/):

Contract	Purpose	Lines of Code
Registry	Central infrastructure hub	405
WithdrawalRegistry	Manages withdrawal approvals	326
UnderwriterRegistry	Public underwriter registry	239
ProtocolConfiguration	Global settings and fees	147

Factory (contracts/v2.1/factory/):

Contract	Purpose	Lines of Code
PoolFactory	Deploys pools via minimal proxies	197

Abstract Base Contracts (2 Contracts)

Located in contracts/v2.1/base/:

Contract	Purpose	Lines
AccessControlHelpers	Governance self-bricking prevention	106
AccessControlHelpersUpgradeable	Upgradeable governance protection	109

Supporting Libraries (6 Libraries)

Organized by function in contracts/v2.1/libraries/:

Library	Location	Purpose	Lines
Errors	`helpers/`	Custom error definitions	88
MathUtils	`math/`	Interest rate calculations	122
ValidationLogic	`logic/`	Settings validation	155
SettingsProposal	`logic/`	2-step approval pattern	101
Roles	`access/`	Role definitions	48
DataTypes	`types/`	Data structures	48

Deprecated Contracts (v2-deprecated)

Legacy contracts from earlier protocol versions are maintained in contracts/v2-deprecated/ for reference and backwards compatibility. These include:

Core: CreditLineController.sol, CreditLineLIController.sol, VaultV2.sol, VaultV2LI.sol
Libraries: Minimal error set (24 lines), legacy validation, interest index logic, rate calculations
Interfaces: Legacy controller and vault interfaces

Note: Deprecated contracts are not recommended for new deployments.

🧪 Testing

Test Coverage

35+ comprehensive test files organized by component:

Tranche: 8 test files (ERC4626 compliance, fees, inflation protection, interest compounding, access control)
StructuredPool: 7 test files (deployment, access control, underwriter, tranche settings, repayment during shutdown, upgradeability, drawdown, repayment, interest)
Registry: 4 test files (registration, access control, role rotation)
Reserve: 2 test files (custody, access control)
WithdrawalRegistry: 3 test files (request/approve/consume flows, access control)
ProtocolConfiguration: 2 test files (configuration, access control, governance self-bricking prevention)
Factory: 3 test files (deployment, security, access control)
Libraries: 3 test files (math, validation, roles)
Total Test Cases: 884 individual tests ✅

Running Tests

bash

# All v2.1 tests
cd packages/protocol
yarn test

# Specific component
yarn hardhat test test/v2.1/Tranche/

# With gas reporting
REPORT_GAS=true yarn test

# With coverage
yarn hardhat coverage

🚀 Quick Start

1. Local Development

bash

# Terminal 1: Start Hardhat node
cd packages/protocol
yarn hardhat node

# Terminal 2: Deploy v2.1
yarn deploy:v2:local

Addresses saved to: packages/constants/src/addresses.localhost.json

2. Interact with a Pool

typescript

import { useContractRead, useContractWrite } from 'wagmi'
import { parseUnits } from 'viem'
import { SAMPLE_POOL } from '@textile/constants'

// Deposit
const { write: deposit } = useContractWrite({
  address: trancheAddress,
  abi: TrancheABI,
  functionName: 'deposit',
  args: [parseUnits('1000', 6), userAddress]
})

See Developer Guide for complete examples.

3. Deploy to Testnet

bash

# Configure environment variables
cp .env.example .env
# Edit .env with your keys

# Deploy to Celo Sepolia (Celo testnet)
yarn deploy:v2:celo-sepolia

🎯 Key Improvements in v2.1

Coming from v1.x or v2.0? Here's what's new:

1. ERC4626 Standard Compliance

Tranches are now industry-standard vaults
Compatible with DeFi aggregators
Standardized deposit/withdraw interface

2. Immutable Custody (Reserve)

Trustless asset custody
No upgrade mechanism
Guardian with 3-day timelock for emergencies only

3. Consolidated Architecture

Credit line logic is now integrated directly into StructuredPool
Reduces architectural complexity and deployment steps
Pool includes integrated credit line management
State preserved during upgrades via BeaconProxy pattern

4. Factory Pattern

Deploy pools and tranches via BeaconProxies
Standardized and secure mass upgrade capability via Beacons
Auto-registers pool in Registry

5. Helper Functions

getVirtualBalances() - All accounting in one call
getPoolMetrics() - Complete pool stats
getDebtDetails() - Full debt breakdown
More efficient RPC usage

6. Withdrawal Approval System

Optional two-step withdrawal flow
Reserved shares prevent borrowing approved funds
Better liquidity management
Prevents bank-run scenarios

7. Settings Proposals

2-step approval for critical changes (if pool has underwriter)
Manager proposes, underwriter approves
Default 7-day expiry window (not a mandatory waiting period)
Without underwriter, changes apply immediately

8. Per-Second Interest

RAY precision (10^27) calculations
4th order binomial approximation for accurate compounding
More accurate than daily/monthly compounding
Fair for all participants

📊 Statistics

Code Metrics

Total Contracts: 9 core + 2 base contracts = 11 active contracts
Supporting Libraries: 6 libraries (organized in helpers/, math/, logic/, access/, types/)
Deprecated Contracts: 4 legacy contracts + 5 deprecated libraries (in v2-deprecated/)
Lines of Solidity: ~4,400 lines (v2.1 active code)
Test Files: 35+ comprehensive test suites
Test Coverage: >95% line coverage
Documentation: 3,500+ lines across 4 major docs

Performance

Metric	Value
Pool Deployment Gas	~3.5M gas
Deposit Gas	~80k-150k gas
Withdrawal Gas	~70k-90k gas
Drawdown Gas	~120k gas
Repayment Gas	~150k gas

🔐 Security

Audit Status

[x] Internal code review complete
[x] 884 tests passing (35+ test suites)
[x] Mathematical validation complete
[x] Upgradeability implementation complete
[ ] External security audit (pending)
[ ] Mainnet deployment (after audit)

Best Practices Implemented

✅ Custom errors for gas efficiency
✅ ReentrancyGuard on all state-changing functions
✅ Checks-Effects-Interactions pattern
✅ Pausable emergency stops with asymmetric shutdown (repayments allowed)
✅ Inflation attack protection
✅ Settings proposal pattern with 2-step approval
✅ Role-based access control with governance self-bricking prevention
✅ Immutable custody layer
✅ AccessControlHelpers pattern for secure role rotation

🤝 Contributing

Report Issues

Found a bug or have a suggestion?

Check existing issues on GitHub
Create a new issue with details
Tag with appropriate labels
Follow up on discussion

Documentation Improvements

Have a documentation suggestion?

Identify which doc needs updating
Submit a PR with changes
Explain the improvement
Tag @protocol-team for review

Code Contributions

Want to contribute code?

Read the Developer Guide
Check open issues for "good first issue" tags
Fork, branch, and implement
Submit PR with tests
Pass CI checks and review

📝 Version History

v2.1 (Current)

Initial release of structured pool architecture
Single tranche per pool
ERC4626 compliance
Immutable custody
Settings proposals with 2-step approval
Auto-interest compounding control (per-LP income distribution)

v2.0 (Deprecated)

Experimental multi-tranche implementation
Not recommended for production use
Migrate to v2.1

v1.x (Legacy, Still Supported)

Original vault implementation
No forced migration
Can coexist with v2.1

📞 Contact

Protocol Team: @textileprotocol (Telegram)
General Support: support@textilecredit.com
Security Issues: benoit@textilecredit.com (please report responsibly)
Partnerships: tomer@textilecredit.com

Happy Building! 🚀

Last Updated: 2025-10-21Protocol Version: v2.1 (Single Tranche)Documentation Version: 1.3Test Suite: 884 tests passing ✅

Textile Protocol v2.1 Documentation ​

📚 Documentation Index ​

For Developers ​

For Security Auditors ​

For DevOps/Deployment ​

🎨 Visual Documentation ​

Flow Diagrams ​

🏗️ Protocol Architecture ​

🔑 Critical: One Pool = One Borrower ​

Core Components (8 Contracts) ​

Abstract Base Contracts (2 Contracts) ​

Supporting Libraries (6 Libraries) ​

Deprecated Contracts (v2-deprecated) ​

🧪 Testing ​

Test Coverage ​

Running Tests ​

🚀 Quick Start ​

1. Local Development ​

2. Interact with a Pool ​

3. Deploy to Testnet ​

🎯 Key Improvements in v2.1 ​

1. ERC4626 Standard Compliance ​

2. Immutable Custody (Reserve) ​

3. Consolidated Architecture ​

4. Factory Pattern ​

5. Helper Functions ​

6. Withdrawal Approval System ​

7. Settings Proposals ​

8. Per-Second Interest ​

📊 Statistics ​

Code Metrics ​

Performance ​

🔐 Security ​

Audit Status ​

Best Practices Implemented ​

🤝 Contributing ​

Report Issues ​

Documentation Improvements ​

Code Contributions ​

📝 Version History ​

v2.1 (Current) ​

v2.0 (Deprecated) ​

v1.x (Legacy, Still Supported) ​

📞 Contact ​

Textile Protocol v2.1 Documentation

📚 Documentation Index

For Developers

For Security Auditors

For DevOps/Deployment

🎨 Visual Documentation

Flow Diagrams

🏗️ Protocol Architecture

🔑 Critical: One Pool = One Borrower

Core Components (8 Contracts)

Abstract Base Contracts (2 Contracts)

Supporting Libraries (6 Libraries)

Deprecated Contracts (v2-deprecated)

🧪 Testing

Test Coverage

Running Tests

🚀 Quick Start

1. Local Development

2. Interact with a Pool

3. Deploy to Testnet

🎯 Key Improvements in v2.1

1. ERC4626 Standard Compliance

2. Immutable Custody (Reserve)

3. Consolidated Architecture

4. Factory Pattern

5. Helper Functions

6. Withdrawal Approval System

7. Settings Proposals

8. Per-Second Interest

📊 Statistics

Code Metrics

Performance

🔐 Security

Audit Status

Best Practices Implemented

🤝 Contributing

Report Issues

Documentation Improvements

Code Contributions

📝 Version History

v2.1 (Current)

v2.0 (Deprecated)

v1.x (Legacy, Still Supported)

📞 Contact