@q00bs/agent-sdk 1.0.0

package/dist/abis/TheQ00bs.d.ts

@@ -0,0 +1,119 @@
+/**
+ * ABI for an individual TheQ00bs contract (one per user).
+ * READ-ONLY subset — the SDK uses this to inspect q00b sides and token holders
+ * for trust-path resolution.
+ */
+export declare const THE_Q00BS_ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "tokensOfOwner";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256[]";
+        readonly name: "";
+        readonly type: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly name: "tokenURI";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "totalSupply";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "tokenInfos";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "exists";
+        readonly type: "bool";
+    }, {
+        readonly internalType: "address";
+        readonly name: "q00bOwner";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "string";
+        readonly name: "q00bName";
+        readonly type: "string";
+    }, {
+        readonly internalType: "string";
+        readonly name: "metadataUrl";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "owner";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "initialOwner";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "factoryAddress";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+//# sourceMappingURL=TheQ00bs.d.ts.map

package/dist/abis/TheQ00bs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TheQ00bs.d.ts","sourceRoot":"","sources":["../../src/abis/TheQ00bs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+DhB,CAAC"}

package/dist/abis/TheQ00bs.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THE_Q00BS_ABI = void 0;
+/**
+ * ABI for an individual TheQ00bs contract (one per user).
+ * READ-ONLY subset — the SDK uses this to inspect q00b sides and token holders
+ * for trust-path resolution.
+ */
+exports.THE_Q00BS_ABI = [
+    {
+        inputs: [{ internalType: 'address', name: 'owner', type: 'address' }],
+        name: 'tokensOfOwner',
+        outputs: [{ internalType: 'uint256[]', name: '', type: 'uint256[]' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [{ internalType: 'uint256', name: 'tokenId', type: 'uint256' }],
+        name: 'tokenURI',
+        outputs: [{ internalType: 'string', name: '', type: 'string' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'totalSupply',
+        outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [{ internalType: 'address', name: 'owner', type: 'address' }],
+        name: 'balanceOf',
+        outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+        name: 'tokenInfos',
+        outputs: [
+            { internalType: 'bool', name: 'exists', type: 'bool' },
+            { internalType: 'address', name: 'q00bOwner', type: 'address' },
+            { internalType: 'uint256', name: 'id', type: 'uint256' },
+            { internalType: 'string', name: 'q00bName', type: 'string' },
+            { internalType: 'string', name: 'metadataUrl', type: 'string' },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'owner',
+        outputs: [{ internalType: 'address', name: '', type: 'address' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'initialOwner',
+        outputs: [{ internalType: 'address', name: '', type: 'address' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'factoryAddress',
+        outputs: [{ internalType: 'address', name: '', type: 'address' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+];
+//# sourceMappingURL=TheQ00bs.js.map

package/dist/abis/TheQ00bs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TheQ00bs.js","sourceRoot":"","sources":["../../src/abis/TheQ00bs.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,aAAa,GAAG;IAC3B;QACE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACrE,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QACrE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC/D,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACrE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE;YACP,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE;YACtD,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;YAC/D,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;YACxD,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC5D,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;SAChE;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjE,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;CACO,CAAC"}

package/dist/abis/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ABI barrel export — import any ABI from '@q00bs/agent-sdk'.
+ */
+export { Q00B_FACTORY_ABI } from './Q00bFactory';
+export { THE_Q00BS_ABI } from './TheQ00bs';
+export { AGENT_REGISTRY_ABI } from './AgentRegistry';
+export { AGENT_ESCROW_ABI } from './AgentEscrow';
+export { CONSENSUS_MODULE_ABI } from './ConsensusModule';
+//# sourceMappingURL=index.d.ts.map

package/dist/abis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/abis/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSENSUS_MODULE_ABI = exports.AGENT_ESCROW_ABI = exports.AGENT_REGISTRY_ABI = exports.THE_Q00BS_ABI = exports.Q00B_FACTORY_ABI = void 0;
+/**
+ * ABI barrel export — import any ABI from '@q00bs/agent-sdk'.
+ */
+var Q00bFactory_1 = require("./Q00bFactory");
+Object.defineProperty(exports, "Q00B_FACTORY_ABI", { enumerable: true, get: function () { return Q00bFactory_1.Q00B_FACTORY_ABI; } });
+var TheQ00bs_1 = require("./TheQ00bs");
+Object.defineProperty(exports, "THE_Q00BS_ABI", { enumerable: true, get: function () { return TheQ00bs_1.THE_Q00BS_ABI; } });
+var AgentRegistry_1 = require("./AgentRegistry");
+Object.defineProperty(exports, "AGENT_REGISTRY_ABI", { enumerable: true, get: function () { return AgentRegistry_1.AGENT_REGISTRY_ABI; } });
+var AgentEscrow_1 = require("./AgentEscrow");
+Object.defineProperty(exports, "AGENT_ESCROW_ABI", { enumerable: true, get: function () { return AgentEscrow_1.AGENT_ESCROW_ABI; } });
+var ConsensusModule_1 = require("./ConsensusModule");
+Object.defineProperty(exports, "CONSENSUS_MODULE_ABI", { enumerable: true, get: function () { return ConsensusModule_1.CONSENSUS_MODULE_ABI; } });
+//# sourceMappingURL=index.js.map

package/dist/abis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/abis/index.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AACzB,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AACtB,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAC3B,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AACzB,qDAAyD;AAAhD,uHAAA,oBAAoB,OAAA"}

package/dist/client.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @q00bs/agent-sdk — Blockchain Client
+ *
+ * Creates viem public + wallet clients for reading/writing to Base mainnet.
+ * All contract interactions go through these two clients:
+ *
+ *   publicClient  → read-only calls (getAgent, canCommunicate, etc.)
+ *   walletClient  → write calls that require a signer (registerAgent, createEscrow, etc.)
+ *
+ * TWO WALLET MODES:
+ *
+ *   MODE 1: Raw Private Key (legacy)
+ *     - Private key loaded from env var and used by viem directly.
+ *     - Simpler but riskier for autonomous agents (key exposure).
+ *
+ *   MODE 2: Privy Server Wallet (recommended for ClawBot agents)
+ *     - Private key is held by Privy's secure enclave — NEVER in your code.
+ *     - Transaction policies (spend limits, contract whitelists) enforced server-side.
+ *     - Same pattern used by OpenClaw agents:
+ *       https://privy.io/blog/securely-equipping-openclaw-agents-with-privy-wallets
+ *     - For write calls, the SDK routes through PrivyWalletManager instead of viem.
+ *     - Read calls still use viem publicClient (no signing needed).
+ *
+ * WHY VIEM?
+ *   The existing q00bs app uses wagmi (which wraps viem). Using viem directly
+ *   keeps the SDK lightweight (~50 KB) and avoids pulling in React dependencies.
+ */
+import { type PublicClient, type WalletClient, type Chain, type Transport, type Account } from 'viem';
+import type { Logger, PrivyConfig } from './types';
+import { PrivyWalletManager } from './privy';
+export interface ClientConfig {
+    /** Hex private key (0x...). Required for Mode 1 (raw key). Ignored if using Privy. */
+    privateKey?: string;
+    /** Base mainnet RPC URL. Defaults to public endpoint. */
+    rpcUrl?: string;
+    /** Optional logger. */
+    logger?: Logger;
+}
+/** Config for Mode 2: Privy-managed wallet. */
+export interface PrivyClientConfig {
+    /** Privy configuration (appId, appSecret, optional walletId). */
+    privy: PrivyConfig;
+    /** Base mainnet RPC URL. Defaults to public endpoint. */
+    rpcUrl?: string;
+    /** Optional logger. */
+    logger?: Logger;
+}
+export interface BlockchainClients {
+    /** Read-only client for view/pure calls. */
+    publicClient: PublicClient<Transport, Chain>;
+    /** Signing client for state-changing transactions (undefined in Privy mode). */
+    walletClient?: WalletClient<Transport, Chain, Account>;
+    /** The account derived from the private key (undefined in Privy mode). */
+    account?: Account;
+    /** The chain object (Base). */
+    chain: Chain;
+    /** Privy wallet manager — set when using Privy mode. */
+    privyWalletManager?: PrivyWalletManager;
+    /** Which mode is active. */
+    mode: 'privateKey' | 'privy';
+}
+/**
+ * Initialize viem clients for Base mainnet using a raw private key (Mode 1).
+ *
+ * @param config - Private key and optional RPC URL.
+ * @returns An object with publicClient, walletClient, account, and chain.
+ *
+ * @example
+ * ```ts
+ * const clients = createClients({
+ *   privateKey: process.env.AGENT_PRIVATE_KEY!,
+ *   rpcUrl: process.env.BASE_RPC_URL,
+ * });
+ * ```
+ */
+export declare function createClients(config: ClientConfig): BlockchainClients;
+/**
+ * Initialize viem read client + Privy wallet manager (Mode 2).
+ *
+ * This is the RECOMMENDED mode for ClawBot / OpenClaw agents. Instead
+ * of managing a private key, you configure Privy credentials and the
+ * SDK creates a policy-enforced wallet through Privy's API.
+ *
+ * @param config - Privy config (appId, appSecret) and optional RPC URL.
+ * @returns An object with publicClient, privyWalletManager, and chain.
+ *
+ * @example
+ * ```ts
+ * const clients = createPrivyClients({
+ *   privy: {
+ *     appId: process.env.PRIVY_APP_ID!,
+ *     appSecret: process.env.PRIVY_APP_SECRET!,
+ *     walletId: process.env.PRIVY_WALLET_ID, // optional
+ *   },
+ * });
+ * ```
+ */
+export declare function createPrivyClients(config: PrivyClientConfig): BlockchainClients;
+declare const LOG_LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+/**
+ * Create a minimal, no-dependency logger.
+ * Prefixes all messages with [Q00BS] and respects log level.
+ */
+export declare function createLogger(level?: keyof typeof LOG_LEVELS): Logger;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,MAAM,CAAC;AAId,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAM7C,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,KAAK,EAAE,WAAW,CAAC;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC7C,gFAAgF;IAChF,YAAY,CAAC,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvD,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,4BAA4B;IAC5B,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,iBAAiB,CA0BrE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CAoB/E;AAMD,QAAA,MAAM,UAAU;;;;;CAAoD,CAAC;AAErE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,MAAM,OAAO,UAAmB,GAAG,MAAM,CAiB5E"}

package/dist/client.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * @q00bs/agent-sdk — Blockchain Client
+ *
+ * Creates viem public + wallet clients for reading/writing to Base mainnet.
+ * All contract interactions go through these two clients:
+ *
+ *   publicClient  → read-only calls (getAgent, canCommunicate, etc.)
+ *   walletClient  → write calls that require a signer (registerAgent, createEscrow, etc.)
+ *
+ * TWO WALLET MODES:
+ *
+ *   MODE 1: Raw Private Key (legacy)
+ *     - Private key loaded from env var and used by viem directly.
+ *     - Simpler but riskier for autonomous agents (key exposure).
+ *
+ *   MODE 2: Privy Server Wallet (recommended for ClawBot agents)
+ *     - Private key is held by Privy's secure enclave — NEVER in your code.
+ *     - Transaction policies (spend limits, contract whitelists) enforced server-side.
+ *     - Same pattern used by OpenClaw agents:
+ *       https://privy.io/blog/securely-equipping-openclaw-agents-with-privy-wallets
+ *     - For write calls, the SDK routes through PrivyWalletManager instead of viem.
+ *     - Read calls still use viem publicClient (no signing needed).
+ *
+ * WHY VIEM?
+ *   The existing q00bs app uses wagmi (which wraps viem). Using viem directly
+ *   keeps the SDK lightweight (~50 KB) and avoids pulling in React dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClients = createClients;
+exports.createPrivyClients = createPrivyClients;
+exports.createLogger = createLogger;
+const viem_1 = require("viem");
+const accounts_1 = require("viem/accounts");
+const chains_1 = require("viem/chains");
+const constants_1 = require("./constants");
+const privy_1 = require("./privy");
+/**
+ * Initialize viem clients for Base mainnet using a raw private key (Mode 1).
+ *
+ * @param config - Private key and optional RPC URL.
+ * @returns An object with publicClient, walletClient, account, and chain.
+ *
+ * @example
+ * ```ts
+ * const clients = createClients({
+ *   privateKey: process.env.AGENT_PRIVATE_KEY!,
+ *   rpcUrl: process.env.BASE_RPC_URL,
+ * });
+ * ```
+ */
+function createClients(config) {
+    // Validate private key format
+    if (!config.privateKey || !config.privateKey.startsWith('0x')) {
+        throw new Error('Private key must start with 0x. Set the AGENT_PRIVATE_KEY environment variable.');
+    }
+    const rpcUrl = config.rpcUrl || constants_1.DEFAULT_RPC_URL;
+    const account = (0, accounts_1.privateKeyToAccount)(config.privateKey);
+    config.logger?.info(`Initialized wallet: ${account.address}`);
+    config.logger?.info(`RPC endpoint: ${rpcUrl.replace(/\/\/.*@/, '//<redacted>@')}`);
+    const publicClient = (0, viem_1.createPublicClient)({
+        chain: chains_1.base,
+        transport: (0, viem_1.http)(rpcUrl),
+    });
+    const walletClient = (0, viem_1.createWalletClient)({
+        chain: chains_1.base,
+        transport: (0, viem_1.http)(rpcUrl),
+        account,
+    });
+    return { publicClient, walletClient, account, chain: chains_1.base, mode: 'privateKey' };
+}
+/**
+ * Initialize viem read client + Privy wallet manager (Mode 2).
+ *
+ * This is the RECOMMENDED mode for ClawBot / OpenClaw agents. Instead
+ * of managing a private key, you configure Privy credentials and the
+ * SDK creates a policy-enforced wallet through Privy's API.
+ *
+ * @param config - Privy config (appId, appSecret) and optional RPC URL.
+ * @returns An object with publicClient, privyWalletManager, and chain.
+ *
+ * @example
+ * ```ts
+ * const clients = createPrivyClients({
+ *   privy: {
+ *     appId: process.env.PRIVY_APP_ID!,
+ *     appSecret: process.env.PRIVY_APP_SECRET!,
+ *     walletId: process.env.PRIVY_WALLET_ID, // optional
+ *   },
+ * });
+ * ```
+ */
+function createPrivyClients(config) {
+    const rpcUrl = config.rpcUrl || constants_1.DEFAULT_RPC_URL;
+    const logger = config.logger || createLogger('info');
+    logger.info('Initializing Privy-managed wallet mode...');
+    logger.info(`RPC endpoint: ${rpcUrl.replace(/\/\/.*@/, '//<redacted>@')}`);
+    const publicClient = (0, viem_1.createPublicClient)({
+        chain: chains_1.base,
+        transport: (0, viem_1.http)(rpcUrl),
+    });
+    const privyWalletManager = new privy_1.PrivyWalletManager(config.privy, logger);
+    return {
+        publicClient,
+        chain: chains_1.base,
+        privyWalletManager,
+        mode: 'privy',
+    };
+}
+// ─────────────────────────────────────────────────────────────
+// LOGGER FACTORY
+// ─────────────────────────────────────────────────────────────
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+/**
+ * Create a minimal, no-dependency logger.
+ * Prefixes all messages with [Q00BS] and respects log level.
+ */
+function createLogger(level = 'info') {
+    const threshold = LOG_LEVELS[level];
+    const log = (lvl, msg, ...args) => {
+        if (LOG_LEVELS[lvl] >= threshold) {
+            const prefix = `[Q00BS][${lvl.toUpperCase()}]`;
+            // eslint-disable-next-line no-console
+            console[lvl === 'debug' ? 'log' : lvl](prefix, msg, ...args);
+        }
+    };
+    return {
+        debug: (msg, ...args) => log('debug', msg, ...args),
+        info: (msg, ...args) => log('info', msg, ...args),
+        warn: (msg, ...args) => log('warn', msg, ...args),
+        error: (msg, ...args) => log('error', msg, ...args),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/consensus.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @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.
+ */
+import type { PublicClient, WalletClient, Chain, Transport, Account } from 'viem';
+import type { ConsensusParams, ConsensusResult, ConsensusRecord, Logger } from './types';
+export declare class ConsensusManager {
+    private publicClient;
+    private walletClient;
+    private consensusAddress;
+    private logger;
+    constructor(publicClient: PublicClient<Transport, Chain>, walletClient: WalletClient<Transport, Chain, Account>, consensusAddress: string, 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
+     * });
+     * ```
+     */
+    request(agentId: number, params: ConsensusParams): Promise<number>;
+    /**
+     * 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.
+     */
+    vote(requestId: number, voterAgentId: number, approve: boolean): Promise<string>;
+    /**
+     * Mark a consensus request as executed (after the approved action is done).
+     *
+     * @param requestId - The request to finalize.
+     */
+    markExecuted(requestId: number): Promise<string>;
+    /**
+     * Read a consensus request from the chain.
+     *
+     * @param requestId - The request to query.
+     */
+    get(requestId: number): Promise<ConsensusRecord>;
+    /**
+     * Check if a consensus request has been approved.
+     *
+     * @param requestId - The request to check.
+     */
+    isApproved(requestId: number): Promise<boolean>;
+    /**
+     * 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).
+     */
+    waitForResult(requestId: number, pollIntervalMs?: number, timeoutMs?: number): Promise<ConsensusResult>;
+    private parseRequestIdFromReceipt;
+}
+//# sourceMappingURL=consensus.d.ts.map

package/dist/consensus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.d.ts","sourceRoot":"","sources":["../src/consensus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAQlF,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,eAAe,EAEf,MAAM,EACP,MAAM,SAAS,CAAC;AASjB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,MAAM,CAAS;gBAGrB,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,EAC5C,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM;IAQhB;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IA8BxE;;;;;;OAMG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBtF;;;;OAIG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBtD;;;;OAIG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBtD;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrD;;;;;;;OAOG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,cAAc,SAAS,EACvB,SAAS,SAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAwC3B,OAAO,CAAC,yBAAyB;CAelC"}