@agirails/sdk 2.2.3 → 2.3.1

package/dist/wallet/aa/TransactionBatcher.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * TransactionBatcher — Encodes ACTP multi-call batches.
+ *
+ * An ACTP payment requires 3 contract calls:
+ *   1. USDC.approve(escrowVault, amount)
+ *   2. ACTPKernel.createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash, agentId)
+ *   3. ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
+ *
+ * TransactionBatcher encodes all 3 as SmartWalletCall[] for executeBatch.
+ * It pre-computes the txId using the same keccak256 formula as the contract.
+ *
+ * @module wallet/aa/TransactionBatcher
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTestnetInitBatch = exports.buildTestnetMintBatch = exports.buildRegisterAgentBatch = exports.buildACTPPayBatch = exports.computeTransactionId = void 0;
+const ethers_1 = require("ethers");
+// ============================================================================
+// ABI fragments — minimal for encoding only
+// ============================================================================
+const ERC20_APPROVE_ABI = [
+    'function approve(address spender, uint256 amount)',
+];
+const ACTP_KERNEL_ABI = [
+    'function createTransaction(address provider, address requester, uint256 amount, uint256 deadline, uint256 disputeWindow, bytes32 serviceHash, uint256 agentId)',
+    'function linkEscrow(bytes32 txId, address escrowVault, bytes32 escrowId)',
+];
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Pre-compute ACTP transaction ID.
+ *
+ * Matches ACTPKernel.sol:
+ *   transactionId = keccak256(abi.encodePacked(requester, provider, amount, serviceHash, nonce))
+ */
+function computeTransactionId(requester, provider, amount, serviceHash, nonce) {
+    return ethers_1.ethers.keccak256(ethers_1.ethers.solidityPacked(['address', 'address', 'uint256', 'bytes32', 'uint256'], [requester, provider, BigInt(amount), serviceHash, nonce]));
+}
+exports.computeTransactionId = computeTransactionId;
+/**
+ * Build the 3-call ACTP payment batch.
+ *
+ * Returns SmartWalletCall[] for executeBatch and the pre-computed txId.
+ */
+function buildACTPPayBatch(params) {
+    const amount = BigInt(params.amount);
+    // Pre-compute txId
+    const txId = computeTransactionId(params.requester, params.provider, params.amount, params.serviceHash, params.actpNonce);
+    const erc20Iface = new ethers_1.ethers.Interface(ERC20_APPROVE_ABI);
+    const kernelIface = new ethers_1.ethers.Interface(ACTP_KERNEL_ABI);
+    // Call 1: USDC.approve(escrowVault, amount)
+    const approveData = erc20Iface.encodeFunctionData('approve', [
+        params.contracts.escrowVault,
+        amount,
+    ]);
+    // Call 2: ACTPKernel.createTransaction(...)
+    const createTxData = kernelIface.encodeFunctionData('createTransaction', [
+        params.provider,
+        params.requester,
+        amount,
+        params.deadline,
+        params.disputeWindow,
+        params.serviceHash,
+        BigInt(params.agentId || '0'),
+    ]);
+    // Call 3: ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
+    // escrowId = txId (ACTP standard)
+    const linkEscrowData = kernelIface.encodeFunctionData('linkEscrow', [
+        txId,
+        params.contracts.escrowVault,
+        txId,
+    ]);
+    const calls = [
+        { target: params.contracts.usdc, value: 0n, data: approveData },
+        { target: params.contracts.actpKernel, value: 0n, data: createTxData },
+        { target: params.contracts.actpKernel, value: 0n, data: linkEscrowData },
+    ];
+    return { calls, txId };
+}
+exports.buildACTPPayBatch = buildACTPPayBatch;
+/**
+ * ABI fragment for AgentRegistry.registerAgent.
+ *
+ * Matches IAgentRegistry.sol:
+ *   registerAgent(string endpoint, ServiceDescriptor[] serviceDescriptors)
+ *
+ * ServiceDescriptor = (bytes32, string, string, uint256, uint256, uint256, string)
+ */
+const AGENT_REGISTRY_ABI = [
+    'function registerAgent(string endpoint, (bytes32 serviceTypeHash, string serviceType, string schemaURI, uint256 minPrice, uint256 maxPrice, uint256 avgCompletionTime, string metadataCID)[] serviceDescriptors)',
+];
+/**
+ * Build a register-agent batch for AgentRegistry.
+ *
+ * Used for bootstrap registration (gasless even before registration — chicken-and-egg).
+ *
+ * @param agentRegistryAddress - AgentRegistry contract address
+ * @param endpoint - Agent webhook / IPFS gateway URL
+ * @param serviceDescriptors - At least 1 service descriptor (contract requirement)
+ */
+function buildRegisterAgentBatch(agentRegistryAddress, endpoint, serviceDescriptors) {
+    if (serviceDescriptors.length === 0) {
+        throw new Error('At least one service descriptor is required for registration');
+    }
+    const iface = new ethers_1.ethers.Interface(AGENT_REGISTRY_ABI);
+    // Convert to contract format (bigint fields already correct)
+    const descriptors = serviceDescriptors.map(sd => ({
+        serviceTypeHash: sd.serviceTypeHash,
+        serviceType: sd.serviceType,
+        schemaURI: sd.schemaURI,
+        minPrice: sd.minPrice,
+        maxPrice: sd.maxPrice,
+        avgCompletionTime: sd.avgCompletionTime,
+        metadataCID: sd.metadataCID,
+    }));
+    const data = iface.encodeFunctionData('registerAgent', [endpoint, descriptors]);
+    return [
+        { target: agentRegistryAddress, value: 0n, data },
+    ];
+}
+exports.buildRegisterAgentBatch = buildRegisterAgentBatch;
+/**
+ * Build a MockUSDC mint call (testnet only).
+ */
+function buildTestnetMintBatch(mockUsdcAddress, recipient, amount) {
+    const iface = new ethers_1.ethers.Interface([
+        'function mint(address to, uint256 amount)',
+    ]);
+    const data = iface.encodeFunctionData('mint', [recipient, BigInt(amount)]);
+    return [
+        { target: mockUsdcAddress, value: 0n, data },
+    ];
+}
+exports.buildTestnetMintBatch = buildTestnetMintBatch;
+/**
+ * Build a combined register + mint batch for testnet init.
+ *
+ * Single UserOp: register on AgentRegistry + mint test USDC.
+ * Both are bootstrap-allowed (gasless without prior registration).
+ */
+function buildTestnetInitBatch(params) {
+    const registerCalls = buildRegisterAgentBatch(params.agentRegistryAddress, params.endpoint, params.serviceDescriptors);
+    const mintCalls = buildTestnetMintBatch(params.mockUsdcAddress, params.recipient, params.mintAmount);
+    return [...registerCalls, ...mintCalls];
+}
+exports.buildTestnetInitBatch = buildTestnetInitBatch;
+//# sourceMappingURL=TransactionBatcher.js.map

