@satelink/sdk 0.2.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@satelink/sdk",
+  "version": "0.2.0",
+  "description": "Official SDK for the Satelink DePIN network — RPC, MEV relay, AI inference, and blockchain tools",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./rpc": {
+      "import": "./dist/rpc.js",
+      "types": "./dist/rpc.d.ts"
+    },
+    "./mev": {
+      "import": "./dist/mev.js",
+      "types": "./dist/mev.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/adapters.js",
+      "types": "./dist/adapters.d.ts"
+    },
+    "./ai": {
+      "import": "./dist/ai.js",
+      "types": "./dist/ai.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "echo 'Skipped (TypeScript handles linting)'",
+    "test": "vitest"
+  },
+  "keywords": [
+    "satelink",
+    "depin",
+    "rpc",
+    "ethereum",
+    "polygon",
+    "mev",
+    "flashbots",
+    "blockchain",
+    "ai",
+    "openai",
+    "ethers",
+    "viem",
+    "wagmi"
+  ],
+  "author": "Satelink Network",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Satelink-Protocol/Satelink_Network.git"
+  },
+  "homepage": "https://satelink.network",
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "ethers": ">=5.0.0",
+    "viem": ">=1.0.0",
+    "wagmi": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": { "optional": true },
+    "viem": { "optional": true },
+    "wagmi": { "optional": true }
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,207 @@
+/**
+ * Framework Adapters
+ * L8-002: Drop-in adapters for ethers.js, wagmi, and viem
+ *
+ * Makes Satelink RPC a drop-in replacement for Alchemy/Infura
+ */
+
+const BASE_URL = 'https://rpc.satelink.network';
+
+export const SATELINK_CHAINS = {
+  polygon: { chainId: 137, name: 'Polygon', rpcUrl: `${BASE_URL}/rpc/polygon` },
+  ethereum: { chainId: 1, name: 'Ethereum', rpcUrl: `${BASE_URL}/rpc/ethereum` },
+  arbitrum: { chainId: 42161, name: 'Arbitrum One', rpcUrl: `${BASE_URL}/rpc/arbitrum` },
+  base: { chainId: 8453, name: 'Base', rpcUrl: `${BASE_URL}/rpc/base` },
+  amoy: { chainId: 80002, name: 'Polygon Amoy', rpcUrl: `${BASE_URL}/rpc/amoy` }
+} as const;
+
+export type SatelinkChain = keyof typeof SATELINK_CHAINS;
+
+/**
+ * Get the RPC URL for a chain
+ */
+export function getSatelinkRpcUrl(chain: SatelinkChain = 'polygon', apiKey?: string): string {
+  const config = SATELINK_CHAINS[chain];
+  return apiKey ? `${config.rpcUrl}?apiKey=${apiKey}` : config.rpcUrl;
+}
+
+/**
+ * Create an ethers.js v6 JsonRpcProvider for Satelink
+ *
+ * @example
+ * ```ts
+ * import { getEthersProvider } from '@satelink/sdk';
+ * const provider = getEthersProvider('polygon');
+ * const block = await provider.getBlockNumber();
+ * ```
+ */
+export function getEthersProvider(
+  chain: SatelinkChain = 'polygon',
+  apiKey?: string
+): unknown {
+  const config = SATELINK_CHAINS[chain];
+  const url = config.rpcUrl;
+
+  try {
+    // Try ethers v6 first
+    const { JsonRpcProvider } = require('ethers');
+    const fetchRequest = apiKey ? {
+      url,
+      getUrlFunc: () => url,
+      processFunc: (req: unknown, resp: unknown) => resp,
+      setHeader: (key: string, value: string) => {},
+    } : undefined;
+
+    return new JsonRpcProvider(url, config.chainId, {
+      staticNetwork: true
+    });
+  } catch {
+    try {
+      // Fall back to ethers v5
+      const { providers } = require('ethers');
+      const connection = apiKey
+        ? { url, headers: { 'X-API-Key': apiKey } }
+        : url;
+      return new providers.JsonRpcProvider(connection, config.chainId);
+    } catch {
+      throw new Error(
+        '@satelink/sdk ethers adapter requires ethers ^5.0.0 or ^6.0.0. ' +
+        'Install with: npm install ethers'
+      );
+    }
+  }
+}
+
+/**
+ * Create a viem http transport for Satelink
+ *
+ * @example
+ * ```ts
+ * import { createPublicClient } from 'viem';
+ * import { polygon } from 'viem/chains';
+ * import { getViemTransport } from '@satelink/sdk';
+ *
+ * const client = createPublicClient({
+ *   chain: polygon,
+ *   transport: getViemTransport('polygon'),
+ * });
+ * ```
+ */
+export function getViemTransport(
+  chain: SatelinkChain = 'polygon',
+  apiKey?: string
+): unknown {
+  const config = SATELINK_CHAINS[chain];
+
+  try {
+    const { http } = require('viem');
+    return http(config.rpcUrl, {
+      fetchOptions: apiKey
+        ? { headers: { 'X-API-Key': apiKey } }
+        : undefined,
+      retryCount: 3,
+      retryDelay: 150,
+      timeout: 20000
+    });
+  } catch {
+    throw new Error(
+      '@satelink/sdk viem adapter requires viem ^1.0.0 or ^2.0.0. ' +
+      'Install with: npm install viem'
+    );
+  }
+}
+
+/**
+ * Get a wagmi-compatible chain config for Satelink RPC
+ *
+ * @example
+ * ```ts
+ * import { createConfig, http } from 'wagmi';
+ * import { getSatelinkChainConfig } from '@satelink/sdk';
+ *
+ * const config = createConfig({
+ *   chains: [getSatelinkChainConfig('polygon')],
+ *   transports: { 137: http('https://rpc.satelink.network/rpc/polygon') }
+ * });
+ * ```
+ */
+export function getSatelinkChainConfig(chain: SatelinkChain = 'polygon') {
+  const config = SATELINK_CHAINS[chain];
+
+  return {
+    id: config.chainId,
+    name: config.name,
+    nativeCurrency: getNativeCurrency(chain),
+    rpcUrls: {
+      default: { http: [config.rpcUrl] },
+      public: { http: [config.rpcUrl] }
+    },
+    blockExplorers: getBlockExplorer(chain)
+  };
+}
+
+function getNativeCurrency(chain: SatelinkChain) {
+  switch (chain) {
+    case 'polygon':
+    case 'amoy':
+      return { name: 'MATIC', symbol: 'MATIC', decimals: 18 };
+    case 'ethereum':
+      return { name: 'Ether', symbol: 'ETH', decimals: 18 };
+    case 'arbitrum':
+      return { name: 'Ether', symbol: 'ETH', decimals: 18 };
+    case 'base':
+      return { name: 'Ether', symbol: 'ETH', decimals: 18 };
+    default:
+      return { name: 'Ether', symbol: 'ETH', decimals: 18 };
+  }
+}
+
+function getBlockExplorer(chain: SatelinkChain) {
+  const explorers: Record<SatelinkChain, { default: { name: string; url: string } }> = {
+    polygon: { default: { name: 'Polygonscan', url: 'https://polygonscan.com' } },
+    ethereum: { default: { name: 'Etherscan', url: 'https://etherscan.io' } },
+    arbitrum: { default: { name: 'Arbiscan', url: 'https://arbiscan.io' } },
+    base: { default: { name: 'Basescan', url: 'https://basescan.org' } },
+    amoy: { default: { name: 'Polygonscan Amoy', url: 'https://amoy.polygonscan.com' } }
+  };
+  return explorers[chain];
+}
+
+/**
+ * Raw JSON-RPC call to Satelink (no dependencies)
+ *
+ * @example
+ * ```ts
+ * import { rpc } from '@satelink/sdk';
+ * const blockNumber = await rpc('eth_blockNumber', [], 'polygon');
+ * ```
+ */
+export async function rpc<T = unknown>(
+  method: string,
+  params: unknown[] = [],
+  chain: SatelinkChain = 'polygon',
+  apiKey?: string
+): Promise<T> {
+  const config = SATELINK_CHAINS[chain];
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (apiKey) headers['X-API-Key'] = apiKey;
+
+  const response = await fetch(config.rpcUrl, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method,
+      params
+    })
+  });
+
+  const data = await response.json();
+
+  if (data.error) {
+    throw new Error(`RPC error: ${data.error.message} (code: ${data.error.code})`);
+  }
+
+  return data.result as T;
+}

