NodeMasterX (nmx-infra) - Complete Project Understanding

Executive Summary

NodeMasterX is a Serverless Web3 Gateway built by Neural Inverse that provides developers instant access to blockchain networks (Polygon, Bitcoin) through a standard JSON-RPC 2.0 API. It serves as a drop-in replacement for Alchemy, Infura, or QuickNode.

Philosophy: No UI. No Lock-in. Better B2D (Business-to-Developer).

Architecture Overview

┌──────────────────────────────────────────────────────────────────────────────┐
│                           CLIENT (Developer App)                              │
└─────────────────────────────────┬────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                        AWS API Gateway (HTTP API)                             │
│                      https://nodemasterx.com                                  │
└────┬──────────┬──────────┬──────────┬──────────┬──────────┬─────────────────┘
     │          │          │          │          │          │
     ▼          ▼          ▼          ▼          ▼          ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Status  │ │  OAuth  │ │  RPC    │ │ V2 RPC  │ │Interface│ │ Billing │
│Endpoint │ │Callback │ │Endpoint │ │ Handler │ │  APIs   │ │  APIs   │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
     │          │          │          │          │          │
     └──────────┴──────────┴────┬─────┴──────────┴──────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
            ┌──────────────┐      ┌──────────────────┐
            │   Shared     │      │   External       │
            │   Modules    │      │   Services       │
            │              │      │                  │
            │ • Validator  │      │ • GitHub API     │
            │ • Billing    │      │ • AWS Blockchain │
            │   Service    │      │ • Azure OpenAI   │
            │              │      │ • Stripe         │
            └──────┬───────┘      └──────────────────┘
                   │
                   ▼
            ┌──────────────────────────────────────────┐
            │              DynamoDB                     │
            │  • nodemasterx-users                     │
            │  • nodemasterx-token-cache               │
            │  • nodemasterx-interface-profiles        │
            └──────────────────────────────────────────┘

File Structure

Path	Purpose
`lambdas/`	All Lambda function source code
`lambdas/v2/`	V2 Intelligence Layer functions
`lambdas/cron/`	Scheduled jobs (billing)
`infrastructure/`	AWS SAM/CloudFormation templates
`scripts/`	Build, package, and deploy scripts
`local-dev/`	Local testing harness and mocks
`docs/`	Documentation (AWS permissions, deployment guides)

V1 - Core Infrastructure Functions

1. `status-endpoint.js`

Route: GET /
Purpose: Public health check and service info
Auth: None required
Response: Product info, supported networks, getting started guide

2. `auth-oauth-callback.js`

Route: GET /callback
Purpose: Handle GitHub OAuth flow, register new users
Flow: GitHub OAuth code → Exchange for access token → Create user record in DynamoDB

3. `auth-token-validator.js`

Type: Shared middleware (imported by other functions)
Purpose: Validate GitHub Personal Access Tokens (PAT)
Key Functions:
- validateToken(token, requestId) - Main validation entry point
- getCachedToken(tokenHash) - DynamoDB cache lookup
- storeCachedToken() - Cache new tokens
- extendTokenTTL() - Sliding window cache extension
Security Features:
- SHA-256 token hashing (never stores raw tokens)
- Sliding window cache: 15min initial → extends up to 1hr on activity
- Force revalidation after 5 hours of inactivity
- User must exist in nodemasterx-users table (OAuth registration required)

4. `rpc-endpoint.js`

Route: POST /v1/{network}
Purpose: Forward JSON-RPC requests to blockchain
Networks: polygon-mainnet, bitcoin-mainnet, bitcoin-testnet
Key Functions:
- handler() - Main Lambda handler
- forwardToBlockchain() - AWS SigV4 signed requests to AMB
- validateJsonRpcRequest() - JSON-RPC 2.0 validation
- dispatchUsageEvent() - Send usage to SQS for billing

5. `batch-endpoint.js`

Route: POST /v1/batch/{network}
Purpose: Handle batched JSON-RPC requests (array of requests)

V2 - Intelligence Layer Functions

The V2 API adds Programmable AI Middleware that allows developers to inject "intelligence" into the RPC stream.

Key Concepts

Interface Manifest - A JSON schema defining AI behavior, stored in nodemasterx-interface-profiles
Dynamic Compiler - Builds AI system prompts at runtime from the Manifest
Execution Gate - Enforces block, flag, or shadow_mode strategies based on AI analysis

1. `v2/interface-config.js`

Route: POST /v2/interface/create
Purpose: Register a new Interface Manifest
Billing: Deducts $0.10 creation fee from prepaid balance
Manifest Schema:

{
  "interface_metadata": { "version": "...", "tier": "...", "label": "..." },
  "intelligence_config": { "model": "...", "logic_mode": "..." },
  "active_constraints": {
    "heuristic_rules": ["..."],
    "thresholds": {},
    "fail_strategy": "block|flag|shadow_mode"
  }
}

2. `v2/interface-list.js`

Route: GET /v2/interface/list
Purpose: View user's registered interfaces

3. `v2/interface-delete.js`

Route: POST /v2/interface/delete
Purpose: Soft-delete an interface (stops recurring billing)
Security: IDOR check ensures user owns the interface

4. `v2/interface-engine.js`

Type: Internal module (not exposed as endpoint)
Purpose: Core AI evaluation logic
Key Functions:
- evaluateTransaction(rpcRequest, interfaceId, context) - Main evaluation
- buildDynamicPrompt(rpcRequest, profile, enrichment) - Compile AI prompt
- executeDecisionGate(inferenceResult, constraints) - Enforce block/flag/shadow
- callAzureOpenAI() - Azure OpenAI API integration

5. `v2/rpc-handler.js`

Route: POST /v2/{network} with header X-NMX-Interface-ID
Purpose: Execute transactions through the Intelligence Layer
Flow:
1. Validate token
2. Parse JSON-RPC request
3. Call evaluateTransaction() from interface-engine
4. If allowed, forward to blockchain
5. If blocked, return custom error

Billing System

Pricing Model

Item	Cost
Interface Creation	$0.10 (one-time)
Interface Monthly Storage	$0.50/month (~$0.0166/day)
RPC Requests	Token-based (via AI model execution)
Initial Free Credits	Provided on signup

1. `billing-service.js`

Type: Shared module
Purpose: Core billing logic and Stripe integration
Key Functions:
- createOrGetCustomer() - Stripe customer management
- createPortalSession() - Generate Stripe billing portal URL
- deductPrepaidBalance() - Synchronous credit deduction
- checkPrepaidBalance() - Check if user has credits
- calculateChargeThreshold() - Determine next auto-charge amount
- attemptCharge() - Charge Stripe payment method
- shouldThrottle() - Determine if user should be rate-limited

2. `account-billing.js`

Route: GET /v1/account/billing
Purpose: User billing dashboard endpoint
Response: Account status, usage stats, prepaid balance, portal link

3. `billing-worker.js`

Trigger: SQS (Usage Queue)
Purpose: Async processing of usage events
Flow:
1. Receive usage event from SQS
2. Calculate cost
3. Deduct from prepaid credits OR increment unpaid balance
4. Auto-charge when threshold reached
5. Throttle user if charge fails

4. `cron/daily-billing.js`

Trigger: EventBridge (Daily schedule)
Purpose: Deduct recurring storage fees for active interfaces
Flow:
1. Scan all active interfaces
2. Aggregate by user
3. Deduct daily rate from prepaid balance
4. Mark insufficient funds (TODO: freeze interface logic)

DynamoDB Schema

1. `nodemasterx-users`

Primary Key: github_user_id (Number)
GSI: StripeCustomerIdIndex on stripe_customer_id
Contains: User profile, OAuth data, billing state, usage counters

2. `nodemasterx-token-cache`

Primary Key: token_hash (String, SHA-256)
TTL: expires_at (automatic cleanup)
Contains: Cached token validation, user snapshot, timestamps

3. `nodemasterx-interface-profiles`

Primary Key: interface_id (String, UUID)
Contains: Interface manifest, owner, status, timestamps

Scripts

Script	Purpose
`package-all.sh`	Unified packager for all V1+V2 Lambdas → `dist/`
`package-lambdas.sh`	Legacy V1 packager
`package-v2-lambdas.sh`	V2-only packager → `dist-v2/`
`validate-packages.sh`	Validate zip contents and structure
`deploy-to-aws.sh`	Deploy to dev/staging/prod
`quick-deploy.sh`	Fast re-deploy of code only

Infrastructure Templates

`template.yaml` (AWS SAM)

Defines all resources:

3 DynamoDB Tables (Users, Token Cache, Interface Profiles)
10+ Lambda Functions
1 SQS Queue (Usage processing)
1 HTTP API (API Gateway)
IAM Policies (DynamoDB, SQS, Managed Blockchain)

`cloudformation.yml`

