How the app flows

This note is a map. It shows who does what, in what order, and where the campaign vs the ATS bond live.

The longer explainer is README-non-technical.md. ATS in plain English: README-ats.md. Check this creator: README-creator-lookup.md. What the prototype can and cannot do: README-limitations.md. Technical README: README.md.

This is a hackathon prototype on Hedera testnet (play money).

---

Big picture

Three people, two screens.

The founder writes a listing: who they are, the story, how much they want.

The backer reads that listing, can look the founder up, then sends a little play money.

The operator is the office after money is in. They print a locked receipt, freeze it, then send money out.

Two screens, two jobs:

• Campaign page = “I want to fund this.”
• Operator desk = “Print the certificate, lock it, pay people.”

---

End to end

The whole product, top to bottom.

Start a campaign only creates a flyer on the website. No Hedera transaction. No bond yet.

Check this creator is the look-up before you send money. You can skip it with Pledge anyway.

Pledge is the real cash move: HBAR leaves the backer’s wallet and sits in one treasury (the office jar).

The ATS bond is not that money. It is a locked receipt printed later. Pay founder / Pay backers is when the raise actually leaves the jar.

---

Check this creator

The backer clicks once. The app’s robot does the work and pays the tiny fees.

The Graph is a free live look-up of three lending books (Aave, Compound, Spark) for the founder’s wallet.

x402 is two tiny Hedera fees. The app pays them, not the backer: one for the web search, one for a written risk note.

HCS is a public fingerprint of that note (and the payment receipts) so nobody can quietly swap the text later.

Step-by-step of this click: README-creator-lookup.md.

---

Operator desk and the bond

The listing lives in the app. The bond lives on Hedera. They point at each other; they are not the same thing.

The desk is /campaigns/<slug>/operate — the office after money is in. Backers pledge on the campaign page. You do the rest here.

Two piles. Pledging only fills the cash pile.

Button-by-button: Issue bond and Mint share.

1. Issue bond

Prints one blank form for this campaign and registers it on Hedera. You get a contract id (0.0.…) and a HashScan link. The flyer stores that id as tokenId so the site knows “this listing’s IOU is that contract.”

On the bond: a name, a ticker, a short memo like zikibols:your-campaign-slug, plus dummy paperwork (fake ISIN, face value, dates). Not the pledged amount. Not the story.

Does not: give anyone a share, move HBAR, or need a pledger first. You can issue with an empty list. You can only issue once.

2. Mint share — once per unique pledger

The desk lists everyone who pledged (same wallet = one row, amounts added up). Each Mint share click:

1. Puts that wallet on the allowed list (only listed wallets can hold the IOU)
2. Hands them 1 unit of the same bond

A 13 ℏ pledge still mints 1 share, not 13. Alice 13 ℏ and Bob 50 ℏ each get 1 of the same IOU.

You can mint another pledger. The same wallet cannot be minted twice. After the first mint, status becomes Transferred. Each mint is saved in runtime[slug].mints with a HashScan tx.

Mint to another address is for a wallet that is not on the pledge list.

Mint does not create the bond (that was Issue) and does not pay anyone.

3. Pause bond

One stamp on the whole bond: “cannot be freely sold.” Not per backer.

Mint already put each holder on the allowed list, so Pause does not add them again. After Pause, minting is closed and the listing stops taking pledges.

4. Unpause bond

Peel that stamp back off. Transfers resume, minting reopens, the listing takes pledges, and Pay founder / Pay backers go back to waiting for a pause. The button only shows while the bond is paused, and it refuses once either payout has run — a settled raise cannot reopen.

5. Money out

Pay founder / Pay backers are ordinary treasury HBAR sends. The amounts come from pledges in state.json, but who gets paid follows the bond: only backers you already minted a share to.

Pause first, then mint everyone first. Pay founder and Pay backers both refuse until the bond is paused. If any pledger still has no share, Pay backers also opens a modal naming them and pays nobody.

There is a cap (PAYOUT_MAX_HBAR) and a reserve the jar must keep for gas. Nothing checks that an invoice cleared or a crop sold — an operator decides it is time.

Order

Issue bond  →  Mint share (each unique pledger)  →  Pause bond
        →  Pay founder  and/or  Pay backers
                   ↑                    │
                   └── Unpause bond ────┘  (only before either payout)

Issue first is the usual path. Mint cannot run before Issue. Mint cannot run after Pause — until you Unpause bond.

Mint every pledger before you Pause. The desk refuses to pause while anyone is unminted. Pause closes minting and new pledges, and Pay backers needs every pledger to hold a share.

ATS is the printer and the rulebook. The bond is the locked receipt. The HBAR is the cash. More on the workshop: README-ats.md.

---

Where things live

On HashScan: the pledge txs into the treasury, the bond contract, each mint, pause, and the payout txs.

Only on the flyer (.data/state.json): the story, the goal, the progress bar, which pledge belongs to which campaign, and who already got a unit. If you open HashScan with no app, you cannot see the Rotterdam story.