From 06c2e41133f90abb182f37627519474dc64851c8 Mon Sep 17 00:00:00 2001 From: Max Date: Tue, 16 Jun 2026 16:28:05 +0100 Subject: [PATCH 1/8] docs: add T7 storage credit guidance --- src/components/StorageSavingsExplorer.tsx | 222 ++++++++++++++++++ .../guide/issuance/distribute-rewards.mdx | 4 + .../docs/guide/machine-payments/index.mdx | 1 + .../guide/machine-payments/pay-as-you-go.mdx | 4 + .../stablecoin-dex/providing-liquidity.mdx | 4 + src/pages/docs/guide/t7-storage-credits.mdx | 146 ++++++++++++ .../protocol/exchange/providing-liquidity.mdx | 4 + src/pages/docs/protocol/fees/index.mdx | 6 +- .../docs/protocol/tip20-rewards/overview.mdx | 4 + .../docs/protocol/tip20-rewards/spec.mdx | 4 + src/pages/docs/protocol/upgrades/t7.mdx | 121 ++++++++-- vocs.config.ts | 4 + 12 files changed, 499 insertions(+), 25 deletions(-) create mode 100644 src/components/StorageSavingsExplorer.tsx create mode 100644 src/pages/docs/guide/t7-storage-credits.mdx diff --git a/src/components/StorageSavingsExplorer.tsx b/src/components/StorageSavingsExplorer.tsx new file mode 100644 index 00000000..3fdd9d9c --- /dev/null +++ b/src/components/StorageSavingsExplorer.tsx @@ -0,0 +1,222 @@ +'use client' + +import * as React from 'react' +import { Container } from './Container' + +type Scenario = { + id: string + label: string + description: string + earnLabel: string + earnBefore: number + earnAfter: number + reuseLabel: string + reuseBefore: number + reuseAfter: number +} + +const SCENARIOS: Scenario[] = [ + { + id: 'cancel', + label: 'Order is canceled', + description: + 'The maker cancels an eligible order, then returns later to place another eligible order.', + earnLabel: 'Cancel bid, earn reusable savings', + earnBefore: 304_741, + earnAfter: 361_184, + reuseLabel: 'Same maker reuses savings after cancel', + reuseBefore: 2_075_413, + reuseAfter: 868_756, + }, + { + id: 'full-fill', + label: 'Order is fully filled', + description: + 'An eligible order is fully filled, then the same maker returns later with another eligible order.', + earnLabel: 'Full fill, earn reusable savings', + earnBefore: 384_497, + earnAfter: 436_040, + reuseLabel: 'Same maker reuses savings after full fill', + reuseBefore: 1_828_213, + reuseAfter: 621_456, + }, +] + +const numberFormat = new Intl.NumberFormat('en-US') +const percentFormat = new Intl.NumberFormat('en-US', { + maximumFractionDigits: 1, +}) + +function formatGas(value: number) { + return `${numberFormat.format(value)} gas` +} + +function formatSignedGas(value: number) { + const sign = value > 0 ? '+' : value < 0 ? '-' : '' + return `${sign}${formatGas(Math.abs(value))}` +} + +function formatSavings(value: number) { + if (value > 0) return `${formatGas(value)} saved` + if (value < 0) return `${formatGas(Math.abs(value))} more` + return 'No gas change' +} + +function formatPercent(value: number) { + const sign = value > 0 ? '+' : value < 0 ? '-' : '' + return `${sign}${percentFormat.format(Math.abs(value))}%` +} + +function changePercent(before: number, after: number) { + return ((after - before) / before) * 100 +} + +export function StorageSavingsExplorer() { + const [scenarioId, setScenarioId] = React.useState(SCENARIOS[0].id) + const [repeatOrders, setRepeatOrders] = React.useState(1) + const scenario = SCENARIOS.find((item) => item.id === scenarioId) ?? SCENARIOS[0] + + const earningCost = scenario.earnAfter - scenario.earnBefore + const reuseSavings = scenario.reuseBefore - scenario.reuseAfter + const beforeTotal = scenario.earnBefore + scenario.reuseBefore * repeatOrders + const afterTotal = scenario.earnAfter + scenario.reuseAfter * repeatOrders + const netSavings = beforeTotal - afterTotal + const netPercent = changePercent(beforeTotal, afterTotal) + const breaksEven = reuseSavings > earningCost + const updateRepeatOrders = (value: number) => { + setRepeatOrders(Math.min(10, Math.max(1, value))) + } + + return ( + + Storage savings explorer + + } + footer={ + + Uses the merged DEX benchmark in{' '} + tempoxyz/tempo#5903. These + numbers are for the StablecoinDEX benchmark only. + + } + > +
+
+

+ Pick the lifecycle that earns a storage saving, then choose how many later eligible + orders the same maker places. +

+ +
+ Storage lifecycle + {SCENARIOS.map((item) => { + const active = item.id === scenario.id + return ( + + ) + })} +
+
+ +
+
+ Later eligible orders by the same maker + + + {repeatOrders} + + +
+ updateRepeatOrders(Number(event.currentTarget.value))} + onInput={(event) => updateRepeatOrders(Number(event.currentTarget.value))} + className="w-full accent-gray12" + /> +
+ +
+
+
Benchmark impact
+ +
+ {scenario.earnLabel} + + {formatSignedGas(earningCost)} ( + {formatPercent(changePercent(scenario.earnBefore, scenario.earnAfter))}) + + {scenario.reuseLabel} + + {formatSavings(reuseSavings)} ( + {formatPercent(changePercent(scenario.reuseBefore, scenario.reuseAfter))}) + + Net over this lifecycle + + {formatSavings(netSavings)} ({formatPercent(netPercent)}) + +
+
+ +
+
Who should get the saving?
+ +
    +
  1. Alice clears eligible order storage and earns reusable savings.
    2. +
  2. Bob places an order later, but does not spend Alice's savings.
    3. +
  3. Alice returns and can use the savings she earned.
    4. +
+
+
+ +
+ {breaksEven ? ( +

+ In this benchmark, one later eligible order is enough to outweigh the extra gas paid + when the DEX records who earned the reusable savings. +

+ ) : ( +

+ This lifecycle needs more repeat usage before the reusable savings outweigh the + upfront accounting cost. +

+ )} +
+
+ + ) +} diff --git a/src/pages/docs/guide/issuance/distribute-rewards.mdx b/src/pages/docs/guide/issuance/distribute-rewards.mdx index f00146de..c1dc9c5e 100644 --- a/src/pages/docs/guide/issuance/distribute-rewards.mdx +++ b/src/pages/docs/guide/issuance/distribute-rewards.mdx @@ -16,6 +16,10 @@ import { Cards, Card } from 'vocs' # Distribute Rewards +:::warning[Rewards deprecation planned] +This change is planned for testnet on July 2, 2026 and mainnet on July 9, 2026. After activation, new Tempo Token Rewards opt-ins and distributions become no-ops. Already-accrued rewards remain claimable through the existing `claimRewards()` flow. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full timeline and scope. +::: + Distribute rewards to token holders using TIP-20's built-in reward distribution mechanism. Rewards allow parties to incentivize holders of a token by distributing tokens proportionally based on their balance. Rewards can be distributed by anyone on any TIP-20 token, and claimed by any holder who has opted in. This guide covers both the reward distributor and token holder use cases. While the demo below uses a token you create, the same principles apply to any token. diff --git a/src/pages/docs/guide/machine-payments/index.mdx b/src/pages/docs/guide/machine-payments/index.mdx index 010aab53..91418ffb 100644 --- a/src/pages/docs/guide/machine-payments/index.mdx +++ b/src/pages/docs/guide/machine-payments/index.mdx @@ -46,6 +46,7 @@ Tempo's transaction model is designed for agentic payments using MPP: - **~500ms finality** — Deterministic confirmation fast enough for synchronous request/response flows - **Sub-cent fees** — Low enough for micropayments and per-request billing +- **Lower repeated channel lifecycle costs** — The planned T7 upgrade adds payer-scoped storage credits for MPP payment channels, helping repeated session lifecycles reuse channel-state savings - **Fee sponsorship** — Servers can cover gas on behalf of clients so they only need stablecoins - **2D and expiring nonces** — Parallel nonce lanes prevent payment transactions from blocking other account activity - **High throughput** — Supports the on-chain settlement volume that payment channels generate at scale diff --git a/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx b/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx index ed0cb15c..c797afdf 100644 --- a/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx +++ b/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx @@ -14,6 +14,10 @@ Build a payment-gated photo gallery API that charges $0.01 per photo using `mppx Unlike [one-time payments](/docs/guide/machine-payments/one-time-payments), sessions open a payment channel once and use off-chain vouchers for each subsequent request — vouchers are processed in pure CPU-bound signature checks, not bottlenecked by blockchain throughput. ::: +:::info[T7 payment-channel savings] +The [T7 network upgrade](/docs/protocol/upgrades/t7) adds payer-scoped storage credits for MPP payment channels. When a payer closes or withdraws a finished channel, the reserve can record a channel storage credit for that payer. If the same payer opens another channel later, that payer can reuse the credit. Other payers cannot spend it. +::: + ## How sessions work diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx new file mode 100644 index 00000000..d5707bee --- /dev/null +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -0,0 +1,146 @@ +--- +title: Storage Savings to Benefit Your Users +description: Learn how shared contracts can use storage savings to benefit the users who earned them. +interactive: true +--- + +import { StorageSavingsExplorer } from '../../../components/StorageSavingsExplorer' + +# Storage Savings to Benefit Your Users + +Storage credits are a network feature for contracts that create storage, clear it, and later create storage again in the same contract. The benefit is strongest for repeat workflows with temporary state, such as DEX orders. + +For partners, the important question is not just "can my contract earn a storage credit?" It is "how should I allocate the storage credits to benefit my users fairly?" + +:::info[Feature status] +Storage credits are part of the T7 network upgrade: testnet rollout is planned for July 2, 2026, and mainnet rollout is planned for July 9, 2026. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full scope and release details. +::: + +## DEX benchmark example + +The DEX benchmark shows why user-level allocation matters. Fresh order placement stays effectively unchanged, while same-maker reuse becomes much cheaper in the measured lifecycle. + +| Flow | Before | After | Gas change | +|---|---:|---:|---:| +| Fresh place bid | 2,595,385 | 2,604,066 | +8,681 (+0.3%) | +| Fresh place ask | 2,348,185 | 2,356,766 | +8,581 (+0.4%) | +| Cancel bid, earn reusable savings | 304,741 | 361,184 | +56,443 (+18.5%) | +| **Same maker reuses savings after cancel** | **2,075,413** | **868,756** | **1,206,657 gas saved (-58.1%)** | +| Full fill, earn reusable savings | 384,497 | 436,040 | +51,543 (+13.4%) | +| **Same maker reuses savings after full fill** | **1,828,213** | **621,456** | **1,206,757 gas saved (-66.0%)** | + +Fresh wallet flows are effectively unchanged. The credit-earning steps cost more because the DEX records who earned the reusable savings. The benefit appears when the same maker later places another eligible order: the repeat order is about 1.21M gas cheaper. + +## Explore the savings pattern + + + +The explorer uses the merged StablecoinDEX benchmark numbers because that is the clearest verified example today. Use it to understand the pattern, then benchmark the specific partner flow before making claims for a bridge, vault, routing contract, or other shared system. + +## How storage credits work + +The storage credit primitive gives an account a storage credit when it clears one of its own storage slots. Later, that same account can use the credit to reduce the gas cost of creating storage again. + +In simple terms: + +1. A contract creates storage. +2. The contract later clears that storage. +3. The network records a storage credit for that contract. +4. The contract can use that credit to reduce gas for a future storage creation. + +This is useful when storage is temporary rather than permanent. A one-time storage write is different from a repeated create, clear, and recreate pattern. + +## Why shared contracts need allocation + +Storage credits belong to the account that owns the storage. For shared contracts, that usually means the contract earns the credit, not the end user automatically. + +That creates an allocation problem. + +For example: + +1. Alice places and later cancels an order. +2. The DEX clears Alice's order storage and earns a storage credit. +3. Bob places a new order later. +4. Without user-level accounting, Bob could receive the benefit from storage Alice cleared. + +Contracts that serve many users should add their own accounting layer when credits need to stay attached to a specific user, payer, maker, or account. + +## Pattern: credit the user who cleared state + +The DEX implementation applies this idea to the StablecoinDEX. + +Instead of treating all DEX storage credits as one shared pool, the DEX tracks which maker earned reusable order-storage savings. When that same maker later creates eligible order storage, the DEX can apply that maker's savings. + +Technically, [TIP-1064](https://tips.sh/1064) applies this allocation pattern to the StablecoinDEX on top of [TIP-1060](https://tips.sh/1060), the contract storage credits primitive. + +| Event | Result | +|---|---| +| Maker cancels an eligible order | The DEX clears order storage and records reusable savings for that maker | +| Maker's order is fully filled | The DEX clears order storage and records reusable savings for that maker | +| Same maker places a later eligible order | The DEX can apply that maker's savings | +| Different maker places an order | They do not consume savings they did not earn | + +Use this pattern for shared contracts: + +1. Identify which storage is clearly attributable to one user. +2. Credit that user when the contract clears that storage. +3. Spend that user's credits only when the same user creates eligible storage later. +4. Keep shared accounting storage separate from user-attributed storage. + +## Prevent cross-user leakage + +User-level allocation prevents one user's savings from being spent by another user. + +| Case | Expected behavior | +|---|---| +| Same maker returns after earning savings | Apply that maker's stored savings to an eligible order | +| Different maker places the next order | Do not spend the first maker's savings | +| Shared internal accounting is cleared | Do not assign the saving to whichever user happened to trigger cleanup | + +The DEX benchmark includes cross-user isolation tests to prove this behavior, but the partner-facing rule is simpler: savings earned by Alice should stay available to Alice, and Bob should pay the normal cost unless Bob earned savings too. + +## When to use this pattern + +Use this pattern when the same user, payer, maker, or account has a repeated lifecycle: + +1. The contract creates temporary storage for that user. +2. The contract later clears that storage. +3. The same user is likely to create storage again through the same contract. +4. The contract can track that user's credits without mixing them with unrelated users. + +For bridge, vault, routing, and other shared-contract flows, benchmark the specific workflow before making partner-facing claims. Do not reuse DEX numbers for a different contract shape. + +## Partner checklist + +When deciding whether a contract can benefit from storage credits, check: + +1. Does the contract create storage during the user flow? +2. Does the contract later clear that storage? +3. Is the cleared storage attributable to one user, payer, order owner, or account? +4. Does the same user later create eligible storage again? +5. Can the contract track credits per user instead of sharing all credits globally? +6. Are there shared internal accounting slots that should not be credited to any one user? +7. Do gas estimates differ between first-time usage and repeated usage? +8. Do benchmarks include cross-user cases to make sure credits do not leak? +9. Are the numbers from a merged benchmark or a partner-specific test, rather than a draft confidence check? + +## What not to assume + +Storage credits are not a blanket gas discount. + +Do not assume: + +- Every transaction gets cheaper. +- First-time users receive the same savings as repeat users. +- Contract-level credits automatically map to the right end user. +- Shared accounting storage should be credited to whichever user happened to trigger the cleanup. +- DEX benchmark numbers apply to bridge, vault, or routing contracts without testing those workflows separately. + +## Related pages + +- [T7 network upgrade](/docs/protocol/upgrades/t7) +- [Providing Liquidity](/docs/protocol/exchange/providing-liquidity) +- [Stablecoin DEX Specification](/docs/protocol/exchange/spec) +- [Contract storage credits proposal (TIP-1060)](https://tips.sh/1060) +- [StablecoinDEX order storage credits proposal (TIP-1064)](https://tips.sh/1064) +- [Merged DEX benchmark](https://github.com/tempoxyz/tempo/pull/5903) diff --git a/src/pages/docs/protocol/exchange/providing-liquidity.mdx b/src/pages/docs/protocol/exchange/providing-liquidity.mdx index a16d447e..2d5de509 100644 --- a/src/pages/docs/protocol/exchange/providing-liquidity.mdx +++ b/src/pages/docs/protocol/exchange/providing-liquidity.mdx @@ -16,6 +16,10 @@ The DEX uses an onchain orderbook where you can place orders at specific price t Unlike traditional AMMs, you specify exact prices where you want to buy or sell, giving you more precise control over your liquidity provision strategy. +:::info[Storage credits for DEX makers] +Storage credits can reduce gas for active DEX makers who repeatedly place, cancel, or fully fill eligible orders. See [Storage Savings to Benefit Your Users](/docs/guide/t7-storage-credits) for the allocation pattern and benchmark examples. +::: + ## Order Types ### Limit Orders diff --git a/src/pages/docs/protocol/fees/index.mdx b/src/pages/docs/protocol/fees/index.mdx index a309d0d3..d1dd2fac 100644 --- a/src/pages/docs/protocol/fees/index.mdx +++ b/src/pages/docs/protocol/fees/index.mdx @@ -10,7 +10,11 @@ Tempo has no native token. Instead, transaction fees—including both gas fees a For a stablecoin to be accepted, it must be USD-denominated, issued as a native TIP-20 contract, and have sufficient liquidity on the native Fee AMM. -Tempo uses a fixed base fee (rather than a variable base fee as in EIP-1559), set so that a TIP-20 transfer costs less than $0.001. All fees accrue to the validator who proposes the block. +Tempo currently uses a fixed base fee (rather than a variable base fee as in EIP-1559), set so that a TIP-20 transfer costs less than $0.001. All fees accrue to the validator who proposes the block. + +:::info[Dynamic base fee] +A dynamic base fee can fall when block gas usage is below target and rise back to the cap when the network is busy. See the [T7 network upgrade](/docs/protocol/upgrades/t7) and [dynamic base fee proposal](https://tips.sh/1067-1). +::: ## Learn More diff --git a/src/pages/docs/protocol/tip20-rewards/overview.mdx b/src/pages/docs/protocol/tip20-rewards/overview.mdx index 07684311..e4de42cf 100644 --- a/src/pages/docs/protocol/tip20-rewards/overview.mdx +++ b/src/pages/docs/protocol/tip20-rewards/overview.mdx @@ -6,6 +6,10 @@ import { Cards, Card } from 'vocs' # Tempo Token Rewards +:::warning[Tempo Token Rewards cleanup planned] +This change is planned for testnet on July 2, 2026 and mainnet on July 9, 2026. After activation, new Tempo Token Rewards opt-ins and distributions become no-ops. Already-accrued rewards remain claimable through the existing `claimRewards()` flow. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full timeline and scope. +::: + Tempo Token Rewards is a built-in mechanism that allows for efficient distribution of rewards to opted-in token holders proportional to their holdings, while maintaining low gas costs at scale and complying with [TIP-403 transfer policies](/docs/protocol/tip403/spec). Traditional reward mechanisms require tokens to be staked in separate contracts, which fragments user holdings and adds complexity to wallet implementations. Tempo Token Rewards solves this by: diff --git a/src/pages/docs/protocol/tip20-rewards/spec.mdx b/src/pages/docs/protocol/tip20-rewards/spec.mdx index e90275fd..c0312bc5 100644 --- a/src/pages/docs/protocol/tip20-rewards/spec.mdx +++ b/src/pages/docs/protocol/tip20-rewards/spec.mdx @@ -4,6 +4,10 @@ description: Technical specification for Tempo Token Rewards using reward-per-to # Tempo Token Rewards Specification +:::warning[Tempo Token Rewards cleanup planned] +This change is planned for testnet on July 2, 2026 and mainnet on July 9, 2026. After activation, new reward opt-ins and new reward distributions become no-ops. Already-accrued rewards remain claimable through the existing `claimRewards()` flow. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full timeline and scope. +::: + ## Abstract An opt-in, scalable, pro-rata reward distribution mechanism built into TIP-20 tokens. The system uses a "reward-per-token" accumulator pattern to distribute rewards proportionally to opted-in holders without requiring staking or per-holder iteration. Rewards are distributed instantly; time-based streaming distributions are planned for a future upgrade. diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 638b56d6..84c0927a 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -1,11 +1,13 @@ --- title: T7 Network Upgrade -description: Partner-focused overview and rollout dates for the T7 network upgrade, including storage credits, dynamic base fee behavior, and TIP-20 rewards deprecation. +description: Partner-focused overview and rollout dates for the T7 network upgrade, including storage savings, payment-channel savings, dynamic base fee behavior, and TIP-20 rewards deprecation. --- # T7 Network Upgrade -T7 gives partners a clearer fee model for high-volume payment and exchange flows. It adds storage credits for reusable DEX order and TIP-20 channel state, makes the base fee move down when network usage is below the target threshold, and deprecates new TIP-20 rewards. +T7 makes repeated onchain workflows cheaper and gives partners a clearer fee story for payment and exchange flows. It adds storage savings for DEX order state and TIP-20 payment-channel state, lets the base fee move down when network usage is low, and deprecates new TIP-20 rewards activity. + +For partners, the headline is simple: apps with repeat contract workflows can pass meaningful gas savings to returning users, MPP sessions can reuse channel-state savings for the same payer, and all users can benefit from lower base fees during quieter network periods. :::info[T7 status] Release [v1.10.1](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) is required for T7. See the [Network Upgrades and Releases table](/docs/guide/node/network-upgrades#node-operator-updates) for the current node-operator release status. @@ -22,41 +24,103 @@ Node operators should upgrade to [v1.10.1](https://github.com/tempoxyz/tempo/rel ## Overview -T7 focuses on three partner needs: +T7 focuses on five partner-facing changes: + +- **Reusable storage savings.** Contracts that create storage, clear it, and later create storage again in the same contract can lower the cost of the next eligible storage write. +- **Savings tied to the right user.** Shared systems such as the StablecoinDEX can keep those savings attached to the maker who earned them, instead of letting the next user spend them by accident. +- **Payment-channel savings.** MPP payment channels can keep storage credits attached to the payer who earned them, so repeated session lifecycles can reuse channel-state savings. +- **Lower fees during quiet periods.** The base fee can fall when block gas usage is below the target threshold. +- **Rewards cleanup.** New Tempo Token Rewards opt-ins and distributions stop after activation, while already-accrued rewards remain claimable. + +These changes make costs easier to reason about for partners building high-throughput payment, liquidity, and exchange experiences. The main opportunity is to identify workflows with temporary state and decide whether the contract should allocate storage-credit savings per user, payer, maker, or account. -- **Lower fees for reusable protocol state.** Storage credits reduce fees when previously freed protocol storage can be reused, including DEX order storage and TIP-20 channel storage. -- **A more responsive base fee.** Dynamic base fee behavior lowers the base fee when gas usage is below the target threshold. -- **A simpler TIP-20 rewards model.** Deprecating new TIP-20 rewards simplifies reward-related accounting and user-facing balances. +## Why it matters -These changes are designed to make costs easier to reason about for partners building high-throughput payment, liquidity, and exchange experiences. Storage credits and dynamic base fee behavior affect fee calculations, while existing TIP-20 transfer behavior and claims for already-accrued rewards continue to work. +| Partner impact | What changes | +|----------------|--------------| +| Active DEX makers can pay much less on repeat order placement | In the merged DEX benchmark, same-maker reuse is about 1.21M gas cheaper after a cancel or full fill. | +| Returning users can benefit without first-time flows getting worse | Fresh DEX order placement changes by less than 0.5% in the measured bid and ask flows. | +| Apps can avoid random gas discounts | Shared contracts can track which user earned credits and spend them only for that same user. | +| MPP sessions can get cheaper over repeated channel lifecycles | Payment-channel credits stay scoped to the payer who closed or withdrew a channel, then can be reused when that payer opens a later channel. | +| All integrators get a simpler low-fee story | The new base fee cap is 40% lower than today's fixed base fee, and quiet periods can be up to 20x cheaper than the cap. | ## Features -### Storage credits for reusable protocol state +### Reusable storage savings + +Storage credits lower fees for workflows that repeatedly create and clear temporary storage. A contract earns a credit when it clears eligible storage, then can use that credit to reduce the cost of creating eligible storage later. + +This is not a blanket gas discount. It matters most when a workflow has a natural lifecycle: create state, clear it, then create more state in the same contract. + +### User-attributed DEX savings -Storage credits lower fees for protocol surfaces where deleted storage can later be reused. This helps reduce the cost of flows where the network can account for reusable state separately from net-new long-lived state. +The StablecoinDEX uses the same storage-credit idea but adds maker-level accounting. If a maker cancels or fully fills an eligible order, the DEX can keep the reusable order-storage savings attached to that maker. When the same maker places a later eligible order, the DEX can apply those savings. -| TIP | Scope | -|-----|-------| -| [TIP-1060: Storage Credits](https://tips.sh/1060) | Core storage credits primitive | -| [TIP-1064: StablecoinDEX Order Storage Credits](https://tips.sh/1064) | Storage credits for DEX order storage | -| [TIP-1066: TIP-20 Channel Storage Credits](https://tips.sh/1066) | Storage credits for TIP-20 channel state | +Read [Storage Savings to Benefit Your Users](/docs/guide/t7-storage-credits) for the allocation pattern, interactive example, and DEX benchmark. + +### Payer-scoped payment-channel savings + +T7 applies the storage-credit pattern to MPP payment channels through the `TIP20ChannelReserve` precompile. When a payer closes or withdraws a finished channel, the reserve can record a channel storage credit for that payer. When the same payer opens a later channel, the reserve can use that payer's credit. + +This keeps channel savings attached to the payer who earned them. A different payer cannot spend another payer's channel credit. + +For MPP partners, the benefit is focused on repeated session lifecycles. Per-request vouchers already stay off-chain; T7 can lower the net onchain lifecycle cost when a close or withdraw is followed by a later open from the same payer. + +Read [Accept pay-as-you-go payments](/docs/guide/machine-payments/pay-as-you-go) for the MPP session flow. ### Dynamic base fee -Dynamic base fee behavior lets the base fee move down when gas usage is below the target threshold. This gives wallets, apps, and infrastructure a fee model that can respond to lower network usage instead of assuming a fixed base fee. +T7 replaces the fixed base fee with a bounded dynamic base fee. The new cap is 40% lower than the current fixed fee. When block gas usage is below target, the base fee can fall toward a floor that is one twentieth of the cap. + +For a simple fee example, a 50,000 gas transfer costs about $0.0006 at the new cap and about $0.00003 at the floor. -| TIP | Scope | -|-----|-------| -| [TIP-1067: Dynamic Base Fee](https://tips.sh/1067-1) | Dynamic base fee behavior | +| Example transaction | Today's fixed fee | T7 cap | T7 quiet-period floor | +|---------------------|------------------:|-------:|----------------------:| +| 50,000 gas transfer | $0.0010 | $0.0006 | $0.00003 | +| 1,000,000 gas transaction | $0.0200 | $0.0120 | $0.0006 | + +At the quiet-period floor, the same transaction is 20x cheaper than the T7 cap and about 33x cheaper than today's fixed fee. The base fee starts at the cap at activation and moves with block usage. ### Deprecate TIP-20 rewards -T7 deprecates new TIP-20 reward opt-ins and reward distributions so partners do not need to model new reward accrual after the upgrade. Already-accrued rewards remain claimable, so historical rewards data should remain separate from post-T7 payment and balance reporting. +T7 deprecates new Tempo Token Rewards opt-ins and reward distributions so partners do not need to model new reward accrual after the upgrade. Already-accrued rewards remain claimable through the existing `claimRewards()` flow. + +Apps that show reward information should keep already-accrued rewards separate from post-T7 balances, and should stop presenting new rewards as accruing from post-T7 reward distributions. See [Tempo Token Rewards](/docs/protocol/tip20-rewards/overview) if your integration still uses rewards. + +## Technical references + +| Feature | What changes | Reference | +|---------|--------------|-----------| +| Reusable storage savings | Contracts can earn credits when they clear eligible storage and use those credits to lower later storage-creation gas | [TIP-1060: Storage Credits](https://tips.sh/1060) | +| User-attributed DEX savings | The DEX can keep reusable order-storage credits attached to the maker who earned them | [TIP-1064: StablecoinDEX Order Storage Credits](https://tips.sh/1064) | +| Payer-scoped payment-channel savings | MPP channel credits stay attached to the payer who earned them and can be reused by that payer on a later channel open | [TIP-1066: TIP-20 Channel Storage Credits](https://tips.sh/1066) | +| Dynamic base fee | The base fee can move within a bounded range instead of staying fixed | [TIP-1067: Dynamic Base Fee](https://tips.sh/1067-1) | +| Tempo Token Rewards cleanup | New reward opt-ins and distributions stop, while already-accrued rewards remain claimable | [TIP-1075: Deprecate TIP-20 Rewards](https://github.com/tempoxyz/tempo/pull/5380) | + +## Partner benefits + +| Partner type | What T7 can help with | +|--------------|-----------------------| +| DEX makers and liquidity providers | Lower gas when a maker cancels or fully fills orders, then places eligible orders later | +| MPP and pay-as-you-go providers | Lower onchain channel lifecycle costs when the same payer closes or withdraws a channel, then opens another channel later | +| Shared contract developers | A clear pattern for passing storage savings to the user who earned them | +| Wallets, checkout teams, and consumer apps | Lower base fees during periods of low network usage | +| Rewards integrators | Clear migration timing for stopping new Tempo Token Rewards activity | -| TIP | Scope | -|-----|-------| -| [TIP-1075: Deprecate TIP-20 Rewards](https://github.com/tempoxyz/tempo/pull/5380) | Deprecate new TIP-20 rewards and preserve claims for already-accrued rewards | +## Benchmark highlights + +For DEX order flows, fresh order placement is effectively unchanged while same-maker credit reuse is about 1.21M gas cheaper in the merged benchmark. + +| DEX flow | Before | After | Gas change | +|----------|-------:|------:|-------:| +| Fresh place bid | 2,595,385 | 2,604,066 | +8,681 (+0.3%) | +| Fresh place ask | 2,348,185 | 2,356,766 | +8,581 (+0.4%) | +| Cancel bid, earn reusable savings | 304,741 | 361,184 | +56,443 (+18.5%) | +| **Same maker reuses savings after cancel** | **2,075,413** | **868,756** | **1,206,657 gas saved (-58.1%)** | +| Full fill, earn reusable savings | 384,497 | 436,040 | +51,543 (+13.4%) | +| **Same maker reuses savings after full fill** | **1,828,213** | **621,456** | **1,206,757 gas saved (-66.0%)** | + +The credit-earning steps cost more because the DEX records which maker earned the reusable savings. The payoff is the next eligible order from that same maker. ## Compatible releases @@ -72,13 +136,22 @@ Release notes and binaries are available in the [v1.10.1 release](https://github T7 changes fee and reward behavior. Node operators, integrators, indexers, wallets, and partner infrastructure should review the notes below before testnet and mainnet rollout. -### For storage credits +### For storage savings -Partners using DEX or TIP-20 channel flows should review fee assumptions once the T7-compatible release is available. +Partners using DEX or TIP-20 channel flows should review fee assumptions on a T7-compatible testnet. - Storage credits are included for the core primitive, DEX order storage, and TIP-20 channel storage. - Wallets and apps that estimate fees should validate their fee displays against T7 behavior on testnet. - Indexers and analytics systems should keep pre-T7 fee assumptions separate from post-T7 fee data. +- Shared contracts should avoid global credit pools when savings should stay attached to a specific user, maker, payer, or account. + +### For dynamic fees + +Wallets, checkout flows, and infrastructure that display fees should expect the base fee to move instead of staying fixed. + +- The base fee starts at the cap at activation. +- Fees can fall when block gas usage is below target. +- Fee analytics should compare pre-T7 fixed-fee periods separately from post-T7 dynamic-fee periods. ### For TIP-20 rewards deprecation diff --git a/vocs.config.ts b/vocs.config.ts index 9c0f06dd..0abc210c 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -339,6 +339,10 @@ export default defineConfig({ text: 'Withdraw from a zone', link: '/docs/guide/private-zones/withdraw-from-a-zone', }, + { + text: 'Storage savings to benefit your users', + link: '/docs/guide/t7-storage-credits', + }, ], }, { From 06d9c80760a9be4002b34be1c38709cc6b49d619 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 14:32:01 +0100 Subject: [PATCH 2/8] docs: add T7 release benchmark highlights --- .../docs/guide/machine-payments/index.mdx | 2 +- .../guide/machine-payments/pay-as-you-go.mdx | 9 ++++++++ src/pages/docs/guide/t7-storage-credits.mdx | 10 +++++++++ src/pages/docs/protocol/fees/index.mdx | 2 +- src/pages/docs/protocol/upgrades/t7.mdx | 21 ++++++++++++++++++- 5 files changed, 41 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/guide/machine-payments/index.mdx b/src/pages/docs/guide/machine-payments/index.mdx index 91418ffb..d18cfd77 100644 --- a/src/pages/docs/guide/machine-payments/index.mdx +++ b/src/pages/docs/guide/machine-payments/index.mdx @@ -46,7 +46,7 @@ Tempo's transaction model is designed for agentic payments using MPP: - **~500ms finality** — Deterministic confirmation fast enough for synchronous request/response flows - **Sub-cent fees** — Low enough for micropayments and per-request billing -- **Lower repeated channel lifecycle costs** — The planned T7 upgrade adds payer-scoped storage credits for MPP payment channels, helping repeated session lifecycles reuse channel-state savings +- **Lower repeated channel lifecycle costs** — T7 adds payer-scoped storage credits for MPP payment channels. In the [v1.10.1 release benchmark](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1), channel-reserve open calls are 72.1% lower for the open-existing path and 39.2% lower for the open-first path. - **Fee sponsorship** — Servers can cover gas on behalf of clients so they only need stablecoins - **2D and expiring nonces** — Parallel nonce lanes prevent payment transactions from blocking other account activity - **High throughput** — Supports the on-chain settlement volume that payment channels generate at scale diff --git a/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx b/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx index c797afdf..765a41ba 100644 --- a/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx +++ b/src/pages/docs/guide/machine-payments/pay-as-you-go.mdx @@ -18,6 +18,15 @@ Unlike [one-time payments](/docs/guide/machine-payments/one-time-payments), sess The [T7 network upgrade](/docs/protocol/upgrades/t7) adds payer-scoped storage credits for MPP payment channels. When a payer closes or withdraws a finished channel, the reserve can record a channel storage credit for that payer. If the same payer opens another channel later, that payer can reuse the credit. Other payers cannot spend it. ::: +In the [v1.10.1 release benchmark](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1), channel-reserve open calls are lower after T7: + +| Channel reserve path | T6 | T7 | Gas change | +|----------------------|---:|---:|-----------:| +| Open existing | 1,055,229 | 294,425 | -760,804 (-72.1%) | +| Open first | 1,302,429 | 791,625 | -510,804 (-39.2%) | + +These are call-level gas numbers and exclude separate approval gas. They matter most for session services where the same payer opens, closes or withdraws, and later opens channels again. + ## How sessions work x` | 250,000 gas | 5,000 residual + up to 245,000 creditable gas | When credits are available, most of the storage-creation cost can be offset. | + +In plain English: storage creation is not free, and a contract still has to earn credits first. But for repeat workflows that clear and recreate temporary state, T7 lets the contract reuse much more of the value from cleared storage. + ## Why shared contracts need allocation Storage credits belong to the account that owns the storage. For shared contracts, that usually means the contract earns the credit, not the end user automatically. diff --git a/src/pages/docs/protocol/fees/index.mdx b/src/pages/docs/protocol/fees/index.mdx index d1dd2fac..0560df71 100644 --- a/src/pages/docs/protocol/fees/index.mdx +++ b/src/pages/docs/protocol/fees/index.mdx @@ -13,7 +13,7 @@ For a stablecoin to be accepted, it must be USD-denominated, issued as a native Tempo currently uses a fixed base fee (rather than a variable base fee as in EIP-1559), set so that a TIP-20 transfer costs less than $0.001. All fees accrue to the validator who proposes the block. :::info[Dynamic base fee] -A dynamic base fee can fall when block gas usage is below target and rise back to the cap when the network is busy. See the [T7 network upgrade](/docs/protocol/upgrades/t7) and [dynamic base fee proposal](https://tips.sh/1067-1). +A dynamic base fee can fall when block gas usage is below target and rise back to the cap when the network is busy. For a 50,000 gas transfer, the base-fee ceiling moves from about $0.001 to a T7 cap of about $0.0006, with a quiet-period floor around $0.00003. See the [T7 network upgrade](/docs/protocol/upgrades/t7) and [dynamic base fee proposal](https://tips.sh/1067-1). ::: ## Learn More diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 84c0927a..0f5bc973 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -41,7 +41,7 @@ These changes make costs easier to reason about for partners building high-throu | Active DEX makers can pay much less on repeat order placement | In the merged DEX benchmark, same-maker reuse is about 1.21M gas cheaper after a cancel or full fill. | | Returning users can benefit without first-time flows getting worse | Fresh DEX order placement changes by less than 0.5% in the measured bid and ask flows. | | Apps can avoid random gas discounts | Shared contracts can track which user earned credits and spend them only for that same user. | -| MPP sessions can get cheaper over repeated channel lifecycles | Payment-channel credits stay scoped to the payer who closed or withdrew a channel, then can be reused when that payer opens a later channel. | +| MPP sessions can get cheaper over repeated channel lifecycles | In the release benchmark, channel-reserve open calls are 72.1% lower for the open-existing path and 39.2% lower for the open-first path. | | All integrators get a simpler low-fee story | The new base fee cap is 40% lower than today's fixed base fee, and quiet periods can be up to 20x cheaper than the cap. | ## Features @@ -66,6 +66,13 @@ This keeps channel savings attached to the payer who earned them. A different pa For MPP partners, the benefit is focused on repeated session lifecycles. Per-request vouchers already stay off-chain; T7 can lower the net onchain lifecycle cost when a close or withdraw is followed by a later open from the same payer. +The release benchmark reports the channel-reserve open paths below. These are call-level gas numbers and exclude separate approval gas. + +| Channel reserve path | T6 | T7 | Gas change | +|----------------------|---:|---:|-----------:| +| Open existing | 1,055,229 | 294,425 | -760,804 (-72.1%) | +| Open first | 1,302,429 | 791,625 | -510,804 (-39.2%) | + Read [Accept pay-as-you-go payments](/docs/guide/machine-payments/pay-as-you-go) for the MPP session flow. ### Dynamic base fee @@ -109,6 +116,18 @@ Apps that show reward information should keep already-accrued rewards separate f ## Benchmark highlights +The [v1.10.1 release notes](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) include the headline gas benchmarks below. Treat these as protocol-level benchmarks: they show where T7 lowers base fees and storage-related costs, while partner-specific flows should still be tested end to end. + +| Area | T6 / before | T7 / after | What changes | +|------|-------------|------------|--------------| +| Base-fee ceiling for a 50,000 gas transfer | $0.001 | Cap $0.0006; quiet-period floor $0.00003 | The cap is 40% lower, and the floor is 20x below the cap. | +| Credited storage creation (`SSTORE 0 -> x`) | 250,000 gas | 5,000 residual + up to 245,000 creditable gas | When credits are available, most of the storage-creation cost can be offset. | +| Channel reserve open-existing path | 1,055,229 gas | 294,425 gas | 760,804 gas lower (-72.1%). | +| Channel reserve open-first path | 1,302,429 gas | 791,625 gas | 510,804 gas lower (-39.2%). | +| Observed transfer-like costs before T7 | Average $0.0037857 and median $0.0011855 across 1,000 transactions; median $0.0007657 across 598 steady-state transfers | T7 lowers the per-gas component through the new cap and floor | Useful baseline context, not a post-T7 production average. | + +### DEX order reuse + For DEX order flows, fresh order placement is effectively unchanged while same-maker credit reuse is about 1.21M gas cheaper in the merged benchmark. | DEX flow | Before | After | Gas change | From 5d9da38d8352e4907e9685bdd0f0ee2682ffd8a2 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 14:40:28 +0100 Subject: [PATCH 3/8] docs: remove internal benchmark references --- src/components/StorageSavingsExplorer.tsx | 5 ++--- src/pages/docs/guide/t7-storage-credits.mdx | 6 +++--- src/pages/docs/protocol/upgrades/t7.mdx | 4 ++-- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/components/StorageSavingsExplorer.tsx b/src/components/StorageSavingsExplorer.tsx index 3fdd9d9c..8bf4cce3 100644 --- a/src/components/StorageSavingsExplorer.tsx +++ b/src/components/StorageSavingsExplorer.tsx @@ -96,9 +96,8 @@ export function StorageSavingsExplorer() { } footer={ - Uses the merged DEX benchmark in{' '} - tempoxyz/tempo#5903. These - numbers are for the StablecoinDEX benchmark only. + Uses the StablecoinDEX T7 benchmark numbers. These numbers are for the StablecoinDEX + benchmark only. } > diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx index bb00f620..b14813fa 100644 --- a/src/pages/docs/guide/t7-storage-credits.mdx +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -35,7 +35,7 @@ Fresh wallet flows are effectively unchanged. The credit-earning steps cost more -The explorer uses the merged StablecoinDEX benchmark numbers because that is the clearest verified example today. Use it to understand the pattern, then benchmark the specific partner flow before making claims for a bridge, vault, routing contract, or other shared system. +The explorer uses the StablecoinDEX T7 benchmark numbers because that is the clearest example today. Use it to understand the pattern, then benchmark the specific partner flow before making claims for a bridge, vault, routing contract, or other shared system. ## How storage credits work @@ -132,7 +132,7 @@ When deciding whether a contract can benefit from storage credits, check: 6. Are there shared internal accounting slots that should not be credited to any one user? 7. Do gas estimates differ between first-time usage and repeated usage? 8. Do benchmarks include cross-user cases to make sure credits do not leak? -9. Are the numbers from a merged benchmark or a partner-specific test, rather than a draft confidence check? +9. Are the numbers from this DEX example or a partner-specific test, rather than an early confidence check? ## What not to assume @@ -153,4 +153,4 @@ Do not assume: - [Stablecoin DEX Specification](/docs/protocol/exchange/spec) - [Contract storage credits proposal (TIP-1060)](https://tips.sh/1060) - [StablecoinDEX order storage credits proposal (TIP-1064)](https://tips.sh/1064) -- [Merged DEX benchmark](https://github.com/tempoxyz/tempo/pull/5903) +- [v1.10.1 release notes](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 0f5bc973..0b0a10a2 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -38,7 +38,7 @@ These changes make costs easier to reason about for partners building high-throu | Partner impact | What changes | |----------------|--------------| -| Active DEX makers can pay much less on repeat order placement | In the merged DEX benchmark, same-maker reuse is about 1.21M gas cheaper after a cancel or full fill. | +| Active DEX makers can pay much less on repeat order placement | In the T7 DEX benchmark, same-maker reuse is about 1.21M gas cheaper after a cancel or full fill. | | Returning users can benefit without first-time flows getting worse | Fresh DEX order placement changes by less than 0.5% in the measured bid and ask flows. | | Apps can avoid random gas discounts | Shared contracts can track which user earned credits and spend them only for that same user. | | MPP sessions can get cheaper over repeated channel lifecycles | In the release benchmark, channel-reserve open calls are 72.1% lower for the open-existing path and 39.2% lower for the open-first path. | @@ -128,7 +128,7 @@ The [v1.10.1 release notes](https://github.com/tempoxyz/tempo/releases/tag/v1.10 ### DEX order reuse -For DEX order flows, fresh order placement is effectively unchanged while same-maker credit reuse is about 1.21M gas cheaper in the merged benchmark. +For DEX order flows, fresh order placement is effectively unchanged while same-maker credit reuse is about 1.21M gas cheaper in the T7 benchmark. | DEX flow | Before | After | Gas change | |----------|-------:|------:|-------:| From 3d6f193193324976ef6f969fa2ee4462ea3e94fa Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 15:05:28 +0100 Subject: [PATCH 4/8] docs: add T7 benchmark visuals --- src/components/StorageSavingsExplorer.tsx | 221 -------------------- src/components/StorageSavingsSummary.tsx | 101 +++++++++ src/components/T7BenchmarkVisual.tsx | 127 +++++++++++ src/pages/docs/guide/t7-storage-credits.mdx | 27 +-- src/pages/docs/protocol/upgrades/t7.mdx | 4 + 5 files changed, 241 insertions(+), 239 deletions(-) delete mode 100644 src/components/StorageSavingsExplorer.tsx create mode 100644 src/components/StorageSavingsSummary.tsx create mode 100644 src/components/T7BenchmarkVisual.tsx diff --git a/src/components/StorageSavingsExplorer.tsx b/src/components/StorageSavingsExplorer.tsx deleted file mode 100644 index 8bf4cce3..00000000 --- a/src/components/StorageSavingsExplorer.tsx +++ /dev/null @@ -1,221 +0,0 @@ -'use client' - -import * as React from 'react' -import { Container } from './Container' - -type Scenario = { - id: string - label: string - description: string - earnLabel: string - earnBefore: number - earnAfter: number - reuseLabel: string - reuseBefore: number - reuseAfter: number -} - -const SCENARIOS: Scenario[] = [ - { - id: 'cancel', - label: 'Order is canceled', - description: - 'The maker cancels an eligible order, then returns later to place another eligible order.', - earnLabel: 'Cancel bid, earn reusable savings', - earnBefore: 304_741, - earnAfter: 361_184, - reuseLabel: 'Same maker reuses savings after cancel', - reuseBefore: 2_075_413, - reuseAfter: 868_756, - }, - { - id: 'full-fill', - label: 'Order is fully filled', - description: - 'An eligible order is fully filled, then the same maker returns later with another eligible order.', - earnLabel: 'Full fill, earn reusable savings', - earnBefore: 384_497, - earnAfter: 436_040, - reuseLabel: 'Same maker reuses savings after full fill', - reuseBefore: 1_828_213, - reuseAfter: 621_456, - }, -] - -const numberFormat = new Intl.NumberFormat('en-US') -const percentFormat = new Intl.NumberFormat('en-US', { - maximumFractionDigits: 1, -}) - -function formatGas(value: number) { - return `${numberFormat.format(value)} gas` -} - -function formatSignedGas(value: number) { - const sign = value > 0 ? '+' : value < 0 ? '-' : '' - return `${sign}${formatGas(Math.abs(value))}` -} - -function formatSavings(value: number) { - if (value > 0) return `${formatGas(value)} saved` - if (value < 0) return `${formatGas(Math.abs(value))} more` - return 'No gas change' -} - -function formatPercent(value: number) { - const sign = value > 0 ? '+' : value < 0 ? '-' : '' - return `${sign}${percentFormat.format(Math.abs(value))}%` -} - -function changePercent(before: number, after: number) { - return ((after - before) / before) * 100 -} - -export function StorageSavingsExplorer() { - const [scenarioId, setScenarioId] = React.useState(SCENARIOS[0].id) - const [repeatOrders, setRepeatOrders] = React.useState(1) - const scenario = SCENARIOS.find((item) => item.id === scenarioId) ?? SCENARIOS[0] - - const earningCost = scenario.earnAfter - scenario.earnBefore - const reuseSavings = scenario.reuseBefore - scenario.reuseAfter - const beforeTotal = scenario.earnBefore + scenario.reuseBefore * repeatOrders - const afterTotal = scenario.earnAfter + scenario.reuseAfter * repeatOrders - const netSavings = beforeTotal - afterTotal - const netPercent = changePercent(beforeTotal, afterTotal) - const breaksEven = reuseSavings > earningCost - const updateRepeatOrders = (value: number) => { - setRepeatOrders(Math.min(10, Math.max(1, value))) - } - - return ( - - Storage savings explorer - - } - footer={ - - Uses the StablecoinDEX T7 benchmark numbers. These numbers are for the StablecoinDEX - benchmark only. - - } - > -
-
-