package/dist/wallet/aa/TransactionBatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionBatcher.js","sourceRoot":"","sources":["../../../src/wallet/aa/TransactionBatcher.ts"],"names":[],"mappings":"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"}

package/dist/wallet/aa/UserOpBuilder.d.ts

@@ -0,0 +1,71 @@
+/**
+ * UserOpBuilder — Constructs ERC-4337 v0.6 UserOperations.
+ *
+ * Builds UserOps for CoinbaseSmartWallet:
+ * - Encodes executeBatch(Call[]) as callData
+ * - Adds initCode for first-time wallet deployment
+ * - Signs with owner's private key (EIP-191 over UserOp hash)
+ *
+ * Uses ethers v6 for ABI encoding (no viem dependency yet — see Phase 2 note).
+ * viem+permissionless will be added if needed for paymaster integration.
+ *
+ * @module wallet/aa/UserOpBuilder
+ */
+import { ethers } from 'ethers';
+import { UserOperationV06, SmartWalletCall } from './constants';
+/**
+ * Compute the counterfactual Smart Wallet address for a given signer.
+ *
+ * This address is deterministic (CREATE2) and can be computed off-chain
+ * without deploying the wallet.
+ */
+export declare function computeSmartWalletAddress(signerAddress: string, provider: ethers.JsonRpcProvider, nonce?: bigint): Promise<string>;
+/**
+ * Build initCode for first-time wallet deployment.
+ *
+ * initCode = factory address + createAccount calldata
+ * When the wallet already exists, pass '0x' as initCode.
+ */
+export declare function buildInitCode(signerAddress: string, nonce?: bigint): string;
+/**
+ * Encode executeBatch calldata from an array of calls.
+ */
+export declare function encodeExecuteBatch(calls: SmartWalletCall[]): string;
+/**
+ * Build a full UserOperation (unsigned).
+ *
+ * Gas limits and paymasterAndData must be filled by the caller
+ * (via BundlerClient.estimateGas and PaymasterClient.sponsor).
+ */
+export declare function buildUserOp(params: {
+    sender: string;
+    nonce: bigint;
+    calls: SmartWalletCall[];
+    isFirstDeploy: boolean;
+    signerAddress: string;
+}): UserOperationV06;
+/**
+ * Compute the UserOperation hash for signing (v0.6).
+ *
+ * hash = keccak256(abi.encode(
+ *   keccak256(pack(userOp)),
+ *   entryPoint,
+ *   chainId
+ * ))
+ */
+export declare function getUserOpHash(userOp: UserOperationV06, chainId: number): string;
+/**
+ * Sign a UserOperation with the owner's private key.
+ *
+ * CoinbaseSmartWallet expects the signature to be:
+ *   abi.encode(SignatureWrapper(0, abi.encodePacked(r,s,v)))
+ *
+ * where ownerIndex=0 for single-owner wallets.
+ */
+export declare function signUserOp(userOp: UserOperationV06, signer: ethers.Wallet, chainId: number): Promise<string>;
+/**
+ * Serialize UserOp for JSON-RPC (bundler API).
+ * Converts bigints to hex strings.
+ */
+export declare function serializeUserOp(userOp: UserOperationV06): Record<string, string>;
+//# sourceMappingURL=UserOpBuilder.d.ts.map

package/dist/wallet/aa/UserOpBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserOpBuilder.d.ts","sourceRoot":"","sources":["../../../src/wallet/aa/UserOpBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,eAAe,EAIhB,MAAM,aAAa,CAAC;AAiCrB;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,CAAC,eAAe,EAChC,KAAK,GAAE,MAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,MAA6B,GACnC,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,CASnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,gBAAgB,CAoBnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAqCR;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF"}

package/dist/wallet/aa/UserOpBuilder.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * UserOpBuilder — Constructs ERC-4337 v0.6 UserOperations.
+ *
+ * Builds UserOps for CoinbaseSmartWallet:
+ * - Encodes executeBatch(Call[]) as callData
+ * - Adds initCode for first-time wallet deployment
+ * - Signs with owner's private key (EIP-191 over UserOp hash)
+ *
+ * Uses ethers v6 for ABI encoding (no viem dependency yet — see Phase 2 note).
+ * viem+permissionless will be added if needed for paymaster integration.
+ *
+ * @module wallet/aa/UserOpBuilder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeUserOp = exports.signUserOp = exports.getUserOpHash = exports.buildUserOp = exports.encodeExecuteBatch = exports.buildInitCode = exports.computeSmartWalletAddress = void 0;
+const ethers_1 = require("ethers");
+const constants_1 = require("./constants");
+const abiCoder = ethers_1.ethers.AbiCoder.defaultAbiCoder();
+// ============================================================================
+// ABI fragments
+// ============================================================================
+/** CoinbaseSmartWallet.executeBatch(Call[]) */
+const EXECUTE_BATCH_ABI = [
+    'function executeBatch((address target, uint256 value, bytes data)[] calls)',
+];
+/** CoinbaseSmartWalletFactory.createAccount(bytes[],uint256) */
+const FACTORY_CREATE_ABI = [
+    'function createAccount(bytes[] owners, uint256 nonce)',
+];
+/** CoinbaseSmartWalletFactory.getAddress(bytes[],uint256) */
+const FACTORY_GET_ADDRESS_ABI = [
+    'function getAddress(bytes[] owners, uint256 nonce) view returns (address)',
+];
+// Typed factory interface to avoid ethers v6 getAddress() collision
+const FACTORY_ABI = [
+    ...FACTORY_CREATE_ABI,
+    ...FACTORY_GET_ADDRESS_ABI,
+];
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Compute the counterfactual Smart Wallet address for a given signer.
+ *
+ * This address is deterministic (CREATE2) and can be computed off-chain
+ * without deploying the wallet.
+ */
+async function computeSmartWalletAddress(signerAddress, provider, nonce = constants_1.DEFAULT_WALLET_NONCE) {
+    const factory = new ethers_1.ethers.Contract(constants_1.SMART_WALLET_FACTORY, FACTORY_ABI, provider);
+    // CoinbaseSmartWallet encodes owners as bytes[] — EOA address is abi.encode(address)
+    const ownerBytes = abiCoder.encode(['address'], [signerAddress]);
+    // Use getFunction to avoid collision with ethers v6 BaseContract.getAddress()
+    const fn = factory.getFunction('getAddress');
+    return await fn([ownerBytes], nonce);
+}
+exports.computeSmartWalletAddress = computeSmartWalletAddress;
+/**
+ * Build initCode for first-time wallet deployment.
+ *
+ * initCode = factory address + createAccount calldata
+ * When the wallet already exists, pass '0x' as initCode.
+ */
+function buildInitCode(signerAddress, nonce = constants_1.DEFAULT_WALLET_NONCE) {
+    const iface = new ethers_1.ethers.Interface(FACTORY_CREATE_ABI);
+    const ownerBytes = abiCoder.encode(['address'], [signerAddress]);
+    const calldata = iface.encodeFunctionData('createAccount', [
+        [ownerBytes],
+        nonce,
+    ]);
+    // initCode = factory address (20 bytes) + calldata
+    return constants_1.SMART_WALLET_FACTORY + calldata.slice(2);
+}
+exports.buildInitCode = buildInitCode;
+/**
+ * Encode executeBatch calldata from an array of calls.
+ */
+function encodeExecuteBatch(calls) {
+    const iface = new ethers_1.ethers.Interface(EXECUTE_BATCH_ABI);
+    return iface.encodeFunctionData('executeBatch', [
+        calls.map((c) => ({
+            target: c.target,
+            value: c.value,
+            data: c.data,
+        })),
+    ]);
+}
+exports.encodeExecuteBatch = encodeExecuteBatch;
+/**
+ * Build a full UserOperation (unsigned).
+ *
+ * Gas limits and paymasterAndData must be filled by the caller
+ * (via BundlerClient.estimateGas and PaymasterClient.sponsor).
+ */
+function buildUserOp(params) {
+    const callData = encodeExecuteBatch(params.calls);
+    const initCode = params.isFirstDeploy
+        ? buildInitCode(params.signerAddress)
+        : '0x';
+    return {
+        sender: params.sender,
+        nonce: params.nonce,
+        initCode,
+        callData,
+        // Placeholder values — filled by gas estimation
+        callGasLimit: 0n,
+        verificationGasLimit: 0n,
+        preVerificationGas: 0n,
+        maxFeePerGas: 0n,
+        maxPriorityFeePerGas: 0n,
+        paymasterAndData: '0x',
+        signature: '0x',
+    };
+}
+exports.buildUserOp = buildUserOp;
+/**
+ * Compute the UserOperation hash for signing (v0.6).
+ *
+ * hash = keccak256(abi.encode(
+ *   keccak256(pack(userOp)),
+ *   entryPoint,
+ *   chainId
+ * ))
+ */
+function getUserOpHash(userOp, chainId) {
+    // Pack all fields except signature
+    const packed = abiCoder.encode([
+        'address', // sender
+        'uint256', // nonce
+        'bytes32', // keccak256(initCode)
+        'bytes32', // keccak256(callData)
+        'uint256', // callGasLimit
+        'uint256', // verificationGasLimit
+        'uint256', // preVerificationGas
+        'uint256', // maxFeePerGas
+        'uint256', // maxPriorityFeePerGas
+        'bytes32', // keccak256(paymasterAndData)
+    ], [
+        userOp.sender,
+        userOp.nonce,
+        ethers_1.ethers.keccak256(userOp.initCode),
+        ethers_1.ethers.keccak256(userOp.callData),
+        userOp.callGasLimit,
+        userOp.verificationGasLimit,
+        userOp.preVerificationGas,
+        userOp.maxFeePerGas,
+        userOp.maxPriorityFeePerGas,
+        ethers_1.ethers.keccak256(userOp.paymasterAndData),
+    ]);
+    const packedHash = ethers_1.ethers.keccak256(packed);
+    return ethers_1.ethers.keccak256(abiCoder.encode(['bytes32', 'address', 'uint256'], [packedHash, constants_1.ENTRYPOINT_V06, chainId]));
+}
+exports.getUserOpHash = getUserOpHash;
+/**
+ * Sign a UserOperation with the owner's private key.
+ *
+ * CoinbaseSmartWallet expects the signature to be:
+ *   abi.encode(SignatureWrapper(0, abi.encodePacked(r,s,v)))
+ *
+ * where ownerIndex=0 for single-owner wallets.
+ */
+async function signUserOp(userOp, signer, chainId) {
+    const hash = getUserOpHash(userOp, chainId);
+    // ethers signMessage adds EIP-191 prefix. CoinbaseSmartWallet expects raw ECDSA.
+    // We use signingKey.sign() for raw signature over the hash bytes.
+    const sig = signer.signingKey.sign(hash);
+    // Pack r + s + v
+    const rawSig = ethers_1.ethers.concat([sig.r, sig.s, new Uint8Array([sig.v])]);
+    // CoinbaseSmartWallet SignatureWrapper: abi.encode(uint256 ownerIndex, bytes signatureData)
+    return abiCoder.encode(['uint256', 'bytes'], [0, rawSig]);
+}
+exports.signUserOp = signUserOp;
+/**
+ * Serialize UserOp for JSON-RPC (bundler API).
+ * Converts bigints to hex strings.
+ */
+function serializeUserOp(userOp) {
+    return {
+        sender: userOp.sender,
+        nonce: toHex(userOp.nonce),
+        initCode: userOp.initCode,
+        callData: userOp.callData,
+        callGasLimit: toHex(userOp.callGasLimit),
+        verificationGasLimit: toHex(userOp.verificationGasLimit),
+        preVerificationGas: toHex(userOp.preVerificationGas),
+        maxFeePerGas: toHex(userOp.maxFeePerGas),
+        maxPriorityFeePerGas: toHex(userOp.maxPriorityFeePerGas),
+        paymasterAndData: userOp.paymasterAndData,
+        signature: userOp.signature,
+    };
+}
+exports.serializeUserOp = serializeUserOp;
+function toHex(n) {
+    return '0x' + n.toString(16);
+}
+//# sourceMappingURL=UserOpBuilder.js.map

