@citrate/sdk 0.2.0

package/README.md

@@ -0,0 +1,284 @@
+# Citrate JavaScript/TypeScript SDK
+
+The official JavaScript/TypeScript SDK for the Citrate AI blockchain platform. This SDK provides a comprehensive interface for interacting with Citrate nodes, deploying AI models, managing accounts, and executing transactions.
+
+## Installation
+
+```bash
+npm install @citrate-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CitrateSDK } from '@citrate-ai/sdk';
+
+// Initialize the SDK (JSON-RPC endpoint)
+const sdk = new CitrateSDK({
+  rpcEndpoint: 'http://localhost:8545',
+  chainId: 1337,
+});
+
+// Import an account (enables raw-tx signing)
+const address = sdk.accounts.importAccount('<PRIVATE_KEY_HEX>');
+
+// Get balance
+const balance = await sdk.accounts.getBalance(address);
+console.log(`Balance (wei): ${balance}`);
+
+// List models and run inference
+const ids: string[] = await sdk.models.listModels();
+if (ids.length) {
+  const info = await sdk.models.getModel(ids[0]);
+  console.log('Model:', info);
+  const result = await sdk.models.runInference(ids[0], { text: 'hello lattice' });
+  console.log('Inference:', result);
+}
+```
+
+## Features
+
+### 🔗 Node Connectivity
+- Connect to Citrate nodes via RPC/WebSocket
+- Real-time event listening
+- Automatic reconnection handling
+
+### 🤖 AI Model Management
+- Deploy models to the blockchain
+- Execute model inference
+- Model versioning and metadata
+- IPFS integration for model storage
+
+### 💰 Account Management
+- Wallet integration (MetaMask, WalletConnect)
+- Account creation and import
+- Balance queries
+- Transaction signing
+
+### 🔄 Transaction Management
+- Send transactions
+- Smart contract interaction
+- Gas estimation
+- Transaction status tracking
+
+### 📊 DAG Explorer
+- Query block DAG structure
+- Get block information
+- Explore transaction history
+- Real-time chain updates
+
+## API Reference
+
+### CitrateSDK
+
+Main SDK class that provides access to all functionality.
+
+```typescript
+const sdk = new CitrateSDK({
+  nodeUrl: string,
+  chainId?: number,
+  timeout?: number,
+  retries?: number,
+});
+```
+
+### Models
+
+Model deployment and management.
+
+```typescript
+// Deploy a new model
+await sdk.models.deploy({
+  name: string,
+  description: string,
+  ipfsHash: string,
+  framework: 'pytorch' | 'tensorflow' | 'onnx',
+  version: string,
+  accessType: 'public' | 'private',
+  price?: string,
+});
+
+// Execute model inference
+const result = await sdk.models.execute(modelId, {
+  inputs: any[],
+  outputFormat: 'json' | 'binary',
+});
+
+// Get model information
+const modelInfo = await sdk.models.getInfo(modelId);
+```
+
+### Accounts
+
+Account and wallet management.
+
+```typescript
+// Connect wallet
+await sdk.account.connectWallet();
+
+// Create new account
+const account = await sdk.account.create();
+
+// Get balance
+const balance = await sdk.account.getBalance(address?);
+
+// Send transaction
+const txHash = await sdk.account.sendTransaction({
+  to: string,
+  value: string,
+  data?: string,
+  gasLimit?: number,
+});
+```
+
+### Contracts
+
+Smart contract interaction.
+
+```typescript
+// Deploy contract
+const contractAddress = await sdk.contracts.deploy({
+  bytecode: string,
+  abi: any[],
+  constructorArgs?: any[],
+});
+
+// Call contract method
+const result = await sdk.contracts.call({
+  address: string,
+  abi: any[],
+  method: string,
+  args: any[],
+});
+
+// Send contract transaction
+const txHash = await sdk.contracts.send({
+  address: string,
+  abi: any[],
+  method: string,
+  args: any[],
+  value?: string,
+});
+```
+
+## Advanced Usage
+
+### Event Listening
+
+```typescript
+// Listen for new blocks
+sdk.on('block', (block) => {
+  console.log(`New block: ${block.hash}`);
+});
+
+// Listen for model deployments
+sdk.on('modelDeployed', (event) => {
+  console.log(`Model deployed: ${event.modelId}`);
+});
+
+// Listen for transactions
+sdk.on('transaction', (tx) => {
+  console.log(`Transaction: ${tx.hash}`);
+});
+```
+
+### Custom Providers
+
+```typescript
+import { ethers } from 'ethers';
+
+// Use custom provider
+const provider = new ethers.providers.WebSocketProvider('ws://localhost:8546');
+const sdk = new CitrateSDK({
+  provider,
+  chainId: 1337,
+});
+```
+
+### Batch Operations
+
+```typescript
+// Batch multiple model executions
+const results = await sdk.models.batchExecute([
+  { modelId: 'model1', inputs: [1, 2, 3] },
+  { modelId: 'model2', inputs: [4, 5, 6] },
+]);
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+CITRATE_NODE_URL=http://localhost:8545
+CITRATE_CHAIN_ID=1337
+CITRATE_TIMEOUT=30000
+CITRATE_RETRIES=3
+```
+
+### TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2018",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const ids = await sdk.models.listModels();
+  if (!ids.length) throw new Error('No models registered');
+  const result = await sdk.models.runInference(ids[0], { text: 'hello' });
+  console.log(result.output);
+} catch (e) {
+  console.error('SDK/RPC error:', e);
+}
+```
+
+## Signing Best Practices
+
+- Prefer client-side signing (raw tx) for public/testnet RPCs. Import a private key or mnemonic via `sdk.accounts.importAccount(...)`.
+- In local development, the node can accept `eth_sendTransaction` without a valid signature only if started with `CITRATE_REQUIRE_VALID_SIGNATURE=false`.
+
+## Testing
+
+```bash
+npm test              # Run all tests
+npm run test:unit     # Run unit tests
+npm run test:integration  # Run integration tests
+npm run test:coverage # Run with coverage
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+Apache-2.0 License. See [LICENSE](../../LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](https://docs.citrate.ai)
+- 💬 [Discord Community](https://discord.gg/lattice-ai)
+- 🐛 [Issue Tracker](https://github.com/lattice-ai/citrate/issues)
+- 📧 [Email Support](mailto:support@citrate.ai)
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.

package/dist/account.d.ts

@@ -0,0 +1,59 @@
+import { AxiosInstance } from 'axios';
+import { CitrateConfig } from './types';
+export declare class AccountManager {
+    private rpcClient;
+    private config;
+    private wallet?;
+    constructor(rpcClient: AxiosInstance, config: CitrateConfig);
+    /**
+     * Create a new account
+     */
+    createAccount(): {
+        address: string;
+        privateKey: string;
+        mnemonic?: string;
+    };
+    /**
+     * Import account from private key
+     */
+    importAccount(privateKey: string): string;
+    /**
+     * Import account from mnemonic
+     */
+    importFromMnemonic(mnemonic: string, path?: string): string;
+    /**
+     * Get account balance
+     */
+    getBalance(address?: string): Promise<bigint>;
+    /**
+     * Get account nonce
+     */
+    getNonce(address?: string): Promise<number>;
+    /**
+     * Send transaction
+     */
+    sendTransaction(tx: {
+        to: string;
+        value?: string;
+        data?: string;
+        gasLimit?: number;
+        gasPrice?: string;
+    }): Promise<string>;
+    /**
+     * Sign and send transaction
+     */
+    private sendSignedTransaction;
+    /**
+     * Sign message
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Verify message signature
+     */
+    verifyMessage(message: string, signature: string, address: string): boolean;
+    /**
+     * List accounts (from node)
+     */
+    listAccounts(): Promise<string[]>;
+    private rpcCall;
+}

package/dist/account.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountManager = void 0;
+const ethers_1 = require("ethers");
+class AccountManager {
+    constructor(rpcClient, config) {
+        this.rpcClient = rpcClient;
+        this.config = config;
+    }
+    /**
+     * Create a new account
+     */
+    createAccount() {
+        const wallet = ethers_1.ethers.Wallet.createRandom();
+        return {
+            address: wallet.address,
+            privateKey: wallet.privateKey,
+            mnemonic: wallet.mnemonic?.phrase
+        };
+    }
+    /**
+     * Import account from private key
+     */
+    importAccount(privateKey) {
+        const wallet = new ethers_1.ethers.Wallet(privateKey);
+        this.wallet = wallet;
+        this.config.defaultAccount = wallet.address;
+        return wallet.address;
+    }
+    /**
+     * Import account from mnemonic
+     */
+    importFromMnemonic(mnemonic, path = "m/44'/60'/0'/0/0") {
+        // In ethers v6, fromPhrase already derives the default BIP-44 path internally.
+        // Use fromMnemonic for explicit path control to avoid double-derivation.
+        const mnemonicObj = ethers_1.ethers.Mnemonic.fromPhrase(mnemonic);
+        const wallet = ethers_1.ethers.HDNodeWallet.fromMnemonic(mnemonicObj, path);
+        this.wallet = wallet;
+        this.config.defaultAccount = wallet.address;
+        return wallet.address;
+    }
+    /**
+     * Get account balance
+     */
+    async getBalance(address) {
+        const addr = address || this.config.defaultAccount;
+        if (!addr) {
+            throw new Error('No address specified');
+        }
+        const response = await this.rpcCall('eth_getBalance', [addr, 'latest']);
+        return BigInt(response);
+    }
+    /**
+     * Get account nonce
+     */
+    async getNonce(address) {
+        const addr = address || this.config.defaultAccount;
+        if (!addr) {
+            throw new Error('No address specified');
+        }
+        const response = await this.rpcCall('eth_getTransactionCount', [addr, 'latest']);
+        return parseInt(response, 16);
+    }
+    /**
+     * Send transaction
+     */
+    async sendTransaction(tx) {
+        if (!this.config.defaultAccount) {
+            throw new Error('No default account set');
+        }
+        const nonce = await this.getNonce();
+        const txData = {
+            from: this.config.defaultAccount,
+            to: tx.to,
+            value: tx.value || '0x0',
+            data: tx.data || '0x',
+            gas: `0x${(tx.gasLimit || this.config.gasLimit || 21000).toString(16)}`,
+            gasPrice: tx.gasPrice || this.config.gasPrice || '0x3b9aca00',
+            nonce: `0x${nonce.toString(16)}`
+        };
+        // If we have a wallet, sign the transaction
+        if (this.wallet) {
+            return await this.sendSignedTransaction(txData);
+        }
+        // Otherwise, send unsigned (requires unlocked account on node)
+        return await this.rpcCall('eth_sendTransaction', [txData]);
+    }
+    /**
+     * Sign and send transaction
+     */
+    async sendSignedTransaction(txData) {
+        if (!this.wallet) {
+            throw new Error('No wallet available for signing');
+        }
+        // Create transaction object for ethers
+        const tx = {
+            to: txData.to,
+            value: txData.value,
+            data: txData.data,
+            gasLimit: txData.gas,
+            gasPrice: txData.gasPrice,
+            nonce: parseInt(txData.nonce, 16),
+            chainId: this.config.chainId
+        };
+        // Sign transaction
+        const signedTx = await this.wallet.signTransaction(tx);
+        // Send raw transaction
+        return await this.rpcCall('eth_sendRawTransaction', [signedTx]);
+    }
+    /**
+     * Sign message
+     */
+    async signMessage(message) {
+        if (!this.wallet) {
+            throw new Error('No wallet available for signing');
+        }
+        return await this.wallet.signMessage(message);
+    }
+    /**
+     * Verify message signature
+     */
+    verifyMessage(message, signature, address) {
+        const recoveredAddress = ethers_1.ethers.verifyMessage(message, signature);
+        return recoveredAddress.toLowerCase() === address.toLowerCase();
+    }
+    /**
+     * List accounts (from node)
+     */
+    async listAccounts() {
+        return await this.rpcCall('eth_accounts');
+    }
+    async rpcCall(method, params = []) {
+        const response = await this.rpcClient.post('', {
+            jsonrpc: '2.0',
+            method,
+            params,
+            id: Date.now()
+        });
+        if (response.data.error) {
+            throw new Error(response.data.error.message);
+        }
+        return response.data.result;
+    }
+}
+exports.AccountManager = AccountManager;

package/dist/contract.d.ts

@@ -0,0 +1,67 @@
+import { AxiosInstance } from 'axios';
+import { CitrateConfig, ContractInfo } from './types';
+export declare class ContractManager {
+    private rpcClient;
+    private config;
+    constructor(rpcClient: AxiosInstance, config: CitrateConfig);
+    /**
+     * Deploy a contract
+     */
+    deploy(bytecode: string, abi?: any[], constructorArgs?: any[], value?: string): Promise<string>;
+    /**
+     * Call a contract method (transaction)
+     */
+    call(address: string, abi: any[], method: string, args?: any[], value?: string): Promise<any>;
+    /**
+     * Read contract state (call without transaction)
+     */
+    read(address: string, abi: any[], method: string, args?: any[]): Promise<any>;
+    /**
+     * Get contract code
+     */
+    getCode(address: string): Promise<string>;
+    /**
+     * Get contract info
+     */
+    getContractInfo(address: string): Promise<ContractInfo>;
+    /**
+     * Verify contract source code
+     */
+    verify(address: string, sourceCode: string, compilerVersion: string, optimizationEnabled?: boolean): Promise<string>;
+    /**
+     * Create contract instance with ABI
+     */
+    createInstance(address: string, abi: any[]): ContractInstance;
+    private waitForReceipt;
+    rpcCall(method: string, params: any[]): Promise<any>;
+}
+/**
+ * Contract instance helper class
+ */
+export declare class ContractInstance {
+    address: string;
+    abi: any[];
+    private manager;
+    private iface;
+    constructor(address: string, abi: any[], manager: ContractManager);
+    /**
+     * Call a method (transaction)
+     */
+    send(method: string, args?: any[], value?: string): Promise<any>;
+    /**
+     * Read state (no transaction)
+     */
+    call(method: string, args?: any[]): Promise<any>;
+    /**
+     * Encode method call data
+     */
+    encodeCall(method: string, args?: any[]): string;
+    /**
+     * Decode method result
+     */
+    decodeResult(method: string, data: string): any;
+    /**
+     * Parse event logs
+     */
+    parseLogs(logs: any[]): any[];
+}