Civitas

Civitas is an AI-powered cross-chain agreement platform that transforms natural language into deployed, funded, and verifiable smart contracts — all within a single conversational flow. Our mission is to eliminate the complexity barrier between everyday users and decentralized finance by letting an AI agent handle negotiation, deployment, and cross-chain funding so that anyone can create trustless financial agreements without writing a single line of code or understanding blockchain mechanics.

Agentic AI at the Core Civitas is built around a conversational AI agent powered by Gemini 3.0 Pro Preview and the Vercel AI SDK. Rather than presenting users with intimidating forms, the agent engages in natural dialogue — asking one clarifying question at a time to extract structured contract configurations validated against strict Zod schemas. The agent is equipped with five specialized tools that it invokes autonomously: ENS name resolution across L1 and L2, Ethereum address validation, USDC balance checking, proactive multi-chain wallet scanning (across Ethereum, Base, Arbitrum, Optimism, and Polygon simultaneously), and optimal cross-chain funding route calculation. When a user says "I'm ready to fund," the agent proactively scans their wallet across all supported chains, identifies where their assets sit, queries LI.FI for the cheapest and fastest bridging route, and presents a recommendation — all without the user needing to understand bridging, gas costs, or chain differences.

R2F2C: Requirement-to-FSM-to-Code Civitas follows a Requirement-to-FSM-to-Code (R2F2C) pipeline. Users express requirements in plain English ("I want to split rent with my two roommates at $1,000/month for 6 months"). The AI agent maps these requirements onto one of three finite state machine templates — RentVault (multi-tenant rent collection with landlord withdrawal and refund states), GroupBuyEscrow (collective purchases with funding, delivery confirmation, majority voting, and timelock refund states), or StableAllowanceTreasury (counter-based periodic allowances with pause, unpause, and termination states). Each template implements a formally defined state machine in Solidity with explicit transitions and guards. The AI then populates the FSM parameters (participants, amounts, dates, shares in basis points) and deploys the configured contract via a gas-efficient EIP-1167 proxy clone from our CivitasFactory, using CREATE2 for deterministic address prediction.

Cross-Chain Liquidity via LI.FI Funding a contract shouldn't require users to be on the right chain with the right token. Civitas integrates the LI.FI SDK to enable funding from 60+ source chains. The AI agent first scans the user's balances across five major chains, then queries LI.FI's routing engine to find the optimal path — comparing gas costs, execution duration, and bridging tools (Across, Hop, Stargate, etc.). The destination is locked to Base USDC at the contract's predicted CREATE2 address, so funds bridge directly into the contract. Contracts use balance-based activation — once sufficient USDC arrives (even after a 1-5 minute bridge delay), the contract automatically becomes active without any additional user action.

Decentralized Identity & On-Chain Verification via ENS Every deployed contract receives a human-readable Basename (ENS on Base) such as downtown-studio-6mo.civitas.base.eth. But Civitas goes far beyond simple naming — each contract stores 11-14 ENS text records on-chain containing full contract metadata: type, status, rent amount, due dates, participant count, voting thresholds, funding progress, currency details, and legal classification. This transforms ENS from a naming system into a decentralized contract registry. Anyone can look up a contract's terms and status through our public verification page without connecting a wallet — enabling transparent, trustless discovery and audit of agreements.

Tech Stack The frontend is built with Next.js 15 (App Router), TypeScript, and Tailwind CSS, with RainbowKit v2 and wagmi v2 for wallet connectivity. Smart contracts are written in Solidity 0.8.20 using the Foundry toolchain, deployed on Base (Coinbase's L2). The backend runs Express.js with SWC builds. Data persistence uses Supabase (PostgreSQL 17 with Row Level Security). The AI layer uses Google's Gemini 3 Flash model for fast, cost-efficient structured output generation and streaming chat responses.

Civitas is built as a full-stack dApp with a Next.js 15 App Router frontend (TypeScript, Tailwind CSS), Solidity 0.8.20 smart contracts compiled with Foundry, and an Express.js backend. Wallet connectivity uses RainbowKit v2 and wagmi v2 with viem for on-chain reads/writes, and data is persisted in Supabase (PostgreSQL 17 with Row Level Security).

The AI Agent (Gemini 3 Flash + Vercel AI SDK) At the core is a conversational AI agent powered by Google's Gemini 3 Flash, integrated through the Vercel AI SDK's streamText() API running on Edge Runtime. Instead of forms, users describe what they want in plain English. The agent is equipped with five agentic tools it invokes autonomously mid-conversation: resolveENS (resolves .eth, .base.eth, and .basetest.eth names to addresses via L1/L2 resolvers), validateAddress (checks if an address is an EOA or contract), checkBalance (reads USDC balances on Base), scanWalletBalances (proactively scans ETH and USDC across Ethereum, Base, Arbitrum, Optimism, and Polygon simultaneously using parallel viem public clients), and getOptimalFundingRoute (queries LI.FI's routing engine to compare gas costs, execution time, and bridging tools like Across/Hop/Stargate). The agent decides when to call these tools — for instance, when a user says "I'm ready to fund," it proactively scans their wallet, finds where their assets are, and recommends the cheapest bridge route.

After each AI response, a background extract-config endpoint calls generateObject() with template-specific Zod schemas to pull structured configuration (addresses, amounts, dates, participant shares in basis points) from the conversation. This powers a real-time contract preview card that updates live as the user chats — showing a completeness percentage that climbs from 0% to 100% as details are confirmed.

R2F2C: Requirement-to-FSM-to-Code The system follows a Requirement-to-FSM-to-Code pipeline. Natural language requirements map onto one of three formally defined finite state machine templates implemented in Solidity: RentVault (states: Initialized → Fully Funded → Withdrawn/Refunded, with multi-tenant deposit tracking via basis-point shares), GroupBuyEscrow (states: Funding → Goal Reached → Delivery Confirmed → Voting → Released/Refunded, with majority-vote release and timelock safety valves), and StableAllowanceTreasury (states: Active ↔ Paused → Terminated, with counter-based discrete claim approvals). The AI extracts the FSM parameters — participants, amounts, dates, share splits — and the CivitasFactory deploys the configured state machine as a gas-efficient EIP-1167 minimal proxy clone. CREATE2 deterministic addressing (salt = keccak256(creator, basename)) lets us predict the contract address before deployment, which is critical for the funding step.

LI.FI Integration — Cross-Chain Liquidity LI.FI is what makes Civitas chain-agnostic. Our LiFiBridgeStep component integrates the LI.FI SDK directly — calling getRoutes() with the source chain/token and locking the destination to Base USDC at the predicted CREATE2 contract address, then executing via executeRoute() with a custom updateTransactionRequestHook that applies a 150% gas buffer on L2 baseFeePerGas (fixing an issue where LI.FI leaves maxFeePerGas undefined on rollups). But more importantly, LI.FI powers the AI agent itself: the getOptimalFundingRoutes tool queries LI.FI's routing API across every chain where the user holds funds, comparing cost and speed, so the agent can say "Send USDC from Arbitrum — $0.12 gas, ~45 seconds via Across" before the user ever opens the bridge UI. Funds bridge directly to the contract address (not the user's wallet), and the contract activates automatically via balance-based detection once sufficient USDC arrives — no explicit deposit function needed, handling the 1-5 minute async bridge delay gracefully.

ENS — On-Chain Contract Registry We use ENS not just for naming but as a decentralized contract metadata store. The CivitasFactory integrates directly with the Base L2 ENS Registry and Text Resolver contracts. At deploy time, createSubdomainAndSetRecords() registers a semantic Basename (e.g., downtown-studio-a3f9e2c1.civitas.base.eth), sets forward address resolution, and writes 11-14 ENS text records on-chain per contract — storing contract.type, contract.status, contract.rent.amount, contract.escrow.participantCount, contract.treasury.allowancePerIncrement, voting thresholds, currency addresses, and legal.type. This means anyone can look up a contract's full terms and live status by querying its ENS name — no wallet connection required, no proprietary API, just standard ENS text record reads. The factory also supports batchUpdateENSRecords() for updating metadata as contract state changes. Our public /verify page reads these records to provide trustless, wallet-free contract verification and discovery.

How it all connects: User chats with AI → AI extracts config + resolves ENS names + scans wallets → Factory deploys EIP-1167 clone at predicted CREATE2 address → ENS records written on-chain → LI.FI bridges funds from any chain directly to contract → Balance triggers activation. One conversation, one click, fully on-chain.