package/dist/wallet/aa/UserOpBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserOpBuilder.js","sourceRoot":"","sources":["../../../src/wallet/aa/UserOpBuilder.ts"],"names":[],"mappings":"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"}

package/dist/wallet/aa/constants.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Account Abstraction constants for CoinbaseSmartWallet on Base.
+ *
+ * EntryPoint v0.6 — CoinbaseSmartWallet hardcodes this version.
+ * Factory address is canonical across all Base networks.
+ *
+ * @module wallet/aa/constants
+ */
+/** ERC-4337 EntryPoint v0.6 (canonical, all EVM chains) */
+export declare const ENTRYPOINT_V06 = "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789";
+/** CoinbaseSmartWallet factory (canonical, all Base networks) */
+export declare const SMART_WALLET_FACTORY = "0xBA5ED110eFDBa3D005bfC882d75358ACBbB85842";
+/** Default nonce for first Smart Wallet per owner */
+export declare const DEFAULT_WALLET_NONCE = 0n;
+/**
+ * UserOperation v0.6 struct — 11 unpacked fields.
+ * CoinbaseSmartWallet does NOT support v0.7 packed format.
+ */
+export interface UserOperationV06 {
+    sender: string;
+    nonce: bigint;
+    initCode: string;
+    callData: string;
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    paymasterAndData: string;
+    signature: string;
+}
+/**
+ * CoinbaseSmartWallet Call struct for executeBatch.
+ */
+export interface SmartWalletCall {
+    target: string;
+    value: bigint;
+    data: string;
+}
+/**
+ * Gas estimation result from bundler.
+ */
+export interface GasEstimate {
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+}
+/**
+ * Paymaster sponsorship response.
+ */
+export interface PaymasterResponse {
+    paymasterAndData: string;
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/wallet/aa/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/wallet/aa/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,cAAc,+CAA+C,CAAC;AAE3E,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,+CAA+C,CAAC;AAEjF,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;CAC1B"}

package/dist/wallet/aa/constants.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Account Abstraction constants for CoinbaseSmartWallet on Base.
+ *
+ * EntryPoint v0.6 — CoinbaseSmartWallet hardcodes this version.
+ * Factory address is canonical across all Base networks.
+ *
+ * @module wallet/aa/constants
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WALLET_NONCE = exports.SMART_WALLET_FACTORY = exports.ENTRYPOINT_V06 = void 0;
+/** ERC-4337 EntryPoint v0.6 (canonical, all EVM chains) */
+exports.ENTRYPOINT_V06 = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';
+/** CoinbaseSmartWallet factory (canonical, all Base networks) */
+exports.SMART_WALLET_FACTORY = '0xBA5ED110eFDBa3D005bfC882d75358ACBbB85842';
+/** Default nonce for first Smart Wallet per owner */
+exports.DEFAULT_WALLET_NONCE = 0n;
+//# sourceMappingURL=constants.js.map

package/dist/wallet/aa/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/wallet/aa/constants.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,2DAA2D;AAC9C,QAAA,cAAc,GAAG,4CAA4C,CAAC;AAE3E,iEAAiE;AACpD,QAAA,oBAAoB,GAAG,4CAA4C,CAAC;AAEjF,qDAAqD;AACxC,QAAA,oBAAoB,GAAG,EAAE,CAAC"}

package/dist/wallet/keystore.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Auto-resolve private key: env var → keystore → undefined.
+ * Never logs or prints the key itself.
+ */
+export declare function resolvePrivateKey(stateDirectory?: string): Promise<string | undefined>;
+/**
+ * Get cached address from last resolvePrivateKey() call.
+ * Works for both env-var and keystore resolution paths.
+ */
+export declare function getCachedAddress(stateDirectory?: string): string | undefined;
+/**
+ * Clear all cached keys and addresses (for testing).
+ * @internal
+ */
+export declare function _clearCache(): void;
+//# sourceMappingURL=keystore.d.ts.map

package/dist/wallet/keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.d.ts","sourceRoot":"","sources":["../../src/wallet/keystore.ts"],"names":[],"mappings":"AA+CA;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwC7B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU5E;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAGlC"}

package/dist/wallet/keystore.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._clearCache = exports.getCachedAddress = exports.resolvePrivateKey = void 0;
+/**
+ * Keystore auto-resolution for ACTP wallets.
+ *
+ * Resolution order:
+ *   1. ACTP_PRIVATE_KEY env var (backward compat, highest priority)
+ *   2. .actp/keystore.json decrypted with ACTP_KEY_PASSWORD
+ *   3. undefined (caller decides what to do)
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ethers_1 = require("ethers");
+// Cache keyed by resolved keystorePath to support multiple stateDirectories
+const _cache = new Map();
+// Separate cache for env-var-resolved key (no path dependency)
+let _envCache = null;
+/**
+ * Validate that stateDirectory doesn't escape expected boundaries.
+ * Guards against path traversal when stateDirectory comes from user input.
+ */
+function validateStateDirectory(stateDirectory) {
+    if (stateDirectory.includes('\0')) {
+        throw new Error('Invalid stateDirectory: null byte detected');
+    }
+    // Reject raw '..' in the input (before normalization resolves it)
+    // Catches both relative traversal (../../etc) and embedded traversal (/tmp/../../etc)
+    if (stateDirectory.includes('..')) {
+        throw new Error('Invalid stateDirectory: path traversal detected (..)');
+    }
+}
+/**
+ * Validate and normalize a raw private key string.
+ * Trims whitespace and verifies 0x-prefixed 64-char hex format.
+ */
+function validateRawKey(raw, source) {
+    const trimmed = raw.trim();
+    if (!/^0x[0-9a-fA-F]{64}$/.test(trimmed)) {
+        throw new Error(`Invalid private key from ${source}: expected 0x-prefixed 64-char hex string`);
+    }
+    return trimmed;
+}
+/**
+ * Auto-resolve private key: env var → keystore → undefined.
+ * Never logs or prints the key itself.
+ */
+async function resolvePrivateKey(stateDirectory) {
+    // 1. Env var (highest priority, backward compat)
+    if (process.env.ACTP_PRIVATE_KEY) {
+        if (_envCache)
+            return _envCache.key;
+        const key = validateRawKey(process.env.ACTP_PRIVATE_KEY, 'ACTP_PRIVATE_KEY env var');
+        const address = new ethers_1.Wallet(key).address;
+        _envCache = { key, address };
+        return key;
+    }
+    // 2. Resolve keystore path
+    if (stateDirectory) {
+        validateStateDirectory(stateDirectory);
+    }
+    const actpDir = stateDirectory
+        ? path.join(stateDirectory, '.actp')
+        : path.join(process.cwd(), '.actp');
+    const keystorePath = path.resolve(actpDir, 'keystore.json');
+    // 3. Cache hit (keyed by resolved path)
+    const cached = _cache.get(keystorePath);
+    if (cached)
+        return cached.key;
+    // 4. Keystore file
+    if (!fs.existsSync(keystorePath))
+        return undefined;
+    const password = process.env.ACTP_KEY_PASSWORD;
+    if (!password) {
+        throw new Error('Keystore found at ' + keystorePath + ' but ACTP_KEY_PASSWORD is not set.\n' +
+            'Set it: export ACTP_KEY_PASSWORD="your-password"');
+    }
+    const keystore = fs.readFileSync(keystorePath, 'utf-8');
+    const wallet = await ethers_1.Wallet.fromEncryptedJson(keystore, password);
+    _cache.set(keystorePath, { key: wallet.privateKey, address: wallet.address });
+    return wallet.privateKey;
+}
+exports.resolvePrivateKey = resolvePrivateKey;
+/**
+ * Get cached address from last resolvePrivateKey() call.
+ * Works for both env-var and keystore resolution paths.
+ */
+function getCachedAddress(stateDirectory) {
+    // Env var path
+    if (_envCache)
+        return _envCache.address;
+    // Keystore path — look up by resolved path
+    const actpDir = stateDirectory
+        ? path.join(stateDirectory, '.actp')
+        : path.join(process.cwd(), '.actp');
+    const keystorePath = path.resolve(actpDir, 'keystore.json');
+    return _cache.get(keystorePath)?.address;
+}
+exports.getCachedAddress = getCachedAddress;
+/**
+ * Clear all cached keys and addresses (for testing).
+ * @internal
+ */
+function _clearCache() {
+    _cache.clear();
+    _envCache = null;
+}
+exports._clearCache = _clearCache;
+//# sourceMappingURL=keystore.js.map