tfgrid/docs_tfgrid_economics
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

...
Some checks failed
Deploy to GitHub Pages / Deploy to GitHub Pages (push) Has been cancelled
Details

Browse Source
This commit is contained in:
despiegk
2025-10-11 07:42:27 +04:00
parent a00a487a53
commit 08f065258b
5 changed files with 8 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/core-concepts/dutch-auction-exit.md
View File

@@ -1,128 +0,0 @@
---
sidebar_position: 4
---
# Dutch Auction Exit: Fair and Controlled Liquidity Release
To keep our liquidity pool strong and sustainable, we use a Dutch auction system for exits. This creates a market-driven, disciplined, and fair process that protects long-term participants and discourages opportunistic withdrawals.
## Why a Dutch Auction?
Unlike open liquidity pools where anyone can withdraw anytime, a Dutch auction:
- Prevents sudden value loss or pool drain
- Encourages long-term holding by adding discipline to exits
- Ensures price discovery — exits only happen at a price the market agrees on
## Key Principles
### 1. No Timing Advantage
Everyone can submit their bids before the auction closes. It doesn't matter when you bid — what matters is how low you're willing to go.
### 2. Price Determines Priority
Those who are willing to exit at a lower price per token (i.e. accept a greater discount) get filled first. If more exits are requested than the system allows, only the lowest-price bids are executed.
### 3. Capped Exit Volume
Only up to 50% of total liquidity ever contributed (minus past exits) is allowed to leave through Dutch auctions. This cap protects the pool from being drained.
---
## How It Works — Step by Step
### 1. Bids Are Submitted
Liquidity providers (LPs) submit a request like:
*"I want to exit with €500,000, and I'm willing to sell my tokens at no less than €0.092 each."*
### 2. Bids Are Sorted by Price (Low to High)
The system ranks all bids from lowest price to highest — those willing to accept the biggest discount come first.
### 3. Clearing Price Is Found
The auction accepts bids from the bottom up (lowest price first) until the total exit amount hits the allowed maximum (e.g., €3 million).
The last bid that fits sets the **clearing price** — everyone who bid at or below this price exits at that same clearing price.
### 4. Settlement
Successful LPs receive their share of the paired token (e.g., USDC or mg Gold). Others can try again in the next round.
---
## Example Scenario
Let's say:
- Max exit allowed this round = €3 million
- There can be other rules too (e.g., minimum price thresholds)
- LPs submit the following bids:
| LP | Amount | Minimum Price |
|----|--------|----------------|
| A | €500k | €0.088 |
| B | €600k | €0.090 |
| C | €400k | €0.092 |
| D | €700k | €0.095 |
| E | €300k | €0.098 |
| F | €200k | €0.100 |
| G | €500k | €0.105 |
| H | €400k | €0.110 |
After sorting from lowest price to highest, we fill bids starting from the bottom. The system stops when total accepted bids reach €3 million.
Suppose this happens at **LP F's bid at €0.100** — that becomes the clearing price.
**Result**: Everyone who bid €0.100 or lower gets filled at €0.100, even if they asked for less.
Bids above €0.100 are not executed.
---
## Margin Redistribution to Pool Members
The margin between what a bidder was willing to accept and the final clearing price is collected by the pool. This value is then redistributed to all liquidity providers who remain in the pool, proportional to their share of the total liquidity.
### Example
- **LP A** bids to exit at €0.088, but the clearing price is €0.100
- The **€0.012 margin per token** is collected by the pool
- This margin is aggregated across all filled bids and shared among the remaining LPs
- **The longer you hold, the more you benefit** when others leave
---
## Why This Works
| Benefit | Description |
|---------|-------------|
| **Fair** | All successful bidders receive the same clearing price |
| **Protective** | Exits only happen with a discount, preventing abuse |
| **Incentivizing** | Remaining LPs gain rewards when others exit |
| **Sustainable** | Controls liquidity outflow with capped exit volume and loss-based exit mechanics |
---
## Key Takeaways
:::tip Market-Driven Fairness
The Dutch auction mechanism ensures that:
- No one can "front-run" or time the market for unfair advantage
- Those most eager to exit subsidize those who stay
- The pool becomes stronger with each exit, not weaker
:::
:::info Protection Mechanisms
- Maximum exit caps prevent pool drainage
- Minimum discounts ensure pool sustainability
- Clearing price mechanism ensures equal treatment
- Margin redistribution rewards patient participants
:::
:::note Related Concepts
This mechanism works hand-in-hand with [Position-Based Liquidity Pools](./position-based-lp.md) to create a fair and sustainable system.
:::

282
docs/core-concepts/liquidity-pools-overview.md
View File

@@ -1,282 +0,0 @@
---
sidebar_position: 1
---
# Liquidity Pools: Simplified Overview
Our ecosystem uses three interconnected liquidity pools to manage the flow of value between tokens and external markets. This page provides a high-level understanding before diving into the detailed mechanics.
:::tip Start Here
If you're new to the system, read this overview first. Then explore the detailed documentation on [Position-Based Pools](/core-concepts/position-based-lp) and [Dutch Auction Exits](/core-concepts/dutch-auction-exit).
:::
---
## The Big Picture: Three Pools
```mermaid
graph TB
subgraph External["External World"]
FIAT[💵 Fiat/USDC]
TFT_MARKET[🌐 TFT Market]
end
subgraph Internal["ThreeFold Ecosystem"]
TFT_LOCKED[🔒 Locked TFT]
CC[💎 Cloud Credits CC]
TFTF[📊 TFT Future TFTF]
POOL1["Pool 1: TFT → CC<br/>(One-Way Entry)"]
POOL2["Pool 2: CC ↔ TFTF<br/>(Internal Trading)"]
POOL3["Pool 3: TFTF ↔ USDC<br/>(Controlled Exit)"]
end
TFT_MARKET -->|Buy TFT| POOL1
POOL1 -->|Lock TFT<br/>Mint CC| CC
CC <-->|Convert| POOL2
POOL2 <-->|Based on TFT price| TFTF
TFTF <-->|Dutch Auction<br/>5% cap, 20% discount| POOL3
POOL3 <-->|Controlled bridge| FIAT
style POOL1 fill:#e1f5ff
style POOL2 fill:#fff4e1
style POOL3 fill:#ffe1e1
```
---
## Your Journey Through the System
### 1. Entry (Pool 1: TFT → CC)
**What it does**: Converts your TFT into stable Cloud Credits
**How it works**:
- You bring TFT (purchased from market or earned from farming)
- TFT gets **locked** (not sold, not converted - just held)
- CC is **minted** at a fixed rate (currently 1 CC for 2 TFT)
- You receive CC to spend on cloud services
**Key point**: This is a **one-way** swap. You can't directly convert CC back to TFT through this pool.
**Example**:
```
You have: 1,000 TFT
You deposit → 1,000 TFT gets locked
You receive → 500 CC (at 2:1 rate)
Your CC is pegged to gold (~$0.128 per CC as of Oct 2024)
```
---
### 2. Internal Movement (Pool 2: CC ↔ TFTF)
**What it does**: Lets you maintain TFT exposure while holding stable CC
**How it works**:
- You earn CC from farming or have CC from services
- You can convert CC to TFTF (TFT Future) based on current TFT market price
- TFTF represents a claim on TFT value without holding actual TFT
- You can convert back to CC when needed
**Key point**: This allows you to **participate in TFT upside** without immediately exiting to fiat.
**Example**:
```
You earned: 500 CC from farming
TFT market price: $0.10
You convert → 500 CC becomes 5,000 TFTF
If TFT rises to $0.15, your TFTF value increases
You can convert back to CC at any time
```
---
### 3. Exit to Fiat (Pool 3: TFTF ↔ USDC)
**What it does**: Provides a controlled bridge to cash out to fiat currency
**How it works**:
- You submit a bid in the Dutch auction: amount + minimum acceptable price
- Bids are sorted from lowest price to highest (most discount to least)
- System fills bids until reaching the monthly cap (e.g., 5% of total liquidity)
- Successful bidders receive USDC at the clearing price
**Key point**: This is **controlled liquidity** - not instant withdrawals. It protects the pool from being drained.
**Example**:
```
You want to exit: 10,000 TFTF (worth ~$1,000)
You're willing to accept: 20% discount minimum
Others bid: 15%, 18%, 22%, 25%, 30%
Clearing price: 22% (your bid gets filled)
You receive: $780 USDC (after 22% discount)
Margin benefit: Goes to remaining pool members
```
---
## Traditional DeFi vs. Our Approach
| Feature | Traditional Liquidity Pools | ThreeFold Position-Based Pools |
|---------|---------------------------|-------------------------------|
| **LP Tokens** | Floating value tokens issued | No tokens - fixed positions tracked |
| **Your Share** | Changes with market volatility | Fixed based on contribution + time |
| **Exit** | Instant (swap LP tokens) | Controlled (Dutch auction) |
| **Impermanent Loss** | Yes - you lose value in volatile markets | No - your position doesn't change |
| **Gaming Risk** | Front-running, sandwich attacks | Protected by time-weighting |
| **Best For** | Active traders | Long-term supporters |
---
## Why Three Pools?
Each pool serves a distinct purpose:
```mermaid
graph LR
A[User Needs] --> B{What do you need?}
B -->|Stable pricing for services| P1[Pool 1: TFT→CC<br/>Get stable credits]
B -->|Keep TFT upside exposure| P2[Pool 2: CC↔TFTF<br/>Maintain position]
B -->|Cash out for operations| P3[Pool 3: TFTF→USDC<br/>Controlled exit]
style P1 fill:#e1f5ff
style P2 fill:#fff4e1
style P3 fill:#ffe1e1
```
### Pool 1: Stability
Gives you predictable pricing for cloud services without exposure to TFT volatility.
### Pool 2: Flexibility
Allows you to move between stable CC and TFT-linked TFTF based on your market outlook.
### Pool 3: Liquidity
Provides real fiat exit when needed, with controls that protect all participants.
---
## Visual Flow: Complete User Journey
```mermaid
graph TD
START([👤 New User]) --> BUY[Buy TFT on Market]
BUY --> ENTER[Enter Pool 1]
ENTER --> LOCKED[TFT Locked + CC Minted]
LOCKED --> USE{How to use CC?}
USE -->|Spend on services| SERVICES[☁️ Use ThreeFold Cloud]
USE -->|Hold as stable value| HOLD[💎 Keep CC]
USE -->|Want TFT exposure| CONVERT[Convert to TFTF in Pool 2]
SERVICES --> BURN[CC Burned by Network]
HOLD --> WAIT[Wait for opportunities]
CONVERT --> TFTF_HOLD[Hold TFTF Position]
TFTF_HOLD --> TFTF_USE{What next?}
TFTF_USE -->|Need stability again| BACK[Back to CC in Pool 2]
TFTF_USE -->|Need fiat| EXIT[Enter Pool 3 Dutch Auction]
EXIT --> BID[Submit bid with discount]
BID --> AUCTION{Bid filled?}
AUCTION -->|Yes| RECEIVE[Receive USDC]
AUCTION -->|No| RETRY[Try next auction round]
BACK --> LOCKED
WAIT --> USE
style START fill:#90EE90
style RECEIVE fill:#90EE90
style BURN fill:#FFB6C1
```
---
## Key Protections Built In
### 1. No Unlimited Dumping
- Exits are capped per period (e.g., max 5% of total liquidity)
- Dutch auction requires accepting a discount
- Protects all participants from sudden value crashes
### 2. Fair Distribution
- Position-based tracking means early supporters aren't diluted
- Time-weighting rewards long-term commitment
- No front-running or gaming the system
### 3. Sustainable Liquidity
- Only 50% of total contributed liquidity can ever exit via Dutch auctions
- Margin from discounts gets redistributed to remaining participants
- System strengthens with each exit, rather than weakening
### 4. Transparency
- All positions are clearly tracked and visible
- Rules are consistent and applied equally
- No hidden fees or complex formulas
---
## Common Questions
<details>
<summary><strong>Can I get my TFT back immediately?</strong></summary>
Not instantly. You need to:
1. Convert CC to TFTF (Pool 2)
2. Exit TFTF via Dutch auction (Pool 3) to USDC
3. Buy TFT on the market with USDC if you want TFT again
The original TFT you deposited is locked to back the CC that was minted.
</details>
<details>
<summary><strong>What if I just want stable income from farming?</strong></summary>
Perfect! Just keep your earnings in CC. You get:
- Stable value (pegged to gold)
- No exposure to TFT market swings
- Ability to convert to TFTF later if you want upside
</details>
<details>
<summary><strong>How do I benefit from TFT price increases?</strong></summary>
Convert your CC to TFTF in Pool 2. TFTF value tracks TFT market price, so if TFT goes up, your TFTF position becomes more valuable in CC or USDC terms.
</details>
<details>
<summary><strong>What happens to the margin from Dutch auctions?</strong></summary>
When someone exits at, say, a 25% discount, that 25% margin is collected and redistributed to all remaining liquidity providers proportionally. The longer you hold, the more you benefit from others exiting.
</details>
<details>
<summary><strong>Is this like Uniswap or Curve?</strong></summary>
Fundamentally different. Traditional AMMs use value-weighted pools with instant liquidity and impermanent loss. We use time-weighted, position-based pools with controlled exits and no impermanent loss. Trade-off: less instant liquidity, more fairness and protection.
</details>
---
## Next Steps
Now that you understand the overall flow, dive deeper:
1. **[Token System](/core-concepts/token-system)** - Understand TFT, CC, and TFTF roles
2. **[Position-Based Liquidity Pools](/core-concepts/position-based-lp)** - Learn why this approach is fair
3. **[Dutch Auction Exit](/core-concepts/dutch-auction-exit)** - See exactly how exits work with examples
4. **[Yin-Yang Currency](/core-concepts/yin-yang-currency)** - The philosophy behind dual tokens
---
:::tip Simplified Summary
- **Pool 1**: Get in (TFT → CC)
- **Pool 2**: Move around (CC ↔ TFTF)
- **Pool 3**: Get out (TFTF → USDC)
All three work together to give you **stability**, **flexibility**, and **controlled liquidity**.
:::

