@q00bs/agent-sdk 1.0.0

package/dist/discovery.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * @q00bs/agent-sdk — Discovery Module
+ *
+ * Finds other registered agents on-chain based on trust proximity,
+ * activity status, and capabilities.
+ *
+ * HOW DISCOVERY WORKS:
+ *   1. Read totalSupply() from AgentRegistry to know how many agents exist.
+ *   2. Iterate through agents, filtering by:
+ *      - Active + not frozen
+ *      - Connected to the querying agent (trust path exists)
+ *      - Minimum trust score
+ *      - Max hops
+ *   3. Sort results by trust score (default) or recency.
+ *
+ * NOTE: For large agent populations, this on-chain iteration won't scale.
+ *   The Trust API server (api/) provides an indexed, paginated version.
+ *   This SDK module works well for <1000 agents.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDiscovery = void 0;
+const AgentRegistry_1 = require("./abis/AgentRegistry");
+const constants_1 = require("./constants");
+// ─────────────────────────────────────────────────────────────
+// AGENT DISCOVERY
+// ─────────────────────────────────────────────────────────────
+class AgentDiscovery {
+    client;
+    registryAddress;
+    trustResolver;
+    logger;
+    constructor(client, registryAddress, trustResolver, logger) {
+        this.client = client;
+        this.registryAddress = registryAddress;
+        this.trustResolver = trustResolver;
+        this.logger = logger;
+    }
+    /**
+     * Search for agents that match given criteria.
+     *
+     * @param myAgentId - Your agent's on-chain ID (used for trust-path filtering).
+     * @param query - Filters: minimum trust, max hops, limit, sort order.
+     * @returns Array of discovered agents, sorted by effective trust (descending).
+     *
+     * @example
+     * ```ts
+     * const agents = await discovery.find(1, {
+     *   minTrustScore: 50,
+     *   maxHops: 2,
+     *   limit: 10,
+     * });
+     * ```
+     */
+    async find(myAgentId, query = {}) {
+        const { minTrustScore = 0, maxHops = constants_1.DEFAULT_MAX_HOPS, limit = 20, sortBy = 'trust', } = query;
+        this.logger.info(`Discovering agents: minTrust=${minTrustScore}, maxHops=${maxHops}, limit=${limit}`);
+        // Get total agent count
+        const totalSupply = await this.client.readContract({
+            address: this.registryAddress,
+            abi: AgentRegistry_1.AGENT_REGISTRY_ABI,
+            functionName: 'totalSupply',
+        });
+        const total = Number(totalSupply);
+        this.logger.debug(`Total registered agents: ${total}`);
+        const results = [];
+        // Iterate through all agents (IDs start at 1)
+        for (let id = 1; id <= total && results.length < limit * 2; id++) {
+            if (id === myAgentId)
+                continue; // Skip self
+            try {
+                // Read agent record
+                const agentData = await this.client.readContract({
+                    address: this.registryAddress,
+                    abi: AgentRegistry_1.AGENT_REGISTRY_ABI,
+                    functionName: 'getAgent',
+                    args: [BigInt(id)],
+                });
+                // Skip inactive/frozen
+                if (!agentData.active || agentData.frozen)
+                    continue;
+                // Check raw trust score threshold
+                const rawTrust = Number(agentData.trustScore);
+                if (rawTrust / 100 < minTrustScore)
+                    continue;
+                // Check trust path
+                try {
+                    const trustPath = await this.trustResolver.resolve(myAgentId, id);
+                    if (!trustPath.connected || trustPath.pathLength > maxHops)
+                        continue;
+                    results.push({
+                        id,
+                        wallet: agentData.wallet,
+                        ownerQ00b: agentData.ownerQ00b,
+                        trustScore: rawTrust / 100,
+                        hops: trustPath.pathLength,
+                        effectiveTrust: trustPath.effectiveTrust / 100,
+                        active: true,
+                        capabilitiesHash: agentData.capabilitiesHash,
+                    });
+                }
+                catch {
+                    // No trust path → skip
+                    continue;
+                }
+            }
+            catch (error) {
+                this.logger.debug(`Skipping agent ${id}: ${error}`);
+                continue;
+            }
+        }
+        // Sort results
+        if (sortBy === 'trust') {
+            results.sort((a, b) => b.effectiveTrust - a.effectiveTrust);
+        }
+        else if (sortBy === 'recent') {
+            // Would need lastActiveAt — for now sort by ID desc (higher ID = more recent)
+            results.sort((a, b) => b.id - a.id);
+        }
+        // Apply limit
+        const limited = results.slice(0, limit);
+        this.logger.info(`Found ${limited.length} agents matching criteria`);
+        return limited;
+    }
+    /**
+     * Get a single agent by its on-chain ID.
+     *
+     * @param agentId - The agent's on-chain ID.
+     * @returns The agent record, or null if not found.
+     */
+    async getAgent(agentId) {
+        try {
+            const data = await this.client.readContract({
+                address: this.registryAddress,
+                abi: AgentRegistry_1.AGENT_REGISTRY_ABI,
+                functionName: 'getAgent',
+                args: [BigInt(agentId)],
+            });
+            // Check if agent exists (wallet will be zero address if not)
+            if (data.wallet === '0x0000000000000000000000000000000000000000') {
+                return null;
+            }
+            return {
+                wallet: data.wallet,
+                ownerQ00b: data.ownerQ00b,
+                sidePosition: Number(data.sidePosition),
+                capabilitiesHash: data.capabilitiesHash,
+                trustScore: Number(data.trustScore),
+                registeredAt: Number(data.registeredAt),
+                lastActiveAt: Number(data.lastActiveAt),
+                active: data.active,
+                frozen: data.frozen,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get an agent by its wallet address.
+     *
+     * @param wallet - The agent's wallet address.
+     * @returns Object with { id, agent } or null if not found.
+     */
+    async getAgentByWallet(wallet) {
+        try {
+            const [id, data] = await this.client.readContract({
+                address: this.registryAddress,
+                abi: AgentRegistry_1.AGENT_REGISTRY_ABI,
+                functionName: 'getAgentByWallet',
+                args: [wallet],
+            });
+            if (Number(id) === 0)
+                return null;
+            return {
+                id: Number(id),
+                agent: {
+                    wallet: data.wallet,
+                    ownerQ00b: data.ownerQ00b,
+                    sidePosition: Number(data.sidePosition),
+                    capabilitiesHash: data.capabilitiesHash,
+                    trustScore: Number(data.trustScore),
+                    registeredAt: Number(data.registeredAt),
+                    lastActiveAt: Number(data.lastActiveAt),
+                    active: data.active,
+                    frozen: data.frozen,
+                },
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if a specific agent is active and not frozen.
+     *
+     * @param agentId - The agent's on-chain ID.
+     */
+    async isActive(agentId) {
+        try {
+            return await this.client.readContract({
+                address: this.registryAddress,
+                abi: AgentRegistry_1.AGENT_REGISTRY_ABI,
+                functionName: 'isAgentActive',
+                args: [BigInt(agentId)],
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.AgentDiscovery = AgentDiscovery;
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

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

package/dist/erc8004.d.ts

@@ -0,0 +1,311 @@
+/**
+ * @q00bs/agent-sdk — ERC-8004 Trustless Agents Manager
+ *
+ * This module integrates the ERC-8004 standard (Trustless Agents) into the
+ * Q00bs agent platform. ERC-8004 defines three on-chain registries that give
+ * agents interoperable identity, reputation, and validation across the
+ * broader ecosystem — not just within Q00bs.
+ *
+ * WHY ERC-8004?
+ *   Q00bs agents already have identity via AgentRegistry (ERC-721) and trust
+ *   via the q00b graph. ERC-8004 adds a PORTABLE layer:
+ *     - Identity that other agent platforms can read and verify
+ *     - Reputation that follows an agent across ecosystems
+ *     - Validation from third-party auditors (compliance, capabilities)
+ *
+ *   Base is already implementing ERC-8004, making it the canonical standard
+ *   for agent identity on L2. Integrating now gives Q00bs agents first-mover
+ *   advantage in the interoperable agent economy.
+ *
+ * ARCHITECTURE:
+ *   ┌──────────────────┐     ┌────────────────────────────────────┐
+ *   │  Q00bs            │     │  ERC-8004 Registries (Base)         │
+ *   │  AgentRegistry    │────▶│  IdentityRegistry (0x8004...432)   │
+ *   │  (your agents)    │     │  ReputationRegistry (0x8004...b63) │
+ *   │                   │     │  ValidationRegistry (TBD)           │
+ *   └──────────────────┘     └────────────────────────────────────┘
+ *
+ *   Q00bs agents register in BOTH registries:
+ *     1. AgentRegistry (Q00bs-specific: trust scores, q00b graph, escrow)
+ *     2. ERC-8004 IdentityRegistry (ecosystem-wide: portable identity)
+ *
+ *   The ERC-8004 identity links back to the Q00bs agent via:
+ *     - agentWallet (same wallet address)
+ *     - agentURI (points to registration file with Q00bs metadata)
+ *     - Metadata keys (e.g. "q00bs_agent_id", "q00bs_trust_score")
+ *
+ * THREE REGISTRIES:
+ *
+ *   1. IDENTITY REGISTRY (ERC-721)
+ *      - Mint agent identity NFTs
+ *      - Set agentURI (registration file)
+ *      - Bind agent wallet with EIP-712/ERC-1271 proof
+ *      - Store extensible key-value metadata
+ *
+ *   2. REPUTATION REGISTRY
+ *      - Give signed fixed-point feedback to other agents
+ *      - Read aggregate reputation summaries
+ *      - Respond to feedback received
+ *      - Self-feedback is prevented on-chain
+ *
+ *   3. VALIDATION REGISTRY (evolving)
+ *      - Request validation from third-party validators
+ *      - Read validation results and summaries
+ *
+ * REFERENCE: https://www.8004.org/build
+ *
+ * USAGE:
+ *   ```ts
+ *   const manager = new ERC8004Manager(publicClient, walletClient, logger);
+ *
+ *   // Register an ERC-8004 identity
+ *   const identity = await manager.registerIdentity('0xOwnerAddress');
+ *
+ *   // Set the agent URI
+ *   await manager.setAgentURI(identity.agentId, 'https://q00bs.com/agents/42.json');
+ *
+ *   // Give feedback to another agent
+ *   await manager.giveFeedback({
+ *     subjectAgentId: 7,
+ *     value: 4.5,
+ *     decimals: 2,
+ *   }, myAgentId);
+ *
+ *   // Read reputation
+ *   const summary = await manager.getReputationSummary(7);
+ *   console.log(`Average: ${summary.average}`);
+ *   ```
+ */
+import type { PublicClient, WalletClient, Chain, Transport, Account } from 'viem';
+import type { ERC8004Config, ERC8004Identity, ERC8004AgentIdentifier, ERC8004Feedback, ERC8004ReputationSummary, ERC8004ValidationResult, ERC8004ValidationSummary, GiveFeedbackParams, Logger } from './types';
+export declare class ERC8004Manager {
+    private publicClient;
+    private walletClient?;
+    private logger;
+    private identityRegistry;
+    private reputationRegistry;
+    private validationRegistry;
+    private _erc8004AgentId?;
+    /** The agent's ERC-8004 agentId (if registered). */
+    get erc8004AgentId(): number | undefined;
+    /** The IdentityRegistry address being used. */
+    get identityRegistryAddress(): string;
+    /** The ReputationRegistry address being used. */
+    get reputationRegistryAddress(): string;
+    constructor(publicClient: PublicClient<Transport, Chain>, logger: Logger, walletClient?: WalletClient<Transport, Chain, Account>, config?: ERC8004Config);
+    /**
+     * Register a new ERC-8004 agent identity.
+     *
+     * Mints an ERC-721 token in the IdentityRegistry. The tokenId becomes
+     * the agent's ERC-8004 agentId.
+     *
+     * @param ownerAddress - Address to mint the identity NFT to.
+     * @returns The new ERC-8004 identity.
+     * @throws ERC8004RegistryError if the transaction fails.
+     *
+     * @example
+     * ```ts
+     * const identity = await erc8004.registerIdentity('0xYourAddress');
+     * console.log(`ERC-8004 ID: ${identity.agentId}`);
+     * console.log(`Identifier: ${identity.identifier}`);
+     * ```
+     */
+    registerIdentity(ownerAddress: string): Promise<ERC8004Identity>;
+    /**
+     * Get an ERC-8004 identity by agentId.
+     *
+     * @param agentId - The ERC-8004 agentId (tokenId).
+     * @returns The identity, or null if not found.
+     */
+    getIdentity(agentId: number): Promise<ERC8004Identity | null>;
+    /**
+     * Set the agentURI (tokenURI) for an ERC-8004 identity.
+     *
+     * The agentURI should point to a JSON file describing the agent
+     * (name, capabilities, endpoints, etc.).
+     *
+     * @param agentId - The ERC-8004 agentId.
+     * @param uri - The URI to set (IPFS, HTTPS, etc.).
+     *
+     * @example
+     * ```ts
+     * await erc8004.setAgentURI(42, 'ipfs://Qm.../agent.json');
+     * ```
+     */
+    setAgentURI(agentId: number, uri: string): Promise<void>;
+    /**
+     * Get metadata for an ERC-8004 identity.
+     *
+     * @param agentId - The ERC-8004 agentId.
+     * @param key - The metadata key to read.
+     * @returns The metadata value (empty string if not set).
+     */
+    getMetadata(agentId: number, key: string): Promise<string>;
+    /**
+     * Set metadata on an ERC-8004 identity.
+     *
+     * Use this to store Q00bs-specific data on the ERC-8004 identity,
+     * making it discoverable by other platforms.
+     *
+     * @param agentId - The ERC-8004 agentId.
+     * @param key - The metadata key (cannot be "agentWallet" — use setAgentWallet).
+     * @param value - The metadata value.
+     *
+     * @example
+     * ```ts
+     * await erc8004.setMetadata(42, 'q00bs_agent_id', '7');
+     * await erc8004.setMetadata(42, 'q00bs_trust_score', '8500');
+     * await erc8004.setMetadata(42, 'capabilities', 'data_analysis,web_scraping');
+     * ```
+     */
+    setMetadata(agentId: number, key: string, value: string): Promise<void>;
+    /**
+     * Get the agent wallet address for an ERC-8004 identity.
+     *
+     * @param agentId - The ERC-8004 agentId.
+     * @returns The wallet address, or null if not set.
+     */
+    getAgentWallet(agentId: number): Promise<string | null>;
+    /**
+     * Set the agent wallet for an ERC-8004 identity with EIP-712/ERC-1271 proof.
+     *
+     * The proof ensures the wallet owner has consented to being linked
+     * to this identity. In practice, this means the agent wallet signs
+     * a typed-data message proving ownership.
+     *
+     * @param agentId - The ERC-8004 agentId.
+     * @param wallet - The wallet address to bind.
+     * @param proof - The EIP-712 or ERC-1271 proof bytes.
+     */
+    setAgentWallet(agentId: number, wallet: string, proof: `0x${string}`): Promise<void>;
+    /**
+     * Get the total number of ERC-8004 identities registered.
+     */
+    getIdentityCount(): Promise<number>;
+    /**
+     * Give feedback to another agent via the ERC-8004 ReputationRegistry.
+     *
+     * Feedback is a signed fixed-point number (e.g. 4.5 → value=450, decimals=2).
+     * Self-feedback is prevented at the contract level.
+     *
+     * @param params - Feedback parameters (subject, value, decimals).
+     * @param fromAgentId - The ERC-8004 agentId of the feedback giver (your agent).
+     * @param fromIdentityRegistry - Override sender's identity registry (default: this one).
+     * @returns The feedback index.
+     *
+     * @example
+     * ```ts
+     * const index = await erc8004.giveFeedback({
+     *   subjectAgentId: 7,
+     *   value: 4.5,
+     *   decimals: 2,
+     * }, myERC8004AgentId);
+     * ```
+     */
+    giveFeedback(params: GiveFeedbackParams, fromAgentId: number, fromIdentityRegistry?: string): Promise<number>;
+    /**
+     * Revoke previously given feedback.
+     *
+     * @param subjectAgentId - The agent that received the feedback.
+     * @param fromAgentId - Your agent's ERC-8004 ID.
+     * @param feedbackIndex - The index of the feedback to revoke.
+     * @param subjectIdentityRegistry - Override subject's registry.
+     * @param fromIdentityRegistry - Override sender's registry.
+     */
+    revokeFeedback(subjectAgentId: number, fromAgentId: number, feedbackIndex: number, subjectIdentityRegistry?: string, fromIdentityRegistry?: string): Promise<void>;
+    /**
+     * Append a response to feedback your agent received.
+     *
+     * @param agentId - Your agent's ERC-8004 ID.
+     * @param fromAgentId - The feedback giver's ERC-8004 ID.
+     * @param feedbackIndex - The index of the feedback to respond to.
+     * @param response - The response text.
+     * @param fromIdentityRegistry - Override feedback giver's registry.
+     */
+    respondToFeedback(agentId: number, fromAgentId: number, feedbackIndex: number, response: string, fromIdentityRegistry?: string): Promise<void>;
+    /**
+     * Read a specific feedback entry.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @param index - The feedback index.
+     * @param identityRegistry - Override identity registry.
+     * @returns The feedback entry.
+     */
+    readFeedback(agentId: number, index: number, identityRegistry?: string): Promise<ERC8004Feedback>;
+    /**
+     * Read all feedback entries for an agent.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @param identityRegistry - Override identity registry.
+     * @returns Array of all feedback entries.
+     */
+    readAllFeedback(agentId: number, identityRegistry?: string): Promise<ERC8004Feedback[]>;
+    /**
+     * Get the reputation summary for an agent.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @param identityRegistry - Override identity registry.
+     * @returns Aggregate reputation summary.
+     *
+     * @example
+     * ```ts
+     * const rep = await erc8004.getReputationSummary(42);
+     * console.log(`${rep.count} ratings, average: ${rep.average.toFixed(2)}`);
+     * ```
+     */
+    getReputationSummary(agentId: number, identityRegistry?: string): Promise<ERC8004ReputationSummary>;
+    /**
+     * Get the last feedback index for an agent.
+     */
+    getLastFeedbackIndex(agentId: number, identityRegistry?: string): Promise<number>;
+    /**
+     * Request validation from a validator contract.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @param validatorContract - The validator contract address.
+     * @returns The validation request ID.
+     */
+    requestValidation(agentId: number, validatorContract: string): Promise<number>;
+    /**
+     * Get the status of a validation request.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @param requestId - The validation request ID.
+     * @returns The validation result.
+     */
+    getValidationStatus(agentId: number, requestId: number): Promise<ERC8004ValidationResult>;
+    /**
+     * Get the validation summary for an agent.
+     *
+     * @param agentId - The agent's ERC-8004 ID.
+     * @returns Validation summary with counts.
+     */
+    getValidationSummary(agentId: number): Promise<ERC8004ValidationSummary>;
+    /**
+     * Sync a Q00bs agent's trust score to ERC-8004 metadata.
+     *
+     * This writes the Q00bs trust score as metadata on the ERC-8004 identity,
+     * making it visible to other agent platforms that read ERC-8004.
+     *
+     * @param erc8004AgentId - The agent's ERC-8004 ID.
+     * @param q00bsAgentId - The agent's Q00bs AgentRegistry ID.
+     * @param trustScore - The Q00bs trust score (0-10000).
+     */
+    syncTrustToMetadata(erc8004AgentId: number, q00bsAgentId: number, trustScore: number): Promise<void>;
+    /**
+     * Build the full ERC-8004 agent identifier string.
+     *
+     * Format: {namespace}:{chainId}:{identityRegistry}:{agentId}
+     */
+    buildIdentifier(agentId: number): string;
+    /**
+     * Parse an ERC-8004 agent identifier string.
+     *
+     * @param identifier - The identifier string.
+     * @returns Parsed components.
+     */
+    static parseIdentifier(identifier: string): ERC8004AgentIdentifier;
+    private ensureWalletClient;
+    private ensureValidationRegistry;
+}
+//# sourceMappingURL=erc8004.d.ts.map

package/dist/erc8004.d.ts.map

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