Skip to content

Proof relay: carry the proof and bind it to a Stellar address #17

Open

Description

@Lexirieru

Owner: James (@Lin1er) · Branch: feat/17-proof-relay · Milestone: M3 · Blocked by: #4, #6

What to build

The relay takes the proof produced by a Reclaim session in the creator's browser and submits it to the advance contract with the borrower's Stellar address bound in.

Base it on reclaimprotocol/reclaim-stellar-example — the SOW names zkfetch-stellar-example, which 404s; see #4.

The binding must be inside the signed claim

Not a parameter sitting next to it. See #9: a binding the witness did not sign is not a binding — it is a field the attacker fills in. If the Stellar address is not inside the bytes covered by the attestor's signature, anyone can take someone else's proof and point the disbursement at their own wallet.

The relay's job is to get the address into the claim before it is signed, not to attach it afterwards.

Done when

A proof produced in a real browser session reaches the contract through the relay and disburses on testnet, with a transaction hash.


Working agreement

  1. One issue, one owner. 2. Branch per issue, named above — not the GitHub-suggested one. 3. MCP Stellar Raven for any Stellar/Soroban fact that gets written down. 4. Merge through PR review by Axel (PM); no self-merge. If an ACC has not arrived within two days on something already verified, merge and say so in the PR. 5. Deploys need evidence: contract address or tx hash on stellar.expert, recorded in docs/deployments.md. 6. Secrets live in .env, gitignored, chmod 600 — never printed, never committed, never pasted into an issue or PR. Only public G… and C… addresses appear anywhere. 7. Issues, commits and PRs in English.

Scope: instawards/Forepay Instawards SOW.pdf. Timeline assumes 2026-10-09 → 2026-11-08; tell Axel if the real window differs.

Activity

  1. added
    M3-appWeek 3 — proof relay and the creator front end
    deliverable-2SOW Deliverable 2 — Reclaim provider and application
    on Oct 9, 2026
  2. added a commit that references this issue on Oct 15, 2026
  3. Nabil-Aufa commented on Oct 16, 2026

    @Nabil-Aufa
    Collaborator

    @Lin1er, the front end side of #17 is ready to plug in. #57 (#20, Prove and accept) calls one seam, proveRevenue(borrower, onStage) in fe/src/lib/reclaim/, which must resolve to an AdvanceRequest (fe/src/lib/stellar/contract.ts: revenueUsd, pubId, windowStart, windowEnd, timestampS, epoch, signature, recoveryId).

    • While NEXT_PUBLIC_RELAY_URL is empty, a mock walks through the session stages and returns fixed values. That proof is refused by the deployed contract, as it should be.
    • Everything after the seam is real: request_advance is simulated before the offer, then signed and sent, and every contract code has its own words.

    What I need from you:

    1. The browser flow: popup, QR or redirect, and which Reclaim SDK. ARCHITECTURE.md says not to install one before you choose.
    2. The relay's API: what it takes (at least the borrower's G…, which must end up inside the signed claim as contextAddress) and what it returns.

    Also for the #5 gate, the AdSense account: if someone with an active AdSense website account agrees to help, can they just send you an access token from the OAuth 2.0 Playground (adsense.readonly, valid about one hour) for you to run pnpm -C be prove:adsense? And through which channel would you like to receive it, so the token is never posted anywhere public?

  4. added 2 commits that reference this issue on Oct 17, 2026
  5. Lin1er commented on Oct 20, 2026

    @Lin1er
    Collaborator

    @Nabil-Aufa answers to both questions are in #73 (stacked on #66). The full reference is docs/api.md → "The proof relay".

    1. Browser flow. Google's own sign-in popup, through the Google Identity Services token client, asking for adsense.readonly only. No Reclaim SDK in the browser, so there's nothing to install on the Reclaim side. The proving happens on the relay, because snarkjs needs about 330 MB of circuit files and roughly 10 minutes of CPU per proof. For your ProveStage:

    • waiting is while Google's popup is open;
    • reading runs from POST /proofs until the job ends.

    2. Relay API.

    • Request: POST /proofs with { borrower, accessToken, publisherId? }. It answers 202 { id, stage }.
    • Polling: poll GET /proofs/:id every few seconds. The job ends at done or failed.
    • On done: request is your AdvanceRequest, except timestampS and epoch arrive as strings, so pass them through BigInt().
    • On failed: the job carries error.code:
      • token: the creator signs in again;
      • account: no READY AdSense account;
      • provider, prove, audit, internal: our side, show a retry.
    • Submission stays with the wallet. The relay never submits; your #20 Prove revenue, see the offer with its derivation, accept #57 flow signs request_advance as it does now.

    The front end needs two values: NEXT_PUBLIC_RELAY_URL, plus a Google OAuth Web client id with your origins listed as authorized JavaScript origins.

    On the AdSense token for #5: yes, an OAuth Playground token works. Send it to me in a private DM, never on GitHub. It expires within an hour anyway. Once your side calls the relay, the helper can sign in themselves through the popup, and nobody has to pass a token by hand.

    Still blocked, as before: a READY AdSense account, and the encoding decision on #6 before #61 can pin the template.

  6. added a commit that references this issue on Oct 20, 2026
  7. Lin1er commented on Oct 20, 2026

    @Lin1er
    Collaborator

    @Nabil-Aufa the relay is live for testing: https://api-forepay.jameshub.fun. It also serves the #16 routes.

    Still missing before a real run: a Google OAuth Web client id (see #5) and a READY AdSense account (#5).

  8. added a commit that references this issue on Oct 20, 2026
  9. added 3 commits that reference this issue on Oct 20, 2026
  10. 10 remaining items

  11. added 2 commits that reference this issue on Oct 23, 2026
  12. added 7 commits that reference this issue on Oct 25, 2026
  13. added a commit that references this issue on Oct 27, 2026
  14. added a commit that references this issue on Oct 29, 2026
  15. added 3 commits that reference this issue on Oct 29, 2026
  16. added a commit that references this issue on Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

M3-appWeek 3 — proof relay and the creator front enddeliverable-2SOW Deliverable 2 — Reclaim provider and application

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions