Skip to content

AdMob (#90): contract, a revenue source in the template, the nullifier and sizing #94

Closed

Description

@Lin1er

Owner: @Lexirieru · Branch: feat/admob-contract · Parent: #90 · Was blocked by: #93, done 2026-10-26 (both parts) · Start: now on the branch, pending @Lexirieru's go on #90 for merging before 2026-10-30 (otherwise after 2026-11-08) · Label: out-of-sow · Also after: #81 deployed

Let the advance contract verify an AdMob claim beside an AdSense one, without moving anything already stored.

What

  1. enum Source { AdSense, AdMob }.
    • New keys ParamsTemplateFor(Source) and ProviderHashFor(Source).
    • The existing ParamsTemplate and ProviderHash keys are read as AdSense. DataKey stays append-only.
  2. set_claim_template takes source.
    • verify_claim, verify_and_reserve and request_advance take source and rebuild from that source's template.
    • The template pins the host, so an AdMob claim can never be checked against the AdSense template.
  3. AdMob's template layout.
  4. Micros to cents.
    • AdMob's ESTIMATED_EARNINGS is microsValue ("123450000" = $123.45).
    • Add a micros parser that truncates to cents and never rounds up. sizing stays one function over cents.
  5. The nullifier is tagged for AdMob only.
  6. The source of an advance is stored as a parallel key, not as a field.
    • DataKey::AdvanceSource(BytesN<32>) -> Source, written at disbursement. Absent means AdSense.
    • Not a new field on Advance: old entries would fail to decode.
    • Prove that premise first with a test: write an Advance in the old shape, upgrade, read it back.
  7. Upgrade through propose_upgrade and the 24-hour timelock. Evidence goes in docs/deployments.md.

Done when


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.

Activity

  1. added
    M2-contractWeek 2 — the advance contract on Soroban
    out-of-sowNot an Instawards deliverable
    on Oct 25, 2026
  2. removed
    M2-contractWeek 2 — the advance contract on Soroban
    on Oct 25, 2026
  3. Lexirieru commented on Oct 25, 2026

    @Lexirieru
    Collaborator

    A design consequence of #93 that is not written down anywhere yet, and that a template-per-source does not cover on its own.

    @Lin1er already spotted the cause in #93:

    body sorts first in the canonical parameters, before url. The pub_id therefore comes late in the template, and the window comes early.

    What follows from it is bigger than the template. The order of the seven values is hardcoded in the contract, at sc/advance/src/lib.rs:570:

    let parameters =
        claim::rebuild_parameters(&parts, &[pub_id_b.clone(), sy, sm, sd, ey, em, ed])

    rebuild_parameters interleaves N parts with N−1 values positionally. For AdSense that order is right: pub_id sits in the URL path, the dates in the query string after it. For AdMob the window is inside body, which sorts before url, so the order is reversed — the six date numbers come first and pub_id last. A template alone cannot express that, because the template is only the literal segments; the order lives in this line.

    Proven, not inferred

    I built an AdMob-shaped canonical parameters using the key order the attestor itself produced in #93 (body, headers, method, responseMatches, responseRedactions, url) and ran tools/pin_template.py's own derivation against it:

    canonical key order: ['body', 'headers', 'method', 'responseMatches', 'responseRedactions', 'url']
    pub_id at offset 386 | window year 2026 first at offset 65
    
    values_for() order (what the contract hardcodes): ['pub-…8910', '2026', '7', '1', '2026', '9', '30']
    split_parts: REFUSED -> value 1 ('2026') does not appear in the signed parameters after offset 406.
    
    reordered [dates…, pub_id]:               ['2026', '7', '1', '2026', '9', '30', 'pub-…8910']
    split_parts: SUCCEEDED with 8 parts
      part0 ends with '/': False   | part0 tail: 'artDate\":{\"year\":'
      separators ending '=':  [False, False, False, False, False, False]
      separator tails: '\"month\":'  ',\"day\":'  '{\"year\":'  '\"month\":'  ',\"day\":'  '/accounts/'
    

    Two things fall out:

    1. In the AdSense order the derivation refuses an AdMob proof outright — pub_id is at offset 386 and the dates at offset 65, so a left-to-right search for the dates after pub_id finds nothing. Good: it fails loudly rather than producing a wrong template. That refusal is tools(#61): derive the claim template from a real proof, and prove it three ways #83's structure check doing its job on a shape it was never written for.
    2. Reordered it derives 8 parts cleanly, and every structure assertion in check() is wrong for AdMob. Part 0 ends \"year\":, not /. All six separators end with :, not =. The last one ends /accounts/. Those assertions are the check that actually catches a split at the wrong occurrence of "1" or "7" (tools(#61): derive the claim template from a real proof, and prove it three ways #83), so they cannot just be dropped for AdMob — they have to be restated for a JSON body.

    Caveat on my own evidence: this is a synthetic parameters string, not a real AdMob proof. What it establishes is the ordering and the separator shape, which follow from alphabetical key sorting and from JSON escaping and do not depend on the exact bytes. The real parts still have to come from a real proof (#96).

    What I propose for this issue

    Add the value order to the per-source branch, beside the template — not as new storage, since it is derivable from the source:

    // The seven values are interleaved positionally, so their ORDER is part of the
    // source's shape, not just the template's bytes. AdSense carries pub_id in the URL
    // path and the window in the query string after it. AdMob puts the window inside
    // `body`, which sorts before `url` in the canonical parameters (#93), so the window
    // comes first and pub_id last. Getting this wrong does not fail safe into a wrong
    // template — `rebuild_parameters` would hash a different request and the attestor's
    // identifier would not match, surfacing as ClaimMismatch with no hint why.
    let values = match source {
        Source::AdSense => [pub_id_b, sy, sm, sd, ey, em, ed],
        Source::AdMob => [sy, sm, sd, ey, em, ed, pub_id_b],
    };

    Seven lines, no storage change, and it keeps the property that makes this design safe: the template fixes the host, so a claim made against admob.googleapis.com can never be checked against the AdSense template.

    And a test that would have caught it: pin the AdMob template, then verify a claim whose parameters were built in the AdSense order and assert ClaimMismatch. Without it, the failure mode is the one #83's docstring calls the hardest in this pipeline to read — an unexplained mismatch with nothing pointing at the cause.

    This also means #96 is not "the same tool with a different value layout", which is what I wrote on #90. values_for() needs a per-source order and check() needs per-source structure rules. Noted there.

    Still blocked by #93 and still after 2026-11-08 — nothing changes about the schedule. This is only so it is not rediscovered at the point where it costs a timelock cycle.

  4. Lin1er commented on Oct 25, 2026

    @Lin1er
    CollaboratorAuthor

    Agreed on both: the per-source match for the value order, and the test that pins the AdMob template and expects ClaimMismatch for a claim built in the AdSense order. I had noticed body sorting before url, but not that the order lives in lib.rs:570, outside the template. That is exactly what would have shown up as an unexplained mismatch after a timelock cycle.

    The relay side (#95) does not change: the relay sends the reportSpec body as built, and the attestor canonicalises it. I will add one relay test that builds the AdMob parameters from a fixed window and asserts the value order [sy, sm, sd, ey, em, ed, pub_id] against split_parts. That way the relay, pin_template.py and the contract each check the order on their own.

  5. added
    ready-to-devUnblocked: development can start on the issue's branch
    on Oct 26, 2026
  6. Lin1er commented on Oct 26, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru one input for the contract from #100, the relay side of #95:

    • The value order is now pinned by a test on the relay side. be/src/admob/request.test.ts asserts that in the canonical parameters the six date numbers come before /accounts/pub-…, which is your [sy, sm, sd, ey, em, ed, pub_id].
    • The AdMob figure is extracted as revenueMicros, not revenueUsd. So rebuild_context also needs the key per source: one more arm in the same match. A separate name means a micros string can never be read as dollars by anything that sees the claim. If you would rather keep one key, tell me before AdMob (#90): pin the AdMob claim template from a real proof #96 derives the template, because the name is inside the signed context.
  7. added a commit that references this issue on Oct 29, 2026
  8. Lexirieru commented on Oct 29, 2026

    @Lexirieru
    Collaborator

    @Lin1er revenueMicros as its own key. Yes, keep them separate — and the reason is stronger than readability, so I checked it against the live contract before answering.

    If a micros figure were ever read as dollars, here is what quote() on CCQFL2Q6…I2HS actually does today:

    quote("123.45")      = 308625000     stroops   → 30.86 USDC, correct for $123.45
    quote("123450000")   = 1000000000    stroops   → exactly the 100 USDC cap
    quote("0.004")       = error                   → AdvanceTooSmall
    

    $123.45 expressed as 123450000 micros, read as dollars, does not overflow and does not error. It returns the maximum advance, silently, because cap_stroops is 1,000,000,000 and sizing truncates into it. Every AdMob advance would be exactly 100 USDC no matter what the creator earned, and nothing in the pipeline would say a word. A reviewer would see plausible numbers.

    The reverse mistake — dollars read as micros — gives 123.45 micros, truncates to 0 cents, and fails loudly as AdvanceTooSmall. So the two directions are not symmetric: one is a loud refusal, the other is a silent maximum. A shared key would leave the silent one one typo away, in the one place a typo cannot be fixed afterwards, because the key name is inside the signed context and therefore inside the identifier.

    So: one more arm in the same match, as you suggested.

    // The key names the unit, inside the signed context. Not cosmetic: a micros figure
    // read as dollars does not overflow or error — it returns the cap, silently, for
    // every advance. Dollars read as micros truncates to zero cents and refuses. The
    // asymmetry is why these never share a name.
    let revenue_key = match source {
        Source::AdSense => "revenueUsd",
        Source::AdMob => "revenueMicros",
    };

    Go ahead on #96/#101 with revenueMicros.

    Two more things from your #100 note

    The relay-side order test is the right shape. Three independent checks of the same ordering — be/src/admob/request.test.ts, pin_template.py --self-test, and the contract test — is what I would have asked for. They can only agree by being right, because none of them derives the order from the others.

    tools/fixtures/admob-claim.json unblocks me. I was expecting to need the real proof from prove:admob before I could write #94's contract tests. With a signed AdMob-shaped fixture whose identifier recomputes, I can build and test the whole per-source path now, and #96 only has to swap in the real parts afterwards. That is the same thing make_claim_fixture.py did for #76, and it is why that fixture was worth generating rather than pasting.

    Where #94 stands

    Starting it now, on top of #103 rather than on main, because they share one upgrade and one timelock — #81 is deployed as of today (1220778c… and 17262af5…, rehearsal 7/7 GREEN), so propose_upgrade is free.

    That upgrade will also carry the two changes I asked for on #103: refusing when no claim owner is pinned, rather than falling back to the borrower, and its own error code instead of reusing ClaimMismatch.

  9. added a commit that references this issue on Oct 29, 2026
  10. Lexirieru commented on Oct 29, 2026

    @Lexirieru
    Collaborator

    Built: #106, on feat/admob-contract, based on #103 because they share one upgrade and one timelock.

    61 contract tests pass, up from 51. fmt, clippy -D warnings, the wasm build, the no_std wasm check, make_claim_fixture.py --check and pin_template.py --self-test are all clean, and CI's "Test snapshots are committed" passes.

    Everything this issue listed is in, with three things worth pulling out of the PR:

    1. @Lin1er, your AdMob identifier and mine agree byte for byte.

    0x4f3b53c4ab1ee8f71e6827166cda154d4a5fc22cb2df30d58c69b15977d8aba6
    

    make_claim_fixture.py now derives the AdMob chain in Python; be/src/admob/fixture.test.ts derives it in TypeScript (#101). Two encoders, written separately, never compared until today, agreeing on the canonical parameters, the context and the keccak over them. That is the property the AdSense fixture exists to give and the AdMob one now has it too — and unlike tools/fixtures/admob-claim.json, mine is signed, so the contract verifies it end to end rather than just matching a string.

    2. The micros/dollars asymmetry is worse than "confusing", and it is measured. Already on this issue, now pinned by dollars_and_micros_are_never_interchangeable: quote("123450000") is exactly 1000000000 stroops. Not an overflow, not an error — the cap, for any revenue at all.

    3. The item I did not turn into a unit test, and why. This issue asks for "write an Advance in the old shape, upgrade, read it back" — my own ask on #90. With the parallel key, Advance is untouched, so a unit test would only restate that. The honest version is on chain: the dev contract holds real Advance entries written by the old wasm, and reading one back after execute_upgrade is the evidence. It goes in docs/deployments.md with the upgrade, and I will not call the upgrade verified until that read is done.

    Deploy order, which is four admin calls and not one

    Production needs all of these in one sitting, because between 1 and 2 the contract refuses everything by design:

    1. execute_upgrade
    2. set_claim_owner 0x6415200c713135e77157e1536d488df4f2bb7d04
    3. set_claim_template AdSense … — production's claim_template() is still null (Pin the AdSense claim template on the deployed advance contract #61)
    4. set_claim_template AdMob … — needs the real proof (AdMob (#90): pin the AdMob claim template from a real proof #96)

    Read the fee at simulation on 2 and 3. Both call bump(), and #76 taught us that is rent rather than computation: it wanted 21,370 XLM once.

    Blocked on #103 merging. Nothing here pins a template on chain — that is #96's, from a real proof.

  11. added 3 commits that reference this issue on Oct 29, 2026
  12. 5 remaining items

  13. added a commit that references this issue on Oct 29, 2026
  14. added a commit that references this issue on Oct 30, 2026
  15. added 2 commits that reference this issue on Oct 30, 2026
  16. added 2 commits that reference this issue on Oct 30, 2026
  17. added 8 commits that reference 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

out-of-sowNot an Instawards deliverableready-to-devUnblocked: development can start on the issue's branch

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions