Skip to content

fix: add docs for TFT billing price on TFChain #849

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mik-tf wants to merge 1 commit into
base: development
Choose a base branch
from
Open

fix: add docs for TFT billing price on TFChain #849

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions labs/docs/knowledge_base/cloud_toc/pricing_toc/grid_billing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,67 @@ TFT price can be retrieved directly through [Stellar](https://stellar.expert/exp

![](./img/grid_billing_1.png)

### TFT Billing Price on TFChain

The TFT price used for on-chain billing is **not** the raw market price. Instead, TFChain applies a **billing price**: the market-derived average price clamped within council-defined minimum and maximum bounds. This prevents extreme market volatility from causing unpredictable costs for users or unfair compensation for farmers.

#### Market Price vs Billing Price

TFT has two distinct prices, each used for a different purpose:

- **Market price**: The real trading value of TFT on exchanges. Used for buying, selling, swapping, and displaying TFT value in fiat.
- **Billing price**: The value of TFT used internally by TFChain to calculate resource costs and contract billing. Derived from the market price but clamped to council-defined bounds.

#### Why This Matters

The clamping mechanism protects both users and farmers from extreme market swings. Consider a workload that costs 100 mUSD/hour:

**When market price is below the floor** (protects users):

- Market price = 5 mUSD per TFT, but the floor is 10 mUSD
- Billing price becomes 10 mUSD per TFT
- On-chain cost: `100 / 10 = 10 TFT/hour` instead of `100 / 5 = 20 TFT/hour`
- The user pays **fewer TFT** than the market price would suggest

**When market price is above the ceiling** (protects farmers):

- Market price = 1500 mUSD per TFT, but the ceiling is 1000 mUSD
- Billing price becomes 1000 mUSD per TFT
- On-chain cost: `100 / 1000 = 0.1 TFT/hour` instead of `100 / 1500 = 0.067 TFT/hour`
- The farmer receives **more TFT** than the market price would suggest

Grid tooling (e.g. the grid client and calculator) has been updated to use the billing price for cost estimations, matching the actual on-chain billing logic.

#### How It Works

Three values stored on TFChain govern this mechanism. All values are expressed in **mUSD (millionths of USD)**:

| Parameter | Description | Current Value |
| --- | --- | --- |
| `MinTftPrice` | Floor billing price | 10 mUSD (0.01 USD) |
| `MaxTftPrice` | Ceiling billing price | 1000 mUSD (1.00 USD) |
| `AverageTftPrice` | Market-derived average price | Varies |

The billing price is calculated by clamping the average market price to the configured bounds:

```
BillingPrice = max(MinTftPrice, min(AverageTftPrice, MaxTftPrice))
```

- If the market price drops below `MinTftPrice`, the billing price uses the **minimum** (floor).
- If the market price rises above `MaxTftPrice`, the billing price uses the **maximum** (ceiling).
- Otherwise, the actual average market price is used as-is.

#### Querying the Current Values

These values can be queried from TFChain using the [Polkadot UI](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.grid.tf#/chainstate):

1. Go to the **Chain State** page
2. Select `tftPriceModule` as the **selected state query**
3. Query `minTftPrice`, `maxTftPrice`, and `averageTftPrice` to see the current on-chain values

> **Note:** The min and max bounds are set by the TFChain council and can be updated through governance. Always query the current values rather than relying on the defaults listed above.

### Current Cloud Units Values

The current cloud units values can be retrieved directly from TChain with the [Polkadot UI](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.grid.tf#/chainstate) and the current chain state.
Expand Down