From f69a1943521726a681390229ccb7da720f9cbfd8 Mon Sep 17 00:00:00 2001
From: Max <maxime@ithaca.xyz>
Date: Thu, 28 May 2026 13:04:55 +0100
Subject: [PATCH] docs(t5): fill in missing T5 callouts on TIP-20 spec,
 overview, payment-lane spec, and MPP guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Triple-check pass over the T5 callout rollout from #405.

Surfaced by looking at the published TIP-20 overview (which advertises
T5 features) vs the spec (which had no T5 content at all).

## T5 coverage gaps filled

- protocol/tip20/spec.mdx — add T4 → T5 migration appendix covering
  TIP-1026 (logoURI / setLogoURI / LogoURIUpdated / 7-arg createToken
  overload / on-chain validation), TIP-1035 (Implicit Approvals List
  and system_transfer_from semantics), and TIP-1034 cross-reference
  to the TIP20ChannelReserve precompile. Appendix only — preserves
  Josh's prior decision in #405 not to put a top-of-page Coming-with
  callout on the spec.
- protocol/tip20/overview.mdx — Coming-with-T5 callout summarising
  the three TIP-20 features above with a link to the spec appendix.
- protocol/blockspace/payment-lane-specification.mdx — Coming-with-T5
  callout for TIP-1045 (consensus-level payment-lane classification).
- guide/machine-payments/pay-as-you-go.mdx — Coming-with-T5 callout
  for TIP-1034 channel reserve precompile with the precompile address
  and the gas-savings note from TIP-1035 implicit approvals.

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019e6e22-0805-7628-b3b5-899366ecd1f6
---
 .../guide/machine-payments/pay-as-you-go.mdx  |  4 +
 .../blockspace/payment-lane-specification.mdx |  4 +
 src/pages/protocol/tip20/overview.mdx         |  9 +++
 src/pages/protocol/tip20/spec.mdx             | 75 +++++++++++++++++++
 4 files changed, 92 insertions(+)

