neooracle

NeoOracle Marble Service

TEE-secured HTTP oracle proxy running inside MarbleRun enclave.

Overview

The NeoOracle Marble service implements secure external data fetching:

1. User contracts request external data via Gateway
2. TEE fetches data from external URLs within secure enclave
3. Supports secret injection for authenticated API calls
4. Returns data with TEE attestation

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    MarbleRun Enclave (TEE)                      │
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐      ┌─────────────┐        │
│  │   Handler   │    │ URL Allow-  │      │  Secrets    │        │
│  │  (REST API) │───>│   list      │      │  Client     │        │
│  └─────────────┘    └──────┬──────┘      └──────┬──────┘        │
│         │                  │                    │               │
│         │                  │                    │               │
│  ┌──────▼──────────────────▼────────────────────▼──────┐        │
│  │                  HTTP Client                        │        │
│  │           (with optional secret auth)               │        │
│  └─────────────────────────┬───────────────────────────┘        │
└────────────────────────────┼────────────────────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  External APIs  │
                    │ (api.coingecko.com│
                    │   etc.)         │
                    └─────────────────┘

File Structure

Key Components

Service Struct

type Service struct {
    *commonservice.BaseService
    secretProvider secrets.Provider
    httpClient   *http.Client
    maxBodyBytes int64
    allowlist    URLAllowlist
}

Secrets Provider

The oracle can inject user-owned secrets into outbound requests (e.g., API keys). Secrets are fetched via the shared infrastructure/secrets.Provider interface and enforced by per-secret access policies.

type Provider interface {
    GetSecret(ctx context.Context, userID, name string) (string, error)
}

URLAllowlist

Controls which external URLs can be fetched:

type URLAllowlist struct {
    Prefixes []string
}

func (a URLAllowlist) Allows(url string) bool

Security Features

URL Allowlist

Only configured URL prefixes are allowed:

allowlist := URLAllowlist{
    Prefixes: []string{
        "https://api.coingecko.com/",
        "https://api.binance.com/",
    },
}

Secret Injection

Secrets can be automatically injected into request headers:

{
    "url": "https://api.binance.com/api/v3/account",
    "secret_name": "binance_api_key",
    "secret_as_key": "X-MBX-APIKEY"
}

Response Size Limit

Maximum response body size (default 2MB) to prevent memory exhaustion.

API Endpoints

Request/Response Types

QueryInput

type QueryInput struct {
    URL         string            `json:"url"`
    Method      string            `json:"method,omitempty"`        // default: GET
    Headers     map[string]string `json:"headers,omitempty"`
    SecretName  string            `json:"secret_name,omitempty"`   // optional: secret for auth
    SecretAsKey string            `json:"secret_as_key,omitempty"` // header key (default: Authorization)
    Body        string            `json:"body,omitempty"`          // body for POST/PUT
}

QueryResponse

type QueryResponse struct {
    StatusCode int               `json:"status_code"`
    Headers    map[string]string `json:"headers"`
    Body       string            `json:"body"`
}

Configuration

type Config struct {
    Marble            *marble.Marble
    SecretProvider    secrets.Provider
    MaxBodyBytes      int64        // optional: default 2MB
    URLAllowlist      URLAllowlist // optional: URL restrictions
    Timeout           time.Duration
}

Constants

Usage Examples

Basic GET Request

POST /query
{
    "url": "https://api.coingecko.com/api/v3/simple/price?ids=neo&vs_currencies=usd"
}

Authenticated Request with Secret

POST /query
{
    "url": "https://api.private.com/data",
    "method": "GET",
    "secret_name": "private_api_key",
    "secret_as_key": "X-API-Key"
}

POST Request with Body

POST /query
{
    "url": "https://api.thegraph.com/subgraphs/name/neo-project/neo",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "body": "{\"query\": \"{ users { id } }\"}"
}

Dependencies

Internal Packages

External Packages

Related Documentation

• NeoOracle Service Overview
• Smart Contract