Last active
March 30, 2026 08:07
-
-
Save Aboudjem/c21e4c54dd4c90851b4700c678324382 to your computer and use it in GitHub Desktop.
Integra PRD: 28-passport-populator (HTML)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>PRD: Passport Populator</title><style>*{margin:0;padding:0;box-sizing:border-box}body{background:#0A0A1A;color:#E8E8F0;font-family:'Inter',system-ui,sans-serif;line-height:1.7}a{color:#00CEC9;text-decoration:none}a:hover{text-decoration:underline}.hero{padding:48px 32px 36px;border-bottom:1px solid #2A2A4A;background:linear-gradient(135deg,#0A0A1A 0%,#1A1040 50%,#0A0A1A 100%)}.hero h1{font-size:2rem;font-weight:800;color:#fff;margin-bottom:8px}.hero .meta{display:flex;gap:10px;flex-wrap:wrap;margin-bottom:12px}.badge{display:inline-block;padding:4px 12px;border-radius:6px;font-size:12px;font-weight:700}.badge-owner{background:rgba(108,92,231,0.15);color:#A29BFE;border:1px solid rgba(108,92,231,0.3)}.badge-week{background:rgba(0,206,201,0.15);color:#00CEC9;border:1px solid rgba(0,206,201,0.3)}.badge-est{background:rgba(0,184,148,0.15);color:#00B894;border:1px solid rgba(0,184,148,0.3)}.container{max-width:900px;margin:0 auto;padding:32px 24px}.section{background:#12122A;border:1px solid #2A2A4A;border-radius:12px;padding:24px;margin-bottom:20px}.section h2{font-size:0.8rem;font-weight:700;color:#8888AA;text-transform:uppercase;letter-spacing:1.5px;margin-bottom:14px;padding-bottom:8px;border-bottom:1px solid #2A2A4A}.section h3{font-size:0.95rem;font-weight:600;color:#E8E8F0;margin:12px 0 6px}.section p{font-size:0.95rem;margin-bottom:8px}.section ul{list-style:none;padding:0}.section ul li{padding:6px 0 6px 20px;position:relative;font-size:0.95rem}.section ul li::before{content:'>';position:absolute;left:0;color:#A29BFE;font-weight:700;font-family:monospace}.section code{background:rgba(108,92,231,0.1);padding:2px 6px;border-radius:4px;font-size:0.88rem;color:#A29BFE}table{width:100%;border-collapse:collapse;font-size:0.9rem;margin:8px 0}th{text-align:left;padding:8px 12px;background:rgba(108,92,231,0.08);color:#A29BFE;font-size:0.75rem;text-transform:uppercase;letter-spacing:1px;border-bottom:1px solid #2A2A4A}td{padding:8px 12px;border-bottom:1px solid rgba(42,42,74,0.5)}.checklist li::before{content:'\2610' !important;color:#8888AA !important;font-family:inherit !important}.back{display:inline-block;margin-bottom:16px;color:#8888AA;font-size:0.9rem}.footer{text-align:center;padding:24px;color:#555577;font-size:0.82rem;border-top:1px solid #2A2A4A;margin-top:32px}</style></head><body><div class="hero"><a class="back" href="https://gist.githack.com/Aboudjem/0af8c2ce9d5b62038a18eeff09603553/raw/integra-testnet-master-plan.html">← Back to Master Plan</a><h1>Passport Populator</h1><div class="meta"><span class="badge badge-owner">Kalki</span><span class="badge badge-week">Week 3</span><span class="badge badge-est">0.5 day</span></div><p style="color:#8888AA;font-size:0.9rem">N/A (headless agent, monitored via Agent Arena)</p></div><div class="container"><div class="section"><h2>Overview</h2><div class=""><p>Autonomous agent that scrapes public real estate data from multiple sources and auto-generates Asset Passports on-chain. Raw listing data is normalized into structured passport metadata using AI, then minted via AgentAuth delegation. This solves the cold-start problem by filling GOB with thousands of realistic property listings without any manual data entry. Every mint is a real on-chain transaction contributing to the 1M+ tx target.</p></div></div> | |
| <div class="section"><h2>Features</h2><div class=""><ul><li><strong>Multi-Source Scraping</strong> — Pulls public listing data from Zillow, Realtor.com, and county public records via Apify actors</li></ul><ul><li><strong>AI Structuring</strong> — LLM normalizes raw, messy listing data into the AssetPassport schema (address, sqft, beds/baths, year built, zoning, valuation, images)</li></ul><ul><li><strong>Automated Minting</strong> — Calls <code>AssetPassport.mint()</code> for each structured listing, writing the passport on-chain without human intervention</li></ul><ul><li><strong>AgentAuth Integration</strong> — Agent registers on startup, receives a session wallet, and signs all txs via delegated auth</li></ul><ul><li><strong>Configurable Targeting</strong> — Operator sets target city, property type (residential/commercial/land), price range, and volume cap per hour</li></ul><ul><li><strong>Rate Limiting</strong> — Respects source rate limits and applies configurable delay between mints (default: 1 tx/sec)</li></ul><ul><li><strong>Batch Processing</strong> — Groups mints where possible to optimize gas usage and throughput</li></ul><ul><li><strong>Activity Logging</strong> — Logs every mint tx hash, success/failure status, gas used, and metadata quality score</li></ul><ul><li><strong>Agent Arena Monitoring</strong> — Registers itself in Agent Arena, reports heartbeat, and surfaces throughput/error metrics on the dashboard</li></ul><ul><li><strong>Fault Tolerance</strong> — Retries failed mints with exponential backoff, skips permanently invalid listings, and resumes from last checkpoint on restart</li></ul><ul><li><strong>Data Deduplication</strong> — Tracks minted addresses to avoid duplicate passports for the same property</li></ul></div></div> | |
| <div class="section"><h2>Functions</h2><div class=""><ul><li><code>scrapeListings(city, propertyType, priceRange)</code> — Fetches raw listing data from configured public sources</li></ul><ul><li><code>structurePassport(rawListing)</code> — AI-normalizes raw data into valid AssetPassport metadata JSON</li></ul><ul><li><code>mintPassport(metadata)</code> — Calls <code>AssetPassport.mint(bytes metadata)</code> via AgentAuth session wallet</li></ul><ul><li><code>getAgentStatus()</code> — Returns current throughput, error rate, total minted, and uptime</li></ul><ul><li><code>configure(targetCity, propertyType, priceRange, volumePerHour)</code> — Updates agent targeting parameters at runtime</li></ul><ul><li><code>validateMetadata(passportJSON)</code> — Validates structured metadata against the AssetPassport schema before minting</li></ul></div></div> | |
| <div class="section"><h2>User Flow</h2><div class=""><ul><li>Operator configures target parameters: city, property type, price range, volume per hour</li></ul><ul><li>Agent authenticates via AgentAuth and receives a session wallet</li></ul><ul><li>Scraper pulls public listing data from configured sources</li></ul><ul><li>AI structuring layer normalizes each listing into AssetPassport schema</li></ul><ul><li>Agent validates metadata and calls `AssetPassport.mint()` for each listing</li></ul><ul><li>Agent logs every tx hash, gas used, and success/failure status</li></ul><ul><li>Operator monitors throughput and errors via Agent Arena dashboard</li></ul><ul><li>Minted passports automatically appear in GOB listings</li></ul></div></div> | |
| <div class="section"><h2>Deliverables</h2><div class="checklist"><ul class="checklist"><li>Scraper module with Apify actors for Zillow and Realtor.com (+ public records fallback)</li></ul><ul class="checklist"><li>AI structuring module that normalizes raw listings into AssetPassport metadata</li></ul><ul class="checklist"><li>Minting module with AgentAuth session key signing and batch support</li></ul><ul class="checklist"><li>Configuration system (target city, property type, price range, volume cap, scrape interval)</li></ul><ul class="checklist"><li>Rate limiter respecting source limits and configurable mint delay</li></ul><ul class="checklist"><li>Deduplication tracker (no duplicate passports for same property)</li></ul><ul class="checklist"><li>Activity logger with per-tx details (hash, gas, status, metadata quality)</li></ul><ul class="checklist"><li>Agent Arena registration with heartbeat and dashboard metrics</li></ul><ul class="checklist"><li>Fault tolerance: retry with backoff, skip invalid, resume from checkpoint</li></ul></div></div> | |
| <div class="section"><h2>Integration Points</h2><div class=""><ul><li><strong>Depends on:</strong> AgentAuth (session wallet), AssetPassport.sol (<code>mint()</code>), Apify (scraping actors), AI model (structuring)</li></ul><ul><li><strong>Used by:</strong> GOB (minted passports appear as marketplace listings), Agent Arena (monitoring dashboard)</li></ul><ul><li><strong>Explorer:</strong> Integra Explorer (all mint txs visible)</li></ul></div></div> | |
| <div class="section"><h2>XP Rewards</h2><div class=""><table><thead><tr><th>Action</th><th>Points</th></tr></thead><tbody><tr><td>Successful passport mint (per tx)</td><td>Standard agent XP rate</td></tr><tr><td>Passport later wrapped or traded on GOB</td><td>Bonus XP</td></tr><tr><td>Reach 1,000 passports minted (operator badge)</td><td>"Populator" badge</td></tr></tbody></table></div></div> | |
| <div class="section"><h2>Success Metrics</h2><div class=""><table><thead><tr><th>Metric</th><th>Target</th></tr></thead><tbody><tr><td>Sustained minting throughput</td><td>60 mints/hour</td></tr><tr><td>Uptime without crash or stall</td><td>24+ hours continuous</td></tr><tr><td>Total passports minted in first week</td><td>5,000+</td></tr><tr><td>Metadata validation pass rate</td><td>>95%</td></tr><tr><td>Passports subsequently wrapped or traded</td><td>>10%</td></tr></tbody></table></div></div> | |
| </div><div class="footer">Integra Testnet PRD — Passport Populator — Chain: integra-testnet-1 (EVM 26218)</div></body></html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment