@tangram-mover/sdk 0.1.0

package/README.md

@@ -0,0 +1,349 @@
+# Tangram Mover TypeScript SDK
+
+TypeScript SDK for **Tangram Mover** - A comprehensive transaction trace analyzer for Sui Move protocols. Detect smart contract invariant violations, trace transactions, and execute transactions on the Sui network.
+
+## Features
+
+✅ **Transaction Tracing** - Fetch and parse complete transaction traces including PTB commands, balance changes, object changes, and events
+
+✅ **Invariant Detection** - Detect common security violations:
+  - Token inflation/deflation bugs
+  - Access control violations
+  - Ownership transfer anomalies
+  - Balance consistency issues
+
+✅ **Transaction Execution** - Execute transactions using [sui-kit](https://github.com/scallop-io/sui-kit):
+  - Transfer SUI and custom coins
+  - Call Move functions
+  - Transfer objects
+  - HD wallet multi-account support
+
+✅ **Batch Processing** - Process multiple transactions efficiently with rate limiting
+
+## Installation
+
+```bash
+npm install @tangram-mover/sdk @scallop-io/sui-kit
+```
+
+## Quick Start
+
+### Initialize the SDK
+
+```typescript
+import { TangramMover } from '@tangram-mover/sdk';
+
+// Initialize with secret key
+const mover = new TangramMover({
+  secretKey: 'your-secret-key',
+  networkType: 'testnet', // 'mainnet' | 'testnet' | 'devnet'
+});
+
+// Or initialize with mnemonics
+const mover = new TangramMover({
+  mnemonics: 'word1 word2 ... word12',
+  networkType: 'testnet',
+});
+
+// Or create a new HD wallet
+const mover = new TangramMover({
+  networkType: 'testnet',
+});
+```
+
+### Trace a Transaction
+
+```typescript
+// Fetch and parse transaction trace
+const trace = await mover.traceTransaction('transaction-digest-here');
+
+console.log('Transaction:', trace.digest);
+console.log('Sender:', trace.sender);
+console.log('Status:', trace.status);
+console.log('Balance Changes:', trace.balance_changes);
+console.log('PTB Commands:', trace.ptb_commands);
+```
+
+### Analyze for Invariant Violations
+
+```typescript
+// Analyze a single transaction
+const analysis = await mover.analyzeTransaction('transaction-digest-here');
+
+console.log('Status:', analysis.status); // 'safe' | 'violations_detected'
+console.log('Violations:', analysis.summary.violations);
+console.log('Critical Violations:', analysis.summary.critical_violations);
+
+// Check individual invariant results
+analysis.invariants.forEach(inv => {
+  if (inv.violated) {
+    console.log(`⚠️ ${inv.name}: ${inv.message}`);
+  }
+});
+```
+
+### Trace and Analyze in One Call
+
+```typescript
+// Get both trace data and analysis
+const result = await mover.traceAndAnalyze('transaction-digest-here');
+
+console.log('Trace:', result.trace);
+console.log('Analysis:', result.analysis);
+```
+
+### Execute Transactions
+
+```typescript
+// Transfer SUI
+const result = await mover.transferSui('0xrecipient-address', 1000000000); // 1 SUI
+console.log('Transaction Digest:', result.digest);
+
+// Transfer custom coin
+const coinResult = await mover.transferCoin(
+  '0xrecipient-address',
+  1000000,
+  '0xpackage::module::CoinType'
+);
+
+// Call Move function
+const moveResult = await mover.moveCall(
+  '0xpackage::module::function',
+  [arg1, arg2],
+  ['TypeArg1']
+);
+```
+
+### Batch Operations
+
+```typescript
+// Trace multiple transactions
+const traces = await mover.traceTransactions([
+  'digest1',
+  'digest2',
+  'digest3',
+]);
+
+// Analyze multiple transactions
+const analyses = await mover.analyzeTransactions([
+  'digest1',
+  'digest2',
+  'digest3',
+]);
+```
+
+### HD Wallet Multi-Accounts
+
+```typescript
+// Get address for different account indices
+const addr0 = mover.getAddress({ accountIndex: 0 });
+const addr1 = mover.getAddress({ accountIndex: 1 });
+
+// Execute transaction from specific account
+await mover.transferSui('0xrecipient', 1000000, { accountIndex: 1 });
+```
+
+## API Reference
+
+### TangramMover
+
+Main SDK class that provides all functionality.
+
+#### Constructor Options
+
+```typescript
+interface TangramMoverOptions {
+  secretKey?: string;           // Base64, hex, or legacy format key
+  mnemonics?: string;           // 12 or 24 word mnemonic phrase
+  networkType?: NetworkType;    // 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+  fullnodeUrls?: string[];      // Custom fullnode URLs
+  faucetUrl?: string;           // Custom faucet URL
+  accountIndex?: number;        // HD wallet account index (default: 0)
+  rateLimitMs?: number;         // Rate limit between RPC calls (default: 1000)
+}
+```
+
+#### Methods
+
+**Transaction Tracing**
+- `traceTransaction(digest: string): Promise<TraceData>`
+- `traceTransactions(digests: string[]): Promise<TraceData[]>`
+
+**Invariant Analysis**
+- `analyzeTransaction(digest: string): Promise<AnalysisResult>`
+- `analyzeTransactions(digests: string[]): Promise<AnalysisResult[]>`
+- `traceAndAnalyze(digest: string): Promise<TraceAndAnalysisResult>`
+
+**Transaction Execution**
+- `transferSui(recipient: string, amount: number, options?: { accountIndex?: number }): Promise<TransactionResult>`
+- `transferSuiToMany(recipients: string[], amounts: number[], options?: { accountIndex?: number }): Promise<TransactionResult>`
+- `transferCoin(recipient: string, amount: number, coinType: string, options?: { accountIndex?: number }): Promise<TransactionResult>`
+- `transferCoinToMany(recipients: string[], amounts: number[], coinType: string, options?: { accountIndex?: number }): Promise<TransactionResult>`
+- `moveCall(target: string, arguments: any[], typeArguments?: string[], options?: { accountIndex?: number }): Promise<TransactionResult>`
+- `transferObjects(objectIds: string[], recipient: string, options?: { accountIndex?: number }): Promise<TransactionResult>`
+
+**Utilities**
+- `getCurrentAddress(): string`
+- `getAddress(options?: { accountIndex?: number }): string`
+- `getBalance(coinType?: string, options?: { accountIndex?: number }): Promise<{ totalBalance: number }>`
+
+### TraceData
+
+Complete transaction trace information.
+
+```typescript
+interface TraceData {
+  digest: string;
+  sender: string;
+  status: string;
+  gas_computation: number;
+  gas_storage: number;
+  gas_storage_rebate: number;
+  events: SuiEvent[];
+  balance_changes: BalanceChange[];
+  object_changes: ObjectChange[];
+  ptb_commands: PTBCommand[];
+  num_commands: number;
+  num_events: number;
+  num_balance_changes: number;
+  num_object_changes: number;
+  objects_created: number;
+  objects_mutated: number;
+  objects_deleted: number;
+  has_move_calls: boolean;
+  net_balance_change: number | string;
+}
+```
+
+### AnalysisResult
+
+Result of invariant analysis.
+
+```typescript
+interface AnalysisResult {
+  digest: string;
+  timestamp: string;
+  status: 'safe' | 'violations_detected' | 'error';
+  invariants: InvariantResult[];
+  summary: {
+    total_checks: number;
+    violations: number;
+    critical_violations: number;
+  };
+}
+```
+
+## Invariant Checks
+
+The SDK includes several built-in invariant checks:
+
+1. **Inflation Detection** - Detects when tokens are created out of thin air (positive net balance change)
+2. **Access Control** - Basic validation of authorized operations (extendable for protocol-specific checks)
+3. **Ownership Consistency** - Validates object ownership transfers
+4. **Balance Consistency** - Ensures balance changes match object changes
+
+### Adding Custom Invariants
+
+You can extend the analyzer with custom invariant checks:
+
+```typescript
+import { Analyzer } from '@tangram-mover/sdk';
+import type { TraceData } from '@tangram-mover/sdk';
+
+const analyzer = new Analyzer();
+
+// Add custom check
+function checkCustomInvariant(traceData: TraceData): InvariantResult {
+  // Your custom logic here
+  return {
+    name: 'custom_check',
+    violated: false,
+    message: 'Custom check passed',
+  };
+}
+
+// Use in your analysis
+const trace = await mover.traceTransaction('digest');
+const customResult = checkCustomInvariant(trace);
+```
+
+## Examples
+
+### Monitor Protocol Transactions
+
+```typescript
+import { TangramMover } from '@tangram-mover/sdk';
+
+const mover = new TangramMover({ networkType: 'mainnet' });
+
+async function monitorTransaction(digest: string) {
+  const result = await mover.traceAndAnalyze(digest);
+  
+  if (result.analysis.status === 'violations_detected') {
+    console.error('🚨 INVARIANT VIOLATION DETECTED!');
+    console.error('Transaction:', digest);
+    
+    result.analysis.invariants.forEach(inv => {
+      if (inv.violated) {
+        console.error(`  - ${inv.name}: ${inv.message}`);
+        if (inv.severity === 'critical') {
+          // Send alert, pause protocol, etc.
+        }
+      }
+    });
+  } else {
+    console.log('✅ Transaction is safe');
+  }
+}
+```
+
+### Batch Analysis
+
+```typescript
+async function analyzeBatch(digests: string[]) {
+  const analyses = await mover.analyzeTransactions(digests);
+  
+  const violations = analyses.filter(a => a.status === 'violations_detected');
+  const critical = violations.filter(a => 
+    a.summary.critical_violations > 0
+  );
+  
+  console.log(`Analyzed ${digests.length} transactions`);
+  console.log(`Found ${violations.length} with violations`);
+  console.log(`Found ${critical.length} with critical violations`);
+}
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+## Related Projects
+
+- [Tangram Mover Rust Crawler](../crawler/) - High-performance Rust implementation for batch processing
+- [Tangram Mover Python Analyzer](../analysis/) - Python-based invariant detection
+- [sui-kit](https://github.com/scallop-io/sui-kit) - Sui network interaction toolkit
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/src/analyzer/analyzer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Invariant analyzer for transaction traces
+ */
+import type { TraceData } from '../tracer/types';
+import type { AnalysisResult, InvariantResult } from './types';
+/**
+ * Analyzer class for detecting invariant violations
+ */
+export declare class Analyzer {
+    /**
+     * Analyze transaction trace and detect invariant violations
+     */
+    analyze(traceData: TraceData): Promise<AnalysisResult>;
+    /**
+     * Check inflation invariant only
+     */
+    checkInflationInvariant(traceData: TraceData): InvariantResult;
+    /**
+     * Check access control invariant only
+     */
+    checkAccessControlInvariant(traceData: TraceData): InvariantResult;
+    /**
+     * Check ownership invariant only
+     */
+    checkOwnershipInvariant(traceData: TraceData): InvariantResult;
+    /**
+     * Check balance consistency invariant only
+     */
+    checkBalanceConsistencyInvariant(traceData: TraceData): InvariantResult;
+    /**
+     * Analyze multiple transactions
+     */
+    analyzeMultiple(traceDataArray: TraceData[]): Promise<AnalysisResult[]>;
+}
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/src/analyzer/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/analyzer/analyzer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ/D;;GAEG;AACH,qBAAa,QAAQ;IACnB;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAkC5D;;OAEG;IACH,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe;IAI9D;;OAEG;IACH,2BAA2B,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe;IAIlE;;OAEG;IACH,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe;IAI9D;;OAEG;IACH,gCAAgC,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe;IAIvE;;OAEG;IACG,eAAe,CAAC,cAAc,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAG9E"}

package/dist/src/analyzer/analyzer.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Invariant analyzer for transaction traces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analyzer = void 0;
+const invariants_1 = require("./invariants");
+/**
+ * Analyzer class for detecting invariant violations
+ */
+class Analyzer {
+    /**
+     * Analyze transaction trace and detect invariant violations
+     */
+    async analyze(traceData) {
+        const invariants = [];
+        // Run all invariant checks
+        invariants.push((0, invariants_1.checkInflationInvariant)(traceData));
+        invariants.push((0, invariants_1.checkAccessControlInvariant)(traceData));
+        invariants.push((0, invariants_1.checkOwnershipInvariant)(traceData));
+        invariants.push((0, invariants_1.checkBalanceConsistencyInvariant)(traceData));
+        // Calculate summary
+        const violations = invariants.filter(inv => inv.violated);
+        const critical_violations = violations.filter(inv => inv.severity === 'critical').length;
+        // Determine overall status
+        let status = 'safe';
+        if (violations.length > 0) {
+            status = 'violations_detected';
+        }
+        return {
+            digest: traceData.digest,
+            timestamp: new Date().toISOString(),
+            status,
+            invariants,
+            summary: {
+                total_checks: invariants.length,
+                violations: violations.length,
+                critical_violations,
+            },
+        };
+    }
+    /**
+     * Check inflation invariant only
+     */
+    checkInflationInvariant(traceData) {
+        return (0, invariants_1.checkInflationInvariant)(traceData);
+    }
+    /**
+     * Check access control invariant only
+     */
+    checkAccessControlInvariant(traceData) {
+        return (0, invariants_1.checkAccessControlInvariant)(traceData);
+    }
+    /**
+     * Check ownership invariant only
+     */
+    checkOwnershipInvariant(traceData) {
+        return (0, invariants_1.checkOwnershipInvariant)(traceData);
+    }
+    /**
+     * Check balance consistency invariant only
+     */
+    checkBalanceConsistencyInvariant(traceData) {
+        return (0, invariants_1.checkBalanceConsistencyInvariant)(traceData);
+    }
+    /**
+     * Analyze multiple transactions
+     */
+    async analyzeMultiple(traceDataArray) {
+        return Promise.all(traceDataArray.map(trace => this.analyze(trace)));
+    }
+}
+exports.Analyzer = Analyzer;
+//# sourceMappingURL=analyzer.js.map

package/dist/src/analyzer/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","sourceRoot":"","sources":["../../../src/analyzer/analyzer.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAIH,6CAKsB;AAEtB;;GAEG;AACH,MAAa,QAAQ;IACnB;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,SAAoB;QAChC,MAAM,UAAU,GAAsB,EAAE,CAAC;QAEzC,2BAA2B;QAC3B,UAAU,CAAC,IAAI,CAAC,IAAA,oCAAuB,EAAC,SAAS,CAAC,CAAC,CAAC;QACpD,UAAU,CAAC,IAAI,CAAC,IAAA,wCAA2B,EAAC,SAAS,CAAC,CAAC,CAAC;QACxD,UAAU,CAAC,IAAI,CAAC,IAAA,oCAAuB,EAAC,SAAS,CAAC,CAAC,CAAC;QACpD,UAAU,CAAC,IAAI,CAAC,IAAA,6CAAgC,EAAC,SAAS,CAAC,CAAC,CAAC;QAE7D,oBAAoB;QACpB,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1D,MAAM,mBAAmB,GAAG,UAAU,CAAC,MAAM,CAC3C,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,UAAU,CACnC,CAAC,MAAM,CAAC;QAET,2BAA2B;QAC3B,IAAI,MAAM,GAA6C,MAAM,CAAC;QAC9D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,GAAG,qBAAqB,CAAC;QACjC,CAAC;QAED,OAAO;YACL,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM;YACN,UAAU;YACV,OAAO,EAAE;gBACP,YAAY,EAAE,UAAU,CAAC,MAAM;gBAC/B,UAAU,EAAE,UAAU,CAAC,MAAM;gBAC7B,mBAAmB;aACpB;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,SAAoB;QAC1C,OAAO,IAAA,oCAAuB,EAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,2BAA2B,CAAC,SAAoB;QAC9C,OAAO,IAAA,wCAA2B,EAAC,SAAS,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,SAAoB;QAC1C,OAAO,IAAA,oCAAuB,EAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,gCAAgC,CAAC,SAAoB;QACnD,OAAO,IAAA,6CAAgC,EAAC,SAAS,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,cAA2B;QAC/C,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;CACF;AAxED,4BAwEC"}

package/dist/src/analyzer/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Analyzer module exports
+ */
+export { Analyzer } from './analyzer';
+export * from './invariants';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/analyzer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analyzer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}

package/dist/src/analyzer/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Analyzer module exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analyzer = void 0;
+var analyzer_1 = require("./analyzer");
+Object.defineProperty(exports, "Analyzer", { enumerable: true, get: function () { return analyzer_1.Analyzer; } });
+__exportStar(require("./invariants"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/analyzer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analyzer/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,+CAA6B;AAC7B,0CAAwB"}

package/dist/src/analyzer/invariants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Invariant detection logic
+ */
+import type { TraceData } from '../tracer/types';
+import type { InvariantResult } from './types';
+/**
+ * Check for token inflation/deflation violations
+ * Invariant: Sum of balance changes should be <= 0 (excluding mints/burns)
+ */
+export declare function checkInflationInvariant(traceData: TraceData): InvariantResult;
+/**
+ * Check for access control violations
+ * This is a placeholder - actual implementation would need protocol-specific logic
+ */
+export declare function checkAccessControlInvariant(traceData: TraceData): InvariantResult;
+/**
+ * Check for ownership transfer anomalies
+ */
+export declare function checkOwnershipInvariant(traceData: TraceData): InvariantResult;
+/**
+ * Check for balance consistency
+ * Verify that balance changes match object changes
+ */
+export declare function checkBalanceConsistencyInvariant(traceData: TraceData): InvariantResult;
+//# sourceMappingURL=invariants.d.ts.map

package/dist/src/analyzer/invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../../../src/analyzer/invariants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CAuD7E;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CAqBjF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CAgD7E;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CA6BtF"}