Skip to content

Proposal: AdMob as a second revenue source, beside AdSense (needs a decision) #90

Open

Description

@Lin1er

Owner: @Lin1er (proposal) · Decision: @Lexirieru · Branch: none until approved · Label: out-of-sow

@Lexirieru, this is a proposal and nothing has been built. It needs your decision and your opinion before anyone writes code. The questions are at the end.

TL;DR

Let a creator prove revenue from AdMob (ads inside mobile apps) as well as AdSense (websites), and size the advance from either one.

  • Same idea, a different API. AdMob has an official read-only reporting API, with the same kind of OAuth token we already use for AdSense.
  • It is a real build. The contract pins exactly one claim template today, so the contract, the relay, the Reclaim template, the front end and the consent screen all change.
  • SOW §4.1 excludes it. "Revenue sources beyond AdSense" is listed as out of scope (Forepay Instawards — build plan, verified facts, and what is out of scope #30).
  • My recommendation: approve it as post-SOW work (after 2026-11-08). Nothing in M3/M4 changes. The only near-term exception is path B below.

Why

  • More creators. Many creators earn from apps rather than websites. Today they cannot use Forepay at all.
  • A better story. The pitch becomes "an advance on your Google ad revenue", not "an advance on AdSense". The mechanism stays the same: a zkTLS proof of a Google reporting API response, bound to a Stellar address.
  • A possible way out of Find an approved (READY) AdSense account for the gate and the demo #77. If someone we know has an AdMob account with revenue, that is a real proof for the demo. Our only AdSense account (pub-1144314860018910) is READY but has had $0 and no report rows since 2023-12.

What AdMob gives us

Sources: the AdMob API reference, checked 2026-10-25.

AdSense (today) AdMob (proposed)
Endpoint GET https://adsense.googleapis.com/v2/accounts/pub-…/reports:generate?… POST https://admob.googleapis.com/v1/accounts/pub-…/networkReport:generate
Request Query string, with dates as startDate.year=…&startDate.month=…&startDate.day=… (#76) JSON body reportSpec: dateRange {startDate {year,month,day}, endDate {…}}, metrics, localizationSettings.currencyCode
Scope adsense.readonly admob.readonly (or admob.report)
Response One JSON object; totals is present only when there is data A stream: one header, then rows, then a footer (as a JSON array over REST)
Revenue figure ESTIMATED_EARNINGS as a decimal string, e.g. "123.45" ESTIMATED_EARNINGS as microsValue, e.g. "123450000" = $123.45
Currency Set in the request, checked in the response localizationSettings.currencyCode: "USD" in the request
Publisher id pub- + 16 digits pub- + 16 digits, and it can be the same id as the creator's AdSense one (to confirm on a real account)

The dates still line up with #76. AdMob also takes the window as three integers per date, so the contract's seven values (pub_id plus six date numbers) still fit, just placed into a JSON body instead of a query string.

What has to change, layer by layer

1. Contract (sc/advance), owner @Lexirieru

Today DataKey::ParamsTemplate and DataKey::ProviderHash are singletons, and verify_claim always rebuilds an AdSense request (sc/advance/src/lib.rs:479, :523).

  1. A revenue source. Add enum Source { AdSense, AdMob }, and new keys ParamsTemplateFor(Source) and ProviderHashFor(Source).
    • DataKey is append-only, so the existing two keys stay, read as AdSense, and nothing already pinned moves.
    • set_claim_template takes a source.
  2. verify_claim / verify_and_reserve / request_advance take source. They rebuild from that source's template.
    • The template, not the caller, fixes the host. A claim made against admob.googleapis.com can never be checked against the AdSense template, and the reverse.
  3. Micros. sizing.rs parses a decimal revenueUsd into cents today. AdMob gives an integer in micros.
    • Option (a): a second parser in the contract, micros / 10_000 → cents, truncating and never rounding up.
    • Option (b): keep one parser and have the regex capture something already decimal. That is not possible: RE2 cannot divide, and the figure must come from the signed bytes.
    • So (a).
  4. The nullifier must include the source. Today it is nullifier_of(pub_id, start, end).
    • If a creator's AdSense and AdMob share one pub- id, an AdMob proof for a window would spend the AdSense nullifier for the same window, or block it.
    • Proposal: hash the source in only for AdMob. AdSense nullifiers keep their current bytes, so the advances already recorded keep their keys.
  5. Advance records the source. Advance is a contracttype struct, so this is a new field and a storage-shape question for you. Alternatively, keep Advance as is and emit the source in the event only.
  6. Upgrade. This goes through propose_upgrade and the timelock, like Contract: rebuild the AdSense claim in the encoding the AdSense API actually produces #76. It should land after the Security: request_advance and verify_and_reserve take no borrower authorisation #81 fix is deployed, not instead of it.

2. Relay (be/), owner @Lin1er

  • be/src/admob/, beside be/src/adsense/, with the same shape:
    • request.ts: the POST with a fixed reportSpec body (metrics: ["ESTIMATED_EARNINGS"], no dimensions, currencyCode: "USD"), and the token in secretOptions.headers only;
    • RE2 responseMatches for the currency and the micros total;
    • audit.ts, the same checks as for AdSense;
    • account.ts: accounts.list to find the one AdMob account, like the AdSense account check.
  • POST /proofs takes source: "adsense" | "admob", defaulting to adsense, so today's clients keep working. docs/api.md documents it.
  • A spike first, before any contract work. Two things must be proven against a real account:
    1. zkFetch signs a POST with a JSON body, and the attestor's parameters include the body bytes. If the body is not in the signed bytes, the window is not bound, and the design falls over.
    2. What the response looks like at $0. AdSense omits totals, which is why Find an approved (READY) AdSense account for the gate and the demo #77 is stuck. AdMob's docs do not say whether a zero account returns a row.

3. Reclaim template, as in #61, owner @Lexirieru with @Lin1er

4. Front end (fe/), owner @Nabil-Aufa (design @AncungAulia)

  • 2a gets a choice between "AdSense (websites)" and "AdMob (apps)".
  • The Google sign-in asks only for the scope of the chosen source, never both at once.
  • Copy, the failure panels (noAdmob, like noAdsense) and the offer screen name the source. The board gets the new state.

5. Consent screen and legal pages (#85, #86), owners @AncungAulia and @Lin1er

6. Docs

docs/interface.md (the claim chain per source), docs/api.md, docs/deployments.md (the new template pin and the upgrade tx), the README.

Security notes

  • Cross-source replay is the main new risk. It is covered by a template per source (the host is pinned) and a nullifier per source (item 1.4).
  • Rounding. Truncate micros to cents, never round up, so the advance is never sized from more than was attested.
  • The context message stays "Forepay advance request" for both sources. The source is already fixed by the host in the signed URL. A second context message would not add anything.
  • Scope minimisation. One scope per proof, read-only, and the token is used for one proof only (as for AdSense today).

The three paths

Path What When Cost Risk to the deadline
A (recommended) Full dual support, everything above After 2026-11-08, as post-SOW About 1.5–2× #4 + #76 + #61, plus a timelock cycle None: M3/M4 untouched
B AdMob replaces AdSense for the demo, only if an AdMob account with revenue exists and no AdSense one does Now The spike, the AdMob template, a contract upgrade with the micros parser, and FE copy High. It changes what the SOW calls the product, and the timelock lands close to M4.
C Do nothing; keep it as "future work" in the pitch and in #30 n/a None None

Whatever you choose, #77 option 3 (the demo on the probe witness, deadline 2026-10-27) is still the plan for the current demo unless you say otherwise.

Proposed split, if A is approved

Each becomes its own issue, with one owner and one branch:

  1. Spike: zkFetch POST and a $0 AdMob response. @Lin1er, spike/admob-zkfetch. This goes first, and it decides go or no-go.
  2. Contract: a revenue source in the template, the nullifier and sizing. @Lexirieru, feat/admob-contract.
  3. Relay: the AdMob provider and source on POST /proofs. @Lin1er, feat/admob-relay.
  4. Template: pin the AdMob template from a real proof. @Lexirieru with @Lin1er, tools/admob-template.
  5. Front end: choosing the source on 2a. @Nabil-Aufa, feat/admob-fe. Design by @AncungAulia.
  6. Consent screen and privacy policy: the second scope. @AncungAulia and @Lin1er, docs/admob-consent.

Questions for @Lexirieru

  1. A, B or C? If A, is "after 2026-11-08" right, or would you rather start the spike (item 1) earlier, since it changes no shipped code?
  2. Does anyone on the team or in the chapter have an AdMob account with revenue? That is what decides whether B is even possible.
  3. Contract design: is Source as a parameter, with a source-tagged nullifier for AdMob only, acceptable? Do you want the source as a field on Advance, or in the event only?
  4. The SOW: does a post-SOW feature belong in this repo with the out-of-sow label, or somewhere else?

Until you answer, nothing here gets built.


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. self-assigned this
    on Oct 25, 2026
  2. added
    questionFurther information is requested
    out-of-sowNot an Instawards deliverable
    on Oct 25, 2026
  3. Lexirieru commented on Oct 25, 2026

    @Lexirieru
    Collaborator

    Decision: A, but start the spike now. Answers to your four questions below, and one correction to the contract design that I think would have cost us on-chain data.

    Thank you for writing this as a proposal with nothing built. That is the right way to put a scope question in front of a deadline.

    1. A, B or C — and when

    A. Full dual support, post-SOW, after 2026-11-08.

    B is a no, and not for technical reasons. SOW §4.1 names AdSense. Swapping the revenue source three weeks before the deadline changes what the SOW calls the product, and "we changed the product late because our own account had no revenue" is the hardest possible thing to explain to a Chapter Lead. The demo problem is solved by #77 option 3, honestly labelled — not by changing what we built.

    But start item 1, the spike, now. It touches no shipped code, and its outcome can invalidate the entire design:

    zkFetch signs a POST with a JSON body, and the attestor's parameters include the body bytes. If the body is not in the signed bytes, the window is not bound, and the design falls over.

    That is exactly right, and it is worth knowing in October rather than November. If the body is not covered, AdMob is not viable through zkFetch at all and path A dies — better to find that out before anyone designs around it. The second half (what a $0 account returns) is cheap to answer at the same time.

    So: spike now, build after 2026-11-08.

    2. An AdMob account with revenue

    Not that I know of, and it is the same ask as #77 — which just got worse, not better: the AdSense account is approved and in good standing and has never recorded a cent. An approved account that never served an ad has nothing to prove.

    Worth asking for both in one breath when anyone asks around: "an AdSense or AdMob account that actually earned something between July and September 2026, even four dollars."

    3. Contract design — yes to Source, yes to the tagged nullifier, no to the field on Advance

    Source as a parameter, with ParamsTemplateFor(Source) / ProviderHashFor(Source): agreed. DataKey is append-only and this respects that. The template fixing the host — so an AdMob claim can never be checked against the AdSense template — is the right security property and the right place for it.

    The source in the nullifier, for AdMob only: agreed, and your reason is the real one. The asymmetry is forced by advances already recorded on chain, not chosen. But asymmetries like this are where the next person slips, so put the exception in exactly one place with its reason attached — something like:

    /// AdSense nullifiers carry no source tag. Not a style choice: advances already on
    /// chain are keyed on the untagged bytes, and tagging AdSense now would orphan them.
    /// Every source added after AdSense is tagged.
    fn source_tag(s: &Source) -> Option<&'static [u8]> { … }

    so nobody has to rediscover why one branch is bare.

    The source as a field on Advance — don't. This is the part I want to push back on.

    Advance is a #[contracttype] struct, encoded as a map with symbol keys. Adding a required field changes the type of the value stored under an existing key, and existing Advance entries were written without it — so after the upgrade, reading any advance recorded today would fail to decode. That is not a migration we want on records that represent debts, and it is the one thing lib.rs opens by warning about ("never remove, rename or retype a key").

    Event-only is safe but weak: the front end would have to reconstruct the source from history, and #66 deliberately reads figures from the contract's own record rather than summing Horizon — for good reasons we would be undoing.

    What I would do instead: a parallel key.

    DataKey::AdvanceSource(BytesN<32>) -> Source   // absent means AdSense

    Written beside the Advance at disbursement. Append-only, so nothing already stored moves; old advances decode exactly as they do today; the front end gets the source from a contract read rather than from an event; and "absent means AdSense" is the same forced asymmetry as the nullifier, which means there is one rule to remember instead of two.

    Before building any of it, prove the premise with a test: write an Advance in the old shape, upgrade the wasm, read it back. If a struct with an added field decodes old entries fine, I am wrong and the field is simpler. I would rather be shown that by a test than assume either way — the storage rule in lib.rs has been a comment for two weeks and only became evidence when #76's upgrade let us read the old entries back.

    4. Where post-SOW work lives

    This repo, with the out-of-sow label. A second repository for a 30-day grant costs more than a label does, and the evidence pack (#27) is built around one repository a reviewer can open. The label is what keeps the SOW boundary legible.

    Split, approved

    Your six issues as written, with two changes:

    1. Spike — @Lin1er, spike/admob-zkfetch. Start now. Go/no-go for everything below.
    2. Contract — @Lexirieru, feat/admob-contract. After 2026-11-08, after the spike passes, and after Security: request_advance and verify_and_reserve take no borrower authorisation #81 is deployed. AdvanceSource as a parallel key, not a field.
    3. Relay — @Lin1er, feat/admob-relay.
    4. Template — @Lexirieru with @Lin1er, tools/admob-template. tools/pin_template.py (tools(#61): derive the claim template from a real proof, and prove it three ways #83) already does the derivation and proves it three ways; it should take the AdMob shape with little more than a different value layout.
    5. Front end — @Nabil-Aufa, design @AncungAulia.
    6. Consent screen and privacy — @AncungAulia and @Lin1er. Note that admob.readonly may restart Google's sensitive-scope verification (Publish the Google OAuth consent screen: domain verification, policy links, review #86), so this one has a lead time nobody controls — worth knowing before it is the last item.

    Open them when the spike comes back green. Nothing else changes before 2026-11-08.

    One thing to carry into the spike

    Your table says AdMob returns ESTIMATED_EARNINGS as microsValue. If the spike confirms the body is signed, please capture a real response at a non-zero amount and at zero, both, and attach them. The zero case is what #77 turned out to hinge on for AdSense, and we only learned it by reading the whole history. Knowing AdMob's zero shape before the contract work starts is worth the extra minute.

  4. Lin1er commented on Oct 25, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru the spike's go/no-go question has its answer: go for part 1. A zkFetch POST signs its JSON body. The production attestor signed the body byte for byte, a swapped window no longer recovers to the attestor, and Reclaim's verifier accepts the genuine digest and refuses a one-byte flip. Details and the signed parameters are in #93.

    Part 2 (AdMob's response at zero and above zero) waits on an AdMob account. Nothing else from #90 opens until it is answered, as agreed.

  5. Lin1er commented on Oct 25, 2026

    @Lin1er
    CollaboratorAuthor

    Follow-up issues opened, as approved. Each has one owner and one branch, carries out-of-sow, is blocked by #93 and starts after 2026-11-08:

    # What Owner
    #93 Spike: POST body signing (passed), AdMob's response at zero and above (open) @Lin1er
    #94 Contract: Source, templates per source, micros, tagged nullifier, AdvanceSource parallel key @Lexirieru
    #95 Relay: be/src/admob/, source on POST /proofs @Lin1er
    #96 Template: pin AdMob's from a real proof (pin_template.py) @Lexirieru with @Lin1er
    #97 Front end: choose the source on 2a @Nabil-Aufa, design @AncungAulia
    #98 Consent screen and privacy: admob.readonly @AncungAulia, @Lin1er

    One ordering note, written into #98: admob.readonly goes on our OAuth client only after #86 is published, so it cannot reset that review. The spike does not need it, because #93 part 2 takes its token from the OAuth Playground's own client.

  6. Lin1er commented on Oct 25, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru #93 part 2's zero case is in. AdMob at $0 sends a header and an empty footer, with no row, the same problem as AdSense's missing totals, and the same handling. The publisher id is shared with AdSense (pub-1144314860018910 is both), so #94's tagged nullifier is now required rather than precautionary. Verdict: go. Only the non-zero row's exact shape is still unseen, which affects #95's regex, not the design.

  7. Nabil-Aufa commented on Oct 26, 2026

    @Nabil-Aufa
    Collaborator

    @Lexirieru a question on the timing in your decision. You wrote "spike now, build after 2026-11-08". Did you mean that AdMob should be built before the deadline, so the demo can use a real proof?

    A correction on the date as well: the deadline is 2026-10-30, not 2026-11-08. #30 still shows the old window (M4 ending Nov 8).

    Why this matters for the demo:

    • We still have no AdSense account with revenue (Find an approved (READY) AdSense account for the gate and the demo #77). The accounts on offer, including the ones for sale, are READY but have never earned anything.
    • The account outside the team that @Lin1er is checking may have AdMob revenue.
    • AdSense stays the product. AdMob is added next to it, not swapped in, so this is your path A, moved earlier, and not path B.

    If it is meant to land before 2026-10-30, the contract upgrade's timelock (#94) and the real-proof template (#96) set the pace. Should those start now, or does the demo stay on #77 option 3?

    🤖 Generated with Claude Code

  8. Lin1er commented on Oct 26, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru #93 is done: both parts, with the non-zero case read on 2026-10-26. That changes the question @Nabil-Aufa asked above. There is now an account with AdMob revenue in the window (Jul–Sep 2026, a few tens of USD, figures redacted on #93). Its AdSense is READY but has nothing in the window, so it cannot unlock #77 on the AdSense path. It can unlock it on the AdMob path, if that lands by 2026-10-30.

    So I am proposing path A, moved earlier, as Nabil described: AdSense stays the product, and AdMob is added next to it.

    The critical path to 2026-10-30

    Day What Issue Who
    10-26 The relay's AdMob provider, plus a prove:admob CLI that takes a Playground token, so the first real proof does not wait on the OAuth client or the front end #95 @Lin1er
    10-26 Source, the value order per source (your note on #94), the micros parser, the tagged nullifier, AdvanceSource #94 @Lexirieru
    10-26 pin_template.py: values_for() and check() per source, with an AdMob self-test fixture #96 @Lin1er, reviewed by @Lexirieru
    10-27 One real AdMob proof from that account → the template and provider_hash, derived and checked three ways #96 @Lin1er + @Lexirieru
    10-27 Release, then propose_upgrade on production. #81's upgrade has to be executed first; its timelock ran out on 10-26 #94 @Lexirieru
    10-28 execute_upgrade (24 h timelock), then set_claim_template for AdMob #94 @Lexirieru
    10-29 request_advance on production with the real proof, and the evidence in docs/deployments.md #77 @Lin1er
    10-26 → 29 Choosing the source on 2a, and the copy #97 @Nabil-Aufa, design @AncungAulia
    10-26 → 29 Privacy policy and terms name the second scope #98 @AncungAulia

    The fallback stays in place. If any step slips, the demo uses option 3, which is already merged (#91). Nothing on this path touches the shipped AdSense flow before your review.

    One thing outside our control: a proof on chain makes that account's pub- id, the window, the revenue figure and a Stellar address public, permanently. The owner has to agree to that explicitly (the exposure note on #77) before 10-27. I am asking them now.

    The OAuth client (#98) keeps only adsense.readonly until #86 is through, so as not to restart Google's review. The demo's proof does not need it: the CLI takes a Playground token, the same way #93 did. Adding admob.readonly to our client is the one piece that stays after 11-08.

    What I have done

    Your call: go for A, moved earlier, on this timeline? Or keep 11-08, and the branches wait as drafts?

  9. Lin1er commented on Oct 26, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru two things since my plan above, both with evidence:

    1. The first real AdMob proof exists. It was signed by the production attestor, the audit passed, and feat(#96): pin_template.py derives an AdMob template, with its own order and boundaries #101's tool derived the AdMob template from it, with all three checks passing. The signed bytes are identical to what the relay builds (AdMob (#90): pin the AdMob claim template from a real proof #96). The account's owner agreed to everything going public (Find an approved (READY) AdSense account for the gate and the demo #77).
    2. The contract rebuilds the attestor's owner as the borrower, so no real proof can verify #102, a blocker for any real proof, AdSense included. The contract rebuilds owner as the borrower, while the real attestor signs our Reclaim app id. The rehearsal never saw it, because it signs synthetic claims with owner = borrower. The proposed fix is a pinned ClaimOwner beside the template, with no interface change.

    Both now hang on one contract upgrade: #94 + #102. With the 24 h timelock, it has to be proposed by 2026-10-28 to execute before the 30th. Your call on #90, and the contract work, are the critical path. I can draft the #102 fix as a contract PR for your review if that saves you time. Tell me.

  10. Lin1er commented on Oct 27, 2026

    @Lin1er
    CollaboratorAuthor

    @Lexirieru, the AdMob work waits on your go or no here. The full list of what is waiting on you is on #103: #103. The most urgent part is #103 itself: it has to be proposed by 2026-10-28 for a real advance before 2026-10-30.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestout-of-sowNot an Instawards deliverablequestionFurther information is requested

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions