Textile Docs

Appearance

Protocol v2.1 Flow Diagrams ​

This directory contains Mermaid flow diagrams documenting the Textile Protocol v2.1 architecture and core flows.

Diagram Files ​

01. Architecture Overview ​

File: 01-architecture-overview.mmd

Complete system architecture showing:

  • Protocol infrastructure layer (Registry, WithdrawalRegistry, ProtocolConfiguration, etc.)
  • Pool instance components (StructuredPool, Tranche, Reserve, CreditLineController)
  • External actor interactions
  • Component relationships and data flows

02. Deposit Flow ​

File: 02-deposit-flow.mmd

Liquidity provider deposit flow:

  1. Pre-flight checks (pause state, limits, shutdown)
  2. Share calculation (ERC4626 standard)
  3. Fund custody transfer to Reserve
  4. Virtual accounting updates
  5. Share token minting

03. Drawdown Flow ​

File: 03-drawdown-flow.mmd

Borrower capital deployment flow:

  1. Authorization checks (onlyBorrower)
  2. Forced interest accrual
  3. Credit limit validation
  4. Tranche selection
  5. Capital deployment from Reserve to borrower
  6. Virtual accounting updates (virtualBalance → virtualDeployed)

04. Repayment Flow ​

File: 04-repayment-flow.mmd

Borrower repayment processing:

  1. Forced interest accrual
  2. Payment split (interest vs principal)
  3. Interest routing to Reserve → Tranche
  4. Principal routing to Reserve → Tranche
  5. Virtual accounting updates
  6. Credit line adjustment

05. Approval-Based Withdrawal Flow ​

File: 05-withdrawal-approval-flow.mmd

Three-step withdrawal process when approval required:

  1. Request: LP submits withdrawal request to WithdrawalRegistry
  2. Approve: Pool manager approves specific share amount (shares become reserved)
  3. Execute: LP executes standard withdraw/redeem with approval consumption

Reserved Shares Protection: Approved shares are tracked in totalReservedShares and excluded from getAvailableForBorrowing(), preventing borrowers from drawing funds that LPs have requested to withdraw.

06. Factory Deployment Flow ​

File: 06-factory-deployment-flow.mmd

Complete pool deployment sequence:

  1. Deploy StructuredPool as BeaconProxy (includes integrated credit line)
  2. Deploy Tranche as BeaconProxy
  3. Deploy immutable Reserve in Tranche constructor
  4. Register pool in Registry
  5. Register tranche with pool

Key Feature: All pool components use BeaconProxy pattern for mass upgradeability with timelock protection.

Viewing the Diagrams ​

Online Viewer ​

Use Mermaid Live Editor:

  1. Copy the .mmd file contents
  2. Paste into the editor
  3. View rendered diagram

VS Code ​

Install the Mermaid Preview extension:

code --install-extension bierner.markdown-mermaid

Then open any .mmd file and use Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows/Linux).

Command Line ​

Install Mermaid CLI:

bash
npm install -g @mermaid-js/mermaid-cli

Render to PNG/SVG:

bash
# PNG output
mmdc -i 01-architecture-overview.mmd -o architecture.png

# SVG output
mmdc -i 01-architecture-overview.mmd -o architecture.svg -b transparent

# PDF output
mmdc -i 01-architecture-overview.mmd -o architecture.pdf

Markdown Documentation ​

These diagrams can be embedded in Markdown files:

markdown
```mermaid
{{contents of .mmd file}}
```

Diagram Conventions ​

Color Coding ​

  • Light Blue (#e1f5ff): Infrastructure components
  • Light Yellow (#fff4e1): Pool system components
  • Light Red (#ffcccc): Custody layer (Reserve)
  • Light Gray (#f0f0f0): External actors

Sequence Diagram Sections ​

Colored rectangles indicate logical phases:

  • Pink (rgb(255, 240, 240)): Validation/authorization checks
  • Blue (rgb(240, 248, 255)): Calculations/state reads
  • Green (rgb(240, 255, 240)): State updates/transfers
  • Yellow (rgb(255, 248, 240)): Interest/fee processing

Annotations ​

  • ✅ indicates successful completion
  • ⏳ indicates waiting/pending state
  • ↑ / ↓ indicate increases/decreases
  • Notes provide context about checks, calculations, or state changes
  • Auditor Introduction: ../auditor-intro.md - Comprehensive protocol documentation
  • Developer Guide: ../developer-guide.md - Developer integration guide
  • Protocol Overview: ../overview.md - Non-technical introduction

Updating Diagrams ​

When updating the protocol:

  1. Update the corresponding .mmd file(s)
  2. Regenerate any embedded PNG/SVG images
  3. Update the main auditor intro document if architectural changes occurred
  4. Verify diagrams render correctly in preview tools

Diagram Generation Script ​

A script is available to batch-generate all diagrams:

bash
cd packages/protocol
npm run generate:diagrams

This will:

  • Validate all .mmd files for syntax errors
  • Generate PNG and SVG versions
  • Output to docs/v2.1/flows/generated/

Last Updated: 2025-01-14 Protocol Version: v2.1 (Single Tranche)