Skip to content

STE-46: GET /licenses lists every licence an address holds, from the contract - #55

Merged
Lin1er merged 2 commits into
mainfrom
feat/46-licenses-by-agent
Sep 17, 2026
Merged

Lin1er merged 2 commits into
mainfrom
feat/46-licenses-by-agent

Conversation

@Lin1er

@Lin1er Lin1er commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Linear: STE-46 · ACC by Axel 2026-09-17 · reviewers @axelmatsama @fable

What

GET /licenses?agent=G… returns every licence an address holds, newest first. It includes mint_tx links and total_supply. No verdict is joined in; that is a separate read, as in §3.8.

Decision: the source is the contract's own enumeration

The list comes from total_supply() + get_token(id), not from the event index.

  • getEvents only reaches back about a week, so a list built from events would silently drop older licences after a rebuild.
  • Tokens are soulbound and never burned, so each record is cached by id for good. total_supply is read live on every request.
  • license_minted events are tailed only to attach mint_tx. A licence older than the event window is still listed, with mint_tx: null.
  • A failed read is 502, never a shorter list.

Tests

  • API: 260 passed.
  • Rebased onto main with STE-34/48/53. The poll-loop conflict with STE-34 was merged by hand, and a test now pins the combined behaviour.

E2E (testnet)

  • /licenses equals a direct get_token enumeration for all 9 holders.
  • mint_tx matches 3 known mints.
  • A fresh production purchase appears in the list.
  • With the index deleted and the indexer off, every list is unchanged.

Evidence: docs/evidence/ste-46-e2e-licenses-by-agent-2026-09-17.json.

Deploy note

Drop the deploy_index volume on redeploy so mint_tx is backfilled within the event window. The list itself does not depend on it.

…m the contract

Frontend asked (Ancung) for "which licences does G... hold" without
iterating get_token 1..total_supply from the browser on every visit.

Decision: the list is the tokens contract's own enumeration, not the
event index the ticket suggested. getEvents only reaches back about a week
on testnet, so an event-built list silently drops older licences after a
rebuild; deleting a cache must never change an answer (api-spec 6). Tokens
are soulbound and never burned, so each get_token record is cached by id
for good and only newly minted ids are read. total_supply is read live on
every request, so the list is complete to the current ledger.

The indexer now also tails license_minted from the tokens contract into
its own table, only to attach mint_tx; a licence older than the event
window is listed with mint_tx null, never omitted. Events are accepted per
contract: license_minted only from the tokens contract, registry events
only from the registry, so nothing new can leak into /feed.

A failed total_supply or get_token read is 502, never a shorter list;
TokenNotFound below total_supply is a failed read, and the next request
fills the gap.

Tests: API 170 passed (25 new for /licenses, 3 for event decoding).
E2E on testnet against a local API with the indexer on:
- all 9 holders' lists equal a direct get_token enumeration (supply 28),
  every listed licence confirmed by has_license on chain;
- mint_tx from indexed events matches 3 known mints;
- 19 VERIFIED badges of the developer are not listed as licences;
- a fresh production purchase (GAFQ6QYS..., mint dcaac10e) is listed, and
  its mint_tx attaches once indexed;
- with the index file deleted and the indexer off, every list is unchanged
  (mint_tx null).
…and only registry events drop the /skills snapshot

Rebasing onto STE-34 put both tickets' changes into the same poll loop.
The first automatic resolution concatenated the two versions and stored
registry rows twice; the events table's UNIQUE constraint made that
harmless (INSERT OR IGNORE), so it was wasted work rather than wrong
data, and this test cannot tell the two apart. The loop was merged by
hand; the test pins the combined behaviour that does matter.
@vercel

vercel Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
sterish Ready Ready Preview Sep 17, 2026 11:58am UTC

@Lin1er
Lin1er merged commit b003860 into main Sep 17, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — a13e621c Deployed Sep 17, 2026 by vercel[bot]
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.

1 participant