@aastar/sdk 0.16.8 → 0.16.11

package/examples/l3-community-launch.ts

@@ -0,0 +1,49 @@
+import { createWalletClient, http, parseEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { sepolia } from 'viem/chains';
+import { CommunityClient } from '@aastar/sdk'; // Should be available now via re-export
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+/**
+ * L3 Scenario: Community Launch
+ * 
+ * Demonstrates how to create a new community using the CommunityClient.
+ */
+async function main() {
+    // 1. Setup User
+    const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+    const wallet = createWalletClient({
+        account,
+        chain: sepolia,
+        transport: http(process.env.RPC_URL)
+    });
+
+    console.log(`\n🚀 Starting Community Launch for ${account.address}...`);
+
+    // 2. Initialize CommunityClient (New Architecture)
+    const communityClient = new CommunityClient(wallet as any, {
+        registryAddress: process.env.REGISTRY_ADDRESS as `0x${string}`,
+        xPNTsFactoryAddress: process.env.XPNTS_FACTORY_ADDRESS as `0x${string}`,
+        reputationAddress: process.env.REPUTATION_ADDRESS as `0x${string}`
+    });
+
+    // 3. Launch Community
+    console.log('\n🏗️ Launching Community "ExampleDAO"...');
+    
+    // Note: Real deployment would require careful gas management if on mainnet
+    const result = await communityClient.deployCommunity({
+        name: 'ExampleDAO',
+        tokenName: 'ExampleToken',
+        tokenSymbol: 'EXT',
+        initialSupply: parseEther('1000000'),
+        minStake: parseEther('100')
+    });
+
+    console.log(`   ✅ Community Launched!`);
+    console.log(`   - Community Address: ${result.communityAddress}`);
+    console.log(`   - Token Address: ${result.tokenAddress}`);
+}
+
+main().catch(console.error);

package/examples/l3-user-onboarding.ts

@@ -0,0 +1,56 @@
+import { createWalletClient, http, parseEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { sepolia } from 'viem/chains';
+import { UserClient } from '@aastar/sdk'; // Should be available now via re-export
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+/**
+ * L3 Scenario: User Onboarding
+ * 
+ * Demonstrates how a new user interacts with the system:
+ * 1. Checks credit score (SBT)
+ * 2. Mints an SBT if eligible
+ * 3. Claims initial reputation
+ */
+async function main() {
+    // 1. Setup User
+    const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+    const wallet = createWalletClient({
+        account,
+        chain: sepolia,
+        transport: http(process.env.RPC_URL)
+    });
+
+    console.log(`\n🚀 Starting User Onboarding for ${account.address}...`);
+
+    // 2. Initialize UserClient (New Architecture)
+    // Note: In a real app, addresses would come from config or discovery
+    const userClient = new UserClient(wallet as any, {
+        registryAddress: process.env.REGISTRY_ADDRESS as `0x${string}`,
+        sbtAddress: process.env.SBT_ADDRESS as `0x${string}`,
+        reputationAddress: process.env.REPUTATION_ADDRESS as `0x${string}`
+    });
+
+    // 3. Check SBT Status
+    console.log('\n📊 Checking SBT Status...');
+    const hasSBT = await userClient.hasSBT(account.address);
+    console.log(`   - Has SBT: ${hasSBT}`);
+
+    if (!hasSBT) {
+        console.log('   - Minting SBT...');
+        const tx = await userClient.mintSBT();
+        console.log(`   ✅ SBT Minted! Tx: ${tx}`);
+    }
+
+    // 4. Check Reputation
+    console.log('\n⭐ Checking Reputation...');
+    const score = await userClient.getReputationScore(account.address);
+    // reputation score is bigint, convert to string for display
+    console.log(`   - Current Score: ${score.toString()}`);
+
+    console.log('\n✅ User Onboarding Complete!');
+}
+
+main().catch(console.error);

package/examples/prepare-gasless.ts

@@ -0,0 +1,89 @@
+import { createPublicClient, createWalletClient, http, parseEther, type Address } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { sepolia } from 'viem/chains';
+import { PaymasterClient, PaymasterOperator } from '../packages/paymaster/src/V4/index.js';
+import { loadNetworkConfig } from '../tests/regression/config.js';
+import * as dotenv from 'dotenv';
+
+dotenv.config({ path: '.env.sepolia' });
+
+async function main() {
+    console.log('🛠️  Preparing Gasless Environment...');
+    
+    // 0. Load Config & Operator Account (Anni)
+    const config = await loadNetworkConfig('sepolia');
+    const rpcUrl = process.env.RPC_URL || 'https://eth-sepolia.g.alchemy.com/v2/your-key';
+    const anniAccount = privateKeyToAccount(process.env.PRIVATE_KEY_ANNI as `0x${string}`);
+    const client = createPublicClient({ chain: sepolia, transport: http(rpcUrl) });
+    const operatorWallet = createWalletClient({ account: anniAccount, chain: sepolia, transport: http(rpcUrl) });
+
+    const APP_CONFIG = {
+        paymaster: '0x82862b7c3586372DF1c80Ac60adA57e530b0eB82' as Address, // Anni PM
+        gasToken: '0x424DA26B172994f98D761a999fa2FD744CaF812b' as Address,   // dPNTs
+        aaAccount: '0xECD9C07f648B09CFb78906302822Ec52Ab87dd70' as Address,  // Jason AA1
+        entryPoint: config.contracts.entryPoint as Address
+    };
+
+    console.log(`Operator: ${anniAccount.address}`);
+    console.log(`Paymaster: ${APP_CONFIG.paymaster}`);
+    console.log(`Target App User: ${APP_CONFIG.aaAccount}`);
+
+    // 1. Diagnose
+    console.log('\n🔍 Check 1: Diagnosing SDK Readiness...');
+    const report = await PaymasterOperator.checkGaslessReadiness(
+        client,
+        APP_CONFIG.entryPoint,
+        APP_CONFIG.paymaster,
+        APP_CONFIG.aaAccount,
+        APP_CONFIG.gasToken
+    );
+
+    if (report.isReady) {
+        console.log('✅ Environment is READY. You can run the simple demo now!');
+        return;
+    }
+
+    // 2. Auto-Heal
+    console.log('⚠️  Environment Not Ready. Fixing...');
+    console.log('Issues:', report.issues);
+
+    const steps = await PaymasterOperator.prepareGaslessEnvironment(
+        operatorWallet,
+        client,
+        APP_CONFIG.entryPoint,
+        APP_CONFIG.paymaster,
+        APP_CONFIG.gasToken,
+        { tokenPriceUSD: 100000000n } // $1.00 USD
+    );
+
+    for (const s of steps) {
+        console.log(`   🚀 Executing: ${s.step}...`);
+        console.log(`      Hash: ${s.hash}`);
+        await client.waitForTransactionReceipt({ hash: s.hash as `0x${string}` });
+        console.log('      ✅ Confirmed.');
+    }
+
+    // 3. User Deposit Check (Optional Seeding)
+    const userDeposit = await PaymasterClient.getDepositedBalance(client, APP_CONFIG.paymaster, APP_CONFIG.aaAccount, APP_CONFIG.gasToken);
+    if (userDeposit < parseEther('50')) {
+        console.log(`\n🏦 Seeding User Deposit (Current: ${userDeposit})...`);
+        
+        // Approve
+        const hashApprove = await PaymasterClient.approveGasToken(
+            operatorWallet,
+            APP_CONFIG.gasToken,
+            APP_CONFIG.paymaster,
+            parseEther('100')
+        );
+        await client.waitForTransactionReceipt({ hash: hashApprove });
+
+        // Deposit
+        const hashDep = await PaymasterClient.depositFor(operatorWallet, APP_CONFIG.paymaster, APP_CONFIG.aaAccount, APP_CONFIG.gasToken, parseEther('50'));
+        await client.waitForTransactionReceipt({ hash: hashDep as `0x${string}` });
+        console.log('   ✅ Seeded 50 dPNTs.');
+    }
+
+    console.log('\n🎉 ALL SET! Run `npx tsx examples/simple-gasless-demo.ts` now.');
+}
+
+main().catch(console.error);

package/examples/sdk-demo/DEVELOPER_GUIDE.md

@@ -0,0 +1,159 @@
+# AAStar SDK Developer Integration Guide (Bilingual)
+# AAStar SDK 开发者集成指南 (中英双语)
+
+This guide provides a comprehensive "How-To" map for developers building on the AAStar ecosystem. We break down complex business scenes into intuitive SDK integration patterns.
+
+本指南为基于 AAStar 生态构建的开发者提供了全面的“如何做”地图。我们将复杂的业务场景拆解为直观的 SDK 集成模式。
+
+---
+
+## 🏛 Scene A: Registry & Identity 管家：身份与统一注册
+*The orchestrator for all roles and permissions.*
+*所有角色和权限的编排核心。*
+
+### 1. How to register a new Community? / 如何注册一个新社区？
+> **Story**: As a developer, I want to onboard a new DAO or project into the ecosystem.
+> **诉求**: 作为一个开发者，我希望将一个新的 DAO 或项目引入生态系统。
+
+```typescript
+import { RegistryClient } from '@aastar/registry';
+
+// One-stop registration: Handles role binding and profile metadata
+// 一站式注册：处理角色绑定和个人资料元数据
+const tx = await RegistryClient.registerCommunity(walletClient, REGISTRY_ADDR, {
+    name: "My Awesome DAO",
+    ensName: "awesome.eth",
+    website: "https://awesome.dao",
+    description: "A community for builders",
+    logoURI: "ipfs://...",
+    stakeAmount: parseEther("100") // Required GToken stake
+});
+```
+
+### 2. How to register an EndUser? / 如何注册终端用户？
+> **Story**: I want to link a user to a specific community and mint their identity SBT.
+> **诉求**: 我希望将用户链接到特定社区并铸造其身份 SBT。
+
+```typescript
+const tx = await RegistryClient.registerEndUser(walletClient, REGISTRY_ADDR, {
+    account: userAddress,
+    community: communityAddress,
+    avatarURI: "ipfs://...",
+    ensName: "user.awesome.eth",
+    stakeAmount: 0n // Basic users might not need stake
+});
+```
+
+---
+
+## ⚡ Scene B: SuperPaymaster & Sponsorship 中间件：免 Gas 赞助
+*The gasless experience for Smart Accounts.*
+*智能账户的免 Gas 体验。*
+
+### 1. How to register a Paymaster Operator? / 如何注册 Paymaster 运营商？
+> **Story**: I want to start a service that sponsors gas for users in exchange for fees.
+> **诉求**: 我希望建立一个服务，通过收取费用来为用户赞助 Gas。
+
+```typescript
+import { RegistryClient, ROLES } from '@aastar/registry';
+import { SuperPaymasterClient } from '@aastar/superpaymaster';
+
+// 1. Bind Role in Registry / 在注册表中绑定角色
+await RegistryClient.registerRole(walletClient, REGISTRY_ADDR, ROLES.PAYMASTER_SUPER, operatorAddr, "0x");
+
+// 2. Configure Operator Settings / 配置运营商设置
+await SuperPaymasterClient.configureOperator(walletClient, SUPER_PM_ADDR, 
+    tokenAddr,      // Allowed payment token (e.g., USDT)
+    treasuryAddr,   // Where fees are sent
+    1000000n        // Exchange rate (Token/ETH)
+);
+```
+
+### 2. How to sponsor a UserOperation in a DApp? / 如何在 DApp 中赞助 UserOp？
+> **Story**: In my frontend, I want to generate the `paymasterAndData` for a gasless transaction.
+> **诉求**: 在我的前端，我希望为免 Gas 交易生成 `paymasterAndData`。
+
+```typescript
+import { getPaymasterMiddleware } from '@aastar/superpaymaster';
+
+const middleware = getPaymasterMiddleware({
+    paymasterAddress: SUPER_PM_ADDR,
+    operator: operatorAddress
+});
+
+const { paymasterAndData } = await middleware.sponsorUserOperation({ userOperation });
+// Now inject this into your UserOp before signing
+```
+
+---
+
+## 🎫 Scene C: Tokens & Community Assets 资产：SBT 与代币
+*Managing identity and incentivization.*
+*管理身份与激励。*
+
+### 1. How to airdrop SBTs to eligible users? / 如何给合规用户空投 SBT？
+> **Story**: I want to reward active contributors with a non-transferable badge.
+> **诉求**: 我希望奖励活跃贡献者一个不可转让的勋章。
+
+```typescript
+import { TokensClient } from '@aastar/tokens';
+
+// High-level: Check eligibility logic then mint
+// 高级层面：检查合规逻辑后铸造
+if (isEligible) {
+    await TokensClient.mintSBT(walletClient, MY_SBT_ADDR, userAddress, {
+        role: ROLES.ENDUSER,
+        metadataURI: "ipfs://badge-data"
+    });
+}
+```
+
+### 2. How to provide self-service SBT minting? / 如何提供自助式 SBT 领取？
+> **Story**: Users pay GTokens -> get xPNTs -> mint SBT automatically.
+> **诉求**: 用户支付 GToken -> 获取 xPNT -> 自动铸造 SBT。
+
+```typescript
+// Sequence / 流程:
+// 1. Approve GToken / 授权 GToken
+await ERC20Client.approve(walletClient, GTOKEN_ADDR, CONVERTER_ADDR, amount);
+
+// 2. Wrap GToken to xPNTs / 将 GToken 包装为 xPNT
+await FinanceClient.wrapGTokenToXPNTs(walletClient, CONVERTER_ADDR, GTOKEN_ADDR, amount);
+
+// 3. Register Role (This triggers SBT minting in V3) / 注册角色（V3中会触发 SBT 铸造）
+await RegistryClient.registerEndUser(...);
+```
+
+---
+
+## 💰 Scene D: Finance & Staking 经济：质押与流转
+*Security through economic alignment.*
+*通过经济一致性保障安全。*
+
+### 1. How to provide collateral for a Community? / 如何为社区缴纳质押金？
+> **Story**: A community owner needs to deposit GTokens to unlock high-tier features.
+> **诉求**: 社区所有者需要存入 GToken 以解锁高级功能。
+
+```typescript
+import { FinanceClient } from '@aastar/finance';
+
+// Using the 1363 "TransferAndCall" pattern for zero-approval UX
+// 使用 1363 "TransferAndCall" 模式实现零授权交互
+await FinanceClient.depositViaTransferAndCall(walletClient, GTOKEN_ADDR, REGISTRY_ADDR, amount);
+```
+
+---
+
+## 📊 Summary of 72 Scenarios / 72 个场景总结
+While AAStar supports 72 discrete business scenarios (e.g., "KMS Migration", "Anode Penalties"), they all use the **Building Blocks** above.
+AAStar 支持 72 个离散业务场景（如“KMS 迁移”、“Anode 惩罚”），但它们都使用了上述**构建块**。
+
+| Scene Category | Core SDK Module | Primary Client Action |
+| :--- | :--- | :--- |
+| **Governance** | `@aastar/registry` | `registerRole`, `createNewRole` |
+| **Monetization** | `@aastar/superpaymaster` | `configureOperator`, `deposit` |
+| **Loyalty** | `@aastar/tokens` | `mintXPNTs`, `isSBTActive` |
+| **Collateral** | `@aastar/finance` | `stakeGToken`, `depositToEP` |
+
+---
+*助力 Stage 2 结算与 Phase 1-3 顺利推进。*

package/examples/sdk-demo/README.md

@@ -0,0 +1,30 @@
+# AAStar SDK Usage Demo
+
+This folder contains a comprehensive demonstration of the **AAStar SDK** modular architecture (v0.x - v1.0).
+
+## 📁 Folder Structure
+- `usage.ts`: The main demo script with detailed comments for each module.
+- `DEVELOPER_GUIDE.md`: **[New]** Comprehensive "How-To" patterns for 72+ business scenarios (Bilingual).
+
+## 🚀 How to Use
+This demo assumes you are in a TypeScript environment with the AAStar SDK installed (or referenced via workspace).
+
+### Prerequisites
+- Node.js (v18+)
+- `pnpm` (Workspace managed)
+
+### Usage Patterns
+The demo covers:
+1. **Core Layer**: Using standard Clients and ABIs.
+2. **Identity & Roles**: Verifying roles via Registry and SBTs.
+3. **Smart Account Middleware**: Integrating SuperPaymaster for gasless transactions.
+4. **Asset Management**: Handling xPNTs and MySBT tokens.
+5. **Finance & Staking**: Managing collateral and paymaster deposits.
+
+## 📝 Key Concepts
+- **Modular Imports**: Each feature is isolated in its own package (e.g., `@aastar/registry`).
+- **One-Stop Helpers**: High-level static methods for complex flows like Community Registration.
+- **Viem Powered**: Built on top of the performant and type-safe Viem library.
+
+---
+*助力 Stage 2 结算与 Phase 1-3 顺利推进。*

package/examples/sdk-demo/usage.ts

@@ -0,0 +1,137 @@
+import { createPublicClient, createWalletClient, http, parseEther, type Hex, type Address } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { foundry } from 'viem/chains';
+
+/**
+ * AAStar SDK Modular Usage Demo (v0.4.x - v1.0.x)
+ * 
+ * This script demonstrates how to use the various modules of the AAStar SDK.
+ * The SDK is split into several packages to support different roles:
+ * - @aastar/core: Foundational clients and ABIs.
+ * - @aastar/superpaymaster: Smart Account middleware for gas sponsorship.
+ * - @aastar/finance: Staking, funding, and collateral management.
+ * - @aastar/registry: Identity, roles (SBT), and credit limit orchestration.
+ * - @aastar/tokens: ERC20 (xPNTs) and SBT (MySBT) asset management.
+ * - @aastar/aa: UserOperation construction and bundler helpers.
+ */
+
+// 1. Import Clients from Modular Packages
+import { createAAStarPublicClient } from '../../packages/core/src/index.ts';
+import { SuperPaymasterClient } from '../../packages/superpaymaster/src/index.ts';
+import { RegistryClient, ROLES } from '../../packages/registry/src/index.ts';
+import { ERC20Client } from '../../packages/tokens/src/index.ts';
+import { FinanceClient } from '../../packages/finance/src/index.ts';
+import { UserOpClient } from '../../packages/aa/src/index.ts';
+
+async function main() {
+    // Basic Configuration (Mocked/Env-based)
+    const RPC_URL = "http://127.0.0.1:8545";
+    const REGISTRY_ADDR = "0x..." as Address;
+    const SUPER_PM_ADDR = "0x..." as Address;
+    const XPNTs_TOKEN = "0x..." as Address;
+    const PRIVATE_KEY = "0x..." as Hex;
+
+    // --- Foundational Layer (@aastar/core) ---
+    // Use standard utility clients for consistent blockchain interaction.
+    const publicClient = createAAStarPublicClient({ chain: foundry, rpcUrl: RPC_URL });
+    const account = privateKeyToAccount(PRIVATE_KEY);
+    const walletClient = createWalletClient({
+        account,
+        chain: foundry,
+        transport: http(RPC_URL)
+    });
+    console.log(`Wallet Client initialized for: ${walletClient.account.address}`);
+
+    console.log("--- 1. Identity & Roles (@aastar/registry) ---");
+    const regClient = new RegistryClient(publicClient, REGISTRY_ADDR);
+    
+    // Check if the current user has the ENDUSER role (Identity verification via SBT)
+    const isUser = await regClient.hasRole(ROLES.ENDUSER, account.address);
+    console.log(`User has Identity SBT: ${isUser}`);
+
+    // High-level "One-stop" registration for a Community (v1.0.x feature)
+    // This handles staking + metadata encoding + role binding in one call.
+    /*
+    const hash = await RegistryClient.registerCommunity(walletClient, REGISTRY_ADDR, {
+        name: "My Community",
+        ensName: "my.mycelium.eth",
+        website: "https://mycelium.xyz",
+        description: "A decentralized research hub",
+        logoURI: "ipfs://...",
+        stakeAmount: parseEther("100")
+    });
+    */
+
+    console.log("\n--- 2. Sponsorship Middleware (@aastar/superpaymaster) ---");
+    const pmClient = new SuperPaymasterClient(publicClient, SUPER_PM_ADDR);
+
+    // Get Operator configuration for the current admin
+    const opData = await pmClient.getOperator(account.address);
+    // opData returns: [xPNTsToken, isConfigured, isPaused, treasury, rate, balance, ...]
+    console.log(`Operator Configured: ${opData[1]}, aPNTs Balance: ${opData[5]}`);
+
+    // Usage in a Smart Account (e.g. Kernel/SimpleAccount)
+    // The middleware automatically calculates paymasterData based on our Hybrid model.
+    /*
+    const saMiddleware = pmClient.getPaymasterMiddleware(account.address);
+    const userOp = await createMyUserOp({ ... });
+    const sponsoredUserOp = await saMiddleware(userOp);
+    */
+
+    console.log("\n--- 3. Asset Management (@aastar/tokens) ---");
+    // Interface for interacting with Community Assets (ERC20/SBT)
+    const xPNTsBalance = await ERC20Client.balanceOf(publicClient, XPNTs_TOKEN, account.address);
+    console.log(`xPNTs Asset Balance: ${xPNTsBalance}`);
+
+    console.log("\n--- 4. Protocol Finance (@aastar/finance) ---");
+    // Handle Staking and Collateral Deposits
+    // Supports "Push" pattern (transferAndCall) for better UX/Gas in v1.0
+    /*
+    const depositTx = await FinanceClient.operatorNotifyDeposit(walletClient, SUPER_PM_ADDR, parseEther("50"));
+    console.log(`Deposited 50 Tokens to Paymaster: ${depositTx}`);
+    */
+
+    console.log("\n--- 5. UserOperation Helpers (@aastar/aa) ---");
+    // Standardized helpers for estimating and sending UserOps via Bundlers
+    // const receipt = await UserOpClient.sendUserOp(BUNDLER_URL, signedUserOp, ENTRYPOINT_ADDR);
+
+    console.log("\n--- 6. Frontend Integration (@aastar/react) ---");
+    // [UI Context]: How to use in a React Component
+    /*
+    import { useSuperPaymaster, useCreditScore, EvaluationPanel } from '@aastar/react';
+
+    function MyDApp() {
+        const { creditLimit } = useCreditScore({
+            chain: sepolia,
+            registryAddress: REGISTRY_ADDR,
+            userAddress: account.address
+        });
+
+        const { generatePaymasterAndData } = useSuperPaymaster({
+            paymasterAddress: SUPER_PM_ADDR,
+            operator: account.address
+        });
+
+        return (
+            <div>
+                <EvaluationPanel 
+                    paymasterConfig={{ paymasterAddress: SUPER_PM_ADDR, operator: account.address }}
+                    userAddress={account.address}
+                    chain={sepolia}
+                    registryAddress={REGISTRY_ADDR}
+                />
+                <button onClick={async () => {
+                    const pnd = await generatePaymasterAndData(myUserOp);
+                    // send userOp with sponsored pnd...
+                }}>
+                    Sponsored Transfer (Credit: {formatEther(creditLimit ?? 0n)})
+                </button>
+            </div>
+        );
+    }
+    */
+
+    console.log("\n✅ Demo finished. Individual module documentation can be found in packages/*/README.md");
+}
+
+main().catch(console.error);

package/examples/simple-gasless-demo.ts

@@ -0,0 +1,109 @@
+import { createPublicClient, createWalletClient, http, encodeFunctionData, parseEther, formatEther, createClient } from 'viem';
+import { bundlerActions } from 'viem/account-abstraction';
+import { privateKeyToAccount } from 'viem/accounts';
+import { sepolia } from 'viem/chains';
+import { PaymasterClient } from '../packages/paymaster/src/V4/index.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadNetworkConfig } from '../tests/regression/config.js';
+// dotenv loaded by loadNetworkConfig
+
+// ...
+async function main() {
+    const args = process.argv.slice(2);
+    const networkArgIndex = args.indexOf('--network');
+    const networkName = (networkArgIndex >= 0 ? args[networkArgIndex + 1] : 'sepolia') as any;
+    const config = await loadNetworkConfig(networkName);
+
+    const statePath = path.resolve(process.cwd(), 'scripts/l4-state.json');
+    let aaAddress = '0xECD9C07f648B09CFb78906302822Ec52Ab87dd70';
+    let pmAddress = '0x82862b7c3586372DF1c80Ac60adA57e530b0eB82';
+    
+    if (fs.existsSync(statePath)) {
+        const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        aaAddress = state.aaAccounts?.[0]?.address || aaAddress;
+        pmAddress = state.operators?.jason?.paymasterV4 || pmAddress;
+    }
+
+    const APP_CONFIG = {
+        rpcUrl: process.env.RPC_URL || 'https://eth-sepolia.g.alchemy.com/v2/your-key',
+        bundlerUrl: config.bundlerUrl!,
+        entryPoint: config.contracts.entryPoint, 
+        paymaster: pmAddress, 
+        gasToken: config.contracts.aPNTs, 
+        aaAccount: aaAddress 
+    };
+    console.log('🚀 Developers only need these few lines:');
+
+    // 1. Setup Client & Wallet
+    const account = privateKeyToAccount(process.env.PRIVATE_KEY_JASON as `0x${string}`);
+    const wallet = createWalletClient({ account, chain: config.chain, transport: http(APP_CONFIG.rpcUrl) });
+    const client = createPublicClient({ chain: config.chain, transport: http(APP_CONFIG.rpcUrl) });
+
+    // 2. Define Your Action (e.g. Transfer Token)
+    // 💡 New Semantic Helpers: No more raw ABI encoding!
+    
+    // A. Inner Action: Transfer 0.01 dPNTs to Owner
+    const innerCall = PaymasterClient.encodeTokenTransfer(account.address, parseEther('0.01'));
+
+    // B. Outer Action: Execute via AA (SimpleAccount.execute)
+    const callData = PaymasterClient.encodeExecution(
+        APP_CONFIG.gasToken as `0x${string}`, 
+        0n,                                    
+        innerCall
+    );
+
+    // 3. ✨ ONE-LINER SUBMISSION ✨
+    // (Auto: Gas Estimation, 1.2x Efficiency Guard, Signing, Submission)
+    const txHash = await PaymasterClient.submitGaslessUserOperation(
+        client,
+        wallet,
+        APP_CONFIG.aaAccount as `0x${string}`,
+        APP_CONFIG.entryPoint as `0x${string}`,
+        APP_CONFIG.paymaster as `0x${string}`,
+        APP_CONFIG.gasToken as `0x${string}`,
+        APP_CONFIG.bundlerUrl,
+        callData
+        // Gas prices auto-fetched from network if not specified
+    );
+
+    // 4. Wait for Execution (Optional but recommended for confirmation)
+    console.log(`\n⏳ Waiting for execution...`);
+    const bundlerClient = createClient({
+        chain: config.chain,
+        transport: http(APP_CONFIG.bundlerUrl)
+    }).extend(bundlerActions);
+
+    try {
+        const receipt = await bundlerClient.waitForUserOperationReceipt({ 
+            hash: txHash,
+            timeout: 60000 // Increase timeout to 60s
+        });
+
+        console.log(`\n🎉 Done! Transaction Hash: ${receipt.receipt.transactionHash}`);
+        console.log(`🔗 Tracking: https://sepolia.etherscan.io/tx/${receipt.receipt.transactionHash}`);
+
+        // 5. Decode Protocol Fee (for User Visibility)
+        const feeInfo = PaymasterClient.getFeeFromReceipt(receipt.receipt, APP_CONFIG.paymaster as `0x${string}`);
+        if (feeInfo) {
+            console.log(`\n🧾 [Instant Bill] Cost: ${formatEther(feeInfo.tokenCost)} dPNTs`);
+            console.log(`   (Sponsored ETH: ${formatEther(feeInfo.actualGasCostWei)} ETH)`);
+        } else {
+            console.log('\n⚠️ Could not decode fee from logs.');
+        }
+    } catch (error: any) {
+        if (error.name === 'TimeoutError' || error.message?.includes('timed out')) {
+            console.log(`\n⚠️  Polling Timeout: The UserOperation was submitted but the receipt is not yet available.`);
+            console.log(`💡 UserOp Hash: ${txHash}`);
+            console.log(`🔗 You can check the status later at: https://sepolia.etherscan.io/tx/${txHash}`);
+            console.log(`   or via Bundler Explorer using the hash above.`);
+        } else {
+            console.error('\n❌ Error waiting for receipt:', error.shortMessage || error.message);
+        }
+    }
+}
+
+main().catch(e => {
+    console.error(e);
+    process.exit(1);
+});