@q00bs/agent-sdk 1.0.0

package/dist/Q00bsAgent.d.ts

@@ -0,0 +1,331 @@
+/**
+ * @q00bs/agent-sdk — Q00bsAgent (Main Entry Point)
+ *
+ * This is the primary class developers interact with. It wraps all SDK
+ * modules (trust, escrow, consensus, discovery) behind a clean interface.
+ *
+ * WHAT THIS CLASS DOES:
+ *   - Initializes blockchain clients from a private key (Mode 1) OR Privy (Mode 2).
+ *   - Registers the agent on-chain as an ERC-721 on the owner's q00b.
+ *   - Provides methods for trust verification, agent discovery, payments, and consensus.
+ *   - Enforces spend limits and trust-path checks BEFORE sending transactions.
+ *
+ * TWO WALLET MODES:
+ *
+ *   MODE 1 — Raw Private Key (legacy):
+ *     Pass `privateKey` in config. The SDK creates viem clients locally.
+ *
+ *   MODE 2 — Privy Server Wallet (recommended for ClawBot / OpenClaw agents):
+ *     Pass `privy` in config (appId + appSecret). The SDK creates a Privy-managed
+ *     wallet with spending policies. No private keys in your code.
+ *     See: https://privy.io/blog/securely-equipping-openclaw-agents-with-privy-wallets
+ *
+ * SECURITY GUARANTEES:
+ *   - In Mode 1: Private keys are used by viem locally and never leave the process.
+ *   - In Mode 2: Private keys are held by Privy's HSM and NEVER appear in your code.
+ *   - All state-changing operations go through on-chain contracts.
+ *   - Spend limits are enforced at 3 layers: Privy policy → SDK pre-check → on-chain.
+ *   - Trust paths are verified on-chain through the q00b graph before communication.
+ *
+ * USAGE (Mode 1 — raw key):
+ *   ```ts
+ *   const agent = new Q00bsAgent({
+ *     privateKey: process.env.AGENT_PRIVATE_KEY!,
+ *     rpcUrl: process.env.BASE_RPC_URL!,
+ *     registryAddress: '0x...',
+ *   });
+ *   await agent.initialize();
+ *   ```
+ *
+ * USAGE (Mode 2 — Privy, recommended):
+ *   ```ts
+ *   const agent = new Q00bsAgent({
+ *     privy: {
+ *       appId: process.env.PRIVY_APP_ID!,
+ *       appSecret: process.env.PRIVY_APP_SECRET!,
+ *       walletId: process.env.PRIVY_WALLET_ID, // optional, creates new if omitted
+ *     },
+ *     rpcUrl: process.env.BASE_RPC_URL!,
+ *     registryAddress: '0x...',
+ *   });
+ *   await agent.initialize();
+ *   ```
+ */
+import { PrivyWalletManager } from './privy';
+import { ERC8004Manager } from './erc8004';
+import type { AgentConfig, AgentRecord, TrustPath, AgentQuery, DiscoveredAgent, CreateEscrowParams, EscrowRecord, ConsensusParams, ConsensusResult, ConsensusRecord, PrivyWalletPolicy, PrivyWalletInfo, ERC8004Identity, ERC8004ReputationSummary, ERC8004Feedback, GiveFeedbackParams } from './types';
+export declare class Q00bsAgent {
+    private config;
+    private logger;
+    private publicClient;
+    private walletClient?;
+    private walletAddress;
+    private privyManager?;
+    private _walletMode;
+    private trustResolver;
+    private escrowManager?;
+    private consensusManager?;
+    private agentDiscovery;
+    private _erc8004Manager?;
+    private _agentId?;
+    private _initialized;
+    /** The agent's on-chain ID (set after register() or from config). */
+    get agentId(): number | undefined;
+    /** Whether initialize() has been called. */
+    get initialized(): boolean;
+    /** The agent's wallet address (derived from private key or Privy). */
+    get address(): string;
+    /** Which wallet mode is active: 'privateKey' (Mode 1) or 'privy' (Mode 2). */
+    get walletMode(): 'privateKey' | 'privy';
+    /** Whether this agent uses a Privy-managed wallet (Mode 2). */
+    get isPrivyMode(): boolean;
+    /** The Privy wallet manager (only available in Mode 2). */
+    get privyWallet(): PrivyWalletManager | undefined;
+    /** The ERC-8004 manager (available if erc8004 config is set or after initialize). */
+    get erc8004(): ERC8004Manager | undefined;
+    /**
+     * Create a new Q00bsAgent.
+     *
+     * @param config - Agent configuration. Must include either `privateKey` (Mode 1) or `privy` (Mode 2).
+     *
+     * NOTE: This does NOT connect to the blockchain yet. Call initialize() next.
+     */
+    constructor(config: AgentConfig);
+    /**
+     * Initialize blockchain connections and sub-modules.
+     * Must be called before any other method.
+     *
+     * In Mode 1 (private key): Creates viem clients and derives wallet address.
+     * In Mode 2 (Privy): Creates/loads Privy wallet with policy, gets address.
+     *
+     * @param walletPolicy - (Mode 2 only) Policy to apply when creating a new Privy wallet.
+     * @throws If configuration is invalid.
+     */
+    initialize(walletPolicy?: PrivyWalletPolicy): Promise<void>;
+    /**
+     * Register this agent on-chain on one side of the owner's q00b.
+     *
+     * @param ownerQ00bAddress - The q00b contract address owned by this agent's human.
+     * @param sidePosition - Which side of the q00b (0-5) to occupy.
+     * @returns The new agent's on-chain ID.
+     *
+     * IMPORTANT: The transaction sender must be the q00b OWNER (not the agent wallet).
+     * In practice, the owner calls registerAgent() from their wallet, passing
+     * the agent's wallet address. This method is for convenience when the owner's
+     * private key is used.
+     *
+     * @example
+     * ```ts
+     * const agentId = await agent.register('0xMyQ00bAddress', 0);
+     * console.log(`Registered as agent #${agentId}`);
+     * ```
+     */
+    register(ownerQ00bAddress: string, sidePosition: number): Promise<number>;
+    /**
+     * Check the trust path between this agent and another.
+     *
+     * @param targetAgentId - The other agent's on-chain ID.
+     * @returns TrustPath with connection status, hops, and effective trust score.
+     */
+    checkTrust(targetAgentId: number): Promise<TrustPath>;
+    /**
+     * Get this agent's on-chain record.
+     */
+    getMyRecord(): Promise<AgentRecord | null>;
+    /**
+     * Search for agents in the trust network.
+     *
+     * @param query - Optional filters (minTrustScore, maxHops, limit, sortBy).
+     * @returns Array of discovered agents sorted by effective trust.
+     */
+    discoverAgents(query?: AgentQuery): Promise<DiscoveredAgent[]>;
+    /**
+     * Get any agent's record by ID.
+     */
+    getAgent(agentId: number): Promise<AgentRecord | null>;
+    /**
+     * Get any agent's record by wallet address.
+     */
+    getAgentByWallet(wallet: string): Promise<{
+        id: number;
+        agent: AgentRecord;
+    } | null>;
+    /**
+     * Create an escrow to pay another agent for a task.
+     *
+     * @param params - Service agent ID, task description, payment amount, deadline.
+     * @returns The new escrow ID.
+     * @throws If escrow module is not configured.
+     */
+    createEscrow(params: CreateEscrowParams): Promise<number>;
+    /**
+     * Accept an escrow (as the service agent).
+     */
+    acceptEscrow(escrowId: number): Promise<string>;
+    /**
+     * Mark an escrow complete (as the service agent).
+     */
+    completeEscrow(escrowId: number, deliverableDescription: string): Promise<string>;
+    /**
+     * Release escrowed funds to the service agent (as the client agent).
+     */
+    releaseEscrow(escrowId: number): Promise<string>;
+    /**
+     * Request refund for an expired escrow.
+     */
+    refundEscrow(escrowId: number): Promise<string>;
+    /**
+     * Get escrow details.
+     */
+    getEscrow(escrowId: number): Promise<EscrowRecord>;
+    /**
+     * Request consensus from peer agents for a high-stakes action.
+     *
+     * @param params - Action description, value, and optional timeout.
+     * @returns The consensus request ID.
+     */
+    requestConsensus(params: ConsensusParams): Promise<number>;
+    /**
+     * Vote on a peer's consensus request.
+     */
+    voteOnConsensus(requestId: number, approve: boolean): Promise<string>;
+    /**
+     * Wait for a consensus request to reach a decision (blocking).
+     */
+    waitForConsensus(requestId: number, pollIntervalMs?: number, timeoutMs?: number): Promise<ConsensusResult>;
+    /**
+     * Get consensus request details.
+     */
+    getConsensusRequest(requestId: number): Promise<ConsensusRecord>;
+    /**
+     * Get this agent's Privy wallet info (Mode 2 only).
+     *
+     * @returns The Privy wallet info, or undefined if not in Privy mode.
+     */
+    getPrivyWalletInfo(): PrivyWalletInfo | undefined;
+    /**
+     * Update the spending policy on this agent's Privy wallet (Mode 2 only).
+     *
+     * Use this to dynamically adjust limits — for example, after the agent
+     * gains more trust or is granted higher permissions by its owner.
+     *
+     * @param policy - The new wallet policy to apply.
+     * @throws PrivyWalletError if not in Privy mode or update fails.
+     *
+     * @example
+     * ```ts
+     * await agent.updatePrivyPolicy({
+     *   name: 'Elevated Limits',
+     *   rules: [
+     *     { type: 'max_transaction_value', value: '0.5' },
+     *     { type: 'daily_spend_limit', value: '5.0' },
+     *   ],
+     * });
+     * ```
+     */
+    updatePrivyPolicy(policy: PrivyWalletPolicy): Promise<void>;
+    /**
+     * Sign a message with this agent's wallet.
+     *
+     * Works in both modes:
+     *   - Mode 1: Uses viem walletClient.signMessage()
+     *   - Mode 2: Uses Privy's signMessage API
+     *
+     * @param message - The message to sign.
+     * @returns The signature hex string.
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Register this agent's ERC-8004 identity in the IdentityRegistry.
+     *
+     * This creates a portable identity on the canonical ERC-8004 registry
+     * that other agent platforms can discover and verify.
+     *
+     * @param ownerAddress - Address to mint the identity NFT to (usually your wallet).
+     * @returns The new ERC-8004 identity.
+     *
+     * @example
+     * ```ts
+     * const identity = await agent.registerERC8004Identity(agent.address);
+     * console.log(`ERC-8004 ID: ${identity.agentId}`);
+     * console.log(`Identifier: ${identity.identifier}`);
+     * ```
+     */
+    registerERC8004Identity(ownerAddress?: string): Promise<ERC8004Identity>;
+    /**
+     * Get an ERC-8004 identity by agentId.
+     *
+     * @param agentId - The ERC-8004 agentId (tokenId in IdentityRegistry).
+     * @returns The identity, or null if not found.
+     */
+    getERC8004Identity(agentId: number): Promise<ERC8004Identity | null>;
+    /**
+     * Set the agentURI on this agent's ERC-8004 identity.
+     *
+     * The URI should point to a JSON registration file describing
+     * the agent (name, capabilities, endpoints, trust level, etc.).
+     *
+     * @param erc8004AgentId - The agent's ERC-8004 ID.
+     * @param uri - The URI (IPFS, HTTPS, etc.).
+     */
+    setERC8004AgentURI(erc8004AgentId: number, uri: string): Promise<void>;
+    /**
+     * Sync this agent's Q00bs trust score to its ERC-8004 metadata.
+     *
+     * This makes the Q00bs trust score visible to other agent platforms
+     * that read ERC-8004 metadata.
+     *
+     * @param erc8004AgentId - The agent's ERC-8004 ID.
+     */
+    syncTrustToERC8004(erc8004AgentId: number): Promise<void>;
+    /**
+     * Give ERC-8004 feedback to another agent.
+     *
+     * This publishes a reputation signal on the canonical ReputationRegistry.
+     * Other agent platforms can read this feedback to assess your peer's
+     * trustworthiness.
+     *
+     * @param params - Feedback parameters (subject, value, decimals).
+     * @param fromERC8004AgentId - Your agent's ERC-8004 ID.
+     * @returns The feedback index.
+     *
+     * @example
+     * ```ts
+     * await agent.giveERC8004Feedback({
+     *   subjectAgentId: 7,
+     *   value: 4.5,     // positive feedback
+     *   decimals: 2,
+     * }, myERC8004Id);
+     * ```
+     */
+    giveERC8004Feedback(params: GiveFeedbackParams, fromERC8004AgentId: number): Promise<number>;
+    /**
+     * Get the ERC-8004 reputation summary for an agent.
+     *
+     * @param erc8004AgentId - The agent's ERC-8004 ID.
+     * @returns Aggregate reputation summary.
+     */
+    getERC8004Reputation(erc8004AgentId: number): Promise<ERC8004ReputationSummary>;
+    /**
+     * Read all ERC-8004 feedback for an agent.
+     *
+     * @param erc8004AgentId - The agent's ERC-8004 ID.
+     * @returns Array of feedback entries.
+     */
+    getERC8004Feedback(erc8004AgentId: number): Promise<ERC8004Feedback[]>;
+    /**
+     * Calculate effective trust locally (no blockchain call).
+     * Useful for quick UI previews.
+     */
+    calculateTrust(baseTrustScore: number, hops: number): number;
+    /**
+     * Clear the trust cache (call after known on-chain changes).
+     */
+    clearTrustCache(): void;
+    private ensureInitialized;
+    private ensureRegistered;
+    private ensureEscrow;
+    private ensureConsensus;
+    private ensureERC8004;
+}
+//# sourceMappingURL=Q00bsAgent.d.ts.map

package/dist/Q00bsAgent.d.ts.map

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