m2m-sentinel-sdk 1.2.3 → 1.2.7

package/eliza_plugin.js

@@ -69,7 +69,7 @@ const m2mSentinelPlugin = {
     },
     {
       name: 'GET_GAS_FEES',
-      description: 'Fetches live Base gas fees.',
+      description: 'Fetches current Base gas-price telemetry with upstream provenance.',
       handler: async (runtime) => {
         try { return { text: JSON.stringify(await clientFor(runtime).getGasFees()) }; }
         catch (err) { return { text: errorText(err) }; }

package/index.d.ts

@@ -23,6 +23,192 @@ export interface TransactionPreflightRequest {
   blockNumber?: number | string;
 }
 
+/** A top-level call in the documented EIP-5792 wallet_sendCalls envelope. */
+export interface WalletSendCallsCall {
+  to: string;
+  data: string;
+  /** Base Account uses canonical 0x quantities for call value. */
+  value?: string;
+  capabilities?: Record<string, Record<string, unknown>>;
+  flowControl?: Record<string, unknown>;
+}
+
+export interface WalletSendCallsParams {
+  version: '1.0';
+  id?: string;
+  from: string;
+  /** Deliberately restricted to Base's canonical wallet_sendCalls value. */
+  chainId: '0x2105';
+  atomicRequired?: boolean;
+  calls: WalletSendCallsCall[];
+  capabilities?: Record<string, Record<string, unknown>>;
+}
+
+export interface WalletSendCallsRequest {
+  method: 'wallet_sendCalls';
+  params: [WalletSendCallsParams];
+}
+
+export interface Eip1193Provider {
+  request(request: WalletSendCallsRequest): Promise<unknown>;
+}
+
+export type BaseTrustLevel = 'HIGH_TRUST_PRIMARY' | 'QUORUM_PUBLIC';
+
+export interface BaseObservationBlock {
+  status: 'PINNED';
+  chainId: number | string;
+  network: 'eip155:8453';
+  blockNumber: number | string;
+  blockHash: string;
+  blockTag: string;
+  trustLevel: BaseTrustLevel;
+  [key: string]: unknown;
+}
+
+export interface BaseSimulationObservation {
+  attempted: true;
+  trusted: true;
+  outcome: 'NOT_ATTEMPTED' | 'SUCCEEDED' | 'REVERTED' | 'UNAVAILABLE' | 'MALFORMED';
+  blockTag: string;
+  evidenceOnly: true;
+  [key: string]: unknown;
+}
+
+export interface BaseRpcObservation {
+  pinnedBlockTag: string;
+  stateBearingCallCount: number;
+  failedReadCount: 0;
+  failures: unknown[];
+  calls: BaseRpcObservationCall[];
+  [key: string]: unknown;
+}
+
+export interface BaseRpcObservationCall {
+  method?: string;
+  params?: unknown[];
+  blockTag?: string | null;
+  status?: 'OK' | 'UNSUPPORTED_OPTIONAL_METHOD' | 'EXECUTION_ERROR' | string;
+  trustLevel?: BaseTrustLevel | 'DEGRADED_LOW_TRUST';
+  [key: string]: unknown;
+}
+
+export interface BaseCapabilityEvidence {
+  sourceAddress: string;
+  executionRole: 'RESOLVED_EXECUTING_CODE' | 'SELECTED_DIAMOND_FACET';
+  transactionSelector: string | null;
+  dissection: BaseDissection;
+  notASafetyGuarantee: true;
+  reachability: 'NOT_ESTABLISHED';
+  [key: string]: unknown;
+}
+
+export interface BaseDissectionCapability {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface BaseDissection {
+  isValidContract: true;
+  bytecodeSizeBytes: number;
+  targetBytecodeHash: string;
+  capabilities: BaseDissectionCapability[];
+  detectedCapabilities: string[];
+  [key: string]: unknown;
+}
+
+export interface BaseBytecodeHashes {
+  runtimeBytecodeHash: string | null;
+  finalTargetBytecodeHash: string;
+  facetBytecodeHash: string | null;
+  facetBytecodeHashes: unknown[];
+  [key: string]: unknown;
+}
+
+export interface BaseAccountPreflightObservation {
+  status: 'SUCCESS';
+  operation: 'TRANSACTION_PREFLIGHT_OBSERVATION';
+  request: TransactionPreflightRequest;
+  selectorHex: string | null;
+  surfaceTarget: string;
+  resolvedExecutionTarget: string;
+  resolution: Record<string, unknown> & { status: 'COMPLETE'; resolutionComplete: true };
+  evidenceGrade: true;
+  evidenceStatus: 'VERIFIED';
+  effectiveTrust: BaseTrustLevel;
+  observationBlock: BaseObservationBlock;
+  simulationObservation: BaseSimulationObservation;
+  rpcObservation: BaseRpcObservation;
+  capabilityEvidence: BaseCapabilityEvidence;
+  bytecodeHashes: BaseBytecodeHashes;
+  notASafetyGuarantee: true;
+  reachability: 'NOT_ESTABLISHED';
+  limitations: string[];
+  conclusion: null;
+  [key: string]: unknown;
+}
+
+export interface BaseAccountObservationIdentity {
+  blockNumber: bigint;
+  blockTag: string;
+  blockHash: string;
+  effectiveTrust: BaseTrustLevel;
+  blockTrustLevel: BaseTrustLevel;
+  finalTargetBytecodeHash: string;
+}
+
+export interface BaseAccountGuardContext {
+  callIndex: number;
+  index: number;
+  call: WalletSendCallsCall;
+  transaction: TransactionPreflightRequest;
+  request: WalletSendCallsRequest;
+  params: WalletSendCallsParams;
+  [key: string]: unknown;
+}
+
+export type BaseAccountCallerPolicyResult =
+  | true
+  | false
+  | null
+  | undefined
+  | { allow: true; reason?: string }
+  | { allow: false; reason?: string };
+
+export type BaseAccountCallerPolicy = (
+  observation: BaseAccountPreflightObservation,
+  context: BaseAccountGuardContext
+) => BaseAccountCallerPolicyResult | Promise<BaseAccountCallerPolicyResult>;
+
+export interface GuardWalletSendCallsOptions {
+  client: Pick<M2MSentinelClient, 'preflightTransaction'>;
+  provider: Eip1193Provider;
+  request: WalletSendCallsRequest;
+  policy: BaseAccountCallerPolicy;
+  context?: Record<string, unknown>;
+}
+
+export interface BaseAccountPaymasterGuardOptions {
+  client: Pick<M2MSentinelClient, 'preflightTransaction'>;
+  policy: BaseAccountCallerPolicy;
+}
+
+export interface BaseAccountGuardCallOptions {
+  policy?: BaseAccountCallerPolicy;
+  context?: Record<string, unknown>;
+}
+
+export interface PreflightBeforeSigningOptions {
+  client: Pick<M2MSentinelClient, 'preflightTransaction'>;
+  transaction: TransactionPreflightRequest;
+  policy: (
+    observation: BaseAccountPreflightObservation,
+    context: { transaction: TransactionPreflightRequest; [key: string]: unknown }
+  ) => BaseAccountCallerPolicyResult | Promise<BaseAccountCallerPolicyResult>;
+  signAndSend: (transaction: TransactionPreflightRequest, observation: BaseAccountPreflightObservation) => Promise<unknown>;
+  context?: Record<string, unknown>;
+}
+
 export interface M2MSentinelErrorOptions {
   status?: number;
   body?: unknown;
@@ -74,6 +260,64 @@ export class M2MSentinelClient {
   revokeKey(confirm?: boolean): Promise<any>;
 }
 
+export class WalletSendCallsInputError extends TypeError {
+  readonly code: 'INVALID_WALLET_SEND_CALLS_INPUT';
+  readonly field: string;
+  constructor(field: string, message: string);
+}
+
+export class ExecutionIdentityBlockedError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+
+export const PreflightInputError: typeof WalletSendCallsInputError;
+export const PreflightBlockedError: typeof ExecutionIdentityBlockedError;
+
+export const BASE_CHAIN_ID: 8453;
+export const BASE_CHAIN_HEX: '0x2105';
+export const BASE_NETWORK: 'eip155:8453';
+export const MAX_CALLS: number;
+export const MAX_PREFLIGHT_CONCURRENCY: number;
+export const MAX_RPC_OBSERVATION_CALLS: number;
+export const MAX_DATA_BYTES: number;
+
+export function isAffirmativePolicyResult(value: unknown): value is true | { allow: true; reason?: string };
+export function validateWalletSendCallsRequest(request: unknown): WalletSendCallsRequest;
+export const normalizeWalletSendCallsRequest: typeof validateWalletSendCallsRequest;
+export function transactionFromCall(params: WalletSendCallsParams, call: WalletSendCallsCall, index?: number): TransactionPreflightRequest;
+export function toPreflightTransaction(params: WalletSendCallsParams, call: WalletSendCallsCall, index?: number): TransactionPreflightRequest;
+export function assertObservationReady(
+  observation: unknown,
+  transaction: TransactionPreflightRequest
+): BaseAccountObservationIdentity;
+export function guardWalletSendCalls(options: GuardWalletSendCallsOptions): Promise<unknown>;
+export const preflightWalletSendCalls: typeof guardWalletSendCalls;
+export const sendCallsWithPreflight: typeof guardWalletSendCalls;
+export const executeWalletSendCalls: typeof guardWalletSendCalls;
+
+export function preflightBeforeSigning(options: PreflightBeforeSigningOptions): Promise<unknown>;
+export const guardTransaction: typeof preflightBeforeSigning;
+export const preflightTransactionBeforeSigning: typeof preflightBeforeSigning;
+
+export class BaseAccountPaymasterGuard {
+  constructor(options: BaseAccountPaymasterGuardOptions);
+  request(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
+  sendCalls(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
+  preflightTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
+  guardTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
+}
+
+export const BaseAccountExecutionGuard: typeof BaseAccountPaymasterGuard;
+export function createBaseAccountPaymasterGuard(options: BaseAccountPaymasterGuardOptions): BaseAccountPaymasterGuard;
+export function createExecutionIdentityGuard(options: BaseAccountPaymasterGuardOptions): BaseAccountPaymasterGuard;
+export function createPublicClient(options: {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  sdk?: { M2MSentinelClient: typeof M2MSentinelClient };
+}): M2MSentinelClient;
+
 export type SentinelPolicy = (
   analysis: any,
   context: { targetAddress: string; integration: string }
@@ -120,4 +364,3 @@ export class X402SignerClient {
 export function x402SignerClient(options?: X402SignerClientOptions): X402SignerClient;
 export function parsePaymentHeader(value: string | object | null): any;
 export function parsePriceToUnits(priceStr: string | number, decimals?: number): bigint;
-

package/index.js

@@ -176,6 +176,7 @@ function createViemSentinelInterceptor(apiKey, baseUrl, policy) {
 
 const { M2MSentinelActionProvider, m2mSentinelActionProvider } = require('./agent_adapter.js');
 const { X402SignerClient, x402SignerClient, parsePaymentHeader, parsePriceToUnits } = require('./x402_signer.js');
+const baseAccountPaymasterGuard = require('./base_account_paymaster_guard.js');
 
 module.exports = {
   M2MSentinelClient,
@@ -191,5 +192,6 @@ module.exports = {
   X402SignerClient,
   x402SignerClient,
   parsePaymentHeader,
-  parsePriceToUnits
+  parsePriceToUnits,
+  ...baseAccountPaymasterGuard
 };

package/langchain_tool.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * LangChain & LangGraph Tool Provider for M2M Sentinel.
+ *
+ * Compatible with @langchain/core/tools StructuredTool and DynamicStructuredTool.
+ */
+
+const { M2MSentinelClient } = require('./index.js');
+
+class M2MSentinelLangChainTools {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.apiKey] M2M Sentinel API Key
+   * @param {string} [options.baseUrl] M2M Sentinel Base URL
+   */
+  constructor(options = {}) {
+    this.client = new M2MSentinelClient(options);
+  }
+
+  /**
+   * Return a list of tool definitions compatible with LangChain agents.
+   * Can be passed directly to `createOpenAIToolsAgent({ tools })` or `AgentExecutor`.
+   */
+  getTools() {
+    return [
+      {
+        name: 'm2m_audit_contract',
+        description: 'Deterministic EVM bytecode capability analysis and proxy resolution for Base contracts. Run before signing or sending transactions to unverified contracts.',
+        schema: {
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'The 0x-prefixed 40-hex Ethereum address on Base (Chain ID 8453) to inspect.'
+            }
+          },
+          required: ['address']
+        },
+        func: async ({ address }) => {
+          try {
+            const res = await this.client.auditContract(address);
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      },
+      {
+        name: 'm2m_get_gas_metrics',
+        description: 'Fetch current Base gas price in wei/gwei with RPC provenance. Read-only telemetry; does not authorize or submit transactions.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        func: async () => {
+          try {
+            const res = await this.client.getGasFees();
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      },
+      {
+        name: 'm2m_get_token_price',
+        description: 'Fetch sourced Base DEX spot price for one allowlisted token symbol (e.g. USDC, WETH), with pool provenance and no historical price series.',
+        schema: {
+          type: 'object',
+          properties: {
+            symbol: {
+              type: 'string',
+              description: 'The asset symbol (e.g., USDC, WETH).'
+            }
+          },
+          required: ['symbol']
+        },
+        func: async ({ symbol }) => {
+          try {
+            const res = await this.client.getTokenPrice(symbol);
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      }
+    ];
+  }
+}
+
+module.exports = {
+  M2MSentinelLangChainTools
+};