Merge pull request #7 from bcnmy/feat/examples

feat: examples

Author: vr16x

README.md

@@ -17,6 +17,7 @@ With composable transactions, you describe what should happen — not just what
   - [Pre-conditions and post-conditions](#pre-conditions-and-post-conditions)
   - [Runtime values](#runtime-values)
   - [On-chain constraints](#on-chain-constraints)
+- [Examples](#examples)
 - [Installation](#installation)
 - [Smart Batching Core](#smart-batching-core)
   - [createComposableBatch](#createcomposablebatch)
@@ -289,6 +290,27 @@ This pattern is a slippage guard: the batch only proceeds if the post-swap balan
 
 ---
 
+## Examples
+
+End-to-end examples showing real-world DeFi flows. Each file is self-contained and runs against Base mainnet addresses.
+
+| Example | Description |
+|---------|-------------|
+| [01 — Safe ERC-20 transfer](./examples/01-safe-erc20-transfer.ts) | USDC transfer with sender pre-condition and recipient balance post-condition |
+| [02 — Aave deposit guarded](./examples/02-aave-deposit-guarded.ts) | Aave V3 deposit gated by balance and allowance pre-conditions |
+| [03 — Aave full deposit](./examples/03-aave-full-deposit.ts) | Atomic approve + Aave supply that sweeps the full runtime USDC balance |
+| [04 — Vault auto-compound](./examples/04-vault-auto-compound.ts) | ERC-4626 auto-compound with runtime balance and a deposit range guard |
+| [05 — Swap output guard](./examples/05-swap-output-guard.ts) | Uniswap V3 swap with a post-condition asserting minimum WETH received |
+| [06 — Compound debt repay](./examples/06-compound-debt-repay.ts) | Compound V3 full debt repayment using live `borrowBalanceOf` at execution time |
+| [07 — MEV-protected swap](./examples/07-mev-protected-swap.ts) | Uniswap swap gated by a live Chainlink oracle price band to block sandwich attacks |
+| [08 — Swap and vault deposit](./examples/08-swap-and-vault-deposit.ts) | Swap output captured at execution time and piped atomically into a yield vault |
+| [09 — Collateral top-up](./examples/09-collateral-topup.ts) | Keeper-triggered Aave collateral top-up using storage to lock in the amount |
+| [10 — Leverage loop](./examples/10-leverage-loop.ts) | Single-batch Aave leverage loop: deposit collateral → borrow → swap → re-deposit |
+| [11 — OR stop-loss / take-profit](./examples/11-or-stop-loss-take-profit.ts) | WETH exit triggered by stop-loss OR take-profit in a single OR predicate |
+| [12 — Cross-chain predicate-gated](./examples/12-cross-chain-predicate-gated.ts) | Across bridge + Aave deposit across Base → Arbitrum as one MEE supertransaction |
+
+---
+
 ## Installation
 
 ```bash

examples/01-safe-erc20-transfer.ts

@@ -0,0 +1,77 @@
+/**
+ * Example: Safe ERC-20 transfer with pre/post guards
+ *
+ * Scenario: Send 100 USDC to a recipient. Simple enough — but in production
+ * you want guarantees that plain `transfer` cannot give you:
+ *
+ *   - The SCA actually holds enough before the transfer executes
+ *   - The recipient genuinely received the funds (not silently swallowed by
+ *     a fee-on-transfer token or a broken contract)
+ *   - If either condition fails, no state changes at all
+ *
+ * This is the most fundamental ERC-8211 pattern: pre-condition → action →
+ * post-condition. Everything is atomic — either all three succeed or none do.
+ */
+
+import { createComposableBatch } from '@biconomy/smart-batching';
+import { createPublicClient, http, parseUnits } from 'viem';
+import { base } from 'viem/chains';
+
+// ─── Addresses (Base mainnet) ────────────────────────────────────────────────
+
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const recipient = '0xRecipientAddress' as `0x${string}`;
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+const publicClient = createPublicClient({ chain: base, transport: http() });
+const scaAddress = '0xYourSmartAccountAddress' as `0x${string}`;
+
+// ─── Transfer parameters ─────────────────────────────────────────────────────
+
+const TRANSFER_AMOUNT = parseUnits('100', 6); // 100 USDC
+
+// ─── Build the batch ─────────────────────────────────────────────────────────
+
+const batch = createComposableBatch(publicClient, scaAddress);
+const usdc = batch.erc20Token(USDC);
+
+// Read recipient balance now so the post-condition can verify the exact delta
+const recipientBalanceBefore = await usdc.read({
+  functionName: 'balanceOf',
+  args: [recipient],
+});
+
+batch.add([
+  // ── Pre-condition: sender has enough ──────────────────────────────────────
+  // Reverts the entire batch if the SCA doesn't hold at least TRANSFER_AMOUNT.
+  // Catches insufficient-balance situations before any gas is spent on a
+  // transfer that would fail anyway.
+  usdc.check({
+    functionName: 'balanceOf',
+    args: [scaAddress],
+    constraint: { gte: TRANSFER_AMOUNT },
+  }),
+
+  // ── Action: transfer ──────────────────────────────────────────────────────
+  usdc.write({
+    functionName: 'transfer',
+    args: [recipient, TRANSFER_AMOUNT],
+  }),
+
+  // ── Post-condition: recipient actually received the funds ─────────────────
+  // Verifies the recipient's balance increased by at least TRANSFER_AMOUNT.
+  // This catches fee-on-transfer tokens and any protocol that intercepts
+  // the transfer without delivering the full amount to the recipient.
+  usdc.check({
+    functionName: 'balanceOf',
+    args: [recipient],
+    constraint: { gte: recipientBalanceBefore + TRANSFER_AMOUNT },
+  }),
+]);
+
+// ─── Generate calldata ────────────────────────────────────────────────────────
+
+const calls = await batch.toCalls();
+// biome-ignore lint/suspicious/noConsole: intentional in examples
+console.log('Composable calls:', JSON.stringify(calls, null, 2));

examples/02-aave-deposit-guarded.ts

@@ -0,0 +1,93 @@
+/**
+ * Example: Pre-conditions — safe Aave deposit
+ *
+ * Scenario: Deposit USDC into Aave V3 to start earning yield.
+ *
+ * The problem without pre-conditions: if the SCA doesn't hold enough USDC, or
+ * hasn't approved the Aave pool, the deposit call reverts on-chain — wasting
+ * gas and leaving the batch in an inconsistent state.
+ *
+ * ERC-8211 pre-conditions let you place `check()` calls *before* the main
+ * action. If any condition fails, the entire batch is rejected before any
+ * state changes happen. Think of them as on-chain assertions that gate
+ * execution.
+ */
+
+import { createComposableBatch } from '@biconomy/smart-batching';
+import { createPublicClient, http, parseUnits } from 'viem';
+import { base } from 'viem/chains';
+
+// ─── Addresses (Base mainnet) ────────────────────────────────────────────────
+
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const AAVE_V3_POOL = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+
+// ─── Minimal Aave V3 Pool ABI ────────────────────────────────────────────────
+
+const AAVE_V3_POOL_ABI = [
+  {
+    name: 'supply',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'onBehalfOf', type: 'address' },
+      { name: 'referralCode', type: 'uint16' },
+    ],
+    outputs: [],
+  },
+] as const;
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+const publicClient = createPublicClient({ chain: base, transport: http() });
+
+// Your ERC-4337 smart account address
+const scaAddress = '0xYourSmartAccountAddress' as `0x${string}`;
+
+// ─── Deposit parameters ───────────────────────────────────────────────────────
+
+const DEPOSIT_AMOUNT = parseUnits('500', 6); // Deposit 500 USDC into Aave
+
+// ─── Build the batch ─────────────────────────────────────────────────────────
+
+const batch = createComposableBatch(publicClient, scaAddress);
+
+const usdc = batch.erc20Token(USDC);
+const aavePool = batch.contract(AAVE_V3_POOL, AAVE_V3_POOL_ABI);
+
+batch.add([
+  // ── Pre-condition 1: assert the SCA holds enough USDC ─────────────────────
+  // If the balance is below DEPOSIT_AMOUNT, the batch reverts here — the
+  // deposit call is never reached and no gas is wasted on a doomed transaction.
+  usdc.check({
+    functionName: 'balanceOf',
+    args: [scaAddress],
+    constraint: { gte: DEPOSIT_AMOUNT },
+  }),
+
+  // ── Pre-condition 2: assert the Aave pool has sufficient allowance ─────────
+  // Aave's `supply` will pull USDC from the SCA via transferFrom. If the
+  // allowance hasn't been set (or has been partially consumed), this check
+  // catches it before the deposit is even attempted.
+  usdc.check({
+    functionName: 'allowance',
+    args: [scaAddress, AAVE_V3_POOL],
+    constraint: { gte: DEPOSIT_AMOUNT },
+  }),
+
+  // ── Main action: deposit into Aave ────────────────────────────────────────
+  // Only reached if both pre-conditions above pass. The SCA supplies USDC to
+  // Aave on its own behalf and starts accruing aUSDC yield immediately.
+  aavePool.write({
+    functionName: 'supply',
+    args: [USDC, DEPOSIT_AMOUNT, scaAddress, 0],
+  }),
+]);
+
+// ─── Generate calldata ────────────────────────────────────────────────────────
+
+const calls = await batch.toCalls();
+// biome-ignore lint/suspicious/noConsole: intentional in examples
+console.log('Composable calls:', JSON.stringify(calls, null, 2));

examples/03-aave-full-deposit.ts

@@ -0,0 +1,111 @@
+/**
+ * Example: ERC20 — atomic approve + Aave deposit in one batch
+ *
+ * Scenario: A user wants to move their entire USDC balance into Aave to earn
+ * yield. Aave requires an ERC-20 approval before it can pull funds, which
+ * normally means two separate transactions: approve, then supply.
+ *
+ * With ERC-8211, both happen atomically in a single batch. If either step
+ * fails, neither executes — you can never end up in a state where the
+ * approval was granted but the deposit didn't happen.
+ *
+ * The deposit amount is also unknown at construction time — it depends on
+ * whatever balance the SCA holds at execution time. `runtimeBalance()` resolves
+ * this: the same live balance value is used for both the approval amount and
+ * the deposit amount, so they are guaranteed to match exactly.
+ *
+ * Flow:
+ *   1. Pre-condition: assert USDC balance is worth depositing (not dust)
+ *   2. Approve the Aave pool for exactly the runtime balance
+ *   3. Supply that same runtime balance to Aave
+ *   4. Post-condition: assert USDC balance is now (near) zero
+ */
+
+import { createComposableBatch } from '@biconomy/smart-batching';
+import { createPublicClient, http, parseUnits } from 'viem';
+import { base } from 'viem/chains';
+
+// ─── Addresses (Base mainnet) ────────────────────────────────────────────────
+
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const AAVE_V3_POOL = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+
+// ─── Minimal Aave V3 Pool ABI ────────────────────────────────────────────────
+
+const AAVE_V3_POOL_ABI = [
+  {
+    name: 'supply',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'onBehalfOf', type: 'address' },
+      { name: 'referralCode', type: 'uint16' },
+    ],
+    outputs: [],
+  },
+] as const;
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+const publicClient = createPublicClient({ chain: base, transport: http() });
+
+// Your ERC-4337 smart account address
+const scaAddress = '0xYourSmartAccountAddress' as `0x${string}`;
+
+// ─── Deposit floor ────────────────────────────────────────────────────────────
+
+const MIN_DEPOSIT = parseUnits('10', 6); // Don't bother depositing less than 10 USDC
+
+// ─── Build the batch ─────────────────────────────────────────────────────────
+
+const batch = createComposableBatch(publicClient, scaAddress);
+
+const usdc = batch.erc20Token(USDC);
+const aavePool = batch.contract(AAVE_V3_POOL, AAVE_V3_POOL_ABI);
+
+batch.add([
+  // ── Step 1: pre-condition — assert balance is worth depositing ─────────────
+  // `check()` acts as an inline guard. If the SCA holds less than MIN_DEPOSIT
+  // the whole batch reverts before anything moves.
+  usdc.check({
+    functionName: 'balanceOf',
+    args: [scaAddress],
+    constraint: { gte: MIN_DEPOSIT },
+  }),
+
+  // ── Step 2: approve Aave for exactly the runtime balance ──────────────────
+  // The approval amount is resolved on-chain at execution time — not hardcoded.
+  // This means the approval is tight (no excess allowance left over) and always
+  // matches the deposit amount in step 3 regardless of when the batch executes.
+  usdc.write({
+    functionName: 'approve',
+    args: [AAVE_V3_POOL, usdc.runtimeBalance()],
+  }),
+
+  // ── Step 3: supply the runtime balance to Aave ────────────────────────────
+  // Uses the same live balance as step 2. Both resolve via independent
+  // staticcalls at execution time, but since no balance change happens between
+  // them in this batch, they are guaranteed to return the same value.
+  aavePool.write({
+    functionName: 'supply',
+    args: [USDC, usdc.runtimeBalance(), scaAddress, 0],
+  }),
+
+  // ── Step 4: post-condition — assert the full balance was deposited ─────────
+  // After a full-balance deposit the SCA should hold no USDC. If Aave only
+  // partially accepted the deposit for any reason, this check catches it and
+  // reverts the entire batch — including the approval and the supply.
+  usdc.check({
+    functionName: 'balanceOf',
+    args: [scaAddress],
+    constraint: { eq: 0n },
+  }),
+]);
+
+// ─── Generate calldata ────────────────────────────────────────────────────────
+
+const calls = await batch.toCalls();
+// biome-ignore lint/suspicious/noConsole: intentional in examples
+console.log('Composable calls:', JSON.stringify(calls, null, 2));