Repository navigation
#17 Proof relay: POST /proofs, bound to the borrower inside the signed claim - #73
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Deployed for testing at https://api-forepay.jameshub.fun, from this branch with #74 merged in. The evidence is in
|
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.
fb4794e to
f867f36
Compare
|
Retargeted to #66 landed as a squash merge, so your branch carried the original #16 commits against a One conflict, in
|
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).
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.
|
Two follow-ups from the review on #75, both live on
Checked live after the redeploy: |
Lexirieru
left a comment
There was a problem hiding this comment.
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:
sessionStorageholding{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) + 3600Then #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.
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.
* 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>
Refs #17. Stacked on #66 (#16): review that first. Once it merges, this PR retargets to
mainand 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.readonlyonly). That popup returns an access token, and the front end sends it to the relay together with the wallet'sG…. No Reclaim SDK runs in the browser.Proving happens on the relay, not in the browser, for two reasons:
snarkjs(see FEASIBILITY GATE: one real AdSense revenue proof verified on testnet #5). It needs about 330 MB of circuit files and takes about 10 minutes of CPU per proof.2. The relay's API
POST /proofstakes{ borrower, accessToken, publisherId? }. It answers202with a job id.GET /proofs/:idreports the job's progress:queued→checking→proving→auditing→doneorfailed.done, the job carriesrequest, which is exactlyAdvanceRequest. The only difference:timestampSandepochare strings, so pass them throughBigInt().failed, the job carries anerror.codethat says whose move it is:token: sign in again;account: there is no AdSense account, more than one, or one that is notREADY;provider,prove,audit,internal: our side.request_advanceneeds 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
G…goes intocontext.contextAddressbefore 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.503withRetry-After.Shared code
The pre-flight checks moved out of the
prove:adsenseCLI intoadsense/account.tsandrelay/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.POST.pnpm -C be startwith Reclaim credentials and the circuit files:/configreports"relay": true.POST /proofswith an invalid token gave202, then the job endedfailedwith codetoken, from Google's real401.Not done yet: what blocks "Done when"
READYstate (FEASIBILITY GATE: one real AdSense revenue proof verified on testnet #5). The one we have is CLOSED.adsense/request.tschanges. The relay's API stays the same.NEXT_PUBLIC_RELAY_URLplus a Google OAuth Web client id are all the front end needs. While the consent screen is in testing, only the test users listed on it can sign in.