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
+ This transaction will be paid for by the Paymaster, not your ETH balance. +
+ + + + {error && ( +