Skip to content

OVERVIEW.md

Latest commit

 

History

History
67 lines (56 loc) · 3.02 KB

OVERVIEW.md

File metadata and controls

67 lines (56 loc) · 3.02 KB
Raw

Nodemasterx (nmx-infra) Project Overview 🎯 Executive Summary Nodemasterx is a Serverless Web3 Gateway that provides developer access to blockchain networks (Polygon, Bitcoin) via a standard JSON-RPC 2.0 API. It functions as a lightweight, drop-in replacement for services like Alchemy or Infura, but with a unique "Zero Lock-in" philosophy.

Key Value Props:

No UI: purely API-driven. Serverless: Built entirely on AWS Lambda and Managed Blockchain. Auth: Uses GitHub Personal Access Tokens (PAT) as API keys. 🏗️ Technical Architecture Stack Runtime: Node.js 20+ (ES Modules) Compute: AWS Lambda Database: Amazon DynamoDB (Users, Token Cache) Blockchain: AWS Managed Blockchain (AMB) Infrastructure: AWS SAM / CloudFormation Modules (/lambdas) rpc-endpoint.js (Core):

Handles JSON-RPC traffic. Routes requests to AWS Managed Blockchain based on network/region. Signs requests using AWS Signature V4. Supports: Polygon Mainnet, Bitcoin Mainnet, Bitcoin Testnet. Multi-Region: Supports 6 AWS regions (fallback to us-east-1). auth-token-validator.js (Middleware):

Validates GitHub PATs. Smart Caching: Implements a sliding window cache (15m - 1h) in DynamoDB to minimize GitHub API calls. Security: Verifies user existence in nodemasterx-users table (users must "register" first via OAuth flow). auth-login-redirect.js & auth-oauth-callback.js:

Handles the initial GitHub OAuth flow to register users and generate/link PATs. batch-endpoint.js:

Handles batched JSON-RPC requests (array of requests). status-endpoint.js:

Public health check and service info. 🔐 Security & Optimization Authentication: Bearer Token (GitHub PAT). Optimization: Cache hit = 1 DynamoDB read (skips GitHub API). Cache miss = GitHub API verification + DynamoDB write. Rate Limiting: Respects GitHub API limits and implements internal limits. 📂 Key Files lambdas/rpc-endpoint.js: The "router" logic. lambdas/auth-token-validator.js: The "guard" logic. infrastructure/template.yaml: AWS SAM definition. infrastructure/cloudformation.yml: CloudFormation alternative. 🚀 Getting Started (Dev) Run Tests: npm run test:all Local Dev: npm run dev (uses nodemon) Mock Mode: Set MOCK_GITHUB_API=true in .env to bypass real GitHub Auth during dev.

🧠 NMX Intelligence Layer (V2)

The V2 update introduces Programmable AI Middleware. Unlike V1 which is pure infrastructure, V2 allows developers to inject "Intelligence" into the RPC stream.

Key Concepts

  1. Interface Manifest (The "Real Config"): A JSON schema defining the AI's behavior. Stored statefully in nodemasterx-interface-profiles.
  2. Dynamic Compiler: The Engine (interface-engine.js) builds the AI's system prompt at runtime based on the Manifest.
  3. Execution Gate: Enforces block, flag, or shadow_mode strategies based on AI analysis.

New Endpoints

  • POST /v2/interface/create: Register a Manifest. Returns interface_id (UUID).
  • GET /v2/interface/list: View your registered interfaces.
  • POST /v2/{network} with X-NMX-Interface-ID: Execute a transaction through the Intelligence Layer.