CRC FlowFix

An embedded-first Circles mini app that answers one practical question before a CRC payment:

Can I send this amount to this recipient right now, and if not, what is the safest next action?

The problem

Your total CRC balance can be higher than the amount you can actually send to a specific recipient. Routeability depends on trust connections and how tokens are distributed across the graph. FlowFix preflights the payment and explains the result in plain language.

What it does

• Detects whether it is running inside the Circles host or standalone.
• Connects or creates a Circles account through the host.
• Accepts a recipient address and CRC amount.
• Runs a Pathfinder max-flow preflight against the Circles RPC.
• Shows one of four clear outcomes:
  • Sendable now — route exists for the full amount.
  • Partial amount only — a smaller amount can be sent.
  • No route — no trust/path currently reaches the recipient.
  • Check failed — network/SDK error; retryable.
• Lets the user preview and submit the payment through the embedded host wallet.
• Generates shareable repair links and Gnosis App QR-code fallback payments.
• Optionally polls for standalone QR payment confirmation via transfer-data events.

Circles primitives used

• @aboutcircles/miniapp-sdk host bridge (onWalletChange, requestCreateAccount, sendTransactions, onAppData).
• @aboutcircles/sdk Pathfinder (findMaxFlow, findPath).
• @aboutcircles/sdk-transfers TransferBuilder.constructAdvancedTransfer / buildFlowMatrixTx.
• @aboutcircles/sdk-utils encodeCrcV2TransferData / decodeCrcV2TransferData for standalone payment references.
• Circles RPC event queries for standalone confirmation.

Embedded vs standalone

Feature	Embedded (Circles host)	Standalone (direct browser)
Connect account	Via host passkey flow	Not available; read-only fallback
Preflight route	Yes	Yes (same RPC)
Submit payment	Via sendTransactions	Gnosis App deep link / QR
Confirmation	Host shows result	Client-local event polling

Setup

Requires pnpm.

pnpm install

Copy the example environment file if you want to override the default RPC URL:

cp .env.example .env.local

Run locally

pnpm dev

Open http://localhost:3000. Outside the Circles host the app shows a standalone message and disables the embedded wallet flow.

Test

pnpm test

Pure domain logic tests run with Vitest + jsdom. They do not require private keys or network calls.

Build

pnpm build

Deploy

This is a standard Next.js 16 app. The easiest deployment target is Vercel:

vercel

The CSP frame-ancestors header in next.config.ts already allows *.gnosis.io and *.vercel.app so the app can be iframed by the Circles playground.

Testing inside the Circles playground

1. Deploy the app to a public HTTPS URL.
2. Open https://circles.gnosis.io/playground?url=<your-deploy-url>.
3. The host injects a Safe address; the wallet badge in the header updates.
4. Enter a recipient and amount, then Check route.

Safety notes

• FlowFix never asks for seed phrases or private keys.
• Recipient, amount, and route status are shown before any wallet approval.
• The app never recommends blindly trusting unknown accounts.
• Trust Score is never treated as a guarantee or real-world eligibility score.
• Account-scoped state is reset on every onWalletChange event.

Known limitations

• Standalone payment confirmation is client-local for MVP. It polls Circles events but has no backend.
• Live embedded transaction submission requires a real host wallet and a routeable recipient; unit tests cover the state machine, not the live network.
• Event type CrcV2_TransferData is used per the project spec but may not yet be exposed in the public SDK EventType enum; the adapter casts it explicitly.

Project structure

app/                  Next.js app router
components/flowfix/   FlowFix-specific UI
components/ui/        shadcn/ui primitives
host/                 @aboutcircles/miniapp-sdk bridge
circles/              @aboutcircles/sdk / RPC adapters
domain/               Pure domain logic, types, state machines
test/                 Unit tests

QA checklist

• Standalone direct browser open renders the app.
• Embedded playground open renders inside the iframe.
• Connect/create account flow updates the wallet badge.
• Invalid recipient address shows inline error before route check.
• Invalid amount shows inline error before route check.
• Route check success state appears when a known route exists.
• Partial/blocked states appear or can be simulated via fixtures.
• Transaction reject path leaves the form recoverable.
• Transaction success path shows hashes and a "check another payment" action.
• Mobile viewport (375px) is usable without horizontal scrolling.
• Share link round-trips recipient, amount, and note.
• Standalone QR link encodes transfer data that decodes back to the reference.

Garage submission

Prepared data for https://garage.aboutcircles.com/register:

• App name: CRC FlowFix
• Short pitch: Preflight CRC payments and see whether the full amount can reach the recipient before approving the transaction.
• Live demo URL: (deploy then fill in)
• GitHub repository: https://github.com/bitfalt/crc-flowfix
• Circles integration: Uses account connect, Pathfinder max-flow, route construction, transaction submission, transfer annotations, and standalone QR fallback.

License

MIT — see LICENSE.