Alternative CloudFormation template with similar resources.

Local Development

Environment Setup

cp .env.example .env
npm install

Key Environment Variables

Variable	Purpose
`MOCK_GITHUB_API`	Set to `true` to mock GitHub OAuth (default)
`LOCAL_DEV_MODE`	Enable local DynamoDB
`GITHUB_CLIENT_ID/SECRET`	For real OAuth testing

Test Commands

npm run test:status      # Status endpoint
npm run test:auth        # OAuth callback
npm run test:validator   # Token validator
npm run test:rpc         # RPC endpoint
npm run test:batch       # Batch endpoint
npm run test:all         # All tests
npm run dev              # Watch mode

External Service Dependencies

Service	Purpose	Required Credentials
GitHub API	OAuth authentication, PAT validation	`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
AWS Managed Blockchain	Polygon/Bitcoin RPC access	AWS credentials with `managedblockchain:InvokeRpcCall`
Azure OpenAI	V2 Intelligence Layer inference	`AZURE_OPENAI_KEY`, `AZURE_OPENAI_ENDPOINT`
Stripe	Payment processing, billing portal	`STRIPE_SECRET_KEY`
AWS DynamoDB	Data persistence	Standard AWS credentials
AWS SQS	Async usage event processing	Standard AWS credentials

API Endpoints Summary

V1 Endpoints

Method	Path	Auth	Purpose
GET	`/`	No	Service status
GET	`/callback`	No	OAuth callback
POST	`/v1/{network}`	Yes	JSON-RPC request
GET	`/v1/account/billing`	Yes	Billing dashboard

V2 Endpoints

Method	Path	Auth	Purpose
POST	`/v2/interface/create`	Yes	Create interface
GET	`/v2/interface/list`	Yes	List interfaces
POST	`/v2/interface/delete`	Yes	Delete interface
POST	`/v2/{network}`	Yes	AI-gated RPC

Version History

v2.1.0-alpha (Current)
- V2 Intelligence Layer with Azure OpenAI
- Prepaid credit billing system
- Interface creation/deletion with billing
Future (v2.2.0)
- WebSocket support
- Additional networks (Ethereum, Solana)
- Usage analytics dashboard
Future (v3.0.0)
- GraphQL API
- SDK libraries (JS, Python, Go)
- Enterprise features

Built with ❤️ by Neural Inverse

No UI. No Lock-in. Better B2D.

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
docs		docs
infrastructure		infrastructure
lambdas		lambdas
local-dev		local-dev
scripts		scripts
tests		tests
v2-attacker		v2-attacker
website		website
.npmignore		.npmignore
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
NodeMasterX.postman_collection.json		NodeMasterX.postman_collection.json
OVERVIEW.md		OVERVIEW.md
README.md		README.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

NodeMasterX (nmx-infra) - Complete Project Understanding

Executive Summary

Architecture Overview

File Structure

V1 - Core Infrastructure Functions

1. status-endpoint.js

2. auth-oauth-callback.js

3. auth-token-validator.js

4. rpc-endpoint.js

5. batch-endpoint.js

V2 - Intelligence Layer Functions

Key Concepts

1. v2/interface-config.js

2. v2/interface-list.js

3. v2/interface-delete.js

4. v2/interface-engine.js

5. v2/rpc-handler.js

Billing System

Pricing Model

1. billing-service.js

2. account-billing.js

3. billing-worker.js

4. cron/daily-billing.js

DynamoDB Schema

1. nodemasterx-users

2. nodemasterx-token-cache

3. nodemasterx-interface-profiles

Scripts

Infrastructure Templates

template.yaml (AWS SAM)

cloudformation.yml

Local Development

Environment Setup

Key Environment Variables

Test Commands

External Service Dependencies

API Endpoints Summary

V1 Endpoints

V2 Endpoints

Version History

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `status-endpoint.js`

2. `auth-oauth-callback.js`

3. `auth-token-validator.js`

4. `rpc-endpoint.js`

5. `batch-endpoint.js`

1. `v2/interface-config.js`

2. `v2/interface-list.js`

3. `v2/interface-delete.js`

4. `v2/interface-engine.js`

5. `v2/rpc-handler.js`

1. `billing-service.js`

2. `account-billing.js`

3. `billing-worker.js`

4. `cron/daily-billing.js`

1. `nodemasterx-users`

2. `nodemasterx-token-cache`

3. `nodemasterx-interface-profiles`

`template.yaml` (AWS SAM)

`cloudformation.yml`

Packages