PPA Protocol - Demo Guide

For Hackathon Judges

End-to-end in 4 minutes

The demo uses time-warp: the oracle pushes a new simulated day every 60 seconds, and the agent evaluates every 10 seconds. Every transaction is real and verifiable on Mantlescan.

T+0:00

Setup

Wallet connected, USDT approved

T+0:30

Fund Plant

PPAT minted on-chain

T+1:00

Day 1 Credit

Oracle push → USDT credited

T+1:30

Agent DEPLOY

Idle float → USDY pool

T+3:30

RETRIEVE

Agent unwinds USDY position

T+4:00

Bill Settled

Zero clicks from funder

Prerequisites · 1 min

Wallet setup on Mantle Sepolia

Open MetaMask (or any EVM wallet). Add the Mantle Sepolia network if it isn't there yet:

Network name: Mantle Sepolia · RPC: https://rpc.sepolia.mantle.xyz · Chain ID: 5003 · Symbol: MNT

Need test MNT? Visit faucet.sepolia.mantle.xyz - drips 0.5 MNT, enough for all demo transactions.

Screen 1 - Marketplace

Browse the Chennai solar plant

Open the app and go to the Overview tab. The Marketplace card shows the reference plant: 100 kW commercial rooftop, Chennai, India.

What to observe: funding progress bar (tokens already sold by the demo seed wallets), 16.4% gross APY, tariff of ₹4.50/kWh vs ₹7.00 grid rate, and the live oracle timestamp. The plant data is read directly from PlantRegistry on-chain.

Judging signal: Every stat is contract-sourced - no hard-coded frontend values. Open DevTools Network tab to confirm calls to the Mantle Sepolia RPC.

Screen 2 - Fund

Approve USDT and fund the plant

The Fund widget (right panel of Overview) lets you choose a USDT amount. Hit Get USDT first - the faucet mints 500 test USDT to your wallet from the MockUSDT contract.

Then enter an amount (e.g. 48 USDT → 1,000 PPAT). Two transactions:

Tx 1 USDT approve → PlantEscrow Tx 2 PlantEscrow.fund() → PPAT minted

Judging signal: After Tx 2 confirms, a Mantlescan link appears inline. Click it - you'll see the Funded event with your address, watt amount, and PPAT tokens minted.

Screen 3 - Dashboard

Watch USDT credits accumulate in real time

The three stat cards at the bottom of Overview refresh every 10 seconds: PPAT balance, Credit account (USDT), and last oracle push timestamp.

In time-warp mode the oracle pushes every 60 seconds. Each push runs the full pipeline: CreditOracle → RevenueSplitter → CreditVault. Your credit balance will tick up proportionally to your PPAT share of the plant.

Math check: 1,000 PPAT = 1 kW. At 400 kWh/day for a 100 kW plant, your 1 kW generates 4 kWh · ₹4.50 ≈ ₹18 ≈ $0.22/day (≈ 16.4% APY on $48 invested).

Screen 4 - Agent Panel

Watch the AI agent make on-chain decisions

Switch to the Agent tab. The live feed streams AgentDecision events from the AgentRegistry contract in real time. Every decision - including HOLD - is a transaction.

The three pre-seeded demo wallets show all states simultaneously:

DEPLOY Wallet A · D+7 - idle > $5, sweep 80% to USDY pool

HOLD Wallet B · D+3 - window too short, emit reason on-chain

RETRIEVE Wallet C · D+1 - unwind full USDY + accrued yield

Judging signal: The event signature is AgentDecision(agentId, funder, action, amount, daysToBill, reasonCode). Click any event row to open the Mantlescan transaction - the raw log data is verifiable. The agent has no LLM in the transaction path; all decisions are deterministic threshold logic.

Screen 5 - Bill Settlement

Zero-click bill payment by the agent

Switch to the Bills tab. Three wallet cards show pending bills with countdown timers. When Wallet C's timer reaches zero, the agent automatically calls BillPay.settle() - the card flips to Settled with a Mantlescan link, no user action needed.

Judging signal: The funder never interacts with BillPay. The agent has AGENT_ROLE on BillPay and CreditVault, scoped only to those two contracts - no other permissions.

Judging Track

AI × RWA

On-chain AI benchmarking · Dynamic USDY yield · Automated risk management · Mantle RWA infrastructure

Contracts live

All deployed and verified on Mantle Sepolia (chain ID 5003). Identical bytecode for mainnet - one env flag swap.

Test suite

78 / 78

Foundry contract tests + 5 keeper state machine unit tests. All green. Run with make test.

Agent decisions on-chain

50+

Pre-seeded AgentDecision events emitted before judging starts. Every HOLD, DEPLOY, RETRIEVE, SETTLE recorded.

For Judges - Optional

Run it locally

Contracts are already deployed - you don't need to redeploy. Just clone, fill in keys, and run the demo stack.

Clone and install

git clone https://github.com/anbusan19/PPA_protocol.git

cd PPA_protocol

npm install              # root workspace (optional)

cd frontend && npm install

Configure environment

# Copy examples

cp keeper/.env.example keeper/.env

cp frontend/.env.example frontend/.env

# Fill in keeper/.env ─────────────────────

MANTLE_RPC=https://rpc.sepolia.mantle.xyz

PRIVATE_KEY=0x<deployer-key>

ORACLE_SIGNER_PK=0x<oracle-key>

DEMO_WALLET_1_PK=0x<wallet-a-key>

DEMO_WALLET_2_PK=0x<wallet-b-key>

DEMO_WALLET_3_PK=0x<wallet-c-key>

DEMO_MODE=true

Note: The deployer key must hold AGENT_ROLE on AgentRegistry. All addresses are in frontend/public/deployed.json.

Start the full demo stack

make demo

# Launches 3 processes in parallel:

# · oracle.js  - pushes kWh every 60s

# · agent.js   - polls every 10s, emits AgentDecision

# · Vite dev   - http://localhost:5173

# Run tests independently:

make test           # 78 Foundry + 5 keeper tests

On-chain Reference

9 deployed contracts

All on Mantle Sepolia (chain ID 5003). Click any address to open Mantlescan.

Contract	Role in demo	Address
PlantRegistry	Plant metadata, oracle signer, PPA data read by S1	0x7d15…653B6	View ↗
PPAToken	ERC-20 PPAT - minted in S2, balance shown in S3	0x50Fe…1644	View ↗
PlantEscrow	Receives USDT in S2, triggers PPAToken mint	0x483A…A471	View ↗
CreditOracle	ECDSA-signed daily kWh; oracle timestamp shown in S3	0x7740…4D429	View ↗
RevenueSplitter	kWh → USDT conversion, Merkle-batched pro-rata distribution	0x58D8…fE14	View ↗
CreditVault	Per-funder claimable USDT balance; balance shown in S3	0x59d5…3d14	View ↗
YieldRouter	Agent-only path to USDY pool; used in DEPLOY / RETRIEVE	0xEB78…41Ca7	View ↗
BillPay	Bill registration; agent calls settle() in S5	0xE7e2…2211	View ↗
AgentRegistry	ERC-8004 identity NFT; emits AgentDecision events shown in S4	0x6f89…4350	View ↗

For Users

How to use PPA Protocol

Fund a real solar plant from $10, earn daily revenue, and let an AI agent handle the rest. No active management required.

Step 01

Connect your wallet

Hit Connect Wallet in the top-right corner. PPA Protocol uses wagmi - any EVM wallet works (MetaMask, Rabby, Coinbase Wallet, WalletConnect).

Switch your wallet to Mantle Sepolia for the testnet demo, or Mantle Mainnet for the live version. The app will prompt you to switch if you're on the wrong network.

Step 02

Get testnet USDT

On testnet, the Fund widget has a Get USDT button that mints 500 test USDT straight to your wallet - no external faucet needed.

You'll also need a small amount of test MNT for gas. Visit faucet.sepolia.mantle.xyz to drip 0.5 MNT free.

Step 03

Browse the Marketplace

The Marketplace card on the Overview tab shows the live Chennai plant. You can see total capacity (100,000 PPAT = 100 kW), how much has been funded, the PPA tariff, and the projected APY.

1 PPAT = 1 watt of funded plant capacity. The minimum ticket is $10 ≈ 208 PPAT.

Step 04 - Key action

Fund the plant

Enter a USDT amount in the Fund widget. The app shows how many PPAT you'll receive and your projected daily credit.

Two wallet confirmations:
① Approve USDT spend on PlantEscrow
② Confirm the fund transaction

PPAT lands in your wallet immediately. A Mantlescan link shows the mint event.

Takes ~30 seconds

Step 05

Watch credits accumulate

The Dashboard (bottom of Overview) shows your PPAT balance, USDT credit account, and the last oracle push timestamp.

Each oracle cycle (every 60s in demo mode), your credit balance increases proportionally to your share of the plant. Credits are calculated by the RevenueSplitter using a Merkle tree for gas efficiency - no manual claim needed.

Step 06

The agent works for you

Switch to the Agent tab to watch the AI agent in action.

When you have more than 5 days before a bill is due and more than $5 idle, the agent automatically sweeps 80% of your credits into a USDY yield pool - adding 4–5% on top of your PPA revenue.

It retrieves the funds before the bill is due. You do nothing.

Step 07

Bills are paid automatically

Check the Bills tab to see your pending energy bills with countdown timers. When a bill is due, the agent calls BillPay on your behalf using your CreditVault balance.

The card switches to Settled automatically. You never have to touch a bill.

Step 08

Track everything on-chain

Every action - funding, credits, agent decisions, and settlements - is verifiable on Mantlescan. The Agent Panel feed shows live AgentDecision events with direct links to each transaction.

Your PPAT tokens are transferable ERC-20s - you can trade or transfer your plant stake at any time.

Step 09

What the agent will never do

The agent only has permission on YieldRouter and BillPay. It cannot move funds out of your CreditVault to any external address - only into the USDY pool or toward a bill registered on-chain.

A 20% liquidity buffer is always kept liquid regardless of agent state. Every decision, including HOLD, emits an on-chain event explaining why.

FAQ

Common questions

For both judges and users.

Is this real money / a real solar plant?

The contracts, tokens, and agent logic are real and fully on-chain. The plant data and oracle readings are [SIMULATED] for the hackathon demo - modeled on a real 100 kW commercial rooftop PPA in Chennai, India, using real tariff and generation data. This is a technology prototype; no instrument is offered to the public.

Why is the oracle centralized? Isn't that a risk?

In Phase 1, the oracle is a signed off-chain data feed (ECDSA, verified on-chain by CreditOracle). This is the same trust model used by Chainlink price feeds. The oracle signer key is separate from the deployer. Phase 2 will explore decentralized physical infrastructure (DePIN) reporting as an alternative oracle source.

Does the AI agent use an LLM for transactions?

No. Every fund-moving decision is deterministic threshold logic with on-chain-verifiable inputs (balance B, days-to-bill D, position P). The Groq integration is optional and used only to generate plain-English explanations of decisions in the Agent Panel UI - it has zero access to wallet actions.

Can I run this on Mantle mainnet?

Yes. The contracts compile identically for mainnet. In keeper/.env and frontend/.env, switch VITE_NETWORK=mainnet and update the RPC to https://rpc.mantle.xyz. Run make deploy RPC=$(MAINNET_RPC) to redeploy.

What is time-warp mode and how do I disable it?

Time-warp compresses the demo: 1 real minute = 1 simulated day. The oracle pushes every 60s, the agent polls every 10s. Set DEMO_MODE=false in keeper/.env to switch to production cadence (oracle daily, agent every 6 hours).

My USDT balance didn't update after funding - what do I do?

The app refreshes balances every 10 seconds. Wait one cycle and it should update. If it doesn't, check that your wallet is on Mantle Sepolia (chain ID 5003) and that both the approve and fund transactions confirmed. Open the browser console for any RPC errors.

Launch App Pitch Deck Mantlescan GitHub MNT Faucet