From 96567eef4c5de22ac6d6dd3260fc42c02265bcef Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Thu, 26 Mar 2026 20:52:11 +0100 Subject: [PATCH 1/2] Move fee abstraction docs to "Build on Celo" section Split the single fee abstraction page into three focused pages: - Overview: what fee abstraction is, allowlist, adapters - Using Fee Abstraction: practical guide with viem and CLI - Adding Fee Currencies: IFeeCurrency interface and implementation Update all cross-references and redirects. --- build-on-celo/build-on-minipay/quickstart.mdx | 2 +- build-on-celo/build-with-ai/overview.mdx | 2 +- build-on-celo/build-with-ai/x402.mdx | 2 +- .../fee-abstraction/add-fee-currency.mdx | 151 ++++++++++++++++++ build-on-celo/fee-abstraction/overview.mdx | 62 +++++++ .../fee-abstraction/using-fee-abstraction.mdx | 96 +++-------- build-on-celo/index.mdx | 2 +- docs.json | 23 ++- home/protocol/transactions/overview.mdx | 2 +- home/wallets.mdx | 2 +- tooling/libraries-sdks/ethers/index.mdx | 4 +- tooling/libraries-sdks/web3/index.mdx | 6 +- tooling/wallets/index.mdx | 2 +- 13 files changed, 262 insertions(+), 94 deletions(-) create mode 100644 build-on-celo/fee-abstraction/add-fee-currency.mdx create mode 100644 build-on-celo/fee-abstraction/overview.mdx rename tooling/overview/fee-abstraction.mdx => build-on-celo/fee-abstraction/using-fee-abstraction.mdx (54%) diff --git a/build-on-celo/build-on-minipay/quickstart.mdx b/build-on-celo/build-on-minipay/quickstart.mdx index 2f9670f34..5dda18463 100644 --- a/build-on-celo/build-on-minipay/quickstart.mdx +++ b/build-on-celo/build-on-minipay/quickstart.mdx @@ -134,7 +134,7 @@ Request CELO testnet tokens from the Celo [faucet](https://faucet.celo.org/celo- ## Helpful Tips to Make Your Mini App MiniPay Compatible - MiniPay uses Custom [Fee Abstraction](/tooling/overview/fee-abstraction) based + MiniPay uses Custom [Fee Abstraction](/build-on-celo/fee-abstraction/overview) based transactions. We recommend using viem or wagmi as they provide native support for fee currency. diff --git a/build-on-celo/build-with-ai/overview.mdx b/build-on-celo/build-with-ai/overview.mdx index d7818e0fa..5a948bbbc 100644 --- a/build-on-celo/build-with-ai/overview.mdx +++ b/build-on-celo/build-with-ai/overview.mdx @@ -114,4 +114,4 @@ await sendUSDCWithFeeAbstraction("0xRecipient...", parseUnits("1", 6)); | USDT | Mainnet | [`0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e`](https://celoscan.io/address/0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e) | [`0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72`](https://celoscan.io/address/0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72) | | USDC | Sepolia | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://sepolia.celoscan.io/address/0x2f25deb3848c207fc8e0c34035b3ba7fc157602b) | [`0x4822e58de6f5e485eF90df51C41CE01721331dC0`](https://sepolia.celoscan.io/address/0x4822e58de6f5e485eF90df51C41CE01721331dC0) | -For the full guide — including gas estimation, CIP-64 transaction types, and CLI usage — see [Implementing Fee Abstraction](/tooling/overview/fee-abstraction). +For the full guide — including gas estimation, CIP-64 transaction types, and CLI usage — see [Fee Abstraction](/build-on-celo/fee-abstraction/using-fee-abstraction). diff --git a/build-on-celo/build-with-ai/x402.mdx b/build-on-celo/build-with-ai/x402.mdx index df0debb31..724e0ad01 100644 --- a/build-on-celo/build-with-ai/x402.mdx +++ b/build-on-celo/build-with-ai/x402.mdx @@ -337,4 +337,4 @@ app.get("/articles/:id", async (req, res) => { - [ERC-8004](/build-on-celo/build-with-ai/8004) - Trust layer for AI agents - [Agent Skills](/build-on-celo/build-with-ai/agent-skills) - Modular agent capabilities -- [Fee Abstraction](/tooling/overview/fee-abstraction) - Pay gas with stablecoins on Celo +- [Fee Abstraction](/build-on-celo/fee-abstraction/overview) - Pay gas with stablecoins on Celo diff --git a/build-on-celo/fee-abstraction/add-fee-currency.mdx b/build-on-celo/fee-abstraction/add-fee-currency.mdx new file mode 100644 index 000000000..126403bb0 --- /dev/null +++ b/build-on-celo/fee-abstraction/add-fee-currency.mdx @@ -0,0 +1,151 @@ +--- +title: Adding Fee Currencies +sidebarTitle: "Adding Fee Currencies" +og:description: How to implement and register a new ERC20 token as a fee currency on Celo +--- + +Any ERC20 token can become a fee currency on Celo by implementing the `IFeeCurrency` interface and being added to the on-chain allowlist through governance. This guide explains the interface requirements and walks through an example implementation. + +For background on how fee abstraction works, see the [Overview](/build-on-celo/fee-abstraction/overview). + +--- + +## The IFeeCurrency Interface + +Fee currencies must implement the [IFeeCurrency](https://github.com/celo-org/fee-currency-example/blob/main/src/IFeeCurrency.sol) interface, which extends ERC20 with two additional functions used by the Celo blockchain to debit and credit gas fees. + +When a [CIP-64](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) transaction is executed: + +1. **Before execution** — the blockchain calls `debitGasFees` to reserve the maximum gas the transaction can spend +2. **After execution** — the blockchain calls `creditGasFees` to refund unused gas and distribute fees to the appropriate recipients + +### debitGasFees + +```solidity +function debitGasFees(address from, uint256 value) external; +``` + +Called before transaction execution to reserve the maximum gas amount. + +- Must deduct `value` from `from`'s balance +- Must revert if `msg.sender` is not `address(0)` (only the VM may call this) + +### creditGasFees + +There are two versions of `creditGasFees`. Both should be implemented for compatibility. + +**New signature** (used once all fee currencies have migrated): +```solidity +function creditGasFees(address[] calldata recipients, uint256[] calldata amounts) external; +``` + +- Must credit each `recipient` the corresponding `amount` +- Must revert if `msg.sender` is not `address(0)` +- Must revert if `recipients` and `amounts` have different lengths + +**Legacy signature** (for backwards compatibility): +```solidity +function creditGasFees( + address refundRecipient, + address tipRecipient, + address _gatewayFeeRecipient, + address baseFeeRecipient, + uint256 refundAmount, + uint256 tipAmount, + uint256 _gatewayFeeAmount, + uint256 baseFeeAmount +) external; +``` + +- `_gatewayFeeRecipient` and `_gatewayFeeAmount` are deprecated and will always be zero +- Must revert if `msg.sender` is not `address(0)` + +--- + +## Example Implementation + +The following example from [celo-org/fee-currency-example](https://github.com/celo-org/fee-currency-example) shows a minimal fee currency token using OpenZeppelin's ERC20 with burn/mint mechanics for gas fee handling: + +```solidity +pragma solidity ^0.8.13; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import {IFeeCurrency} from "./IFeeCurrency.sol"; + +contract FeeCurrency is ERC20, IFeeCurrency { + constructor(uint256 initialSupply) ERC20("ExampleFeeCurrency", "EFC") { + _mint(msg.sender, initialSupply); + } + + modifier onlyVm() { + require(msg.sender == address(0), "Only VM can call"); + _; + } + + function debitGasFees(address from, uint256 value) external onlyVm { + _burn(from, value); + } + + // New function signature + function creditGasFees( + address[] calldata recipients, + uint256[] calldata amounts + ) public onlyVm { + require( + recipients.length == amounts.length, + "Recipients and amounts must be the same length." + ); + + for (uint256 i = 0; i < recipients.length; i++) { + _mint(recipients[i], amounts[i]); + } + } + + // Legacy function signature for backwards compatibility + function creditGasFees( + address from, + address feeRecipient, + address, // gatewayFeeRecipient, unused + address communityFund, + uint256 refund, + uint256 tipTxFee, + uint256, // gatewayFee, unused + uint256 baseTxFee + ) public onlyVm { + _mint(from, refund); + _mint(feeRecipient, tipTxFee); + _mint(communityFund, baseTxFee); + } +} +``` + +This implementation uses `_burn` in `debitGasFees` and `_mint` in `creditGasFees` to handle the gas fee lifecycle. The `onlyVm` modifier ensures only the blockchain itself (via `address(0)`) can call these functions. + +--- + +## Testing + +Use [Foundry](https://book.getfoundry.sh/) to test your fee currency implementation. The [fee-currency-example](https://github.com/celo-org/fee-currency-example) repository includes a test suite you can use as a starting point: + +```bash +git clone https://github.com/celo-org/fee-currency-example.git +cd fee-currency-example +forge build +forge test +``` + +Key things to test: + +- `debitGasFees` correctly reduces the sender's balance +- `debitGasFees` reverts when called by any address other than `address(0)` +- Both `creditGasFees` signatures correctly credit all recipients +- `creditGasFees` reverts when called by any address other than `address(0)` +- The total debited amount equals the total credited amount across a transaction lifecycle + +--- + +## Registering a Fee Currency + +Once your token implements `IFeeCurrency`, it must be added to the on-chain allowlist in [**FeeCurrencyDirectory.sol**](/tooling/contracts/core-contracts) through a governance proposal. The governance process ensures that fee currencies meet the necessary requirements for network stability. + +If your token uses decimals other than 18, you will also need to deploy an adapter contract. See [Adapters for Non-18-Decimal Tokens](/build-on-celo/fee-abstraction/overview#adapters-for-non-18-decimal-tokens) for details. diff --git a/build-on-celo/fee-abstraction/overview.mdx b/build-on-celo/fee-abstraction/overview.mdx new file mode 100644 index 000000000..cd944e855 --- /dev/null +++ b/build-on-celo/fee-abstraction/overview.mdx @@ -0,0 +1,62 @@ +--- +title: Fee Abstraction +sidebarTitle: "Overview" +og:description: Pay gas fees using ERC20 tokens instead of the native CELO token +--- + +Celo allows users to pay gas fees in currencies other than the native CELO token. This feature, known as fee abstraction, means users never need to hold CELO to transact on the network. + +To use an alternate fee currency, set its token or adapter address as the `feeCurrency` property on the transaction object. This field is exclusive to Celo. Leaving it empty defaults to CELO. Note that transactions specifying a non-CELO fee currency cost approximately 50,000 additional gas. + +--- + +## Allowlisted Fee Currencies + +The protocol maintains a governable allowlist of smart contract addresses that can be used as fee currencies. These contracts implement an extension of the ERC20 interface with additional functions for debiting and crediting transaction fees (see [Adding Fee Currencies](/build-on-celo/fee-abstraction/add-fee-currency)). + +To fetch the current allowlist, call `getCurrencies()` on the `FeeCurrencyDirectory` contract, or use `celocli`: +```bash +# Celo Sepolia testnet +celocli network:whitelist --node celo-sepolia + +# Celo mainnet +celocli network:whitelist --node https://forno.celo.org +``` + +--- + +## Adapters for Non-18-Decimal Tokens + +After Contract Release 11, allowlisted addresses may be **adapters** rather than full ERC20 tokens. Adapters are used when a token has decimals other than 18 (e.g., USDC and USDT use 6 decimals). The Celo blockchain calculates gas pricing in 18 decimals, so adapters normalize the value. + +- **For transfers**: use the token address as usual. +- **For `feeCurrency`**: use the adapter address. +- **For `balanceOf`**: querying via the adapter returns the balance as if the token had 18 decimals — useful for checking whether an account can cover gas without converting units. + +To get the underlying token address for an adapter, call `adaptedToken()` on the adapter contract. + +For more on gas pricing, see [Gas Pricing](/legacy/protocol/transaction/gas-pricing). + +### Adapter Addresses + +#### Mainnet + +| Name | Token Address | Adapter Address | +| ------ | ------------- | --------------- | +| `USDC` | [`0xcebA9300f2b948710d2653dD7B07f33A8B32118C`](https://celoscan.io/address/0xcebA9300f2b948710d2653dD7B07f33A8B32118C#code) | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://celoscan.io/address/0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B#code) | +| `USDT` | [`0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e`](https://celoscan.io/address/0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e#code) | [`0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72`](https://celoscan.io/address/0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72#code) | + +#### Celo Sepolia (Testnet) + +| Name | Token Address | Adapter Address | +| ------ | ------------- | --------------- | +| `USDC` | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://sepolia.celoscan.io/address/0x2f25deb3848c207fc8e0c34035b3ba7fc157602b#code) | [`0x4822e58de6f5e485eF90df51C41CE01721331dC0`](https://sepolia.celoscan.io/address/0x4822e58de6f5e485eF90df51C41CE01721331dC0#code) | + +--- + +## Related + +- [Fee Abstraction for AI Agents](/build-on-celo/build-with-ai/overview#fee-abstraction-for-agents) — Using fee abstraction in autonomous agent backends +- [x402: Agent Payments](/build-on-celo/build-with-ai/x402) — HTTP-native stablecoin payments for agents +- [Using Fee Abstraction](/build-on-celo/fee-abstraction/using-fee-abstraction) — How to pay gas with alternate fee currencies in your transactions +- [Adding Fee Currencies](/build-on-celo/fee-abstraction/add-fee-currency) — How to implement and register a new fee currency diff --git a/tooling/overview/fee-abstraction.mdx b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx similarity index 54% rename from tooling/overview/fee-abstraction.mdx rename to build-on-celo/fee-abstraction/using-fee-abstraction.mdx index ea89983f5..ec606c38b 100644 --- a/tooling/overview/fee-abstraction.mdx +++ b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx @@ -1,77 +1,14 @@ --- -title: Implementing Fee Abstraction in Wallets -og:description: How to allow your wallet users to pay for gas fees using alternate fee currencies -sidebarTitle: "Fee Abstraction" +title: Using Fee Abstraction in Transactions +sidebarTitle: "Using Fee Abstraction" +og:description: How to pay gas fees using alternate fee currencies on Celo with viem and celocli --- -Celo allows users to pay gas fees in currencies other than the native CELO token. The list of accepted tokens is governed on-chain and maintained in [**FeeCurrencyDirectory.sol**](/contracts/core-contracts). - -To use an alternate fee currency, set its token or adapter address as the `feeCurrency` property on the transaction object. This field is exclusive to Celo. Leaving it empty defaults to CELO. Note that transactions specifying a non-CELO fee currency cost approximately 50,000 additional gas. +This guide shows how to send transactions that pay gas fees in ERC20 tokens instead of CELO. For background on how fee abstraction works, see the [Overview](/build-on-celo/fee-abstraction/overview). --- -## Allowlisted Fee Currencies - -The protocol maintains a governable allowlist of smart contract addresses that implement an extension of the ERC20 interface, with additional functions for debiting and crediting transaction fees. - -To fetch the current allowlist, call `getCurrencies()` on the `FeeCurrencyDirectory` contract, or use `celocli`: -```bash -# Celo Sepolia testnet -celocli network:whitelist --node celo-sepolia - -# Celo mainnet -celocli network:whitelist --node https://forno.celo.org -``` - ---- - -## Adapters for Non-18-Decimal Tokens - -After Contract Release 11, allowlisted addresses may be **adapters** rather than full ERC20 tokens. Adapters are used when a token has decimals other than 18 (e.g., USDC and USDT use 6 decimals). The Celo blockchain calculates gas pricing in 18 decimals, so adapters normalize the value. - -- **For transfers**: use the token address as usual. -- **For `feeCurrency`**: use the adapter address. -- **For `balanceOf`**: querying via the adapter returns the balance as if the token had 18 decimals — useful for checking whether an account can cover gas without converting units. - -To get the underlying token address for an adapter, call `adaptedToken()` on the adapter contract. - -For more on gas pricing, see [Gas Pricing](/legacy/protocol/transaction/gas-pricing). - -### Adapter Addresses - -#### Mainnet - -| Name | Token Address | Adapter Address | -| ------ | ------------- | --------------- | -| `USDC` | [`0xcebA9300f2b948710d2653dD7B07f33A8B32118C`](https://celoscan.io/address/0xcebA9300f2b948710d2653dD7B07f33A8B32118C#code) | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://celoscan.io/address/0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B#code) | -| `USDT` | [`0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e`](https://celoscan.io/address/0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e#code) | [`0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72`](https://celoscan.io/address/0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72#code) | - -#### Celo Sepolia (Testnet) - -| Name | Token Address | Adapter Address | -| ------ | ------------- | --------------- | -| `USDC` | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://sepolia.celoscan.io/address/0x2f25deb3848c207fc8e0c34035b3ba7fc157602b#code) | [`0x4822e58de6f5e485eF90df51C41CE01721331dC0`](https://sepolia.celoscan.io/address/0x4822e58de6f5e485eF90df51C41CE01721331dC0#code) | - ---- - -## Using Fee Abstraction with Celo CLI - -Transfer 1 USDC using USDC as the fee currency via [`celocli`](/cli): -```bash -celocli transfer:erc20 \ - --erc20Address 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B \ - --from 0x22ae7Cf4cD59773f058B685a7e6B7E0984C54966 \ - --to 0xDF7d8B197EB130cF68809730b0D41999A830c4d7 \ - --value 1000000 \ - --gasCurrency 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B \ - --privateKey [PRIVATE_KEY] -``` - -When using USDC or USDT, use the adapter address (not the token address) to avoid inaccuracies caused by their 6-decimal precision. - ---- - -## Using Fee Abstraction with viem +## Using viem We recommend [viem](https://viem.sh/), which has native support for the `feeCurrency` field. Ethers.js and web3.js do not currently support this field. @@ -85,7 +22,7 @@ The gas price returned from the RPC is always expressed in 18 decimals, regardle Use the adapter address (for USDC/USDT) or token address (for USDm, EURm, BRLm) as the `feeCurrency` value when estimating. ```js -import { createPublicClient, hexToBigInt, http } from "viem"; +import { createPublicClient, formatEther, hexToBigInt, http } from "viem"; import { celo } from "viem/chains"; const USDC_ADAPTER_MAINNET = "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B"; @@ -111,11 +48,10 @@ async function getGasPriceInUSDC() { } async function estimateGasInUSDC(transaction) { - const estimatedGasInHex = await publicClient.estimateGas({ + return await publicClient.estimateGas({ ...transaction, feeCurrency: USDC_ADAPTER_MAINNET, }); - return hexToBigInt(estimatedGasInHex); } async function main() { @@ -143,7 +79,7 @@ let tx = { The example below transfers 1 USDC, subtracting the estimated fee from the transfer amount so the sender's full balance is not over-spent. ```js -import { createWalletClient, http } from "viem"; +import { createWalletClient, encodeFunctionData, http, parseEther } from "viem"; import { celo } from "viem/chains"; import { privateKeyToAccount } from "viem/accounts"; import { stableTokenAbi } from "@celo/abis"; @@ -196,12 +132,20 @@ async function send(amountInWei) { --- ---- +## Using Celo CLI -## Related +Transfer 1 USDC using USDC as the fee currency via [`celocli`](/cli): +```bash +celocli transfer:erc20 \ + --erc20Address 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B \ + --from 0x22ae7Cf4cD59773f058B685a7e6B7E0984C54966 \ + --to 0xDF7d8B197EB130cF68809730b0D41999A830c4d7 \ + --value 1000000 \ + --gasCurrency 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B \ + --privateKey [PRIVATE_KEY] +``` -- [Fee Abstraction for AI Agents](/build-on-celo/build-with-ai/overview#fee-abstraction-for-agents) — Using fee abstraction in autonomous agent backends -- [x402: Agent Payments](/build-on-celo/build-with-ai/x402) — HTTP-native stablecoin payments for agents +When using USDC or USDT, use the adapter address (not the token address) to avoid inaccuracies caused by their 6-decimal precision. --- diff --git a/build-on-celo/index.mdx b/build-on-celo/index.mdx index 65734cd7d..a33e281ac 100644 --- a/build-on-celo/index.mdx +++ b/build-on-celo/index.mdx @@ -15,7 +15,7 @@ Whether you're building your first dApp or looking to integrate an existing prot - **EVM Compatibile:** Celo is fully EVM-compatible, offering the same development experience as Ethereum with improved scalability and lower costs. - **Fast Transactions:** After the migrations to an L2 Celo now has a **1-second block finality** compared to formerly 5 seconds. -- **Easy, Low-Cost Payments:** Celo's seamless payment infrastructure, including [Fee Abstraction](/developer/fee-abstraction), **sub-cent fees**, and **native stablecoins**, enables simple and affordable transactions. +- **Easy, Low-Cost Payments:** Celo's seamless payment infrastructure, including [Fee Abstraction](/build-on-celo/fee-abstraction/overview), **sub-cent fees**, and **native stablecoins**, enables simple and affordable transactions. - **Global Reach:** Celo provides access to more than **8 million real-world users** with some dApps having more than **200,000 DAUs**. ## Getting Started diff --git a/docs.json b/docs.json index f003dbdb0..8e0cf2859 100644 --- a/docs.json +++ b/docs.json @@ -171,6 +171,14 @@ "build-on-celo/build-with-local-stablecoin", "build-on-celo/build-with-defi" ] + }, + { + "group": "Fee Abstraction", + "pages": [ + "build-on-celo/fee-abstraction/overview", + "build-on-celo/fee-abstraction/using-fee-abstraction", + "build-on-celo/fee-abstraction/add-fee-currency" + ] } ] }, @@ -182,7 +190,6 @@ "pages": [ "tooling/overview/index", "tooling/overview/faucet", - "tooling/overview/fee-abstraction", "tooling/bridges/bridges", "tooling/bridges/cross-chain-messaging", "tooling/testnets/celo-sepolia/index" @@ -677,7 +684,11 @@ }, { "source": "/cel2/guides/fee-abstraction", - "destination": "/tooling/overview/fee-abstraction" + "destination": "/build-on-celo/fee-abstraction/overview" + }, + { + "source": "/tooling/overview/fee-abstraction", + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/celo-codebase/protocol", @@ -1725,7 +1736,7 @@ }, { "source": "/developer/fee-currency", - "destination": "/tooling/overview/fee-abstraction" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/developer/indexer", @@ -2185,7 +2196,7 @@ }, { "source": "/protocol/transaction/erc20-transaction-fees", - "destination": "/tooling/overview/fee-abstraction" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/protocol/transaction/escrow", @@ -2193,7 +2204,7 @@ }, { "source": "/protocol/transaction/gas-pricing", - "destination": "/tooling/overview/fee-abstraction" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/protocol/transaction/native-currency", @@ -2565,7 +2576,7 @@ }, { "source": "/developer/fee-abstraction", - "destination": "/tooling/overview/fee-abstraction" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/developer/launch-checklist", diff --git a/home/protocol/transactions/overview.mdx b/home/protocol/transactions/overview.mdx index 72b876f96..0551587e8 100644 --- a/home/protocol/transactions/overview.mdx +++ b/home/protocol/transactions/overview.mdx @@ -28,7 +28,7 @@ gas currencies incur approximately 50,000 additional gas units. Celo allows paying gas fees in currencies other than the native currency. The tokens that can be used to pay gas fees are controlled via governance and the list of tokens allowed is maintained in FeeCurrencyDirectory.sol. Fee abstraction on Celo works with EOAs. No paymaster required! Learn all -about [fee abstraction](/developer/fee-abstraction). +about [fee abstraction](/build-on-celo/fee-abstraction/overview). ## Transaction Fee Allocation Post-L2 Transition diff --git a/home/wallets.mdx b/home/wallets.mdx index a3dc07fcd..78e03f06b 100644 --- a/home/wallets.mdx +++ b/home/wallets.mdx @@ -11,7 +11,7 @@ Overview of digital wallets available to send, spend, and earn Celo assets. Celo is designed to work seamlessly with a range of wallets, each offering features to meet different user needs. -The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/developer/fee-abstraction). +The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/build-on-celo/fee-abstraction/overview). The [Celo Compatible Wallets](#celo-compatible-wallets) section provides an overview of commonly used wallets wallets that support the Celo network. diff --git a/tooling/libraries-sdks/ethers/index.mdx b/tooling/libraries-sdks/ethers/index.mdx index fdc0cbed9..a522b4daf 100644 --- a/tooling/libraries-sdks/ethers/index.mdx +++ b/tooling/libraries-sdks/ethers/index.mdx @@ -4,9 +4,9 @@ og:description: A minimal wrapper to make Ethers.JS compatible with the Celo net --- -When using Ethers.js on Celo, we suggest using the Celo Ethers.js Wrapper to make Ethers.JS compatible with the Celo network. This means being able to handle [fee abstraction](/developer/fee-abstraction) when opened in MiniPay/ Valora. +When using Ethers.js on Celo, we suggest using the Celo Ethers.js Wrapper to make Ethers.JS compatible with the Celo network. This means being able to handle [fee abstraction](/build-on-celo/fee-abstraction/overview) when opened in MiniPay/ Valora. -[Fee Abstraction](/developer/fee-abstraction) on Celo enables the use of stablecoins like cUSD, USDT and USDC as gas tokens. +[Fee Abstraction](/build-on-celo/fee-abstraction/overview) on Celo enables the use of stablecoins like cUSD, USDT and USDC as gas tokens. ## Celo Ethers.JS Wrapper diff --git a/tooling/libraries-sdks/web3/index.mdx b/tooling/libraries-sdks/web3/index.mdx index 421966aac..b43a2cc4b 100644 --- a/tooling/libraries-sdks/web3/index.mdx +++ b/tooling/libraries-sdks/web3/index.mdx @@ -11,13 +11,13 @@ sidebarTitle: "Web3.js (deprecated)" Web3.js has been sunset in 2024. Please consider using [thirdweb](https://thirdweb.com/?utm_source=celo&utm_medium=documentation&utm_campaign=chain_docs) or viem for your project. -Web3.js was established in 2014, making it the oldest web3 library. With extensive documentation, an active community and modular design, Web3.js is powerful and easy-to-use. It has _support for Celo features (specifically **[Fee Abstraction](/developer/fee-abstraction)** via plugins since version 4.13.1_. +Web3.js was established in 2014, making it the oldest web3 library. With extensive documentation, an active community and modular design, Web3.js is powerful and easy-to-use. It has _support for Celo features (specifically **[Fee Abstraction](/build-on-celo/fee-abstraction/overview)** via plugins since version 4.13.1_. To learn more about building with Web3.js, check out their [docs](https://docs.web3js.org/) as they have excellent examples of how to use it in your project. ### Fee Abstraction with Web3.js -[Fee Abstraction](/developer/fee-abstraction) on Celo enables the use of stablecoins like cUSD, USDT and USDC as gas tokens. +[Fee Abstraction](/build-on-celo/fee-abstraction/overview) on Celo enables the use of stablecoins like cUSD, USDT and USDC as gas tokens. #### Requirements @@ -25,7 +25,7 @@ To learn more about building with Web3.js, check out their [docs](https://docs.w #### Install the Celo Web3.js Plugin -For Celo' specific features like [Fee Abstraction](/developer/fee-abstraction) transactions you need to install `@celo/web3-plugin-transaction-types` as well as `web3@4.13.1` or higher. This also adds utils like `getCoreContractAddress` for fetching core contract address from onchain registry. This is useful to get the stablecoin addresses you are planning to use programmatically. Make sure they are listed in the [**FeeCurrencyDirectory.sol**](/contracts/core-contracts). +For Celo' specific features like [Fee Abstraction](/build-on-celo/fee-abstraction/overview) transactions you need to install `@celo/web3-plugin-transaction-types` as well as `web3@4.13.1` or higher. This also adds utils like `getCoreContractAddress` for fetching core contract address from onchain registry. This is useful to get the stablecoin addresses you are planning to use programmatically. Make sure they are listed in the [**FeeCurrencyDirectory.sol**](/contracts/core-contracts). {/* prettier-ignore-start */} diff --git a/tooling/wallets/index.mdx b/tooling/wallets/index.mdx index 96a370d1e..0cec4ea05 100644 --- a/tooling/wallets/index.mdx +++ b/tooling/wallets/index.mdx @@ -12,7 +12,7 @@ Overview of digital wallets available to send, spend, and earn Celo assets. Celo is designed to work seamlessly with a range of wallets, each offering features to meet different user needs. -The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/developer/fee-abstraction). +The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/build-on-celo/fee-abstraction/overview). The [Wallet Infrastructure](#wallet-infrastructure) section provides an overview of wallet infrastructure solutions you can integrate into your dapp to enable seamless web3 interactions for your users. From a9a0f482d7fa8927476a3efa7bb244462088f7b3 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 27 Mar 2026 00:17:15 +0100 Subject: [PATCH 2/2] Flesh out fee abstraction overview Add sections explaining why fee abstraction matters, how it works at the protocol level, and key use cases. --- build-on-celo/fee-abstraction/overview.mdx | 26 ++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/build-on-celo/fee-abstraction/overview.mdx b/build-on-celo/fee-abstraction/overview.mdx index cd944e855..53762a4a8 100644 --- a/build-on-celo/fee-abstraction/overview.mdx +++ b/build-on-celo/fee-abstraction/overview.mdx @@ -4,9 +4,31 @@ sidebarTitle: "Overview" og:description: Pay gas fees using ERC20 tokens instead of the native CELO token --- -Celo allows users to pay gas fees in currencies other than the native CELO token. This feature, known as fee abstraction, means users never need to hold CELO to transact on the network. +Fee abstraction is one of Celo's core protocol features. It allows users to pay gas fees in ERC20 tokens — like USDC, USDT, or Mento stablecoins — instead of needing to hold the native CELO token. -To use an alternate fee currency, set its token or adapter address as the `feeCurrency` property on the transaction object. This field is exclusive to Celo. Leaving it empty defaults to CELO. Note that transactions specifying a non-CELO fee currency cost approximately 50,000 additional gas. +## Why Fee Abstraction Matters + +On most EVM chains, users must hold the native token to pay for gas. This creates friction: a user who receives USDC on Celo can't send it anywhere without first acquiring CELO. Fee abstraction removes this barrier entirely. + +With fee abstraction, a user holding only USDC can send transactions, interact with contracts, and pay gas — all in USDC. No bridging, no swaps, no extra steps. This is especially valuable for: + +- **Onboarding new users** who receive stablecoins but don't know about gas tokens +- **Payment applications** where users transact in a single currency end-to-end +- **AI agents** that operate autonomously with a single token balance + +## How It Works + +Fee abstraction is built into the Celo protocol at the node level — it is not a paymaster or relayer. When a transaction includes a `feeCurrency` field, the Celo blockchain: + +1. Calls `debitGasFees` on the fee currency contract to reserve the maximum gas cost +2. Executes the transaction normally +3. Calls `creditGasFees` to refund unused gas and distribute fees to block producers + +This means fee abstraction works with any externally owned account (EOA). No smart contract wallets, no relayers, no extra infrastructure needed. + +To use an alternate fee currency, set its token or adapter address as the `feeCurrency` property on the transaction object. + +For implementation details, see [Using Fee Abstraction](/build-on-celo/fee-abstraction/using-fee-abstraction). To add a new fee currency to the protocol, see [Adding Fee Currencies](/build-on-celo/fee-abstraction/add-fee-currency). ---