- Pick the lifecycle that earns a storage saving, then choose how many later eligible - orders the same maker places. -

- -
- Storage lifecycle - {SCENARIOS.map((item) => { - const active = item.id === scenario.id - return ( - - ) - })} -
-
- -
-
- Later eligible orders by the same maker - - - {repeatOrders} - - -
- updateRepeatOrders(Number(event.currentTarget.value))} - onInput={(event) => updateRepeatOrders(Number(event.currentTarget.value))} - className="w-full accent-gray12" - /> -
- -
-
-
Benchmark impact
- -
- {scenario.earnLabel} - - {formatSignedGas(earningCost)} ( - {formatPercent(changePercent(scenario.earnBefore, scenario.earnAfter))}) - - {scenario.reuseLabel} - - {formatSavings(reuseSavings)} ( - {formatPercent(changePercent(scenario.reuseBefore, scenario.reuseAfter))}) - - Net over this lifecycle - - {formatSavings(netSavings)} ({formatPercent(netPercent)}) - -
-
- -
-
Who should get the saving?
- -
    -
  1. Alice clears eligible order storage and earns reusable savings.
    2. -
  2. Bob places an order later, but does not spend Alice's savings.
    3. -
  3. Alice returns and can use the savings she earned.
    4. -
-
-
- -
- {breaksEven ? ( -

- In this benchmark, one later eligible order is enough to outweigh the extra gas paid - when the DEX records who earned the reusable savings. -

- ) : ( -

- This lifecycle needs more repeat usage before the reusable savings outweigh the - upfront accounting cost. -

- )} -
-
- - ) -} diff --git a/src/components/StorageSavingsSummary.tsx b/src/components/StorageSavingsSummary.tsx new file mode 100644 index 00000000..b4348d5e --- /dev/null +++ b/src/components/StorageSavingsSummary.tsx @@ -0,0 +1,101 @@ +'use client' + +import { Container } from './Container' + +const numberFormat = new Intl.NumberFormat('en-US') + +function formatGas(value: number) { + return `${numberFormat.format(value)} gas` +} + +function formatPercent(value: number) { + return `${value.toFixed(1)}%` +} + +function reduction(before: number, after: number) { + return ((before - after) / before) * 100 +} + +function barWidth(value: number, max: number) { + return `${Math.max((value / max) * 100, 3)}%` +} + +function BeforeAfterRow(props: { label: string; before: number; after: number }) { + const saved = props.before - props.after + + return ( +
+
+ {props.label} + + {formatGas(saved)} lower ({formatPercent(reduction(props.before, props.after))}) + +
+ +
+
+ Before + +
+ After + +
+
+ ) +} + +export function StorageSavingsSummary() { + return ( + + DEX savings at a glance + + } + footer={ + + This is the StablecoinDEX benchmark. Benchmark non-DEX contracts before making the same + claim. + + } + > +
+
+
+
Same-maker repeat orders
+

+ The saving shows up when the maker who earned it later places another eligible order. +

+
+ + +
+ +
+
+
Allocation rule
+

+ Savings should follow the user who cleared the storage. +

+
+
    +
  1. A maker cancels or fully fills an eligible order.
    2. +
  2. The DEX records reusable savings for that maker.
    3. +
  3. Only that same maker can use the saving on a later eligible order.
    4. +
+
+
+ + ) +} diff --git a/src/components/T7BenchmarkVisual.tsx b/src/components/T7BenchmarkVisual.tsx new file mode 100644 index 00000000..c56524fd --- /dev/null +++ b/src/components/T7BenchmarkVisual.tsx @@ -0,0 +1,127 @@ +'use client' + +import { Container } from './Container' + +const numberFormat = new Intl.NumberFormat('en-US') + +function formatGas(value: number) { + return `${numberFormat.format(value)} gas` +} + +function formatPercent(value: number) { + return `${value.toFixed(1)}%` +} + +function reduction(before: number, after: number) { + return ((before - after) / before) * 100 +} + +function barWidth(value: number, max: number) { + return `${Math.max((value / max) * 100, 3)}%` +} + +function BaseFeeRow(props: { + label: string + value: string + width: number + tone: 'before' | 'after' +}) { + return ( +
+
+ {props.label} + {props.value} +
+ + ) +} + +function BeforeAfterRow(props: { label: string; before: number; after: number; unit?: 'gas' }) { + const saved = props.before - props.after + + return ( +
+
+ {props.label} + + {formatGas(saved)} lower ({formatPercent(reduction(props.before, props.after))}) + +
+ +
+
+ Before + +
+ After + +
+
+ ) +} + +export function T7BenchmarkVisual() { + return ( + Fee impact at a glance + } + footer={ + + Bars are normalized within each comparison. Exact benchmark numbers are listed below. + + } + > +
+
+
+
Base fee
+

Example cost for a 50,000 gas transfer.

+
+ + + +
+ +
+
+
Payment channels
+

+ Repeated channel opens can reuse payer-scoped savings. +

+
+ + +
+ +
+
+
DEX repeat orders
+

+ Returning makers can reuse order-storage savings. +

+
+ + +
+
+ + ) +} diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx index b14813fa..2aeb06ff 100644 --- a/src/pages/docs/guide/t7-storage-credits.mdx +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -1,10 +1,9 @@ --- title: Storage Savings to Benefit Your Users description: Learn how shared contracts can use storage savings to benefit the users who earned them. -interactive: true --- -import { StorageSavingsExplorer } from '../../../components/StorageSavingsExplorer' +import { StorageSavingsSummary } from '../../../components/StorageSavingsSummary' # Storage Savings to Benefit Your Users @@ -16,26 +15,18 @@ For partners, the important question is not just "can my contract earn a storage Storage credits are part of the T7 network upgrade: testnet rollout is planned for July 2, 2026, and mainnet rollout is planned for July 9, 2026. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full scope and release details. ::: -## DEX benchmark example +## DEX savings example -The DEX benchmark shows why user-level allocation matters. Fresh order placement stays effectively unchanged, while same-maker reuse becomes much cheaper in the measured lifecycle. +The DEX benchmark shows why user-level allocation matters. Fresh order placement stays effectively unchanged, while repeat orders from a maker who already earned savings become much cheaper. -| Flow | Before | After | Gas change | -|---|---:|---:|---:| -| Fresh place bid | 2,595,385 | 2,604,066 | +8,681 (+0.3%) | -| Fresh place ask | 2,348,185 | 2,356,766 | +8,581 (+0.4%) | -| Cancel bid, earn reusable savings | 304,741 | 361,184 | +56,443 (+18.5%) | -| **Same maker reuses savings after cancel** | **2,075,413** | **868,756** | **1,206,657 gas saved (-58.1%)** | -| Full fill, earn reusable savings | 384,497 | 436,040 | +51,543 (+13.4%) | -| **Same maker reuses savings after full fill** | **1,828,213** | **621,456** | **1,206,757 gas saved (-66.0%)** | - -Fresh wallet flows are effectively unchanged. The credit-earning steps cost more because the DEX records who earned the reusable savings. The benefit appears when the same maker later places another eligible order: the repeat order is about 1.21M gas cheaper. + -## Explore the savings pattern - - +| Repeat order path | Before | After | Gas saved | +|---|---:|---:|---:| +| Same maker after cancel | 2,075,413 | 868,756 | 1,206,657 (-58.1%) | +| Same maker after full fill | 1,828,213 | 621,456 | 1,206,757 (-66.0%) | -The explorer uses the StablecoinDEX T7 benchmark numbers because that is the clearest example today. Use it to understand the pattern, then benchmark the specific partner flow before making claims for a bridge, vault, routing contract, or other shared system. +The cancellation or fill step does a little extra accounting to remember who earned the reusable savings. The payoff appears when that same maker places a later eligible order. ## How storage credits work diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 0b0a10a2..702c2aee 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -3,6 +3,8 @@ title: T7 Network Upgrade description: Partner-focused overview and rollout dates for the T7 network upgrade, including storage savings, payment-channel savings, dynamic base fee behavior, and TIP-20 rewards deprecation. --- +import { T7BenchmarkVisual } from '../../../../components/T7BenchmarkVisual' + # T7 Network Upgrade T7 makes repeated onchain workflows cheaper and gives partners a clearer fee story for payment and exchange flows. It adds storage savings for DEX order state and TIP-20 payment-channel state, lets the base fee move down when network usage is low, and deprecates new TIP-20 rewards activity. @@ -118,6 +120,8 @@ Apps that show reward information should keep already-accrued rewards separate f The [v1.10.1 release notes](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) include the headline gas benchmarks below. Treat these as protocol-level benchmarks: they show where T7 lowers base fees and storage-related costs, while partner-specific flows should still be tested end to end. + + | Area | T6 / before | T7 / after | What changes | |------|-------------|------------|--------------| | Base-fee ceiling for a 50,000 gas transfer | $0.001 | Cap $0.0006; quiet-period floor $0.00003 | The cap is 40% lower, and the floor is 20x below the cap. | From 0c05a36fe2082f77a76b2e8ab31fe966aaa15611 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 17:22:58 +0100 Subject: [PATCH 5/8] docs: simplify storage credit allocation wording --- src/pages/docs/guide/t7-storage-credits.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx index 2aeb06ff..65919f8e 100644 --- a/src/pages/docs/guide/t7-storage-credits.mdx +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -9,7 +9,7 @@ import { StorageSavingsSummary } from '../../../components/StorageSavingsSummary Storage credits are a network feature for contracts that create storage, clear it, and later create storage again in the same contract. The benefit is strongest for repeat workflows with temporary state, such as DEX orders. -For partners, the important question is not just "can my contract earn a storage credit?" It is "how should I allocate the storage credits to benefit my users fairly?" +Partners building shared contracts should decide who earns each credit and make sure that same user, maker, payer, or account can use it later. :::info[Feature status] Storage credits are part of the T7 network upgrade: testnet rollout is planned for July 2, 2026, and mainnet rollout is planned for July 9, 2026. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full scope and release details. From 8ba4cb0cf73f6aea16d3436b2d238fad78729970 Mon Sep 17 00:00:00 2001 From: 0xrusowsky <90208954+0xrusowsky@users.noreply.github.com> Date: Mon, 29 Jun 2026 22:55:10 +0200 Subject: [PATCH 6/8] docs: improve storage credits explanation (#617) * docs: improve storage credits explanation * fix: typo --- src/pages/docs/guide/t7-storage-credits.mdx | 162 +++++++++++--------- 1 file changed, 89 insertions(+), 73 deletions(-) diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx index 65919f8e..9ae42212 100644 --- a/src/pages/docs/guide/t7-storage-credits.mdx +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -1,129 +1,144 @@ --- -title: Storage Savings to Benefit Your Users -description: Learn how shared contracts can use storage savings to benefit the users who earned them. +title: Storage Credits for Repeated Workflows +description: Learn how storage credits lower repeat storage costs, how Refund mode works by default, and when to attribute savings to specific users. --- import { StorageSavingsSummary } from '../../../components/StorageSavingsSummary' -# Storage Savings to Benefit Your Users +# Storage Credits for Repeated Workflows -Storage credits are a network feature for contracts that create storage, clear it, and later create storage again in the same contract. The benefit is strongest for repeat workflows with temporary state, such as DEX orders. +Storage credits make repeated storage workflows cheaper. Products can pass those savings to users through lower transaction costs, or explicitly attribute them to the users who earned them. They are useful for repeated business flows like DEX orders: placing an order creates storage, canceling or filling the order clears it, and the same maker may place another order later. -Partners building shared contracts should decide who earns each credit and make sure that same user, maker, payer, or account can use it later. +T7 keeps fresh storage expensive enough to discourage state-growth spam, while letting contracts reuse value from storage they clear. By default, contracts benefit automatically. If your product needs the savings to follow a specific user, maker, payer, or account, you can add user-level accounting on top. :::info[Feature status] Storage credits are part of the T7 network upgrade: testnet rollout is planned for July 2, 2026, and mainnet rollout is planned for July 9, 2026. See the [T7 network upgrade](/docs/protocol/upgrades/t7) for the full scope and release details. ::: -## DEX savings example +## How storage credits work -The DEX benchmark shows why user-level allocation matters. Fresh order placement stays effectively unchanged, while repeat orders from a maker who already earned savings become much cheaper. +Each account has a protocol-maintained storage credit balance. A credit is not a token, cannot be transferred, and can only offset storage creation by the same account that earned it. - +The balance changes when that account's storage slots move between empty and non-empty: -| Repeat order path | Before | After | Gas saved | -|---|---:|---:|---:| -| Same maker after cancel | 2,075,413 | 868,756 | 1,206,657 (-58.1%) | -| Same maker after full fill | 1,828,213 | 621,456 | 1,206,757 (-66.0%) | +| Storage transition | What happens | +|---|---| +| Nonzero to zero | The account deletes storage and earns one storage credit | +| Zero to nonzero | The account creates storage; one available credit can offset the creditable portion of that creation, depending on the account's storage creation mode | -The cancellation or fill step does a little extra accounting to remember who earned the reusable savings. The payoff appears when that same maker places a later eligible order. +A credit is tied to the storage-owning account, not to the transaction sender or the user whose action triggered the write. The same rule applies whether the account is a smart contract, precompile, or EOA, though contracts are the common case for application storage. -## How storage credits work +One credit can offset most of the storage-creation cost for one new slot. For contract storage, the account is the contract address, so credits earned by a contract belong to the contract. + +## Default behavior: `Refund` mode -The storage credit primitive gives an account a storage credit when it clears one of its own storage slots. Later, that same account can use the credit to reduce the gas cost of creating storage again. +Contracts do not need to call the storage credits precompile to benefit from storage credits. Every account starts each transaction in `Refund` mode. -In simple terms: +In `Refund` mode, storage creations pay upfront. At the end of the transaction, the protocol matches eligible creations with available credits for the same contract, consumes those credits, and applies the gas refund. -1. A contract creates storage. -2. The contract later clears that storage. -3. The network records a storage credit for that contract. -4. The contract can use that credit to reduce gas for a future storage creation. +| Action | `Refund` mode behavior | +|---|---| +| Contract deletes one of its own storage slots | The contract earns a protocol storage credit | +| Contract creates storage later | The creation pays upfront during execution | +| End-of-transaction settlement | Available credits can be consumed to refund matched creations | +| Contract has no user-level accounting | Credits are spent first-come, first-served by later storage creations | + +This default mode is usually enough when the contract simply wants lower net cost for repeated storage churn. It is not user-aware: whichever eligible storage creation happens next can consume an available credit, regardless of which user caused the earlier storage deletion. -This is useful when storage is temporary rather than permanent. A one-time storage write is different from a repeated create, clear, and recreate pattern. +That first-come, first-served behavior is why explicit user-level attribution can be useful for products that want savings to follow a specific user. ## Storage creation benchmark -The [v1.10.1 release benchmark](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) shows why this primitive matters. In T6, credited storage creation cost `250,000` gas. In T7, that same storage-creation component is split into a `5,000` gas residual cost plus up to `245,000` gas that can be covered by storage credits. +The [v1.10.1 release benchmark](https://github.com/tempoxyz/tempo/releases/tag/v1.10.1) shows why this primitive matters. In T6, the TIP-1000 storage creation component cost `250,000` gas. In T7, that component is split into a `5,000` gas residual cost plus a `245,000` gas creditable portion that one storage credit can offset. | Storage creation path | T6 | T7 | What it means | |---|---:|---:|---| -| Credited `SSTORE 0 -> x` | 250,000 gas | 5,000 residual + up to 245,000 creditable gas | When credits are available, most of the storage-creation cost can be offset. | - -In plain English: storage creation is not free, and a contract still has to earn credits first. But for repeat workflows that clear and recreate temporary state, T7 lets the contract reuse much more of the value from cleared storage. +| Credited `SSTORE 0 -> x` | 250,000 gas | 5,000 residual + up to 245,000 creditable gas | When a credit is applied, most of the storage-creation component can be offset. | -## Why shared contracts need allocation +Storage creation is not free, and a contract still has to earn credits first. But for workflows that repeatedly create, clear, and recreate temporary state, T7 lets the contract reuse much more of the value from cleared storage. -Storage credits belong to the account that owns the storage. For shared contracts, that usually means the contract earns the credit, not the end user automatically. +## Why user-level accounting can be useful -That creates an allocation problem. +Protocol storage credits lower the contract's cost, but they do not answer the product question of which user should receive the benefit. For example: -1. Alice places and later cancels an order. -2. The DEX clears Alice's order storage and earns a storage credit. -3. Bob places a new order later. -4. Without user-level accounting, Bob could receive the benefit from storage Alice cleared. +1. Alice places an order on a DEX. +2. Alice cancels the order, so the DEX deletes the order's physical storage. +3. The protocol credits the DEX contract because the DEX owned the storage. +4. Bob places a new order later. +5. With default first-come, first-served behavior, Bob's storage creation could use the credit that came from Alice's deleted order storage. -Contracts that serve many users should add their own accounting layer when credits need to stay attached to a specific user, payer, maker, or account. +That may be fine for some products. For the StablecoinDEX, the intended behavior is different: if Alice's order lifecycle created the reusable storage benefit, Alice should be able to use that benefit when she places a later order. -## Pattern: credit the user who cleared state +Use user-level accounting when all of these are true: -The DEX implementation applies this idea to the StablecoinDEX. +1. Deleted storage is clearly attributable to one user, maker, payer, or account. +2. That same user is expected to create similar storage again later. +3. You want the savings to follow that user instead of going to whichever eligible action happens next. +4. The contract can distinguish user-attributed storage from internal accounting storage. -Instead of treating all DEX storage credits as one shared pool, the DEX tracks which maker earned reusable order-storage savings. When that same maker later creates eligible order storage, the DEX can apply that maker's savings. +### StablecoinDEX pattern -Technically, [TIP-1064](https://tips.sh/1064) applies this allocation pattern to the StablecoinDEX on top of [TIP-1060](https://tips.sh/1060), the contract storage credits primitive. +[TIP-1064](https://tips.sh/1064) adds user-level reusable storage accounting for StablecoinDEX order storage. -| Event | Result | +The DEX keeps a dedicated state variable, `dex_storage_credits`, to track reusable order-storage credits per user. This is not the same as the TIP-1060 protocol credit balance. The protocol balance belongs to the DEX contract; `dex_storage_credits` is the DEX's user-facing record of which maker should receive the benefit. + +To enforce that attribution, DEX transactions preserve protocol credits by default and only spend them deliberately for attributed writes: + +- By default, DEX storage creations use `Preserve` mode. `Preserve` mode pays the normal storage-creation cost and leaves the DEX's protocol credit balance untouched, so a maker cannot accidentally consume credits attributed to someone else. +- When an eligible maker has DEX storage credits, the DEX switches to `Direct` mode for that maker's storage creation. `Direct` mode consumes an available DEX protocol credit during the write, so the maker's eligible order creation receives the benefit immediately. + +| Event | StablecoinDEX behavior | |---|---| -| Maker cancels an eligible order | The DEX clears order storage and records reusable savings for that maker | -| Maker's order is fully filled | The DEX clears order storage and records reusable savings for that maker | -| Same maker places a later eligible order | The DEX can apply that maker's savings | -| Different maker places an order | They do not consume savings they did not earn | +| An operation deletes reusable order storage | TIP-1060 credits the DEX contract | +| The deleted storage belongs to maker `U` | The DEX increments `dex_storage_credits[U]` | +| Maker `U` later creates eligible order storage and has DEX storage credits | The DEX decrements `dex_storage_credits[U]` and switches to `Direct` mode so one DEX protocol credit can offset the creation | +| A different maker creates order storage, or maker `U` has no DEX storage credits | The DEX stays in `Preserve` mode so the write does not consume a credit attributed to someone else | -Use this pattern for shared contracts: +The key idea is simple: TIP-1060 gives the DEX the raw storage credit, while TIP-1064 lets the DEX decide which maker can spend that benefit. -1. Identify which storage is clearly attributable to one user. -2. Credit that user when the contract clears that storage. -3. Spend that user's credits only when the same user creates eligible storage later. -4. Keep shared accounting storage separate from user-attributed storage. +### DEX savings example -## Prevent cross-user leakage +The DEX benchmark shows why user-level accounting can matter. Fresh order placement stays effectively unchanged, while repeat orders from a maker who already earned DEX storage credits become much cheaper. -User-level allocation prevents one user's savings from being spent by another user. + -| Case | Expected behavior | -|---|---| -| Same maker returns after earning savings | Apply that maker's stored savings to an eligible order | -| Different maker places the next order | Do not spend the first maker's savings | -| Shared internal accounting is cleared | Do not assign the saving to whichever user happened to trigger cleanup | +| Repeat order path | Before | After | Gas saved | +|---|---:|---:|---:| +| Same maker after cancel | 2,075,413 | 868,756 | 1,206,657 (-58.1%) | +| Same maker after full fill | 1,828,213 | 621,456 | 1,206,757 (-66.0%) | -The DEX benchmark includes cross-user isolation tests to prove this behavior, but the partner-facing rule is simpler: savings earned by Alice should stay available to Alice, and Bob should pay the normal cost unless Bob earned savings too. +The cancellation or fill step does a little extra accounting to remember which maker earned the reusable order-storage benefit. The payoff appears when that same maker places a later eligible order. -## When to use this pattern +### Prevent cross-user leakage -Use this pattern when the same user, payer, maker, or account has a repeated lifecycle: +User-level accounting prevents one user's storage benefit from being spent by another user. -1. The contract creates temporary storage for that user. -2. The contract later clears that storage. -3. The same user is likely to create storage again through the same contract. -4. The contract can track that user's credits without mixing them with unrelated users. +| Case | Expected behavior | +|---|---| +| Same maker returns after earning DEX storage credits | Apply that maker's stored credits to eligible order storage | +| Different maker places the next order | Do not spend the first maker's credits | +| Internal accounting storage is cleared | Do not assign the credit to whichever user happened to trigger cleanup | -For bridge, vault, routing, and other shared-contract flows, benchmark the specific workflow before making partner-facing claims. Do not reuse DEX numbers for a different contract shape. +The DEX benchmark includes cross-user isolation tests to prove this behavior, but the product rule is simpler: savings earned by Alice should stay available to Alice, and Bob should pay the normal cost unless Bob earned savings too. ## Partner checklist -When deciding whether a contract can benefit from storage credits, check: +When deciding whether default storage credits are enough or whether you should add user-level accounting, check: 1. Does the contract create storage during the user flow? 2. Does the contract later clear that storage? -3. Is the cleared storage attributable to one user, payer, order owner, or account? -4. Does the same user later create eligible storage again? -5. Can the contract track credits per user instead of sharing all credits globally? -6. Are there shared internal accounting slots that should not be credited to any one user? -7. Do gas estimates differ between first-time usage and repeated usage? -8. Do benchmarks include cross-user cases to make sure credits do not leak? -9. Are the numbers from this DEX example or a partner-specific test, rather than an early confidence check? +3. Is the deleted storage owned by the contract and eligible for protocol storage credits? +4. Is the storage lifecycle clearly attributable to a specific user, payer, maker, or account? +5. Is first-come, first-served credit usage acceptable? +6. If not, should the same user receive the later benefit? +7. Does the same user later create eligible storage again? +8. Can the contract track user-level credits without mixing them with unrelated users? +9. Are there internal accounting slots that should not be credited to any one user? +10. Do gas estimates differ between first-time usage and repeated usage? +11. Do benchmarks include cross-user cases to make sure credits do not leak? +12. Are the numbers from this DEX example or a workflow-specific test, rather than an early confidence check? ## What not to assume @@ -133,9 +148,10 @@ Do not assume: - Every transaction gets cheaper. - First-time users receive the same savings as repeat users. -- Contract-level credits automatically map to the right end user. -- Shared accounting storage should be credited to whichever user happened to trigger the cleanup. -- DEX benchmark numbers apply to bridge, vault, or routing contracts without testing those workflows separately. +- Protocol storage credits automatically map to the right end user. +- Default first-come, first-served usage is always the right product behavior. +- Internal accounting storage should be credited to whichever user happened to trigger cleanup. +- DEX benchmark numbers apply to bridge, vault, routing, or other contracts without testing those workflows separately. ## Related pages From 475906f7a70ca749f8c705c6818c181325ccc624 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 21:58:40 +0100 Subject: [PATCH 7/8] docs: update storage credits guide links --- src/pages/docs/guide/stablecoin-dex/providing-liquidity.mdx | 2 +- src/pages/docs/protocol/exchange/providing-liquidity.mdx | 2 +- src/pages/docs/protocol/upgrades/t7.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/guide/stablecoin-dex/providing-liquidity.mdx b/src/pages/docs/guide/stablecoin-dex/providing-liquidity.mdx index 67dc3b1c..455b2357 100644 --- a/src/pages/docs/guide/stablecoin-dex/providing-liquidity.mdx +++ b/src/pages/docs/guide/stablecoin-dex/providing-liquidity.mdx @@ -19,7 +19,7 @@ Add liquidity for a token pair by placing orders on the Stablecoin DEX. You can In this guide you will learn how to place buy and sell orders to provide liquidity on the Stablecoin DEX orderbook. :::info[Planned storage savings for active makers] -After the T7 network upgrade, active makers may pay less gas when they cancel or fully fill eligible orders and later place new eligible orders. See [Storage Savings to Benefit Your Users](/docs/guide/t7-storage-credits) for the DEX benchmark and allocation pattern. +After the T7 network upgrade, active makers may pay less gas when they cancel or fully fill eligible orders and later place new eligible orders. See [Storage Credits for Repeated Workflows](/docs/guide/t7-storage-credits) for the DEX benchmark and allocation pattern. ::: ## Demo diff --git a/src/pages/docs/protocol/exchange/providing-liquidity.mdx b/src/pages/docs/protocol/exchange/providing-liquidity.mdx index 2d5de509..06d311a0 100644 --- a/src/pages/docs/protocol/exchange/providing-liquidity.mdx +++ b/src/pages/docs/protocol/exchange/providing-liquidity.mdx @@ -17,7 +17,7 @@ The DEX uses an onchain orderbook where you can place orders at specific price t Unlike traditional AMMs, you specify exact prices where you want to buy or sell, giving you more precise control over your liquidity provision strategy. :::info[Storage credits for DEX makers] -Storage credits can reduce gas for active DEX makers who repeatedly place, cancel, or fully fill eligible orders. See [Storage Savings to Benefit Your Users](/docs/guide/t7-storage-credits) for the allocation pattern and benchmark examples. +Storage credits can reduce gas for active DEX makers who repeatedly place, cancel, or fully fill eligible orders. See [Storage Credits for Repeated Workflows](/docs/guide/t7-storage-credits) for the allocation pattern and benchmark examples. ::: ## Order Types diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 702c2aee..6a6680ee 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -58,7 +58,7 @@ This is not a blanket gas discount. It matters most when a workflow has a natura The StablecoinDEX uses the same storage-credit idea but adds maker-level accounting. If a maker cancels or fully fills an eligible order, the DEX can keep the reusable order-storage savings attached to that maker. When the same maker places a later eligible order, the DEX can apply those savings. -Read [Storage Savings to Benefit Your Users](/docs/guide/t7-storage-credits) for the allocation pattern, interactive example, and DEX benchmark. +Read [Storage Credits for Repeated Workflows](/docs/guide/t7-storage-credits) for the allocation pattern, storage credit modes, and DEX benchmark. ### Payer-scoped payment-channel savings From 9295715a1225b072a737a42f160454b075a64403 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 29 Jun 2026 22:19:38 +0100 Subject: [PATCH 8/8] docs: clarify filled order labels --- src/components/StorageSavingsSummary.tsx | 2 +- src/components/T7BenchmarkVisual.tsx | 2 +- src/pages/docs/guide/t7-storage-credits.mdx | 2 +- src/pages/docs/protocol/upgrades/t7.mdx | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/components/StorageSavingsSummary.tsx b/src/components/StorageSavingsSummary.tsx index b4348d5e..bc094aaa 100644 --- a/src/components/StorageSavingsSummary.tsx +++ b/src/components/StorageSavingsSummary.tsx @@ -79,7 +79,7 @@ export function StorageSavingsSummary() {

