m2m-sentinel-sdk 1.1.1 → 1.2.0

package/README.md

@@ -1,61 +1,146 @@
-# M2M Sentinel SDK
+# M2M Sentinel SDKs
+
+Production API Base URL: `https://api.m2msentinel.com` (with fallback `https://m2msentinel.com`).
+
+Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography; transaction middleware requires a caller-defined policy and has no built-in decision threshold.
+
+---
+
+## 🏗️ Recommended Defense-in-Depth Pipeline for Agents
+
+Autonomous agents handling value must never rely on a single oracle or heuristic. M2M Sentinel can supply static observations as Layer 1 of a caller-owned pipeline:
+
+```text
+[Agent Intent] 
+       │
+       ▼
+[Transaction Builder]
+       │
+       ▼
+[Stage 1: M2M Sentinel Observation] ── (Bytecode hash, proxy target, selected opcode/selector evidence)
+       │
+       ▼
+[Stage 2: Local Policy Engine]    ── (Caller-defined rules: Check spending bounds, reject DELEGATECALL, verify allowlist)
+       │
+       ▼
+[Stage 3: Execution Simulation]   ── (eth_call / Tenderly / Trace state simulation)
+       │
+       ▼
+[Stage 4: Sub-Wallet Signing]     ── (Scoped ephemeral wallet signs & broadcasts on Base)
+```
 
-Official multi-language client libraries for M2M Sentinel — the pre-transaction capability evidence layer for Base agents.
+---
 
-[![npm version](https://img.shields.io/npm/v/m2m-sentinel-sdk.svg)](https://www.npmjs.com/package/m2m-sentinel-sdk)
-[![PyPI version](https://img.shields.io/pypi/v/m2m-sentinel.svg)](https://pypi.org/project/m2m-sentinel/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+## Installation
 
-M2M Sentinel provides proxy-aware contract capability observations, implementation slot resolution, gas metrics, DEX liquidity telemetry, and whale signals for autonomous agents operating on Base.
+### JavaScript / TypeScript (npm)
 
-## Installation
+```bash
+# Scoped package (recommended)
+npm install @m2msentinel/sdk
+
+# Or unscoped package
+npm install m2m-sentinel-sdk@1.2.0
+```
+
+### Python (PyPI)
 
-### JavaScript / TypeScript (Node.js)
 ```bash
-npm install m2m-sentinel-sdk
+pip install m2m-sentinel==1.2.0
 ```
 
-### Python
+### MCP Server (Model Context Protocol)
+
 ```bash
-pip install m2m-sentinel
+npx -y @m2msentinel/sdk
+# or
+npx -y m2m-sentinel-sdk
 ```
 
-## Quick Start
+---
+
+## Quickstart: JavaScript / TypeScript
 
-### Node.js / TypeScript
 ```javascript
-const { M2MSentinelClient } = require('m2m-sentinel-sdk');
+const { M2MSentinelClient, X402SignerClient } = require('@m2msentinel/sdk');
 
+// 1. Standard API Client (Header Authentication)
 const client = new M2MSentinelClient({
-  apiKey: process.env.M2M_SENTINEL_API_KEY
+  apiKey: process.env.M2M_SENTINEL_API_KEY,
+  baseUrl: 'https://api.m2msentinel.com'
 });
 
-async function main() {
-  const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
-  console.log('Contract Type:', audit.data.bytecodeAnalysis.contractType);
-  console.log('Proxy Detected:', audit.data.proxyDetection.isProxy);
-  console.log('Capabilities:', audit.data.bytecodeAnalysis.detectedCapabilities);
-}
+// Inspect contract capabilities before transaction
+const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+console.log('Contract capabilities:', audit.audit.verdict.executableCapabilities);
+console.log('Capability evidence:', audit.audit.dissection.capabilities);
+console.log('Proxy Target:', audit.audit.proxyResolution.targetAddress);
+console.log('Reachability:', audit.audit.reachability || 'NOT_ESTABLISHED');
+
+// 2. Autonomous Headless x402 Micropayments (EIP-3009 Local Signing)
+const x402Client = new X402SignerClient({
+  walletSigner: myAgentWallet, // ethers / viem signer
+  baseUrl: 'https://api.m2msentinel.com',
+  maxPriceUsd: 0.01 // Optional: strict spending limit (default $0.05)
+});
 
-main().catch(console.error);
+const res = await x402Client.fetchWithAutoPayment('/v1/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+console.log('Paid analysis result:', res.json);
 ```
 
-### Python
-```python
-from m2m_sentinel import M2MSentinelClient
+---
+
+## 🛡️ Autonomous Wallet Policy & Security Boundaries
+
+To prevent autonomous AI agents from blindly signing arbitrary or spoofed HTTP 402 challenges from untrusted sources, `X402SignerClient` enforces **4 strict client-side invariants** locally before generating any cryptographic signature:
+
+| Client Invariant | Enforced Value | Security Protection |
+| :--- | :--- | :--- |
+| **Chain ID** | `8453` (Base Mainnet) | Rejects signing on any unapproved EVM chain. |
+| **Asset Contract** | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Rejects signing for unapproved tokens (Base USDC only). |
+| **Payout Recipient** | `0x6d6c398390cfb88f1cd42715b84906a0bd6652aa` | Rejects signing payments to unexpected recipient addresses. |
+| **Price Ceiling** | `maxPriceUsd` (Default: `$0.05`) | Throws if remote challenge requests funds exceeding caller's authorized ceiling. |
 
-client = M2MSentinelClient(api_key="your_api_key")
-audit = client.audit_contract("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
-print("Contract Type:", audit["data"]["bytecodeAnalysis"]["contractType"])
+```javascript
+import { X402SignerClient } from '@m2msentinel/sdk';
+
+// Fully policy-constrained autonomous signer with immutable recipient & domain constants
+const signer = new X402SignerClient({
+  wallet: agentWallet,
+  maxPriceUsd: 0.005 // Strict spending limit: 0.5 cents max per decision (default $0.05)
+});
 ```
 
-## Model Context Protocol (MCP) Server
+---
 
-M2M Sentinel includes a full Model Context Protocol (MCP) server supporting stdio and HTTP/SSE streams.
+## Authentication and x402
 
-```bash
-node mcp_server.js
+Send API keys only in `x-api-key` (or `Authorization: Bearer`). Query-string credentials are rejected with HTTP 401. Payable routes also support x402 v2 on Base USDC. An unpaid call returns a base64 `PAYMENT-REQUIRED` challenge; a successful settlement returns `PAYMENT-RESPONSE`.
+
+---
+
+## Public Routes
+
+- `GET /v1/status`
+- `GET /v1/stats` (public privacy envelope; exact aggregate commercial counters are operator-only)
+- `GET /v1/plans`
+- `GET /v1/demo/audit/:address` for the published sample allowlist
+- `GET /v1/audit/:address` (requires API key or x402 payment)
+
+The JavaScript, TypeScript, and Python clients expose multi-period purchase/renewal and wallet recovery without requiring callers to hand-build requests:
+
+```javascript
+await client.createSubscriptionIntent('GROWTH', wallet, {
+  durationDays: 90,
+  renewExistingKey: true,
+  apiKey: existingPaidKey
+});
+const challenge = await client.createRecoveryChallenge(wallet, { txHash });
+await client.claimRecoveredKey(challenge.intent.id, walletSignature);
 ```
 
-## License
-MIT License. Copyright (c) 2026 M2M Sentinel.
+---
+
+## Disclaimer & Limitations
+
+Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography.

package/agent_adapter.js

@@ -13,6 +13,31 @@ const http = require('http');
 const DEFAULT_BASE_URL = process.env.M2M_SENTINEL_BASE_URL || 'https://api.m2msentinel.com';
 const DEFAULT_TIMEOUT_MS = Number(process.env.M2M_SENTINEL_TIMEOUT_MS || 30000);
 
+function summarizeAuditResponse(body, requestedAddress) {
+  const audit = body && body.audit ? body.audit : {};
+  const proxy = audit.proxyResolution || {};
+  const capabilities = Array.isArray(audit.verdict && audit.verdict.executableCapabilities)
+    ? audit.verdict.executableCapabilities
+    : (audit.dissection && Array.isArray(audit.dissection.capabilities)
+        ? audit.dissection.capabilities
+          .map((item) => typeof item === 'string' ? item : item && item.type)
+          .filter(Boolean)
+        : []);
+
+  return {
+    address: audit.address || requestedAddress,
+    isContract: Boolean(audit.dissection && audit.dissection.isValidContract),
+    isProxy: Boolean(proxy.isProxy),
+    proxyType: proxy.proxyType || 'NONE',
+    targetAddress: proxy.targetAddress || null,
+    executableCapabilities: capabilities,
+    reachability: audit.reachability || 'NOT_ESTABLISHED',
+    trustLevel: audit.provenance && audit.provenance.trustLevel
+      ? audit.provenance.trustLevel
+      : 'NOT_REPORTED'
+  };
+}
+
 class M2MSentinelActionProvider {
   constructor(options = {}) {
     this.name = 'm2m_sentinel';
@@ -42,7 +67,7 @@ class M2MSentinelActionProvider {
 
     const headers = {
       Accept: 'application/json',
-      'User-Agent': 'M2MSentinel-AgentKit/1.1.1',
+      'User-Agent': 'M2MSentinel-AgentKit/1.2.0',
       ...options.headers
     };
     if (this.apiKey && !headers['x-api-key']) {
@@ -98,11 +123,13 @@ class M2MSentinelActionProvider {
       });
     }
 
+    const observation = summarizeAuditResponse(res.body, address);
     return JSON.stringify({
       status: 'SUCCESS',
       data: res.body,
       notASafetyGuarantee: true,
-      observationSummary: `Contract ${address}: Type=${res.body.bytecodeAnalysis?.contractType || 'UNKNOWN'}, isProxy=${Boolean(res.body.proxyDetection?.isProxy)}`
+      observation,
+      observationSummary: `Contract ${observation.address}: isContract=${observation.isContract}, isProxy=${observation.isProxy}, proxyTarget=${observation.targetAddress || 'UNRESOLVED'}, capabilities=${observation.executableCapabilities.join(',') || 'NONE_OBSERVED'}, reachability=${observation.reachability}`
     });
   }
 
@@ -134,6 +161,24 @@ class M2MSentinelActionProvider {
     return JSON.stringify(res.body);
   }
 
+  async getDexLiquidity(args = {}) {
+    const pair = String(args.pair || 'WETH-USDC').trim();
+    const res = await this._queryApi(`/v1/dex/metrics?pair=${encodeURIComponent(pair)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve DEX liquidity' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getWhaleSignals(args = {}) {
+    const limit = Number(args.limit || 10);
+    const res = await this._queryApi(`/v1/whales/signals?limit=${encodeURIComponent(limit)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve whale signals' });
+    }
+    return JSON.stringify(res.body);
+  }
+
   getActions(_walletProvider) {
     return [
       {
@@ -175,6 +220,34 @@ class M2MSentinelActionProvider {
         },
         invoke: (args) => this.getTokenPrice(args)
       },
+      {
+        name: 'm2m_get_dex_liquidity',
+        description: 'Get tracked Base DEX pool reserve and liquidity metrics.',
+        schema: {
+          type: 'object',
+          properties: {
+            pair: {
+              type: 'string',
+              description: 'DEX pair identifier (e.g. WETH-USDC)'
+            }
+          }
+        },
+        invoke: (args) => this.getDexLiquidity(args)
+      },
+      {
+        name: 'm2m_get_whale_signals',
+        description: 'Get tracked Base whale transfer and concentration signals.',
+        schema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum signals to retrieve (1-50)'
+            }
+          }
+        },
+        invoke: (args) => this.getWhaleSignals(args)
+      },
       {
         name: 'm2m_get_service_status',
         description: 'Check operational status of M2M Sentinel upstream verification rails.',
@@ -198,5 +271,6 @@ class M2MSentinelAgentTool extends M2MSentinelActionProvider {}
 module.exports = {
   M2MSentinelActionProvider,
   m2mSentinelActionProvider,
-  M2MSentinelAgentTool
+  M2MSentinelAgentTool,
+  summarizeAuditResponse
 };

package/eliza_plugin.js

@@ -1,4 +1,9 @@
-// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+/**
+ * M2M Sentinel ElizaOS Production Adapter Plugin
+ * 
+ * Provides automated pre-transaction contract capability preflight and proxy inspection
+ * actions for autonomous agents running on the ElizaOS runtime framework.
+ */
 
 const { M2MSentinelClient } = require('./index.js');
 
@@ -81,4 +86,4 @@ const m2mSentinelPlugin = {
   ]
 };
 
-module.exports = { m2mSentinelPlugin };
+module.exports = { m2mSentinelPlugin };

package/index.d.ts

@@ -1,94 +1,113 @@
-export interface M2MSentinelClientOptions {
-  apiKey?: string;
-  baseUrl?: string;
-  timeoutMs?: number;
-  paymentSignature?: string;
-}
-
-export interface CreateSubscriptionIntentOptions extends M2MSentinelClientOptions {
-  durationDays?: 31 | 90 | 365;
-  renewExistingKey?: boolean;
-}
-
-export interface RecoveryChallengeOptions {
-  txHash?: string;
-}
-
-export interface M2MSentinelErrorOptions {
-  status?: number;
-  body?: unknown;
-  retryAfter?: string | null;
-  paymentRequired?: unknown;
-  paymentResponse?: unknown;
-}
-
-export class M2MSentinelError extends Error {
-  readonly status?: number;
-  readonly body?: unknown;
-  readonly retryAfter?: string | null;
-  readonly paymentRequired?: unknown;
-  readonly paymentResponse?: unknown;
-  constructor(message: string, options?: M2MSentinelErrorOptions);
-}
-
-export class PaymentRequiredError extends M2MSentinelError {}
-export class RateLimitedError extends M2MSentinelError {}
-export class DataSourceUnavailableError extends M2MSentinelError {}
-
-export class M2MSentinelClient {
-  constructor(options?: M2MSentinelClientOptions);
-  constructor(apiKey?: string, baseUrl?: string);
-  request(method: string, path: string, body?: unknown, options?: M2MSentinelClientOptions): Promise<any>;
-  getStatus(): Promise<any>;
-  getPublicStats(days?: number): Promise<any>;
-  /** Backward-compatible alias for getPublicStats; customer keys never reveal operator counters. */
-  getAggregateStats(days?: number): Promise<any>;
-  getOperatorAggregateStats(days: number, operatorToken: string): Promise<any>;
-  getPlans(): Promise<any>;
-  demoAudit(address: string): Promise<any>;
-  createFreeChallenge(userWallet: string): Promise<any>;
-  claimFreeTier(intentId: string, signature: string): Promise<any>;
-  createSubscriptionIntent(tier: string, userWallet: string, options?: CreateSubscriptionIntentOptions): Promise<any>;
-  claimSubscription(intentId: string, signature: string, txHash: string): Promise<any>;
-  createRecoveryChallenge(userWallet: string, options?: RecoveryChallengeOptions): Promise<any>;
-  claimRecoveredKey(intentId: string, signature: string): Promise<any>;
-  auditContract(address: string, options?: M2MSentinelClientOptions): Promise<any>;
-  getCapabilityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
-  /** Legacy alias. The response is a capability coverage index, not a safety score. */
-  getSecurityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
-  getGasFees(options?: M2MSentinelClientOptions): Promise<any>;
-  getDexMetrics(options?: M2MSentinelClientOptions): Promise<any>;
-  getTokenPrice(symbol: string, options?: M2MSentinelClientOptions): Promise<any>;
-  getWhaleSignals(options?: M2MSentinelClientOptions): Promise<any>;
-  getKeySelf(): Promise<any>;
-  revokeKey(confirm?: boolean): Promise<any>;
-}
-
-export type SentinelPolicy = (
-  analysis: any,
-  context: { targetAddress: string; integration: string }
-) => boolean | { allow: boolean; reason?: string } | Promise<boolean | { allow: boolean; reason?: string }>;
-
-export function enforceCallerPolicy(
-  policy: SentinelPolicy | undefined,
-  analysis: any,
-  context: { targetAddress: string; integration: string }
-): Promise<void>;
-
-export function createEthersSentinelMiddleware(
-  apiKey?: string,
-  baseUrl?: string,
-  policy?: SentinelPolicy
-): {
-  client: M2MSentinelClient;
-  verifyContractBeforeTx(targetAddress: string, policyOverride?: SentinelPolicy): Promise<any>;
-};
-
-export function createViemSentinelInterceptor(
-  apiKey?: string,
-  baseUrl?: string,
-  policy?: SentinelPolicy
-): {
-  client: M2MSentinelClient;
-  inspectSwapTarget(address: string, policyOverride?: SentinelPolicy): Promise<any>;
-};
+export interface M2MSentinelClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  paymentSignature?: string;
+}
+
+export interface CreateSubscriptionIntentOptions extends M2MSentinelClientOptions {
+  durationDays?: 31 | 90 | 365;
+  renewExistingKey?: boolean;
+}
+
+export interface RecoveryChallengeOptions {
+  txHash?: string;
+}
+
+export interface M2MSentinelErrorOptions {
+  status?: number;
+  body?: unknown;
+  retryAfter?: string | null;
+  paymentRequired?: unknown;
+  paymentResponse?: unknown;
+}
+
+export class M2MSentinelError extends Error {
+  readonly status?: number;
+  readonly body?: unknown;
+  readonly retryAfter?: string | null;
+  readonly paymentRequired?: unknown;
+  readonly paymentResponse?: unknown;
+  constructor(message: string, options?: M2MSentinelErrorOptions);
+}
+
+export class PaymentRequiredError extends M2MSentinelError {}
+export class RateLimitedError extends M2MSentinelError {}
+export class DataSourceUnavailableError extends M2MSentinelError {}
+
+export class M2MSentinelClient {
+  constructor(options?: M2MSentinelClientOptions);
+  constructor(apiKey?: string, baseUrl?: string);
+  request(method: string, path: string, body?: unknown, options?: M2MSentinelClientOptions): Promise<any>;
+  getStatus(): Promise<any>;
+  getPublicStats(days?: number): Promise<any>;
+  /** Backward-compatible alias for getPublicStats; customer keys never reveal operator counters. */
+  getAggregateStats(days?: number): Promise<any>;
+  getOperatorAggregateStats(days: number, operatorToken: string): Promise<any>;
+  getPlans(): Promise<any>;
+  demoAudit(address: string): Promise<any>;
+  createFreeChallenge(userWallet: string): Promise<any>;
+  claimFreeTier(intentId: string, signature: string): Promise<any>;
+  createSubscriptionIntent(tier: string, userWallet: string, options?: CreateSubscriptionIntentOptions): Promise<any>;
+  claimSubscription(intentId: string, signature: string, txHash: string): Promise<any>;
+  createRecoveryChallenge(userWallet: string, options?: RecoveryChallengeOptions): Promise<any>;
+  claimRecoveredKey(intentId: string, signature: string): Promise<any>;
+  auditContract(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getCapabilityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  /** Legacy alias. The response is a capability coverage index, not a safety score. */
+  getSecurityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getGasFees(options?: M2MSentinelClientOptions): Promise<any>;
+  getDexMetrics(options?: M2MSentinelClientOptions): Promise<any>;
+  getTokenPrice(symbol: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getWhaleSignals(options?: M2MSentinelClientOptions): Promise<any>;
+  getKeySelf(): Promise<any>;
+  revokeKey(confirm?: boolean): Promise<any>;
+}
+
+export type SentinelPolicy = (
+  analysis: any,
+  context: { targetAddress: string; integration: string }
+) => boolean | { allow: boolean; reason?: string } | Promise<boolean | { allow: boolean; reason?: string }>;
+
+export function enforceCallerPolicy(
+  policy: SentinelPolicy | undefined,
+  analysis: any,
+  context: { targetAddress: string; integration: string }
+): Promise<void>;
+
+export function createEthersSentinelMiddleware(
+  apiKey?: string,
+  baseUrl?: string,
+  policy?: SentinelPolicy
+): {
+  client: M2MSentinelClient;
+  verifyContractBeforeTx(targetAddress: string, policyOverride?: SentinelPolicy): Promise<any>;
+};
+
+export function createViemSentinelInterceptor(
+  apiKey?: string,
+  baseUrl?: string,
+  policy?: SentinelPolicy
+): {
+  client: M2MSentinelClient;
+  inspectSwapTarget(address: string, policyOverride?: SentinelPolicy): Promise<any>;
+};
+
+export interface X402SignerClientOptions {
+  wallet?: any;
+  walletSigner?: any;
+  privateKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+
+export class X402SignerClient {
+  constructor(options?: X402SignerClientOptions);
+  signPaymentAuthorization(challenge: any): Promise<any>;
+  fetchWithAutoPayment(path: string, options?: any): Promise<any>;
+}
+
+export function x402SignerClient(options?: X402SignerClientOptions): X402SignerClient;
+export function parsePaymentHeader(value: string | object | null): any;
+export function parsePriceToUnits(priceStr: string | number, decimals?: number): bigint;
+