package/src/ai.ts

@@ -0,0 +1,100 @@
+import type {
+  SatelinkAIOptions,
+  ChatMessage,
+  ChatCompletionOptions,
+  ChatCompletionResponse,
+  Model
+} from './types.js';
+
+const DEFAULT_BASE_URL = 'https://rpc.satelink.network';
+
+export class SatelinkAI {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(options: SatelinkAIOptions) {
+    if (!options.apiKey) {
+      throw new Error('API key is required for SatelinkAI');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private getHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'x-api-key': this.apiKey
+    };
+  }
+
+  async chat(
+    messages: ChatMessage[],
+    options: ChatCompletionOptions = {}
+  ): Promise<ChatCompletionResponse> {
+    const body = {
+      model: options.model || 'satelink-default',
+      messages,
+      max_tokens: options.max_tokens || 1000,
+      temperature: options.temperature,
+      stream: false
+    };
+
+    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(
+        `AI request failed: ${response.status} - ${error.error?.message || response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  async complete(prompt: string, options: ChatCompletionOptions = {}): Promise<string> {
+    const body = {
+      model: options.model || 'satelink-default',
+      prompt,
+      max_tokens: options.max_tokens || 100,
+      temperature: options.temperature
+    };
+
+    const response = await fetch(`${this.baseUrl}/v1/completions`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(
+        `AI request failed: ${response.status} - ${error.error?.message || response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+    return data.choices?.[0]?.text || '';
+  }
+
+  async getModels(): Promise<Model[]> {
+    const response = await fetch(`${this.baseUrl}/v1/models`, {
+      method: 'GET',
+      headers: this.getHeaders()
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch models: ${response.status}`);
+    }
+
+    const data = await response.json();
+    return data.data || [];
+  }
+
+  get models(): Promise<Model[]> {
+    return this.getModels();
+  }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// Core RPC client
+export { SatelinkRPC, createProvider } from './rpc.js';
+
+// EIP-1193 Provider
+export { SatelinkProvider, createSatelinkProvider } from './provider.js';
+
+// AI inference client
+export { SatelinkAI } from './ai.js';
+
+// MEV relay client
+export { SatelinkMEV, createMevClient } from './mev.js';
+
+// Framework adapters (ethers.js, viem, wagmi)
+export {
+  SATELINK_CHAINS,
+  getSatelinkRpcUrl,
+  getEthersProvider,
+  getViemTransport,
+  getSatelinkChainConfig,
+  rpc
+} from './adapters.js';
+
+// Types
+export type {
+  SatelinkRPCOptions,
+  SatelinkAIOptions,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  ChatMessage,
+  ChatCompletionOptions,
+  ChatCompletionResponse,
+  Model,
+  TransactionRequest
+} from './types.js';
+export type { EIP1193Provider } from './rpc.js';
+export type { SatelinkProviderOptions } from './provider.js';
+export type { SatelinkChain } from './adapters.js';
+export type {
+  MevClientOptions,
+  MevSubmitResult,
+  MevSimulationResult,
+  MevBundleStatus
+} from './mev.js';

package/src/mev.ts

@@ -0,0 +1,213 @@
+/**
+ * MEV Relay Client
+ * L8-002: Satelink MEV private relay for searchers
+ *
+ * Features:
+ * - Private transaction submission
+ * - Bundle submission (Flashbots-compatible)
+ * - Bundle simulation (eth_callBundle)
+ * - Bundle status tracking
+ */
+
+export interface MevSubmitResult {
+  ok: boolean;
+  txHash?: string;
+  bundleHash?: string;
+  provider?: string;
+  requestId?: string;
+  priceUsdt?: number;
+  error?: string;
+}
+
+export interface MevSimulationResult {
+  ok: boolean;
+  simulation?: {
+    bundleHash?: string;
+    coinbaseDiff?: string;
+    ethSentToCoinbase?: string;
+    gasFees?: string;
+    totalGasUsed?: number;
+    results?: unknown[];
+  };
+  profitable?: boolean;
+  latency_ms?: number;
+  fee_usdt?: number;
+  error?: string;
+  requestId?: string;
+}
+
+export interface MevBundleStatus {
+  ok: boolean;
+  bundleHash: string;
+  status: 'pending' | 'pending_high_priority' | 'not_found' | 'unknown';
+  stats?: {
+    isSimulated?: boolean;
+    isSentToMiners?: boolean;
+    isHighPriority?: boolean;
+    simulatedAt?: string;
+    submittedAt?: string;
+    sentToMinersAt?: string;
+  };
+  fee_usdt?: number;
+  error?: string;
+}
+
+export interface MevClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  chain?: 'ethereum' | 'polygon' | 'arbitrum';
+}
+
+const DEFAULT_BASE_URL = 'https://rpc.satelink.network';
+
+export class SatelinkMEV {
+  private apiKey: string;
+  private baseUrl: string;
+  private chain: string;
+
+  constructor(options: MevClientOptions) {
+    if (!options.apiKey) {
+      throw new Error('MEV relay requires an API key');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.chain = options.chain || 'ethereum';
+  }
+
+  private getHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'X-API-Key': this.apiKey
+    };
+  }
+
+  /**
+   * Submit a signed transaction to the private mempool
+   * Transaction is NOT broadcast publicly — goes directly to validators
+   */
+  async submitPrivateTransaction(signedTx: string): Promise<MevSubmitResult> {
+    const response = await fetch(`${this.baseUrl}/rpc/mev?chain=${this.chain}`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: Date.now(),
+        method: 'eth_sendRawTransaction',
+        params: [signedTx]
+      })
+    });
+
+    const data = await response.json();
+
+    if (data.error) {
+      return { ok: false, error: data.error.message || data.error };
+    }
+
+    return {
+      ok: true,
+      txHash: data.result,
+      provider: data._mev?.provider,
+      requestId: data._mev?.requestId,
+      priceUsdt: data._mev?.priceUsdt
+    };
+  }
+
+  /**
+   * Submit a bundle of transactions (Flashbots-compatible)
+   * All transactions execute atomically or none do
+   */
+  async submitBundle(
+    txs: string[],
+    options: {
+      blockNumber?: string | number;
+      minTimestamp?: number;
+      maxTimestamp?: number;
+    } = {}
+  ): Promise<MevSubmitResult> {
+    const response = await fetch(`${this.baseUrl}/rpc/mev/bundle?chain=${this.chain}`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify({
+        txs,
+        blockNumber: options.blockNumber,
+        minTimestamp: options.minTimestamp,
+        maxTimestamp: options.maxTimestamp
+      })
+    });
+
+    const data = await response.json();
+
+    if (!data.ok) {
+      return { ok: false, error: data.error || data.message };
+    }
+
+    return {
+      ok: true,
+      bundleHash: data.bundleHash,
+      provider: data.provider,
+      requestId: data.requestId,
+      priceUsdt: data.priceUsdt
+    };
+  }
+
+  /**
+   * Simulate a bundle without submitting (eth_callBundle)
+   * Use this to check profitability before paying for submission
+   */
+  async simulateBundle(
+    txs: string[],
+    options: {
+      blockNumber?: string;
+      stateBlockNumber?: string;
+    } = {}
+  ): Promise<MevSimulationResult> {
+    const response = await fetch(`${this.baseUrl}/rpc/mev/bundle/simulate`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify({
+        txs,
+        blockNumber: options.blockNumber,
+        stateBlockNumber: options.stateBlockNumber
+      })
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Check if a bundle was included on-chain
+   */
+  async getBundleStatus(bundleHash: string, blockNumber?: string): Promise<MevBundleStatus> {
+    const url = new URL(`${this.baseUrl}/rpc/mev/bundle/${bundleHash}`);
+    if (blockNumber) url.searchParams.set('blockNumber', blockNumber);
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers: this.getHeaders()
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Get MEV relay status and stats
+   */
+  async getStatus(): Promise<unknown> {
+    const response = await fetch(`${this.baseUrl}/rpc/mev/status`);
+    return response.json();
+  }
+
+  /**
+   * Set the target chain for MEV operations
+   */
+  setChain(chain: 'ethereum' | 'polygon' | 'arbitrum'): void {
+    this.chain = chain;
+  }
+}
+
+/**
+ * Create a Satelink MEV client
+ */
+export function createMevClient(options: MevClientOptions): SatelinkMEV {
+  return new SatelinkMEV(options);
+}