@a3stack/core 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@a3stack/core",
+  "version": "0.1.0",
+  "description": "A3Stack SDK — identity + payments + data for AI agents",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --outDir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@a3stack/identity": "file:../identity",
+    "@a3stack/payments": "file:../payments",
+    "@a3stack/data": "file:../data",
+    "viem": "^2.39.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,262 @@
+/**
+ * A3Stack — the all-in-one glue layer
+ * Combines identity + payments + data into one clean interface
+ */
+
+import type { Account } from "viem";
+import { z } from "zod";
+import { AgentIdentity, verifyAgent, getMcpEndpoint, IDENTITY_REGISTRY_ADDRESS } from "@a3stack/identity";
+import type { VerificationResult } from "@a3stack/identity";
+import { PaymentClient } from "@a3stack/payments";
+import { AgentMcpServerInstance, createAgentMcpClient, probeAgent } from "@a3stack/data";
+import type { AgentProbeResult } from "@a3stack/data";
+import type { AgentMcpClientInstance } from "@a3stack/data";
+import type { A3StackConfig, A3StackRegisterOptions } from "./types.js";
+
+export class A3Stack {
+  private config: A3StackConfig;
+  private identity: AgentIdentity;
+  private payer: PaymentClient;
+  private mcpServer?: AgentMcpServerInstance;
+  private _agentId?: number;
+  private _serverUrl?: string;
+
+  constructor(config: A3StackConfig) {
+    this.config = config;
+
+    // Initialize identity manager
+    this.identity = new AgentIdentity({
+      account: config.account,
+      chain: config.chain,
+      rpc: config.rpc,
+    });
+
+    // Initialize payment client
+    this.payer = new PaymentClient({
+      account: config.account,
+      chains: [`eip155:${config.chain.id}`, "eip155:*"],
+      ...config.payer,
+    });
+
+    // Initialize MCP server if configured
+    if (config.server) {
+      // Determine payTo address (default to agent's own wallet)
+      const payTo = config.server.payment?.payTo ?? config.account.address;
+
+      this.mcpServer = new AgentMcpServerInstance({
+        name: config.server.name,
+        version: config.server.version ?? "0.1.0",
+        port: config.server.port ?? 3000,
+        cors: config.server.cors ?? true,
+        payment: config.server.payment
+          ? {
+              ...config.server.payment,
+              payTo,
+            }
+          : undefined,
+      });
+    }
+  }
+
+  /**
+   * Register this agent on-chain via ERC-8004.
+   * Call this once to create your agent identity.
+   */
+  async register(options: A3StackRegisterOptions): Promise<{
+    agentId: number;
+    txHash: `0x${string}`;
+    globalId: string;
+  }> {
+    // Check if already registered
+    const { registered } = await this.identity.isRegistered();
+    if (registered) {
+      throw new Error(
+        `Agent is already registered on chain ${this.config.chain.id}. ` +
+          `Use updateIdentity() to change your registration.`
+      );
+    }
+
+    // Auto-add MCP server endpoint if configured
+    const services = [...(options.services ?? [])];
+    if (
+      options.includeServerEndpoint !== false &&
+      this.config.server &&
+      this._serverUrl
+    ) {
+      const hasMcp = services.some((s) => s.name.toUpperCase() === "MCP");
+      if (!hasMcp) {
+        services.push({
+          name: "MCP",
+          endpoint: options.mcpUrl ?? this._serverUrl,
+          version: "2025-06-18",
+        });
+      }
+    }
+
+    const result = await this.identity.register({ ...options, services });
+    this._agentId = result.agentId;
+    return result;
+  }
+
+  /**
+   * Start the MCP server (if configured).
+   * Returns the server URL.
+   */
+  async start(port?: number): Promise<{ url: string }> {
+    if (!this.mcpServer) {
+      throw new Error(
+        "No server configured. Pass server config to A3Stack constructor."
+      );
+    }
+    const result = await this.mcpServer.listen(port);
+    this._serverUrl = result.url;
+    return result;
+  }
+
+  /**
+   * Stop the MCP server
+   */
+  async stop(): Promise<void> {
+    await this.mcpServer?.close();
+  }
+
+  /**
+   * Register a tool on this agent's MCP server.
+   * Handler must return a CallToolResult: { content: [{ type: "text", text: string }] }
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tool(
+    name: string,
+    description: string,
+    paramsSchema: Record<string, z.ZodTypeAny>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler: (args: any) => Promise<any>
+  ): void {
+    if (!this.mcpServer) {
+      throw new Error("No server configured. Pass server config to A3Stack constructor.");
+    }
+    this.mcpServer.tool(name, description, paramsSchema, handler);
+  }
+
+  /**
+   * Register a resource on this agent's MCP server
+   */
+  resource(
+    name: string,
+    uri: string,
+    description: string,
+    handler: (uri: URL) => Promise<{ contents: Array<{ uri: string; text: string; mimeType?: string }> }>
+  ): void {
+    if (!this.mcpServer) {
+      throw new Error("No server configured.");
+    }
+    this.mcpServer.resource(name, uri, description, handler);
+  }
+
+  /**
+   * Connect to another agent by ERC-8004 global ID.
+   * Auto-resolves MCP endpoint and handles payment.
+   */
+  async connect(agentGlobalId: string): Promise<AgentMcpClientInstance> {
+    return createAgentMcpClient({
+      agentId: agentGlobalId,
+      payer: {
+        account: this.config.account,
+        maxAmount: this.config.payer?.maxAmountPerRequest,
+      },
+    });
+  }
+
+  /**
+   * Connect to another agent by direct URL (no identity verification)
+   */
+  async connectUrl(url: string): Promise<AgentMcpClientInstance> {
+    return createAgentMcpClient({
+      url,
+      payer: {
+        account: this.config.account,
+        maxAmount: this.config.payer?.maxAmountPerRequest,
+      },
+    });
+  }
+
+  /**
+   * Verify another agent's identity before interacting
+   */
+  async verify(agentGlobalId: string): Promise<VerificationResult> {
+    return verifyAgent(agentGlobalId);
+  }
+
+  /**
+   * Probe another agent — discover capabilities without connecting.
+   * Returns identity, endpoints, payment requirements, services.
+   * Read-only, no wallet needed for the target agent.
+   */
+  async probe(agentGlobalId: string): Promise<AgentProbeResult> {
+    return probeAgent(agentGlobalId);
+  }
+
+  /**
+   * Get another agent's MCP endpoint
+   */
+  async getMcpEndpoint(agentGlobalId: string): Promise<string | null> {
+    return getMcpEndpoint(agentGlobalId);
+  }
+
+  /**
+   * Check USDC balance on current chain
+   */
+  async getBalance() {
+    return this.payer.getBalance(`eip155:${this.config.chain.id}`, this.config.rpc);
+  }
+
+  /**
+   * The payment-wrapped fetch for making calls to paid APIs
+   */
+  get fetch() {
+    return this.payer.fetch;
+  }
+
+  /**
+   * Current agent ID (set after register())
+   */
+  get agentId(): number | undefined {
+    return this._agentId;
+  }
+
+  /**
+   * Current global agent ID (set after register() + start())
+   */
+  get globalId(): string | undefined {
+    if (!this._agentId) return undefined;
+    return `eip155:${this.config.chain.id}:${IDENTITY_REGISTRY_ADDRESS}#${this._agentId}`;
+  }
+
+  /**
+   * MCP server URL (set after start())
+   */
+  get serverUrl(): string | undefined {
+    return this._serverUrl;
+  }
+
+  /**
+   * Raw identity manager for advanced ERC-8004 operations
+   */
+  get identityManager(): AgentIdentity {
+    return this.identity;
+  }
+
+  /**
+   * Raw payment client for advanced payment operations
+   */
+  get paymentClient(): PaymentClient {
+    return this.payer;
+  }
+
+  /**
+   * Raw MCP server for advanced operations
+   */
+  get mcpServerInstance(): AgentMcpServerInstance | undefined {
+    return this.mcpServer;
+  }
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @a3stack/core
+ * A3Stack SDK — identity + payments + data for AI agents
+ *
+ * The all-in-one glue layer. Import just what you need:
+ *   import { A3Stack } from "@a3stack/core"
+ *
+ * Or use individual packages for more control:
+ *   import { AgentIdentity } from "@a3stack/identity"
+ *   import { PaymentClient } from "@a3stack/payments"
+ *   import { createAgentMcpServer } from "@a3stack/data"
+ */
+
+// Main class
+export { A3Stack } from "./agent.js";
+
+// Re-export everything from sub-packages for convenience
+export {
+  // Identity
+  AgentIdentity,
+  verifyAgent,
+  parseAgentId,
+  formatAgentId,
+  fetchRegistrationFile,
+  getMcpEndpoint,
+  getA2aEndpoint,
+  getAgentCount,
+  findAllRegistrations,
+  IDENTITY_REGISTRY_ADDRESS,
+  SUPPORTED_CHAINS,
+} from "@a3stack/identity";
+
+export type {
+  AgentRegistrationFile,
+  AgentService,
+  AgentRef,
+  VerificationResult,
+  RegisterOptions,
+  RegisterResult,
+} from "@a3stack/identity";
+
+export {
+  // Payments
+  PaymentClient,
+  PaymentServer,
+  createPaymentClient,
+  createPaymentServer,
+  USDC_BASE,
+  USDC_ETH,
+  DEFAULT_NETWORK,
+  NETWORK_USDC,
+} from "@a3stack/payments";
+
+export type {
+  PaymentClientConfig,
+  PaymentServerConfig,
+  PaymentDetails,
+  PaymentBalance,
+  PaymentVerifyResult,
+} from "@a3stack/payments";
+
+export {
+  // Data / MCP
+  createAgentMcpServer,
+  createAgentMcpClient,
+  AgentMcpServerInstance,
+  AgentMcpClientInstance,
+  probeAgent,
+} from "@a3stack/data";
+
+export type { AgentMcpServerConfig, AgentMcpClientConfig, AgentProbeResult } from "@a3stack/data";
+
+export type { A3StackConfig, A3StackRegisterOptions } from "./types.js";

package/src/types.ts

@@ -0,0 +1,55 @@
+/**
+ * @a3stack/core — Type Definitions
+ */
+
+import type { Chain, Account } from "viem";
+import type { RegisterOptions } from "@a3stack/identity";
+import type { PaymentServerConfig, PaymentClientConfig } from "@a3stack/payments";
+
+export interface A3StackConfig {
+  /**
+   * viem Account (e.g. from privateKeyToAccount())
+   * Must have signTransaction for on-chain write operations (register, setAgentURI)
+   * Can be a read-only account (address only) for read/verify operations
+   */
+  account: Account;
+
+  /**
+   * viem Chain (e.g. import { base } from "viem/chains")
+   */
+  chain: Chain;
+
+  /**
+   * RPC URL override for the chain
+   */
+  rpc?: string;
+
+  /**
+   * MCP Server configuration.
+   * If provided, this A3Stack instance can serve MCP tools.
+   */
+  server?: {
+    name: string;
+    version?: string;
+    port?: number;
+    cors?: boolean;
+    /** Require payment to call tools */
+    payment?: Omit<PaymentServerConfig, "payTo"> & { payTo?: `0x${string}` };
+  };
+
+  /**
+   * Payment client configuration for calling other agents.
+   * Defaults to auto-configured from account + chain.
+   */
+  payer?: Omit<PaymentClientConfig, "account">;
+}
+
+export interface A3StackRegisterOptions extends RegisterOptions {
+  /**
+   * If true, auto-include the current MCP server URL in services.
+   * Only valid if server.port is configured.
+   */
+  includeServerEndpoint?: boolean;
+  /** Override the MCP URL to include in services */
+  mcpUrl?: string;
+}