Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions api/src/sterish_api/chain.py
Original file line number Diff line number Diff line change
Expand Up @@ -229,3 +229,25 @@ def is_verified_token(skill_id: str, version: str) -> bool:
[scval.to_string(skill_id), scval.to_string(version)],
)
)


def total_supply() -> int:
"""Tokens ever minted on the tokens contract. Ids run 1..total_supply and nothing
is ever burned, so this is exact (contracts/tokens/src/lib.rs::total_supply)."""
return int(_tokens_invoke("total_supply", []))


def get_token(token_id: int) -> dict:
"""`get_token(u32) -> TokenRecord`, decoded. `kind` is "VERIFIED" or "LICENSE"."""
raw = _tokens_invoke("get_token", [scval.to_uint32(token_id)])
kind = raw.get("kind")
if isinstance(kind, (list, tuple)) and kind:
kind = kind[0]
return {
"token_id": int(raw["token_id"]),
"kind": str(kind).upper(),
"skill_id": str(raw["skill_id"]),
"version": str(raw["version"]),
"owner": address_str(raw.get("owner")),
"minted_at": int(raw["minted_at"]),
}
55 changes: 52 additions & 3 deletions api/src/sterish_api/indexer.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
"""Lightweight event indexer.

Tails the registry's `skill_registered` / `version_registered` / `version_recorded` /
`verdict_flipped` events into SQLite. Two jobs:
`verdict_flipped` events into SQLite, and the tokens contract's `license_minted` into its
own table (STE-46, only to attach a mint transaction to a licence — see licenses.py for
why the licence list itself is not built from events). Two jobs:

1. supply the transaction hashes for the `evidence` object — the contract does not
store them, so without this the tx links are permanently null;
Expand Down Expand Up @@ -83,9 +85,13 @@ def init_db() -> None:

def rebuild() -> None:
"""Drop every indexed row and reset the cursor. The next poll refills from chain."""
from . import licenses

licenses.init_db()
with _lock, _connect() as conn:
conn.executescript(_SCHEMA)
conn.execute("DELETE FROM events")
conn.execute("DELETE FROM license_events")
conn.execute("DELETE FROM meta WHERE key = 'last_indexed_ledger'")
logger.info("indexer cache dropped; will rebuild from chain")

Expand Down Expand Up @@ -176,6 +182,30 @@ def feed(
# --- polling ----------------------------------------------------------------


def _decode_license_event(ev: Any, topics: list) -> dict | None:
"""`license_minted` (docs/specs/events.md §3b.2): topics (name, skill_id, version),
data {agent}. Accepted only from the configured tokens contract."""
if not settings.tokens_contract_id or getattr(ev, "contract_id", None) != (
settings.tokens_contract_id
):
return None
if len(topics) < 3:
return None
value = scval.to_native(stellar_xdr.SCVal.from_xdr(ev.value))
agent = address_str(value.get("agent")) if isinstance(value, dict) else None
if not agent:
return None
return {
"tokens_contract_id": settings.tokens_contract_id,
"agent": agent,
"skill_id": str(topics[1]),
"version": str(topics[2]),
"ledger": int(ev.ledger),
"tx_hash": ev.transaction_hash,
"occurred_at": _ledger_time(ev),
}


def _decode_event(ev: Any) -> dict | None:
# Events emitted inside a contract call that ultimately failed are not facts about
# the ledger state; indexing them would show phantom activity in the feed. Current
Expand All @@ -189,8 +219,16 @@ def _decode_event(ev: Any) -> dict | None:
if not topics:
return None
name = str(topics[0])
if name == "license_minted":
row = _decode_license_event(ev, topics)
return {"_license": row} if row else None
if name not in TRACKED_EVENTS:
return None
# Registry events only from the registry: the filter now also covers the tokens
# contract, and nothing else it emits may land in the feed table.
contract_id = getattr(ev, "contract_id", None)
if contract_id is not None and contract_id != settings.registry_contract_id:
return None

value = scval.to_native(stellar_xdr.SCVal.from_xdr(ev.value))
if not isinstance(value, dict):
Expand Down Expand Up @@ -250,7 +288,10 @@ def _get_events(server: SorobanServer, start: int):
filters=[
EventFilter(
event_type=EventFilterType.CONTRACT,
contract_ids=[settings.registry_contract_id],
contract_ids=[
c for c in (settings.registry_contract_id, settings.tokens_contract_id)
if c
],
)
],
limit=200,
Expand Down Expand Up @@ -319,13 +360,21 @@ def poll_once() -> int:
logger.warning("indexer: getEvents at %s failed: %s", start, exc)
break

rows = [r for r in (_decode_event(e) for e in res.events) if r]
decoded = [r for r in (_decode_event(e) for e in res.events) if r]
rows = [r for r in decoded if "_license" not in r]
new_rows = _store(rows)
if new_rows:
# A registration, a new version or a verdict landed: the filtered /skills
# view (STE-34) may now be wrong, so drop it rather than wait out its TTL.
registry_snapshot.invalidate()
stored += new_rows
if any("_license" in r for r in decoded):
from . import licenses

for r in decoded:
if "_license" in r:
licenses.record_license_event(r["_license"])
stored += 1
start = min(start + chunk, latest + 1)
_meta_set("last_indexed_ledger", str(min(start - 1, latest)))

Expand Down
163 changes: 163 additions & 0 deletions api/src/sterish_api/licenses.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
"""Every licence one address holds (STE-46), read from the tokens contract.

**Why not simply the event index.** The ticket suggested tailing `license_minted`. That
alone would be wrong in the same way STE-34 found for `/skills`: `getEvents` only reaches
back as far as the RPC node retains events (about a week on testnet), so an index rebuilt
today silently lacks every licence minted before that window, and an address that paid a
month ago would be told it holds nothing. Deleting the cache must never change an answer.

So the list comes from the contract's own enumeration: `total_supply()` then
`get_token(id)` for ids 1..total_supply. Tokens are soulbound and never burned, so a
record, once read, is true forever — it is cached by id and only the ids minted since the
last request are read. Every request still reads `total_supply` live, so the list is
complete up to the current ledger, never up to whenever the cache was last filled.

`license_minted` events are still tailed (indexer.py), but only to decorate a licence with
the transaction that minted it; a licence older than the event window is listed with
`mint_tx: null`, never left out.

A read that fails is raised, never served as a shorter list (api-spec §6).
"""

from __future__ import annotations

import logging
import sqlite3
import threading
from typing import Any

from . import chain, fanout
from .config import settings

logger = logging.getLogger(__name__)

_SCHEMA = """
CREATE TABLE IF NOT EXISTS tokens (
tokens_contract_id TEXT NOT NULL,
token_id INTEGER NOT NULL,
kind TEXT NOT NULL,
skill_id TEXT NOT NULL,
version TEXT NOT NULL,
owner TEXT NOT NULL,
minted_at INTEGER NOT NULL,
PRIMARY KEY (tokens_contract_id, token_id)
);
CREATE INDEX IF NOT EXISTS idx_tokens_owner ON tokens (tokens_contract_id, owner, kind);
CREATE TABLE IF NOT EXISTS license_events (
tokens_contract_id TEXT NOT NULL,
agent TEXT NOT NULL,
skill_id TEXT NOT NULL,
version TEXT NOT NULL,
ledger INTEGER NOT NULL,
tx_hash TEXT NOT NULL,
occurred_at INTEGER,
UNIQUE (tokens_contract_id, agent, skill_id, version, tx_hash)
);
CREATE INDEX IF NOT EXISTS idx_license_events ON license_events
(tokens_contract_id, agent, skill_id, version);
"""

_db_lock = threading.Lock()
# One sync at a time: two page loads racing would otherwise both read the same new ids.
_sync_lock = threading.Lock()


def _connect() -> sqlite3.Connection:
conn = sqlite3.connect(settings.db_path, check_same_thread=False)
conn.row_factory = sqlite3.Row
return conn


def init_db() -> None:
with _db_lock, _connect() as conn:
conn.executescript(_SCHEMA)


def _known_ids(contract: str) -> set[int]:
with _db_lock, _connect() as conn:
conn.executescript(_SCHEMA)
rows = conn.execute(
"SELECT token_id FROM tokens WHERE tokens_contract_id = ?", (contract,)
).fetchall()
return {int(r["token_id"]) for r in rows}


def _store_tokens(contract: str, records: list[dict]) -> None:
with _db_lock, _connect() as conn:
conn.executemany(
"INSERT OR IGNORE INTO tokens "
"(tokens_contract_id, token_id, kind, skill_id, version, owner, minted_at) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
[
(contract, r["token_id"], r["kind"], r["skill_id"], r["version"],
r["owner"], r["minted_at"])
for r in records
],
)


def sync() -> int:
"""Bring the token cache up to the live `total_supply`. Returns that supply.

Reads every id not yet cached, including gaps a crashed earlier sync left behind.
Raises `chain.ChainError` if any of them cannot be read.
"""
contract = settings.tokens_contract_id
if not contract:
raise chain.NotConfiguredError("TOKENS_CONTRACT_ID (or TOKENS_CA) is not set")

with _sync_lock:
supply = chain.total_supply()
missing = sorted(set(range(1, supply + 1)) - _known_ids(contract))
if not missing:
return supply

def read(token_id: int) -> dict:
try:
return chain.get_token(token_id)
except chain.ContractError as exc:
# An id at or below total_supply that the contract cannot return is not
# "no such licence"; it is a read we could not complete.
raise chain.ChainError(
f"get_token({token_id}) failed below total_supply {supply}: {exc}"
) from exc

records = fanout.map_bounded(read, missing, settings.chain_concurrency)
_store_tokens(contract, records)
logger.info("licences: cached %s new token records (supply %s)", len(records), supply)
return supply


def record_license_event(row: dict[str, Any]) -> None:
"""Store one decoded `license_minted` event (called by the indexer)."""
with _db_lock, _connect() as conn:
conn.executescript(_SCHEMA)
conn.execute(
"INSERT OR IGNORE INTO license_events "
"(tokens_contract_id, agent, skill_id, version, ledger, tx_hash, occurred_at) "
"VALUES (:tokens_contract_id, :agent, :skill_id, :version, :ledger, :tx_hash, "
" :occurred_at)",
row,
)


def for_agent(agent: str) -> list[dict[str, Any]]:
"""Licences held by `agent` on the configured tokens contract, newest first.

Call `sync()` first; this reads the cache it filled.
"""
contract = settings.tokens_contract_id
with _db_lock, _connect() as conn:
conn.executescript(_SCHEMA)
rows = conn.execute(
"SELECT t.token_id, t.skill_id, t.version, t.minted_at, "
" (SELECT e.tx_hash FROM license_events e "
" WHERE e.tokens_contract_id = t.tokens_contract_id AND e.agent = t.owner "
" AND e.skill_id = t.skill_id AND e.version = t.version "
" ORDER BY e.ledger DESC LIMIT 1) AS mint_tx "
"FROM tokens t "
"WHERE t.tokens_contract_id = ? AND t.owner = ? AND t.kind = 'LICENSE' "
"ORDER BY t.minted_at DESC, t.token_id DESC",
(contract, agent),
).fetchall()
return [dict(r) for r in rows]
3 changes: 2 additions & 1 deletion api/src/sterish_api/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
from fastapi.responses import JSONResponse
from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware

from . import chain, indexer, payments, proofs, x402
from . import chain, indexer, licenses, payments, proofs, x402
from .chain import ChainError, ContractError, NotConfiguredError
from .config import settings
from .errors import (
Expand Down Expand Up @@ -54,6 +54,7 @@ async def lifespan(app: FastAPI):
# and the evidence lookups then read an empty index instead of erroring on a
# missing table.
indexer.init_db()
licenses.init_db()
# The payments ledger is not a cache (STE-42): created here, never rebuilt.
payments.init_db()
proofs.init_db()
Expand Down
30 changes: 30 additions & 0 deletions api/src/sterish_api/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -180,3 +180,33 @@ class HealthResponse(BaseModel):
class ErrorResponse(BaseModel):
error: str
detail: str = ""


class LicenseItem(BaseModel):
token_id: int
skill_id: str
version: str
minted_at: int
minted_at_iso: str | None
# From the indexed `license_minted` event; null when the mint is older than the RPC's
# event window or not indexed yet. The licence is listed either way.
mint_tx: str | None
mint_tx_url: str | None


class LicensesByAgentResponse(BaseModel):
"""`GET /licenses?agent=G...` (STE-46).

Ownership only, like `/license`: no verdict is joined in. Whether a licensed version
is still SAFE is a different read against a different contract (`/check`).
"""

agent: str
licenses: list[LicenseItem]
total: int
start: int
limit: int
# `total_supply()` read live for this response: the list is complete up to it.
total_supply: int
tokens_contract_id: str
contract_url: str
Loading
Loading