@q00bs/agent-sdk 1.0.0

package/dist/privy.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @q00bs/agent-sdk — Privy Wallet Manager
+ *
+ * This module integrates Privy's server-side wallet API to give each
+ * Q00bs agent a custody-free wallet with built-in spending policies.
+ *
+ * WHY THIS EXISTS:
+ *   Raw private keys in env vars are a security liability for autonomous agents.
+ *   Privy holds key material in a secure enclave and enforces transaction policies
+ *   BEFORE signing. This is the same pattern used by OpenClaw agents:
+ *   https://privy.io/blog/securely-equipping-openclaw-agents-with-privy-wallets
+ *
+ * ARCHITECTURE:
+ *   ┌──────────────────┐     ┌──────────────────┐     ┌────────────┐
+ *   │  Q00bsAgent SDK  │────▶│  Privy Server API │────▶│  Base L2   │
+ *   │  (your agent)    │     │  (policy check +   │     │  (on-chain) │
+ *   │                  │     │   key custody)     │     │            │
+ *   └──────────────────┘     └──────────────────┘     └────────────┘
+ *
+ *   1. Agent calls createWallet() or getWallet() via this module.
+ *   2. Privy provisions a wallet with a policy (spend limits, allowed contracts).
+ *   3. Agent sends transactions via sendTransaction() — Privy checks policy, signs, broadcasts.
+ *   4. Private key NEVER leaves Privy's secure infrastructure.
+ *
+ * SECURITY PRINCIPLES (from Privy's guide):
+ *   1. Always attach policies at wallet creation
+ *   2. Validate every transaction (destination, amount, chain)
+ *   3. Protect credentials (app secret never in agent prompts/memory)
+ *   4. Guard against prompt injection
+ *   5. Require explicit confirmation for security-weakening changes
+ */
+import type { PrivyConfig, PrivyWalletPolicy, PrivyWalletInfo, PrivyTransactionRequest, PrivyTransactionResult, Logger } from './types';
+/**
+ * Manages Privy server wallets for Q00bs agents.
+ *
+ * Each agent gets a dedicated wallet with a policy that mirrors its
+ * on-chain AgentPermissions. Three layers of defense:
+ *   Layer 1: Privy policy (server-side, instant reject)
+ *   Layer 2: SDK pre-validation (local check before API call)
+ *   Layer 3: Smart contract modifiers (on-chain, final authority)
+ *
+ * USAGE:
+ *   ```ts
+ *   const manager = new PrivyWalletManager({
+ *     appId: process.env.PRIVY_APP_ID!,
+ *     appSecret: process.env.PRIVY_APP_SECRET!,
+ *   }, logger);
+ *
+ *   // Create a new agent wallet with spending policies
+ *   const wallet = await manager.createWallet({
+ *     name: 'ResearchBot #47 Limits',
+ *     rules: [
+ *       { type: 'max_transaction_value', value: '0.1' },
+ *       { type: 'daily_spend_limit', value: '1.0' },
+ *       { type: 'allowed_chains', value: [8453] },  // Base only
+ *       { type: 'allowed_contracts', value: ['0xRegistryAddress', '0xEscrowAddress'] },
+ *     ],
+ *   });
+ *
+ *   // Send a transaction through Privy (policy-checked + signed)
+ *   const result = await manager.sendTransaction(wallet.walletId, {
+ *     to: '0xEscrowContract',
+ *     data: '0x...',  // encoded createEscrow() call
+ *     value: '0x2386F26FC10000',  // 0.01 ETH in hex
+ *   });
+ *   ```
+ */
+export declare class PrivyWalletManager {
+    private config;
+    private logger;
+    private authHeaders;
+    private _walletInfo?;
+    /** The current wallet info (set after createWallet/getWallet). */
+    get walletInfo(): PrivyWalletInfo | undefined;
+    /** The wallet's Ethereum address (or undefined if not initialized). */
+    get address(): string | undefined;
+    constructor(config: PrivyConfig, logger: Logger);
+    /**
+     * Create a new Privy server wallet for this agent.
+     *
+     * This provisions a fresh Ethereum wallet in Privy's secure enclave
+     * and attaches the specified spending policy. The private key NEVER
+     * leaves Privy — it exists only in their HSM.
+     *
+     * @param policy - Spending policy to enforce on this wallet.
+     * @returns Info about the newly created wallet.
+     *
+     * @example
+     * ```ts
+     * const wallet = await manager.createWallet({
+     *   name: 'DataBot Spending Limits',
+     *   rules: [
+     *     { type: 'max_transaction_value', value: '0.1', description: 'Max 0.1 ETH per tx' },
+     *     { type: 'daily_spend_limit', value: '1.0', description: 'Max 1 ETH per day' },
+     *     { type: 'allowed_chains', value: [8453] },
+     *   ],
+     * });
+     * console.log(`Agent wallet created: ${wallet.address}`);
+     * ```
+     */
+    createWallet(policy?: PrivyWalletPolicy): Promise<PrivyWalletInfo>;
+    /**
+     * Retrieve an existing Privy wallet by its ID.
+     *
+     * @param walletId - The Privy wallet ID (from a previous createWallet call).
+     * @returns Info about the existing wallet.
+     */
+    getWallet(walletId: string): Promise<PrivyWalletInfo>;
+    /**
+     * Initialize the wallet — either load an existing one or create a new one.
+     *
+     * @param policy - Policy to use if creating a new wallet.
+     * @returns The wallet info.
+     */
+    initialize(policy?: PrivyWalletPolicy): Promise<PrivyWalletInfo>;
+    /**
+     * Attach or update a spending policy on a Privy wallet.
+     *
+     * Policies are the key security layer for agentic wallets. They define:
+     *   - Max value per transaction
+     *   - Daily spending cap
+     *   - Allowed contract addresses (whitelist)
+     *   - Allowed chains (e.g. Base only)
+     *   - Function selector whitelist
+     *   - Human approval requirements for high-value actions
+     *
+     * @param walletId - The wallet to apply the policy to.
+     * @param policy - The policy definition.
+     */
+    setPolicy(walletId: string, policy: PrivyWalletPolicy): Promise<void>;
+    /**
+     * Build a default policy from Q00bs AgentPermissions.
+     *
+     * This translates on-chain permission parameters into Privy policy rules,
+     * ensuring the server-side guard matches the on-chain guard.
+     *
+     * @param maxTxValueEth - Max ETH per transaction (e.g. '0.1').
+     * @param dailyLimitEth - Max ETH per day (e.g. '1.0').
+     * @param allowedContracts - Contract addresses the agent can interact with.
+     * @param requireHumanApproval - Whether to require human approval for high-value txs.
+     * @returns A PrivyWalletPolicy ready to attach.
+     */
+    static buildDefaultPolicy(maxTxValueEth?: string, dailyLimitEth?: string, allowedContracts?: string[], requireHumanApproval?: boolean): PrivyWalletPolicy;
+    /**
+     * Send a transaction through Privy.
+     *
+     * Privy validates the transaction against the wallet's policy BEFORE signing.
+     * If the policy rejects it, a PrivyPolicyViolationError is thrown and
+     * nothing is broadcast to the network.
+     *
+     * @param walletId - The Privy wallet ID to send from.
+     * @param tx - Transaction parameters (to, value, data, etc.).
+     * @returns Transaction hash and policy status.
+     *
+     * @example
+     * ```ts
+     * const result = await manager.sendTransaction(walletId, {
+     *   to: escrowContractAddress,
+     *   data: encodedCalldata,
+     *   value: parseEther('0.01').toString(16),
+     *   chainId: 8453,
+     * });
+     * console.log(`TX hash: ${result.hash}`);
+     * ```
+     */
+    sendTransaction(walletId: string, tx: PrivyTransactionRequest): Promise<PrivyTransactionResult>;
+    /**
+     * Sign a message with the Privy wallet (for SIWE, EIP-712, etc.).
+     *
+     * @param walletId - The Privy wallet ID.
+     * @param message - The message to sign.
+     * @returns The signature hex string.
+     */
+    signMessage(walletId: string, message: string): Promise<string>;
+    /**
+     * Sign typed data (EIP-712) with the Privy wallet.
+     *
+     * @param walletId - The Privy wallet ID.
+     * @param typedData - The EIP-712 typed data object.
+     * @returns The signature hex string.
+     */
+    signTypedData(walletId: string, typedData: Record<string, unknown>): Promise<string>;
+    /**
+     * SDK-level pre-validation before hitting the Privy API.
+     * This catches obvious errors instantly without a network round-trip.
+     */
+    private preValidateTransaction;
+    /**
+     * Convert our PrivyWalletPolicy to Privy's API format.
+     */
+    private convertToPrivyPolicy;
+    /**
+     * Map our rule type names to Privy's API rule type names.
+     */
+    private mapRuleType;
+}
+//# sourceMappingURL=privy.d.ts.map

package/dist/privy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privy.d.ts","sourceRoot":"","sources":["../src/privy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAEjB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,MAAM,EACP,MAAM,SAAS,CAAC;AAcjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAyB;IAG5C,OAAO,CAAC,WAAW,CAAC,CAAkB;IAEtC,kEAAkE;IAClE,IAAI,UAAU,IAAI,eAAe,GAAG,SAAS,CAE5C;IAED,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;gBAEW,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM;IAwB/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAiDxE;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAiC3D;;;;;OAKG;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAWtE;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B3E;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,kBAAkB,CACvB,aAAa,GAAE,MAAc,EAC7B,aAAa,GAAE,MAAc,EAC7B,gBAAgB,GAAE,MAAM,EAAO,EAC/B,oBAAoB,GAAE,OAAc,GACnC,iBAAiB;IA6CpB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,uBAAuB,GAC1B,OAAO,CAAC,sBAAsB,CAAC;IAyDlC;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BrE;;;;;;OAMG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAmC1F;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAiD9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;OAEG;IACH,OAAO,CAAC,WAAW;CAWpB"}