@q00bs/agent-sdk 1.0.0

package/dist/consensus.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * @q00bs/agent-sdk — Consensus Module
+ *
+ * Handles multi-agent voting for high-stakes actions.
+ *
+ * WHEN IS CONSENSUS NEEDED?
+ *   Actions above certain ETH thresholds require approval from peer agents
+ *   in the initiator's trust network. This prevents rogue agents from
+ *   unilaterally making expensive decisions.
+ *
+ *   Value ≤ 0.01 ETH  → No consensus (auto-approved)
+ *   Value ≤ 0.10 ETH  → 2 of 6 peer agents must approve
+ *   Value ≤ 1.00 ETH  → 4 of 6 peer agents must approve
+ *   Value > 1.00 ETH  → 4 of 6 peer agents + the human owner must approve
+ *
+ * FLOW:
+ *   1. Initiator calls requestConsensus() → gets a requestId.
+ *   2. Peer agents in the trust network call vote() with approve/reject.
+ *   3. If human approval is required, the owner calls humanApprove().
+ *   4. Once thresholds are met, the contract sets state to APPROVED.
+ *   5. Initiator calls markExecuted() after completing the action.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsensusManager = void 0;
+const viem_1 = require("viem");
+const ConsensusModule_1 = require("./abis/ConsensusModule");
+const errors_1 = require("./errors");
+// Default timeout: 1 hour
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+// ─────────────────────────────────────────────────────────────
+// CONSENSUS MANAGER
+// ─────────────────────────────────────────────────────────────
+class ConsensusManager {
+    publicClient;
+    walletClient;
+    consensusAddress;
+    logger;
+    constructor(publicClient, walletClient, consensusAddress, logger) {
+        this.publicClient = publicClient;
+        this.walletClient = walletClient;
+        this.consensusAddress = consensusAddress;
+        this.logger = logger;
+    }
+    /**
+     * Request consensus for an action.
+     *
+     * @param agentId - Your agent's on-chain ID.
+     * @param params - Action description, value, and optional timeout.
+     * @returns The new consensus request ID.
+     *
+     * @example
+     * ```ts
+     * const requestId = await consensus.request(1, {
+     *   actionDescription: 'Transfer 0.5 ETH to agent 7 for data processing',
+     *   valueEth: '0.5',
+     *   timeoutMs: 3600000, // 1 hour
+     * });
+     * ```
+     */
+    async request(agentId, params) {
+        const actionHash = (0, viem_1.keccak256)((0, viem_1.toHex)(params.actionDescription));
+        const value = (0, viem_1.parseEther)(params.valueEth);
+        const timeoutSec = Math.floor((params.timeoutMs || DEFAULT_TIMEOUT_MS) / 1000);
+        this.logger.info(`Requesting consensus: agent ${agentId}, value ${params.valueEth} ETH, ` +
+            `timeout ${timeoutSec}s`);
+        try {
+            const hash = await this.walletClient.writeContract({
+                address: this.consensusAddress,
+                abi: ConsensusModule_1.CONSENSUS_MODULE_ABI,
+                functionName: 'requestConsensus',
+                args: [BigInt(agentId), actionHash, value, BigInt(timeoutSec)],
+            });
+            const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+            this.logger.info(`Consensus request tx confirmed in block ${receipt.blockNumber}`);
+            // Parse request ID from event
+            const requestId = this.parseRequestIdFromReceipt(receipt);
+            return requestId;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new errors_1.ContractCallError(this.consensusAddress, 'requestConsensus', msg);
+        }
+    }
+    /**
+     * Vote on a consensus request.
+     *
+     * @param requestId - The consensus request to vote on.
+     * @param voterAgentId - Your agent's on-chain ID.
+     * @param approve - true to approve, false to reject.
+     */
+    async vote(requestId, voterAgentId, approve) {
+        this.logger.info(`Voting on request ${requestId}: agent ${voterAgentId} → ${approve ? 'APPROVE' : 'REJECT'}`);
+        try {
+            const hash = await this.walletClient.writeContract({
+                address: this.consensusAddress,
+                abi: ConsensusModule_1.CONSENSUS_MODULE_ABI,
+                functionName: 'vote',
+                args: [BigInt(requestId), BigInt(voterAgentId), approve],
+            });
+            await this.publicClient.waitForTransactionReceipt({ hash });
+            this.logger.info(`Vote on request ${requestId} confirmed`);
+            return hash;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new errors_1.ContractCallError(this.consensusAddress, 'vote', msg);
+        }
+    }
+    /**
+     * Mark a consensus request as executed (after the approved action is done).
+     *
+     * @param requestId - The request to finalize.
+     */
+    async markExecuted(requestId) {
+        this.logger.info(`Marking request ${requestId} as executed`);
+        try {
+            const hash = await this.walletClient.writeContract({
+                address: this.consensusAddress,
+                abi: ConsensusModule_1.CONSENSUS_MODULE_ABI,
+                functionName: 'markExecuted',
+                args: [BigInt(requestId)],
+            });
+            await this.publicClient.waitForTransactionReceipt({ hash });
+            this.logger.info(`Request ${requestId} marked executed`);
+            return hash;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new errors_1.ContractCallError(this.consensusAddress, 'markExecuted', msg);
+        }
+    }
+    /**
+     * Read a consensus request from the chain.
+     *
+     * @param requestId - The request to query.
+     */
+    async get(requestId) {
+        const raw = await this.publicClient.readContract({
+            address: this.consensusAddress,
+            abi: ConsensusModule_1.CONSENSUS_MODULE_ABI,
+            functionName: 'getRequest',
+            args: [BigInt(requestId)],
+        });
+        return {
+            id: requestId,
+            initiatorAgentId: Number(raw.initiatorAgentId),
+            actionHash: raw.actionHash,
+            value: raw.value,
+            requiredApprovals: Number(raw.requiredApprovals),
+            currentApprovals: Number(raw.currentApprovals),
+            currentRejections: Number(raw.currentRejections),
+            state: Number(raw.state),
+            createdAt: Number(raw.createdAt),
+            expiresAt: Number(raw.expiresAt),
+            humanApprovalRequired: raw.humanApprovalRequired,
+            humanApproved: raw.humanApproved,
+        };
+    }
+    /**
+     * Check if a consensus request has been approved.
+     *
+     * @param requestId - The request to check.
+     */
+    async isApproved(requestId) {
+        return await this.publicClient.readContract({
+            address: this.consensusAddress,
+            abi: ConsensusModule_1.CONSENSUS_MODULE_ABI,
+            functionName: 'isApproved',
+            args: [BigInt(requestId)],
+        });
+    }
+    /**
+     * Poll for consensus result (blocking, with timeout).
+     * Useful when you need to wait for peer agents to vote.
+     *
+     * @param requestId - The request to wait on.
+     * @param pollIntervalMs - How often to check (default: 10s).
+     * @param timeoutMs - Maximum wait time (default: matches request timeout).
+     */
+    async waitForResult(requestId, pollIntervalMs = 10_000, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const record = await this.get(requestId);
+            if (record.state === 1) {
+                // APPROVED
+                return {
+                    requestId,
+                    approved: true,
+                    approvals: record.currentApprovals,
+                    rejections: record.currentRejections,
+                    humanApproved: record.humanApproved,
+                };
+            }
+            if (record.state === 2) {
+                // REJECTED
+                throw new errors_1.ConsensusRejectedError(requestId, record.currentApprovals, record.currentRejections);
+            }
+            if (record.state === 3) {
+                // EXPIRED
+                throw new errors_1.ConsensusTimeoutError(requestId);
+            }
+            // Still PENDING — wait and poll again
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+        throw new errors_1.ConsensusTimeoutError(requestId);
+    }
+    // ── Private helpers ─────────────────────────────────────────
+    parseRequestIdFromReceipt(receipt) {
+        for (const log of receipt.logs) {
+            try {
+                if (log.address?.toLowerCase() === this.consensusAddress.toLowerCase()) {
+                    if (log.topics && log.topics.length > 1) {
+                        return Number(BigInt(log.topics[1]));
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        this.logger.warn('Could not parse requestId from receipt');
+        return -1;
+    }
+}
+exports.ConsensusManager = ConsensusManager;
+//# sourceMappingURL=consensus.js.map

package/dist/consensus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.js","sourceRoot":"","sources":["../src/consensus.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAGH,+BAAoD;AACpD,4DAA8D;AAC9D,qCAIkB;AASlB,0BAA0B;AAC1B,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1C,gEAAgE;AAChE,oBAAoB;AACpB,gEAAgE;AAEhE,MAAa,gBAAgB;IACnB,YAAY,CAAiC;IAC7C,YAAY,CAA0C;IACtD,gBAAgB,CAAgB;IAChC,MAAM,CAAS;IAEvB,YACE,YAA4C,EAC5C,YAAqD,EACrD,gBAAwB,EACxB,MAAc;QAEd,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,gBAAgB,GAAG,gBAAiC,CAAC;QAC1D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,MAAuB;QACpD,MAAM,UAAU,GAAG,IAAA,gBAAS,EAAC,IAAA,YAAK,EAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,IAAA,iBAAU,EAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC,GAAG,IAAI,CAAC,CAAC;QAE/E,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,+BAA+B,OAAO,WAAW,MAAM,CAAC,QAAQ,QAAQ;YACxE,WAAW,UAAU,GAAG,CACzB,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC;gBACjD,OAAO,EAAE,IAAI,CAAC,gBAAgB;gBAC9B,GAAG,EAAE,sCAAoB;gBACzB,YAAY,EAAE,kBAAkB;gBAChC,IAAI,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;aAC/D,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;YAEnF,8BAA8B;YAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC;YAC1D,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,IAAI,0BAAiB,CAAC,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,GAAG,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,YAAoB,EAAE,OAAgB;QAClE,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,qBAAqB,SAAS,WAAW,YAAY,MAAM,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAC5F,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC;gBACjD,OAAO,EAAE,IAAI,CAAC,gBAAgB;gBAC9B,GAAG,EAAE,sCAAoB;gBACzB,YAAY,EAAE,MAAM;gBACpB,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;aACzD,CAAC,CAAC;YAEH,MAAM,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,SAAS,YAAY,CAAC,CAAC;YAC3D,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,IAAI,0BAAiB,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,SAAiB;QAClC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,SAAS,cAAc,CAAC,CAAC;QAE7D,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC;gBACjD,OAAO,EAAE,IAAI,CAAC,gBAAgB;gBAC9B,GAAG,EAAE,sCAAoB;gBACzB,YAAY,EAAE,cAAc;gBAC5B,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;aAC1B,CAAC,CAAC;YAEH,MAAM,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,SAAS,kBAAkB,CAAC,CAAC;YACzD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,IAAI,0BAAiB,CAAC,IAAI,CAAC,gBAAgB,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,SAAiB;QACzB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;YAC/C,OAAO,EAAE,IAAI,CAAC,gBAAgB;YAC9B,GAAG,EAAE,sCAAoB;YACzB,YAAY,EAAE,YAAY;YAC1B,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;SAC1B,CAAQ,CAAC;QAEV,OAAO;YACL,EAAE,EAAE,SAAS;YACb,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;YAC9C,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,iBAAiB,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;YAChD,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;YAC9C,iBAAiB,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;YAChD,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAmB;YAC1C,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;YAChC,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;YAChC,qBAAqB,EAAE,GAAG,CAAC,qBAAqB;YAChD,aAAa,EAAE,GAAG,CAAC,aAAa;SACjC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;YAC1C,OAAO,EAAE,IAAI,CAAC,gBAAgB;YAC9B,GAAG,EAAE,sCAAoB;YACzB,YAAY,EAAE,YAAY;YAC1B,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;SAC1B,CAAY,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,aAAa,CACjB,SAAiB,EACjB,cAAc,GAAG,MAAM,EACvB,SAAS,GAAG,kBAAkB;QAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAExC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAEzC,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;gBACvB,WAAW;gBACX,OAAO;oBACL,SAAS;oBACT,QAAQ,EAAE,IAAI;oBACd,SAAS,EAAE,MAAM,CAAC,gBAAgB;oBAClC,UAAU,EAAE,MAAM,CAAC,iBAAiB;oBACpC,aAAa,EAAE,MAAM,CAAC,aAAa;iBACpC,CAAC;YACJ,CAAC;YAED,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;gBACvB,WAAW;gBACX,MAAM,IAAI,+BAAsB,CAC9B,SAAS,EACT,MAAM,CAAC,gBAAgB,EACvB,MAAM,CAAC,iBAAiB,CACzB,CAAC;YACJ,CAAC;YAED,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;gBACvB,UAAU;gBACV,MAAM,IAAI,8BAAqB,CAAC,SAAS,CAAC,CAAC;YAC7C,CAAC;YAED,sCAAsC;YACtC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,IAAI,8BAAqB,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,+DAA+D;IAEvD,yBAAyB,CAAC,OAAY;QAC5C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,EAAE,CAAC;oBACvE,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACxC,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBACvC,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;QAC3D,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;CACF;AApOD,4CAoOC"}

package/dist/constants.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @q00bs/agent-sdk — Constants
+ *
+ * All chain IDs, contract addresses, and default values.
+ * Contract addresses for AgentRegistry, AgentEscrow, and ConsensusModule
+ * are placeholders until you deploy them — see the deployment guide in README.md.
+ */
+/** Base mainnet chain ID. */
+export declare const BASE_CHAIN_ID = 8453;
+/** Default Base mainnet RPC URL (public, rate-limited — use your own for production). */
+export declare const DEFAULT_RPC_URL = "https://mainnet.base.org";
+/**
+ * q00bFactory — LIVE on Base since Jan 15 2026.
+ * This is YOUR existing deployed contract. Do NOT change.
+ */
+export declare const Q00B_FACTORY_ADDRESS = "0xe611b837E2D06f92D4a258e77fab8a26b33452b0";
+/**
+ * Genesis Q00b — the first q00b ever deployed.
+ */
+export declare const GENESIS_Q00B_ADDRESS = "0x14597A318D4C03ABbB8E054d31591541E446cB54";
+/**
+ * AgentRegistry — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+export declare const AGENT_REGISTRY_ADDRESS = "0xF7c8acecdfbBEAf08F596ab1F85f68f7E6568172";
+/**
+ * AgentEscrow — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+export declare const AGENT_ESCROW_ADDRESS = "0xe1139A7BebD89e534d4C459b252BA0963e0A0499";
+/**
+ * ConsensusModule — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+export declare const CONSENSUS_MODULE_ADDRESS = "0xcB4A36a7c99e42B3F4b1c8EE6EDD0f3A7DDEcC76";
+/** Maximum trust score (100.00% stored as integer). */
+export declare const MAX_TRUST_SCORE = 10000;
+/** New agents start at 50% of their owner's trust score. */
+export declare const INITIAL_TRUST_DIVISOR = 2;
+/** Trust decays by 15% per hop in the q00b graph. */
+export declare const TRUST_DECAY_PER_HOP_PERCENT = 15;
+/** Minimum effective trust floor (10%). */
+export declare const MIN_TRUST_FLOOR_PERCENT = 10;
+/** Default max hops for communication. */
+export declare const DEFAULT_MAX_HOPS = 3;
+/** Default max single transaction value: 0.1 ETH. */
+export declare const DEFAULT_MAX_TX_VALUE_ETH = "0.1";
+/** Default daily spend limit: 1 ETH. */
+export declare const DEFAULT_DAILY_LIMIT_ETH = "1";
+/** Maximum number of sides on a q00b. */
+export declare const MAX_Q00B_SIDES = 6;
+/** Protocol fee in basis points (100 = 1%). */
+export declare const PROTOCOL_FEE_BPS = 100;
+/** Default escrow deadline: 24 hours. */
+export declare const DEFAULT_ESCROW_DEADLINE_MS: number;
+/** Below this ETH value, no consensus needed. */
+export declare const LOW_RISK_THRESHOLD_ETH = "0.01";
+/** Below this ETH value, 2/6 consensus needed. */
+export declare const MEDIUM_RISK_THRESHOLD_ETH = "0.1";
+/** Below this ETH value, 4/6 consensus needed. */
+export declare const HIGH_RISK_THRESHOLD_ETH = "1";
+/** Above HIGH_RISK, 4/6 consensus + human approval needed. */
+/**
+ * ERC-8004 IdentityRegistry on Base mainnet.
+ * ERC-721-based agent identity registry.
+ */
+export declare const ERC8004_IDENTITY_REGISTRY_ADDRESS = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+/**
+ * ERC-8004 ReputationRegistry on Base mainnet.
+ * Stores signed fixed-point feedback signals.
+ */
+export declare const ERC8004_REPUTATION_REGISTRY_ADDRESS = "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63";
+/**
+ * ERC-8004 ValidationRegistry on Base mainnet.
+ * Hooks for validator contracts to publish results.
+ * NOTE: Address TBD — the ValidationRegistry spec is still evolving.
+ * Update this when the canonical deployment is confirmed.
+ */
+export declare const ERC8004_VALIDATION_REGISTRY_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * Q00bs namespace for ERC-8004 agent identifiers.
+ * Used in the identifier format: {namespace}:{chainId}:{registry}:{agentId}
+ */
+export declare const ERC8004_NAMESPACE = "q00bs";
+//# 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;;;;;;GAMG;AAMH,6BAA6B;AAC7B,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAM1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,+CAA+C,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,oBAAoB,+CAA+C,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,+CAA+C,CAAC;AAEnF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,+CAA+C,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,+CAA+C,CAAC;AAMrF,uDAAuD;AACvD,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,qDAAqD;AACrD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAM1C,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,yCAAyC;AACzC,eAAO,MAAM,cAAc,IAAI,CAAC;AAMhC,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAM9D,iDAAiD;AACjD,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAE7C,kDAAkD;AAClD,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAE/C,kDAAkD;AAClD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,8DAA8D;AAU9D;;;GAGG;AACH,eAAO,MAAM,iCAAiC,+CAA+C,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,mCAAmC,+CAA+C,CAAC;AAEhG;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,+CAA+C,CAAC;AAEhG;;;GAGG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC"}

package/dist/constants.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * @q00bs/agent-sdk — Constants
+ *
+ * All chain IDs, contract addresses, and default values.
+ * Contract addresses for AgentRegistry, AgentEscrow, and ConsensusModule
+ * are placeholders until you deploy them — see the deployment guide in README.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8004_NAMESPACE = exports.ERC8004_VALIDATION_REGISTRY_ADDRESS = exports.ERC8004_REPUTATION_REGISTRY_ADDRESS = exports.ERC8004_IDENTITY_REGISTRY_ADDRESS = exports.HIGH_RISK_THRESHOLD_ETH = exports.MEDIUM_RISK_THRESHOLD_ETH = exports.LOW_RISK_THRESHOLD_ETH = exports.DEFAULT_ESCROW_DEADLINE_MS = exports.PROTOCOL_FEE_BPS = exports.MAX_Q00B_SIDES = exports.DEFAULT_DAILY_LIMIT_ETH = exports.DEFAULT_MAX_TX_VALUE_ETH = exports.DEFAULT_MAX_HOPS = exports.MIN_TRUST_FLOOR_PERCENT = exports.TRUST_DECAY_PER_HOP_PERCENT = exports.INITIAL_TRUST_DIVISOR = exports.MAX_TRUST_SCORE = exports.CONSENSUS_MODULE_ADDRESS = exports.AGENT_ESCROW_ADDRESS = exports.AGENT_REGISTRY_ADDRESS = exports.GENESIS_Q00B_ADDRESS = exports.Q00B_FACTORY_ADDRESS = exports.DEFAULT_RPC_URL = exports.BASE_CHAIN_ID = void 0;
+// ─────────────────────────────────────────────────────────────
+// CHAIN CONFIGURATION
+// ─────────────────────────────────────────────────────────────
+/** Base mainnet chain ID. */
+exports.BASE_CHAIN_ID = 8453;
+/** Default Base mainnet RPC URL (public, rate-limited — use your own for production). */
+exports.DEFAULT_RPC_URL = 'https://mainnet.base.org';
+// ─────────────────────────────────────────────────────────────
+// DEPLOYED CONTRACT ADDRESSES (BASE MAINNET)
+// ─────────────────────────────────────────────────────────────
+/**
+ * q00bFactory — LIVE on Base since Jan 15 2026.
+ * This is YOUR existing deployed contract. Do NOT change.
+ */
+exports.Q00B_FACTORY_ADDRESS = '0xe611b837E2D06f92D4a258e77fab8a26b33452b0';
+/**
+ * Genesis Q00b — the first q00b ever deployed.
+ */
+exports.GENESIS_Q00B_ADDRESS = '0x14597A318D4C03ABbB8E054d31591541E446cB54';
+/**
+ * AgentRegistry — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+exports.AGENT_REGISTRY_ADDRESS = '0xF7c8acecdfbBEAf08F596ab1F85f68f7E6568172';
+/**
+ * AgentEscrow — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+exports.AGENT_ESCROW_ADDRESS = '0xe1139A7BebD89e534d4C459b252BA0963e0A0499';
+/**
+ * ConsensusModule — LIVE on Base mainnet.
+ * Deployed Feb 6 2026.
+ */
+exports.CONSENSUS_MODULE_ADDRESS = '0xcB4A36a7c99e42B3F4b1c8EE6EDD0f3A7DDEcC76';
+// ─────────────────────────────────────────────────────────────
+// TRUST DEFAULTS
+// ─────────────────────────────────────────────────────────────
+/** Maximum trust score (100.00% stored as integer). */
+exports.MAX_TRUST_SCORE = 10000;
+/** New agents start at 50% of their owner's trust score. */
+exports.INITIAL_TRUST_DIVISOR = 2;
+/** Trust decays by 15% per hop in the q00b graph. */
+exports.TRUST_DECAY_PER_HOP_PERCENT = 15;
+/** Minimum effective trust floor (10%). */
+exports.MIN_TRUST_FLOOR_PERCENT = 10;
+// ─────────────────────────────────────────────────────────────
+// AGENT DEFAULTS
+// ─────────────────────────────────────────────────────────────
+/** Default max hops for communication. */
+exports.DEFAULT_MAX_HOPS = 3;
+/** Default max single transaction value: 0.1 ETH. */
+exports.DEFAULT_MAX_TX_VALUE_ETH = '0.1';
+/** Default daily spend limit: 1 ETH. */
+exports.DEFAULT_DAILY_LIMIT_ETH = '1';
+/** Maximum number of sides on a q00b. */
+exports.MAX_Q00B_SIDES = 6;
+// ─────────────────────────────────────────────────────────────
+// ESCROW DEFAULTS
+// ─────────────────────────────────────────────────────────────
+/** Protocol fee in basis points (100 = 1%). */
+exports.PROTOCOL_FEE_BPS = 100;
+/** Default escrow deadline: 24 hours. */
+exports.DEFAULT_ESCROW_DEADLINE_MS = 24 * 60 * 60 * 1000;
+// ─────────────────────────────────────────────────────────────
+// CONSENSUS THRESHOLDS
+// ─────────────────────────────────────────────────────────────
+/** Below this ETH value, no consensus needed. */
+exports.LOW_RISK_THRESHOLD_ETH = '0.01';
+/** Below this ETH value, 2/6 consensus needed. */
+exports.MEDIUM_RISK_THRESHOLD_ETH = '0.1';
+/** Below this ETH value, 4/6 consensus needed. */
+exports.HIGH_RISK_THRESHOLD_ETH = '1';
+/** Above HIGH_RISK, 4/6 consensus + human approval needed. */
+// ─────────────────────────────────────────────────────────────
+// ERC-8004 TRUSTLESS AGENTS (BASE MAINNET)
+// ─────────────────────────────────────────────────────────────
+//
+// Canonical registry addresses deployed by the ERC-8004 team.
+// These are the OFFICIAL addresses on Base mainnet.
+// Reference: https://www.8004.org/build
+/**
+ * ERC-8004 IdentityRegistry on Base mainnet.
+ * ERC-721-based agent identity registry.
+ */
+exports.ERC8004_IDENTITY_REGISTRY_ADDRESS = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432';
+/**
+ * ERC-8004 ReputationRegistry on Base mainnet.
+ * Stores signed fixed-point feedback signals.
+ */
+exports.ERC8004_REPUTATION_REGISTRY_ADDRESS = '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63';
+/**
+ * ERC-8004 ValidationRegistry on Base mainnet.
+ * Hooks for validator contracts to publish results.
+ * NOTE: Address TBD — the ValidationRegistry spec is still evolving.
+ * Update this when the canonical deployment is confirmed.
+ */
+exports.ERC8004_VALIDATION_REGISTRY_ADDRESS = '0x0000000000000000000000000000000000000000';
+/**
+ * Q00bs namespace for ERC-8004 agent identifiers.
+ * Used in the identifier format: {namespace}:{chainId}:{registry}:{agentId}
+ */
+exports.ERC8004_NAMESPACE = 'q00bs';
+//# 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;;;;;;GAMG;;;AAEH,gEAAgE;AAChE,sBAAsB;AACtB,gEAAgE;AAEhE,6BAA6B;AAChB,QAAA,aAAa,GAAG,IAAI,CAAC;AAElC,yFAAyF;AAC5E,QAAA,eAAe,GAAG,0BAA0B,CAAC;AAE1D,gEAAgE;AAChE,6CAA6C;AAC7C,gEAAgE;AAEhE;;;GAGG;AACU,QAAA,oBAAoB,GAAG,4CAA4C,CAAC;AAEjF;;GAEG;AACU,QAAA,oBAAoB,GAAG,4CAA4C,CAAC;AAEjF;;;GAGG;AACU,QAAA,sBAAsB,GAAG,4CAA4C,CAAC;AAEnF;;;GAGG;AACU,QAAA,oBAAoB,GAAG,4CAA4C,CAAC;AAEjF;;;GAGG;AACU,QAAA,wBAAwB,GAAG,4CAA4C,CAAC;AAErF,gEAAgE;AAChE,iBAAiB;AACjB,gEAAgE;AAEhE,uDAAuD;AAC1C,QAAA,eAAe,GAAG,KAAK,CAAC;AAErC,4DAA4D;AAC/C,QAAA,qBAAqB,GAAG,CAAC,CAAC;AAEvC,qDAAqD;AACxC,QAAA,2BAA2B,GAAG,EAAE,CAAC;AAE9C,2CAA2C;AAC9B,QAAA,uBAAuB,GAAG,EAAE,CAAC;AAE1C,gEAAgE;AAChE,iBAAiB;AACjB,gEAAgE;AAEhE,0CAA0C;AAC7B,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAElC,qDAAqD;AACxC,QAAA,wBAAwB,GAAG,KAAK,CAAC;AAE9C,wCAAwC;AAC3B,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAE3C,yCAAyC;AAC5B,QAAA,cAAc,GAAG,CAAC,CAAC;AAEhC,gEAAgE;AAChE,kBAAkB;AAClB,gEAAgE;AAEhE,+CAA+C;AAClC,QAAA,gBAAgB,GAAG,GAAG,CAAC;AAEpC,yCAAyC;AAC5B,QAAA,0BAA0B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9D,gEAAgE;AAChE,uBAAuB;AACvB,gEAAgE;AAEhE,iDAAiD;AACpC,QAAA,sBAAsB,GAAG,MAAM,CAAC;AAE7C,kDAAkD;AACrC,QAAA,yBAAyB,GAAG,KAAK,CAAC;AAE/C,kDAAkD;AACrC,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAE3C,8DAA8D;AAE9D,gEAAgE;AAChE,2CAA2C;AAC3C,gEAAgE;AAChE,EAAE;AACF,8DAA8D;AAC9D,oDAAoD;AACpD,wCAAwC;AAExC;;;GAGG;AACU,QAAA,iCAAiC,GAAG,4CAA4C,CAAC;AAE9F;;;GAGG;AACU,QAAA,mCAAmC,GAAG,4CAA4C,CAAC;AAEhG;;;;;GAKG;AACU,QAAA,mCAAmC,GAAG,4CAA4C,CAAC;AAEhG;;;GAGG;AACU,QAAA,iBAAiB,GAAG,OAAO,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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.
+ */
+import type { PublicClient, Chain, Transport } from 'viem';
+import type { AgentQuery, DiscoveredAgent, AgentRecord, Logger } from './types';
+import { TrustResolver } from './trust';
+export declare class AgentDiscovery {
+    private client;
+    private registryAddress;
+    private trustResolver;
+    private logger;
+    constructor(client: PublicClient<Transport, Chain>, registryAddress: string, trustResolver: TrustResolver, 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,
+     * });
+     * ```
+     */
+    find(myAgentId: number, query?: AgentQuery): Promise<DiscoveredAgent[]>;
+    /**
+     * 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.
+     */
+    getAgent(agentId: number): Promise<AgentRecord | 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.
+     */
+    getAgentByWallet(wallet: string): Promise<{
+        id: number;
+        agent: AgentRecord;
+    } | null>;
+    /**
+     * Check if a specific agent is active and not frozen.
+     *
+     * @param agentId - The agent's on-chain ID.
+     */
+    isActive(agentId: number): Promise<boolean>;
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAOxC,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAS;gBAGrB,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,EACtC,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM;IAQhB;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmFjF;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA8B5D;;;;;OAKG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IA8BrD;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAYlD"}