Documentation

Technical documentation for Heliora Protocol execution layer infrastructure.

Optimistic execution layer for autonomous protocols on Base.

Production Documentation · Full execution network on Base Mainnet

Overview

Heliora Protocol is an execution layer infrastructure for on-chain automation. It enables protocols to register execution conditions and have them fulfilled by a permissionless executor network.

Key Properties

- Condition verification happens on-chain

- No trusted keepers or centralized operators

- No off-chain dependencies (no Chainlink, no Gelato)

- Cryptoeconomic guarantees via executor staking

- Primary network: Base Mainnet (real network, not custom chain)

Architecture

The protocol consists of four layers:

1. Condition Registry On-chain registry where protocols define execution conditions. Conditions specify: - Condition type (block number or timestamp) - Target contract address - Target function to execute - Execution mode (single or repeatable)

2. Executor Network Permissionless set of executors who monitor conditions and submit executions. Executors stake collateral proportional to execution value.

3. Verification Layer On-chain verification that conditions were met before execution finalized. Uses optimistic verification with challenge period.

4. Settlement Fee distribution to executors after successful execution. Slashing for invalid executions.

Execution Jobs

An ExecutionJob represents a registered automation task.

Job Model

```typescript

interface ExecutionJob {

id: string;

condition_type: "block" | "timestamp";

condition_value: number;

target_contract: string;

target_function: string;

chain: "Base";

execution_mode: "single" | "repeatable";

status: "PENDING" | "ACTIVE" | "EXECUTED" | "FAILED" | "PAUSED";

last_execution: number | null;

created_at: number;

updated_at: number;

}

```

Status Lifecycle

- PENDING — Created but not activated

- ACTIVE — Being monitored by executor network

- EXECUTED — Condition met and execution completed

- FAILED — Execution attempted but failed

- PAUSED — Manually paused by owner

Condition Types

Block Number Condition Triggers when current block number >= specified value. ``conditionType: "block" conditionValue: 18500000 // Execute at or after this block

Timestamp Condition Triggers when current timestamp >= specified Unix timestamp. ``conditionType: "timestamp" conditionValue: 1703980800 // Unix timestamp in seconds

Future condition types (planned): - Price oracle conditions - Storage slot conditions - Event-based conditions

Production Setup

Environment Variables

# Database (PostgreSQL for production)

# RPC (Base Mainnet) RPC_URL=https://mainnet.base.org # Or use paid RPC for better reliability: # RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY

# On-chain execution (optional) ONCHAIN_EXECUTION_ENABLED=true EXECUTOR_PRIVATE_KEY=0x... EXECUTOR_TEST_CONTRACT_ADDRESS=0x... USE_TESTNET=false

# Admin console ADMIN_SECRET=your-secure-secret-here

# Application URL NEXT_PUBLIC_APP_URL=https://heliora-protocol.xyz ```

Deployment Checklist

1. Set up PostgreSQL database (Neon, Supabase, or Railway)

2. Configure Base Mainnet RPC (use paid RPC for production)

3. Deploy ExecutorTest contract on Base Mainnet (optional)

4. Set ADMIN_SECRET for admin console access

5. Configure NEXT_PUBLIC_APP_URL to your production domain

6. Enable ONCHAIN_EXECUTION_ENABLED if using on-chain execution

Database Schema

The database automatically initializes required tables on first connection:

- execution_jobs - Execution job registry

- execution_logs - Execution history and logs

- newsletter_subscribers - Newsletter subscriptions

- contact_messages - Contact form submissions

- access_keys - Execution access keys

API Reference

Base URL `/api`

Endpoints

GET /api/jobs List all execution jobs.

POST /api/jobs Create new execution job. ``json { "conditionType": "block", "conditionValue": 18500000, "targetContract": "0x...", "targetFunction": "execute()", "executionMode": "single" }

GET /api/jobs/:id Get job details and logs.

PATCH /api/jobs/:id Update job status. ``json { "action": "activate" | "pause" | "retry" }

DELETE /api/jobs/:id Delete a job.

GET /api/execute Get current network state.

POST /api/execute Trigger execution loop (internal).

Integration Guide

Step 1: Create Execution Job

Send a POST request to create a new job: ``bash curl -X POST /api/jobs \ -H "Content-Type: application/json" \ -d '{ "conditionType": "block", "conditionValue": 18500000, "targetContract": "0x742d35Cc6634C0532925a3b844Bc9e7595f7e123", "targetFunction": "execute()", "executionMode": "single" }'

Step 2: Activate Job

Jobs are created in PENDING state. Activate to start monitoring: ``bash curl -X PATCH /api/jobs/:id \ -H "Content-Type: application/json" \ -d '{ "action": "activate" }'

Step 3: Monitor Execution

Check job status and logs: ``bash curl /api/jobs/:id

Step 4: Handle Completion

Jobs with executionMode: "single" move to EXECUTED status after successful execution. Repeatable jobs remain ACTIVE.

Pricing Model

Heliora uses a Subscription + Execution Fee + Stake model:

1. Subscription Fee - Mainnet tier: $500/month - Provides network access and execution quota - Includes priority executor assignment

2. Execution Fee - Standard: $0.01–$0.10 per execution (based on complexity) - Value-based (Enterprise): 0.1% of liquidation volume - Client pays only when execution happens

3. Stake (Economic Guarantee) - 0.01 ETH per condition - Slashed for invalid execution - Provides cryptoeconomic security

Why This Model

- **Cheaper than keepers:** No per-keeper subscription fees

- **Value-aligned:** Pay only for successful executions

- **Secure:** Stake provides economic guarantee

- **Independent:** No dependency on Chainlink or Gelato infrastructure

Cost Comparison Example

For 100 liquidations/month:

- Gelato: ~$2,000/month

- Chainlink: ~$1,500/month

- Heliora: ~$510/month ($500 + $0.10 × 100)

Security Model

Trust Assumptions

- Condition evaluation is deterministic

- At least one honest executor exists

- Network (Base Mainnet) is available

Guarantees

- Execution Correctness: Invalid executions are detected via fraud proofs and slashed

- Liveness: Economic incentives ensure timely execution

- MEV Resistance: Commit-reveal prevents front-running

- No Off-Chain Dependencies: All condition verification on-chain

Competitive Advantages

- **Cheaper:** No per-keeper fees, pay only for executions

- **Safer:** Cryptoeconomic guarantees via staking & slashing

- **Independent:** No Chainlink DON, no Gelato infrastructure

- **Real Network:** Executes on Base Mainnet with real block data

Current Status

- ✓ Production execution network on Base Mainnet

- ✓ Real Base Mainnet block data

- ✓ On-chain condition evaluation

- ✓ On-chain execution verified

- ✓ Cryptoeconomic security model

Enhancement Roadmap

- Enhanced executor staking with slashing

- Multi-chain adapters

- ZK validity proofs for instant finality

FAQ

Is this a production system? Yes. Heliora is a production execution network running on Base Mainnet with verified on-chain execution.

What network is supported? Base Mainnet (EVM). Real block data from Base Mainnet. No custom chain.

How is Heliora different from Gelato/Chainlink?

- **Cheaper:** No per-keeper fees, pay only for executions ($0.01–$0.10 per execution)

- **Safer:** Cryptoeconomic guarantees via staking & slashing

- **No dependencies:** No Chainlink DON, no Gelato infrastructure

- **Real network:** Works directly on Base Mainnet

How do I become an executor? Executor participation is available. Contact the team for executor onboarding and staking requirements.

Are there any tokens? No. Heliora does not have a token. Fees are paid in ETH/USD.

Can I use this for real transactions? Yes. Heliora executes real on-chain transactions on Base Mainnet. Configure your execution contracts and start automating.

What's the pricing model? Subscription ($500/month for Mainnet) + Execution Fee ($0.01–$0.10 per execution) + Stake (0.01 ETH per condition).