FlowRail

Slow, or exposed — agencies have lived with those two. FlowRail, on Tempo, is the third.

flowrail.vercel.app

Payout-operations software for agencies that pay many people — freelancers, creators, vendors — on Tempo.

The customer approves a payout run once. FlowRail turns that single approval into a set of per-recipient access keys, each limited to one payee, one capped amount, and a short expiry. An inbound client payment is reconciled to payees via memos. Payouts leave as a batch, and every payout links back to on-chain proof.

---

Try it

Live site	flowrail.vercel.app
Product demo	flowrail.vercel.app/app — the desk
Chain	Tempo Moderato testnet, chain id 42431
Token	pathUSD

Two surfaces, deliberately separate:

• / is the marketing site. Every figure it shows is generated by the real policy engine, not typed in.
• /app is the product UI: the run, the split between what released itself and what is waiting, the held line, and the ledger underneath it.

What is actually proven

Nine probes were executed against Moderato. Five of them are rejections, which are the point — they show the constraints are enforced by a contract rather than by FlowRail's own bookkeeping.

Claim	Outcome
A fresh key is unrestricted until scoped	accepted — and that is the problem
A recipient lock is accepted on-chain	accepted
A locked key still pays its one recipient	accepted
A locked key pays nobody else	reverted
The authorised amount is a hard ceiling	reverted
Expiry is enforced by the chain	reverted
Moderato exposes no atomic batch call	reverted
pathUSD gates recipients it has not seen	reverted

Transaction hashes for every row are in web/src/lib/evidence.ts and rendered on the landing page. Nothing there is a hash the chain did not return.

The rule

address tenure < 7 days        -> dual      (irreversible: unvouched destination)
amount > $500                 -> finance   (a size problem, not a trust problem)
otherwise                     -> auto      (releases on its own key)

The dualCap of $2,000 is deliberately not a tier. A large payment to a long-known address is a size question a human should answer, not a trust question. Merging the two would tell a reviewer that a standing payee is unvouched for.

Auto keys live 7 days. Escalated keys live 12 hours.

Quick start

Requires Node 22+.

# 1. Install both packages (the root package.json is scripts-only)
npm --prefix spike install
npm --prefix web install

# 2. Create a throwaway testnet root key and fund it
npm --prefix spike run agent:new
npm --prefix spike run faucet

# 3. Prove the chain is doing what we claim
npm --prefix spike run probe:chain

# 4. Regenerate the artefact the web app renders
npm --prefix spike run demo:export

# 5. Run the product
npm --prefix web run dev

spike/.data/ is gitignored and holds key material. Never commit it.

Tests

npm run check

check is the pre-push guard. Vercel auto-deploys every push to main, so this is the only thing standing between a broken commit and a broken live site. It fails fast and runs the full green suite:

npm --prefix spike test         # 32 tests, no RPC required
npm --prefix spike run typecheck
npm --prefix web run typecheck
npm --prefix web run lint
npm --prefix web run build

The test suite is deliberately network-free: the whole policy engine — tier decision, escalation, reconciliation, per-leg approval — runs against in-memory fakes. Only the chain adapters touch an RPC, and no test does.

How it fits together

flowrail/
├── README.md              This file.
├── SPEC.md                Original build spec. Superseded in part - see its banners.
├── docs/                  Protocol facts, architecture, decisions, and status.
├── spike/                 Protocol spike: a real CLI that talks to Moderato.
│   ├── src/domain/        Pure policy and types. No chain imports. Unit-testable.
│   ├── src/ports/         Interfaces the domain and app may depend on.
│   ├── src/adapters/      The only code allowed to know Tempo or the filesystem exist.
│   ├── src/app/           Use cases: classify, approve, authorize, settle.
│   ├── src/cli/           Argument parsing and printing, nothing else.
│   └── test/              32 tests. No network.
└── web/                   Next.js: marketing site and product UI.

The dependency rule is one direction only: domain imports nothing from the project, app depends on ports, and only adapters know that Tempo exists. The web app never imports the spike — it reads a generated artefact, so it deploys to Vercel where a sibling checkout and a child process do not exist.

Documentation

The Status section above is the current state of the project. Every other document is dated where it matters.

Document	Read it when you need to
docs/HANDOFF.md	You want the 2026-10-01 snapshot of how work progressed. Superseded — see its banner.
docs/KNOWLEDGE.md	You are new to this codebase. The reasoning, the traps, and what is still open.
docs/PROTOCOL.md	You are touching Tempo selectors, limits, scopes, or witnesses.
docs/SECURITY.md	You are signing anything, or changing what FlowRail may do.
spike/THREAT-MODEL.md	You want the threats enumerated, and which ones are actually fixed.
docs/DECISIONS.md	You want to know why it is built this way, or want to change it.
docs/ARCHITECTURE.md	You are adding a file under spike/src/.
docs/UI.md	You are building a screen.
docs/PRODUCT.md	You need to know what FlowRail is and who it serves.

Read this first

Tempo's canonical TIP documents and the Moderato deployment disagree. Spend periods, richer read functions, and per-token limit updates are specified upstream but not deployed. Building against the TIP will produce code that reverts.

Every protocol claim in this repo is labelled VERIFIED, FROM-TIP, or OPEN. Do not let an unlabelled assumption through. We verify against the deployment, not the specification — see D6 in docs/DECISIONS.md.

Status

Honest, as of 2026-10-05.

Area	State
Protocol investigation	Substantially done. Moderato surface mapped, 9 probes executed.
Spike code	Working. 11 files, ~2,000 lines, 32 passing tests, no known compile errors.
Testnet account	Exists and funded. Keys authorize, lock, and expire as designed.
Landing site	Deployed, 7 pages, builds and lints clean.
Product UI	Built. Wallet connect works.
Atomic batch	Unavailable on Moderato. Not yet re-probed on Tempo mainnet.
New-recipient payouts	Blocked by PolicyForbids. Not worked around.
Auth	Not implemented. No session, no database.

What this is not

Not production-ready, and it would be dishonest to imply otherwise:

• No payment has ever moved through this system. The batch path fails on Moderato and fresh recipients hit PolicyForbids. Every successful probe used a recipient who had already opted in.
• The root key is a plaintext file. It exists to get out of the way of protocol work. It must not survive into production, where the customer should hold it and FlowRail never should.
• The ledger is plaintext JSONL with no integrity check.
• The artefact is unsigned. Validation is not authentication — anyone who can edit demo-run.json can change what the UI claims to have decided.
• There is no auth, no nonce, and no rate limiting, because there is no API yet. Rate limiting a CLI a human runs would be theatre. See T9 in the threat model.

Before any real money moves

1. Resolve PolicyForbids. No onboarding path, no product.
2. Move the root key out of the process.
3. Decide the settlement consistency model, then implement the nonce it needs.
4. Sign the artefact, or serve it from the authority that produced it.
5. Re-probe executeBatch on Tempo mainnet before relying on it or deleting it.

The full list, with the reasoning, is in spike/THREAT-MODEL.md.

Licence

MIT © 2026 Mofe-Bankole.

Note that MIT carries no explicit patent grant, and this project sits on top of Tempo — a chain whose own patent terms are Tempo's, not ours.