How it works, exactly.

NairaFlow has two products that share one security model. Savings circles are on-chain Ajo or Esusu for a group. Goal vaults are a personal lock. Both are non-custodial: money sits in a contract, and no person or company can move it outside that contract's rules.

An optional agent can close due circle rounds and release vault allowances you approved. It can never go beyond limits you set, and you can revoke it at any time.

A savings score shows how reliably any wallet pays into circles, read live from public events.

Each circle is its own contract with its own address, created from a factory. Funds are never pooled between circles.

Setting one up

The creator joins automatically as the first member and posts the deposit. When the last seat fills, the circle starts by itself and the first round deadline is set from that moment.

Each round

1. Every member contributes before the round deadline.
2. After the deadline, anyone can close the round. The agent does it automatically when it is running.
3. A member who did not pay loses their deposit into that round's pot and is marked defaulted. They are skipped for the rest of the circle.
4. The next member in order is credited the whole pot. They collect it with a Withdraw button.

Order of payouts

Members are paid in join order, with no randomness. If someone leaves before the circle is full, the last member to join takes their place in the order. Once the circle is full the order is fixed.

Leaving, finishing and getting stuck

• You can leave while the circle is still filling and your deposit comes straight back.
• If a circle never fills within 30 days, any member can cancel it and reclaim their deposit.
• When it finishes, deposits of members who never defaulted are returned.
• If every member defaulted, whatever is left is split between all members rather than locked forever.

A vault belongs to one owner and holds one stablecoin. It is created with a destination address, an unlock date, and optionally a recurring allowance.

The agent is an off-chain service. It watches the chain and can call exactly two functions on a contract named AgentExecutor: close a due circle round, and release an allowance from a vault. It holds no funds and no token allowance.

The policy you grant

Every call is checked against the policy on chain, and the vault checks its own unlock and allowance rules separately. Revoke the policy and the agent's next attempt reverts with policy inactive.

Gas and the activity log

For vault releases the agent may wait up to four minutes for a lower gas price, then acts anyway so your schedule is honored. Every action emits an event with the gas price at that moment, and the Activity page reads those events back from the chain with a link to each transaction.

Who runs it

The agent is a program in the repository. It is set up to run on GitHub's servers on a schedule, with its own key that holds only testnet gas and the agent role, and it is also run directly by the project maintainers. GitHub treats schedules as best effort and can delay or skip runs, so a due round may wait, sometimes for hours. Nothing depends on it: any member can close a due round by hand, and a vault owner can always withdraw within the vault's own rules.

The Score page reads four public events for a wallet: joined, contributed, defaulted and paid out. It shows contributions paid, rounds missed, payouts received and an on-time rate.

on-time rate = contributions paid / (contributions paid + rounds missed)

Reliable is 90% or more, Mixed is 60% to 89%, and At risk is below 60%. It only counts NairaFlow circles on the network you are viewing. There is no stored score and no extra contract, so nobody can edit it.

Mock tokens carry an m in their own on-chain symbol and have a public mint, so they can never be mistaken for the real ones. A Need test tokens card on the create pages mints them in one click.

Every address below comes from a real deployment broadcast, and every contract is source-verified.

• 22 unit tests and a funds-conservation invariant test that runs 128,000 random calls.
• Slither static analysis: no High or Medium findings. The 16 Low results are triaged in the security notes.
• Payouts are pull based, and state-changing functions are guarded against reentrancy.
• A platform admin can pause a circle or vault. It cannot move funds.
• Not audited by a professional firm. The mainnet deployment holds real USDG, so use small amounts.

Three real bugs were found by operating and reviewing the deployed system and are written up in the deployments document. Full notes are in SECURITY.md.

git clone https://github.com/angelraph/nairaflow
cd nairaflow/contracts
npm ci
git clone --depth 1 https://github.com/foundry-rs/forge-std lib/forge-std
forge test

cd ../frontend
npm ci
npm run dev

The agent lives in the agent folder. Copy .env.example to .env, give it a funded testnet key that holds the agent role, then run npm start.