m2m-sentinel-sdk 1.0.4 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M2M Sentinel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,59 +1,61 @@
-# M2M Sentinel SDKs
+# M2M Sentinel SDK
 
-Base URL: `https://m2msentinel.vercel.app`.
+Official multi-language client libraries for M2M Sentinel — the pre-transaction capability evidence layer for Base agents.
 
-## Support status
+[![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)
 
-Supported in this repository:
-- JavaScript/Node: `public/sdk/index.js` (`m2m_sentinel_sdk.js` re-exports it)
-- TypeScript source: `public/sdk/typescript/index.ts`
-- Python source: `public/sdk/m2m_sentinel/` and `public/sdk/python/m2m_sentinel/`
-- MCP stdio server: `public/sdk/mcp_server.js`
-
-Community preview only: Go, Rust, Java, Kotlin, Swift, C#, PHP, Ruby, CLI, Eliza plugin, and agent adapter. They include current route/header examples but are not covered by the supported-SDK guarantee; verify against `/openapi.json` before production use.
+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.
 
 ## Installation
 
-Install from source (recommended for current `v1.0.4` build):
-
+### JavaScript / TypeScript (Node.js)
 ```bash
-# JavaScript / Node.js (local path)
-node -e "const { M2MSentinelClient } = require('./public/sdk')"
-
-# Python (local path)
-python -m pip install ./public/sdk/python
+npm install m2m-sentinel-sdk
 ```
 
-*Note on Registry Packages (`v1.0.4`)*:
-Once published to npm and PyPI (via `npm publish` and `twine upload`), install directly via the package manager:
-- **npm registry**: `m2m-sentinel-sdk`
-- **PyPI registry**: `m2m-sentinel`
+### Python
+```bash
+pip install m2m-sentinel
+```
 
-## Authentication
+## Quick Start
 
-API keys must be sent only in headers:
+### Node.js / TypeScript
+```javascript
+const { M2MSentinelClient } = require('m2m-sentinel-sdk');
 
-```text
-x-api-key: <key>
-```
+const client = new M2MSentinelClient({
+  apiKey: process.env.M2M_SENTINEL_API_KEY
+});
 
-`Authorization: Bearer <key>` is accepted by the API, but the supported SDKs use `x-api-key`. Never place credentials in URLs or query strings; the server rejects them with HTTP 401.
+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);
+}
 
-## x402 / 402 behavior
-
-Paid endpoints accept either `x-api-key` or a settled x402 v2 payment. Without credentials they return HTTP 402 and a `PAYMENT-REQUIRED` header containing a JSON challenge. Supported SDKs raise/return a payment-required error that exposes the parsed challenge. After settlement, retry with `PAYMENT-SIGNATURE`; successful paid responses may include `PAYMENT-RESPONSE` and include `provenance` in the JSON body.
+main().catch(console.error);
+```
 
-## Free-tier signup
+### Python
+```python
+from m2m_sentinel import M2MSentinelClient
 
-1. `POST /v1/subscribe/free/challenge` with `{ "userWallet": "0x..." }`.
-2. Sign `intent.messageToSign` with that wallet.
-3. `POST /v1/subscribe/free/claim` with `{ "intentId": "...", "signature": "..." }`.
-4. Store the returned `apiKey`; it cannot be recovered later.
+client = M2MSentinelClient(api_key="your_api_key")
+audit = client.audit_contract("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
+print("Contract Type:", audit["data"]["bytecodeAnalysis"]["contractType"])
+```
 
-## Current routes
+## Model Context Protocol (MCP) Server
 
-Public: `GET /v1/status`, `GET /v1/plans`, free signup, and subscription intent/claim routes.
+M2M Sentinel includes a full Model Context Protocol (MCP) server supporting stdio and HTTP/SSE streams.
 
-Protected/paid: `GET /v1/audit/:address`, `GET /v1/security/score/:address`, `GET /v1/gas/fees`, `GET /v1/dex/metrics`, `GET /v1/token/price/:symbol`, `GET /v1/whales/signals`, `GET /v1/keys/self`, `POST /v1/keys/revoke`.
+```bash
+node mcp_server.js
+```
 
-SDKs preserve response bodies, including `provenance`. They surface 401, 402, 405, 429 (`Retry-After`), and 503 `DATA_SOURCE_UNAVAILABLE` without inventing fallback values.
+## License
+MIT License. Copyright (c) 2026 M2M Sentinel.

package/agent_adapter.js

@@ -1,30 +1,202 @@
-// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+'use strict';
 
-const { M2MSentinelClient } = require('./index.js');
+/**
+ * Coinbase AgentKit Action Provider for M2M Sentinel.
+ *
+ * Exposes pre-transaction contract bytecode capability inspection, proxy resolution,
+ * and market observations to autonomous Base agents using @coinbase/agentkit.
+ */
 
-class M2MSentinelAgentTool {
+const https = require('https');
+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);
+
+class M2MSentinelActionProvider {
   constructor(options = {}) {
-    this.name = 'm2m_sentinel_security_audit';
-    this.description = 'Audits EVM smart contracts on Base for security risks, proxies, and bytecode findings.';
-    this.client = new M2MSentinelClient({
-      apiKey: options.apiKey || process.env.M2M_SENTINEL_API_KEY,
-      baseUrl: options.baseUrl
+    this.name = 'm2m_sentinel';
+    this.actionProviderName = 'm2m_sentinel';
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.apiKey = options.apiKey || process.env.M2M_SENTINEL_API_KEY || '';
+    this.timeoutMs = Number(options.timeoutMs || DEFAULT_TIMEOUT_MS);
+  }
+
+  supportsNetwork(network) {
+    if (!network) return true;
+    const chainId = String(network.chainId || network.networkId || '');
+    const protocolFamily = String(network.protocolFamily || 'evm').toLowerCase();
+    return protocolFamily === 'evm' && (
+      chainId === '8453' ||
+      chainId === 'base' ||
+      chainId === 'base-mainnet' ||
+      chainId === 'base-sepolia' ||
+      chainId === '84532'
+    );
+  }
+
+  async _queryApi(endpointPath, options = {}) {
+    const url = new URL(endpointPath, this.baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+
+    const headers = {
+      Accept: 'application/json',
+      'User-Agent': 'M2MSentinel-AgentKit/1.1.1',
+      ...options.headers
+    };
+    if (this.apiKey && !headers['x-api-key']) {
+      headers['x-api-key'] = this.apiKey;
+    }
+
+    return new Promise((resolve, reject) => {
+      const req = transport.request(url, {
+        method: 'GET',
+        headers,
+        timeout: this.timeoutMs
+      }, (res) => {
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          let body = null;
+          if (data) {
+            try { body = JSON.parse(data); } catch (_) { body = { raw: data }; }
+          }
+          resolve({
+            statusCode: res.statusCode,
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            body
+          });
+        });
+      });
+
+      req.on('timeout', () => req.destroy(new Error('M2M Sentinel request timed out')));
+      req.on('error', reject);
+      req.end();
     });
   }
 
-  async _call(address) {
-    try {
-      return await this.client.auditContract(address);
-    } catch (err) {
-      return {
-        error: err.name || 'M2MSentinelError',
-        message: err.message,
-        status: err.status,
-        paymentRequired: err.paymentRequired || null,
-        retryAfter: err.retryAfter || null
-      };
+  async auditContract(args) {
+    const address = String(args.address || args.contractAddress || '').trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      return JSON.stringify({
+        status: 'ERROR',
+        error: 'INVALID_ADDRESS',
+        message: 'A valid 40-hex 0x-prefixed Base contract address is required.'
+      });
+    }
+
+    const res = await this._queryApi(`/v1/audit/${encodeURIComponent(address)}`);
+    if (!res.ok) {
+      return JSON.stringify({
+        status: 'ERROR',
+        statusCode: res.statusCode,
+        error: res.body && res.body.error ? res.body.error : 'API_ERROR',
+        message: res.body && res.body.message ? res.body.message : 'Contract audit query failed',
+        notASafetyGuarantee: true
+      });
     }
+
+    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)}`
+    });
+  }
+
+  async getGasMetrics() {
+    const res = await this._queryApi('/v1/gas/fees');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve gas fees' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getTokenPrice(args) {
+    const symbol = String(args.symbol || args.tokenSymbol || '').trim().toUpperCase();
+    if (!symbol) {
+      return JSON.stringify({ status: 'ERROR', message: 'Token symbol is required (e.g. USDC, WETH)' });
+    }
+    const res = await this._queryApi(`/v1/token/price/${encodeURIComponent(symbol)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: `Failed to retrieve price for ${symbol}` });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getServiceStatus() {
+    const res = await this._queryApi('/v1/status');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'UNAVAILABLE', statusCode: res.statusCode });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  getActions(_walletProvider) {
+    return [
+      {
+        name: 'm2m_audit_contract',
+        description: 'Inspect Base target contract bytecode capability observations, proxy implementation slots, and limitations before executing transactions. Returns factual evidence, not a safety guarantee.',
+        schema: {
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'Target Base contract address (0x-prefixed 40-hex)'
+            }
+          },
+          required: ['address']
+        },
+        invoke: (args) => this.auditContract(args)
+      },
+      {
+        name: 'm2m_get_gas_metrics',
+        description: 'Get real-time Base network gas execution metrics and recommendations before submitting on-chain transactions.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getGasMetrics()
+      },
+      {
+        name: 'm2m_get_token_price',
+        description: 'Observe real-time Base DEX token price for slippage check and valuation.',
+        schema: {
+          type: 'object',
+          properties: {
+            symbol: {
+              type: 'string',
+              description: 'Token symbol on Base (e.g. USDC, WETH)'
+            }
+          },
+          required: ['symbol']
+        },
+        invoke: (args) => this.getTokenPrice(args)
+      },
+      {
+        name: 'm2m_get_service_status',
+        description: 'Check operational status of M2M Sentinel upstream verification rails.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getServiceStatus()
+      }
+    ];
   }
 }
 
-module.exports = { M2MSentinelAgentTool };
+function m2mSentinelActionProvider(options = {}) {
+  return new M2MSentinelActionProvider(options);
+}
+
+// Backward compatibility alias
+class M2MSentinelAgentTool extends M2MSentinelActionProvider {}
+
+module.exports = {
+  M2MSentinelActionProvider,
+  m2mSentinelActionProvider,
+  M2MSentinelAgentTool
+};

package/eliza_plugin.js

@@ -20,7 +20,7 @@ const m2mSentinelPlugin = {
   actions: [
     {
       name: 'AUDIT_CONTRACT',
-      description: 'Audits an EVM contract on Base Mainnet.',
+      description: 'Reports selected static capability and proxy observations for a Base contract.',
       handler: async (runtime, message) => {
         const address = message.content.text.match(/0x[a-fA-F0-9]{40}/)?.[0];
         if (!address) return { text: 'Please provide a valid 42-character EVM contract address.' };
@@ -28,20 +28,20 @@ const m2mSentinelPlugin = {
           const data = await clientFor(runtime).auditContract(address);
           const audit = data.audit || {};
           const proxy = audit.proxyResolution || {};
-          return { text: `M2M Sentinel audit for ${address}: ${audit.securityRating || 'UNKNOWN'}; proxy=${proxy.isProxy ? proxy.proxyType : 'NO'}; provenance=${JSON.stringify(audit.provenance || data.provenance || null)}` };
+          return { text: `M2M Sentinel capability analysis for ${address}: ${audit.capabilityRating || 'UNVERIFIED'}; proxy=${proxy.isProxy ? proxy.proxyType : 'NO'}; notASafetyGuarantee=true; provenance=${JSON.stringify(audit.provenance || data.provenance || null)}` };
         } catch (err) { return { text: errorText(err) }; }
       }
     },
     {
-      name: 'GET_SECURITY_SCORE',
-      description: 'Returns the security score for a Base contract address.',
+      name: 'GET_CAPABILITY_SCORE',
+      description: 'Returns the static capability coverage index for a Base contract. The index is not a safety score.',
       handler: async (runtime, message) => {
         const address = message.content.text.match(/0x[a-fA-F0-9]{40}/)?.[0];
         if (!address) return { text: 'Please provide a valid EVM contract address.' };
         try {
-          const data = await clientFor(runtime).getSecurityScore(address);
-          const score = data.securityScore === null ? 'not decision-grade' : `${data.securityScore}/100`;
-          return { text: `M2M Sentinel security score for ${address}: ${score}. Provenance: ${JSON.stringify(data.provenance || null)}` };
+          const data = await clientFor(runtime).getCapabilityScore(address);
+          const score = data.capabilityScore === null ? 'unverified' : `${data.capabilityScore}/100 capability coverage`;
+          return { text: `M2M Sentinel static index for ${address}: ${score}; not a safety score. Provenance: ${JSON.stringify(data.provenance || null)}` };
         } catch (err) { return { text: errorText(err) }; }
       }
     },

package/index.d.ts

@@ -0,0 +1,94 @@
+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>;
+};