Skip to content

DarienPerezGit/Apolo

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

159 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Apolo

Apolo

Settlement layer for agentic economic outcomes.

From API calls to economic outcomes.

BNB Mainnet GenLayer Studionet Reliability 7/7 MIT License

WebsiteAppContractProofX


What is Apolo?

Apolo enables autonomous agents and service providers to commit to outcomes, verify fulfillment through GenLayer, and settle consequences on BNB Chain.

Funds move only when the promised outcome is fulfilled. If the outcome fails, settlement changes accordingly: refund, rejection, penalties, or other programmable consequences.

Economic outcomes are consequences. Apolo settles the consequences.

  • A provider commits to an outcome and puts funds at risk.
  • GenLayer's intelligent contract (DeliveryValidator.py) verifies evidence autonomously using AI validators and the Equivalence Principle.
  • The Solver executes release() or refund() on BNB Mainnet — autonomously, on-chain, with durable proof.

If the outcome is fulfilled → payment released.
If the outcome fails → payment refunded or penalized.

No manual arbitration. No counterparty trust. Evidence is public and permanent.


Live Proof

Canonical autonomous settlement — GenLayer validation + BNB settlement with no manual step:

Link Description
Settlement Receipt Human-readable evidence — intent, GenLayer consensus, BNB tx
GenLayer TX validate() call — FINALIZED on studionet
BNB Refund TX On-chain settlement — BNB Mainnet block 95664141
Reliability Endpoint 7/7 test cases passed (release, refund, edge)

Earlier settlement cycles (manual anchor mode, BNB Mainnet):

Cycle Event Transaction
🟢 Release Fund → release() 0x9f9e4...
🔴 Refund Fund → refund() 0xaab3d...

How It Works

Agent / Client
      │
      ▼
ApoloEscrow.sol  ←── intentHash = keccak256(chainId | contract | client | merchant | token | amount | slaUrl)
(BNB Mainnet)         Funds locked
      │
      ▼
Apolo Solver (Node.js · Render)
      │  calls validate()
      ▼
DeliveryValidator.py  ←── GenLayer studionet
(intelligent contract — Equivalence Principle consensus)
      │  fetches evidence URL, AI validators adjudicate
      ▼
Solver executes settlement
      │
 ┌────┴────┐
 ▼         ▼
release() refund()
merchant  client
BNB Mainnet

Tech Stack

Component Technology Status Address / URL
ApoloEscrow.sol Solidity + Foundry · BNB Mainnet 🟢 Live 0x055ad3...
DeliveryValidator.py Python · GenLayer studionet 🟢 Live 0x619d0b...
Solver / Relayer Node.js ESM · Render 🟢 Live apolo-solver.onrender.com
A2A Agent Python · A2A Protocol · Render 🟢 Live apolo-0qpf.onrender.com
Frontend React + Vite + Tailwind · Vercel 🟢 Live project-apolo.vercel.app
Signing viem + EIP-712
Evidence Supabase 🟢 Persistent Public via /evidence/:hash

External Agent Integration (A2A)

Apolo includes ApoloSLAWatcherAgent — an autonomous agent built on the A2A protocol that monitors SLA endpoints and triggers on-chain settlement without any human step.

Client → POST /intent (defer=true) → ApoloEscrow (BNB Mainnet, locked 🔒)
                                              │
                                  ApoloSLAWatcherAgent (A2A Server)
                                    checks slaUrl × N times
                                    decision: approved / rejected
                                              │
                                    POST /settle → Apolo Solver
                                              │
                                    release() / refund() on-chain ✅

Run locally

# Install deps
pip install -r agent-a2a/requirements.txt

# Terminal 1 — Solver
node scripts/apolo-server.mjs

# Terminal 2 — A2A Agent
python agent-a2a/__main__.py
# → http://localhost:8080/.well-known/agent.json

Set AGENT_API_KEY in .env to authenticate agent → solver calls.

Run the full case study

# Approved path: fund + validate + release
node scripts/qa-a2a-case-study.mjs

# Rejected path: fund + validate + refund
node scripts/qa-a2a-case-study.mjs https://httpbin.org/status/500

Produces agent-report.json with intentHash, structured evidence (3 checks + timestamps), and BSCScan links for fund + settle.

Reproduce with the production agent

# Terminal 1
node scripts/apolo-server.mjs

# Terminal 2 — expose locally for the Render agent
ngrok http 3001

# Terminal 3
AGENT_URL=https://apolo-0qpf.onrender.com \
SOLVER_URL=https://YOUR-NGROK-URL.ngrok-free.dev \
node scripts/qa-a2a-case-study.mjs

No UI button. No manual relayer run. The agent drives the full flow end-to-end.

Deploy to cloud

# render.yaml is included — connect repo to Render and set:
# SOLVER_URL=https://your-solver.onrender.com
# AGENT_API_KEY=<shared-secret>

Trust Model (V1)

Apolo V1 uses a Trusted Solver model. The solver node is the single authorized signer for release() / refund() — it bridges GenLayer adjudication with on-chain BNB settlement.

This is an explicit architectural choice, documented here:

Layer State
BNB settlement Mainnet. ApoloEscrow.sol is live and verifiable.
GenLayer validation Studionet. DeliveryValidator.py runs with AI validator consensus (Equivalence Principle).
Coordination Solver-trusted in V1. Solver calls validate(), reads the result, and executes settlement.
Evidence Persisted in Supabase. Public via /evidence/:hash and /evidence/:hash/human.
Decentralization V1 is not fully trustless end-to-end. V2 roadmap: multi-party signing, on-chain GenLayer preconditions.
  • Solver wallet: 0xa2e036eD6f43baC9c67B6B098E8B006365b01464
  • Only this address can call settle() on ApoloEscrow.sol
  • GenLayer evidence URL is fetched by AI validators, not by the solver

Development

Prerequisites

  • Node.js 20+ · Foundry · Python 3.11+

Environment

cp .env.example .env
# Fill in:
# PRIVATE_KEY=          # Solver wallet private key
# BSC_RPC=              # RPC endpoint
# BSC_CHAIN_ID=         # 56 (mainnet) or 97 (testnet)
# ESCROW_CONTRACT_ADDRESS=
# GENLAYER_EVIDENCE_URL= # Publicly reachable URL
# USE_GENLAYER=true

Scripts

npm run solver          # Start the Apolo Solver server
npm run relayer <hash> <approved|rejected>  # Manual settlement
npm run dev             # Frontend (from /frontend)
forge build             # Compile contracts
forge test              # Run contract tests

Contract deployment

forge script script/DeployApoloEscrow.s.sol --broadcast --rpc-url $BSC_RPC

License

MIT — see LICENSE. Copyright © 2026 Darien Perez.

About

Settlement layer for agentic economic outcomes on BNB Chain.

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors