From d2a4b1b7ecd9134062cd8d7ff3a47651bf83eb87 Mon Sep 17 00:00:00 2001 From: Jadonamite Date: Mon, 12 Jan 2026 16:16:20 +0100 Subject: [PATCH] Add gasless integration guide for Smart Wallets Added a comprehensive guide for gasless integration with Smart Wallets, covering account abstraction, implementation details, and troubleshooting common errors. --- .../smart-wallet/gasless-integration-guide.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/cookbook/smart-wallet/gasless-integration-guide.md diff --git a/docs/cookbook/smart-wallet/gasless-integration-guide.md b/docs/cookbook/smart-wallet/gasless-integration-guide.md new file mode 100644 index 00000000..daa49a41 --- /dev/null +++ b/docs/cookbook/smart-wallet/gasless-integration-guide.md @@ -0,0 +1,155 @@ +### Phase 1: The Content + +**The Paradigm Shift: Account Abstraction (ERC-4337)** +To build a "consumer-grade" application, you must eliminate the two biggest friction points in Web3: **Seed Phrases** and **Gas Fees**. + +1. **Smart Accounts vs. EOAs:** +* **EOA (Externally Owned Account):** A standard wallet (MetaMask) controlled by a private key. It is "dumb." It can only sign transactions. It cannot batch actions or perform logic. +* **Smart Account (Coinbase Smart Wallet):** The user's account is a Smart Contract deployed on the blockchain. Because it is code, it can be programmed. It can verify biometric signatures (Passkeys), execute multiple commands in one step (Batching), and allow third parties to pay its bills (Paymasters). + + +2. **The New Standard: EIP-5792** +Legacy applications use `eth_sendTransaction`. This implies the user holds ETH and signs a specific payload. +Modern applications use `wallet_sendCalls`. This requests the wallet to perform a set of actions. Crucially, it allows the application to attach **Capabilities**. The most important capability is the **Paymaster Service**, which tells the wallet: "Do not charge the user for this; send the bill to this URL instead." +3. **The Paymaster Architecture** +When a user "clicks" a button in a Smart Wallet app: +* They do not create a Transaction. They create a **UserOperation (UserOp)**. +* This UserOp is sent to a **Bundler** (a special node), not the Mempool. +* The Bundler asks the **Paymaster**: "Will you pay for this?" +* If yes, the Paymaster signs the operation. +* The Bundler submits the transaction to the blockchain, paying the ETH. The UserOp executes. + + + +--- + +### Phase 2: The Implementation + +**1. Configuration: Forcing the Smart Wallet Environment** +To strictly test Account Abstraction features (Passkeys and Gas Sponsorship), we configure Wagmi to prioritize the Coinbase Smart Wallet. + +**File:** `config/wagmi.ts` + +```typescript +import { http, createConfig } from 'wagmi'; +import { base } from 'wagmi/chains'; +import { coinbaseWallet } from 'wagmi/connectors'; + +export const config = createConfig({ + chains: [base], + transports: { + [base.id]: http(), + }, + connectors: [ + coinbaseWallet({ + appName: 'Base Smart App', + // 'smartWalletOnly' forces the "Create Passkey" flow. + // This is essential for testing AA features during development. + preference: 'smartWalletOnly', + }), + ], +}); + +``` + +**2. Implementation: The Gasless Transaction Hook** +We use `useSendCalls` (Wagmi Experimental) to leverage EIP-5792. This hook allows us to define the `paymasterService` capability. + +**Prerequisite:** You must obtain a Paymaster URL from the [Coinbase Developer Platform](https://portal.cdp.coinbase.com/). + +**File:** `components/GaslessAction.tsx` + +```tsx +'use client'; + +import { useSendCalls } from 'wagmi/experimental'; +import { useAccount } from 'wagmi'; +import { parseAbi, encodeFunctionData } from 'viem'; + +// Example Contract: A simple counter or mint function +const CONTRACT_ADDRESS = '0x...'; +const CONTRACT_ABI = parseAbi(['function performAction() external']); + +export default function GaslessAction() { + const { isConnected } = useAccount(); + const { sendCalls, status, error } = useSendCalls(); + + const handleGaslessTx = () => { + // 1. Define the capabilities object + // This tells the Smart Wallet: "Use this Paymaster URL to sponsor gas." + const capabilities = { + paymasterService: { + url: process.env.NEXT_PUBLIC_PAYMASTER_URL, // e.g., https://api.developer.coinbase.com/rpc/v1/base/... + }, + }; + + // 2. Submit the Call + sendCalls({ + calls: [ + { + to: CONTRACT_ADDRESS, + abi: CONTRACT_ABI, + functionName: 'performAction', + args: [], + }, + ], + capabilities, + }); + }; + + if (!isConnected) return
Please connect wallet
; + + return ( +
+

Sponsored Transaction

+

+ This transaction will be paid for by the Paymaster, not your ETH balance. +

+ + + + {error && ( +
+ Error: {error.message} +
+ )} +
+ ); +} + +``` + +--- + +### Phase 3: Troubleshooting Common AA Errors + +Smart Wallet transactions fail differently than standard Ethereum transactions. The error messages often relate to the Bundler or Paymaster policies. + +**1. Error: "Preverification gas low" (AA21)** + +* **The Symptom:** The transaction fails immediately when the user tries to sign. +* **The Cause:** The Bundler estimates gas based on a "standard" transaction size. However, Passkey signatures (WebAuthn) are significantly larger (300+ bytes) than standard private key signatures (65 bytes). The Bundler underestimates the data cost, and the network rejects the UserOp. +* **The Fix:** +1. **Update Bundler Config:** If running your own Bundler, update the configuration to support specific "UserOp Gas Limits" for Smart Accounts. +2. **Add Buffer:** In the Coinbase Developer Platform (Paymaster settings), increase the **Gas Limit Buffer**. This forces the Paymaster to allocate extra gas to cover the large signature size variance. + + + +**2. Error: "Paymaster policy rejected"** + +* **The Symptom:** The user signs, but the API returns a rejection. +* **The Cause:** The Paymaster is a gatekeeper. It checks an "Allowlist" before paying. +* **The Fix:** +1. **Allowlist the Contract:** Ensure the *exact* address of the contract you are interacting with is in the Policy Allowlist. +2. **Check Proxies:** If your contract is a Proxy, you usually need to allowlist the **Proxy Address**, not the Implementation Address. +3. **Check Daily Limits:** Paymasters often have a "Max ETH per Day" global limit. Ensure your project has not exhausted its sponsorship budget. + + + +---