Skip to content

#17 Proof relay: POST /proofs, bound to the borrower inside the signed claim - #73

Merged
Lexirieru merged 5 commits into
mainfrom
feat/17-proof-relay
Oct 20, 2026
Merged

Lexirieru merged 5 commits into
mainfrom
feat/17-proof-relay

Conversation

@Lin1er

@Lin1er Lin1er commented Oct 20, 2026

Copy link
Copy Markdown
Collaborator

Refs #17. Stacked on #66 (#16): review that first. Once it merges, this PR retargets to main and shows only its own commit.

This answers Nabil's two questions on #17. The full write-up is in docs/api.md → "The proof relay".

1. The browser flow

The creator signs in with Google's own popup (Google Identity Services token client, scope adsense.readonly only). That popup returns an access token, and the front end sends it to the relay together with the wallet's G…. No Reclaim SDK runs in the browser.

Proving happens on the relay, not in the browser, for two reasons:

2. The relay's API

  • POST /proofs takes { borrower, accessToken, publisherId? }. It answers 202 with a job id.
  • GET /proofs/:id reports the job's progress: queued → checking → proving → auditing → done or failed.
  • When done, the job carries request, which is exactly AdvanceRequest. The only difference: timestampS and epoch are strings, so pass them through BigInt().
  • When failed, the job carries an error.code that says whose move it is:
    • token: sign in again;
    • account: there is no AdSense account, more than one, or one that is not READY;
    • provider, prove, audit, internal: our side.
  • The relay does not submit the transaction. request_advance needs the borrower's own auth, so the wallet signs it, as #20 Prove revenue, see the offer with its derivation, accept #57 already does.

Binding and the token

  • Binding. The G… goes into context.contextAddress before the attestor signs (Read the attested amount and the bound borrower from a verified proof #9). The audit then refuses any proof whose signed context names someone else, so that proof is never returned.
  • The token is used for three pre-flight reads and in zkFetch's secret headers, which stay out of the claim. It is held only in memory, inside the running job. It is never written to disk, logged or returned, and error messages are scrubbed of it. A proof that contains the token anywhere fails the audit.
  • One proof runs at a time, with a single job per borrower and a short queue. A busy relay answers 503 with Retry-After.

Shared code

The pre-flight checks moved out of the prove:adsense CLI into adsense/account.ts and relay/prove.ts. The CLI and the relay now run the same steps.

Verified

  • pnpm -C be test: 97 pass (22 new). Lint and tsc are clean.
    • The new tests sign claims with a throwaway attestor key. Each claim is built from the request the relay actually sent, so the tests check the real binding and the real token placement.
    • They also cover: a proof bound to another borrower is refused, a proof that leaks the token is refused, a CLOSED account stops before the attestor, a wrong response shape is caught locally, serial jobs, 409/413/503, and CORS preflight for POST.
  • Live run. pnpm -C be start with Reclaim credentials and the circuit files: /config reports "relay": true. POST /proofs with an invalid token gave 202, then the job ended failed with code token, from Google's real 401.

Not done yet: what blocks "Done when"

@vercel

vercel Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
forepay Ready Ready Preview Oct 20, 2026 3:26pm UTC

@Lin1er

Lin1er commented Oct 20, 2026

Copy link
Copy Markdown
Collaborator Author

Deployed for testing at https://api-forepay.jameshub.fun, from this branch with #74 merged in. The evidence is in docs/deployments.md.

  • Routes: /config reports the recorded addresses with "relay": true, and /ready is ok.
  • Proving on the host: a smoke proof made there was signed by the production attestor in 54 s. verify_proof simulates Ok on the genuine digest and refuses the one-byte flip with #5. So proving takes about a minute here, not the ~10 minutes I measured on my laptop.

@Lexirieru
Lexirieru changed the base branch from feat/16-backend-api to main October 20, 2026 09:07
The relay takes the borrower's G… and a Google access token with
adsense.readonly, proves the trailing AdSense revenue with zkFetch, and
returns request_advance's arguments. The G… goes into contextAddress before
the attestor signs, so the binding is inside the signed claim (#9).

Proving takes about ten minutes of CPU with snarkjs, so the request answers
202 with a job id and the front end polls. One proof runs at a time; one job
per borrower; a short queue. Jobs live in memory and the token only in the
running job's closure: never stored, logged or returned, and scrubbed from
errors.

The pre-flight checks (account, READY, response shape) move from the
prove:adsense CLI to adsense/account.ts and relay/prove.ts, so the CLI and
the relay run the same code. Failures carry a code that says whose move it
is: token, account, provider, prove, audit.

The browser flow and the API are in docs/api.md.
Deployed from feat/17-proof-relay with #74 merged in. /config reports the
recorded addresses and relay: true; /ready answers. A smoke proof made on
the host was signed by the production attestor in 54 s and passes
verify_proof in simulation, with the one-byte flip refused as #5.
@Lexirieru
Lexirieru force-pushed the feat/17-proof-relay branch from fb4794e to f867f36 Compare October 20, 2026 09:08
@Lexirieru

Copy link
Copy Markdown
Collaborator

Retargeted to main and rebased — I force-pushed feat/17-proof-relay, so git fetch && git reset --hard origin/feat/17-proof-relay before you touch it again.

#66 landed as a squash merge, so your branch carried the original #16 commits against a main that had one. I replayed only the three commits unique to this PR. Diff against main is +1159/-131, which is your +1152/-131 plus the seven lines below.

One conflict, in docs/deployments.md, and what I did with it

Both your ## #16 / #17 section and my ## #76 section are appends to the end of the file, so they are both kept, mine first.

I also added a dated note under your "What is not claimed yet", because one line in it stopped being true while this PR was open:

"the contract cannot rebuild a real AdSense claim until the contract side of #6 lands"

It landed — #76 is merged in #79, and your #74 is merged too. What is left is only the account (#5, #77). I added the correction as a marked, dated note rather than editing your sentence, so the record still shows what was true when you wrote it.

One caveat in that note worth repeating here: the wasm carrying the new encoding is uploaded and proposed but behind its 24-hour timelock. execute_upgrade is not before 2026-10-21 08:50 UTC. Until then both contracts still run the old encoding, so a real AdSense claim would still be refused — by the old code, for the old reason.

Not reviewing this one yet

I approved #66 after running it. This PR is 1,159 lines of relay I have not read, and I would rather give it the same treatment than wave it through on the strength of the last one. It is green and mergeable; say the word if you want it merged now and I will do the review first.

For #61, when you get there

The template you hand me is now eight parts with seven values between them, in this order:

pub_id, start_year, start_month, start_day, end_year, end_month, end_day

Each date unpadded — 7, not 07 — exactly as buildRevenueUrl writes them. set_claim_template refuses anything that is not eight parts, so a four-part template fails loudly instead of per-proof.

The front end has to tell "your proof is still running" from "the relay is
full" from "the relay is not set up here", and the status alone cannot: 503
means two of them. Each refusal now says which in `code`.

409 deliberately does not return the running job's id. A borrower's address is
public, and the id is what reads their revenue, so the front end keeps the id
it was given with the 202 (review on #75).
Lin1er added a commit that referenced this pull request Oct 20, 2026
Review on #75:

- The job id is kept in sessionStorage. Coming back to /advance, or
  reloading, while the relay proves waits on the same job without a second
  sign-in, instead of a new POST the relay refuses as already running.
  A kept job the relay no longer has (restart, or past its hour) starts a
  fresh proof. The id is cleared once the job ends, not when the screen is
  left.
- A relay that does not answer is RelayError unreachable, not "We could not
  reach Stellar". Google's script failing to load is googleUnavailable.
- error_callback popup_failed_to_open is popupBlocked: the creator closed
  nothing.
- 409 is running, 503 is busy or unconfigured, read from the relay's new
  `code` (#73), the status as fallback. unconfigured reads like
  relayNotReady, not "try again".
- No 30-minute give-up: polling runs to the hour after which the claim is
  too old and the relay has forgotten the job.
- preloadSignIn() is exported for 2a to call on mount (the preload in 4).

The copy for the four new panels is a first pass for Nabil to replace.
Scrubbing a one-character token out of a failure message cut that
character out of every word ("e[redacted]pired"), seen live on the relay.
Google's tokens run to hundreds of characters; under 16 is a 400.
@Lin1er

Lin1er commented Oct 20, 2026

Copy link
Copy Markdown
Collaborator Author

Two follow-ups from the review on #75, both live on api-forepay.jameshub.fun:

  • Every refusal carries a code: running (409), busy (503, Retry-After: 120), unconfigured (503). The front end needs these because a 503 alone means two different things. The 409 deliberately does not return the running job's id. A borrower's address is public, and the id reads their revenue. docs/api.md updated.
  • A token under 16 characters is a 400. Scrubbing a one-character token out of a failure message cut that letter out of every word ("e[redacted]pired"). I saw it live while checking this.

Checked live after the redeploy: {"accessToken":"x"} → 400, and a second POST for the same borrower → 409 {"code":"running"}. 99 BE tests pass.

@Lexirieru Lexirieru left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read it properly this time, as promised, and ran it. 99 tests pass on this branch after a clean install — your 97 plus the two #74 added when it merged.

The design is right: proving on the relay rather than the browser, the G… inside context.contextAddress before zkFetch runs, the audit refusing a proof bound to anyone else, the token confined to the running closure and scrubbed out of every message. isoDate pads to YYYY-MM-DD while buildRevenueUrl writes unpadded — which is exactly what #76 needs, and I checked those two against claim::split_date rather than assuming.

Approving and merging. Three things below; the first is the one that matters, and it is not about your code.

1. Do not add the job id to the 409. @Nabil-Aufa asked for it on #75 and it would be a real leak.

Your comment at app.ts:198 says it already:

No job id here: a borrower's address is public, and the id is what reads their revenue.

That is correct and it should not be changed. #75's review item 2 proposes that "a 409 could also return the running job's id, so a tab that lost its storage can pick the job up". If it did, then anyone who knows a creator's G… — it is on the ledger, it is in every transaction they have ever signed — could POST /proofs with that address and a junk token, receive the id of the creator's running job, and poll it until it reports their AdSense revenue to the cent.

The job id is a bearer capability. The borrower address is not a secret. Handing the first out in response to the second collapses the two.

The resume Nabil wants is still fine, and worth doing — just not through the 409:

  • sessionStorage holding {borrower, jobId} is the whole fix for the ordinary case (navigate away, come back). It needs nothing from this PR.
  • The lost-storage case (hard reload, crash, other device) cannot be solved without proving control of the wallet, i.e. signing a challenge the relay checks. That is a real feature and out of scope for 30 days.
  • So the honest answer for lost storage is: prove again, and the copy should say so rather than showing "We could not finish your proof".

@Nabil-Aufa — this is the one item on #75 I would drop rather than implement. Everything else in that review looks right to me, especially item 1: "a few seconds" for a ten-minute wait is the kind of copy that causes the data loss in item 2.

2. keepMs is one hour, and so is the proof's shelf life — so a resumed job can hand back a proof the contract will refuse

ProofJobs keeps a finished job readable for keepMs = 3_600_000. The contract's MAX_PROOF_AGE_SECONDS is also 3600, measured from the attestor's timestampS, which is set near the end of proving.

So a job read at minute 55 returns stage: "done" and a complete AdvanceRequest whose proof has about five minutes left — and the creator then has to approve a wallet signature, which can easily take longer than that. They reach the last step of the flow and get #12 ProofStale. No money is lost (simulation refuses it before submission), but it is the worst possible place to fail.

This bites hardest with exactly the resume Nabil is adding: a tab that comes back after 50 minutes will cheerfully present a dead proof as a live offer.

Cheapest fix, and it belongs here rather than in the front end: put the deadline in JobView.

/** Unix seconds after which the contract will refuse this proof as stale. */
expiresAt?: number;   // Number(request.timestampS) + 3600

Then #75 can show "this proof has expired, prove again" before asking for a signature, instead of after. Lowering keepMs to ~45 minutes would also work, but it hides the reason rather than reporting it.

3. Small: the token comment is slightly stronger than the code

jobs.ts says the token "lives only in the closure of the running job". It lives in the closure of every queued job too — up to maxQueued = 5 at once — until pump() picks it up and clears job.run. Nothing is wrong with that, and they are memory-only and expire in an hour. But this is a claim about where secrets are, and those should be exact: "in the closure of a submitted job, dropped the moment it starts running" is what the code does.

While there: keying the one-job-per-borrower rule on a public address means anyone can occupy a given creator's slot by posting their G… with a garbage token. It fails within seconds at Google's 401, so it is a nuisance rather than a vulnerability — worth knowing, not worth fixing.


One correction to your "What blocks Done when": the second bullet, "the provider/contract encoding agreed on #6", is settled — #76 landed in #79 and your #74 is merged. The contract code can rebuild your claim. The deployed contracts cannot yet: the upgrade is proposed and behind its timelock until 2026-10-21 08:50 UTC. After that I re-pin the dev template and re-run the rehearsal.

What is left for #5 is only #77: an AdSense account Google will serve a report for. Nobody has answered that one yet.

@Lexirieru
Lexirieru merged commit 26d749b into main Oct 20, 2026
8 checks passed
@Lexirieru
Lexirieru deleted the feat/17-proof-relay branch October 20, 2026 15:33
Lin1er added a commit that referenced this pull request Oct 23, 2026
Review on #75:

- The job id is kept in sessionStorage. Coming back to /advance, or
  reloading, while the relay proves waits on the same job without a second
  sign-in, instead of a new POST the relay refuses as already running.
  A kept job the relay no longer has (restart, or past its hour) starts a
  fresh proof. The id is cleared once the job ends, not when the screen is
  left.
- A relay that does not answer is RelayError unreachable, not "We could not
  reach Stellar". Google's script failing to load is googleUnavailable.
- error_callback popup_failed_to_open is popupBlocked: the creator closed
  nothing.
- 409 is running, 503 is busy or unconfigured, read from the relay's new
  `code` (#73), the status as fallback. unconfigured reads like
  relayNotReady, not "try again".
- No 30-minute give-up: polling runs to the hour after which the claim is
  too old and the relay has forgotten the job.
- preloadSignIn() is exported for 2a to call on mount (the preload in 4).

The copy for the four new panels is a first pass for Nabil to replace.
Nabil-Aufa added a commit that referenced this pull request Oct 29, 2026
* feat(#17): front end relay client behind proveRevenue

proveRevenue now uses the #17 relay when NEXT_PUBLIC_RELAY_URL and
NEXT_PUBLIC_GOOGLE_CLIENT_ID are set. The creator signs in with Google's
own popup (Identity Services token client, adsense.readonly only), the
token and the wallet's G… go once to POST /proofs, and the job is polled
until it answers with request_advance's arguments. No Reclaim SDK runs in
the browser.

Stages keep their meaning: waiting while Google's popup is open, reading
from the relay job until it ends. Closing the popup, or allowing without
the AdSense scope, is ReclaimCancelledError, as closing the window was.
Reopening waits on the newest popup. An abandoned session stops polling
and never settles.

Relay failures carry the relay's code. Three new prove failures say whose
move it is: googleSignIn (sign in again), noAdsense, relayFailed. The mock
is unchanged while NEXT_PUBLIC_RELAY_URL is empty.

* fix(#17): resume a running proof, and name relay failures as the relay's

Review on #75:

- The job id is kept in sessionStorage. Coming back to /advance, or
  reloading, while the relay proves waits on the same job without a second
  sign-in, instead of a new POST the relay refuses as already running.
  A kept job the relay no longer has (restart, or past its hour) starts a
  fresh proof. The id is cleared once the job ends, not when the screen is
  left.
- A relay that does not answer is RelayError unreachable, not "We could not
  reach Stellar". Google's script failing to load is googleUnavailable.
- error_callback popup_failed_to_open is popupBlocked: the creator closed
  nothing.
- 409 is running, 503 is busy or unconfigured, read from the relay's new
  `code` (#73), the status as fallback. unconfigured reads like
  relayNotReady, not "try again".
- No 30-minute give-up: polling runs to the hour after which the claim is
  too old and the relay has forgotten the job.
- preloadSignIn() is exported for 2a to call on mount (the preload in 4).

The copy for the four new panels is a first pass for Nabil to replace.

* fix(#17): end a kept job the relay no longer has, instead of signing in outside a press

When the relay answers 404 for the job id this tab kept (it restarted, or the hour
passed), the session used to clear it and call signIn() straight away. From the mount
effect that opens Google's popup with no press at all, and from a press it opens after
an await. The browser blocks it, and the creator read "Your browser blocked the Google
window", which is not what happened.

Now the session ends as RelayError("gone"), shown as "Your earlier proof has ended"
with Prove my revenue, so the next sign-in opens inside a click.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(#17): load Google's sign-in while 2a is open, so the press opens the popup

Also on a failure panel, whose Prove my revenue starts the same sign-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(#17): words for the Google sign-in, the minute-long wait and the relay's panels

- Waiting: "Sign in with Google in the new window", naming the account and the AdSense box
  to tick. 2a says "Sign in with Google" too.
- Reading: about a minute, longer behind a queue; other pages are safe, a closed tab means
  proving again. It no longer promises a few seconds.
- noAdsense names the Google account as the thing to change.
- proofRunning no longer promises to pick the job up: a 409 carries no id, so it says to
  wait for it to end and prove again.
- busy has its own panel, "Forepay is busy right now", instead of relayFailed.
- "Nothing was saved" becomes "Nothing was charged", the rule the other panels follow.
- "You closed the Google window", since the window is Google's now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(#17): e2e for proving through the relay

A second e2e build has NEXT_PUBLIC_RELAY_URL and a Google client id set (the relay-desktop
and relay-mobile projects). Google's sign-in is a stub on window.google, which relay.ts
uses when it is already there, and the spec answers /proofs as docs/api.md describes.

Covered: the offer after a real-shaped job, noAdsense, the Google window closed and
blocked, a full queue, a 409 from a tab that lost its job, leaving and coming back to the
same job with one sign-in and one POST, and a kept job the relay no longer has, which must
not open Google's window until the creator presses.

Jobs are polled every 200 ms under NEXT_PUBLIC_E2E, as the mock shortens its delays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(#17): relay panels say only what is true, and coming back never flashes 2a

From the strict review of the four commits before this one:
- proofGone: "Your earlier proof is gone", worded for both causes (the relay restarted, or
  an hour passed); the proof did not necessarily finish. Proof-expired illustration.
- noAdsense covers all of the relay's `account` cases: none, several, or not approved.
- popupBlocked and googleUnavailable: "Nothing was read or charged", like relayBusy. The
  cancelled panel keeps the board's "Nothing was read or saved"; the previous commit's body
  overstated how far that rule went.
- The relay panels pair "Prove again" with "Back" in a row, as the board's pairs do;
  "Prove my revenue" did not fit half the row.
- Back on /advance with a kept job, "Reading your revenue" shows from the first render, as
  a pending advance does, so 2a's button never flashes.
- Comments: why accept has no clock check on the proof (simulation refuses with 12 before
  the wallet is asked), the reading copy describes the relay, and JOB_KEY holds one wallet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(#17): pin the relay's remaining panels, the preload and the resume, and make the relay build optional

- Unit: a poll that fails on the network keeps the id, and the next press reaches gone with
  no sign-in. The relay kinds' "Nothing was charged" claims are asserted.
- e2e: token and prove failures with Prove again, a relay that does not answer, Google's
  script loading on 2a before any press, the script failing to load, and no flash of 2a's
  button when coming back to a running proof.
- PW_RELAY=0 leaves out the relay dev server and its projects, for quicker single-spec runs.
  README and .env.example say what the second build and NEXT_PUBLIC_E2E now do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(#17): Back with a kept job waits on it, and noAdsense's title fits every account case

From the strict re-review:
- A failure that keeps the job id (a poll that failed on the network) left "Back" on a
  "Reading your revenue" spinner with nothing running: the start screen shows it for a kept
  job, and toStart() never started the session. toStart() now waits on the kept job, as it
  does on a pending advance. Two e2e: Back after a failed poll reaches the offer with one
  sign-in and one POST; Back after a gone job returns to 2a.
- noAdsense: "We could not use your AdSense account", true for none, several, or not
  approved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Nabil-Aufa <181296848+Nabil-Aufa@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants