diff --git a/build-on-celo/build-on-minipay/overview.mdx b/build-on-celo/build-on-minipay/overview.mdx index 25bc142e7..46314d43e 100644 --- a/build-on-celo/build-on-minipay/overview.mdx +++ b/build-on-celo/build-on-minipay/overview.mdx @@ -48,7 +48,7 @@ const hash = await walletClient.sendTransaction({ Testnet addresses are on [Fee currency contracts](/tooling/contracts/fee-currencies). -### Gas is paid in the user's stablecoin +### Gas is paid in stablecoins MiniPay uses [fee abstraction](/build-on-celo/fee-abstraction/overview): the user never holds CELO, and the wallet pays gas in the stablecoin the user holds the most of. You may set `feeCurrency` on `eth_sendTransaction`, but MiniPay can override it. Do not build flows that assume a CELO balance, and do not show a "buy CELO for gas" step. diff --git a/build-on-celo/fee-abstraction/overview.mdx b/build-on-celo/fee-abstraction/overview.mdx index 8081b6747..6a4e2a1d2 100644 --- a/build-on-celo/fee-abstraction/overview.mdx +++ b/build-on-celo/fee-abstraction/overview.mdx @@ -1,7 +1,7 @@ --- title: Fee Abstraction sidebarTitle: "Overview" -description: Pay gas fees using ERC20 tokens instead of the native CELO token +description: Pay gas fees in ERC20 tokens instead of CELO, how the protocol charges them, and which wallets build the CIP-64 transaction that makes it work --- 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. @@ -24,12 +24,31 @@ Fee abstraction is built into the Celo protocol at the node level — it is not 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. +This means fee abstraction works with any externally owned account (EOA) at the protocol level. 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). +## Wallet support for CIP-64 + +The protocol accepts a `feeCurrency` transaction from any account, but something has to build that transaction. `feeCurrency` is a field on the [CIP-64](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) transaction type, so the wallet signing it must implement CIP-64. Setting `feeCurrency` in your dApp is necessary but not sufficient: whether it takes effect is decided by the wallet your user brings. + + + A wallet without CIP-64 support does not honour `feeCurrency`, and nothing tells you so. Most drop the field and sign a standard transaction, as MetaMask does: gas then comes out of the user's CELO balance, or, if the user holds no CELO, the transaction fails with a generic insufficient-funds error. A wallet that validates request parameters may instead reject the request outright. None of these outcomes points at the wallet as the cause. + + +| Wallet | How `feeCurrency` is handled | +|---|---| +| [MiniPay](/build-on-celo/build-on-minipay/overview) | Pays gas in the stablecoin the user holds the most of, and [may override](/build-on-celo/build-on-minipay/overview#gas-is-paid-in-stablecoins) a `feeCurrency` you set | +| [Valora](https://valora.xyz/) | Builds CIP-64 itself and ignores a `feeCurrency` you set. It re-selects, paying in CELO when the balance covers the fee and otherwise in the fee currency the user holds the most of by value. Confirmed in the [wallet source](https://github.com/valora-xyz/wallet-stack/blob/main/packages/wallet-stack/src/walletConnect/saga.ts) | +| [Ledger Live](/tooling/wallets/ledger/setup) | Ledger Live's own send flow builds CIP-64 and lets the user choose the fee currency. Needs Ledger Live 4.8 or later and Celo app 1.8 or later. This does not extend to dApps: a Ledger used through MetaMask signs what MetaMask builds, and MetaMask drops `feeCurrency` | +| [MetaMask](/tooling/wallets/metamask/setup) | Not supported. The [transaction controller](https://github.com/MetaMask/core/blob/main/packages/transaction-controller/src/utils/utils.ts) keeps only the fields it knows, so `feeCurrency` is dropped and gas is charged in CELO | + +A wallet not listed here has not been confirmed either way. Check with the wallet before assuming. If a flow depends on fee abstraction, such as onboarding a user who holds no CELO, either target a wallet on this list or keep a path that works when gas is charged in CELO. + +Library support is a separate question from wallet support, and a library in a wallet's stack says nothing about whether that wallet forwards a dApp's `feeCurrency`. For viem, Ethers.js and web3.js, see [Using Fee Abstraction](/build-on-celo/fee-abstraction/using-fee-abstraction#using-fee-abstraction-with-viem). + ## Whitelisted Fee Currencies (Mainnet) The full up-to-date list of whitelisted fee currencies — including token and adapter addresses — is automatically maintained at [Fee Currencies](/tooling/contracts/fee-currencies). @@ -44,3 +63,4 @@ Tokens with non-18 decimals (e.g. USDC, USD₮, USA₮ with 6 decimals) require - [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 +- [Celo Wallets](/tooling/wallets) — The wallets Celo documents, including the ones in the table above diff --git a/build-on-celo/fee-abstraction/using-fee-abstraction.mdx b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx index bd74aa993..4ff799d47 100644 --- a/build-on-celo/fee-abstraction/using-fee-abstraction.mdx +++ b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx @@ -71,7 +71,7 @@ celocli transfer:erc20 \ ## Using Fee Abstraction with 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. +We recommend [viem](https://viem.sh/), which serializes CIP-64 natively when you pass a Celo chain from `viem/chains`. Ethers.js and web3.js do not support the field on their own; use the [Celo Ethers.js wrapper](/tooling/libraries-sdks/ethers) or the [web3 transaction-types plugin](/tooling/libraries-sdks/web3). Whichever library you use, the wallet that signs the transaction must also support CIP-64; see [wallet support](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64). ### 1. Estimate the Gas Fee diff --git a/home/wallets.mdx b/home/wallets.mdx index 215e33ec7..af600ce27 100644 --- a/home/wallets.mdx +++ b/home/wallets.mdx @@ -13,7 +13,11 @@ Celo is designed to work seamlessly with a range of wallets, each offering featu 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](/build-on-celo/build-on-socialconnect) 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. + + **Fee abstraction depends on the wallet.** Paying gas in stablecoins requires the wallet to build a CIP-64 transaction. A wallet without that support charges gas in CELO instead. See [which wallets support it](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64). + + +The [Celo Compatible Wallets](#celo-compatible-wallets) section provides an overview of commonly used wallets that support the Celo network. ## Celo Native Wallets @@ -26,7 +30,7 @@ MiniPay is a non-custodial lightweight mobile wallet that allows users to send a - [Homepage](https://www.opera.com/products/minipay) - Platforms: [Android](https://play.google.com/store/apps/details?id=com.opera.minipay), [iOS](https://apps.apple.com/de/app/minipay-easy-global-wallet/id6504087257?l=en-GB), inside [Opera Mini](https://play.google.com/store/apps/details?id=com.opera.mini.native) in Ghana, Nigeria, Kenya, South Africa, and Uganda - Maintainers: Opera -- Ledger support: No +- Hardware wallet support: No - Supported tokens: USDm, USDT, and USDC --- @@ -38,7 +42,7 @@ Valora is a non-custodial multichain mobile wallet focused on helping users save - [Homepage](https://valora.xyz/) - Platforms: [iOS](https://apps.apple.com/us/app/valora-crypto-wallet/id1520414263?mt=8), [Android](https://play.google.com/store/apps/details?id=co.clabs.valora) - Maintainers: [Valora](https://valora.xyz/) -- Ledger support: No +- Hardware wallet support: No - [Source Code](https://github.com/valora-inc/wallet) --- @@ -50,14 +54,28 @@ Celo Terminal is a wallet and dApp platform designed as a hub for managing and r - Homepage: [celoterminal.com](https://celoterminal.com) - Platforms: MacOS, Linux, Windows - Maintainers: [WOTrust](https://x.com/wotrust1) -- Ledger support: Yes (Note: [EIP-712 signing requires workaround](/wallet/ledger/eip712-workaround)) +- Hardware wallet support: Yes (Note: [EIP-712 signing requires workaround](/wallet/ledger/eip712-workaround)) - [Source Code](https://github.com/zviadm/celoterminal) --- +## Hardware Wallets + +--- + +### [Ledger](https://www.ledger.com/) + +Ledger is a hardware wallet. Ledger Live supports CELO and Celo stablecoins, and its send flow can pay gas in a Celo fee currency of the user's choice, with Ledger Live 4.8 or later and Celo app 1.8 or later. dApp transactions signed with a Ledger through MetaMask are not CIP-64, because MetaMask drops `feeCurrency`; see [wallet support for CIP-64](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64). + +- [Homepage](https://www.ledger.com/) +- Platforms: Ledger Live (desktop, mobile) with a Ledger device +- [Set up a Ledger with Celo](/tooling/wallets/ledger/setup) + +--- + ## Celo Compatible Wallets -Here’s an overview of popular wallets compatible with the Celo network. Note that some wallets do not support fee abstraction for gas payments with different tokens. +Here’s an overview of popular wallets compatible with the Celo network. Not all of them support [fee abstraction](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64), so gas may be charged in CELO. ### [Rabby](https://rabby.io/) diff --git a/tooling/wallets/index.mdx b/tooling/wallets/index.mdx index 5c55a958d..e8ee87b14 100644 --- a/tooling/wallets/index.mdx +++ b/tooling/wallets/index.mdx @@ -10,6 +10,10 @@ Celo is designed to work seamlessly with a range of wallets, each offering featu 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](/build-on-celo/build-on-socialconnect) and [fee abstraction](/build-on-celo/fee-abstraction/overview). + + **Fee abstraction depends on the wallet.** Paying gas in stablecoins requires the wallet to build a CIP-64 transaction. A wallet without that support drops a dApp's `feeCurrency` without an error. See [which wallets support it](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64). + + 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. ## Celo Native Wallets @@ -25,7 +29,7 @@ MiniPay is a non-custodial lightweight mobile wallet that allows users to send a - Homepage: [opera.com/products/minipay](https://www.opera.com/products/minipay) - Platforms: [Android](https://play.google.com/store/apps/details?id=com.opera.minipay), [iOS](https://apps.apple.com/de/app/minipay-easy-global-wallet/id6504087257?l=en-GB), inside [Opera Mini](https://play.google.com/store/apps/details?id=com.opera.mini.native) in Ghana, Nigeria, Kenya, South Africa, and Uganda - Maintainers: Opera -- Ledger support: No +- Hardware wallet support: No - Supported tokens: USDm, USDT, and USDC - [Start building](/build-on-celo/build-on-minipay/overview) @@ -38,7 +42,7 @@ Valora is a non-custodial multichain mobile wallet focused on helping users save - Homepage: [valora.xyz](https://valora.xyz/) - Platforms: [iOS](https://apps.apple.com/us/app/valora-crypto-wallet/id1520414263?mt=8), [Android](https://play.google.com/store/apps/details?id=co.clabs.valora) - Maintainers: [Valora](https://valora.xyz/) -- Ledger support: No +- Hardware wallet support: No - [Source Code](https://github.com/valora-inc/wallet) @@ -51,10 +55,25 @@ Celo Terminal is a wallet and dApp platform designed as a hub for managing and r - Homepage: [celoterminal.com](https://celoterminal.com) - Platforms: MacOS, Linux, Windows - Maintainers: [WOTrust](https://x.com/wotrust1) -- Ledger support: Yes (Note: [EIP-712 signing requires workaround](/wallet/ledger/eip712-workaround)) +- Hardware wallet support: Yes (Note: [EIP-712 signing requires workaround](/wallet/ledger/eip712-workaround)) - [Source Code](https://github.com/zviadm/celoterminal) +## Hardware Wallets + +--- + +### [Ledger](https://www.ledger.com/) + +Ledger is a hardware wallet. Ledger Live supports CELO and Celo stablecoins, and its send flow can pay gas in a Celo fee currency of the user's choice, with Ledger Live 4.8 or later and Celo app 1.8 or later. dApp transactions signed with a Ledger through MetaMask are not CIP-64, because MetaMask drops `feeCurrency`; see [wallet support for CIP-64](/build-on-celo/fee-abstraction/overview#wallet-support-for-cip-64). + +- Homepage: [ledger.com](https://www.ledger.com/) +- Platforms: Ledger Live (desktop, mobile) with a Ledger device +- Maintainers: [Ledger](https://www.ledger.com/) +- Guides: [set up a Ledger with Celo](/tooling/wallets/ledger/setup), connect it to [Celo Terminal](/tooling/wallets/ledger/to-celo-terminal), the [Celo web wallet](/tooling/wallets/ledger/to-celo-web) or the [Celo CLI](/tooling/wallets/ledger/to-celo-cli), and the [EIP-712 signing workaround](/tooling/wallets/ledger/eip712-workaround) + +--- + ## Wallet Infrastructure Server wallets are a crucial part of building accessible applications. In the future of applications, you don't want to ask suers to login with a wallet but rather using their social logins like email account etc.