{"_id":"@alexchen31337/clawchain-sdk","name":"@alexchen31337/clawchain-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alexchen31337/clawchain-sdk","version":"1.0.0","description":"TypeScript SDK for ClawChain — the L1 blockchain for autonomous agents","license":"MIT","type":"module","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"},"./testing":{"import":"./dist/testing/index.mjs","require":"./dist/testing/index.js","types":"./dist/testing/index.d.ts"}},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:integration":"vitest run --config vitest.integration.config.ts","test:coverage":"vitest run --coverage","lint":"eslint src","typecheck":"tsc --noEmit","prepublishOnly":"pnpm run build && pnpm run typecheck && pnpm run test"},"dependencies":{"@polkadot/api":"^12.0.0","@polkadot/keyring":"^12.0.0","@polkadot/util":"^12.0.0","@polkadot/util-crypto":"^12.0.0"},"devDependencies":{"@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","@vitest/coverage-v8":"^1.6.0","eslint":"^8.57.0","prettier":"^3.2.0","tsup":"^8.0.0","typescript":"^5.4.0","vitest":"^1.6.0"},"engines":{"node":">=18"},"keywords":["clawchain","blockchain","substrate","polkadot","agent","did","autonomous-agents","web3"],"repository":{"type":"git","url":"git+https://github.com/clawinfra/clawchain-sdk.git"},"bugs":{"url":"https://github.com/clawinfra/clawchain-sdk/issues"},"homepage":"https://github.com/clawinfra/clawchain-sdk#readme","_id":"@alexchen31337/clawchain-sdk@1.0.0","gitHead":"32dd979c97608987ea1de563d3782091ac068d1d","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-BgTHrBjAj7ShvIfTmAG6emCbYYC1etqUUWWPykm86vxEQ6+U0yyNx4S6ihvyCIUViLCE3/8RXkQ3Yy20LXrfKw==","shasum":"b3ee8f524b750fd7aec57f52d137339dc3e827e5","tarball":"https://registry.npmjs.org/@alexchen31337/clawchain-sdk/-/clawchain-sdk-1.0.0.tgz","fileCount":15,"unpackedSize":369513,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB62PT688Z6jI8H/VF30dUpsHYnDderQZukNgeKI/uIzAiBc/byVtdfZl92RdkUL7NpOavG6u9Wy9eydPgxaDCgFVw=="}]},"_npmUser":{"name":"alexchen31337","email":"alex.chen31337@gmail.com"},"directories":{},"maintainers":[{"name":"alexchen31337","email":"alex.chen31337@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clawchain-sdk_1.0.0_1772252592638_0.24307609014004616"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T04:23:12.556Z","1.0.0":"2026-02-28T04:23:12.802Z","modified":"2026-02-28T04:23:13.025Z"},"maintainers":[{"name":"alexchen31337","email":"alex.chen31337@gmail.com"}],"description":"TypeScript SDK for ClawChain — the L1 blockchain for autonomous agents","homepage":"https://github.com/clawinfra/clawchain-sdk#readme","keywords":["clawchain","blockchain","substrate","polkadot","agent","did","autonomous-agents","web3"],"repository":{"type":"git","url":"git+https://github.com/clawinfra/clawchain-sdk.git"},"bugs":{"url":"https://github.com/clawinfra/clawchain-sdk/issues"},"license":"MIT","readme":"# @clawchain/sdk\n\n> TypeScript SDK for ClawChain — the L1 blockchain for autonomous agents.\n\n[![CI](https://github.com/clawinfra/clawchain-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/clawinfra/clawchain-sdk/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@clawchain/sdk)](https://www.npmjs.com/package/@clawchain/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\n`@clawchain/sdk` provides a typed, ergonomic TypeScript API for interacting with ClawChain's custom Substrate pallets:\n\n- **Agent Registry** — register agent DIDs, query agent info by address or ID\n- **Reputation** — read on-chain reputation scores and leaderboards\n- **Gas Quota** — check quota availability, estimate operation costs\n- **CLW Token** — query balances, get token metadata\n\nBuilt on `@polkadot/api`. Dual CJS/ESM output. Node.js ≥ 18.\n\n---\n\n## Installation\n\n```bash\nnpm install @clawchain/sdk\n# or\npnpm add @clawchain/sdk\n# or\nyarn add @clawchain/sdk\n```\n\n---\n\n## Quick Start\n\n```ts\nimport { ClawChainClient } from '@clawchain/sdk'\n\nconst client = await ClawChainClient.connect({\n  endpoint: 'wss://testnet.clawchain.win:9944',\n})\n\n// Query agents owned by an address\nconst agentIds = await client.agent.getOwnerAgents('5GrwvaEF5zXb...')\nconsole.log('Agent IDs:', agentIds)\n\n// Get full agent details\nconst agent = await client.agent.getAgent(agentIds[0])\nconsole.log('Agent:', agent?.name, agent?.status)\n\n// Resolve a DID\nconst agentByDid = await client.agent.resolveDid('did:clawchain:0xabc...')\n\n// Get reputation\nconst rep = await client.reputation.getReputation('5GrwvaEF5zXb...')\nconsole.log('Reputation score:', rep?.score / 100, '%')\n\n// Get CLW balance\nconst balance = await client.token.getBalance('5GrwvaEF5zXb...')\nconsole.log('Free balance:', balance.free.toString())\n\n// Check gas quota\nconst quota = await client.quota.getQuota('5GrwvaEF5zXb...')\nconst canProceed = await client.quota.hasQuota('5GrwvaEF5zXb...', 500_000n)\n\nawait client.disconnect()\n```\n\n---\n\n## API Reference\n\n### `ClawChainClient`\n\n#### `ClawChainClient.connect(opts: ConnectOptions): Promise<ClawChainClient>`\n\nEstablishes a WebSocket connection to a ClawChain node.\n\n```ts\ninterface ConnectOptions {\n  endpoint: string              // wss://... WebSocket URL\n  timeoutMs?: number            // default: 30_000\n  reconnect?: boolean           // default: true\n  maxReconnectAttempts?: number // default: 5\n  logger?: Logger               // optional custom logger\n}\n```\n\n#### `client.health(): Promise<HealthStatus>`\n\n```ts\ninterface HealthStatus {\n  connected: boolean\n  blockNumber: number\n  blockHash: string\n  peersCount: number\n  isSyncing: boolean\n  nodeVersion: string\n  chainName: string\n}\n```\n\n#### `client.disconnect(): Promise<void>`\n\nCleanly closes the WebSocket connection.\n\n#### `client.getApi(): ApiPromise`\n\nEscape hatch to the raw `@polkadot/api` instance.\n\n---\n\n### Agent Module (`client.agent`)\n\n#### `getOwnerAgents(ownerAddress: string): Promise<AgentId[]>`\n\nReturns all agent IDs registered to an SS58 address.\nStorage: `agentRegistry.ownerAgents(address)`\n\n#### `getAgent(agentId: AgentId): Promise<AgentInfo | null>`\n\nReturns full agent details for a given H256 agent ID.\nStorage: `agentRegistry.agentRegistry(agentId)`\n\n#### `requireAgent(agentId: AgentId): Promise<AgentInfo>`\n\nLike `getAgent`, but throws `AgentNotFoundError` if not found.\n\n#### `resolveDid(did: string): Promise<AgentInfo | null>`\n\nResolves a `did:clawchain:<id>` string to agent info.\n\n#### `listAgents(opts?: PaginationOpts): Promise<PagedResult<AgentInfo>>`\n\nScans all registered agents (use with caution on large chains).\n\n#### `listAgentsByOwner(ownerAddress: string, opts?: PaginationOpts): Promise<PagedResult<AgentInfo>>`\n\nPaginated list of agents for a specific owner.\n\n---\n\n### Reputation Module (`client.reputation`)\n\n#### `getReputation(accountId: string): Promise<ReputationInfo | null>`\n\nGet reputation score for an account.\nStorage: `reputation.reputations(accountId)`\n\n```ts\ninterface ReputationInfo {\n  accountId: string\n  score: number             // 0–10_000 (divide by 100 for display)\n  positiveCount: number\n  negativeCount: number\n  totalInteractions: number\n  lastUpdatedBlock: number\n}\n```\n\n#### `getAgentReputation(agentId: AgentId): Promise<ReputationInfo | null>`\n\nConvenience wrapper — resolves agent owner, then fetches reputation.\n\n#### `getHistory(accountId: string, opts?: HistoryOpts): Promise<PagedResult<ReputationEvent>>`\n\nReturns historical reputation changes. *Phase 1: returns empty (event scanning ships in Phase 4).*\n\n#### `getLeaderboard(limit?: number): Promise<ReputationRanking[]>`\n\nTop accounts by reputation score.\n\n---\n\n### Gas Quota Module (`client.quota`)\n\n#### `getQuota(accountId: string): Promise<QuotaInfo | null>`\n\nCurrent quota state for an account.\nStorage: `gasQuota.agentQuotas(accountId)`\n\n```ts\ninterface QuotaInfo {\n  accountId: string\n  remaining: bigint\n  limit: bigint\n  resetBlock: number\n  tier: 'Basic' | 'Standard' | 'Premium' | 'Unlimited'\n}\n```\n\n#### `hasQuota(accountId: string, estimatedGas: bigint): Promise<boolean>`\n\nReturns `true` if the account's remaining quota covers the estimated gas.\n\n#### `estimate(operation: OperationType): GasEstimate`\n\nReturns static gas estimates for known operation types:\n\n```ts\ntype OperationType =\n  | 'agent.register'\n  | 'agent.update'\n  | 'agent.deactivate'\n  | 'market.bid'\n  | 'market.complete'\n  | 'market.dispute'\n  | 'reputation.submit'\n```\n\n---\n\n### Token Module (`client.token`)\n\n#### `getBalance(address: string): Promise<TokenBalance>`\n\nCLW token balance breakdown for an address.\n\n```ts\ninterface TokenBalance {\n  free: bigint\n  reserved: bigint\n  frozen: bigint\n  total: bigint        // free + reserved\n  transferable: bigint // free - frozen\n}\n```\n\n#### `getBalances(addresses: string[]): Promise<Map<string, TokenBalance>>`\n\nBatch balance fetch.\n\n#### `getTotalSupply(): Promise<bigint>`\n\nTotal CLW in existence.\n\n#### `getMetadata(): TokenMetadata`\n\nReturns `{ name: 'ClawChain Token', symbol: 'CLW', decimals: 18 }`.\n\n---\n\n## Error Handling\n\nAll SDK errors extend `ClawChainError` and include a machine-readable `code` field:\n\n```ts\nimport { AgentNotFoundError, InsufficientQuotaError, ClawChainError } from '@clawchain/sdk'\n\ntry {\n  const agent = await client.agent.requireAgent(agentId)\n} catch (err) {\n  if (err instanceof AgentNotFoundError) {\n    console.error('No such agent:', err.agentId)\n  } else if (err instanceof ClawChainError) {\n    console.error(err.code, err.message)\n  }\n}\n```\n\n| Error class | Code | When |\n|---|---|---|\n| `ConnectionError` | `CONNECTION_ERROR` | WS connect failed |\n| `ChainMismatchError` | `CHAIN_MISMATCH` | Wrong network |\n| `AgentNotFoundError` | `AGENT_NOT_FOUND` | Agent ID not on-chain |\n| `InsufficientQuotaError` | `INSUFFICIENT_QUOTA` | Gas quota exhausted |\n| `InsufficientBalanceError` | `INSUFFICIENT_BALANCE` | Token balance too low |\n| `TransactionError` | `TRANSACTION_ERROR` | Extrinsic rejected |\n| `TimeoutError` | `TIMEOUT_ERROR` | RPC timed out |\n| `InvalidArgumentError` | `INVALID_ARGUMENT` | Bad input |\n\n---\n\n## Testing Utilities\n\nImport mocks from `@clawchain/sdk/testing` (dev/test only):\n\n```ts\nimport { createMockClient, mockAgent, mockReputation } from '@clawchain/sdk/testing'\n\nconst client = createMockClient({\n  agents: [mockAgent],\n  reputations: { [mockAgent.owner]: mockReputation },\n  quotas: { [mockAgent.owner]: { remaining: 1_000_000n, limit: 5_000_000n, ... } },\n})\n\n// Use exactly like a real ClawChainClient — no network needed\nconst rep = await client.reputation.getReputation(mockAgent.owner)\nexpect(rep?.score).toBe(8500)\n```\n\n---\n\n## Configuration\n\n| Environment variable | Purpose |\n|---|---|\n| `CLAWCHAIN_ENDPOINT` | Default node endpoint for integration tests |\n| `TEST_SIGNER_MNEMONIC` | Funded keypair for integration tests |\n\n---\n\n## Roadmap\n\n| Phase | Version | Status |\n|---|---|---|\n| Phase 1 — Read-only API | `0.1.0-alpha.1` | ✅ Current |\n| Phase 2 — Write API (transactions) | `0.1.0-alpha.2` | Planned |\n| Phase 3 — Market module | `0.2.0-alpha.1` | Planned |\n| Phase 4 — Events & subscriptions | `0.2.0-alpha.2` | Planned |\n| Phase 5 — GA stable | `0.1.0` | Planned |\n\n---\n\n## Contributing\n\nSee [AGENTS.md](https://github.com/clawinfra/.github/blob/main/AGENTS.md) for the ClawInfra contribution guide.\n\n```bash\ngit clone https://github.com/clawinfra/clawchain-sdk\ncd clawchain-sdk\npnpm install\npnpm test\npnpm run test:coverage\n```\n\n---\n\n## License\n\nMIT © ClawChain Contributors\n","readmeFilename":"README.md","_rev":"1-bad8cea1899b55bbed4d7242d954855d"}