{"_id":"@altitrace/sdk","name":"@altitrace/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@altitrace/sdk","version":"1.0.0","description":"TypeScript SDK for the Altitrace HyperEVM transaction simulation platform","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./client/altitrace":{"types":"./dist/client/altitrace-client.d.ts","import":"./dist/client/altitrace-client.js","require":"./dist/client/altitrace-client.cjs"},"./client/simulation":{"types":"./dist/client/simulation-client.d.ts","import":"./dist/client/simulation-client.js","require":"./dist/client/simulation-client.cjs"},"./client/trace":{"types":"./dist/client/trace-client.d.ts","import":"./dist/client/trace-client.js","require":"./dist/client/trace-client.cjs"},"./builders/trace":{"types":"./dist/builders/trace-builder.d.ts","import":"./dist/builders/trace-builder.js","require":"./dist/builders/trace-builder.cjs"},"./builders/simulation":{"types":"./dist/builders/simulation-builder.d.ts","import":"./dist/builders/simulation-builder.js","require":"./dist/builders/simulation-builder.cjs"},"./builders/helpers/bundle":{"types":"./dist/builders/helpers/bundle-helpers.d.ts","import":"./dist/builders/helpers/bundle-helpers.js","require":"./dist/builders/helpers/bundle-helpers.cjs"},"./builders/helpers/trace":{"types":"./dist/builders/helpers/trace-helpers.d.ts","import":"./dist/builders/helpers/trace-helpers.js","require":"./dist/builders/helpers/trace-helpers.cjs"},"./builders/helpers/state-context":{"types":"./dist/builders/helpers/state-context-helpers.d.ts","import":"./dist/builders/helpers/state-context-helpers.js","require":"./dist/builders/helpers/state-context-helpers.cjs"},"./builders/helpers/state-override":{"types":"./dist/builders/helpers/state-override-helpers.d.ts","import":"./dist/builders/helpers/state-override-helpers.js","require":"./dist/builders/helpers/state-override-helpers.cjs"},"./builders/helpers/block-override":{"types":"./dist/builders/helpers/block-override-helpers.d.ts","import":"./dist/builders/helpers/block-override-helpers.js","require":"./dist/builders/helpers/block-override-helpers.cjs"},"./utils/validation":{"types":"./dist/utils/validation.d.ts","import":"./dist/utils/validation.js","require":"./dist/utils/validation.cjs"},"./utils/viem":{"types":"./dist/utils/viem-integration.d.ts","import":"./dist/utils/viem-integration.js","require":"./dist/utils/viem-integration.cjs"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.js","require":"./dist/types/index.cjs"}},"scripts":{"build":"tsup","build:types":"bun run generate:types","generate:types":"openapi-typescript swagger.json --output src/generated/api-types.ts","dev":"tsup --watch","test":"bun test","test:watch":"bun test --watch","typecheck":"tsc --noEmit","fmt:check":"biome format .","fmt":"biome format . --write","lint":"biome check . --write --unsafe && biome format . --write","lint:check":"biome check .","clean":"rm -rf dist","prepublishOnly":"bun run clean && bun run build:types && bun run build && bun run test && bun run typecheck"},"keywords":["ethereum","hyperevm","simulation","blockchain","typescript","web3"],"author":{"name":"Altitrace Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/altitrace/altitrace.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/altitrace/altitrace/issues"},"homepage":"https://github.com/altitrace/altitrace/tree/main/packages/sdk#readme","peerDependencies":{"viem":"^2.0.0"},"devDependencies":{"@biomejs/biome":"2.2.0","@eslint/js":"^9.33.0","@types/bun":"^1.2.20","@typescript-eslint/eslint-plugin":"^8.39.1","@typescript-eslint/parser":"^8.39.1","eslint":"^9.33.0","openapi-typescript":"^7.9.1","prettier":"^3.6.2","tsup":"^8.5.0","typescript":"^5.9.2","viem":"^2.34.0"},"dependencies":{},"engines":{"node":">=18.0.0"},"_id":"@altitrace/sdk@1.0.0","gitHead":"87128b3bf792c376aaf5c9883048864247fde32e","_nodeVersion":"24.5.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-gNIbeY7FqFyaPZ+LFH0xyQDVFqHReE+hO/GXqcG5J4lkwLM47LsIr5RlqVlw4LtYCNf6Uk+YnQw8arsY8W9F7Q==","shasum":"84375482f7b9979a08400874726733b58d24c94c","tarball":"https://registry.npmjs.org/@altitrace/sdk/-/sdk-1.0.0.tgz","fileCount":104,"unpackedSize":1569103,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAD3y9Tlh6dwQPbWEhOGkOAntP2wrNO/KkJMDnoWxhEgAiEAlx04mB36GLjgTlz5TelCjC8CDGnKfxjrVFK6WHhu02c="}]},"_npmUser":{"name":"querty","email":"quuertyy@protonmail.com"},"directories":{},"maintainers":[{"name":"querty","email":"quuertyy@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1756081591023_0.14650819575544793"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-25T00:26:30.892Z","1.0.0":"2025-08-25T00:26:31.208Z","modified":"2025-08-25T00:26:31.514Z"},"maintainers":[{"name":"querty","email":"quuertyy@protonmail.com"}],"description":"TypeScript SDK for the Altitrace HyperEVM transaction simulation platform","homepage":"https://github.com/altitrace/altitrace/tree/main/packages/sdk#readme","keywords":["ethereum","hyperevm","simulation","blockchain","typescript","web3"],"repository":{"type":"git","url":"git+https://github.com/altitrace/altitrace.git","directory":"packages/sdk"},"author":{"name":"Altitrace Team"},"bugs":{"url":"https://github.com/altitrace/altitrace/issues"},"license":"MIT","readme":"# @altitrace/sdk\n\n[![npm version](https://img.shields.io/npm/v/@altitrace/sdk.svg)](https://www.npmjs.com/package/@altitrace/sdk)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe official TypeScript SDK for the Altitrace HyperEVM transaction simulation platform. This SDK provides a comprehensive, type-safe interface for simulating Ethereum transactions, with support for complex scenarios like state overrides, batch operations, and detailed gas analysis.\n\n## Features\n\n- 🔒 **Full Type Safety** - Strict TypeScript support with no `any` types\n- 🔄 **Fluent API** - Builder pattern for intuitive request construction  \n- 🛡️ **Robust Error Handling** - Comprehensive error types and retry logic\n- 📊 **Rich Response Processing** - Detailed simulation results with utility methods\n- ⚡ **Viem Integration** - Seamless interoperability with Viem types\n- 🧪 **Comprehensive Testing** - Full test coverage for all functionality\n- 📚 **Extensive Documentation** - Complete JSDoc documentation for all APIs\n\n## Installation\n\n```bash\n# Using bun (recommended)\nbun add @altitrace/sdk\n\n# Using npm\nnpm install @altitrace/sdk\n\n# Using yarn\nyarn add @altitrace/sdk\n```\n\n### Peer Dependencies\n\nThis SDK is designed to work alongside [Viem](https://viem.sh) for optimal Web3 development experience:\n\n```bash\nbun add viem\n```\n\n## Quick Start\n\n```typescript\nimport { AltitraceClient } from '@altitrace/sdk';\n\n// Create a client\nconst client = new AltitraceClient({\n  baseUrl: 'https://api.altitrace.com/v1', // Replace with your API URL\n});\n\n// Simulate a simple transaction\nconst result = await client.simulate()\n  .call({\n    to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC contract\n    data: '0xa9059cbb000000000000000000000000742d35cc6634c0532925a3b844bc9e7595f06e8c0000000000000000000000000000000000000000000000000000000000989680',\n    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f06e8c',\n  })\n  .atBlockTag('latest')\n  .execute();\n\n// Check results\nconsole.log(`Simulation ${result.isSuccess() ? 'succeeded' : 'failed'}`);\nconsole.log(`Gas used: ${result.getTotalGasUsed().toLocaleString()}`);\n\nif (result.isFailed()) {\n  console.log('Errors:', result.getErrors());\n}\n```\n\n## Advanced Usage\n\n### State Overrides\n\nModify account state before simulation:\n\n```typescript\nconst result = await client.simulate()\n  .call({\n    to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n    data: '0xa9059cbb...',\n    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f06e8c',\n  })\n  .withStateOverride({\n    address: '0x742d35Cc6634C0532925a3b844Bc9e7595f06e8c',\n    balance: '0x1000000000000000000', // Give account 1 ETH\n  })\n  .execute();\n```\n\n### Asset Change Tracking\n\nTrack token balance changes during simulation:\n\n```typescript\nconst result = await client.simulate()\n  .call({\n    to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n    data: '0xa9059cbb...',\n    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f06e8c',\n  })\n  .forAccount('0x742d35Cc6634C0532925a3b844Bc9e7595f06e8c')\n  .withAssetChanges(true)\n  .withTransfers(true)\n  .execute();\n\n// Get asset change summary\nconst changes = result.getAssetChangesSummary();\nif (changes) {\n  changes.forEach(change => {\n    console.log(`${change.symbol}: ${change.isGain ? '+' : ''}${change.change}`);\n  });\n}\n```\n\n### Batch Simulation\n\nSimulate multiple independent transactions:\n\n```typescript\nconst batchResult = await client.simulateBatch({\n  simulations: [\n    {\n      params: {\n        calls: [{ to: '0x...', data: '0x...' }],\n        validation: true,\n        traceAssetChanges: false,\n        traceTransfers: false,\n      }\n    },\n    {\n      params: {\n        calls: [{ to: '0x...', data: '0x...' }],\n        validation: true,\n        traceAssetChanges: false,\n        traceTransfers: false,\n      }\n    },\n  ],\n  concurrency: 3,\n});\n\nconsole.log(`${batchResult.successCount}/${batchResult.results.length} simulations succeeded`);\n```\n\n### Viem Integration\n\nSeamlessly convert between Viem and SDK types:\n\n```typescript\nimport { viemToTransactionCall, createClient } from '@altitrace/sdk';\nimport { parseEther, encodeFunctionData } from 'viem';\n\n// Convert Viem transaction request\nconst viemTx = {\n  to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n  value: parseEther('1'),\n  data: encodeFunctionData({\n    abi: erc20Abi,\n    functionName: 'transfer',\n    args: ['0x...', parseUnits('100', 6)],\n  }),\n};\n\nconst result = await client.simulate()\n  .call(viemToTransactionCall(viemTx))\n  .execute();\n```\n\n### Error Handling\n\nThe SDK provides comprehensive error handling with specific error types:\n\n```typescript\nimport { \n  AltitraceApiError, \n  ValidationError, \n  AltitraceNetworkError \n} from '@altitrace/sdk';\n\ntry {\n  const result = await client.simulate()\n    .call({ to: 'invalid-address' })\n    .execute();\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.log('Invalid input:', error.message);\n    console.log('Field:', error.field);\n  } else if (error instanceof AltitraceApiError) {\n    console.log('API error:', error.code, error.message);\n    console.log('Suggestion:', error.suggestion);\n  } else if (error instanceof AltitraceNetworkError) {\n    console.log('Network error:', error.code);\n  }\n}\n```\n\n## Configuration Options\n\n### Client Configuration\n\n```typescript\nconst client = new AltitraceClient({\n  baseUrl: 'https://api.altitrace.com/v1',\n  timeout: 60_000,           // 60 seconds\n  retries: 5,                // 5 retry attempts\n  debug: true,               // Enable debug logging\n  headers: {                 // Custom headers\n    'Authorization': 'Bearer token',\n    'X-Custom-Header': 'value',\n  },\n});\n```\n\n### Pre-configured Clients\n\n```typescript\nimport { createClient } from '@altitrace/sdk';\n\n// Local development\nconst localClient = createClient.local({ debug: true });\n\n// Production\nconst prodClient = createClient.production({\n  headers: { 'Authorization': 'Bearer token' }\n});\n\n// Testing\nconst testClient = createClient.testing({ timeout: 5000 });\n```\n\n## Response Processing\n\n### Extended Simulation Results\n\nAll simulation results include utility methods for easier data access:\n\n```typescript\nconst result = await client.simulate().call({...}).execute();\n\n// Status checks\nconsole.log('Success:', result.isSuccess());\nconsole.log('Failed:', result.isFailed());\n\n// Gas analysis\nconsole.log('Total gas:', result.getTotalGasUsed());\n\n// Event analysis\nconst events = result.getDecodedEvents();\nconsole.log('Decoded events:', events.length);\n\n// Error analysis\nif (result.isFailed()) {\n  const errors = result.getErrors();\n  errors.forEach(error => {\n    console.log(`Error: ${error.reason} (${error.errorType})`);\n  });\n}\n\n// Log filtering\nconst usdcLogs = result.getLogsByAddress('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');\n```\n\n### Gas Analysis\n\n```typescript\nimport { ResponseProcessor } from '@altitrace/sdk';\n\nconst gasBreakdown = ResponseProcessor.extractGasUsage(result);\n\nconsole.log('Total gas used:', gasBreakdown.totalGasUsed);\nconsole.log('Call gas usage:', gasBreakdown.callGasUsage);\n\nif (gasBreakdown.breakdown) {\n  console.log('Intrinsic:', gasBreakdown.breakdown.intrinsic);\n  console.log('Computation:', gasBreakdown.breakdown.computation);\n  console.log('Storage reads:', gasBreakdown.breakdown.storage.reads);\n}\n```\n\n### Event Analysis\n\n```typescript\nimport { ResponseProcessor } from '@altitrace/sdk';\n\nconst events = ResponseProcessor.extractEvents(result);\n\nevents.forEach(event => {\n  console.log(`Event: ${event.decoded?.name || 'Unknown'}`);\n  console.log(`Contract: ${event.contractAddress}`);\n  console.log(`Summary: ${event.decoded?.summary}`);\n});\n```\n\n## Utilities\n\n### Gas Utilities\n\n```typescript\nimport { GasUtils } from '@altitrace/sdk';\n\n// Convert between formats\nconst gasHex = GasUtils.toHexNumber(21000);        // '0x5208'\nconst gasNumber = GasUtils.toNumber('0x5208');     // 21000\nconst gasBigint = GasUtils.toBigint('0x5208');     // 21000n\n\n// Gas calculations\nconst total = GasUtils.add('0x5208', '0x5208');    // '0xa410'\nconst difference = GasUtils.subtract('0xa410', '0x5208'); // '0x5208'\nconst percentage = GasUtils.calculatePercentage('0x5208', '0xa410'); // 50\n```\n\n### Wei Utilities\n\n```typescript\nimport { WeiUtils } from '@altitrace/sdk';\n\n// Convert ETH to Wei\nconst wei = WeiUtils.fromEth('1');                 // '0xde0b6b3a7640000'\nconst eth = WeiUtils.toEth('0xde0b6b3a7640000');   // '1'\n\n// Format with units\nconst formatted = WeiUtils.format('0xde0b6b3a7640000'); // '1 ETH'\nconst gweiFormatted = WeiUtils.format('0x3b9aca00');     // '1 gwei'\n```\n\n### Validation Utilities\n\n```typescript\nimport { ValidationUtils, TypeGuards } from '@altitrace/sdk';\n\n// Type guards\nif (TypeGuards.isAddress(address)) {\n  // TypeScript knows address is valid\n  console.log('Valid address:', address);\n}\n\n// Validation with exceptions\ntry {\n  ValidationUtils.validateAddress(userInput, 'userAddress');\n  ValidationUtils.validateHexNumber(gasLimit, 'gasLimit');\n} catch (error) {\n  console.log('Validation error:', error.message);\n}\n```\n\n## Constants\n\nThe SDK provides useful constants for common values:\n\n```typescript\nimport { \n  BLOCK_TAGS, \n  GAS_LIMITS, \n  COMMON_ADDRESSES, \n  DEFAULT_CONFIG \n} from '@altitrace/sdk';\n\n// Block tags\nawait client.simulate().call({...}).atBlockTag(BLOCK_TAGS.LATEST);\n\n// Common gas limits\nconst gasLimit = GAS_LIMITS.ERC20_TRANSFER; // '0xD6D8'\n\n// Common addresses\nconst wethAddress = COMMON_ADDRESSES.WETH; // '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'\n```\n\n## Health Monitoring\n\nCheck API health status:\n\n```typescript\ntry {\n  const health = await client.healthCheck();\n  console.log(`API Status: ${health.status}`);\n  console.log(`Version: ${health.version}`);\n  console.log(`Uptime: ${health.uptime}ms`);\n  console.log(`Cache Status: ${health.cache.status}`);\n} catch (error) {\n  console.log('Health check failed:', error.message);\n}\n```\n\n## Best Practices\n\n### 1. Always Handle Errors\n\n```typescript\ntry {\n  const result = await client.simulate().call({...}).execute();\n  // Handle success\n} catch (error) {\n  // Handle specific error types\n  if (error instanceof ValidationError) {\n    // Fix input validation\n  } else if (error instanceof AltitraceApiError) {\n    // Handle API-specific errors\n  }\n}\n```\n\n### 2. Use Type Guards\n\n```typescript\nimport { TypeGuards } from '@altitrace/sdk';\n\nif (TypeGuards.isAddress(userInput)) {\n  // Safe to use as address\n  await client.simulate().call({ to: userInput });\n}\n```\n\n### 3. Leverage Builder Pattern\n\n```typescript\n// Build reusable configurations\nconst baseBuilder = client.simulate()\n  .atBlockTag('latest')\n  .withValidation(true);\n\n// Clone and customize\nconst transferSim = baseBuilder.clone()\n  .call({ to: tokenAddress, data: transferData });\n\nconst approveSim = baseBuilder.clone()\n  .call({ to: tokenAddress, data: approveData });\n```\n\n### 4. Monitor Gas Usage\n\n```typescript\nconst result = await client.simulate().call({...}).execute();\n\nif (result.getTotalGasUsed() > 1_000_000) {\n  console.warn('High gas usage detected');\n}\n\nconst gasBreakdown = ResponseProcessor.extractGasUsage(result);\nif (gasBreakdown.breakdown?.storage.writes > 5) {\n  console.warn('Many storage writes - consider optimization');\n}\n```\n\n## TypeScript Support\n\nThe SDK is built with TypeScript-first design:\n\n- **Strict Type Checking** - No `any` types used\n- **Full IntelliSense** - Complete autocomplete and documentation\n- **Type Guards** - Runtime type checking utilities\n- **Branded Types** - Prevent mixing of address/hex string types\n- **Exact Types** - Precise typing for all API structures\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nbun test\n\n# Run with coverage\nbun test --coverage\n\n# Run specific test file\nbun test validation.test.ts\n```\n\n## Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/altitrace/altitrace.git\ncd altitrace/packages/sdk\n\n# Install dependencies\nbun install\n\n# Generate types from OpenAPI spec\nbun run generate:types\n\n# Build the package\nbun run build\n\n# Run tests\nbun test\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes with tests\n4. Run `bun run lint` and `bun run typecheck`\n5. Submit a pull request\n\n## Support\n\n- 📖 **Documentation**: [docs.altitrace.com](https://docs.altitrace.com)\n- 🐛 **Issues**: [GitHub Issues](https://github.com/altitrace/altitrace/issues)\n- 💬 **Discord**: [Join our community](https://discord.gg/altitrace)\n- 📧 **Email**: support@altitrace.com\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes and version history.","readmeFilename":"README.md","_rev":"1-3f3c6230dd3d28f24e3899feef3f192e"}