127
docs/core-concepts/position-based-lp.md
View File

@@ -1,127 +0,0 @@
---
sidebar_position: 3
---
# Position-Based Liquidity Pools
## Overview
In traditional DeFi systems, liquidity providers (LPs) are issued **floating LP tokens** that represent their proportional share of a pool's current value. These are known as **value-weighted pools**, where your position fluctuates with market volatility and total pool value.
However, our model uses a **time-weighted, position-based pool** — a fundamentally different approach that prioritizes fairness and long-term contribution over market speculation.
## Key Principles
### 1. Position-Based Accounting
Every liquidity contribution is recorded as a **fixed position**:
- Token type (e.g., USDC, Peaq, TFT)
- Contribution amount (e.g., 1,000 USDC)
- Timestamp (e.g., January 1, 2025)
These positions are tracked permanently and **do not change with price fluctuations**.
### 2. No Floating LP Tokens
- Unlike standard DeFi protocols, we **do not issue LP tokens** that float with pool value
- Users do not gain or lose share based on volatility
- Instead, share is determined by:
- **How much** you contributed
- **How early** you contributed
## Why This Matters
| Feature | Value-Weighted Pools | Time-Weighted, Position-Based Pools |
| ------------------------------- | -------------------- | ----------------------------------- |
| Contribution tracking | Dynamic | Fixed (amount + time) |
| Exposure to volatility | Yes | No |
| Fairness over time | No | Yes |
| Transferable LP tokens | Yes | No |
| Encourages long-term commitment | No | Yes |
| Impermanent loss | Yes | No |
## Implications
### Pros
- **Fair distribution** based on participation, not market timing
- **No front-running or last-minute pool stacking**
- **No impermanent loss** (unlike traditional DeFi pools)
- Encourages **early and stable contributions**
- Aligns incentives with long-term growth, not speculation
### Trade-Offs
- **No instant liquidity switching** between pools
- Internal migrations between pools require **position translation**, not token swaps
- Less suitable for active traders; optimized for committed supporters
## Internal Switching Considerations
Because we track original token amounts and timestamps:
- Users cannot simply "convert" one pool share into another
- Any movement between pools requires:
- Removing the original position from Pool A
- Translating it into an equivalent position in Pool B, preserving contribution integrity
This model behaves more like **vesting or NFT-based positions** than traditional LP tokens.
---
## Value Calculation and Profit Distribution
### How Value is Calculated
Value in this system is calculated using a fundamentally different approach:
- Each liquidity contribution maintains its **original value** rather than floating with market prices
- Your share of the pool is determined by **contribution amount** and **contribution time**
### Profit Distribution When Someone Exits
When liquidity providers exit the pool through the Dutch auction mechanism:
#### Dutch Auction Process
1. LPs submit exit bids with an amount and minimum acceptable price
2. Bids are sorted from lowest price to highest
3. The system fills bids from the bottom up until reaching the maximum allowed exit amount
4. The last accepted bid sets the clearing price for all successful exits
#### Margin Collection
- A discount is defined per pair of tokens (e.g., USDC to TFT)
- When LPs exit, they receive the agreed amount minus this discount
- The collected margin (the discount amount) is pooled together
#### Profit Distribution
- Collected margins are redistributed to all **remaining liquidity providers**
- Distribution is proportional to each LP's share of the total liquidity
- **The longer you hold, the more you benefit** when others leave
#### Exit Protections
- Only up to 50% of total liquidity ever contributed (minus past exits) can leave through Dutch auctions
- This cap protects the pool from being drained
---
## Summary
Our system is built on **time-weighted, position-based liquidity** — not market-weighted value shares. This ensures that:
- All participants are rewarded based on **what** they contributed and **when**
- Not how the market fluctuates afterward
It's a principled approach for long-term alignment, fair participation, and stable tokenomics.
:::info Virtuous Cycle
This creates a virtuous cycle where early and committed participants are rewarded, while the pool remains protected from being drained by opportunistic withdrawals.
:::
:::tip Learn More
See how exits work in practice with the [Dutch Auction Exit Mechanism](./dutch-auction-exit.md).
:::

104
docs/core-concepts/yin-yang-currency.md
View File

@@ -1,104 +0,0 @@
---
sidebar_position: 5
---
# Yin vs. Yang Currencies
Our token system is philosophically rooted in economist Bernard Lietaer's concept of complementary currencies. Understanding this framework helps explain why we use both TFT and Cloud Credits.
## Currency Philosophies
### Yang Currencies
- **Nature**: Conventional, national currencies (e.g., dollar, euro, yen)
- **Creation**: Centralized, can be fair-launched or created by a centralized authority
- **Characteristics**: Promote **competition**, **scarcity**, **hierarchy**, and **analytical or linear thinking**
- **Strengths**: Efficient for global trade and industrial economic activities
- **Limitations**: Relying solely on Yang currencies fosters fragility, social isolation, and volatility
### Yin Currencies
- **Nature**: Complementary or community currencies (e.g., barter systems, time banking, trade credits, caring relationship tickets)
- **Creation**: Decentralized, often **mutual credit systems** created by participants themselves
- **Foundation**: Rely on **community trust** rather than a central issuer
- **Characteristics**: Foster **cooperation**, **egalitarian relationships**, **quality of life**, **sustainability**, and **social trust**
- **Environment**: Thrive within **bounded communities**, where circulation and reciprocity reinforce social cohesion
---
## Why Both Matter: The Complementarity
Lietaer doesn't present Yin and Yang currencies as antagonistic — but as **complementary tools**, each serving distinct purposes:
- Societies that incorporate both systems, **dual currency systems**, are typically more **resilient**, **socially robust**, and thrive economically
### Real-World Examples
#### Bali's Dual System
- **National (Yang) currency**: Used for wider commerce
- **Community-based Yin currency**: *narayan banjar* (based on hours of service)
- **Impact**: Empowers communal projects and mutual support
- **Scale**: About **30% of adult life** in Bali occurs in this Yin economy, reinforcing trust and collective well-being
#### Japan's Care Economy
- **System**: Complementary Yin currencies reward caregiving
- **Function**: Caring-for-elderly credits can be used for university tuition
- **Result**: Solves multiple community needs through alternative value systems
---
## Lietaer's Integral Economy Vision
Lietaer's broader vision forms part of his **"Integral Economy"**: a balanced system where:
- **Financial capital (Yang)** and **social capital (Yin)** coexist harmoniously
- **Goal**: Foster **integral wealth** — not just material accumulation, but also community, natural, and social well-being
---
## Summary Table
| Feature | Yang Currency | Yin Currency |
| ------------------- | -------------------------------------------------- | --------------------------------------------- |
| **Creation** | Central authority, fiat | Mutual credit, community-based |
| **Focus** | Liquidity, scarcity, hierarchy | Cooperation, mutual credit |
| **Use Case** | Trade, blockchain, investment, liquidity providing | Mutual credit, services, exchange of capacity |
| **Examples** | USD, EUR, JPY, TFT | Time banking, cloud computing capacity, CC |
| **Role in Society** | Efficiency & growth of capital | Builds trust and resilience alongside Yang |
---
## Application to ThreeFold
In our system:
- **TFT (Yang)**: Tradable, scarce, subject to market forces, provides investment opportunity
- **CC (Yin)**: Stable, community-focused, promotes cooperation, enables predictable service exchange
This dual structure aims to:
- Preserve market efficiency and investment potential (Yang)
- Enable stable, community-oriented value exchange (Yin)
- Create resilience through complementarity
- Balance speculation with sustainability
---
## Final Thoughts
Bernard Lietaer's Yin-Yang currency model invites us to **rethink our relationship with money**. By blending **efficiency and competitiveness** (Yang) with **cooperation and scarcity-healing systems** (Yin), communities can cultivate greater **resilience, trust, and sustainable abundance**.
:::info Philosophy in Practice
Our dual-token system isn't just about technical mechanics — it's about creating an economy that serves both market efficiency and community well-being.
:::
---
## References
- [The Yin and Yang of Money: Complementary Currencies](https://baritessler.com/2009/05/yin-and-yang-currency/)
- [The Yin and yang of currency](https://syntropic.world/the-yin-and-yang-of-currency/)
- [Bernard Lietaer, Visionary Economist](https://www.rozsavage.com/bernard-lietaer-visionary-economist/)
- [Of Human Wealth - Bernard Lietaer](https://bernard-lietaer.org/wp-content/uploads/2022/07/2004-Of-Human-Wealth-Beyond-Greed-Scarcity-Lieater-Belgin-annotated.pdf)
- [Interview with Bernard Lietaer -- Money, Community & Social ...](https://uazu.net/money/lietaer.html)
- [THE FUTURE OF MONEY - Bernard A. Lietaer](https://library.uniteddiversity.coop/Money_and_Economics/The_Future_of_Money-Bernard_Lietaer.pdf)
- [Trade: The Yin Currency I Love to Use](https://baritessler.com/2017/07/trade-yin-currency-love-use/)