- +
diff --git a/src/components/T7BenchmarkVisual.tsx b/src/components/T7BenchmarkVisual.tsx index c56524fd..9398e37f 100644 --- a/src/components/T7BenchmarkVisual.tsx +++ b/src/components/T7BenchmarkVisual.tsx @@ -119,7 +119,7 @@ export function T7BenchmarkVisual() {

- +
diff --git a/src/pages/docs/guide/t7-storage-credits.mdx b/src/pages/docs/guide/t7-storage-credits.mdx index 9ae42212..73c68e03 100644 --- a/src/pages/docs/guide/t7-storage-credits.mdx +++ b/src/pages/docs/guide/t7-storage-credits.mdx @@ -107,7 +107,7 @@ The DEX benchmark shows why user-level accounting can matter. Fresh order placem | Repeat order path | Before | After | Gas saved | |---|---:|---:|---:| | Same maker after cancel | 2,075,413 | 868,756 | 1,206,657 (-58.1%) | -| Same maker after full fill | 1,828,213 | 621,456 | 1,206,757 (-66.0%) | +| Same maker after filled order | 1,828,213 | 621,456 | 1,206,757 (-66.0%) | The cancellation or fill step does a little extra accounting to remember which maker earned the reusable order-storage benefit. The payoff appears when that same maker places a later eligible order. diff --git a/src/pages/docs/protocol/upgrades/t7.mdx b/src/pages/docs/protocol/upgrades/t7.mdx index 6a6680ee..1724f339 100644 --- a/src/pages/docs/protocol/upgrades/t7.mdx +++ b/src/pages/docs/protocol/upgrades/t7.mdx @@ -40,7 +40,7 @@ These changes make costs easier to reason about for partners building high-throu | Partner impact | What changes | |----------------|--------------| -| Active DEX makers can pay much less on repeat order placement | In the T7 DEX benchmark, same-maker reuse is about 1.21M gas cheaper after a cancel or full fill. | +| Active DEX makers can pay much less on repeat order placement | In the T7 DEX benchmark, same-maker reuse is about 1.21M gas cheaper after an order is canceled or filled. | | Returning users can benefit without first-time flows getting worse | Fresh DEX order placement changes by less than 0.5% in the measured bid and ask flows. | | Apps can avoid random gas discounts | Shared contracts can track which user earned credits and spend them only for that same user. | | MPP sessions can get cheaper over repeated channel lifecycles | In the release benchmark, channel-reserve open calls are 72.1% lower for the open-existing path and 39.2% lower for the open-first path. | @@ -140,8 +140,8 @@ For DEX order flows, fresh order placement is effectively unchanged while same-m | Fresh place ask | 2,348,185 | 2,356,766 | +8,581 (+0.4%) | | Cancel bid, earn reusable savings | 304,741 | 361,184 | +56,443 (+18.5%) | | **Same maker reuses savings after cancel** | **2,075,413** | **868,756** | **1,206,657 gas saved (-58.1%)** | -| Full fill, earn reusable savings | 384,497 | 436,040 | +51,543 (+13.4%) | -| **Same maker reuses savings after full fill** | **1,828,213** | **621,456** | **1,206,757 gas saved (-66.0%)** | +| Order filled, earn reusable savings | 384,497 | 436,040 | +51,543 (+13.4%) | +| **Same maker reuses savings after filled order** | **1,828,213** | **621,456** | **1,206,757 gas saved (-66.0%)** | The credit-earning steps cost more because the DEX records which maker earned the reusable savings. The payoff is the next eligible order from that same maker.