Documentation

Technical documentation for Heliora Protocol execution layer infrastructure.

MVP Documentation · Execution logic in development

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

- Cryptoeconomic guarantees via executor staking

- Primary network: Base (EVM)

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

conditionType: "block" | "timestamp"

conditionValue: number

targetContract: string

targetFunction: string

chain: "Base"

executionMode: "single" | "repeatable"

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

lastExecution: number | null

createdAt: 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

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.

Security Model

Trust Assumptions

- Condition evaluation is deterministic

- At least one honest executor exists

- Network (Base) is available

Guarantees

- Execution Correctness: Invalid executions are detected via fraud proofs

- Liveness: Economic incentives ensure timely execution

- MEV Resistance: Commit-reveal prevents front-running

Current Limitations (MVP)

- Execution is simulated, not on-chain

- No actual staking or slashing

- Single network (Base) only

Production Roadmap

- On-chain execution via ethers.js

- Executor staking with slashing

- Multi-chain adapters

- ZK validity proofs for instant finality

FAQ

Is this a production system? No. This is an MVP demonstrating execution infrastructure concepts. Execution is simulated.

What network is supported? Base (EVM) is the primary and only supported network.

How do I become an executor? Executor participation is not available in MVP. The execution loop runs server-side.

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

Can I use this for real transactions? No. MVP does not execute real on-chain transactions. It demonstrates the execution control layer.