{"_id":"@brnmwai/qova-core","_rev":"2-dee3e147fac09862a85a9f759d55592a","name":"@brnmwai/qova-core","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@brnmwai/qova-core","version":"0.1.0","_id":"@brnmwai/qova-core@0.1.0","maintainers":[{"name":"brnmwai","email":"brian@hausorlabs.tech"}],"dist":{"shasum":"f57b55cef3adbbca42f491ed65519b2abcd4100a","tarball":"https://registry.npmjs.org/@brnmwai/qova-core/-/qova-core-0.1.0.tgz","fileCount":105,"integrity":"sha512-Gs5UQq3+tsPVjOg8cYUupfHeThJw3rYYO6YX6R9hxpyPIW1VdBcr5A9GaJyzLdAFgxdxcyfsWvTT5hdV0YCITA==","signatures":[{"sig":"MEUCIE/4uGJX8QlcUUWE+WdAY5L88JGjQ/0P6BcCCsywGZ8iAiEA2a/oGzmCBUZUHoMPu2A5HYrl015UrsNIrStgclaan+s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":271731},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./abi":{"types":"./dist/abi/index.d.ts","import":"./dist/abi/index.js"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.js"},"./utils":{"types":"./dist/utils/index.d.ts","import":"./dist/utils/index.js"}},"gitHead":"4e881bf677c407ab3037a191ab864716bb9d2512","scripts":{"test":"vitest run","build":"tsc","check":"bunx biome check src/","check:fix":"bunx biome check --write src/","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"brnmwai","email":"brian@hausorlabs.tech"},"_npmVersion":"11.0.0","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.24.0","viem":"^2.21.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/qova-core_0.1.0_1772763951291_0.8712603680435265","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@brnmwai/qova-core","version":"0.2.0","description":"TypeScript SDK for the Qova protocol -- financial trust infrastructure for AI agents on Base L2","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./abi":{"import":"./dist/abi/index.js","types":"./dist/abi/index.d.ts"},"./types":{"import":"./dist/types/index.js","types":"./dist/types/index.d.ts"},"./utils":{"import":"./dist/utils/index.js","types":"./dist/utils/index.d.ts"}},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","check":"bunx biome check src/","check:fix":"bunx biome check --write src/"},"keywords":["qova","ai-agents","reputation","credit-score","blockchain","base","viem","defi","x402","smart-contracts","typescript","web3"],"author":{"name":"Qova Engineering","email":"eng@qova.cc","url":"https://qova.cc"},"license":"MIT","homepage":"https://github.com/brn-mwai/qova/tree/main/sdk#readme","repository":{"type":"git","url":"git+https://github.com/brn-mwai/qova.git","directory":"sdk"},"bugs":{"url":"https://github.com/brn-mwai/qova/issues"},"engines":{"node":">=18.0.0"},"sideEffects":false,"dependencies":{"viem":"^2.21.0","zod":"^3.24.0"},"devDependencies":{"typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@brnmwai/qova-core@0.2.0","gitHead":"4e881bf677c407ab3037a191ab864716bb9d2512","_nodeVersion":"22.22.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-kzyW4UXNk/8P/KDvZGXS1Di070OsJtjg8xqw3emTHS+y3476RE1p+Jh8tcZnobSo94UcB0P5cbHp4IqpQVLMxw==","shasum":"136b9b0dfd80ce3b508c5e7e010b07f44dbed038","tarball":"https://registry.npmjs.org/@brnmwai/qova-core/-/qova-core-0.2.0.tgz","fileCount":106,"unpackedSize":283605,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCQWlyoG5IYJl5NVNyaBfaVk+5e4Syu+PP3LLXmE/p4WAIhAOOEShfIrlnl5IVDXXhPkEIcFt4lg3l2icqUBWH3eRyk"}]},"_npmUser":{"name":"brnmwai","email":"brian@hausorlabs.tech"},"directories":{},"maintainers":[{"name":"brnmwai","email":"brian@hausorlabs.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qova-core_0.2.0_1772764223879_0.17235656658088905"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T02:25:51.142Z","modified":"2026-03-06T02:30:24.191Z","0.1.0":"2026-03-06T02:25:51.460Z","0.2.0":"2026-03-06T02:30:24.060Z"},"maintainers":[{"name":"brnmwai","email":"brian@hausorlabs.tech"}],"readme":"# @brnmwai/qova-core\n\nTypeScript SDK for the **Qova protocol** -- financial trust infrastructure for AI agents.\n\nQova computes on-chain credit scores (0--1000) for autonomous AI agents by analyzing their transaction history, budget adherence, and behavioral patterns. Think of it as a credit bureau, but for AI agents operating in DeFi.\n\n[![npm](https://img.shields.io/npm/v/@brnmwai/qova-core)](https://www.npmjs.com/package/@brnmwai/qova-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](https://github.com/brn-mwai/qova/blob/main/LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)\n\n## Features\n\n- **Full type safety** -- strict TypeScript with Zod runtime validation\n- **Tree-shakeable** -- ESM-only, named exports, side-effect free\n- **viem-native** -- built on [viem](https://viem.sh), not ethers.js\n- **Multi-chain** -- Base Sepolia (testnet), Base Mainnet, SKALE Europa\n- **4 contract modules** -- ReputationRegistry, TransactionValidator, BudgetEnforcer, QovaCore\n- **Event watchers** -- real-time subscription to on-chain events\n- **Zero config** -- deployed contract addresses baked in, just pick a chain\n\n## Installation\n\n```bash\nnpm install @brnmwai/qova-core viem\n```\n\n```bash\nbun add @brnmwai/qova-core viem\n```\n\n```bash\npnpm add @brnmwai/qova-core viem\n```\n\n> `viem` is a peer dependency and must be installed alongside.\n\n## Quick Start\n\n### Read an agent's credit score\n\n```ts\nimport { createQovaClient } from \"@brnmwai/qova-core\";\n\nconst qova = createQovaClient({ chain: \"base-sepolia\" });\n\nconst score = await qova.getScore(\"0x1234...abcd\");\nconsole.log(score); // 847\n```\n\n### Register an agent and record a transaction\n\n```ts\nimport { createQovaClient, TransactionType } from \"@brnmwai/qova-core\";\nimport { createWalletClient, http } from \"viem\";\nimport { privateKeyToAccount } from \"viem/accounts\";\nimport { baseSepolia } from \"viem/chains\";\n\nconst account = privateKeyToAccount(\"0x...\");\nconst walletClient = createWalletClient({\n  account,\n  chain: baseSepolia,\n  transport: http(),\n});\n\nconst qova = createQovaClient({\n  chain: \"base-sepolia\",\n  walletClient,\n});\n\n// Register the agent on-chain\nconst regTx = await qova.registerAgent(account.address);\n\n// Record a payment transaction\nconst recTx = await qova.recordTransaction(\n  account.address,\n  \"0xabc...def\", // transaction hash\n  1000000n, // amount in wei\n  TransactionType.PAYMENT,\n);\n\n// Check the score after CRE workflow runs\nconst score = await qova.getScore(account.address);\n```\n\n### Set budget limits\n\n```ts\nimport { parseEther } from \"viem\";\n\n// Set daily, monthly, and per-transaction limits\nawait qova.setBudget(\n  agentAddress,\n  parseEther(\"1\"), // 1 ETH daily\n  parseEther(\"10\"), // 10 ETH monthly\n  parseEther(\"0.5\"), // 0.5 ETH per tx\n);\n\n// Check if a spend is within limits\nconst allowed = await qova.checkBudget(agentAddress, parseEther(\"0.3\"));\n\n// Get full budget status\nconst status = await qova.getBudgetStatus(agentAddress);\nconsole.log(status);\n// { dailyLimit, monthlyLimit, perTxLimit, dailySpent, monthlySpent, ... }\n```\n\n### Watch events in real-time\n\n```ts\nimport { watchScoreUpdates, watchTransactions } from \"@brnmwai/qova-core\";\n\n// Watch all score changes\nconst unwatch = watchScoreUpdates(\n  { chain: \"base-sepolia\" },\n  (event) => {\n    console.log(`${event.agent}: ${event.oldScore} -> ${event.newScore}`);\n  },\n);\n\n// Watch transactions for a specific agent\nconst unwatchTx = watchTransactions(\n  { chain: \"base-sepolia\", agent: \"0x1234...abcd\" },\n  (event) => {\n    console.log(`Tx recorded: ${event.txHash} (${event.amount} wei)`);\n  },\n);\n\n// Stop watching\nunwatch();\nunwatchTx();\n```\n\n## API Reference\n\n### `createQovaClient(config)`\n\nCreates a typed client with all protocol methods.\n\n```ts\ntype QovaClientConfig = {\n  chain: \"base-sepolia\" | \"base\" | \"skale-europa\";\n  rpcUrl?: string; // Override default RPC\n  walletClient?: WalletClient; // Required for write operations\n  contracts?: Partial<ContractAddresses>; // Override deployed addresses\n};\n```\n\n**Returns** a `QovaClient` with these methods:\n\n#### Reputation\n\n| Method | Type | Description |\n|--------|------|-------------|\n| `getScore(agent)` | read | Get score (0--1000) |\n| `getAgentDetails(agent)` | read | Full agent struct (score, grade, tx count, timestamps) |\n| `isAgentRegistered(agent)` | read | Check registration status |\n| `registerAgent(agent)` | write | Register a new agent |\n| `updateScore(agent, score, reason)` | write | Update an agent's score |\n| `batchUpdateScores(agents[], scores[], reasons[])` | write | Batch score update |\n\n#### Transactions\n\n| Method | Type | Description |\n|--------|------|-------------|\n| `recordTransaction(agent, txHash, amount, txType)` | write | Record a transaction |\n| `getTransactionStats(agent)` | read | Aggregate stats (count, volume, success rate) |\n\n#### Budget\n\n| Method | Type | Description |\n|--------|------|-------------|\n| `setBudget(agent, daily, monthly, perTx)` | write | Set spending limits |\n| `checkBudget(agent, amount)` | read | Check if spend is within limits |\n| `recordSpend(agent, amount)` | write | Record a spend against budget |\n| `getBudgetStatus(agent)` | read | Get remaining allowances |\n\n#### Core\n\n| Method | Type | Description |\n|--------|------|-------------|\n| `executeAgentAction(agent, txHash, amount, txType)` | write | Execute action through QovaCore orchestrator |\n\n### Score Grades\n\nScores map to letter grades following a credit rating system:\n\n| Grade | Score Range | Meaning |\n|-------|------------|---------|\n| AAA | 950--1000 | Exceptional |\n| AA | 900--949 | Excellent |\n| A | 850--899 | Very Good |\n| BBB | 750--849 | Good |\n| BB | 650--749 | Fair |\n| B | 550--649 | Adequate |\n| CCC | 450--549 | Below Average |\n| CC | 350--449 | Poor |\n| C | 250--349 | Very Poor |\n| D | 0--249 | Default Risk |\n\n### Transaction Types\n\n```ts\nimport { TransactionType } from \"@brnmwai/qova-core\";\n\nTransactionType.PAYMENT; // 0\nTransactionType.SWAP; // 1\nTransactionType.TRANSFER; // 2\nTransactionType.CONTRACT_CALL; // 3\nTransactionType.BRIDGE; // 4\n```\n\n## Sub-path Exports\n\nThe SDK exposes granular imports for tree-shaking:\n\n```ts\n// Contract ABIs only\nimport { reputationRegistryAbi, budgetEnforcerAbi } from \"@brnmwai/qova-core/abi\";\n\n// Type definitions and Zod schemas\nimport type { AgentDetails, BudgetStatus } from \"@brnmwai/qova-core/types\";\nimport { AgentDetailsSchema, TransactionType } from \"@brnmwai/qova-core/types\";\n\n// Utility functions\nimport { getGrade, getScoreColor, formatScore } from \"@brnmwai/qova-core/utils\";\nimport { shortenAddress, isValidAddress } from \"@brnmwai/qova-core/utils\";\nimport { formatWei, formatBasisPoints } from \"@brnmwai/qova-core/utils\";\n```\n\n## Utilities\n\n### Score Utilities\n\n```ts\nimport { getGrade, getScoreColor, formatScore, scoreToPercentage } from \"@brnmwai/qova-core\";\n\ngetGrade(950); // \"AAA\"\ngetGrade(720); // \"BB\"\ngetScoreColor(800); // \"#22C55E\" (green)\ngetScoreColor(500); // \"#FACC15\" (yellow)\ngetScoreColor(200); // \"#EF4444\" (red)\nformatScore(42); // \"0042\"\nscoreToPercentage(750); // 75\n```\n\n### Address Utilities\n\n```ts\nimport { shortenAddress, isValidAddress, checksumAddress } from \"@brnmwai/qova-core\";\n\nshortenAddress(\"0x0a3AF9a104Bd2B5d96C7E24fe95Cc03432431158\"); // \"0x0a3A...1158\"\nisValidAddress(\"0x0a3AF9a104Bd2B5d96C7E24fe95Cc03432431158\"); // true\nchecksumAddress(\"0x0a3af9a104bd2b5d96c7e24fe95cc03432431158\"); // \"0x0a3A...\"\n```\n\n### Format Utilities\n\n```ts\nimport { formatWei, formatTimestamp, formatBasisPoints } from \"@brnmwai/qova-core\";\n\nformatWei(1500000000000000000n); // \"1.5\"\nformatWei(1000000n, 6); // \"1.0\" (USDC)\nformatTimestamp(1709000000n); // Date object\nformatBasisPoints(9750); // \"97.50%\"\n```\n\n## Error Handling\n\nThe SDK throws typed errors that map to Solidity custom errors:\n\n```ts\nimport {\n  QovaError,\n  AgentNotRegisteredError,\n  BudgetExceededError,\n  InvalidScoreError,\n} from \"@brnmwai/qova-core\";\n\ntry {\n  await qova.getScore(\"0x...\");\n} catch (error) {\n  if (error instanceof AgentNotRegisteredError) {\n    console.log(error.code); // \"AGENT_NOT_REGISTERED\"\n  }\n  if (error instanceof BudgetExceededError) {\n    console.log(error.requested); // bigint\n    console.log(error.available); // bigint\n  }\n}\n```\n\nAll error classes extend `QovaError` with a `.code` string:\n\n| Error Class | Code | Trigger |\n|------------|------|---------|\n| `AgentNotRegisteredError` | `AGENT_NOT_REGISTERED` | Operating on unregistered agent |\n| `AgentAlreadyRegisteredError` | `AGENT_ALREADY_REGISTERED` | Double registration |\n| `BudgetExceededError` | `BUDGET_EXCEEDED` | Spend exceeds limits |\n| `InvalidScoreError` | `INVALID_SCORE` | Score outside 0--1000 |\n| `UnauthorizedError` | `UNAUTHORIZED` | Missing required role |\n\n## Deployed Contracts\n\n### Base Sepolia (Chain ID: 84532)\n\n| Contract | Address |\n|----------|---------|\n| ReputationRegistry | `0x0b2466b01E6d73A24D9C716A9072ED3923563fBB` |\n| TransactionValidator | `0x5d7a7AEAb26D2F0076892D1C9A28F230EbB3e900` |\n| BudgetEnforcer | `0x271618781040dc358e4F6B66561b65A839b0C76E` |\n| QovaCore | `0x9Ee4ae0bD93E95498fB6AB444ae6205d56fEf76a` |\n\n## Architecture\n\n```\n@brnmwai/qova-core\n  |-- client.ts          # createQovaClient factory\n  |-- constants.ts       # Chain IDs, contract addresses, score thresholds\n  |-- events.ts          # Real-time event watchers\n  |-- contracts/\n  |   |-- reputation.ts  # ReputationRegistry interactions\n  |   |-- transactions.ts# TransactionValidator interactions\n  |   |-- budget.ts      # BudgetEnforcer interactions\n  |   |-- core.ts        # QovaCore orchestrator\n  |-- types/\n  |   |-- agent.ts       # AgentDetails, ScoreGrade\n  |   |-- budget.ts      # BudgetConfig, BudgetStatus\n  |   |-- config.ts      # QovaClientConfig, ContractAddresses\n  |   |-- errors.ts      # Typed error classes\n  |   |-- events.ts      # Event types\n  |   |-- transaction.ts # TransactionType, TransactionStats\n  |-- abi/               # Contract ABIs (auto-generated from Foundry)\n  |-- utils/\n      |-- score.ts       # Grade, color, formatting\n      |-- address.ts     # Shorten, validate, checksum\n      |-- format.ts      # Wei, timestamps, basis points\n```\n\n## How Qova Works\n\n1. **Register** -- AI agents are registered on-chain via `ReputationRegistry`\n2. **Transact** -- Agent transactions are recorded via `TransactionValidator`\n3. **Budget** -- Spending limits are enforced via `BudgetEnforcer`\n4. **Score** -- Chainlink CRE workflows analyze on-chain + off-chain data and compute a weighted credit score (0--1000), written back on-chain\n5. **Consume** -- Anyone can read an agent's score from the contract. DeFi protocols, lenders, and insurance providers use scores for underwriting decisions.\n\n## Requirements\n\n- Node.js 18+\n- TypeScript 5.7+ (for strict mode)\n- `viem` ^2.21.0\n\n## Contributing\n\nThis SDK is part of the [Qova monorepo](https://github.com/brn-mwai/qova). To develop locally:\n\n```bash\ngit clone https://github.com/brn-mwai/qova.git\ncd qova/sdk\nbun install\nbun run build\nbun run test\n```\n\n## License\n\nMIT -- see [LICENSE](https://github.com/brn-mwai/qova/blob/main/LICENSE)\n","readmeFilename":"README.md","description":"TypeScript SDK for the Qova protocol -- financial trust infrastructure for AI agents on Base L2","homepage":"https://github.com/brn-mwai/qova/tree/main/sdk#readme","keywords":["qova","ai-agents","reputation","credit-score","blockchain","base","viem","defi","x402","smart-contracts","typescript","web3"],"repository":{"type":"git","url":"git+https://github.com/brn-mwai/qova.git","directory":"sdk"},"author":{"name":"Qova Engineering","email":"eng@qova.cc","url":"https://qova.cc"},"bugs":{"url":"https://github.com/brn-mwai/qova/issues"},"license":"MIT"}