@agirails/sdk 2.2.3 → 2.3.1

package/README.md

@@ -3,18 +3,24 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Tests](https://img.shields.io/badge/tests-773%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-1506%20passed-brightgreen.svg)]()
 
 The official TypeScript SDK for the **Agent Commerce Transaction Protocol (ACTP)** - enabling AI agents to transact with each other through blockchain-based escrow.
 
 ## Features
 
 - **Three-tier API**: Basic, Standard, and Advanced levels for different use cases
+- **Adapter Routing**: `0x...` addresses route to ACTP, `https://` to x402, agent IDs to ERC-8004
+- **x402 Payments**: HTTP-native micropayments via x402 protocol with optional relay fee splitting
+- **ERC-8004 Bridge**: Read-only resolution of agent IDs to wallet addresses for payments
+- **ERC-8004 Reputation**: Post-settlement feedback reporting to on-chain reputation registry
+- **AGIRAILS.md**: Agent config as source of truth with publish/pull/diff CLI and drift detection
 - **Mock Runtime**: Full local testing without blockchain connection
 - **Type-safe**: Complete TypeScript types with strict mode support
 - **Async/Await**: Promise-based API for modern async workflows
-- **Comprehensive Errors**: Structured exception types with error codes
+- **Comprehensive Errors**: Structured exception types with error codes and recovery guidance
 - **Security Built-in**: EIP-712 signing, replay protection, safe nonce management
+- **Configurable Confirmations**: Block confirmation depth configurable per-network (default: 2)
 
 ## Installation
 
@@ -38,26 +44,21 @@ Get started with real transactions on Base Sepolia testnet:
 # Install CLI globally
 npm install -g @agirails/sdk
 
-# Initialize configuration
-actp init --network base-sepolia
-
-# Set your private key (or use PRIVATE_KEY env var)
-actp config set private-key YOUR_PRIVATE_KEY
-
-# Note: mint is mock mode only. For testnet/mainnet, bridge real USDC via bridge.base.org
-# In mock mode:
-actp mint --amount 1000  # Mint 1000 test USDC (mock mode only)
+# One-time setup: generates encrypted keystore at .actp/keystore.json
+ACTP_KEY_PASSWORD=your-password actp init -m testnet
 
 # Check your balance
-actp balance
+ACTP_KEY_PASSWORD=your-password actp balance
 
 # Make a payment
-actp pay 0xProviderAddress 100 --deadline 24h
+ACTP_KEY_PASSWORD=your-password actp pay 0xProviderAddress 100 --deadline 24h
 
 # Watch transaction status
 actp watch TX_ID
 ```
 
+> **Alternative**: Set `ACTP_PRIVATE_KEY` env var to use a raw private key instead of the keystore.
+
 ### Basic API - Simple Payments
 
 The simplest way to make a payment - just specify who, how much, and go:
@@ -95,10 +96,10 @@ import { ACTPClient } from '@agirails/sdk';
 import { ethers } from 'ethers';
 
 async function main() {
+  // No wallet param needed — auto-detects .actp/keystore.json
   const client = await ACTPClient.create({
     mode: 'testnet',  // or 'mainnet' for production
     requesterAddress: '0x1111111111111111111111111111111111111111',
-    privateKey: process.env.PRIVATE_KEY,
   });
 
   // Step 1: Create transaction (no funds locked yet)
@@ -197,19 +198,17 @@ const client = await ACTPClient.create({
   stateDirectory: '.actp'  // Optional: persist state to disk
 });
 
-// Testnet mode - Base Sepolia
+// Testnet mode - Base Sepolia (auto-detects keystore or ACTP_PRIVATE_KEY)
 const client = await ACTPClient.create({
   mode: 'testnet',
   requesterAddress: '0x1111111111111111111111111111111111111111',
-  privateKey: '0x...',
   rpcUrl: 'https://sepolia.base.org'  // Optional: custom RPC
 });
 
-// Mainnet mode - Base
+// Mainnet mode - Base (auto-detects keystore or ACTP_PRIVATE_KEY)
 const client = await ACTPClient.create({
   mode: 'mainnet',
   requesterAddress: '0x1111111111111111111111111111111111111111',
-  privateKey: '0x...'
 });
 ```
 
@@ -329,10 +328,30 @@ actp simulate pay <provider> <amount>
 actp simulate fee <amount>
 ```
 
+### AGIRAILS.md Config Management
+
+```bash
+# Publish agent config to on-chain registry
+actp publish [--dry-run]
+
+# Pull config from on-chain registry
+actp pull <agent-id>
+
+# Compare local config vs on-chain
+actp diff <agent-id>
+
+# Register agent on AgentRegistry
+actp register
+```
+
 ### Configuration
 
 ```bash
-# Set configuration
+# Initialize keystore (one-time setup)
+ACTP_KEY_PASSWORD=your-password actp init -m testnet   # or mainnet
+ACTP_KEY_PASSWORD=your-password actp init -m mainnet
+
+# General config
 actp config set <key> <value>
 actp config get <key>
 actp config list
@@ -341,7 +360,6 @@ actp config reset
 # Available config keys:
 #   network: base-sepolia | base-mainnet | mock
 #   rpc-url: RPC endpoint URL
-#   private-key: Wallet private key (or use PRIVATE_KEY env)
 #   state-directory: Directory for mock state persistence
 ```
 
@@ -434,11 +452,11 @@ const providers = directory.find({ capabilities: ['gpt-4'] });
 ```typescript
 import { Agent, AgentConfig } from '@agirails/sdk';
 
-// Create an agent
+// Create an agent (auto-detects keystore, no wallet param needed)
 const agent = new Agent({
   name: 'my-agent',
-  address: '0x...',
-  services: ['text-generation']
+  network: 'testnet',
+  services: ['text-generation'],
 });
 
 // Handle jobs
@@ -461,7 +479,10 @@ This TypeScript SDK maintains **full parity** with the Python SDK:
 | EIP-712 Signing | Full support | Full support |
 | Level0 API | Full ACTP flow | Full ACTP flow |
 | Level1 Agent API | Complete | Complete |
-| CLI Commands | watch, batch, simulate | watch, batch, simulate |
+| CLI Commands | watch, batch, simulate, publish, pull, diff | watch, batch, simulate |
+| Adapter Routing | ACTP + x402 + ERC-8004 | ACTP only |
+| ERC-8004 Bridge | Identity + Reputation | Not yet |
+| AGIRAILS.md Config | publish/pull/diff/drift detection | Not yet |
 | Nonce Tracking | SecureNonce, ReceivedNonceTracker | SecureNonce, ReceivedNonceTracker |
 | Attestation Tracking | UsedAttestationTracker | UsedAttestationTracker |
 
@@ -472,7 +493,7 @@ This TypeScript SDK maintains **full parity** with the Python SDK:
 | Network | Chain ID | Status |
 |---------|----------|--------|
 | Base Sepolia | 84532 | ✅ Active (Testnet) |
-| Base Mainnet | 8453 | ⏳ Coming Soon |
+| Base Mainnet | 8453 | ✅ Active |
 
 ## Fee Structure
 
@@ -485,8 +506,13 @@ This TypeScript SDK maintains **full parity** with the Python SDK:
 - **Replay Protection**: Nonce management prevents transaction replay
 - **Non-custodial Escrow**: 2-of-2 release pattern
 - **EAS Integration**: Ethereum Attestation Service for delivery proofs
+- **ERC-8004 Reputation**: On-chain settlement/dispute feedback after ACTP transactions
 - **Input Validation**: All user inputs validated before processing
 
+### Transaction Confirmations
+
+All state-changing operations in ACTPKernel wait for block confirmations before events are emitted. The default is 2 confirmations (~4-6s on Base L2's ~2s blocks), configurable via `BlockchainRuntimeConfig.confirmations`. The SDK's `EventMonitor` receives already-confirmed events; no additional confirmation handling is needed at the application layer.
+
 ## Decentralized Identifiers (DIDs)
 
 AGIRAILS uses **did:ethr** DIDs based on the [ERC-1056](https://eips.ethereum.org/EIPS/eip-1056) standard for identity management.
@@ -604,19 +630,27 @@ DIDs are used internally for:
 ## Environment Variables
 
 ```bash
-# Required for blockchain mode
-PRIVATE_KEY=0x...
+# Wallet resolution (checked in order):
+ACTP_PRIVATE_KEY=0x...       # Raw private key (takes priority if set)
+ACTP_KEY_PASSWORD=...        # Decrypts .actp/keystore.json (recommended)
 
 # Optional
-BASE_SEPOLIA_RPC=https://sepolia.base.org
-IPFS_GATEWAY=https://gateway.pinata.cloud
+BASE_SEPOLIA_RPC=...         # Custom RPC for Base Sepolia
+BASE_MAINNET_RPC=...         # Custom RPC for Base Mainnet
+CDP_API_KEY=...              # Coinbase Developer Platform API key
+PIMLICO_API_KEY=...          # Pimlico bundler/paymaster API key
+IPFS_GATEWAY=...             # Custom IPFS gateway URL
 ```
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 18+ (required for global `fetch` and `AbortController`)
 - TypeScript 5.0+ (for development)
-- Dependencies: ethers, viem (optional)
+- Dependencies: ethers, viem, permissionless
+
+### Module Format
+
+The SDK ships as **CommonJS only**. It works with `require()` and with bundlers (webpack, esbuild, Rollup) that support CJS. If you are using ESM (`import` syntax), Node.js will auto-interop with CJS modules — no additional configuration is needed.
 
 ## License
 

package/dist/ACTPClient.d.ts

@@ -41,6 +41,7 @@ import { IAdapter, TransactionStatus } from './adapters/IAdapter';
 import { UnifiedPayParams, UnifiedPayResult } from './types/adapter';
 import { EASHelper, EASConfig } from './protocol/EASHelper';
 import { ReputationReporter } from './erc8004/ReputationReporter';
+import { IWalletProvider } from './wallet/IWalletProvider';
 /**
  * Supported modes for ACTPClient.
  *
@@ -67,9 +68,23 @@ export interface ACTPClientConfig {
      * This address is used as the "from" address for all transactions
      * created through this client instance.
      *
+     * When wallet is 'auto', this is auto-derived from the Smart Wallet
+     * and does NOT need to be provided.
+     *
      * @example '0x1111111111111111111111111111111111111111'
      */
-    requesterAddress: string;
+    requesterAddress?: string;
+    /**
+     * AIP-12: Wallet mode.
+     *
+     * - 'auto': CoinbaseSmartWallet + gas sponsorship (Tier 1, recommended).
+     *           Requires CDP_API_KEY env var. Agent address = Smart Wallet address.
+     * - undefined: EOA wallet from privateKey (Tier 2, backward compatible).
+     *
+     * When 'auto', requesterAddress is derived from the Smart Wallet
+     * and does not need to be provided.
+     */
+    wallet?: 'auto';
     /**
      * Optional: Project root directory for mock state file storage.
      *
@@ -152,6 +167,7 @@ export interface ACTPClientConfig {
         actpKernel?: string;
         escrowVault?: string;
         usdc?: string;
+        agentRegistry?: string;
     };
     /**
      * Optional: Gas settings for blockchain transactions.
@@ -203,6 +219,8 @@ export interface ACTPClientInfo {
     address: string;
     /** State directory (mock mode only) */
     stateDirectory?: string;
+    /** Wallet tier ('auto' = Smart Wallet, 'eoa' = EOA, undefined = mock) */
+    walletTier?: 'auto' | 'eoa';
 }
 /**
  * ACTPClient - Main entry point for AGIRAILS SDK.
@@ -334,6 +352,12 @@ export declare class ACTPClient {
      * @internal
      */
     private readonly reputationReporter?;
+    /**
+     * AIP-12: Wallet provider (Tier 1 Auto or Tier 2 EOA).
+     * Only set in testnet/mainnet modes.
+     * @internal
+     */
+    private readonly walletProvider?;
     /**
      * Private constructor - use ACTPClient.create() factory method.
      */
@@ -671,5 +695,22 @@ export declare class ACTPClient {
      * ```
      */
     getReputationReporter(): ReputationReporter | undefined;
+    /**
+     * AIP-12: Get the wallet provider instance.
+     *
+     * Only available in testnet/mainnet modes.
+     * Returns undefined in mock mode.
+     *
+     * Use this for advanced operations like checking wallet info,
+     * or sending custom batched transactions.
+     */
+    getWalletProvider(): IWalletProvider | undefined;
+    /**
+     * Non-blocking drift detection for AGIRAILS.md config.
+     * Checks if local AGIRAILS.md matches on-chain config hash.
+     * Logs warnings but never blocks agent operation.
+     * @internal
+     */
+    private checkConfigDrift;
 }
 //# sourceMappingURL=ACTPClient.d.ts.map

package/dist/ACTPClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ACTPClient.d.ts","sourceRoot":"","sources":["../src/ACTPClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AASH,OAAO,EAAE,YAAY,EAAgB,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA+FlE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,cAAc,CAAC;IAErB;;;;;;;OAOG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QACV,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IAEF;;;;OAIG;IACH,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;IAEF;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,IAAI,EAAE,cAAc,CAAC;IACrB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,UAAU;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,SAAgB,KAAK,EAAE,YAAY,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAgB,QAAQ,EAAE,eAAe,CAAC;IAE1C;;;;;OAKG;IACH,SAAgB,OAAO,EAAE,YAAY,CAAC;IAEtC;;OAEG;IACH,SAAgB,IAAI,EAAE,cAAc,CAAC;IAErC;;;OAGG;IACH,SAAgB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAE3C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAqB;IAEzD;;OAEG;IACH,OAAO;IA0BP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;WACU,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAwIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,cAAc;IAIzB;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM;IAWhB;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAalB;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAchE;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM9D;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKzD;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBzE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCvE;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAIxC;;;;;;;;;;OAUG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,IAAI,kBAAkB,GAAG,SAAS;CAGxD"}
+{"version":3,"file":"ACTPClient.d.ts","sourceRoot":"","sources":["../src/ACTPClient.ts"],"names":[],"mappings":"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"}

package/dist/ACTPClient.js

@@ -74,6 +74,9 @@ const AdapterRouter_1 = require("./adapters/AdapterRouter");
 const ERC8004Bridge_1 = require("./erc8004/ERC8004Bridge");
 const ReputationReporter_1 = require("./erc8004/ReputationReporter");
 const networks_1 = require("./config/networks");
+const EOAWalletProvider_1 = require("./wallet/EOAWalletProvider");
+const AutoWalletProvider_1 = require("./wallet/AutoWalletProvider");
+const Logger_1 = require("./utils/Logger");
 // ============================================================================
 // Security: Path Validation
 // ============================================================================
@@ -88,6 +91,24 @@ const networks_1 = require("./config/networks");
  * @param stateDirectory - The directory path to validate
  * @throws Error if path is unsafe
  */
+/**
+ * Check if an agent is registered on AgentRegistry.
+ * Lightweight read-only check — no signer needed.
+ *
+ * Uses minimal ABI fragment to avoid importing the full AgentRegistry class.
+ * Checks registeredAt field of AgentProfile struct (> 0 means registered).
+ */
+async function checkRegistration(provider, registryAddress, agentAddress) {
+    const contract = new ethers_1.ethers.Contract(registryAddress, [
+        'function getAgent(address agentAddress) view returns ' +
+            '(tuple(address agentAddress, string did, string endpoint, bytes32[] serviceTypes, ' +
+            'uint256 stakedAmount, uint256 reputationScore, uint256 totalTransactions, ' +
+            'uint256 disputedTransactions, uint256 totalVolumeUSDC, uint256 registeredAt, ' +
+            'uint256 updatedAt, bool isActive, bytes32 configHash, string configCID, bool listed))',
+    ], provider);
+    const profile = await contract.getAgent(agentAddress);
+    return profile.registeredAt > 0n;
+}
 function validateStateDirectory(stateDirectory) {
     // Check for path traversal characters
     if (stateDirectory.includes('..')) {
@@ -203,12 +224,13 @@ class ACTPClient {
     /**
      * Private constructor - use ACTPClient.create() factory method.
      */
-    constructor(runtime, requesterAddress, info, easHelper, erc8004Bridge, reputationReporter) {
+    constructor(runtime, requesterAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses) {
         this.runtime = runtime;
         this.info = info;
         this.easHelper = easHelper;
         this.reputationReporter = reputationReporter;
-        this.basic = new BasicAdapter_1.BasicAdapter(runtime, requesterAddress, easHelper);
+        this.walletProvider = walletProvider;
+        this.basic = new BasicAdapter_1.BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses);
         this.standard = new StandardAdapter_1.StandardAdapter(runtime, requesterAddress, easHelper);
         // Initialize registry and router
         this.registry = new AdapterRegistry_1.AdapterRegistry();
@@ -254,27 +276,40 @@ class ACTPClient {
      * ```
      */
     static async create(config) {
-        // Validate requester address
-        if (!config.requesterAddress) {
-            throw new Error('requesterAddress is required');
-        }
-        if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
-            throw new Error(`Invalid requesterAddress: "${config.requesterAddress}". ` +
-                'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
-        }
         let runtime;
         let stateDirectory;
         let easHelper;
         let erc8004Bridge;
         let reputationReporter;
+        let walletProvider;
+        let requesterAddress;
+        let contractAddresses;
         // If custom runtime provided, use it directly
         if (config.runtime) {
+            // Custom runtime: requesterAddress is mandatory
+            if (!config.requesterAddress) {
+                throw new Error('requesterAddress is required when providing a custom runtime');
+            }
+            if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+                throw new Error(`Invalid requesterAddress: "${config.requesterAddress}". ` +
+                    'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
+            }
+            requesterAddress = config.requesterAddress;
             runtime = config.runtime;
         }
         else {
             // Initialize runtime based on mode
             switch (config.mode) {
                 case 'mock': {
+                    // Mock mode: requesterAddress is mandatory
+                    if (!config.requesterAddress) {
+                        throw new Error('requesterAddress is required for mock mode');
+                    }
+                    if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+                        throw new Error(`Invalid requesterAddress: "${config.requesterAddress}". ` +
+                            'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
+                    }
+                    requesterAddress = config.requesterAddress;
                     // SECURITY FIX: Enhanced path validation to prevent path traversal attacks
                     if (config.stateDirectory) {
                         validateStateDirectory(config.stateDirectory);
@@ -294,18 +329,97 @@ class ACTPClient {
                     }
                     // Map mode to network config
                     const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+                    const networkConfig = (0, networks_1.getNetwork)(network);
                     // Default RPC URL from network config if not provided
-                    // This makes Level0/Agent usable on testnet without forcing users to pass rpcUrl explicitly.
-                    const rpcUrl = config.rpcUrl ?? (0, networks_1.getNetwork)(network).rpcUrl;
-                    // Optional persistent state directory can be used for:
-                    // - mock mode state (mock-state.json)
-                    // - blockchain mode safety state (e.g., used-attestation replay protection)
+                    const rpcUrl = config.rpcUrl ?? networkConfig.rpcUrl;
+                    // Optional persistent state directory
                     if (config.stateDirectory) {
                         validateStateDirectory(config.stateDirectory);
                     }
                     // Create ethers provider and signer
                     const provider = new ethers_1.ethers.JsonRpcProvider(rpcUrl);
                     const signer = new ethers_1.ethers.Wallet(config.privateKey, provider);
+                    // ====================================================================
+                    // AIP-12: Wallet Provider Selection
+                    // ====================================================================
+                    if (config.wallet === 'auto') {
+                        // Tier 1: CoinbaseSmartWallet + gasless transactions
+                        if (!networkConfig.aa) {
+                            throw new Error(`AA configuration not available for ${config.mode} mode. ` +
+                                'Check that networks.ts has aa config for this network.');
+                        }
+                        // Validate that bundler/paymaster URLs have actual API keys
+                        const cdpBundlerUrl = networkConfig.aa.bundlerUrls.coinbase;
+                        const hasPimlico = !!networkConfig.aa.bundlerUrls.pimlico;
+                        if (cdpBundlerUrl.endsWith('/') && !hasPimlico) {
+                            throw new Error('CDP_API_KEY is required for gas-sponsored transactions.\n\n' +
+                                'Set up your API key:\n' +
+                                '  1. Visit https://portal.cdp.coinbase.com/\n' +
+                                '  2. Create a new API key\n' +
+                                '  3. export CDP_API_KEY="your-key-here"\n\n' +
+                                'Or set PIMLICO_API_KEY as an alternative bundler/paymaster.\n' +
+                                'Or use wallet: undefined for traditional EOA transactions (requires ETH for gas).');
+                        }
+                        const autoWallet = await AutoWalletProvider_1.AutoWalletProvider.create({
+                            signer,
+                            provider,
+                            chainId: networkConfig.chainId,
+                            actpKernelAddress: config.contracts?.actpKernel ?? networkConfig.contracts.actpKernel,
+                            bundler: {
+                                primaryUrl: networkConfig.aa.bundlerUrls.coinbase,
+                                backupUrl: networkConfig.aa.bundlerUrls.pimlico,
+                            },
+                            paymaster: {
+                                primaryUrl: networkConfig.aa.paymasterUrls.coinbase,
+                                backupUrl: networkConfig.aa.paymasterUrls.pimlico,
+                            },
+                        });
+                        // Check AgentRegistry — gasless only for registered agents
+                        const smartWalletAddress = autoWallet.getAddress();
+                        const agentRegistryAddress = config.contracts?.agentRegistry
+                            ?? networkConfig.contracts.agentRegistry;
+                        let isRegistered = false;
+                        if (agentRegistryAddress) {
+                            try {
+                                isRegistered = await checkRegistration(provider, agentRegistryAddress, smartWalletAddress);
+                            }
+                            catch {
+                                // Registry check failed (e.g. RPC down) — allow AA anyway.
+                                // Rationale: don't punish legit registered agents for infra issues.
+                                // Paymaster contract allowlist + rate limits prevent abuse.
+                                isRegistered = true;
+                                Logger_1.sdkLogger.warn('AgentRegistry check failed, proceeding with AA wallet');
+                            }
+                        }
+                        else {
+                            // No registry deployed — skip check (early testnet)
+                            isRegistered = true;
+                        }
+                        if (isRegistered) {
+                            walletProvider = autoWallet;
+                            requesterAddress = smartWalletAddress;
+                        }
+                        else {
+                            // Not registered — fall back to EOA with warning
+                            Logger_1.sdkLogger.warn('Agent not registered on AgentRegistry. ' +
+                                'Falling back to EOA wallet (gas not sponsored). ' +
+                                'Run "actp register" for gas-free transactions.');
+                            walletProvider = new EOAWalletProvider_1.EOAWalletProvider(signer, networkConfig.chainId);
+                            // Force signer.address — config.requesterAddress may be the Smart Wallet
+                            // address (set by `actp init --wallet auto`), which would be wrong for EOA.
+                            requesterAddress = signer.address;
+                        }
+                    }
+                    else {
+                        // Tier 2: EOA Wallet (backward compatible)
+                        walletProvider = new EOAWalletProvider_1.EOAWalletProvider(signer, networkConfig.chainId);
+                        requesterAddress = config.requesterAddress ?? signer.address;
+                    }
+                    // Validate derived/provided address
+                    if (!/^0x[a-fA-F0-9]{40}$/.test(requesterAddress)) {
+                        throw new Error(`Invalid requesterAddress: "${requesterAddress}". ` +
+                            'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
+                    }
                     const requireAttestation = config.requireAttestation ?? Boolean(config.easConfig);
                     // Create BlockchainRuntime
                     const blockchainRuntime = new BlockchainRuntime_1.BlockchainRuntime({
@@ -327,18 +441,22 @@ class ACTPClient {
                         easHelper = blockchainRuntime.getEASHelper();
                     }
                     // ERC-8004 INTEGRATION: Create bridge for agent ID resolution
-                    // Maps network to ERC8004Network ('base-sepolia' or 'base')
                     const erc8004Network = config.mode === 'testnet' ? 'base-sepolia' : 'base';
                     erc8004Bridge = new ERC8004Bridge_1.ERC8004Bridge({
                         network: erc8004Network,
                         rpcUrl,
                     });
                     // ERC-8004 REPUTATION: Create reporter for settlement outcome reporting
-                    // Reports successful settlements and dispute outcomes to Reputation Registry
                     reputationReporter = new ReputationReporter_1.ReputationReporter({
                         network: erc8004Network,
                         signer,
                     });
+                    // AIP-12: Contract addresses for AA batched payments
+                    contractAddresses = {
+                        usdc: config.contracts?.usdc ?? networkConfig.contracts.usdc,
+                        actpKernel: config.contracts?.actpKernel ?? networkConfig.contracts.actpKernel,
+                        escrowVault: config.contracts?.escrowVault ?? networkConfig.contracts.escrowVault,
+                    };
                     break;
                 }
                 default:
@@ -347,15 +465,22 @@ class ACTPClient {
             }
         }
         // Normalize address to lowercase for consistency
-        const normalizedAddress = config.requesterAddress.toLowerCase();
+        const normalizedAddress = requesterAddress.toLowerCase();
         const info = {
             mode: config.mode,
             address: normalizedAddress,
             stateDirectory,
+            walletTier: walletProvider?.getWalletInfo().tier,
         };
-        // SECURITY FIX (C-4): Pass EASHelper to adapters for attestation verification
-        // ERC-8004: Pass bridge for agent ID resolution, reporter for settlement outcomes
-        return new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter);
+        // Pass wallet provider and contract addresses to constructor
+        const client = new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses);
+        // Drift detection: non-blocking check for AGIRAILS.md sync status
+        if (config.mode !== 'mock') {
+            client.checkConfigDrift(config).catch(() => {
+                // Silently ignore drift check errors — non-critical
+            });
+        }
+        return client;
     }
     // ==========================================================================
     // Public Methods
@@ -700,7 +825,7 @@ class ACTPClient {
             })
                 .then((result) => {
                 if (result) {
-                    console.log(`[ERC8004] Settlement reported for agent ${agentId}: ${result.txHash}`);
+                    Logger_1.sdkLogger.info(`[ERC8004] Settlement reported for agent ${agentId}: ${result.txHash}`);
                 }
             })
                 .catch(() => {
@@ -763,6 +888,66 @@ class ACTPClient {
     getReputationReporter() {
         return this.reputationReporter;
     }
+    /**
+     * AIP-12: Get the wallet provider instance.
+     *
+     * Only available in testnet/mainnet modes.
+     * Returns undefined in mock mode.
+     *
+     * Use this for advanced operations like checking wallet info,
+     * or sending custom batched transactions.
+     */
+    getWalletProvider() {
+        return this.walletProvider;
+    }
+    /**
+     * Non-blocking drift detection for AGIRAILS.md config.
+     * Checks if local AGIRAILS.md matches on-chain config hash.
+     * Logs warnings but never blocks agent operation.
+     * @internal
+     */
+    async checkConfigDrift(config) {
+        try {
+            const { existsSync, readFileSync } = await Promise.resolve().then(() => __importStar(require('fs')));
+            const { join } = await Promise.resolve().then(() => __importStar(require('path')));
+            // Look for AGIRAILS.md in cwd
+            const agirailsMdPath = join(process.cwd(), 'AGIRAILS.md');
+            if (!existsSync(agirailsMdPath)) {
+                return; // No local file — nothing to check
+            }
+            const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+            const networkConfig = (0, networks_1.getNetwork)(network);
+            if (!networkConfig.contracts.agentRegistry) {
+                return; // No registry on this network
+            }
+            const content = readFileSync(agirailsMdPath, 'utf-8');
+            const { computeConfigHash } = await Promise.resolve().then(() => __importStar(require('./config/agirailsmd')));
+            const { configHash: localHash } = computeConfigHash(content);
+            const { AgentRegistryClient } = await Promise.resolve().then(() => __importStar(require('./registry/AgentRegistryClient')));
+            const provider = new ethers_1.ethers.JsonRpcProvider(networkConfig.rpcUrl);
+            const registryClient = AgentRegistryClient.readOnly(networkConfig.contracts.agentRegistry, provider);
+            // Detect template vs published state from frontmatter
+            const { parseAgirailsMd: parseMd } = await Promise.resolve().then(() => __importStar(require('./config/agirailsmd')));
+            const { frontmatter } = parseMd(content);
+            const isTemplate = !frontmatter.config_hash;
+            const onChainState = await registryClient.getConfig(config.requesterAddress ?? this.info.address);
+            const ZERO_HASH = '0x' + '0'.repeat(64);
+            if (onChainState.configHash === ZERO_HASH) {
+                if (isTemplate) {
+                    Logger_1.sdkLogger.info('[AGIRAILS] AGIRAILS.md loaded (template mode). Run "actp publish" to register and sync on-chain.');
+                }
+                else {
+                    Logger_1.sdkLogger.warn('[AGIRAILS] Config not published on-chain. Run: actp publish');
+                }
+            }
+            else if (onChainState.configHash !== localHash) {
+                Logger_1.sdkLogger.warn('[AGIRAILS] Local AGIRAILS.md differs from on-chain. Run: actp diff');
+            }
+        }
+        catch {
+            // Silently ignore — drift detection is best-effort
+        }
+    }
 }
 exports.ACTPClient = ACTPClient;
 //# sourceMappingURL=ACTPClient.js.map