NeuroLedger

ZK Private-Pass Gated Lending + Chainlink CRE Risk Orchestration + CRE Liquidation Keeper

Live App: https://www.neuroledgers.com/#/zk-private-lending
Protocol Info https://www.neuroledgers.com/#/ Demo Video (3–5 min): https://www.youtube.com/watch?v=5mZSca-KnXM Network: Ethereum Sepolia

---

✅ What this project is

NeuroLedger is a policy-aware lending protocol:

• ZK Proof gates who can borrow (private allowlist / zk-pass)
• Chainlink CRE acts as a decentralized orchestration layer:
  • Borrow Risk Workflow (event-driven): listens to BorrowRequested and writes approve/reject on-chain
  • Liquidation Workflow (cron-driven): periodically sweeps positions, checks Health Factor, computes min repay needed to restore solvency, and triggers partial/full liquidations
• On-chain contracts enforce execution (BorrowGate + BorrowApprovalRegistry + LendingPool), using oracle-backed pricing for HealthFactor.

Design principle: policy vs execution separation
CRE computes risk policy off-chain; smart contracts enforce solvency + execution deterministically on-chain.

---

🔗 Chainlink CRE Workflows (REQUIRED LINKS)

1) Borrow Risk Orchestrator (event-driven)

• CRE project config: project.yaml
• Secrets manifest: secrets.yaml Workflow Dir: cre-borrow-orchestrator
• Workflow definition: workflow.yaml
• Workflow code:
  • Entry: index.ts
  • Supporting modules (split files): evm.ts,http.ts,decision.ts,prompt.ts,types.ts,utils.ts,report.ts
• Workflow configs:
  • ./workflows/zkpass-risk-orchestrator/config.staging.json

2) Liquidation Orchestrator (cron-driven)

Workflow Folder: liquidation-orchestrator

• Workflow definition: workflow.yaml
• Workflow code:
  • Entry: index.ts
  • Supporting modules (split files): evm.ts,math.ts,report.ts,discover.ts
• Workflow configs:
  • ./workflows/liquidation-orchestrator/config.staging.json

Chainlink Consumer Contracts (Receivers)

• Borrow decision receiver: ./contracts/contracts/CREBorrowDecisionReceiver.sol
• Liquidation receiver : ./contracts/contracts/CRELiquidationReceiver.sol

---

---

🏗️ System Architecture (diagram)

---

🔁 Borrow Flow (diagram + summary)

Steps:

1. User generates/uploads ZK proof with: amount, root, nullifier, nonce + a,b,c
2. BorrowGate.requestBorrow() verifies proof + emits BorrowRequested(requestId, borrower, nullifier, amount)
3. CRE Borrow Risk Workflow triggers and performs:
   • On-chain context reads (HF projection, LTV, debt, collateral)
   • External API: Fear & Greed
   • AI Agent risk score (riskScoreBp)
   • Decision rule: approve only if deterministic solvency checks pass AND riskScoreBp < 9000 AI Agent has Asymetric VETO power
4. CRE writes signed report → CREBorrowDecisionReceiver → BorrowApprovalRegistry
5. User calls BorrowGate.executeBorrow(requestId) → checks registry decision
6. If approved, LendingPool.borrowFor() transfers NL to borrower

BorrowRequested Transaction: https://sepolia.etherscan.io/tx/0xc653f1772b53b01e9b151d3e384ff3b9158fb95f2c453e839a71f3c93d8532c6

Execute Borrow Transaction : https://sepolia.etherscan.io/tx/0x07711bed2879f914df920070d03026dd1848c6e7cae1ffcd98b14dfd06edc654

withdraw collateral transaction: https://sepolia.etherscan.io/tx/0xb0cdfbe763ab68d48e0d131b5d97b17d5c9d5be7582a627b393c599fdddec994

---

---

🔥 Liquidation Flow (diagram + summary)

Steps:

1. CRE Liquidation Workflow runs on cron
2. It scans borrower positions and checks HealthFactor(user) (< 1 means unsafe)
3. Uses oracle price feed (via LendingPool) for collateral valuation / HF math
4. Computes minimum repay required to restore HF > 1
5. Sends report to protocol receiver / executes LendingPool.creLiquidate(borrower, repayAmount)
6. LendingPool enforces:
   • if repayAmount >= debtNL → full liquidation
   • else → partial liquidation (seize proportional collateral)

🚧 Scheduled Architecture Improvement (Navigating CRE Read Limits) Due to current Chainlink CRE beta constraints (PerWorkflow.ChainRead.CallLimit), running sequential on-chain discovery to find active borrowers inside the workflow loop exhausts the EVM read quota. To prove the core liquidation math engine for this hackathon, the active borrower array is temporarily statically defined off-chain.

The immediate post-submission roadmap includes deploying a getActiveBorrowers() view function directly on the LendingPool contract. This will allow the CRE workflow to ingest the entire active protocol state in a single, highly efficient EVM read, permanently resolving the infrastructure limitation while making the discovery loop fully dynamic.

---

---

🛡 Guardrails & Trust Boundaries

Core safety invariants:

• No valid ZK proof → no borrow request accepted
• Nullifier replay blocked
• Borrow execution blocked unless registry decision is approved
• HF + solvency math enforced by LendingPool
• Liquidation is deterministic on-chain (full vs partial rules)
• CRE is bounded by receiver + contract logic (policy computed off-chain, enforced on-chain)
• AI Agent Policy Hardcoded and can never approve borrow on its own without passing all Protocol checks.

---

📜 Smart Contracts (Sepolia) All contracts verified on Etherscan

Contract	What it does
BorrowGate.sol	ZK-gated borrow entrypoint (requestBorrow → executeBorrow)
ZKPassVerifier.sol	Groth16 verifier (validates proof)
BorrowApprovalRegistry.sol	Stores decision by nullifier (approved/reason/riskScore/ltv/decidedAt)
CREBorrowDecisionReceiver.sol	Consumes CRE reports and writes decisions to registry
LendingPool.sol	Core accounting + HealthFactor + liquidation execution (borrowFor, creLiquidate)
Vault.sol	Escrows collateral
NL.sol	ERC-20 token borrowed by users
CRELiquidationReciever.sol	triggers liquidation

---

✅ Hackathon Requirements Checklist (explicit)

• Project description covers use case + stack/architecture
• 3–5 min public demo video (app execution OR CLI simulate)
• Public GitHub repo
• README links to all Chainlink-related files (above)
• CRE workflow used in the project
• Workflow integrates:
  • Blockchain: Ethereum Sepolia
  • External system: Alternative.me Fear & Greed API
  • LLM: Gemini API
• Demonstrates:
  • Successful CRE CLI simulation

---