Newton Policy Protocol RPC Server

Deprecation Notice: The standalone RPC server is deprecated in favor of the Gateway's integrated RPC endpoints. The Gateway provides a superset of RPC functionality with additional features including:

• Secrets management with encrypted storage
• WebSocket support for real-time updates
• Dual-flow architecture (synchronous and asynchronous)
• API key authentication with fine-grained permissions
• PostgreSQL integration for persistent storage
• Enhanced operator pool management

For new deployments, use the Gateway instead. See crates/gateway/README.md for Gateway documentation.

High-performance JSON-RPC server for Newton Policy Protocol task management and policy evaluation.

Latest Updates

• Cryptographic Authentication: Signature-based authentication with address whitelisting
• Policy Simulation: Test policy evaluation without creating blockchain tasks
• Enhanced Security: IP filtering, rate limiting, and comprehensive auth middleware
• Advanced Monitoring: Detailed metrics collection and health monitoring
• Improved Performance: Optimized async architecture with better error handling

Key Features

• Policy-Based Task Creation: Create tasks for policy evaluation with user intents
• Cryptographic Security: ECDSA signature verification and address-based access control
• Policy Simulation: Test policy logic without blockchain interaction
• Async Architecture: Built with async Rust and jsonrpsee for high performance
• Rate Limiting: Per-sender and global rate limiting with configurable windows
• Metrics & Monitoring: Prometheus metrics, health checks, and comprehensive observability
• EigenLayer Integration: Seamless integration with EigenLayer AVS infrastructure

Quick Start

# Using Make (recommended - automatically deploys if needed on local)
make run bin=rpc

# Using Make on testnet
make run bin=rpc chain_id=11155111 env=testnet

# Using Make with custom data provider config
make run bin=rpc data_provider_config=./my-data-provider.toml

# Using cargo directly
CHAIN_ID=31337 cargo run --manifest-path ./crates/rpc/Cargo.toml -- --chain-id 31337 start

# With custom data provider config
CHAIN_ID=31337 cargo run --manifest-path ./crates/rpc/Cargo.toml -- --chain-id 31337 --data-provider-config ./my-data-provider.toml start

# On testnet
CHAIN_ID=11155111 DEPLOYMENT_ENV=testnet cargo run --manifest-path ./crates/rpc/Cargo.toml -- --chain-id 11155111 start

Configuration

The RPC server is configured through the newton-rpc.toml file, optional data provider config, and environment variables.

Configuration Sources

1. Config File: crates/rpc/newton-rpc.toml - RPC-specific settings (automatically loaded)
2. Data Provider Config (optional): Can be specified with --data-provider-config flag
   • Default: crates/data-provider/data-provider.toml
   • Custom path can be provided via CLI argument
3. Environment Variables: CHAIN_ID, DEPLOYMENT_ENV, PRIVATE_KEY, etc.
4. Deployment Files: Chain-specific configuration loaded based on CHAIN_ID and DEPLOYMENT_ENV

The RPC config file (newton-rpc.toml) includes:

• Task generator settings (signer, quorum configuration)
• Server settings (host, port, max connections)
• Rate limiting configuration
• CORS configuration
• Metrics settings
• Logging configuration
• Task processor settings
• Authentication whitelist
• Data provider settings

Example Configuration

The newton-rpc.toml file structure:

[task_generator]
quorum_number = "00"
quorum_threshold_percentage = "40"

[task_generator.signer]
private_key = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"

[server]
host = "127.0.0.1"
port = 8080
max_connections = 100
max_request_body_size = 10485760 # 10MB

[rate_limit]
max_requests_per_sender = 100
window_seconds = 60
global_rps = 1000

[cors]
enabled = true
allowed_origins = ["*"]
allowed_methods = ["GET", "POST"]
allowed_headers = ["Content-Type", "Authorization", "x-api-key"]

[metrics]
enabled = true

[logging]
level = "newton_rpc=info,jsonrpsee=info"
format = "json"

[processor]
max_pending_tasks = 10000
task_timeout_seconds = 300

[data_provider]
max_cache_size = 104857600                       # 100 MiB
max_wasm_stack = 67108864                        # 64 MiB
fuel = 100000000
max_http_calls = 50
max_http_request_size = 1048576                  # 1 MiB
data_cache_url = "redis://:redis@127.0.0.1:6379"

[auth.whitelist]
"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266" = 100

Environment Variables

# Required
CHAIN_ID=31337
DEPLOYMENT_ENV=stagef

# Optional
RUST_LOG=info

API Endpoints

The Newton RPC Server provides JSON-RPC 2.0 endpoints for policy-based task management. All endpoints require cryptographic authentication via signed requests.

Authentication

All RPC methods require a signature field containing a cryptographic signature of the request parameters. The signature must be generated using a whitelisted private key.

Signature Generation Process

1. Convert request parameters to their internal representation (IRequest types)
2. Generate ABI-encoded packed hash using keccak256(abi.encodePacked(...))
3. Sign the hash using your private key
4. Include the hex-encoded signature in the request

Rate Limiting

• Per-address rate limiting: Configurable requests per time window
• Global rate limiting: Server-wide RPS limits
• IP-based blocking: Support for IP allowlists/blocklists

newton_createTask

Create a new policy evaluation task with user intent validation.

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_createTask",
  "params": {
    "signature": "0x1234567890abcdef...",
    "policy_client": "0x1234567890123456789012345678901234567890",
    "intent": {
      "from": "0x1234567890123456789012345678901234567890",
      "to": "0x0987654321098765432109876543210987654321",
      "value": "1000000000000000000",
      "data": "0x70a08231000000000000000000000000",
      "chain_id": "1",
      "function_signature": "0x70a08231"
    },
    "quorum_number": [1],
    "quorum_threshold_percentage": 40
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_request": {
      "policyClient": "0x1234567890123456789012345678901234567890",
      "intent": { ... },
      "quorumNumber": "0x01",
      "quorumThresholdPercentage": 40
    },
    "status": "Queued",
    "result": null,
    "error": null,
    "processing_time_ms": 15
  },
  "id": 1
}

newton_getTaskId

Get the current status of a task request (immediate response).

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_getTaskId",
  "params": {
    "signature": "0x1234567890abcdef...",
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_request": { ... },
    "status": "Completed",
    "result": {
      "task_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "error": null,
    "processing_time_ms": 150
  },
  "id": 1
}

newton_waitForTaskId

Wait for a task to complete and return the result. This endpoint blocks until the task is completed or the timeout is reached.

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_waitForTaskId",
  "params": {
    "signature": "0x1234567890abcdef...",
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timeout": 60
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_request": { ... },
    "status": "Completed",
    "result": {
      "task_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "error": null,
    "processing_time_ms": 200
  },
  "id": 1
}

newton_createTaskAndWait

Create a new task and wait for its completion in a single request. This combines the functionality of newton_createTask and newton_waitForTaskId.

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_createTaskAndWait",
  "params": {
    "signature": "0x1234567890abcdef...",
    "policy_client": "0x1234567890123456789012345678901234567890",
    "intent": {
      "from": "0x1234567890123456789012345678901234567890",
      "to": "0x0987654321098765432109876543210987654321",
      "value": "1000000000000000000",
      "data": "0x70a08231000000000000000000000000",
      "chain_id": "1",
      "function_signature": "0x70a08231"
    },
    "quorum_number": [1],
    "quorum_threshold_percentage": 40,
    "timeout": 60
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "task_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_request": { ... },
    "status": "Completed",
    "result": {
      "task_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "error": null,
    "processing_time_ms": 250
  },
  "id": 1
}

newton_simulatePolicyEvaluation

Simulate policy evaluation without creating an actual task. This endpoint allows testing policy logic against user intents.

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_simulatePolicyEvaluation",
  "params": {
    "signature": "0x1234567890abcdef...",
    "intent": {
      "from": "0x1234567890123456789012345678901234567890",
      "to": "0x0987654321098765432109876543210987654321",
      "value": "1000000000000000000",
      "data": "0x70a08231000000000000000000000000",
      "chainId": "1",
      "functionSignature": "0x70a08231"
    },
    "policy_task_data": {
      "policy": "0x706f6c696379...",
      "policyParams": "0x7b226d617856616c7565223a313030307d",
      "policyConfig": "0x7b22656e747279706f696e74223a226d61696e227d",
      "policyMetadata": "0x7b226e616d65223a2254657374506f6c696379227d"
    }
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "policy": "package main\n\nallow := true",
    "evaluation_result": true,
    "metadata": {
      "execution_time_ms": 25,
      "policy_version": "1.2.0"
    }
  },
  "id": 1
}

newton_health

Get server health status (no authentication required).

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_health",
  "params": {},
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "healthy",
    "timestamp": 1234567890,
    "version": "0.1.0"
  },
  "id": 1
}

newton_metrics

Get server metrics and performance data (no authentication required).

Request:

{
  "jsonrpc": "2.0",
  "method": "newton_metrics",
  "params": {},
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "request_count": 12345,
    "error_count": 23,
    "avg_response_time_ms": 45.2,
    "active_connections": 15,
    "rate_limit_hits": 5,
    "uptime_seconds": 86400
  },
  "id": 1
}

Task Status Values

• Queued: Task request has been submitted and is waiting to be processed
• Processing: Task is currently being processed by the system
• Completed: Task has been successfully completed
• Failed: Task processing failed with an error

Architecture

The Newton RPC Server is built with a modular, async architecture designed for high performance and reliability.

Core Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                            Newton RPC Server                               │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────────────────┐ ┌─────────────────────────────┐ │
│ │ JSON-RPC    │ │ Middleware Layer        │ │ Task Processor              │ │
│ │ Server      │ │                         │ │                             │ │
│ │             │ │ - Authentication        │ │ - Request Validation        │ │
│ │ - jsonrpsee │ │   • Signature Verify    │ │ - Task Creation             │ │
│ │ - Async     │ │   • Address Whitelist   │ │ - Status Tracking           │ │
│ │ - CORS      │ │ - Rate Limiting         │ │ - Policy Simulation         │ │
│ │ - HTTP/WS   │ │   • Per-Address Limits  │ │ - AVS Integration           │ │
│ │             │ │   • Global RPS Limits   │ │ - Data Provider Access      │ │
│ │             │ │ - Metrics Collection    │ │                             │ │
│ │             │ │ - IP Filtering          │ │                             │ │
│ └─────────────┘ └─────────────────────────┘ └─────────────────────────────┘ │
│           │                     │                            │             │
│           ▼                     ▼                            ▼             │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                        External Services                                │ │
│ │  - EigenLayer AVS Contracts (Task Manager, Service Manager)            │ │
│ │  - Policy Evaluation Engine (Rego/OPA)                                 │ │
│ │  - Blockchain RPC (Ethereum/Holesky)                                   │ │
│ │  - Data Provider Cache (Redis)                                         │ │
│ │  - Metrics Backend (Prometheus)                                        │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Key Features

• Cryptographic Authentication: Signature-based authentication with address whitelisting
• Async Task Processing: Non-blocking task creation and monitoring
• Rate Limiting: Per-sender and global rate limiting with configurable windows
• Policy Simulation: Test policy evaluation without creating actual tasks
• Metrics Collection: Prometheus metrics for monitoring and observability
• Health Monitoring: Built-in health checks and status endpoints
• IP Filtering: Support for IP allowlists and blocklists
• Error Handling: Comprehensive error handling with detailed error messages
• Configuration Management: Flexible TOML-based configuration system

Data Flow

1. Request Reception: JSON-RPC requests are received by the server
2. Authentication: Signature verification and address whitelisting
3. Middleware Processing: Rate limiting, IP filtering, and metrics collection
4. Intent Validation: User intents are validated against policy requirements
5. Task Processing:
   • Task Creation: Tasks are submitted to the AVS TaskManager contract
   • Policy Simulation: Direct policy evaluation without blockchain interaction
6. Status Tracking: Task status is monitored and updated asynchronously
7. Response Generation: Results are returned to the client with processing metrics

Health & Monitoring

Health Endpoints

• Health Check: GET /health - Returns server health status
• Metrics: GET /metrics - Prometheus metrics endpoint

Available Metrics

• Request count and latency by endpoint
• Rate limiting metrics (per-sender and global)
• Error rates and types
• Task processing times
• System resource usage

Example Health Response

{
  "status": "healthy",
  "timestamp": 1234567890,
  "version": "0.1.0"
}

Performance

The RPC server is optimized for high throughput and low latency:

• High Concurrency: Async/await architecture with tokio runtime
• Efficient Serialization: Zero-copy deserialization where possible
• Connection Pooling: Automatic connection management
• Rate Limiting: Configurable per-sender and global limits
• Memory Efficiency: Optimized data structures and minimal allocations

Performance Characteristics

• Throughput: 10,000+ requests per second
• Latency: Sub-millisecond for cached operations
• Memory Usage: Efficient memory management with Arc for shared state
• Concurrency: Multi-threaded async processing

Error Handling

The server provides comprehensive error handling with detailed error messages:

• Authentication Errors: Invalid signatures, non-whitelisted addresses, blocked IPs
• Validation Errors: Intent validation failures with specific field errors
• Rate Limiting: Clear rate limit exceeded messages with retry information
• Network Errors: Connection and timeout error handling
• Processing Errors: Task processing failures with context
• Policy Evaluation Errors: Detailed policy execution errors
• Configuration Errors: Invalid configuration with helpful messages

Common Error Codes

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Whitelisted address required",
    "data": {
      "code": "WHITELISTED_ADDRESS_REQUIRED",
      "details": "This method requires a whitelisted address"
    }
  },
  "id": 1
}

Authentication Error Examples

• Invalid Signature: INVALID_SIGNATURE - Signature verification failed
• Address Not Whitelisted: WHITELISTED_ADDRESS_REQUIRED - Address not in whitelist
• Rate Limit Exceeded: RATE_LIMIT_EXCEEDED - Too many requests from address
• IP Blocked: IP_BLOCKED - Request from blocked IP address

Authentication Setup

Client-Side Signature Generation

To interact with the Newton RPC server, clients must generate valid signatures for each request:

use alloy::{
    primitives::{keccak256, Address},
    signers::{local::PrivateKeySigner, SignerSync},
    sol_types::SolValue,
};
use std::str::FromStr;

// Example: Signing a CreateTaskRequest
let signer = PrivateKeySigner::from_str("0x...")?;

// Create the internal request representation
let internal_request = ICreateTaskRequest {
    policyClient: policy_client_address,
    intent: task_intent,
    quorumNumber: quorum_bytes,
    quorumThresholdPercentage: threshold,
};

// Generate hash and sign
let hash = keccak256(internal_request.abi_encode_packed());
let signature = signer.sign_hash_sync(&hash)?;

// Include in RPC request
let rpc_request = CreateTaskRequest {
    signature: hex::encode(signature.as_bytes()),
    policy_client: policy_client_address,
    intent: task_intent,
    quorum_number: Some(vec![1]),
    quorum_threshold_percentage: Some(40),
};

Whitelist Management

Add your address to the server whitelist configuration:

[rpc.auth]
whitelist_enabled = true
whitelisted_addresses = [
    "0xYourAddressHere",
    # Add more addresses as needed
]

JavaScript/TypeScript Example

import { ethers } from "ethers";

async function signRequest(request: any, privateKey: string): Promise<string> {
  const wallet = new ethers.Wallet(privateKey);

  // Convert to internal format and generate hash
  const internalRequest = convertToInternalFormat(request);
  const hash = ethers.utils.solidityKeccak256(
    ["bytes"],
    [ethers.utils.solidityPack(/* internal request fields */)]
  );

  const signature = await wallet.signMessage(ethers.utils.arrayify(hash));
  return signature;
}

Development

Prerequisites

• Rust 1.88+
• Cargo
• Make (optional, for convenience commands)
• Redis (for data provider cache)

Building from Source

# Clone the repository
git clone <repository-url>
cd newton-prover-avs

# Build the RPC server
cargo build --manifest-path ./crates/rpc/Cargo.toml

# Run tests
cargo test --manifest-path ./crates/rpc/Cargo.toml

# Run the server
CHAIN_ID=31337 cargo run --manifest-path ./crates/rpc/Cargo.toml -- --chain-id 31337 start

Docker Support

The RPC server can be built and run using Docker. The CHAIN_ID environment variable can be set at runtime:

# Build Docker image for RPC (default CHAIN_ID=31337)
docker build --target rpc -t newton-prover-rpc .

# Build for specific chain (configs baked in at build time)
docker build --build-arg CHAIN_ID=11155111 --target rpc -t newton-prover-rpc:sepolia .

# Run with default chain_id (31337)
docker run -p 8080:8080 newton-prover-rpc

# Run Sepolia image on Sepolia
docker run -e CHAIN_ID=11155111 -e DEPLOYMENT_ENV=testnet \
  -p 8080:8080 newton-prover-rpc:sepolia

# Run with custom configs mounted (overrides baked-in configs)
docker run -e CHAIN_ID=11155111 -e DEPLOYMENT_ENV=testnet \
  -v /path/to/custom-configs:/app/config \
  -p 8080:8080 newton-prover-rpc

# Run on mainnet
docker run -e CHAIN_ID=1 -e DEPLOYMENT_ENV=mainnet \
  -v /path/to/mainnet-configs:/app/config \
  -p 8080:8080 newton-prover-rpc

The same pattern applies to all services (operator, aggregator, challenger):

# Build for specific chain
docker build --build-arg CHAIN_ID=31337 --target operator -t newton-prover-operator .
docker build --build-arg CHAIN_ID=11155111 --target aggregator -t newton-prover-aggregator:sepolia .
docker build --build-arg CHAIN_ID=17000 --target challenger -t newton-prover-challenger:holesky .

# Run with baked-in configs
docker run -e CHAIN_ID=11155111 -e DEPLOYMENT_ENV=testnet newton-prover-operator

# Run with custom configs (overrides baked-in configs via volume mount)
docker run -e CHAIN_ID=11155111 -e DEPLOYMENT_ENV=testnet \
  -v /path/to/configs:/app/config \
  -p 9002:9002 newton-prover-aggregator:sepolia

Config Directory Structure:

• Configs are stored in /app/config
• At runtime, mount custom configs to /app/config to override baked-in configs
• Required files in the config directory:
  • operator.toml (for operator)
  • aggregator.toml (for aggregator)
  • challenger.toml (for challenger)
  • newton-rpc.toml (for rpc)
  • data-provider.toml (optional, for custom data provider config)