diff --git a/src/pages/guide/machine-payments/pay-as-you-go.mdx b/src/pages/guide/machine-payments/pay-as-you-go.mdx
index d330f72f..8388695f 100644
--- a/src/pages/guide/machine-payments/pay-as-you-go.mdx
+++ b/src/pages/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](/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[Coming with T5]
+The [T5 network upgrade](/protocol/upgrades/t5) ships an enshrined `TIP20ChannelReserve` precompile at [`0x4D50500000000000000000000000000000000000`](https://explore.tempo.xyz/address/0x4D50500000000000000000000000000000000000) (ASCII `MPP`) that replaces the application-level escrow contract for new MPP integrations ([TIP-1034](https://tips.sh/1034)). The existing escrow contract continues to work; SDKs that target the precompile additionally save gas thanks to [implicit approvals](/protocol/upgrades/t5#tip-1035-implicit-approvals-list) — the channel can pull TIP-20 tokens without a prior `approve` transaction. New `mppx` releases that target the precompile will be linked under [Compatible SDK releases](/protocol/upgrades/t5#compatible-sdk-releases).
+:::
+
 ## How sessions work
 
 <MermaidDiagram chart={`sequenceDiagram
diff --git a/src/pages/protocol/blockspace/payment-lane-specification.mdx b/src/pages/protocol/blockspace/payment-lane-specification.mdx
index c6340181..c2c33d4e 100644
--- a/src/pages/protocol/blockspace/payment-lane-specification.mdx
+++ b/src/pages/protocol/blockspace/payment-lane-specification.mdx
@@ -4,6 +4,10 @@ description: Technical specification for Tempo payment lanes ensuring dedicated
 
 # Payment Lane Specification
 
+:::info[Coming with T5]
+The [T5 network upgrade](/protocol/upgrades/t5) replaces the pre-T5 TIP-20 prefix-only consensus classifier with TIP-1045's allow-listed call shapes ([TIP-1045](https://tips.sh/1045)). The allow-list covers TIP-20 calls and the new `TIP20ChannelReserve` precompile ([TIP-1034](https://tips.sh/1034)), so payment-channel reserve transactions become first-class payment-lane traffic. Indexers, explorers, and payment processors that classify "payments" should pick up the new selector list before activation. Until T5 activates, the prefix-based classification described below still applies.
+:::
+
 ## Abstract
 
 This specification introduces a second consensus gas constraint for **non-payment** transactions. Transactions are classified as either payments or non-payments based solely on their transaction data, without requiring any access to blockchain state. For a block to be valid, total `gas_used` by the block must be less than the `gas_limit`. Non-payment transactions executed in the proposer's lane (i.e. before the gas incentive section) must consume at most `general_gas_limit`, a new field added to the header. Once that budget is exhausted, additional inclusion is constrained by the remaining shared gas budget.
diff --git a/src/pages/protocol/tip20/overview.mdx b/src/pages/protocol/tip20/overview.mdx
index f75190be..a9a213c9 100644
--- a/src/pages/protocol/tip20/overview.mdx
+++ b/src/pages/protocol/tip20/overview.mdx
@@ -6,6 +6,15 @@ import { Cards, Card } from 'vocs'
 
 # TIP-20 Token Standard
 
+:::info[Coming with T5]
+The [T5 network upgrade](/protocol/upgrades/t5) adds three TIP-20 features:
+- An optional on-chain `logoURI` field on every token so wallets and explorers can render the official icon without an off-chain registry ([TIP-1026](https://tips.sh/1026))
+- An Implicit Approvals List that lets the StablecoinDEX, FeeAMM, and the new payment-channel reserve precompile pull TIP-20 tokens without a prior `approve` transaction ([TIP-1035](https://tips.sh/1035))
+- An enshrined `TIP20ChannelReserve` precompile at `0x4D505000…0000` for MPP and other session-based payment flows ([TIP-1034](https://tips.sh/1034))
+
+Existing tokens continue to work unchanged. See the [T4 → T5 migration appendix on the TIP-20 spec](/protocol/tip20/spec#t4--t5-migration) for the full ABI surface.
+:::
+
 TIP-20 is Tempo's native token standard for stablecoins and payment tokens. TIP-20 is designed for stablecoin payments, and is the foundation for many token-related functions on Tempo including transaction fees, payment lanes, DEX quote tokens, and optimized routing for DEX liquidity on Tempo.
 
 All TIP-20 tokens are created by interacting with the [TIP-20 Factory contract](/protocol/tip20/spec#tip20factory), calling the `createToken` function. If you're issuing a stablecoin on Tempo, we **strongly recommend** using the TIP-20 standard. Learn more about the benefits, or follow the guide on issuance [here](/guide/issuance).
diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx
index c3512219..521cc8b5 100644
--- a/src/pages/protocol/tip20/spec.mdx
+++ b/src/pages/protocol/tip20/spec.mdx
@@ -604,3 +604,78 @@ interface ITIP20Factory {
 - TIP20 tokens cannot be transferred to another TIP20 token contract address.
 - `systemTransferFrom`, `transferFeePreTx`, and `transferFeePostTx` never change `totalSupply()`.
 
+## T4 → T5 migration
+
+:::info[Migration appendix]
+This section captures TIP-20 changes shipping with the [T5 network upgrade](/protocol/upgrades/t5). Until T5 activates on testnet and mainnet, the spec above remains canonical. After T5 activation, the items below will be folded into the body and this appendix will be removed.
+:::
+
+T5 introduces three additions that affect the TIP-20 surface:
+
+### TIP-1026: optional on-chain `logoURI`
+
+Adds an optional `logoURI` string (256-byte cap) to every TIP-20, admin-mutable via `setLogoURI`. Tokens without a `logoURI` continue to work; the field is empty by default.
+
+New surface area on `ITIP20`:
+
+```solidity
+/// @notice Returns the on-chain logo URI for this token (empty if unset)
+function logoURI() external view returns (string memory);
+
+/// @notice Updates the logo URI (requires DEFAULT_ADMIN_ROLE)
+/// @param newLogoURI The new logo URI (max 256 bytes; empty string clears the field)
+/// @dev If non-empty, MUST be a syntactically valid URI with a scheme in the
+///      allowlist {https, http, ipfs, data} (case-insensitive).
+///      Reverts LogoURITooLong if length > 256 bytes.
+///      Reverts InvalidLogoURI if the scheme is not in the allowlist or the URI is malformed.
+function setLogoURI(string calldata newLogoURI) external;
+
+/// @notice Emitted when the logo URI changes
+/// @param updater The address that updated the logo URI (msg.sender)
+/// @param newLogoURI The new logo URI value
+event LogoURIUpdated(address indexed updater, string newLogoURI);
+
+/// @notice The provided logoURI exceeds the 256-byte cap
+error LogoURITooLong();
+
+/// @notice The provided logoURI is malformed or uses a scheme outside the allowlist
+error InvalidLogoURI();
+```
+
+The `TIP20Factory` gains a 7-arg `createToken` overload that accepts an initial `logoURI`. When non-empty, the new token emits `LogoURIUpdated(msg.sender, logoURI)` from its own address at creation time. The existing 6-arg overload is unchanged.
+
+```solidity
+/// @notice Creates and deploys a new TIP-20 token with an initial logoURI
+/// @dev Identical to the 6-arg overload, but additionally sets logoURI at creation.
+///      Validation rules for logoURI are the same as setLogoURI (256-byte cap,
+///      allowlisted schemes, syntactically valid URI). Empty string is valid and
+///      leaves logoURI unset (no LogoURIUpdated event emitted).
+function createToken(
+    string memory name,
+    string memory symbol,
+    string memory currency,
+    address quoteToken,
+    address admin,
+    bytes32 salt,
+    string memory logoURI
+) external returns (address token);
+```
+
+Per [TIP-1026's recommended formats](https://tips.sh/1026#recommended-formats), use a square, single-frame rasterized image (PNG or WebP) for `logoURI`. SVG is allowed by the scheme allowlist but not recommended — integrators that accept SVG must follow TIP-1026's SVG-handling guidance.
+
+### TIP-1035: implicit approvals for listed precompiles
+
+T5 introduces an Implicit Approval List of precompiles that may pull TIP-20 tokens without a prior `approve`. Listed precompiles call the internal `system_transfer_from(from, to, amount)` entrypoint, which:
+
+- Is **not** part of the public TIP-20 ABI and is **not** callable by external contracts or EOAs.
+- Skips allowance checks and the allowance storage write.
+- Still enforces balance checks, TIP-403 transfer policies, and AccountKeychain spending limits.
+- Emits the standard TIP-20 `Transfer` event.
+
+This generalizes the existing system-only path (previously documented as `systemTransferFrom`, `transferFeePreTx`, `transferFeePostTx`) to a hardfork-gated allow-list of precompiles — initially the StablecoinDEX, FeeAMM, and the new `TIP20ChannelReserve` precompile. Normal `approve`, `permit`, `allowance`, and `transferFrom` behavior is unchanged.
+
+### TIP-1034: `TIP20ChannelReserve` precompile cross-reference
+
+T5 ships an enshrined TIP-20 payment-channel reserve precompile at [`0x4D50500000000000000000000000000000000000`](https://explore.tempo.xyz/address/0x4D50500000000000000000000000000000000000) (ASCII `MPP`). Channel reserve is a TIP-20 consumer rather than a change to the TIP-20 contract itself — it pulls funds via the implicit-approval path described above and emits standard `Transfer` events from the host TIP-20.
+
+See the [Enshrined TIP-20 reserve channel section of the T5 page](/protocol/upgrades/t5#enshrined-tip-20-reserve-channel-tip-1034) for the channel lifecycle, channel ID derivation, and event surface.