@a3stack/accounts 0.2.0

package/dist/constants.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Constants for @a3stack/accounts
+ */
+/** ERC-8004 Identity Registry — same address on all chains */
+export declare const REGISTRY_ADDRESS: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+/** ERC-8004 registration type URI */
+export declare const REGISTRATION_TYPE = "https://eips.ethereum.org/EIPS/eip-8004#registration-v1";
+/** Zero address */
+export declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
+/** Minimal ABI for ERC-8004 register + Transfer event */
+export declare const REGISTRY_ABI: readonly [{
+    readonly name: "register";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "agentURI";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "setAgentURI";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "newURI";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "Transfer";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }];
+}];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAG,4CAAqD,CAAC;AAEtF,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,4DAA4D,CAAC;AAE3F,mBAAmB;AACnB,eAAO,MAAM,YAAY,EAAG,4CAAqD,CAAC;AAElF,yDAAyD;AACzD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCf,CAAC"}

package/dist/constants.js

@@ -0,0 +1,46 @@
+/**
+ * Constants for @a3stack/accounts
+ */
+/** ERC-8004 Identity Registry — same address on all chains */
+export const REGISTRY_ADDRESS = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+/** ERC-8004 registration type URI */
+export const REGISTRATION_TYPE = "https://eips.ethereum.org/EIPS/eip-8004#registration-v1";
+/** Zero address */
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** Minimal ABI for ERC-8004 register + Transfer event */
+export const REGISTRY_ABI = [
+    {
+        name: "register",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [{ name: "agentURI", type: "string" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "setAgentURI",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "agentId", type: "uint256" },
+            { name: "newURI", type: "string" },
+        ],
+        outputs: [],
+    },
+    {
+        name: "balanceOf",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "owner", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "Transfer",
+        type: "event",
+        inputs: [
+            { name: "from", type: "address", indexed: true },
+            { name: "to", type: "address", indexed: true },
+            { name: "tokenId", type: "uint256", indexed: true },
+        ],
+    },
+];
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAAG,4CAAqD,CAAC;AAEtF,qCAAqC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,yDAAyD,CAAC;AAE3F,mBAAmB;AACnB,MAAM,CAAC,MAAM,YAAY,GAAG,4CAAqD,CAAC;AAElF,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;SACnC;QACD,OAAO,EAAE,EAAE;KACZ;IACD;QACE,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC5C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YAChD,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YAC9C,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;SACpD;KACF;CACO,CAAC"}

package/dist/gasless-register.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Convenience function for one-shot gasless registration.
+ *
+ * For more control, use createAgentAccount() directly.
+ */
+import type { CdpCredentials, RegisterOptions, RegisterResult } from "./types.js";
+/**
+ * Register an agent on ERC-8004 with zero gas cost (one-shot).
+ *
+ * Creates a smart account and registers in a single call.
+ *
+ * @example
+ * ```ts
+ * import { gaslessRegister } from "@a3stack/accounts";
+ *
+ * const result = await gaslessRegister(
+ *   {
+ *     apiKeyId: process.env.CDP_API_KEY_ID!,
+ *     apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *     walletSecret: process.env.CDP_WALLET_SECRET!,
+ *   },
+ *   {
+ *     name: "my-agent",
+ *     description: "An AI agent that does cool things",
+ *     services: [{ type: "website", url: "https://myagent.ai" }],
+ *   }
+ * );
+ *
+ * console.log(`Registered at ${result.smartAccountAddress}`);
+ * console.log(`Tx: ${result.transactionHash}`);
+ * console.log(`Gas cost: $${result.gasCost}`); // $0
+ * ```
+ */
+export declare function gaslessRegister(credentials: CdpCredentials, options: RegisterOptions & {
+    accountName?: string;
+    testnet?: boolean;
+}): Promise<RegisterResult>;
+//# sourceMappingURL=gasless-register.d.ts.map

package/dist/gasless-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gasless-register.d.ts","sourceRoot":"","sources":["../src/gasless-register.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,eAAe,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACrE,OAAO,CAAC,cAAc,CAAC,CAOzB"}

package/dist/gasless-register.js

@@ -0,0 +1,41 @@
+/**
+ * Convenience function for one-shot gasless registration.
+ *
+ * For more control, use createAgentAccount() directly.
+ */
+import { createAgentAccount } from "./smart-account.js";
+/**
+ * Register an agent on ERC-8004 with zero gas cost (one-shot).
+ *
+ * Creates a smart account and registers in a single call.
+ *
+ * @example
+ * ```ts
+ * import { gaslessRegister } from "@a3stack/accounts";
+ *
+ * const result = await gaslessRegister(
+ *   {
+ *     apiKeyId: process.env.CDP_API_KEY_ID!,
+ *     apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *     walletSecret: process.env.CDP_WALLET_SECRET!,
+ *   },
+ *   {
+ *     name: "my-agent",
+ *     description: "An AI agent that does cool things",
+ *     services: [{ type: "website", url: "https://myagent.ai" }],
+ *   }
+ * );
+ *
+ * console.log(`Registered at ${result.smartAccountAddress}`);
+ * console.log(`Tx: ${result.transactionHash}`);
+ * console.log(`Gas cost: $${result.gasCost}`); // $0
+ * ```
+ */
+export async function gaslessRegister(credentials, options) {
+    const agent = await createAgentAccount(credentials, {
+        name: options.accountName ?? `agent-${options.name.toLowerCase().replace(/\s+/g, "-")}`,
+        testnet: options.testnet,
+    });
+    return agent.register(options);
+}
+//# sourceMappingURL=gasless-register.js.map

package/dist/gasless-register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gasless-register.js","sourceRoot":"","sources":["../src/gasless-register.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,WAA2B,EAC3B,OAAsE;IAEtE,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE;QAClD,IAAI,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;QACvF,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @a3stack/accounts — Gasless smart accounts for AI agents
+ *
+ * Create ERC-4337 smart accounts with automatic gas sponsorship
+ * via CDP Paymaster. Register agents on ERC-8004 with zero gas cost.
+ *
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ *
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * });
+ *
+ * // Register on-chain with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "Does cool stuff",
+ * });
+ * ```
+ */
+export { createAgentAccount } from "./smart-account.js";
+export { gaslessRegister } from "./gasless-register.js";
+export { REGISTRY_ADDRESS, REGISTRY_ABI, REGISTRATION_TYPE } from "./constants.js";
+export type { CdpCredentials, CreateAgentAccountOptions, AgentAccount, RegisterOptions, RegisterResult, UserOperationCall, UserOperationResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnF,YAAY,EACV,cAAc,EACd,yBAAyB,EACzB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * @a3stack/accounts — Gasless smart accounts for AI agents
+ *
+ * Create ERC-4337 smart accounts with automatic gas sponsorship
+ * via CDP Paymaster. Register agents on ERC-8004 with zero gas cost.
+ *
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ *
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * });
+ *
+ * // Register on-chain with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "Does cool stuff",
+ * });
+ * ```
+ */
+export { createAgentAccount } from "./smart-account.js";
+export { gaslessRegister } from "./gasless-register.js";
+export { REGISTRY_ADDRESS, REGISTRY_ABI, REGISTRATION_TYPE } from "./constants.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/smart-account.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CDP Smart Account wrapper for gasless agent operations
+ *
+ * Uses Coinbase Developer Platform SDK for:
+ * - Server wallet management (EOA owner)
+ * - Smart account creation (ERC-4337)
+ * - Automatic gas sponsorship via CDP Paymaster on Base
+ */
+import type { CdpCredentials, CreateAgentAccountOptions, AgentAccount } from "./types.js";
+/**
+ * Create a gasless smart account for an AI agent.
+ *
+ * The account is an ERC-4337 smart account on Base, owned by a CDP-managed
+ * EOA. All transactions are gas-sponsored by the CDP Paymaster.
+ *
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ *
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * }, { name: "my-agent" });
+ *
+ * // Register on ERC-8004 with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "An autonomous AI agent",
+ * });
+ * console.log(`Registered! Tx: ${result.transactionHash}`);
+ * ```
+ */
+export declare function createAgentAccount(credentials: CdpCredentials, options?: CreateAgentAccountOptions): Promise<AgentAccount>;
+//# sourceMappingURL=smart-account.d.ts.map

package/dist/smart-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-account.d.ts","sourceRoot":"","sources":["../src/smart-account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,YAAY,EAKb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,cAAc,EAC3B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,YAAY,CAAC,CA6FvB"}

package/dist/smart-account.js

@@ -0,0 +1,115 @@
+/**
+ * CDP Smart Account wrapper for gasless agent operations
+ *
+ * Uses Coinbase Developer Platform SDK for:
+ * - Server wallet management (EOA owner)
+ * - Smart account creation (ERC-4337)
+ * - Automatic gas sponsorship via CDP Paymaster on Base
+ */
+import { CdpClient } from "@coinbase/cdp-sdk";
+import { encodeFunctionData } from "viem";
+import { REGISTRY_ADDRESS, REGISTRY_ABI, REGISTRATION_TYPE } from "./constants.js";
+/**
+ * Create a gasless smart account for an AI agent.
+ *
+ * The account is an ERC-4337 smart account on Base, owned by a CDP-managed
+ * EOA. All transactions are gas-sponsored by the CDP Paymaster.
+ *
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ *
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * }, { name: "my-agent" });
+ *
+ * // Register on ERC-8004 with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "An autonomous AI agent",
+ * });
+ * console.log(`Registered! Tx: ${result.transactionHash}`);
+ * ```
+ */
+export async function createAgentAccount(credentials, options = {}) {
+    const { apiKeyId, apiKeySecret, walletSecret } = credentials;
+    const network = options.testnet ? "base-sepolia" : "base";
+    const accountName = options.name ?? "a3stack-agent";
+    // Initialize CDP client
+    const cdp = new CdpClient({ apiKeyId, apiKeySecret, walletSecret });
+    // Create or retrieve the owner EOA
+    const owner = await cdp.evm.getOrCreateAccount({
+        name: `${accountName}-owner`,
+    });
+    // Create or retrieve the smart account
+    const smartAccount = await cdp.evm.getOrCreateSmartAccount({
+        name: accountName,
+        owner,
+    });
+    // Scope to Base network
+    const scopedAccount = await smartAccount.useNetwork(network);
+    // Build the AgentAccount interface
+    const agentAccount = {
+        address: smartAccount.address,
+        ownerAddress: owner.address,
+        network: network,
+        async sendUserOperation(calls) {
+            const userOp = await scopedAccount.sendUserOperation({
+                calls: calls.map((c) => ({
+                    to: c.to,
+                    value: c.value ?? 0n,
+                    data: c.data ?? "0x",
+                })),
+            });
+            const receipt = await scopedAccount.waitForUserOperation(userOp);
+            const txHash = receipt.transactionHash ?? String(receipt);
+            return {
+                userOpHash: userOp.userOpHash ?? String(userOp),
+                transactionHash: txHash,
+            };
+        },
+        async register(opts) {
+            // Build the agent registration JSON
+            const registration = {
+                type: REGISTRATION_TYPE,
+                name: opts.name,
+                description: opts.description,
+                ...(opts.image ? { image: opts.image } : {}),
+                services: opts.services ?? [],
+                x402Support: opts.x402Support ?? false,
+                active: true,
+                registrations: opts.existingRegistrations ?? [],
+            };
+            const json = JSON.stringify(registration);
+            const agentURI = `data:application/json;base64,${Buffer.from(json).toString("base64")}`;
+            // Encode the register() call
+            const callData = encodeFunctionData({
+                abi: REGISTRY_ABI,
+                functionName: "register",
+                args: [agentURI],
+            });
+            // Send gasless UserOperation
+            const userOp = await scopedAccount.sendUserOperation({
+                calls: [{
+                        to: REGISTRY_ADDRESS,
+                        value: 0n,
+                        data: callData,
+                    }],
+            });
+            const receipt = await scopedAccount.waitForUserOperation(userOp);
+            const txHash = receipt.transactionHash ?? String(receipt);
+            return {
+                transactionHash: txHash,
+                userOpHash: userOp.userOpHash ?? String(userOp),
+                smartAccountAddress: smartAccount.address,
+                network,
+                gasCost: 0,
+                sponsored: true,
+            };
+        },
+    };
+    return agentAccount;
+}
+//# sourceMappingURL=smart-account.js.map

package/dist/smart-account.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Types for @a3stack/accounts
+ */
+export interface CdpCredentials {
+    /** CDP API Key ID */
+    apiKeyId: string;
+    /** CDP API Key Secret */
+    apiKeySecret: string;
+    /** CDP Wallet Secret (EC P-256 PKCS8 key, base64-encoded) */
+    walletSecret: string;
+}
+export interface CreateAgentAccountOptions {
+    /** Human-readable name for the account (used for idempotent getOrCreate) */
+    name?: string;
+    /** Use testnet (Base Sepolia) instead of mainnet */
+    testnet?: boolean;
+}
+export interface AgentAccount {
+    /** Smart account address (ERC-4337) */
+    address: `0x${string}`;
+    /** Owner EOA address */
+    ownerAddress: `0x${string}`;
+    /** The network used */
+    network: "base" | "base-sepolia";
+    /** Send a gasless UserOperation */
+    sendUserOperation: (calls: UserOperationCall[]) => Promise<UserOperationResult>;
+    /** Register this agent on ERC-8004 with zero gas */
+    register: (options: RegisterOptions) => Promise<RegisterResult>;
+}
+export interface UserOperationCall {
+    to: `0x${string}`;
+    value?: bigint;
+    data?: `0x${string}`;
+}
+export interface UserOperationResult {
+    userOpHash: string;
+    transactionHash: string;
+}
+export interface RegisterOptions {
+    /** Agent name */
+    name: string;
+    /** Agent description */
+    description: string;
+    /** Agent image URL (optional) */
+    image?: string;
+    /** Service endpoints */
+    services?: Array<{
+        type: string;
+        url: string;
+    }>;
+    /** Whether agent supports x402 payments */
+    x402Support?: boolean;
+    /** Existing registrations from other chains */
+    existingRegistrations?: Array<{
+        agentId: number;
+        agentRegistry: string;
+    }>;
+}
+export interface RegisterResult {
+    /** Transaction hash on Base */
+    transactionHash: string;
+    /** UserOperation hash */
+    userOpHash: string;
+    /** Smart account address */
+    smartAccountAddress: `0x${string}`;
+    /** Network used */
+    network: string;
+    /** Gas cost to user (always 0 with Paymaster) */
+    gasCost: number;
+    /** Whether gas was sponsored */
+    sponsored: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,wBAAwB;IACxB,YAAY,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B,uBAAuB;IACvB,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;IACjC,mCAAmC;IACnC,iBAAiB,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChF,oDAAoD;IACpD,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,2CAA2C;IAC3C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,qBAAqB,CAAC,EAAE,KAAK,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,mBAAmB,EAAE,KAAK,MAAM,EAAE,CAAC;IACnC,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for @a3stack/accounts
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@a3stack/accounts",
+  "version": "0.2.0",
+  "description": "Gasless smart accounts for ERC-8004 agent registration via CDP Paymaster",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@coinbase/cdp-sdk": "^1.44.1",
+    "viem": "^2.46.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "erc-8004",
+    "agent",
+    "identity",
+    "gasless",
+    "smart-account",
+    "cdp",
+    "paymaster",
+    "base"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arcabotai/a3stack",
+    "directory": "packages/accounts"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,49 @@
+/**
+ * Constants for @a3stack/accounts
+ */
+
+/** ERC-8004 Identity Registry — same address on all chains */
+export const REGISTRY_ADDRESS = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" as const;
+
+/** ERC-8004 registration type URI */
+export const REGISTRATION_TYPE = "https://eips.ethereum.org/EIPS/eip-8004#registration-v1";
+
+/** Zero address */
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
+
+/** Minimal ABI for ERC-8004 register + Transfer event */
+export const REGISTRY_ABI = [
+  {
+    name: "register",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "agentURI", type: "string" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "setAgentURI",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "newURI", type: "string" },
+    ],
+    outputs: [],
+  },
+  {
+    name: "balanceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "owner", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "Transfer",
+    type: "event",
+    inputs: [
+      { name: "from", type: "address", indexed: true },
+      { name: "to", type: "address", indexed: true },
+      { name: "tokenId", type: "uint256", indexed: true },
+    ],
+  },
+] as const;

package/src/gasless-register.ts

@@ -0,0 +1,47 @@
+/**
+ * Convenience function for one-shot gasless registration.
+ * 
+ * For more control, use createAgentAccount() directly.
+ */
+
+import { createAgentAccount } from "./smart-account.js";
+import type { CdpCredentials, RegisterOptions, RegisterResult } from "./types.js";
+
+/**
+ * Register an agent on ERC-8004 with zero gas cost (one-shot).
+ * 
+ * Creates a smart account and registers in a single call.
+ * 
+ * @example
+ * ```ts
+ * import { gaslessRegister } from "@a3stack/accounts";
+ * 
+ * const result = await gaslessRegister(
+ *   {
+ *     apiKeyId: process.env.CDP_API_KEY_ID!,
+ *     apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *     walletSecret: process.env.CDP_WALLET_SECRET!,
+ *   },
+ *   {
+ *     name: "my-agent",
+ *     description: "An AI agent that does cool things",
+ *     services: [{ type: "website", url: "https://myagent.ai" }],
+ *   }
+ * );
+ * 
+ * console.log(`Registered at ${result.smartAccountAddress}`);
+ * console.log(`Tx: ${result.transactionHash}`);
+ * console.log(`Gas cost: $${result.gasCost}`); // $0
+ * ```
+ */
+export async function gaslessRegister(
+  credentials: CdpCredentials,
+  options: RegisterOptions & { accountName?: string; testnet?: boolean }
+): Promise<RegisterResult> {
+  const agent = await createAgentAccount(credentials, {
+    name: options.accountName ?? `agent-${options.name.toLowerCase().replace(/\s+/g, "-")}`,
+    testnet: options.testnet,
+  });
+
+  return agent.register(options);
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @a3stack/accounts — Gasless smart accounts for AI agents
+ * 
+ * Create ERC-4337 smart accounts with automatic gas sponsorship
+ * via CDP Paymaster. Register agents on ERC-8004 with zero gas cost.
+ * 
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ * 
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * });
+ * 
+ * // Register on-chain with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "Does cool stuff",
+ * });
+ * ```
+ */
+
+export { createAgentAccount } from "./smart-account.js";
+export { gaslessRegister } from "./gasless-register.js";
+export { REGISTRY_ADDRESS, REGISTRY_ABI, REGISTRATION_TYPE } from "./constants.js";
+export type {
+  CdpCredentials,
+  CreateAgentAccountOptions,
+  AgentAccount,
+  RegisterOptions,
+  RegisterResult,
+  UserOperationCall,
+  UserOperationResult,
+} from "./types.js";

package/src/smart-account.ts

@@ -0,0 +1,143 @@
+/**
+ * CDP Smart Account wrapper for gasless agent operations
+ * 
+ * Uses Coinbase Developer Platform SDK for:
+ * - Server wallet management (EOA owner)
+ * - Smart account creation (ERC-4337)
+ * - Automatic gas sponsorship via CDP Paymaster on Base
+ */
+
+import { CdpClient } from "@coinbase/cdp-sdk";
+import { encodeFunctionData } from "viem";
+import { REGISTRY_ADDRESS, REGISTRY_ABI, REGISTRATION_TYPE } from "./constants.js";
+import type {
+  CdpCredentials,
+  CreateAgentAccountOptions,
+  AgentAccount,
+  RegisterOptions,
+  RegisterResult,
+  UserOperationCall,
+  UserOperationResult,
+} from "./types.js";
+
+/**
+ * Create a gasless smart account for an AI agent.
+ * 
+ * The account is an ERC-4337 smart account on Base, owned by a CDP-managed
+ * EOA. All transactions are gas-sponsored by the CDP Paymaster.
+ * 
+ * @example
+ * ```ts
+ * import { createAgentAccount } from "@a3stack/accounts";
+ * 
+ * const agent = await createAgentAccount({
+ *   apiKeyId: process.env.CDP_API_KEY_ID!,
+ *   apiKeySecret: process.env.CDP_API_KEY_SECRET!,
+ *   walletSecret: process.env.CDP_WALLET_SECRET!,
+ * }, { name: "my-agent" });
+ * 
+ * // Register on ERC-8004 with zero gas
+ * const result = await agent.register({
+ *   name: "My Agent",
+ *   description: "An autonomous AI agent",
+ * });
+ * console.log(`Registered! Tx: ${result.transactionHash}`);
+ * ```
+ */
+export async function createAgentAccount(
+  credentials: CdpCredentials,
+  options: CreateAgentAccountOptions = {}
+): Promise<AgentAccount> {
+  const { apiKeyId, apiKeySecret, walletSecret } = credentials;
+  const network = options.testnet ? "base-sepolia" : "base";
+  const accountName = options.name ?? "a3stack-agent";
+
+  // Initialize CDP client
+  const cdp = new CdpClient({ apiKeyId, apiKeySecret, walletSecret });
+
+  // Create or retrieve the owner EOA
+  const owner = await cdp.evm.getOrCreateAccount({
+    name: `${accountName}-owner`,
+  });
+
+  // Create or retrieve the smart account
+  const smartAccount = await cdp.evm.getOrCreateSmartAccount({
+    name: accountName,
+    owner,
+  });
+
+  // Scope to Base network
+  const scopedAccount = await smartAccount.useNetwork(network);
+
+  // Build the AgentAccount interface
+  const agentAccount: AgentAccount = {
+    address: smartAccount.address as `0x${string}`,
+    ownerAddress: owner.address as `0x${string}`,
+    network: network as "base" | "base-sepolia",
+
+    async sendUserOperation(calls: UserOperationCall[]): Promise<UserOperationResult> {
+      const userOp = await scopedAccount.sendUserOperation({
+        calls: calls.map((c) => ({
+          to: c.to,
+          value: c.value ?? 0n,
+          data: c.data ?? "0x",
+        })),
+      });
+
+      const receipt = await scopedAccount.waitForUserOperation(userOp);
+      const txHash = (receipt as any).transactionHash ?? String(receipt);
+
+      return {
+        userOpHash: (userOp as any).userOpHash ?? String(userOp),
+        transactionHash: txHash,
+      };
+    },
+
+    async register(opts: RegisterOptions): Promise<RegisterResult> {
+      // Build the agent registration JSON
+      const registration = {
+        type: REGISTRATION_TYPE,
+        name: opts.name,
+        description: opts.description,
+        ...(opts.image ? { image: opts.image } : {}),
+        services: opts.services ?? [],
+        x402Support: opts.x402Support ?? false,
+        active: true,
+        registrations: opts.existingRegistrations ?? [],
+      };
+
+      const json = JSON.stringify(registration);
+      const agentURI = `data:application/json;base64,${Buffer.from(json).toString("base64")}`;
+
+      // Encode the register() call
+      const callData = encodeFunctionData({
+        abi: REGISTRY_ABI,
+        functionName: "register",
+        args: [agentURI],
+      });
+
+      // Send gasless UserOperation
+      const userOp = await scopedAccount.sendUserOperation({
+        calls: [{
+          to: REGISTRY_ADDRESS,
+          value: 0n,
+          data: callData,
+        }],
+      });
+
+      const receipt = await scopedAccount.waitForUserOperation(userOp);
+      const txHash = (receipt as any).transactionHash ?? String(receipt);
+
+      return {
+        transactionHash: txHash,
+        userOpHash: (userOp as any).userOpHash ?? String(userOp),
+        smartAccountAddress: smartAccount.address as `0x${string}`,
+        network,
+        gasCost: 0,
+        sponsored: true,
+      };
+    },
+  };
+
+  return agentAccount;
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Types for @a3stack/accounts
+ */
+
+export interface CdpCredentials {
+  /** CDP API Key ID */
+  apiKeyId: string;
+  /** CDP API Key Secret */
+  apiKeySecret: string;
+  /** CDP Wallet Secret (EC P-256 PKCS8 key, base64-encoded) */
+  walletSecret: string;
+}
+
+export interface CreateAgentAccountOptions {
+  /** Human-readable name for the account (used for idempotent getOrCreate) */
+  name?: string;
+  /** Use testnet (Base Sepolia) instead of mainnet */
+  testnet?: boolean;
+}
+
+export interface AgentAccount {
+  /** Smart account address (ERC-4337) */
+  address: `0x${string}`;
+  /** Owner EOA address */
+  ownerAddress: `0x${string}`;
+  /** The network used */
+  network: "base" | "base-sepolia";
+  /** Send a gasless UserOperation */
+  sendUserOperation: (calls: UserOperationCall[]) => Promise<UserOperationResult>;
+  /** Register this agent on ERC-8004 with zero gas */
+  register: (options: RegisterOptions) => Promise<RegisterResult>;
+}
+
+export interface UserOperationCall {
+  to: `0x${string}`;
+  value?: bigint;
+  data?: `0x${string}`;
+}
+
+export interface UserOperationResult {
+  userOpHash: string;
+  transactionHash: string;
+}
+
+export interface RegisterOptions {
+  /** Agent name */
+  name: string;
+  /** Agent description */
+  description: string;
+  /** Agent image URL (optional) */
+  image?: string;
+  /** Service endpoints */
+  services?: Array<{ type: string; url: string }>;
+  /** Whether agent supports x402 payments */
+  x402Support?: boolean;
+  /** Existing registrations from other chains */
+  existingRegistrations?: Array<{
+    agentId: number;
+    agentRegistry: string;
+  }>;
+}
+
+export interface RegisterResult {
+  /** Transaction hash on Base */
+  transactionHash: string;
+  /** UserOperation hash */
+  userOpHash: string;
+  /** Smart account address */
+  smartAccountAddress: `0x${string}`;
+  /** Network used */
+  network: string;
+  /** Gas cost to user (always 0 with Paymaster) */
+  gasCost: number;
+  /** Whether gas was sponsored */
+  sponsored: boolean;
+}

package/test/integration.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Integration test for @a3stack/accounts
+ * 
+ * Tests:
+ * 1. Import from compiled dist
+ * 2. createAgentAccount() — creates smart account via CDP
+ * 3. agent.register() — gasless ERC-8004 registration on Base
+ * 4. gaslessRegister() — one-shot convenience function
+ * 
+ * Usage:
+ *   node test/integration.mjs [--live]
+ * 
+ * Without --live: tests imports and account creation only (no on-chain tx)
+ * With --live: executes a real gasless registration on Base mainnet
+ */
+
+import { execSync } from "child_process";
+
+// Import from compiled dist
+const {
+  createAgentAccount,
+  gaslessRegister,
+  REGISTRY_ADDRESS,
+  REGISTRY_ABI,
+  REGISTRATION_TYPE,
+} = await import("../dist/index.js");
+
+const LIVE = process.argv.includes("--live");
+
+function keychain(key) {
+  try {
+    return execSync(`security find-generic-password -s "${key}" -w 2>/dev/null`, {
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) {
+    console.error(`  ❌ FAIL: ${msg}`);
+    process.exit(1);
+  }
+  console.log(`  ✅ ${msg}`);
+}
+
+async function main() {
+  console.log("🧪 @a3stack/accounts Integration Tests\n");
+
+  // --- Test 1: Exports ---
+  console.log("1️⃣  Exports");
+  assert(typeof createAgentAccount === "function", "createAgentAccount is a function");
+  assert(typeof gaslessRegister === "function", "gaslessRegister is a function");
+  assert(REGISTRY_ADDRESS === "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", "REGISTRY_ADDRESS correct");
+  assert(Array.isArray(REGISTRY_ABI), "REGISTRY_ABI is an array");
+  assert(REGISTRATION_TYPE.includes("eip-8004"), "REGISTRATION_TYPE contains eip-8004");
+
+  // --- Test 2: Credentials ---
+  console.log("\n2️⃣  Credentials");
+  const credentials = {
+    apiKeyId: process.env.CDP_API_KEY_ID || keychain("cdp-api-key-id"),
+    apiKeySecret: process.env.CDP_API_KEY_SECRET || keychain("cdp-api-secret"),
+    walletSecret: process.env.CDP_WALLET_SECRET || keychain("cdp-wallet-secret"),
+  };
+  assert(!!credentials.apiKeyId, "CDP API Key ID loaded");
+  assert(!!credentials.apiKeySecret, "CDP API Key Secret loaded");
+  assert(!!credentials.walletSecret, "CDP Wallet Secret loaded");
+
+  // --- Test 3: Account creation ---
+  console.log("\n3️⃣  Account Creation");
+  const testName = `a3stack-test-${Date.now()}`;
+  const agent = await createAgentAccount(credentials, { name: testName });
+
+  assert(agent.address.startsWith("0x"), `Smart account: ${agent.address}`);
+  assert(agent.ownerAddress.startsWith("0x"), `Owner EOA: ${agent.ownerAddress}`);
+  assert(agent.network === "base", `Network: ${agent.network}`);
+  assert(typeof agent.sendUserOperation === "function", "sendUserOperation is a function");
+  assert(typeof agent.register === "function", "register is a function");
+
+  // --- Test 4: Idempotent retrieval ---
+  console.log("\n4️⃣  Idempotent Retrieval");
+  const agent2 = await createAgentAccount(credentials, { name: testName });
+  assert(agent2.address === agent.address, `Same name returns same address: ${agent2.address}`);
+  assert(agent2.ownerAddress === agent.ownerAddress, "Same owner address");
+
+  if (!LIVE) {
+    console.log("\n⏭️  Skipping live registration (run with --live to execute on-chain)");
+    console.log("\n✅ All tests passed!");
+    return;
+  }
+
+  // --- Test 5: Live gasless registration ---
+  console.log("\n5️⃣  Live Gasless Registration (Base mainnet)");
+  console.log("   ⛽ Sending UserOperation (CDP Paymaster sponsors gas)...");
+
+  const result = await agent.register({
+    name: "A3Stack Test Agent (integration)",
+    description: "Integration test for @a3stack/accounts package",
+    services: [{ type: "website", url: "https://a3stack.arcabot.ai" }],
+  });
+
+  assert(result.transactionHash.length > 0, `Tx hash: ${result.transactionHash}`);
+  assert(result.userOpHash.length > 0, `UserOp hash: ${result.userOpHash}`);
+  assert(result.smartAccountAddress === agent.address, "Smart account matches");
+  assert(result.network === "base", "Network is base");
+  assert(result.gasCost === 0, "Gas cost is $0");
+  assert(result.sponsored === true, "Gas was sponsored");
+
+  console.log(`\n🎉 Live registration successful!`);
+  console.log(`   BaseScan: https://basescan.org/tx/${result.transactionHash}`);
+
+  console.log("\n✅ All tests passed!");
+}
+
+main().catch((err) => {
+  console.error("\n❌ Test failed:", err.message || err);
+  if (err.cause) console.error("   Cause:", err.cause);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "noEmitOnError": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}