Tenancy Oracle Protocol

1. The Problem

Renting a home in Nigeria is one of the most consequential financial decisions a person makes — and one of the most poorly informed. The average Nigerian tenant commits one to two years of rent upfront, often representing the majority of their liquid savings, before they have lived a single day in the property.

What follows that commitment is frequently nothing like what was advertised. But the real cost is not just financial.

1.1 The human cost of a bad building

A leaking roof is not just an inconvenience — it is weeks of sleep disruption, damaged belongings, arguments with a landlord who stops returning calls, and the slow erosion of the sense of safety that a home is supposed to provide. Mould in a poorly ventilated flat triggers asthma attacks in children. An epileptic water supply means hours lost every week sourcing alternatives. A broken gate or faulty locks turns every night into an anxiety.

These problems compound. A tenant already stretched financially cannot simply move — breaking a two-year lease means forfeiting months of rent with no legal recourse. They are trapped. They endure. And their stress, their health, and their productivity suffer in ways that never show up in any landlord's spreadsheet.

1.2 The financial trap

Nigerian tenancy law offers almost no practical protection. Landlords routinely demand one to three years of rent upfront — an arrangement that is illegal under the Lagos Tenancy Law 2011 but universally practised and unenforced. Security deposits are withheld at the end of tenancies on fabricated grounds, with no independent record of the property's condition at move-in to dispute the claim. Service charge fees are invented, increased without notice, and collected under the implicit threat of non-renewal.

The tenant has no paper trail. The landlord has all of it.

1.3 The silence enforced by fear

Perhaps the most damaging dynamic is the one that perpetuates all the others: tenants cannot speak. A current tenant who posts an honest review of their building is immediately identifiable — their address is in the review. Their landlord will find it. The consequences range from a hostile renewal negotiation to outright eviction. So the reviews never get written. The next family moves in blind, makes the same upfront commitment, and discovers the same problems. The cycle continues because the information that would break it is too dangerous to share.

1.4 A market built on information asymmetry

Landlords and agents control every source of information a prospective tenant has access to: the listing photos, the viewing, the inspection report, the references. There is no neutral record of a building's history — no log of how maintenance requests were handled, no account of what the previous tenants actually experienced, no independent assessment that the tenant commissioned and owns.

When inspections do happen, landlords choose and pay the inspector. The report serves the landlord's interests by design. A prospective tenant reading it is reading a document whose author was selected and compensated by the person trying to rent them the property.

2. Protocol Overview

TOP assembles six on-chain contracts and one messaging layer into a coherent tenant-advocacy system. The design principle is: every user action that advances tenant welfare creates a permanent on-chain record.

2.1 Smart contract deployment

All contracts are deployed on zkSync Era and written in Solidity 0.8.24 using OpenZeppelin base contracts (Ownable, AccessControl, ReentrancyGuard, ERC20, ERC721). The deployment script handles genesis allocation transfers and protocol whitelisting atomically. No manual post-deploy steps are required.

2.2 Upgrade strategy

Contracts are non-upgradeable by design; immutability is a core security property. If a critical bug is discovered, a new deployment is issued and the existing token supply migrated via governance vote. The transfer lock prevents MEV exploitation during migration windows.

3. Residency & SBT Layer

The foundational primitive of TOP is the Residency Soulbound Token (SBT). It answers one question — "does this wallet belong to someone who actually lives in this building?" — without revealing who that person is. Verification is a two-tier process, progressing from a quick physical-presence check to a richer behavioural proof.

3.1 Tier 1 — Basic SBT (GPS + photo)

During onboarding the tenant grants a one-time geolocation check from inside the building and submits an exterior photo. The OnboardingVerifier contract calls a Cloudflare Workers AI endpoint that compares the submitted photo against reference imagery using a CLIP-based similarity model:

No proof hash is stored on-chain for Tier 1 (proofHash = bytes32(0)). The GPS coordinates are used only during registration — no daily location access is ever required again. No PII leaves the device.

3.2 Tier 2 — Verified SBT (behavioural proof)

Tier 2 is earned through consistent physical presence, not a document. A tenant must accumulate 7 geolocated Heartbeat pings on distinct UTC calendar days, of which at least 4 must be corroborated by neighbour consensus, and achieve a cumulative fit score of ≥ 60%. The Tier2Verifier.claimTier2() function validates these conditions on-chain and upgrades the SBT in a single gasless transaction.

The proof hash stored for Tier 2 is deterministic and reproducible:

proofHash = keccak256(
  "tier2-behavioral-v1",
  wallet,
  buildingId,
  qualifyingDays   // array of UTC day numbers that passed
)

No external oracle, no third-party SDK. The proof is derived entirely from on-chain Heartbeat data already committed by the tenant and their building neighbours.

3.3 ResidencySBT contract

All transfer functions are blocked — the token is truly soulbound and cannot be sold or reassigned. One SBT is permitted per wallet per building. An existing SBT can be revoked by the verifier (for slashing), burning the token and clearing the record.

enum ResidencyTier { Basic, Verified }

struct SBTData {
  bytes32      buildingId;   // identifies the property
  bytes32      proofHash;    // behavioural proof hash · bytes32(0) on Tier 1
  uint48       issuedAt;
  uint48       upgradedAt;   // 0 until Tier 2 claimed
  ResidencyTier tier;
  bool         isActive;
}

3.4 SBT as protocol gating

4. Account Abstraction Layer

zkSync Era implements native Account Abstraction (EIP-4337-compatible but at the protocol level). Every user wallet is a smart contract account. This enables gasless transactions without a separate relayer network.

4.1 Phase 1 — Privy

During the MVP phase, Privy provides passkey and social login (ProtonMail signup only — no Google, no phone number). Privy wraps a Biconomy-backed smart account. Users never see a seed phrase; the passkey acts as the signing key. The Biconomy bundler submits sponsored transactions.

4.2 Phase 2 — Native WebAuthn AA

The Ghost Plan target is a Clave-style native WebAuthn implementation on zkSync's IAccount interface. This removes Privy and Biconomy entirely. A self-hosted Alto or Rundler bundler handles UserOp submission. No third-party dependency touches user keys.

4.3 TOPPaymaster

The TOPPaymaster implements zkSync's IPaymaster interface and applies two-tier gas sponsorship:

Tier 1 has a configurable gas cap (default 200,000 gas per transaction) to bound drain from a single call. No standard protocol operation — heartbeat ping, C2E session, bounty contribution, monthly claim — exceeds that. Tier 2 is a tight allowlist: only the OnboardingVerifier contract address is sponsored, and only for the SBT-mint call. No native-token gas path exists in the USDT-only model.

4.4 Paymaster sustainability

The Paymaster holds ETH. It must be actively funded or all Tier 1 gasless transactions will fail and the protocol stops working for verified tenants. This is the single most operationally critical dependency in the protocol.

Funding comes from protocol profit — the remainder of treasury USDT after monthly Heartbeat (10 %) + referral (10 % × 6 months) payouts. The admin converts USDT profit to ETH and loads the Paymaster. Each sponsored transaction costs approximately $0.02–$0.05 in ETH on zkSync Era, so a small fraction of monthly profit covers thousands of user transactions. Paymaster balance is monitored as a first-class protocol health metric.

5. Chat-2-Earn (C2E)

Chat-2-Earn is the primary knowledge-sharing and earning mechanism. A Prospective Tenant (PT) pays USDT to ask questions; a Verified Tenant (VT — Tier 2 SBT holder) earns USDT by answering honestly. All communication is end-to-end encrypted via XMTP; neither party reveals their real identity.

5.1 Session flow

1. PT approves the session fee and calls openSession on ChatEscrow. The fee is locked immediately.
2. An XMTP v3 DM is opened between PT and VT. A system message embeds the on-chain sessionId for correlation.
3. Both parties chat freely — encrypted, anonymous.
4. Resolution takes one of three paths:

5.2 Session fee (USDT, admin-tunable)

The session fee is a direct USDT amount (6 decimals) stored on ChatEscrow. The admin can re-tune it via a setter as macro conditions change — no oracle dependency, no naira-rate math. The current value is read on-chain at openSession time so the UI always shows the live fee.

5.3 Payout split

The treasury cut routes through the RewardsDistributor with the PT's address as payer, so referral attribution flows through to the monthly Merkle payout (see §8).

5.4 Neighborhood Challenge (dispute resolution)

If the PT believes the VT provided false or unhelpful information, they may open a Neighborhood Challenge. The full flow:

Raising a dispute. The PT supplies a written reason (≥ 10 characters). This is hashed client-side (keccak256(reason)) and stored on-chain as reasonHash. Simultaneously the PT must pre-approve and pay a dispute bond = 20% of the session fee (DISPUTE_BOND_BPS = 2000). The bond is collected by the contract and held until resolution.

Evidence window (48 h). During the 48-hour dispute window either party may anchor additional evidence on-chain:

Each TxId is hashed with keccak256 before storage — a commitment proving the document existed before the vote closed. The Arweave TxId is shared off-chain so voters can read the full document.

Adaptive quorum. Voters must be Tier 2 (Verified) SBT holders from the same building — not the PT or VT. The effective quorum is:

effectiveQuorum = min(MAX_NEIGHBOUR_QUORUM=3, eligibleVerifiedVoters)

If there are zero eligible Tier 2 neighbours, the dispute is rejected immediately and the bond returned — the community cannot adjudicate without members.

Resolution rules.

5.5 PT bad-faith protections

To deter serial disputers, the protocol tracks on-chain reputation for every PT address:

struct PTStats {
  uint32 sessionsOpened;
  uint32 sessionsCompleted;  // PT marked satisfied
  uint32 disputesRaised;
  uint32 disputesLost;       // incremented when VT wins
}

All fields are publicly readable. VTs can query a PT's dispute-loss ratio before accepting a session. A high ratio signals a PT who frequently raises losing disputes — a strong signal of bad faith that the community can act on without any protocol-level censorship.

5.6 XMTP v3 MLS

All chat messages use XMTP's browser SDK (v3 MLS, not the deprecated v2 xmtp-js). Messages are encrypted client-side; XMTP nodes cannot read them. The protocol stores only the XMTP conversation ID alongside the on-chain session ID for correlation — no message content is stored on-chain or off-chain by the protocol.

6. Building Heartbeat

A Residency SBT proves that a tenant lives in a building at a point in time. Building Heartbeat extends that proof into a living, continuous signal: once a day, every verified tenant in a building submits a three-question ping — water supply, electricity, security — and the results are aggregated on-chain, anonymously, in real time.

The aggregate is public. Anyone — a prospective tenant, a building agent, a journalist — can query the on-chain record and see how a building has trended over the last thirty days. No single tenant's report is attributable. The building's reputation is built from the ground up, one day at a time, by the people who actually live there.

6.1 How it works

Each ping is a single on-chain write, sponsored by the protocol Paymaster — tenants pay nothing in gas. The HeartbeatOracle contract enforces one submission per verified address per building per UTC day. It records the three boolean statuses, updates the building's day aggregate, and increments the tenant's cumulative ping count.

Before a building can receive heartbeats, it must be registered in the BuildingRegistry. The first verified SBT holder for a building pins its GPS coordinates on-chain (latitude, longitude, and a soft geofence radius of 50–1,000 metres). This registration is a one-time step; coordinates can only be corrected by the protocol admin. After registration, any verified tenant for that building can ping — no further location sharing is ever required.

6.2 Streak counter

Every consecutive day a tenant pings, their streak counter increments on-chain. Gaps reset to one. The streak is a durable participation signal — surfaced in the UI and recorded for any future protocol use.

Verified residents share a single monthly Heartbeat pool — 10 % of the month's treasury revenue, distributed pro-rata by days pinged that month, paid out at month-end via the RewardsDistributor Merkle claim (see §8.2). Basic-tier pings still build streak history and progress toward Verified eligibility, but only Verified residents share the pool.

6.3 Data integrity

The soft geofence is enforced by the client using the browser's Geolocation API during the one-time building registration step only. Daily pings require no location access — the SBT itself is the proof of residency. This design eliminates the privacy risk of daily GPS tracking while preserving a meaningful barrier to registration: a non-resident would need to physically visit the building to register its coordinates and pass the Tier 1 exterior photo check before being issued a Basic SBT.

Sybil resistance comes from the two-tier physical-presence system. Tier 1 requires GPS presence inside the building geofence plus a photo match against the building exterior. Tier 2 requires 7 geolocated Heartbeat pings on distinct calendar days, with ≥ 4 corroborated by neighbour consensus. A single wallet can hold one SBT per building. Fabricating a Tier 2 proof requires sustained, physical presence over multiple days — a cost high enough to keep the aggregate signal trustworthy at any realistic attacker budget.

7. Snag Bounty

Snag Bounty is a crowdfunded inspection system. Tenants pool USDT to commission a professional property inspection — chosen by them, paid by them, reported to them. The resulting report is stored permanently on Arweave and its hash is anchored on-chain.

6.1 Pool lifecycle

Open → Any SBT holder creates a pool for a building. Pool composition is derived from the HINL inspection fee and the building's vacancy state.
Any wallet can contribute USDT, any amount, no minimum number of funders. Pool is hard-capped at target — over-funding reverts.
Active → An eligible Lead Auditor has staked USDT and claimed. The inspection USDT advance has been released. Inspection is underway.
Awaiting Approval → (Path B only) Inspector Node has submitted report; 48-hour approval window opens.
Completed → LA fee + platform fee released. View-fee economy goes live.

6.2 Pool composition (USDT-denominated)

Pool target is derived from the inspection fee anchor. All four slices are percentages of the inspection cost (HINL Move-In = ₦150K ≈ $94 USDT at MVP):

Tenant-pool target ≈ ₦180K; prospective-pool target ≈ ₦195K. Any wallet can contribute any USDT amount — there is no minimum funder count.

6.3 Lead Auditor eligibility (vacancy-gated)

Whether a building is open to prospective Lead Auditors is driven by its vacancy flag, which Verified residents toggle directly from the daily Heartbeat ping. The contract checks at claim time:

Stake exactly matches the USDT released — net economic position is zero unless the LA ghosts. Ghosting forfeits the full stake to treasury.

6.4 Path A — External Inspector (HINL)

The LA receives the inspection-fee USDT advance at claim time, pays HINL, facilitates access, and supervises. Completion proof: a ZK-Email proof from HINL's outbound domain. No human approval required.

On valid proof: stake returned, LA completion fee released (15 % of inspection), platform fee sent to treasury. All in USDT.

6.5 Path B — Inspector Node (on-protocol)

An Inspector Node registers pseudonymously (wallet address only, no KYC) with a quoted USDT fee. Pool creator designates the Node at creation. The Node accepts the job once a Lead Auditor has claimed and the pool is funded.

The Node submits the Arweave report hash directly on-chain. Before payout releases, the report requires approval:

If approval doesn't happen within the window, anyone can trigger finalisation as long as LA has approved.

6.6 Lead Auditor accountability

Pool size is hard-capped at 300 USDT (~₦480K) — the MVP is restricted to one inspection type (Move-In Certification), so the graduated tier system from earlier designs has been collapsed to a single cap. Lead Auditors still build on-chain reputation through completed jobs.

Stake slashing and SBT strikes are applied for ghosting (disappearing after receiving USDT) or fraudulent proofs. Strike severity: 1st = warning, 2nd = 30-day cooldown, 3rd = Lead Auditor role permanently revoked.

6.7 View-fee economy (USDT, both paths)

Pool USDT pays for the inspection itself. The view-fee economy runs after completion — every non-funder who reads the report pays a USDT view fee. Split uniformly across both paths:

Path B Inspector Nodes are compensated only by their quoted USDT fee at completion; they don't share the view-fee tail. Their quoted fee can be set higher at registration to price that in. The treasury cut funds the monthly Merkle payout (see §8).

8. Revenue & Rewards

The protocol is a service: tenants pay USDT for inspections and Chat-2-Earn sessions, the protocol takes a treasury cut, and a portion of that cut flows back to active participants via a monthly Merkle payout. Every flow — fees, splits, stakes, payouts — is denominated in USDT.

8.1 Treasury revenue sources

Every treasury cut routes through RewardsDistributor.recordRevenue(payer, amount) — the originating user's address is recorded on-chain for downstream referral attribution.

8.2 Monthly Merkle payout

At month-end an off-chain cron reads every TreasuryRevenue event, ping record, and referrerOf mapping. It computes per-user owed amounts and posts a Merkle root on-chain. Users claim with a proof — one USDT transfer covers both reward streams below.

The pool is always a fraction of revenue already earned, so it can never run a deficit. Rewards scale with real protocol usage — high usage means a bigger pool, low usage means a smaller one, and the user never waits on future promises.

8.3 Profit retention

The remainder of treasury revenue — after Heartbeat (10 %), referral (10 % of referee revenue), and any forfeited stakes — is protocol profit. Admin can withdraw via withdrawTreasury(to, amount). The contract tracks outstandingClaims so profit withdrawal can never drain USDT users could still claim.

9. Decentralisation Roadmap ("Ghost Plan")

Every architectural decision in TOP follows a strict hierarchy: Sovereign > Decentralised > Pseudonymous > Never KYC.Phase 1 makes pragmatic use of managed services (Privy, Biconomy, Pinata) to ship fast. Phase 2 replaces each one with a self-sovereign or trustless equivalent.

10. Security Considerations

11.1 Reentrancy

All contracts that hold USDT (ChatEscrow, BountyPool, RewardsDistributor) inherit OpenZeppelin's ReentrancyGuard and follow Checks-Effects-Interactions (CEI) ordering throughout.

11.2 Front-running

zkSync Era uses a private mempool by default, which materially reduces front-running risk relative to Ethereum mainnet. Session fees are computed at deposit time from on-chain parameters, removing price-oracle dependencies from the hot path.

11.3 Sybil resistance

The two-tier physical-presence system is the primary Sybil defence. One SBT per wallet per building. Tier 1 requires a GPS check inside the building's geofence plus an exterior photo match — a non-resident must physically attend. Tier 2 further requires 7 geolocated Heartbeat days with neighbour corroboration over multiple calendar days, raising the cost of fabrication to sustained physical presence.

Neighborhood Challenge voters must be Tier 2 (Verified) SBT holders from the same building — not Tier 1. This ensures dispute arbiters have demonstrated the highest level of sustained presence, making sockpuppet voter attacks require a prolonged, multi-day commitment per fake identity.

11.4 Transfer lock abuse

The pre-DEX transfer lock is enforced at the token level on every transfer. Only protocol-approved contracts can move tokens before DEX listing. No contract can approve itself — whitelisting is an explicit protocol governance action.

11.5 Lead Auditor accountability

The stake-before-claim pattern ensures Lead Auditors have skin in the game before receiving pool funds. Stake is USDT matched exactly to the USDT advance — net economic position is zero unless the LA ghosts, in which case 100 % of the stake forfeits to treasury. A single hard cap of 300 USDT per pool (MVP) prevents new actors from controlling large pools while the inspection type is restricted to Move-In Certification. Strike escalation (warn → 30-day cooldown → permanent revoke) handles repeat misconduct.

11.6 Paymaster depletion risk

The Paymaster holds ETH and is a single point of operational failure. If its balance reaches zero, all Tier 1 gasless transactions are rejected by the zkSync sequencer. The protocol mitigates this through: (a) a conservative per-transaction gas cap of 200,000 units; (b) a monitored low-balance alert threshold; and (c) a pre-committed replenishment mechanism funded by the Founding Ops Fund and Redemption Pool inflows. Monitoring the Paymaster balance is treated as a first-class operational health requirement — equivalent to monitoring smart contract balances.

11.7 Privacy guarantees

No PII is stored on-chain. Proof hashes are one-way commitments. XMTP messages are client-side encrypted and the protocol has no decryption key. Wallet addresses are pseudonymous by default on zkSync Era. The Paymaster does not log or store gas-payment data beyond what is visible on-chain.

11. Conclusion

Tenancy Oracle Protocol inverts the power relationship in Nigerian residential rentals. Tenants gain an anonymous, cryptographically verifiable voice. Prospective tenants gain access to honest building intelligence. Independent inspections are funded by tenants, not landlords. Every action that advances this mission creates a permanent on-chain record that no party — landlord, agent, or company — can remove.

The protocol is designed to be fully sovereign: static hosting, no API keys, no KYC requirements, no centralised database. Phase 1 ships fast with managed services. Phase 2 replaces each dependency with a self-hosted or trustless equivalent. The ghost plan is a road, not a distant aspiration.

The building record belongs to tenants. Forever.