Skip to content

Pin the AdSense claim template on the deployed advance contract #61

Open

Description

@Nabil-Aufa

Owner: Axel (@Lexirieru) · Branch: ops/61-pin-claim-template · Milestone: M3 · Blocked by: #5

What to do

Call set_claim_template on the deployed advance contract CCQFL2Q66DHFAZU2KPRWNHU4FTZJW75N5XLNXECFFGMW3PROIXJPI2HS with the parameters template and provider_hash from the first real AdSense proof (#5). docs/interface.md §9 already plans this as one admin call, no code change.

Why it blocks the app

Until the template is set, request_advance answers 10 TemplateNotSet for every proof. The creator flow in #57 (#20) checks the proof before showing the offer, so with a real wallet it stops at 2a with "Advances are not open yet": 2b, 2c and 2d cannot happen on testnet. #20's "Done when" (funds received on testnet in a browser) waits on this.

The front end also needs the revenue window from the template: brief §3 rule 9 (#60) says the window shown on 2a and 2b is data read from chain. If the window can be read back (claim_template() returns the parts), say how the front end should extract it.

Done when

  • claim_template and provider_hash read back non-empty from the deployed contract, with the transaction on stellar.expert in docs/deployments.md.
  • A real AdSense proof passes request_advance simulation (no code 10).
  • A note on how to read the window (start and end dates) from the template, for Front end: prove revenue, see the offer, accept it #20.

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-1SOW Deliverable 1 — advance contract
    on Oct 16, 2026
  2. Lexirieru commented on Oct 16, 2026

    @Lexirieru
    Collaborator

    The window cannot be read from claim_template() — correction to brief §3 rule 9

    Answering the third "Done when" first, because it is answerable today and it changes #60 and #20.

    I read the template back from the dev contract CD25Q4TDGDY6CI3LUIWUOH6SXCH6ETIUCI6FUOBI322GCJL5G3EIHQN4, which already has one pinned. claim_template() returns four literal segments and nothing else:

    [0] {"method":"GET","url":"https://adsense.googleapis.com/v2/accounts/
    [1] /reports:generate?startDate=
    [2] &endDate=
    [3] &metrics=ESTIMATED_EARNINGS"}
    

    The publisher id and the two dates are not in there. They are values the caller supplies to request_advance, interleaved between those segments at verification time (claim.rs::rebuild_parameters: a template of N parts takes exactly N−1 values, in the order pub_id, window_start, window_end). The contract rebuilds the signed string, hashes it, and throws the result away — nothing of the window is written to storage by the template.

    That is deliberate: the template is what we pin so a caller cannot choose the URL, and the values are what varies per request. But it means brief §3 rule 9 as written — "the window shown on 2a and 2b is data read from chain" — cannot be implemented. There is no chain read that returns it before an advance exists.

    Where the window should actually come from, per screen

    2a and 2b (before the advance exists): from the proof, not from the chain. The creator picks the reporting window in the UI; the relay asks AdSense for exactly that window and the attestor signs the response for exactly that window. So the front end already holds startDate / endDate before it ever talks to Soroban — they are the same strings it will pass to request_advance, and the contract will reject the call if they do not match what was signed (the digest changes, #14). The front end displaying its own request parameters is not a weaker claim than reading them from chain: the chain is about to verify them.

    The repayment page (#21) and any "my advances" view: from advance(nullifier). That record does store the window. Read from the dev contract just now, for the advance in the 2026-10-15 rehearsal:

    {"borrower":"GA2CD6PMHMBTCFAQDO3R22BSZN5ZSVTAKVNOKXL2SONZBLGRAYIOWWH2",
     "opened_at":1792084442,"principal":"10000000","pub_id":"pub-h1792084434",
     "repaid":"10000000","revenue_cents":"400",
     "window_end":"2026-09-30","window_start":"2026-07-01"}

    The nullifier is nullifier_for(pub_id, window_start, window_end) — or sha256 of the three fields, each prefixed with its 4-byte big-endian length, which the front end can compute locally without a round trip. I verified both paths agree: computing it off chain gave d0cd01df3303…c839, and is_spent on that value returns true on chain.

    So: before the advance, the window is input; after the advance, it is on chain. There is no window in between, and claim_template() is never the source.

    The pinning half is still blocked on #5

    claim_template() and provider_hash() both return null on the production contract CCQFL2Q66DHFAZU2KPRWNHU4FTZJW75N5XLNXECFFGMW3PROIXJPI2HS, so request_advance there still answers #10 TemplateNotSet, exactly as this issue describes. I am not going to pin a guess: provider_hash has to be the one the attestor actually signed, and the parameters template has to be the request the relay actually sent. Both come out of the first real AdSense proof, which is #5. Pinning a wrong one costs another admin call and a confusing failure in between, so it waits.

    What is ready for the moment #5 lands: the dev contract proves the template shape works end to end (7/7 green, tools/runs/2026-10-15T171351Z/), and pinning is one set_claim_template call with no code change.

    cc @sharkzneverending for #60 rule 9, @AncungAulia for #20/#21.

  3. Lin1er commented on Oct 19, 2026

    @Lin1er
    Collaborator

    @Lexirieru heads-up before pinning: the merged AdSense provider (#4) and claim.rs disagree on the date encoding in parameters, on contextMessage and on extractedParameters, so the first real proof would not rebuild. Details and a proposal are on #6. Please hold the pin until that's settled.

  4. Lin1er commented on Oct 20, 2026

    @Lin1er
    Collaborator

    @Lexirieru update: the provider side of the mismatch is in #74. The pin is still blocked on the contract side of #6 (7-value template, extractedParameters = {"revenueUsd":…}). Once that lands and we have a READY AdSense account (#5), I'll send you the exact template parts and provider_hash from the first real proof.

  5. added 2 commits that reference this issue on Oct 20, 2026
  6. Lexirieru commented on Oct 20, 2026

    @Lexirieru
    Collaborator

    The half of this that was not blocked is done: tools/pin_template.py, merged in #83.

    When the first real proof arrives, pinning the template is one command instead of byte surgery:

    python3 tools/pin_template.py PROOF.json --pub-id pub-… --start 2026-07-01 --end 2026-09-30 \
      --contract CCQFL2Q66DHFAZU2KPRWNHU4FTZJW75N5XLNXECFFGMW3PROIXJPI2HS
    

    It prints the eight template parts, the provider_hash, and the set_claim_template invoke line.

    Why this needed a tool

    I checked the real attestor-signed fixture to see what we will actually be splitting. The canonical parameters carries body, headers, method, responseMatches and responseRedactions before url, in sorted-key order — so part 0 will be a few hundred bytes of JSON, not the tidy prefix the test template uses. One wrong byte produces a different identifier and a bare ClaimMismatch, with nothing to say which byte.

    It proves the split three ways, and the obvious check is the weak one

    Check What it rules out
    Round trip Nothing on its own. A split at the wrong occurrence of a short value like "1" reproduces the original perfectly. This is the check it is tempting to stop at.
    Structure The real one: every separator must end with = and part 0 with /. A split inside a publisher id or a regex does not land on a query-parameter boundary.
    Signature The identifier recomputes from the rebuilt parameters and the claim's context and must equal what the attestor signed. Then the bytes are right because the signature says so.

    --self-test runs the whole derivation against the signed fixture and also checks that a window the proof was not signed for is refused rather than turned into a plausible template for the wrong period. It is in CI, so a tool that executes once cannot rot before the one time it is used.

    The command is not theoretical

    Ran it against the live dev contract with --send=no: the CLI parsed all eight Bytes and the provider_hash, and the contract refused with #11 ClaimMismatch — the old wasm's four-part arity check, which is exactly right until #76's upgrade executes.

    So the format is proven. What is left between here and a pinned template:

    1. Contract: rebuild the AdSense claim in the encoding the AdSense API actually produces #76's upgrade executes — 2026-10-21 08:50 UTC, then the contract accepts eight parts.
    2. Security: request_advance and verify_and_reserve take no borrower authorisation #81's upgrade goes out right after it (one pending upgrade at a time).
    3. Find an approved (READY) AdSense account for the gate and the demo #77 — an AdSense account Google will serve a report for. Still unanswered, and still the only thing on this project that cannot be solved with code.

    The other half of this issue, "a note on how to read the window from the template", was answered earlier: it cannot be, and should not be — claim_template() holds literal segments only. Before the advance the window is input; after it, advance(nullifier).

  7. Lexirieru commented on Oct 30, 2026

    @Lexirieru
    Collaborator

    This cannot be done tomorrow, and I want the reason on the record rather than discovered on the day.

    v0.5.0 is proposed on both contracts (#102), executable 2026-10-31 13:49:10 UTC. After execute_upgrade and set_claim_owner, pinning the AdMob template (#96) is one command, because @Lin1er derived it from a real proof signed by the production attestor.

    Pinning this template is not, and the blocker is upstream of the tool:

    The only READY AdSense account available is the one outside the team (#93), whose Jul–Sep 2026 earnings are zero. A zero window does not give a weak proof — it gives none. be/src/adsense/account.ts refuses before the attestor is called:

    if (isEmptyReport(live)) {
      throw new ProveError("empty", "AdSense reports no earnings for this window: …");
    }

    pin_template.py splits an attestor-signed parameters string. There is no such string for AdSense, so there is nothing to split. The tool has been ready since #83 and CI has kept its self-test green for both sources since #101 — it is waiting on a proof, not on work.

    What unblocks this is #77: an AdSense account with non-zero revenue in the window. $0 is explicitly fine for the account per @Lexirieru's original note, but not for this: $0 means no proof at all, and quote("0.00") is AdvanceTooSmall (#31) — I simulated that against the live contract today.

    Until then, production's claim_template() stays null, which after #94 means an AdSense proof fails with TemplateNotSet rather than being checked against AdMob's shape. Fails closed, with the right reason.

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-1SOW Deliverable 1 — advance contract

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions