Skip to content

feat(#96): pin_template.py derives an AdMob template, with its own order and boundaries - #101

Merged
Lexirieru merged 1 commit into
mainfrom
tools/admob-template
Oct 30, 2026
Merged

Lexirieru merged 1 commit into
mainfrom
tools/admob-template

Conversation

@Lin1er

@Lin1er Lin1er commented Oct 26, 2026

Copy link
Copy Markdown
Collaborator

The tool half of #96, built on #100 (the base is feat/admob-relay, so this diff contains only the tool). Draft, like #100, until @Lexirieru says go on #90.

@Lexirieru, this does what you proved was missing on #94 and #96.

  • --source adsense|admob. values_for() puts the publisher id last for AdMob: [sy, sm, sd, ey, em, ed, pub_id].
  • check() has structure rules per source, and they are tighter for AdMob. Each date number has to follow its own escaped JSON key, with startDate and endDate named, so a swapped start and end is caught. pub_id has to follow /accounts/. AdSense's rules (/, then =) are unchanged.
  • --self-test runs both sources. Each one derives 8 parts, round-trips, and recomputes the identifier. Each one also refuses a wrong window, and refuses the other source's value order. That is the AdMob (#90): contract, a revenue source in the template, the nullifier and sizing #94 mistake, caught here instead of as an unexplained ClaimMismatch.
  • tools/fixtures/admob-claim.json is the relay's own AdMob request, with a made-up account, window and figure. be/src/admob/fixture.test.ts fails if the relay's request and the fixture drift apart. Regenerating it is ADMOB_FIXTURE=write pnpm -C be test.
self-test (admob) against tools/fixtures/admob-claim.json
  values     ['2026', '7', '1', '2026', '9', '30', 'pub-1234567890123456']
  round trip ....... the parts and values reproduce the signed parameters exactly
  structure ........ every value sits immediately after its own admob separator
  signature ........ identifier recomputes to 0x4f3b53c4…8aba6, which the attestor signed
  arity ............ 8 parts for 7 values, which is what set_claim_template takes
  wrong window ..... refused, as it must be
  adsense order .... refused, as it must be

Checked: pin_template.py --self-test and make_claim_fixture.py --check pass, and BE has 118 of 118 tests passing, with typecheck and lint clean.

Still open on #96: running this on the first real AdMob proof (from prove:admob, #100), then pinning the result on chain after #94's upgrade.

@Lin1er
Lin1er requested a review from Lexirieru October 26, 2026 14:59
@vercel

vercel Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
forepay Ready Ready Preview Oct 30, 2026 1:42pm UTC
forepay-vue5 Ready Ready Preview Oct 30, 2026 1:42pm UTC

Lexirieru added a commit that referenced this pull request Oct 29, 2026
…wner

A revenue source selects the template, and the template pins the host. So the
caller's `source` argument cannot make a claim verify against the wrong API: an
AdMob claim checked as AdSense is rebuilt into a request to
adsense.googleapis.com, the identifier differs, and the signature recovers to
nobody. Tested in both directions.

The value order is NOT in the template. `rebuild_parameters` interleaves
positionally, so the order is part of the source's shape and lives in
`claim_values`. AdMob needs the reverse of AdSense's because the attestor sorts
the parameter keys, putting `body` (which holds the window) before `url` (which
holds the publisher id) — #93. Getting it wrong would surface as an unexplained
ClaimMismatch, so three places check the same ordering without deriving it from
each other: this contract, pin_template.py, and the relay.

Micros truncate to cents, never round up. The figure's key is per source
(`revenueUsd` / `revenueMicros`) and sits inside the signed context, because the
two mistakes are not symmetric: dollars read as micros fail loudly, while micros
read as dollars return the 100 USDC cap for any revenue at all, silently.
Measured on the deployed contract, not reasoned about: quote("123450000") is
1000000000 stroops.

The nullifier is tagged for AdMob only. One Google account's AdSense and AdMob
publisher ids are the same `pub-` id (#93, on a real account), so untagged an
AdMob proof would spend the AdSense nullifier for the same window. AdSense stays
untagged because advances already on chain are keyed on those bytes — pinned
against a literal derived independently in Python, so it is not the contract
agreeing with itself.

The source of an advance is `DataKey::AdvanceSource`, beside the `Advance` rather
than a field in it: a required field would retype an existing stored value and
every advance recorded before this upgrade would fail to decode. Those are debts.

Also carries the two changes asked for on #103: an unpinned claim owner is
refused with `ClaimOwnerNotSet` rather than falling back to the borrower, and
`set_claim_owner` has its own `ClaimOwnerMalformed` instead of reusing
`ClaimMismatch`.

Refusing forced the test harness to adopt the real owner shape, which is the
actual fix for the class of bug #102 was: a `G…` address cannot be pinned at all,
so the pre-#102 form cannot be written here by accident any more. Every test now
runs through an app-signed claim.

make_claim_fixture.py gains the AdMob chain. Its identifier is byte-identical to
the one be/src/admob/fixture.test.ts derives in TypeScript (#101) — a Python
encoder and a TypeScript one agreeing on the canonical parameters, the context,
and the keccak over them.

61 contract tests pass, plus 9 in reclaim-claim. fmt, clippy -D warnings, the
wasm build, the no_std wasm check, make_claim_fixture --check and
pin_template --self-test are all clean. The linux wasm row is PENDING for CI to
measure.

Refs #94, #102, #93. Base is #103.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdNuoJ9e954ojofNVGUezW
@Lin1er
Lin1er force-pushed the tools/admob-template branch from 662db68 to 780aa7c Compare October 29, 2026 23:34
Lexirieru added a commit that referenced this pull request Oct 30, 2026
…laim owner (#106)

* feat(#94): AdMob as a second revenue source, and refuse an unpinned owner

A revenue source selects the template, and the template pins the host. So the
caller's `source` argument cannot make a claim verify against the wrong API: an
AdMob claim checked as AdSense is rebuilt into a request to
adsense.googleapis.com, the identifier differs, and the signature recovers to
nobody. Tested in both directions.

The value order is NOT in the template. `rebuild_parameters` interleaves
positionally, so the order is part of the source's shape and lives in
`claim_values`. AdMob needs the reverse of AdSense's because the attestor sorts
the parameter keys, putting `body` (which holds the window) before `url` (which
holds the publisher id) — #93. Getting it wrong would surface as an unexplained
ClaimMismatch, so three places check the same ordering without deriving it from
each other: this contract, pin_template.py, and the relay.

Micros truncate to cents, never round up. The figure's key is per source
(`revenueUsd` / `revenueMicros`) and sits inside the signed context, because the
two mistakes are not symmetric: dollars read as micros fail loudly, while micros
read as dollars return the 100 USDC cap for any revenue at all, silently.
Measured on the deployed contract, not reasoned about: quote("123450000") is
1000000000 stroops.

The nullifier is tagged for AdMob only. One Google account's AdSense and AdMob
publisher ids are the same `pub-` id (#93, on a real account), so untagged an
AdMob proof would spend the AdSense nullifier for the same window. AdSense stays
untagged because advances already on chain are keyed on those bytes — pinned
against a literal derived independently in Python, so it is not the contract
agreeing with itself.

The source of an advance is `DataKey::AdvanceSource`, beside the `Advance` rather
than a field in it: a required field would retype an existing stored value and
every advance recorded before this upgrade would fail to decode. Those are debts.

Also carries the two changes asked for on #103: an unpinned claim owner is
refused with `ClaimOwnerNotSet` rather than falling back to the borrower, and
`set_claim_owner` has its own `ClaimOwnerMalformed` instead of reusing
`ClaimMismatch`.

Refusing forced the test harness to adopt the real owner shape, which is the
actual fix for the class of bug #102 was: a `G…` address cannot be pinned at all,
so the pre-#102 form cannot be written here by accident any more. Every test now
runs through an app-signed claim.

make_claim_fixture.py gains the AdMob chain. Its identifier is byte-identical to
the one be/src/admob/fixture.test.ts derives in TypeScript (#101) — a Python
encoder and a TypeScript one agreeing on the canonical parameters, the context,
and the keccak over them.

61 contract tests pass, plus 9 in reclaim-claim. fmt, clippy -D warnings, the
wasm build, the no_std wasm check, make_claim_fixture --check and
pin_template --self-test are all clean. The linux wasm row is PENDING for CI to
measure.

Refs #94, #102, #93. Base is #103.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdNuoJ9e954ojofNVGUezW

* feat(#94): record the linux wasm hash CI measured

Filled in from the measurement the runner printed for the PENDING row, rather
than from a local build: wasm is byte-identical only within a host triple and
toolchain, so the macOS hash is not the one CI checks.

  x86_64-unknown-linux-gnu  28.1.0  4c5b24de377fab73a55db715739f8b4d9f7e48e75484cad0c8f9df8f52b7a049

Every other step of that run passed, including "Test snapshots are committed",
so the snapshots in the previous commit are complete and stable. Coverage was
skipped because the job stopped at the PENDING row; this push is the first run
that exercises it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdNuoJ9e954ojofNVGUezW

* docs(#94): say why unwrap_or on AdvanceSource is safe

Verified against the official state-archival docs via MCP Stellar Raven: a
persistent entry whose TTL lapses is archived, not deleted, and the host makes
the caller restore it before the read. So an AdMob advance cannot quietly read
back as AdSense once its TTL runs out.

The line itself would be a silent debt-relabelling bug in temporary storage, and
nothing in the code said why it is not one here. Same property the nullifier
already rests on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdNuoJ9e954ojofNVGUezW

* fix(#94): re-record the wasm hash, and why a doc comment moved it

The previous row was measured before faf9540, which added a doc comment and
nothing else. That changed the wasm.

Proven rather than assumed, by building twice with nothing else different:

  with the doc comment on advance_source   0c5c70c9...acdd  (aarch64-apple-darwin)
  with that one comment removed            57f3ebce...04b3

and `strings` finds the comment's text inside the wasm. soroban-sdk embeds the
doc comments of #[contractimpl] functions in the contract-spec metadata section,
so they are part of the deployed bytes.

Two consequences, now in the wasm-hashes.txt header so the next person does not
spend an afternoon on it:

- A "docs only" commit is not docs-only for the artifact. It needs this row
  re-recorded, and on a released contract a new release and a new verification.
- These comments are published on chain and readable by anyone. Good to have on
  purpose, surprising to discover by accident.

Linux row from CI's own measurement on the rebased branch:
  x86_64-unknown-linux-gnu  28.1.0  f4fd10d646307bd4f204a26be3b64c35141587b9e12aca0f41b48c049d3a5a36

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdNuoJ9e954ojofNVGUezW

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
@Lin1er
Lin1er marked this pull request as ready for review October 30, 2026 13:36
@Lin1er
Lin1er force-pushed the tools/admob-template branch from 780aa7c to dc64663 Compare October 30, 2026 13:37
…der and boundaries

The tool was AdSense-shaped in two places (Axel's proof on #94 and #96):
values_for() always put pub_id first, and check() required every
separator to end with '=' and part 0 with '/'.

- --source adsense|admob. For AdMob the values are [sy, sm, sd, ey, em,
  ed, pub_id], because body sorts before url in the signed parameters.
- The structure check is per source, and tighter for AdMob: each date
  number must follow its own escaped JSON key, with startDate and
  endDate named, and pub_id must follow /accounts/.
- --self-test now runs both sources. Each refuses a wrong window and the
  other source's value order, which is the #94 mistake caught before it
  reaches the chain.
- tools/fixtures/admob-claim.json is the relay's own AdMob request, and
  be/src/admob/fixture.test.ts fails if the two drift apart.
@Lexirieru
Lexirieru force-pushed the tools/admob-template branch from dc64663 to f4d2a1d Compare October 30, 2026 13:41
@Lexirieru
Lexirieru changed the base branch from feat/admob-relay to main October 30, 2026 13:41

@Lexirieru Lexirieru left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. This is the tool I will actually run on the day, so I ran it rather than read it.

Rebased onto main and force-pushed (dc64663 → f4d2a1d), then retargeted from feat/admob-relay to main. #100 was squash-merged, so retargeting alone would have shown its 18 files again as if they were yours; git rebase --onto origin/main 8097128 is the fix. The diff is now your four files and nothing else — +152 / -47.

Run here

self-test (adsense) against tools/fixtures/forepay-claim.json
  signature ........ identifier recomputes to 0x18303a91…80dee, which the attestor signed
  wrong window ..... refused, as it must be
  admob order ...... refused, as it must be

self-test (admob) against tools/fixtures/admob-claim.json
  values     ['2026', '7', '1', '2026', '9', '30', 'pub-1234567890123456']
  signature ........ identifier recomputes to 0x4f3b53c4…8aba6, which the attestor signed
  wrong window ..... refused, as it must be
  adsense order .... refused, as it must be

0x4f3b53c4…8aba6 is byte-identical to what my own make_claim_fixture.py derives for the AdMob section, written independently from docs/interface.md. Two separate derivations of a keccak digest over hand-assembled bytes landing on the same 32 bytes is the only kind of agreement worth anything here.

Also run on the rebase: tsx --test 125 of 125, and make_claim_fixture.py --check reports the AdSense fixture up to date.

The part I would have got wrong by hand

Making the "wrong window" and "other order" cases call check() and not just split_parts() is what gives them teeth. split_parts alone can refuse for the shallow reason — the value simply is not present — while a value order that happens to find every substring somewhere would sail through it and die on chain as ClaimMismatch, with nothing to point at. Putting the structure rules and the signature recomputation in the failure path means the test fails for the real reason.

The per-source after table is the right shape too. On #94 I proved this against your tool before writing contract code: in AdSense order split_parts refuses outright, and reordered it finds 8 parts whose every structure assertion fails. That second case is the dangerous one — a template that round-trips and is wrong — and '\\"startDate\\":{\\"year\\":' naming the window boundary explicitly is what catches a swapped start and end, which no round-trip ever would.

Where this leaves #96

The tool is ready and CI will keep it ready. What is left is the day itself, in this order:

  1. v0.5.0 released, uploaded, propose_upgrade, the 24-hour timelock, execute_upgrade. — in progress now
  2. set_claim_owner, then set_claim_template --source adsense (#61) from the real AdSense proof.
  3. prove:admob against the agreeing account, then this tool with --source admob, then set_claim_template --source admob.

I will post each stellar contract invoke line and its tx hash on #96 and #102 as it happens.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants