🧬 Helix
Self-healing infrastructure for AI agent payments. 31 scenarios across 5 platforms — Tempo, Privy, Uniswap, Base, and HTTP.
Two lines of code. Any platform. Every failure fixed once, remembered forever.
Developer Quickstart View on GitHub

## Supported Platforms

One SDK, every platform. Failures healed across all of them.

◆ Tempo / MPP
31 scenarios
✓ Full coverage
◇ Privy Wallets
4 scenarios
✓ Full coverage
○ Generic HTTP
3 scenarios
✓ Full coverage
◊ Stripe
Coming soon
🔜

## Developer API Reference

Add self-healing to any payment agent in 30 seconds.

// Step 1: Install npm install @helix-agent/core // Step 2: Wrap your agent import { wrap } from '@helix-agent/core'; // Your existing payment code — unchanged const payInvoice = async (invoice) => { const res = await fetch('https://mpp.service.com/v1/pay', { method: 'POST', headers: { 'Authorization': `Bearer ${MPP_TOKEN}` }, body: JSON.stringify({ amount: invoice.amount, currency: 'USDC' }), }); if (!res.ok) throw new Error(`Payment failed: ${res.status}`); return res.json(); }; // One line. Same input, same output. Self-healing is transparent. const resilientPay = wrap(payInvoice); // Call it exactly like before const result = await resilientPay(invoice); // If it fails → PCEC auto-repairs → retries → you get the result

### Platform Integration Examples

// Tempo / MPP const resilientFetch = wrap(fetch); const data = await resilientFetch('https://openai.mpp.tempo.xyz/v1/chat/completions', { ... }); // Privy Wallets const resilientSign = wrap(privy.wallets.ethereum.signTransaction); const tx = await resilientSign(walletId, { to: '0x...', value: '100' }); // Any HTTP Service const resilientCall = wrap(fetch); const result = await resilientCall('https://any-api.com/endpoint'); // 429? 500? Timeout? Helix handles it.

### Before & After

❌ Without Helix const pay = async (inv) => { const res = await fetch(url); if (!res.ok) throw new Error(); return res.json(); }; // 402? Agent crashes. // Session expired? Dead. // Wrong currency? Manual fix. // Same error tomorrow? Same crash.
⚡ With Helix import { wrap } from '@helix-agent/core'; const pay = wrap(async (inv) => { const res = await fetch(url); if (!res.ok) throw new Error(); return res.json(); }); // 402? Auto-swaps currency. // Expired? Auto-renews session. // Same error? Instant immune fix.

### Three Integration Levels

import { wrap } from '@helix-agent/core'; // Wrap ANY async function. That's it. const resilientPay = wrap(payInvoice); const resilientSwap = wrap(dexSwapFunction); const resilientTransfer = wrap(batchTransferFunction); // Options (all optional) const resilientPay = wrap(payInvoice, { agentId: 'payroll-bot', // identifies this agent in logs maxRetries: 3, // default 3 verbose: true, // log PCEC steps to console }); // wrap() returns IDENTICAL function signature // TypeScript types are preserved — no type changes needed
wrap() is a transparent proxy. The caller doesn't know Helix exists. Input types, output types, error types — all preserved. Your tests don't change. Your calling code doesn't change.
import { createEngine, GeneMap } from '@helix-agent/core'; const { engine, geneMap } = createEngine({ projectName: 'payroll-agent', geneMapPath: './my-genes.db', }); // Use in your own try/catch flow try { await payEmployee(invoice); } catch (error) { const result = await engine.repair(error, { agentId: 'payroll-agent', walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18', availableBalances: { USDC: 1200, EURC: 500, USDT: 300 }, }); if (result.success) { console.log(`Repaired via ${result.winner.strategy} in ${result.totalMs}ms`); await payEmployee(invoice); // retry } else { console.error('Beyond repair:', result.failure.details); notifyOperator(result.failure); } } // Check engine stats const stats = engine.getStats(); // { repairs: 47, savedRevenue: 12500, immuneHits: 31, geneCount: 12 }
createEngine() for custom error handling, inspecting repair results before retrying, or passing rich context (wallet balances, session state) to PCEC.
import { perceive, construct, evaluate, commit } from '@helix-agent/core'; import { GeneMap } from '@helix-agent/core'; const geneMap = new GeneMap('./genes.db'); // P — Perceive: classify the failure const failure = perceive(error, context); // → { code: 'payment-insufficient', category: 'balance', severity: 'high', // actualBalance: 12.50, requiredAmount: 500 } // Check Gene Map first (immunity check) const existingGene = geneMap.lookup(failure.code, failure.category); if (existingGene) { console.log(`IMMUNE: ${existingGene.strategy}`); // Skip C+E, apply known fix } // C — Construct: generate repair candidates const candidates = construct(failure, geneMap); // E — Evaluate: score and rank const ranked = evaluate(candidates, failure); // ranked[0] = { strategy: 'swap_currency', score: 96, ... } // K — Commit: execute the winning strategy const result = await commit(ranked[0], failure, context); // Store Gene Capsule for next time if (result.success) { geneMap.store({ failureCode: failure.code, category: failure.category, strategy: ranked[0].strategy, params: { description: ranked[0].description }, successCount: 1, avgRepairMs: totalMs, }); }
Individual PCEC steps exported for maximum flexibility. Build custom repair pipelines, add your own scoring, or create audit trails. Every function is pure and testable.

### Gene Map API

import { GeneMap } from '@helix-agent/core'; const geneMap = new GeneMap('./helix-genes.db'); // SQLite file // Or: new GeneMap(':memory:') for testing // ── Query ── geneMap.lookup('payment-insufficient', 'balance'); // → GeneCapsule | null geneMap.list(); // → GeneCapsule[] sorted by successCount DESC geneMap.immuneCount(); // → number of unique patterns with known fixes geneMap.getSuccessRate('payment-insufficient', 'swap_currency'); // → 0.92 (92% from history) or 0.5 if < 3 samples // ── Store ── geneMap.store({ failureCode: 'payment-insufficient', category: 'balance', strategy: 'swap_currency', params: { fromToken: 'EURC', toToken: 'USDC' }, successCount: 1, avgRepairMs: 380, }); // INSERT or UPDATE — auto-increments successCount on conflict geneMap.close(); // close SQLite connection

### CLI Reference

Command | Description
--- | ---
npx helix init | Interactive setup wizard → generates helix.config.json
npx helix status | Live PCEC event stream in terminal (colored P→C→E→C)
npx helix dash | Start dashboard server (Minecraft lab + benchmark)
npm run demo | Run 31 failure scenarios across 5 platforms + cross-platform immunity
npm run demo:tempo | Tempo-only demo (31 scenarios + immunity round)
npm run demo:privy | Privy demo with cross-platform immunity from Tempo Genes
npm run benchmark | HumanEval benchmark (needs OPENAI_API_KEY) — 68%→90%
helix gene list | Phase 2: List all local Gene Capsules
helix gene push | Phase 2: Push Genes to HGP Network
helix gene pull | Phase 2: Pull community Genes

### Configuration — helix.config.json

{ "projectName": "my-payment-agent", // your agent's name "walletAddress": "0x742d...f2bD18", // Tempo wallet for repairs "stablecoins": ["USDC", "EURC", "USDT"], // available for swaps "monthlyBudget": 10000, // repair cost cap (USD) "maxRetries": 3, // PCEC attempts before giving up "timeoutMs": 30000, // per-repair timeout "dashboardPort": 7842, // dashboard server port "verbose": true, // log PCEC to console "geneMapPath": "./helix-genes.db" // SQLite file location }
monthlyBudget is a safety cap — PCEC won't execute repairs that exceed this budget. All candidates have cost estimates, and Evaluate rejects above threshold. Your wallet's signing key never touches the Gene Map.
TypeScript Types Reference click to expand
// What wrap() returns type WrappedFunction<T> = (...args: Parameters<T>) => ReturnType<T>; // What repair() returns interface RepairResult { success: boolean; failure: FailureClassification; candidates: RepairCandidate[]; winner: RepairCandidate | null; gene: GeneCapsule | null; immune: boolean; // true = Gene Map hit, instant fix totalMs: number; revenueProtected: number; } // What Perceive outputs interface FailureClassification { code: MppErrorCode; // 'payment-insufficient' | 'invalid-challenge' | ... category: FailureCategory; // 'balance' | 'session' | 'currency' | ... severity: Severity; // 'low' | 'medium' | 'high' | 'critical' details: string; timestamp: number; actualBalance?: number; requiredAmount?: number; } // What Construct generates interface RepairCandidate { id: string; strategy: string; description: string; estimatedCostUsd: number; estimatedSpeedMs: number; requirements: string[]; score: number; // 0-100, set by Evaluate successProbability: number; // from Gene Map history } // What Gene Map stores interface GeneCapsule { failureCode: MppErrorCode; category: FailureCategory; strategy: string; params: Record<string, unknown>; successCount: number; avgRepairMs: number; }

## The Problem

AI agents process millions of payments. When one fails, nobody's home to fix it.

### Silent Failures

Agent gets HTTP 402. Insufficient balance. No fallback. No retry logic. The task dies silently and revenue evaporates.

### Currency Blindness

Agent holds EUR stablecoins but the service demands USDC. Manual swap required. Meanwhile the window closes.

### Zero Memory

Agent pays for inference 1,000 times but learns nothing. Same balance failure hits every night at 2am. Nobody notices until morning.

Traditional payment failure rate: 2–4%. Agent payment failure rate: 5–8%.
On $10T/day projected agent volume, that's $500B+ at risk.

## How It Works — PCEC

Four steps. Sub-second. Fully autonomous.

P

### Perceive

Parse MPP 402 error response. Classify failure into one of 10 categories. Assess severity.

→
C

### Construct

Generate 2–3 repair candidates. Each has estimated cost, speed, and requirements.

→
E

### Evaluate

Score each candidate 0–100. Pick optimal strategy based on cost, speed, and success history.

→
C

### Commit

Execute the repair. Retry the original payment. Store a Gene Capsule in the Gene Map.

Gene Capsules accumulate over time. When the same failure type recurs → skip C+E → apply the known fix instantly. That's the network effect.

## What Helix Fixes

31 failure scenarios across 5 platforms — Tempo, Privy, Uniswap, Base, Generic HTTP. Cross-platform Gene immunity proven.

# | Failure | MPP Error | Helix Repair | Status
--- | --- | --- | --- | ---
1 | Insufficient Balance | payment-insufficient | Swap alt stablecoin via Tempo DEX | LIVE
2 | Session Expired | invalid-challenge | Auto-renew MPP session | LIVE
3 | Currency Mismatch | method-unsupported | Swap to required asset via DEX | LIVE
4 | Signature Failure | verification-failed | Refresh nonce from Tempo RPC | LIVE
5 | Batch Revert | tx-reverted | Remove failed item, resubmit batch | LIVE
6 | Service Down | HTTP 500 + receipt | Retry with MPP receipt (idempotent) | MOCK
7 | DEX Slippage | swap-reverted | Split into smaller swaps | MOCK
8 | Compliance Block | tip-403 | Switch to unrestricted stablecoin | MOCK
9 | Cascade Failure | cascade-failure | Refund waterfall C→B→A | VISION
10 | Off-Ramp Failure | offramp-failed | Switch off-ramp provider | VISION
11 | Token Pause | token-paused | Switch to unpaused stablecoin | MOCK
12 | Fee Sponsor Empty | sponsor-insufficient | Fallback to self-pay gas | MOCK
13 | Network Mismatch | token-uninitialized | switch_network / bridge_tokens | REAL
PRIVY WALLET
14 | Policy Spending Limit | policy-violation | Split into sub-limit transactions | PRIVY
15 | Nonce Desync | verification-failed | refresh_nonce (cross-platform ⚡) | PRIVY
16 | Gas Sponsor Exhausted | payment-insufficient | self_pay_gas (cross-platform ⚡) | PRIVY
17 | Cross-Chain Mismatch | token-uninitialized | switch_network (cross-platform ⚡) | PRIVY
GENERIC HTTP
18 | 429 Rate Limited | rate-limited | backoff_retry / switch_endpoint | HTTP
19 | 500 Server Error | server-error | retry / switch_provider | HTTP
20 | Request Timeout | timeout | retry with increased timeout | HTTP

⚡ CROSS-PLATFORM IMMUNITY
Gene Map stores by `(code, category)` — not by platform. A fix learned from Tempo automatically heals the same failure on Privy or any other platform.
Example: Tempo agent hits nonce error → Gene stored → Later, Privy agent hits nonce desync → Gene Map hit → IMMUNE ⚡ Instant fix, zero cost.
Scenarios #15, #16, #17 are healed instantly by Genes learned from Tempo scenarios #4, #12, #13. Run `npm run demo` to see this live.
🔴 REAL-WORLD VALIDATION
Scenario #13 is not simulated. We ran `npx mppx` against 50+ live MPP services and hit this error in production.
`$ npx mppx https://mpp.dev/api/ping/paid`
→ ✓ “tm! thanks for paying” (testnet, success)
`$ npx mppx https://openai.mpp.tempo.xyz/v1/chat/completions`
→ ✗ TIP20 token error: Uninitialized(Uninitialized) (mainnet, failure)
This is the exact failure an agent hits when it has testnet tokens but calls a mainnet MPP service. 50+ services on mpp.dev/services are mainnet-only today.
Without Helix: agent crashes. With Helix: PCEC detects network mismatch, switches RPC.

## Use Cases

Anywhere AI agents move money.

### Agentic Commerce

AI agents purchasing APIs, data feeds, and compute via MPP. Helix ensures every payment completes, even when balances shift mid-task.

### Cross-Border Payroll

1,000 employees across 5 currencies. Batch payments with auto-recovery on compliance blocks, nonce collisions, and partial reverts.

### Micro-Payments

Pay-per-token LLM inference at sub-cent granularity. Session management with auto-renewal. Never lose a stream mid-generation.

## Architecture

One function call between your agent and bulletproof payments.

#### Your Agent Code

fetch(), axios, any HTTP client

↓ wrap() — 2 lines

#### Helix SDK Layer

PCEC Engine + Gene Map + EventBus

↓

#### MPP Protocol

HTTP 402 + payment challenges + credentials

↓

#### Tempo Blockchain

Payment Lanes + DEX + TIP-20 Stablecoins

## Deep Dive: System Architecture

The full vision — 4 layers, 12 components, an evolving payment operating system for AI agents.

EVOLUTION FEEDS BACK ↑
User Objective
Agent receives a goal from the user
↓ Objective Decomposition Engine

### ① Intent Understanding

PLANNING & DECOMPOSITION
Intent Parser ROADMAP
Parse & validate goals
click to expand
What

Understands natural language objectives. “Pay 100 employees in 5 currencies” → structured intent with parameters, constraints, and success criteria.

Why

Without this, developers must hard-code every task. With it, agents understand open-ended objectives and can plan autonomously.

Helix

Not yet implemented. Currently the agent’s goal is defined by the developer in code. Phase 3 feature.

Task Dependency Graph ROADMAP
Build execution order
click to expand
What

Decomposes a complex goal into a DAG of subtasks: [check balance] → [swap currencies] → [batch transfer] → [verify receipts]. Handles parallel, serial, and conditional branches.

Why

Real-world agent tasks are multi-step. A flat retry loop can’t handle “step 3 failed but steps 1–2 already executed.”

Helix

Not yet. Currently `wrap()` handles single function calls. Multi-step orchestration is Phase 3.

Execution Orchestrator ROADMAP
Dispatch & coordinate
click to expand
What

Executes the DAG — dispatches tasks to the right executor, handles timeouts, tracks progress, manages rollback if needed.

Why

This is the scheduler. Like Airflow for agent tasks, but with PCEC self-repair at every step.

Helix

Not yet. Currently agent runs single function, `wrap()` catches errors. Full orchestration is Phase 3.

↓ Execution Layer

### ② Distributed Execution

SKILLS & COORDINATION
Skills Framework BUILT
Concrete repair techniques
click to expand
What

The specific “how-to” repair strategies. Each skill is a concrete action: `swap_currency`, `renew_session`, `retry_with_receipt`, `split_swap`, `refresh_nonce`, `switch_stablecoin`.

Why

PCEC Construct generates candidates FROM the skills library. Skills are the atoms of repair.

Helix

Fully implemented. 31 failure categories × 2–3 strategies each = ~25 skills in `pcec.ts`. Each skill has cost estimate, speed estimate, and requirements list.

Experience Layer PARTIAL
Causal meta-learning
click to expand
What

Not just “what worked” but “WHY it worked and WHEN to use it.” Extracts causal reasoning: “EURC→USDC swap works better at UTC 2–4am because DEX liquidity is higher.”

Why

Skills alone are a toolbox. Experience tells you which tool to grab before you even open the box. This is the meta-learning layer.

Helix

Gene Map stores success/failure history — `success_count`, `avg_repair_ms`, `last_used_at`. But it doesn’t yet extract causal patterns. The data is there; the reasoning layer is Phase 2.

Multi-Agent Mesh ROADMAP
Distributed execution
click to expand
What

Multiple agents collaborating on a single objective. Agent A handles currency swaps, Agent B handles execution, Agent C handles verification. They communicate via the mesh and share state.

Why

Complex payment workflows (cascade A→B→C, batch payroll across corridors) need distributed execution. One agent can’t hold all the context.

Helix

Cascade scenario (#9) demonstrates the concept — A→B→C failure chain with refund waterfall. True mesh execution is Phase 3.

↓ Resilience Layer

### ③ Self-Healing & Confidence

CORE OF HELIX
PCEC Engine BUILT
Self-repair loop — the heart of the system
click to expand
What

Perceive → Construct → Evaluate → Commit. Classifies every failure into 10 categories, generates repair candidates, scores by cost/speed/history, executes the best one, stores the result.

Why

This is what makes Helix different. It doesn’t just retry — it understands what broke and picks the optimal fix.

Helix

Fully implemented. `src/core/pcec.ts` — complete P/C/E/K loop with all 31 failure handlers. Proven by HumanEval benchmark: 68% → 90%. Perceive parses MPP 402 errors (RFC 9457). Evaluate scores by speed (30pts), cost, requirements, severity matching.

Predictive Failure Engine ROADMAP
Anticipate before failure
click to expand
What

Uses Gene Map history to predict failures BEFORE they happen. “This service has failed 3 times this week at 2am. It’s 1:55am. Pre-emptively switch to backup.”

Why

Reactive repair (PCEC) costs time and sometimes money. Predictive avoidance costs nothing — you just don’t go down the bad path.

Helix

Not yet. But the data is accumulating in Gene Map. Every repair creates a timestamped Gene Capsule. The prediction layer just needs to read those patterns. Phase 2.

Confidence Layer PARTIAL
Uncertainty bounds
click to expand
What

Assigns a confidence score to every repair. “95% confident this swap will work” vs “40% confident this timeout increase will help.” Enables risk-adjusted decisions.

Why

Without confidence, PCEC is a black box. With it, the agent can decide: low confidence? Ask the human. High confidence? Just do it.

Helix

Evaluate scores (0–100) are a simplified confidence. Based on speed/cost/requirements math. Not yet probabilistic (would need historical success rates per strategy per context). Phase 2.

↓ Evolution Layer

### ④ Compounding Moat

NETWORK EFFECT
Gene Map BUILT
Shared knowledge network
click to expand
What

SQLite database storing every successful repair as a Gene Capsule: `failure_code`, `category`, `strategy`, `params`, `success_count`, `avg_repair_ms`. Lookup by pattern → instant fix if seen before (“immune”).

Why

This is the learning mechanism. 9 of 14 failures in our benchmark were resolved by Gene Map hits — instant, zero-cost.

Helix

Fully implemented. `src/core/gene-map.ts` — SQLite with WAL mode. `lookup()` returns existing gene + increments success_count. `store()` upserts.

Vision

Currently local to each agent. Phase 2: `helix gene push/pull` for community sharing. Phase 3: on-chain Gene Registry where contributors earn micropayments.

Gene Economy ROADMAP
Incentive marketplace
click to expand
What

Agent A discovers a repair strategy → pushes Gene Capsule to public registry → Agent B pays micropayment (via MPP session) to use it → Agent A earns revenue. Reputation scoring ensures quality.

Why

Open-source contributions need incentives at scale. You fix one failure, everyone benefits, you get paid. Network effect with economic gravity.

Helix

Not yet implemented. But Gene Capsules are already structured JSON records that can be serialized, shared, and verified. Phase 3.

Execution Replay PARTIAL
Deterministic audit trail
click to expand
What

Every PCEC repair can be replayed deterministically. Same input error + same Gene Map state + same time → identical repair path. Enables debugging, auditing, and compliance.

Why

Financial systems need audit trails. Agents operating autonomously need even more accountability than human operators.

Helix

Benchmark uses seed-based replay (seed=42 produces identical results). SSE event bus logs all PCEC steps. No formal replay mechanism yet. Phase 2.

↓
World / External Services
Tempo blockchain · MPP services · DEX pools · Off-ramp providers
BUILT Implemented & proven PARTIAL Data exists, reasoning layer next ROADMAP Designed, not yet built

## Developer Quickstart

From zero to self-healing in under a minute.

STEP 1

### Install

    npm install @helix-agent/core

STEP 2

### Initialize

    npx helix init
    # → walks you through: wallet, stablecoins, budget, retries
    # → writes helix.config.json

STEP 3

### Wrap your agent

    import { wrap } from '@helix-agent/core';

    const myAgent = async (input: string) => {
      const res = await fetch('https://api.example.com/v1/data');
      return res.json();
    };

    // That's it. Same input, same output. Self-healing is transparent.
    const resilientAgent = wrap(myAgent);

STEP 4

### Monitor

    npx helix status   # Terminal: live repair logs
    npx helix dash     # Browser: Minecraft lab at localhost:3710

## Competitive Landscape

Helix is purpose-built for the agent payment era.

Capability | Raw MPP | x402 | Stripe Retries | Helix
--- | --- | --- | --- | ---
Agent payments (HTTP 402) | ✓ | ✓ | × | ✓
Self-repair on failure | × | × | × | ✓
Cross-currency swap | × | × | × | ✓
Learning from failures | × | × | × | ✓
Network effect (Gene Map) | × | × | × | ✓
Multi-stablecoin | ✓ | × | × | ✓
Batch recovery | × | × | × | ✓

## The Numbers

The market for agent payment infrastructure is just beginning.

$1.8T/day

Processed by Visa/Mastercard today. Agent commerce will dwarf this within a decade.

$3–5T

Projected agent commerce by 2030 (World Economic Forum / Sam Altman estimates).

5–8%

Agent payment failure rate. On $10T/day volume, that's $500B+ at risk annually.

0.1%

Helix charges on recovered value. Gene Map network effect: more agents = more resilient = more agents.

## Four Failure Philosophies

Helix doesn't just retry. It understands what kind of failure it's facing.

🔧

### Active Repair

Detect → generate candidates → score → execute the best fix → retry

Examples: Swap currency, renew session, refresh nonce, split swap
Scenarios #1–7
🛡️

### Compliance Reroute

Regulatory block detected → find an alternative compliant path → reroute

Examples: Switch stablecoin to avoid KYC restriction, route via compliant wallet
Scenario #8
⏱️

### Temporal Awareness

Policy changed mid-flight → detect the timing of the change → rebuild tx under new rules

Examples: TIP-403 policy updated between blocks, tx reverted after gas spent → query new policy, resubmit
Phase 2
Not just “what failed” but “when it failed relative to what changed”
🧊

### Intelligent Wait

Failure detected as unresolvable on-chain → don't waste gas retrying → monitor and auto-resume when conditions change

Examples: Reward claim blocked by blacklist → wait for policy review → auto-claim when cleared
Phase 2
Knowing when NOT to act is the mark of a mature system
“Most self-healing systems only know how to retry. Helix knows how to repair, reroute, wait, and evolve. That's the difference between a retry wrapper and an operating system.”

## Evolution Roadmap

How Helix grows from a repair engine to an adaptive intelligence.

### Deterministic PCEC + Gene Map

CURRENT HACKATHON DEMO
Fixed repair strategies for known failure patterns. Every repair stored as Gene Capsule. 31 failure types, ~26 strategies, 9 immune hits in benchmark.
Bounded error space (7 MPP codes + 3 Tempo-specific). Evaluate scores by speed/cost/requirements/successProbability. Gene Map in SQLite with WAL mode.
Limitation: Can only handle failures it's been programmed for. Unknown error codes → fallback to human.

### LLM Fallback for Unknown Failures

NEXT Q2 2026
When Gene Map has no match, PCEC sends the full failure context to an LLM. The LLM generates repair candidates. Candidates are validated in a sandbox before execution. Successful repairs are written back to Gene Map — tagged with `source: 'llm'` and low initial confidence.
Unknown failure → Gene Map lookup: MISS → Send to LLM: { errorCode, message, wallet state, protocol context } → LLM returns: 2–3 repair candidates with reasoning → Sandbox validation: test each candidate against constraints → Execute best candidate → Success → Store Gene Capsule { source: 'llm', confidence: 0.6 } → Confidence increases with each successful reuse

    interface GeneCapsule {
      // existing fields...
      source: 'pcec' | 'llm' | 'human' | 'community';
      confidence: number;  // 0-1, starts low for LLM, increases with use
    }

Key insight: LLM-generated Genes enter the same Gene Map as PCEC Genes, but with lower initial trust. As they're validated by real production usage, confidence rises naturally. This is how the system absorbs new knowledge without compromising reliability.

### Evolutionary Parameter Optimization

VISION Q3–Q4 2026
Gene strategies have parameters — slippage tolerance, split count, wait time. These parameters need different optimal values under different market conditions. Evolution algorithms search the parameter space, finding optimal configurations per context.
Gene: swap_currency Parameter space: slippage: [0.5%, 1%, 2%, 3%] splitCount: [1, 2, 3, 5] maxWaitMs: [500, 1000, 2000, 5000] Evolution maintains a population of parameter combinations Successful combinations → higher fitness → survive Failed combinations → eliminated Periodic mutations → explore new configurations Result: Each Gene adapts to its environment automatically
Key insight: Evolution doesn't create new strategies — it tunes existing ones. The LLM creates new Genes. Evolution makes them better over time. Together: the system both discovers and optimizes.
This architecture answers two questions judges always ask:
1. “What if you encounter an unknown failure?” → LLM Fallback generates and validates new Genes
2. “Do Gene strategies go stale?” → Evolution continuously optimizes parameters against real conditions

## Open Gene Registry

Every agent's repair makes every other agent smarter.

### Local Gene Map

CURRENT
Each agent stores its own repair history in local SQLite. Gene Capsules record: what failed, how it was fixed, and how fast.

    helix gene list → shows all local genes

### Community Gene Registry

Q2 2026
Agents push successful Gene Capsules to a shared registry. Other agents pull proven fixes. Like npm for payment reliability.

    helix gene push balance→swap  |  helix gene pull --popular

Fix one failure → every agent on the network is immune.

### On-Chain Gene Economy

Q3 2026
Gene Capsules go on-chain via Tempo. Contributors earn micropayments (via MPP sessions) every time their gene is used. Reputation scoring ensures quality.

    helix gene publish --on-chain  → earns 0.001 USDC per use

Open-source incentivized by the protocol itself.

    interface GeneCapsule {
      failureCode: string;
      category: string;
      strategy: string;
      params: Record<string, any>;
      successCount: number;
      avgRepairMs: number;

      // Source tracking for trust levels
      source: 'pcec' | 'llm' | 'human' | 'community';
      confidence: number;  // 0-1, starts low for LLM/community

      // Registry metadata
      author?: string;        // agent address that created this gene
      usageCount?: number;    // total times used across all agents
      reputation?: number;    // community rating 0-5
    }

PCEC genes start at confidence 1.0. LLM-generated genes start at 0.6. Community genes start at 0.7. Confidence rises with each successful use.

## LLM Fallback for Unknown Failures

When the Gene Map doesn't have an answer, AI generates one.

Unknown
Error
→
Gene Map
MISS
→
Send to
LLM
→
Sandbox
Validate
→
Store as
New Gene
WHAT GETS SENT TO THE LLM

    {
      errorCode: "unknown-error-xyz",
      fullMessage: "Transaction reverted: reason unknown",
      walletState: { balance: "1200 USDC", nonce: 42 },
      protocolContext: "Tempo mainnet, TIP-20, block #4829301",
      previousAttempts: ["retry_failed"]
    }

WHAT COMES BACK

    [
      { strategy: "increase_gas_limit",
        confidence: 0.7 },
      { strategy: "switch_rpc_endpoint",
        confidence: 0.5 },
      { strategy: "wait_and_retry",
        confidence: 0.3 }
    ]

Key insight: Each LLM call costs ~$0.01 and takes ~2 seconds. But it only happens ONCE per unknown failure type. After that, the result is a Gene Capsule — every future occurrence is handled instantly at zero cost. The LLM call rate converges to near-zero over time.

## Deep Spec Analysis — Additional Failure Scenarios

Edge cases identified from TIP-20, TIP-403, Fee AMM, and Tempo Transactions specifications.

20 scenarios across 3 platforms. 13 Tempo. 4 Privy. 3 Generic HTTP. Cross-platform Gene immunity proven.
#13 Fee AMM Liquidity Gap Fee AMM Spec PHASE 2 ›

Problem: Agent uses EURC to pay gas. Fee AMM converts EURC→AlphaUSD (validator's preferred token). But if the EURC→AlphaUSD pool has zero reserves, the fee conversion fails and the entire transaction cannot be submitted.

Why this is tricky (chicken-and-egg): The naive fix is “swap to a stablecoin that has Fee AMM liquidity.” But if Fee AMM has no liquidity for your current token, you can't even pay gas to execute the swap. You're stuck.

Perceive: fee-conversion-failed EURC→AlphaUSD Fee AMM pool reserves = 0 Construct: Candidate 1: Use fee sponsorship to bootstrap → Find sponsor that pays gas in AlphaUSD → Submit DEX swap using sponsored gas Score: 88 Candidate 2: Switch to AlphaUSD (guaranteed liquidity) → AlphaUSD IS the target — no conversion needed Score: 95 (if AlphaUSD balance > 0) Candidate 3: Use different fee token with active pool → Query Fee AMM for all pools with reserves > 0 Score: 82 Gene: Map of active Fee AMM pools with reserve levels → Pre-check pool liquidity before choosing fee token
Pitch note: “This is a Tempo-unique failure. Other chains use native gas tokens. Tempo's stablecoin-native fee system is elegant but creates this edge case. Helix handles it.”
#18 TIP-403 Mid-Flight Policy Change TIP-403 Registry PHASE 2 ›

How this differs from #8: Scenario #8 = STATIC block (error before tx). Scenario #18 = DYNAMIC change. Policy changes DURING block confirmation, tx reverts mid-flight. Gas already consumed.

Perceive: policy-changed-mid-flight tx 0xABC... submitted to mempool TIP-403 policyId changed 5 → 7 between blocks #4829301 and #4829302 New policy blacklisted agent — tx reverted, gas consumed Construct: Candidate 1: Query new policy → find compliant path → retry → Read policyId 7, find authorized intermediary → Route payment through compliant path Score: 88 Candidate 2: Store intent → monitor → auto-retry → Set watcher on TIP403Registry.PolicyUpdated → Auto-resubmit when agent re-authorized Score: 65 Gene: UNIQUE data that #8's Gene cannot store: • Policy change block range • Token + jurisdiction combination • Time-of-day pattern for policy changes → PREDICTIVE: Pre-warn before revert happens
Pitch note: “#8 catches policy blocks you can see coming. #18 catches changes that happen while your tx is in flight. It's a red light vs. a light that turns red while you're in the intersection. Helix handles both.”
#20 Reward Claim Blocked by Policy TIP-20 Rewards + TIP-403 PHASE 2 ›

Problem: TIP-20 reward operations (distributeReward, claimRewards) ALL perform TIP-403 checks. A blacklisted address cannot claim accumulated rewards.

Dead-end analysis:

✗ Candidate 1: setRewardRecipient() to change to non-blacklisted address → This tx ITSELF requires TIP-403 authorization → Blacklisted address can't execute it — DEAD END ✗ Candidate 2: Ask operator for whitelist exemption → Requires human-in-the-loop — too slow ✓ Candidate 3: Intelligent Wait ← CORRECT PATH → Do NOT execute claim (save gas) → Set EventWatcher on TIP403Registry for policyId changes → Monitor: is address removed from blacklist? → When removed → auto-trigger claimRewards() Score: 92 Gene: Record: • Address blacklist status • Policy review cycle estimate (from historical data) • Pending reward amount → Next time: skip claim attempt entirely — no wasted gas
Strongest “Intelligent Wait” example: “Most systems would retry and burn gas every time. Helix recognizes this failure CANNOT be fixed on-chain. The correct action is no action — monitor and wait. That's the difference between a retry loop and an intelligent system.”
#12b InvalidRecipient Address Error TIP-20 validRecipient ORAL ›

Problem: TIP-20 tokens cannot be sent to other TIP-20 contract addresses (prefix 0x20c000...). Reverts with `InvalidRecipient`. Prevents permanent token loss.

Why auto-fix is impossible: Helix does NOT know the “correct” address. This requires external input.

Construct: Candidate 1: Abort + notify with detailed error → "Recipient is a TIP-20 contract, not a user address" Score: 90 (only viable option) Candidate 2: Auto-resolve correct address — IMPOSSIBLE Gene: Mark address as CONTRACT_ADDRESS → Pre-flight check catches it BEFORE submitting tx → Saves gas by preventing known-bad transactions
Key insight: Not every failure should be auto-repaired. Helix knows the difference between “wrong currency” (fixable) and “wrong address” (needs human). The Gene Map still prevents the same mistake from costing gas twice.
#19 Memo Overflow (32-byte limit) TIP-20 Memo Field ORAL ›

Problem: TIP-20 transfers support a 32-byte memo. If an agent attaches a longer memo, the transfer reverts.

Construct: Candidate 1: Hash memo → store full text off-chain → SHA256(full_memo)[0:32] as on-chain memo → Store { hash → full_memo } in local DB Score: 94 Candidate 2: Truncate to 32 bytes — loses information Score: 45 Gene: Auto-detect long memos and pre-hash before submission → Prevents the revert entirely on future calls
— Excluded Scenarios (3) Analyzed & rejected EXCLUDED ›

#14 DEX Crossed Order — Historical bug fixed by TIP-1002. No longer occurs on current Tempo mainnet. Using a fixed bug undermines credibility.

#15 DEX Rounding Loss — Silent error: no revert, no error signal. Agent receives slightly less tokens. PCEC requires an explicit error to trigger. Would need proactive reconciliation (different architectural pattern).

#16 Scheduled Payment Window Expired — Time window expiry implies business-level semantic change. Helix lacks business context to determine if re-scheduling is appropriate. Requires human-in-the-loop.

Why we document exclusions: Showing what we rejected — and why — demonstrates deeper technical rigor than just listing everything.

## Helix Gene Protocol (HGP)

A chain-verified knowledge protocol for payment failure repair.

“Every Helix repair writes a Gene. When enough agents run Helix, no payment failure needs to be solved twice. HGP is the immune system for payment agents.”

### What is an HGP Gene?

interface HelixGene { id: string; // sha256(errorCode + context + strategy) // ── Failure Context (what broke and why) ────────── failure: { errorCode: MppErrorCode; // payment-insufficient, verification-failed, ... chain: 'tempo' | 'base' | 'solana'; tokenIn: string; // what the agent held (EURC) tokenRequired: string; // what was needed (USDC) amountDelta: number; // shortfall amount sessionState: 'fresh' | 'expired' | 'corrupted'; }; // ── Repair Path (how PCEC fixed it) ─────────────── repair: { strategy: RepairStrategy; // swap | topup | refresh | fallback | wait stepsExecuted: Step[]; // complete execution trace timeToResolve: number; // milliseconds costIncurred: number; // gas + swap fees in USD successRate: number; // lifetime success rate (0-1) }; // ── On-Chain Proof (verifiable on Tempo) ────────── proof: { txHash: string; // the actual repair transaction blockHeight: number; validatedAt: number; // unix timestamp }; // ── Applicability Bounds ────────────────────────── applicability: { minBalance: number; // works when balance >= this maxBalance: number; // tested up to this amount supportedChains: string[]; protocolVersion: string; // e.g. "tempo-v1.2" expiresAt: number; // protocol upgrades may invalidate }; }

#### Failure Context

Records EXACT conditions — not just the error code, but token pair, shortfall amount, session state. Two ‘payment-insufficient’ errors with different token pairs need different fixes.

#### Repair Path

Complete execution trace from PCEC’s Commit phase. Strategy, steps, timing, cost, and lifetime success rate. A new agent knows exactly what will happen.

#### On-Chain Proof

Every Gene is anchored to a real Tempo transaction. Verify on-chain that this repair actually happened. Cryptographically proven repair knowledge.

#### Applicability Bounds

Genes work within specific balance ranges, chains, and protocol versions. Stale Genes auto-expire via `expiresAt`. The protocol is self-cleaning.

### Three-Layer Protocol Architecture

#### Layer 3: Gene Inheritance (new agent cold start)

New Helix instance comes online → queries HGP Network for its chain + token config → downloads top-rated Genes for each error category → pre-populates local Gene Map. Day 1 performance = network veteran.

“Zero cold start. Your first failure is already immune.”
↑ pull

#### Layer 2: Gene Validation & Broadcast (cross-instance)

Local Genes submitted to HGP Network periodically. Network performs: a) Deduplication — merge same-pattern Genes. b) Quality scoring — successRate × usage × proof. c) Broadcast — push to subscribers of that errorCode.

“Quality rises organically. Bad Genes die. Good Genes propagate. Natural selection for repair strategies.”
↑ push

#### Layer 1: Gene Generation (single instance)

PCEC repairs a payment failure → auto-generates HGP Gene with full context → stores in local Gene Map (SQLite). Gene includes failure context + repair path + proof.

“Every repair creates knowledge. Automatically.”
# Layer 1: Local gene created after repair $ helix gene list ┌────────────────────┬───────────────┬────────┬───────┐ │ Gene ID │ Failure │ Strat │ Succ │ ├────────────────────┼───────────────┼────────┼───────┤ │ 0xa3f2... │ pay-insuf │ swap │ 14/14 │ │ 0xb8c1... │ session-exp │ renew │ 9/9 │ │ 0xd4e7... │ token-paused │ switch │ 3/3 │ └────────────────────┴───────────────┴────────┴───────┘ # Layer 2: Push to network $ helix gene push --all Pushed 3 genes to HGP Network. Waiting for validation... ✓ 0xa3f2 validated (txHash verified on Tempo block #4829301) ✓ 0xb8c1 validated (txHash verified on Tempo block #4829445) ✓ 0xd4e7 validated (txHash verified on Tempo block #4830102) # Layer 3: New instance inherits $ helix init --chain tempo --tokens USDC,EURC Downloading HGP genes for tempo + USDC/EURC... ✓ Inherited 47 genes (avg success rate: 96.2%) ✓ Gene Map pre-populated. Ready to handle failures.

### $HELIX — Incentivizing the Payment Immune System

VISION TOKEN CONCEPT
$HELIX Token Flow Gene Author Gene Consumer ┌────────┐ ┌────────┐ │ Agent A│ —push gene—→ │ HGP │ │ repairs│ │ Network│ —serve gene—→ │ failure│ ←earn $HELIX— │ │ └────────┘ └────────┘ ↑ pay $HELIX │ ┌────────┐ │ Agent B│ │ (new) │ └────────┘

#### Gene Access Fee

Consumers pay micro $HELIX to use community Genes. ~0.001 USDC per use. Top 10 most common Genes are free (bootstrap).

#### Author Rewards

Authors earn $HELIX every time their Gene is used. Higher-quality Genes earn more. Passive income for repair knowledge.

#### Staking for Quality

Authors stake $HELIX on their Genes. Works → stake + rewards. Fails → slashed. Self-policing quality mechanism.

#### Governance

$HELIX holders vote on: protocol upgrades, quality thresholds, fee structure, new chain integrations.

“The $HELIX token isn't speculation — it's a direct claim on payment reliability.
Every token represents a unit of proven repair knowledge.
More agents → more Genes → more value → more agents. Flywheel.”

### HGP vs Generic Agent Protocols

Dimension | Generic Agent Protocol | HGP (Helix)
--- | --- | ---
Gene source | Human-written or any agent behavior | Only from real payment failure + verified on-chain repair
Verification | No standard | Every Gene has a Tempo txHash
Failure context | Unstructured | Structured: errorCode + tokenPair + chain + sessionState
Applicability | Vague | Precise: balance range + chain + version + expiry
Quality signal | Upvotes / manual review | Automated: successRate × usage × proof status
Network inflection | Needs millions of agents | 100 agents cover 95% of payment failure patterns
Cold start | Every agent starts from zero | New agents inherit full Gene Map from day 1

Payment failures are a bounded problem space. MPP defines 7 error codes. Tempo adds ~13 more, plus Uniswap/Base/Privy. That's ~31 failure patterns total. With 100 active Helix agents, the HGP network has seen every possible failure multiple times. The 101st agent starts with perfect immunity.
Generic agent protocols need millions of users to be useful. HGP reaches critical mass at 100.

## Advanced Features (v1.2.0)

Research-backed intelligence layer built over 9 development days.

### Gene Combine (ELL paper)

Merges duplicate Genes with same category into stronger combined Genes. Runs during GC cycle. Merges platforms, sums success counts, takes max Q-value.

### Root Cause Analysis (MAST paper)

13 root cause mappings. Each failure type gets a hint (e.g. `concurrent_wallet_access`), likely cause, suggested action, and systematic flag.

### Gene Reasoning (ReasoningBank)

Each Gene tracks WHY it works: `reasoning`, `failureAnalysis[]` (max 5 entries), `successContext`, `failureContext`.

### Failure Attribution (Who&When)

Track which agent, which step, which workflow triggered each failure. `getAgentStats()` shows top failing categories per agent.

### Gene Links (A-Mem paper)

Co-occurring failures are linked. If nonce errors often happen with gas estimation failures, Helix tracks the relationship and shows it in the explain output.

### Schema Versioning (v3)

Auto-migration system. Upgrades from any version to latest. v0→v1 (base), v1→v2 (reasoning + attribution), v2→v3 (gene links).

Zod Validation
8 strategy schemas. Validates slippage, addresses, delays before execution.
simulate() Framework
Dry-run diagnosis in CI. `simulate({ error: '429' })` returns recommendation without executing.
Seed Gene Map
12 pre-loaded Genes. New users get immunity from day 1 for common errors.
Idempotency
repair_id + repair_log. Prevents double execution within 5-minute window.
L1 Gene Cache
In-memory Map with 30s TTL. Avoids SQLite on every lookup. Invalidates on writes.
EventBus Backpressure
Queue cap + rate limit. Prevents event flood during high-failure scenarios.

### CLI Commands

$ npx helix status # Gene Map health + Q-values $ npx helix simulate "AA25 nonce" # Dry-run diagnosis $ npx helix gc # Combine + prune genes $ npx helix stats bot-1 # Agent attribution

### Safety Modes

observe (default)
Diagnose only. Zero execution. Zero risk. Perfect for CI and monitoring.
auto
Execute Category A+B (retry, nonce refresh, network switch). No fund movement.
full
Execute Category C (swap, split, topup). Requires cost ceiling. Fund movement enabled.

### LLM Integration (v1.2.0)

LLM Perceive
When string matching fails, Claude/GPT classifies the error. Results cached in Gene Map — LLM called at most once per pattern.
LLM Construct
When no adapter has candidates, LLM picks 1-3 strategies from the menu. Confidence capped at 0.7. Only valid strategy names accepted.
LLM Reasoning
After 3+ successful repairs, async LLM generates WHY the strategy works. Stored in Gene.reasoning. Non-blocking.
// Enable LLM (default: disabled, $0) wrap(fn, { mode: 'auto', llm: { enabled: true }, // reads ANTHROPIC_API_KEY + OPENAI_API_KEY from env telemetry: { enabled: true }, // opt-in: help improve seed genes for everyone logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error' | 'silent' logFormat: 'json', // 'pretty' (colored) | 'json' (structured) });

### Research Foundations

Paper | Year | Implementation
--- | --- | ---
MemRL | 2026 | Gene Q-value RL scoring
SAGE | 2025 | PCEC Verify stage
ELL | 2025 | Gene Combine
MAST | 2025 | Root cause hints (13 mappings)
ReasoningBank | 2025 | Gene reasoning + failure_analysis
A-Mem | 2025 | Gene relationship links
Who&When | 2025 | Failure attribution tracking