Skip to content

Freeze the interface everyone builds against #6

Closed

Description

@Lexirieru

Owner: Axel (@Lexirieru) · Branch: docs/6-interface-freeze · Milestone: M1 · Blocked by: #5

Why

Once the gate passes, freeze the shapes so the contract, the relay and the front end can be built in parallel for the next two weeks without drifting apart. Three people building against a moving interface is how a 30-day project loses a week.

What to freeze in docs/interface.md

  • The claim fields the contract reads, and their exact encoding.
  • Nullifier derivation — what makes a proof unique, and an argument for why that choice cannot be gamed. If the nullifier can be made to differ for what is really the same proof, replay protection is decorative.
  • The sizing rule — advance = capped multiple of proven trailing revenue. State the multiple and the cap as numbers, not as "configurable".
  • The repayment ledger's shape.
  • The error table, with codes assigned once. Error codes are never renumbered. A renumber silently rewrites the meaning of every failure already recorded in evidence.
  • Freshness — what makes a proof stale, in seconds, measured against which clock. This is what Negative case: a stale proof is rejected #26 will test, so it has to be a number now.

Done when

docs/interface.md is merged and @Lin1er and @AncungAulia have each confirmed on this issue that they can build against it. A freeze nobody has read is not a freeze.


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 this to the M1 — Feasibility milestone on Oct 9, 2026
  2. self-assigned this
    on Oct 9, 2026
  3. added 2 commits that reference this issue on Oct 9, 2026
  4. Lexirieru commented on Oct 14, 2026

    @Lexirieru
    CollaboratorAuthor

    Four decisions this freeze has to record, gathered from #3 and from @Lin1er's work on #4. Parking them here so they are not rediscovered later.

    1. Pin provider and parameters in the contract; never accept them from the caller

    Two independent reasons land on the same answer:

    The contract rebuilds parameters from a template using the publisher id and the window. It also removes the need for any JSON parsing on chain. Exact template bytes come from the first live proof (#5).

    2. Nullifier keys on (pub-id, window), not the proof identifier

    Right call, for a stronger reason than the one originally given: a nullifier must key on the economic thing being borrowed against — the account and the period — not on the proof's bytes. Any difference in the response at all (a recalculated total, a trailing zero, a window boundary landing a day differently) mints a fresh identifier and would fund a second advance against the same revenue.

    Open question for this freeze: salt it or not. pub-id is public — it is in the ad code on every page — so an unsalted nullifier is publicly computable, and anyone can check whether a given publisher has borrowed for a given period. Not a security hole, since nobody can write a nullifier without a valid proof, but it leaks who borrowed and when in a product whose pitch is proving revenue without revealing things.

    3. The revenue figure is not a signed field

    It lives in context and reaches the signature only through identifier = keccak256(provider \n parameters \n context). So #9 must recompute the identifier from full claim info before trusting any figure. canonical_context_matches in sc/reclaim-claim rebuilds the context string from a value rather than parsing JSON, which is how this stays affordable in no_std.

    4. Numbers this freeze still has to put on the record

    Still blocked by #5.

  5. added a commit that references this issue on Oct 14, 2026
  6. Lexirieru commented on Oct 14, 2026

    @Lexirieru
    CollaboratorAuthor

    Frozen and merged — 31ba1f6 (PR #41). docs/interface.md

    @Lin1er @AncungAulia @Nabil-Aufa — build against this now.

    Why it did not wait for #5

    It was supposed to. It could not: M2 is due 23 October, all eight contract tickets (#9–#15) sit behind this document, and #5 is blocked on an AdSense account that may not exist before 30 October.

    Waiting would have cost the whole of M2 to a problem about a Google account, not about the design.

    So everything that does not depend on the live AdSense response is frozen, and the one thing that does — the exact parameters bytes — is now admin-settable via set_claim_template. The delay costs us one storage write instead of the contract. Until it is set, request_advance refuses with TemplateNotSet, so the contract deploys safe rather than permissive.

    What you need from it

    @Lin1er — the relay (#17) builds the claim so that contextAddress is the borrower's G… and contextMessage is the constant in §3. Both of your findings are in: provider/parameters are pinned in the contract and never submitted, and the nullifier keys on (pub_id, window).

    @AncungAulia — the front end (#19, #20) needs §5: advance = 25% of three months' proven revenue, capped at 100 USDC, floor 1 USDC. #20 shows that derivation on screen, because the determinism is the product. §7 is the error list to render distinctly — NoTrustline (41) is the one that must say "add a USDC trustline", not "something went wrong".

    Two things written down rather than smoothed over

    The nullifier is publicly computable, and salting it would be theatre. pub_id is in the ad code on every page, so anyone can check whether a publisher has borrowed for a period. A salt only helps if it is secret, and nothing in contract storage is secret — it is all readable off the ledger. The real fix is a commitment scheme, out of scope for 30 days. Recorded as a known limitation rather than left for a reviewer to find.

    What #26 may claim is bounded in advance. A proof older than an hour is refused. A proof forwarded and submitted inside the hour is not — and is worth exactly what the borrower's own proof is worth, because contextAddress binds it to them. Sterun nearly overstated the equivalent claim about a QR screenshot, so the limit is written next to the rule this time.

    Verified rather than assumed

    USDC's SAC reports 7 decimals, read from chain today. The Stellar docs warn explicitly against assuming 7, so it was read rather than carried over from Sterish.

    Separately: the repo is now licensed

    AGPL-3.0-only — 3159ca9, PR #42. @Lin1er's catch. The repo had no licence at all, which means all-rights-reserved by default: nobody could legally use or fork it, and Deliverable 1's evidence is "public GitHub repo". zkFetch is AGPL-3.0 and we cannot drop it, so the dependency sets the licence. Reasoning in docs/licensing.md, including the network clause that matters for a hosted pipeline.

    Next from me

    #9 through #15 are unblocked. Starting #9.

  7. added 3 commits that reference this issue on Oct 15, 2026
  8. Lin1er commented on Oct 19, 2026

    @Lin1er
    Collaborator

    @Lexirieru I checked docs/interface.md and sc/advance/src/claim.rs on main against the AdSense provider merged in #35. I can't confirm yet. In three places the two don't line up, so a real AdSense proof would not rebuild in verify_claim.

    This matters for #61 as well. If the template is pinned from the first proof as things stand, set_claim_template would get bytes the contract cannot rebuild.

    # Contract (claim.rs, interface.md §3/§8) Provider (be/src/adsense/request.ts) Who moves
    1 contextMessage = "Forepay advance request" "forepay:adsense-trailing-revenue:v1" Me. I switch to the contract's constant.
    2 extractedParameters = {currency, endDate, revenueUsd, startDate}, with dates as YYYY-MM-DD {revenueUsd} only Contract, see below
    3 Template with 3 values, …?startDate=<v>&endDate=<v>&metrics=… AdSense v2 takes each date as three query params (startDate.year=2026&startDate.month=7&startDate.day=1), unpadded. The provider's date regexes repeat those numbers inside responseMatches, and those come before url in the sorted parameters. Contract, see below

    Why the provider can't produce #2 and #3. AdSense has no string form for a date.

    • The request takes startDate.year/.month/.day. In Google's API this is the documented query encoding of a google.type.Date.
    • The response echoes the dates back as "startDate": {"year": 2026, "month": 7, "day": 1}.
    • A regex named group captures one contiguous substring, so "2026-07-01" cannot be extracted from that response.
    • One window_start value cannot fill three query params.

    The dev template on CD25Q4…HQN4 (…/reports:generate?startDate= / &endDate= / &metrics=ESTIMATED_EARNINGS"}) has also never been through the attestor. Its parameters would carry body, headers, responseMatches and responseRedactions ahead of url, which is what the smoke proof's parameters show.

    Proposal, the smallest change on each side:

    Provider (mine, one PR):

    • Drop the two date regexes. The URL already fixes the window: Google computes the totals for the window in the URL, and the URL is signed via parameters.
    • Switch contextMessage to "Forepay advance request".

    Contract (yours):

    • Keep request_advance(… window_start: "YYYY-MM-DD", window_end …) and the nullifier exactly as they are.
    • Inside the contract, split each date into unpadded ASCII year/month/day. That is fixed-width parsing of 10 bytes, with no JSON involved.
    • Fill a 7-value template: pub_id, sy, sm, sd, ey, em, ed.
    • In rebuild_context, set extractedParameters to {"revenueUsd":"<x>"}.
      • Currency stays enforced through the "currencyCode": "USD" match, which sits in the signed parameters.
      • The window stays enforced through the URL.

    If you'd rather keep the 3-value template and the 4-key context, tell me which bytes you expect for the dates and I'll check whether AdSense can produce them. As far as I can tell from the API, it can't.

    Everything else I can build against as written:

    • the borrower is contextAddress;
    • freshness is 1 h on ledger time, which is comfortable because a proof takes ~10 min on a laptop;
    • errors are 10–59;
    • USDC has 7 decimals.

    Once #2 and #3 are settled, I'll ship the provider side, confirm here, and hand you the exact template parts and provider_hash for #61 from the first real proof.

  9. Lin1er commented on Oct 20, 2026

    @Lin1er
    Collaborator

    @Lexirieru the provider half of the proposal above is done in #74:

    • contextMessage is now Forepay advance request, byte for byte claim::CONTEXT_MESSAGE. A test now reads claim.rs and compares the two, so they can't drift apart again.
    • The date regexes are gone. responseMatches and responseRedactions are now the same for every proof, so the template only has to fill in the URL's values.

    Still blocking, and it's on the contract side: AdSense only accepts dates as startDate.year=2026&startDate.month=7&startDate.day=1, unpadded, so claim.rs can't rebuild a real claim until it does two things:

    1. split window_start/window_end into those six URL values, so the template has 7 values: pub_id, sy, sm, sd, ey, em, ed;
    2. rebuild extractedParameters as {"revenueUsd":"<x>"}.

    Until then, every real proof gets refused, #61 can't pin a template, and #17's "Done when" (a real disbursement) can't happen. Can you confirm this direction, or tell me the bytes you'd rather have? If it helps you move faster, I can open the claim.rs change as a PR for you to review. Just say so; I won't touch sc/ without your go-ahead.

  10. Lin1er commented on Oct 20, 2026

    @Lin1er
    Collaborator

    @Lexirieru I split the contract side into its own issue, #76, so it has an owner and a branch. Please take it, or say the word and I'll open the claim.rs PR for you to review. It's what's holding #61 and any real proof on chain.

  11. added 2 commits that reference this issue on Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

M1-feasibilityWeek 1 — prove the Reclaim pipeline works at all

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions