Getting Started

AHADI Docs

AHADI (Swahili for "Promise") is a trustless escrow protocol on the Polygon blockchain. It eliminates the need for intermediaries when transacting with unknown parties — your funds are held by immutable code, not a person.

Non-custodial

Funds held by smart contract, never by AHADI.

10-second settlement

Release or refund executes instantly on-chain.

Open source

All contract logic is verifiable on PolygonScan.

AHADI is currently deployed on Polygon Amoy Testnet. Always verify contract addresses in constants/index.ts before mainnet deployment.

How It Works

Every deal goes through the same trustless lifecycle, enforced on-chain.

Seller creates an invoice

The seller generates a payment link via the dashboard. The link encodes the item description, USDT price, and a delivery timeout.

Buyer locks funds

The buyer opens the link, connects their wallet, approves the USDT transfer, and calls createDeal(). Funds move from the buyer's wallet into the smart contract vault.

Goods are delivered

The seller delivers the goods off-chain (physical or digital). Both parties can view the deal status in their dashboard.

Funds are released

Once satisfied, the buyer calls releaseFunds(). The USDT is transferred directly to the seller's wallet instantly, with no platform fee.

Dispute or timeout

If delivery fails, the buyer can raise a dispute or wait for the timeout to claim an automatic refund. Disputes are resolved by the AHADI admin with off-chain evidence.

Smart Contract

Contract Overview

The AhadiEscrow.sol contract is written in Solidity 0.8.19 and uses the OpenZeppelin ReentrancyGuard and SafeERC20 libraries. It supports native ERC-20 USDT deposits with time-locked expiry.

Deal State Machine

Active

Completed

Refunded

Disputed

Deal Struct

solidity

struct Deal {
    uint256 id;
    address buyer;
    address seller;
    uint256 amount;       // in USDT (6 decimals)
    bool    isCompleted;
    bool    isDisputed;
    uint256 createdAt;
    uint256 expiryTime;   // unix timestamp
}

Functions Reference

All state-changing functions require a connected wallet. View functions can be called without gas.

User Functions

createDealpublic

createDeal(address _seller, uint256 _amount, uint256 _timeoutSeconds) → uint256 dealId

Locks USDT from the buyer into the contract vault and creates a new deal. Returns the new deal ID. The buyer must approve the escrow contract to spend at least _amount USDT first.

releaseFundsbuyer only

releaseFunds(uint256 _dealId)

Marks the deal as completed and transfers USDT to the seller. Can only be called by the buyer of the specified deal while the deal is still active.

refundBuyerseller only

refundBuyer(uint256 _dealId)

Allows the seller to voluntarily cancel an active deal and refund the buyer. Useful when goods cannot be delivered.

refundTimedOutDealbuyer only

refundTimedOutDeal(uint256 _dealId)

Returns USDT to the buyer if the deal's expiryTime has passed and the deal is still active. No admin approval needed.

raiseDisputebuyer or seller

raiseDispute(uint256 _dealId)

Flags a deal as disputed, freezing it until the AHADI admin resolves it. Either party can raise a dispute on an active deal.

Admin Functions

resolveDisputeadmin

resolveDispute(uint256 _dealId, address _winner)

Transfers the locked USDT to the winning party (_winner must be buyer or seller). Only callable by the contract owner.

updateFeeadmin

updateFee(uint256 _newFee)

Updates the platform fee in basis points (e.g. 100 = 1%). Currently set to 0 — the platform charges no fees.

View Functions

getDealview

getDeal(uint256 _dealId) → Deal

Returns the full Deal struct for a given deal ID. Use this to check the status, parties, amount, and expiry of any deal.

getContractStatsview

getContractStats() → (totalDeals, locked, balance, excess)

Returns aggregate stats: total deals created, total USDT locked, current USDT balance, and any excess (unclaimed).

Error Codes

The contract uses custom errors for gas-efficient reverts. When a transaction fails, decode the revert reason to get the exact error name.

Error	When it fires
InvalidDealID	Deal ID does not exist
Unauthorized	Caller is not permitted to perform this action
DealClosed	Deal is already completed or refunded
DealDisputed	Deal is in a disputed state — frozen until resolved
DealNotDisputed	resolveDispute called on a non-disputed deal
DealNotTimedOut	refundTimedOutDeal called before expiry
InvalidState	Function called on a deal in the wrong state
InvalidAmount	Amount is zero or below minimum
InvalidAddress	Address is zero or disallowed
SelfDeal	Buyer and seller cannot be the same address
TimeoutRange	Timeout is outside the allowed min–max range

User Guides

For Sellers

Sellers create deals by generating payment links and sharing them with buyers. No coding required.

1
Connect your wallet
Click 'Sign In' on the landing page and connect with your preferred wallet (MetaMask, Coinbase Wallet, etc.). Make sure you're on the Polygon Mainnet network.
2
Navigate to the Seller tab
In the Dashboard, select the Seller tab and click 'Generate Payment Request'.
3
Fill in deal details
Enter the item name, the price in USDT, and the delivery timeout (in hours). The minimum timeout is 1 hour; maximum is 90 days.
4
Copy and share the link
AHADI generates a unique URL that encodes all deal parameters. Share this link with your buyer via any channel — Instagram DM, WhatsApp, email, etc.
5
Wait for the buyer to lock funds
Once the buyer locks USDT, you'll see the deal appear in 'My Deals' with status Active. You'll receive an on-chain event.
6
Deliver and get paid
Deliver the goods. When the buyer releases funds, the USDT arrives in your wallet instantly.

For Buyers

When you receive a payment link from a seller, here's what happens step by step.

1
Open the payment link
The seller's link takes you to the AHADI deal page with all details pre-filled: seller address, item name, price, and timeout.
2
Connect your wallet
Click 'Sign In'. Your wallet must hold at least the deal amount in USDT (Polygon Mainnet) plus a small amount of MATIC for gas.
3
Approve USDT spending
AHADI will ask you to sign two transactions: (1) Approve the escrow contract to spend your USDT, (2) Call createDeal() to lock the funds.
4
Receive the goods
The seller is now incentivised to deliver. Your funds are safe in the contract — they can only go to the seller if you release them, or back to you if you raise a dispute or the timeout expires.
5
Release funds or dispute
Inspect the goods. Happy? Click 'Release Funds'. Problem? Click 'Raise Dispute' and submit your evidence.

Never release funds before inspecting the goods. Once released, the transaction is irreversible. AHADI cannot reverse a voluntary fund release.

Disputes & Resolution

Either party can raise a dispute while the deal is active. Once raised, the deal is frozen — neither party can release or refund until an admin resolves it.

When to raise a dispute

Goods not delivered before timeout
Item significantly differs from description
Counterfeit or damaged goods received
Seller refuses to communicate

Resolution evidence

Chat screenshots (WhatsApp, Instagram DMs)
Photos or video of delivered item
Tracking numbers / courier receipts
Transaction receipts or invoices

Submit evidence to support@ahadi.com with your deal ID. The admin will call resolveDispute(dealId, winner) on-chain within 48 hours. In Q4 2026, this manual step will be replaced by Amani AI for sub-$100 disputes.

Technical Reference

Architecture

AHADI is a three-layer system: a Solidity smart contract, a React frontend, and a Graph Protocol subgraph for indexing.

Frontend

Next.js 15 (App Router) · React 19 · TailwindCSS v4

Server-rendered React app with client-side wallet hooks. React Three Fiber powers the 3D padlock. Reown AppKit / Wagmi handle all wallet connections and chain interactions.

Smart Contract

Solidity 0.8.19 · OpenZeppelin · Polygon PoS

Single-file escrow contract with ReentrancyGuard protection. Stores deal state in a mapping(uint256 => Deal). All events are emitted for subgraph indexing.

Indexer

The Graph · AssemblyScript · IPFS

Subgraph listens to DealCreated, FundsReleased, DisputeRaised, and DisputeResolved events and exposes a GraphQL API for the dashboard's deal history queries.

Contract Addresses

Contract	Network	Address
AhadiEscrow.sol	Polygon (Mainnet)	0x7445B80f07ffcC031cecd3FC645878Baa8373819
USDT (Mainnet)	Polygon (Mainnet)	0xc2132D05D31c914a87C6611C10748AEb04B58e8F

Subgraph & Indexing

The AHADI subgraph indexes all on-chain events from the escrow contract. Query it via GraphQL to get deal history, stats, and event timelines without scanning the blockchain yourself.

Example Query

graphql

{
  deals(orderBy: createdAt, orderDirection: desc, first: 10) {
    id
    buyer
    seller
    amount
    isCompleted
    isDisputed
    createdAt
    expiryTime
  }
}

Indexed Events

DealCreated

Emitted when a buyer locks funds

FundsReleased

Emitted when buyer releases to seller

BuyerRefunded

Emitted on refund or timeout claim

DisputeRaised

Emitted when a dispute is filed

DisputeResolved

Emitted when admin resolves dispute

Subgraph Studio: ahadi-escrow-v-1

Ready to start?

Connect your wallet and create your first escrow deal in minutes.

Launch AHADI