You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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.
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:
@Lin1er (Custom Reclaim AdSense provider: trailing revenue out, credentials redacted #4): the attestor signs whatever the fetched server returned. A zkFetch against attacker.example returning a fat totals carries a perfectly valid signature. If the contract trusts a submitted parameters string, a forged URL is indistinguishable from the real one.
Reproduce the witness digest byte for byte #3: Reclaim's separator is ambiguous — provider="a", parameters="b\nc" hashes identically to provider="a\nb", parameters="c". There is a test asserting that collision.
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
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.
@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 beforeurl 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.
@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:
split window_start/window_end into those six URL values, so the template has 7 values: pub_id, sy, sm, sd, ey, em, ed;
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.
@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.
Activity
feat(#3): reproduce the witness digest, proven against a real attesto…
feat(#8): advance contract skeleton — upgradeable behind a timelock, …
Lexirieru commentedon Oct 14, 2026
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
providerandparametersin the contract; never accept them from the callerTwo independent reasons land on the same answer:
attacker.examplereturning a fattotalscarries a perfectly valid signature. If the contract trusts a submittedparametersstring, a forged URL is indistinguishable from the real one.provider="a", parameters="b\nc"hashes identically toprovider="a\nb", parameters="c". There is a test asserting that collision.The contract rebuilds
parametersfrom 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 identifierRight 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-idis 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
contextand reaches the signature only throughidentifier = keccak256(provider \n parameters \n context). So #9 must recompute the identifier from full claim info before trusting any figure.canonical_context_matchesinsc/reclaim-claimrebuilds the context string from a value rather than parsing JSON, which is how this stays affordable inno_std.4. Numbers this freeze still has to put on the record
timestampSnote (Negative case: a stale proof is rejected #26 tests this, so it cannot be left vague)revenueUsdis a decimal string: parse to fixed-point, rejecting more than two decimals, before sizingStill blocked by #5.
docs(#6): freeze the interface, without waiting for the AdSense accou…
Lexirieru commentedon Oct 14, 2026
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
parametersbytes — is now admin-settable viaset_claim_template. The delay costs us one storage write instead of the contract. Until it is set,request_advancerefuses withTemplateNotSet, so the contract deploys safe rather than permissive.What you need from it
@Lin1er — the relay (#17) builds the claim so that
contextAddressis the borrower'sG…andcontextMessageis the constant in §3. Both of your findings are in:provider/parametersare 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_idis 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
contextAddressbinds 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 indocs/licensing.md, including the network clause that matters for a hosted pipeline.Next from me
#9 through #15 are unblocked. Starting #9.
feat(#16): API skeleton: /health, /ready, /config, exact-origin CORS
feat(#16): API skeleton: /health, /ready, /config, exact-origin CORS
feat(#16): API skeleton: /health, /ready, /config, exact-origin CORS (#…
Lin1er commentedon Oct 19, 2026
@Lexirieru I checked
docs/interface.mdandsc/advance/src/claim.rsonmainagainst 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 inverify_claim.This matters for #61 as well. If the template is pinned from the first proof as things stand,
set_claim_templatewould get bytes the contract cannot rebuild.claim.rs,interface.md§3/§8)be/src/adsense/request.ts)contextMessage="Forepay advance request""forepay:adsense-trailing-revenue:v1"extractedParameters={currency, endDate, revenueUsd, startDate}, with dates asYYYY-MM-DD{revenueUsd}only…?startDate=<v>&endDate=<v>&metrics=…startDate.year=2026&startDate.month=7&startDate.day=1), unpadded. The provider's date regexes repeat those numbers insideresponseMatches, and those come beforeurlin the sortedparameters.Why the provider can't produce #2 and #3. AdSense has no string form for a date.
startDate.year/.month/.day. In Google's API this is the documented query encoding of agoogle.type.Date."startDate": {"year": 2026, "month": 7, "day": 1}."2026-07-01"cannot be extracted from that response.window_startvalue 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. Itsparameterswould carrybody,headers,responseMatchesandresponseRedactionsahead ofurl, which is what the smoke proof'sparametersshow.Proposal, the smallest change on each side:
Provider (mine, one PR):
parameters.contextMessageto"Forepay advance request".Contract (yours):
request_advance(… window_start: "YYYY-MM-DD", window_end …)and the nullifier exactly as they are.year/month/day. That is fixed-width parsing of 10 bytes, with no JSON involved.pub_id, sy, sm, sd, ey, em, ed.rebuild_context, setextractedParametersto{"revenueUsd":"<x>"}."currencyCode": "USD"match, which sits in the signedparameters.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:
contextAddress;Once #2 and #3 are settled, I'll ship the provider side, confirm here, and hand you the exact template parts and
provider_hashfor #61 from the first real proof.Lin1er commentedon Oct 20, 2026
@Lexirieru the provider half of the proposal above is done in #74:
contextMessageis nowForepay advance request, byte for byteclaim::CONTEXT_MESSAGE. A test now readsclaim.rsand compares the two, so they can't drift apart again.responseMatchesandresponseRedactionsare 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, soclaim.rscan't rebuild a real claim until it does two things:window_start/window_endinto those six URL values, so the template has 7 values:pub_id, sy, sm, sd, ey, em, ed;extractedParametersas{"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.rschange as a PR for you to review. Just say so; I won't touchsc/without your go-ahead.Lin1er commentedon Oct 20, 2026
@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.rsPR for you to review. It's what's holding #61 and any real proof on chain.fix(#76): rebuild the claim in the encoding AdSense actually produces (…
fix(#4): provider side of #6 — the contract's context message, no dat…