@misofm/platform 0.26.2 → 0.28.0

package/src/read/receipts.ts

@@ -21,13 +21,19 @@
 // math the chain does.
 
 import * as listingContract from "../contracts/record_shop/listing.ts";
-import {
-  extractTypeParams2,
-  getCompositionsByIds,
-} from "@misofm/musicos";
+import { extractTypeParams2, Musicos, type MusicosDeploymentInvalid, type MusicosService, type MusicosWorkNotFound } from "@misofm/musicos";
 import { normalizeStructTag, normalizeSuiAddress } from "@mysten/sui/utils";
-import { Effect } from "effect";
-import { SuiClient, SuiGraphQL, SuiRpcError, type BcsDecodeError, type ObjectTypeMismatchError } from "@misofm/effect";
+import { Effect, Result } from "effect";
+import {
+  GraphQLUnavailable,
+  ObjectId,
+  Sui,
+  SuiGraphQL,
+  TransportError,
+  type BatchItemError,
+  type DecodeError,
+  type TransactionNotFound,
+} from "@unconfirmed/sui-effect";
 import { getPressingDetail } from "./catalog.ts";
 import { int } from "./internal/scalars.ts";
 import { requireRecordSalesDeployment } from "../deployments.ts";
@@ -52,6 +58,29 @@ const FULLNODE_WAIT_MS = 5_000;
 /** Composition royalty rate (bps) per recording id. Sparse — an unresolved parent has no entry. */
 type CompositionRates = Record<string, number | undefined>;
 
+/**
+ * `GraphQLUnavailable` lets through, not folded into `TransportError` — see
+ * `@misofm/musicos`'s own `queries.ts` (and `read/royalties.ts`) for the
+ * same idiom.
+ */
+const graphqlError = (method: string) => (cause: unknown): GraphQLUnavailable | TransportError =>
+  cause instanceof GraphQLUnavailable ? cause : TransportError.fromUnknown(method, cause);
+
+/**
+ * Builds `Musicos.layer({ deployment: { packageId } })`, provides it, and
+ * hands back the effect it wraps — see `../catalog.ts`'s `withMusicos` for
+ * the same idiom (kept file-local; see `docs/CONVERSION-STATUS.md`).
+ */
+function withMusicos<A, E>(
+  packageId: string,
+  effect: (musicos: MusicosService) => Effect.Effect<A, E, Sui>,
+): Effect.Effect<A, E | MusicosDeploymentInvalid, Sui> {
+  return Effect.gen(function* () {
+    const musicos = yield* Musicos;
+    return yield* effect(musicos);
+  }).pipe(Effect.provide(Musicos.layer({ deployment: { packageId } })));
+}
+
 function coerceU64(v: unknown): bigint | null {
   const value = typeof v === "bigint"
     ? v
@@ -63,20 +92,46 @@ function coerceU64(v: unknown): bigint | null {
   return value !== null && value >= 0n && value <= U64_MAX ? value : null;
 }
 
-function priceFromUnknown(value: unknown): Price | null {
-  if (!value || typeof value !== "object") return null;
-  const variants = value as {
-    $kind?: string;
-    Fixed?: unknown;
-    Floor?: unknown;
-  };
-  const fixed = variants.$kind === "Fixed" || Object.hasOwn(variants, "Fixed");
-  const floor = variants.$kind === "Floor" || Object.hasOwn(variants, "Floor");
-  if (fixed === floor) return null;
-  const amount = coerceU64(fixed ? variants.Fixed : variants.Floor);
+function priceFromRichFields(
+  pricingIsFixed: unknown,
+  priceValue: unknown,
+): Price | null {
+  if (typeof pricingIsFixed !== "boolean") return null;
+  const amount = coerceU64(priceValue);
   return amount == null || amount <= 0n
     ? null
-    : { kind: fixed ? "fixed" : "floor", amount: amount.toString() };
+    : { kind: pricingIsFixed ? "fixed" : "floor", amount: amount.toString() };
+}
+
+/** Decode a Move `vector<u8>` containing a UTF-8 defining type name. */
+function utf8ByteVector(value: unknown): string | null {
+  let bytes: number[];
+  if (typeof value === "string") {
+    // GraphQL's MoveValue JSON projects vector<u8> as standard padded Base64.
+    // Require the canonical spelling and round-trip it before accepting it;
+    // arbitrary strings are never interpreted as a type name.
+    if (value.length === 0 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return null;
+    try {
+      const binary = atob(value);
+      const canonical = btoa(binary);
+      if (canonical !== value) return null;
+      bytes = Array.from(binary, (char) => char.charCodeAt(0));
+    } catch {
+      return null;
+    }
+  } else if (Array.isArray(value) || value instanceof Uint8Array) {
+    bytes = Array.from(value);
+  } else {
+    return null;
+  }
+  if (!bytes.every((byte) => typeof byte === "number" && Number.isInteger(byte) && byte >= 0 && byte <= 255)) {
+    return null;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes));
+  } catch {
+    return null;
+  }
 }
 
 function typeName(value: unknown): string | null {
@@ -121,8 +176,9 @@ function saleFromJson(
   const purchasePrice = coerceU64(json.purchase_price);
   const purchasedTimestampMs = coerceU64(json.purchased_timestamp_ms);
   const recordId = json.record_id;
-  const pricing = priceFromUnknown(json.pricing);
-  const embeddedCurrency = typeName(json.purchase_currency);
+  const pricing = priceFromRichFields(json.pricing_is_fixed, json.price);
+  const currencyText = utf8ByteVector(json.purchase_currency);
+  const embeddedCurrency = currencyText == null ? null : typeName(currencyText);
   if (
     edition == null ||
     number == null ||
@@ -215,14 +271,17 @@ export function findRecordSales(
     );
     if (!currencyType) continue;
     try {
-      // The generated struct decodes addresses to 0x-hex and u64s to decimal strings.
+      // The generated struct decodes addresses to 0x-hex and unsigned values
+      // to decimal strings. `purchase_currency` is the raw Move byte vector,
+      // so decode it before normalizing the defining type tag.
       const s = listingContract.RecordSoldEvent.parse(e.bcs);
-      const pricing = priceFromUnknown(s.pricing);
-      const embeddedCurrency = typeName(s.purchase_currency);
-      const purchasePrice = BigInt(s.purchase_price);
+      const pricing = priceFromRichFields(s.pricing_is_fixed, s.price);
+      const currencyText = utf8ByteVector(s.purchase_currency);
+      const embeddedCurrency = currencyText == null ? null : typeName(currencyText);
+      const purchasePrice = coerceU64(s.purchase_price);
       if (
-        !pricing || embeddedCurrency !== currencyType ||
-        !validPricingRelationship(purchasePrice, pricing) ||
+        !pricing || embeddedCurrency !== currencyType || purchasePrice == null ||
+        purchasePrice <= 0n || !validPricingRelationship(purchasePrice, pricing) ||
         s.edition <= 0 || s.number <= 0
       ) throw new MalformedRecordSoldEventError({ reason: "malformed canonical RecordSoldEvent" });
       sales.push({
@@ -233,7 +292,7 @@ export function findRecordSales(
         edition: s.edition,
         number: s.number,
         purchaseCurrency: embeddedCurrency,
-        purchasePrice: s.purchase_price,
+        purchasePrice: purchasePrice.toString(),
         pricing,
         currencyType,
         purchasedBy: s.purchased_by,
@@ -274,19 +333,18 @@ const salesFromFullnode = Effect.fn("salesFromFullnode")(function* (
   config: MisoConfig,
 ): Effect.fn.Return<
   RecordSale[],
-  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | SuiRpcError,
-  SuiClient
+  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | TransactionNotFound | TransportError,
+  Sui
 > {
-  const client = yield* SuiClient;
-  const result = yield* Effect.tryPromise({
-    try: (signal) =>
-      client.core.waitForTransaction({
-        digest: txDigest,
-        include: { events: true },
-        timeout: FULLNODE_WAIT_MS,
-        signal,
-      }),
-    catch: (cause) => new SuiRpcError({ operation: "waitForTransaction", cause }),
+  const sui = yield* Sui;
+  // The mechanical tier's raw `waitForTransaction`: `Sui`'s opinionated tier
+  // has no timeout-bearing wait convenience of its own, so this reaches
+  // `sui.core` directly, per sui-effect's docs/extensions.md ("reach for it
+  // directly only for a field or method Sui does not expose").
+  const result = yield* sui.core.waitForTransaction({
+    digest: txDigest,
+    include: { events: true },
+    timeout: FULLNODE_WAIT_MS,
   });
   if (result.$kind !== "Transaction" || !result.Transaction.status.success) {
     return yield* new ReceiptNotFoundError({ digest: txDigest });
@@ -325,7 +383,7 @@ const salesFromIndexer = Effect.fn("salesFromIndexer")(function* (
   config: MisoConfig,
 ): Effect.fn.Return<
   RecordSale[],
-  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | SuiRpcError,
+  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | GraphQLUnavailable | TransportError,
   SuiGraphQL
 > {
   const client = yield* SuiGraphQL;
@@ -335,13 +393,13 @@ const salesFromIndexer = Effect.fn("salesFromIndexer")(function* (
         query: TX_EVENTS_QUERY,
         variables: { digest: txDigest },
       }),
-    catch: (cause) => new SuiRpcError({ operation: "transactionEvents", cause }),
+    catch: graphqlError("transactionEvents"),
   });
   if (errors?.length) {
-    return yield* new SuiRpcError({
-      operation: "transactionEvents",
-      cause: new AggregateError(errors.map((e) => new Error(e.message)), "Transaction events query failed"),
-    });
+    return yield* TransportError.fromUnknown(
+      "transactionEvents",
+      new AggregateError(errors.map((e) => new Error(e.message)), "Transaction events query failed"),
+    );
   }
 
   const effects = data?.transaction?.effects;
@@ -374,12 +432,12 @@ const salesFromChain = Effect.fn("salesFromChain")(function* (
   config: MisoConfig,
 ): Effect.fn.Return<
   RecordSale[],
-  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | SuiRpcError,
-  SuiClient | SuiGraphQL
+  ReceiptNotFoundError | RecordPurchaseNotFoundError | MalformedRecordSoldEventError | GraphQLUnavailable | TransportError,
+  Sui | SuiGraphQL
 > {
   return yield* salesFromFullnode(txDigest, config).pipe(
     Effect.catchIf(
-      (error): error is ReceiptNotFoundError | RecordPurchaseNotFoundError | SuiRpcError =>
+      (error): error is ReceiptNotFoundError | RecordPurchaseNotFoundError | TransactionNotFound | TransportError =>
         error._tag !== "MalformedRecordSoldEventError",
       () => salesFromIndexer(txDigest, config),
     ),
@@ -400,20 +458,18 @@ const salesFromChain = Effect.fn("salesFromChain")(function* (
 const compositionRatesByRecording = Effect.fn("compositionRatesByRecording")(function* (
   recordingIds: string[],
   config: MisoConfig,
-): Effect.fn.Return<CompositionRates, SuiRpcError | BcsDecodeError, SuiClient | SuiGraphQL> {
+): Effect.fn.Return<CompositionRates, MusicosDeploymentInvalid | GraphQLUnavailable | TransportError, Sui | SuiGraphQL> {
   if (recordingIds.length === 0) return {};
 
-  const client = yield* SuiClient;
+  const sui = yield* Sui;
   const shareTypeByRecording: Record<string, string> = {};
-  const { objects } = yield* Effect.tryPromise({
-    try: (signal) => client.core.getObjects({ objectIds: [...new Set(recordingIds)], signal }),
-    catch: (cause) => new SuiRpcError({ operation: "getObjects", cause }),
-  });
-  for (const obj of objects) {
-    if (obj instanceof Error || !obj.type) continue;
+  const results = yield* sui.getObjects([...new Set(recordingIds)].map((id) => ObjectId.make(id)));
+  for (const result of results) {
+    if (!Result.isSuccess(result)) continue;
+    const object = result.success;
     try {
-      const [, compositionShareType] = extractTypeParams2(obj.type);
-      shareTypeByRecording[obj.objectId] = compositionShareType;
+      const [, compositionShareType] = extractTypeParams2(object.type);
+      shareTypeByRecording[object.id] = compositionShareType;
     } catch {
       // A recording type we can't read the parent off — skip this track.
     }
@@ -427,12 +483,17 @@ const compositionRatesByRecording = Effect.fn("compositionRatesByRecording")(fun
     config.deployment.musicos,
   );
   const compositionIds = Object.values(addresses.compositions).filter((id): id is string => !!id);
-  const compositions = yield* getCompositionsByIds(compositionIds);
+  const compositionResults = yield* withMusicos(config.deployment.musicos, (musicos) =>
+    musicos.getCompositionsByIds(compositionIds.map((id) => ObjectId.make(id))),
+  );
+  const compositions = new Map(
+    compositionResults.flatMap((result, index) => (Result.isSuccess(result) ? [[compositionIds[index]!, result.success] as const] : [])),
+  );
 
   const rates: CompositionRates = {};
   for (const [recordingId, shareType] of Object.entries(shareTypeByRecording)) {
     const compositionId = addresses.compositions[shareType];
-    const composition = compositionId ? compositions[compositionId] : undefined;
+    const composition = compositionId ? compositions.get(compositionId) : undefined;
     if (composition) rates[recordingId] = int(composition.royaltyRate.value);
   }
   return rates;
@@ -478,18 +539,20 @@ type ReceiptError =
   | ReceiptNotFoundError
   | RecordPurchaseNotFoundError
   | MalformedRecordSoldEventError
-  | ObjectTypeMismatchError
+  | DecodeError
   | ReleaseNotFoundError
-  | BcsDecodeError
-  | SuiRpcError;
+  | MusicosWorkNotFound
+  | BatchItemError
+  | GraphQLUnavailable
+  | TransportError;
 
 const hydratePurchaseReceipt = Effect.fn("hydratePurchaseReceipt")(function* (
   sale: RecordSale,
   config: MisoConfig,
 ): Effect.fn.Return<
   PurchaseReceipt | null,
-  ObjectTypeMismatchError | ReleaseNotFoundError | BcsDecodeError | SuiRpcError,
-  SuiClient | SuiGraphQL
+  DecodeError | ReleaseNotFoundError | MusicosWorkNotFound | BatchItemError | GraphQLUnavailable | TransportError,
+  Sui | SuiGraphQL
 > {
   const detail = yield* getPressingDetail(sale.pressingId, config);
   if (!detail) return null;
@@ -512,7 +575,7 @@ const hydratePurchaseReceipt = Effect.fn("hydratePurchaseReceipt")(function* (
 export const getPurchaseReceipts = Effect.fn("getPurchaseReceipts")(function* (
   txDigest: string,
   config: MisoConfig,
-): Effect.fn.Return<PurchaseReceipt[], ReceiptError, SuiClient | SuiGraphQL> {
+): Effect.fn.Return<PurchaseReceipt[], ReceiptError, Sui | SuiGraphQL> {
   const sales = yield* salesFromChain(txDigest, config);
   const hydrated = yield* Effect.forEach(sales, (sale) => hydratePurchaseReceipt(sale, config), {
     concurrency: "unbounded",
@@ -529,7 +592,7 @@ export const getPurchaseReceipt = Effect.fn("getPurchaseReceipt")(function* (
   txDigest: string,
   recordId: string,
   config: MisoConfig,
-): Effect.fn.Return<PurchaseReceipt | null, ReceiptError, SuiClient | SuiGraphQL> {
+): Effect.fn.Return<PurchaseReceipt | null, ReceiptError, Sui | SuiGraphQL> {
   const sales = yield* salesFromChain(txDigest, config);
   const wanted = normalizeSuiAddress(recordId);
   const sale = sales.find((candidate) => normalizeSuiAddress(candidate.recordId) === wanted);

package/src/read/royalties.ts

@@ -0,0 +1,212 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Royalty claim history for one address, read from the GraphQL indexer's
+// event index. A claim is one transaction that emitted
+// `royalty_pool::pool::RoyaltyClaimedEvent` — one event per pool the
+// transaction swept — filtered by the transaction's sender, which stays the
+// wallet even when gas is sponsored, and which is the same whether the claim
+// went through `pool::claim_rewards` directly or through a routed stake sweep.
+//
+// The index is paged by event, newest last, and a page boundary can fall
+// inside a transaction. Each page returned here holds only complete claims:
+// when older events remain, the oldest transaction on the page is withheld
+// and the next cursor points just before the oldest kept one, so the next
+// page starts with the withheld transaction whole.
+//
+// The public indexers retain events for a bounded window (about four weeks at
+// the time of writing) while keeping transactions back to genesis, so a page
+// also reports the earliest checkpoint the index still covers. A caller can
+// tell "no older claims" from "no older index" with it.
+
+import { normalizeStructTag, normalizeSuiAddress, parseStructTag } from "@mysten/sui/utils";
+import { Effect } from "effect";
+import { GraphQLUnavailable, SuiGraphQL, TransportError } from "@unconfirmed/sui-effect";
+import { MalformedRoyaltyClaimedEventError } from "../errors.ts";
+import type { MisoConfig } from "./config.ts";
+import type { RoyaltyClaim, RoyaltyClaimEntry, RoyaltyClaimPage } from "./types.ts";
+
+/** The indexer caps event pages at 50. */
+export const ROYALTY_CLAIMS_PAGE_LIMIT = 50;
+
+/**
+ * `GraphQLUnavailable` lets through, not folded into `TransportError` — see
+ * `@misofm/musicos`'s own `queries.ts` for the same idiom: under
+ * `SuiGraphQL.layerUnavailable`, every call rejects with the same
+ * `GraphQLUnavailable` instance, and a caller that wants "no endpoint
+ * configured" distinguished from "the endpoint answered badly" needs the
+ * real tag rather than having it stand behind `cause`.
+ */
+const graphqlError = (method: string) => (cause: unknown): GraphQLUnavailable | TransportError =>
+  cause instanceof GraphQLUnavailable ? cause : TransportError.fromUnknown(method, cause);
+
+const CLAIMS_QUERY = `query RoyaltyClaims($sender: SuiAddress!, $type: String!, $last: Int!, $before: String) {
+  events(last: $last, before: $before, filter: { sender: $sender, type: $type }) {
+    pageInfo { hasPreviousPage }
+    edges {
+      cursor
+      node { timestamp transaction { digest } contents { type { repr } json } }
+    }
+  }
+  serviceConfig {
+    availableRange(type: "Query", field: "events") { first { timestamp } }
+  }
+}`;
+
+interface ClaimsQueryVariables {
+  sender: string;
+  type: string;
+  last: number;
+  before: string | null;
+}
+
+interface ClaimsQueryResult {
+  events: {
+    pageInfo: { hasPreviousPage: boolean };
+    edges: Array<{
+      cursor: string;
+      node: {
+        timestamp: string | null;
+        transaction: { digest: string } | null;
+        contents: { type: { repr: string }; json: unknown } | null;
+      };
+    }>;
+  } | null;
+  serviceConfig: {
+    availableRange: { first: { timestamp: string } | null } | null;
+  } | null;
+}
+
+export interface ListRoyaltyClaimsOptions {
+  /** Opaque cursor from a previous page's `nextCursor`; omit for the newest page. */
+  before?: string | null;
+  /** Events per page, 1–50. Claims per page is at most this. */
+  limit?: number;
+}
+
+/** `pkg::pool::RoyaltyClaimedEvent` — the generic name matches every `<Share, Currency>`. */
+export function royaltyClaimedEventType(config: MisoConfig): string {
+  return `${config.protocol.royaltyPool}::pool::RoyaltyClaimedEvent`;
+}
+
+function u64String(value: unknown): string | null {
+  if (typeof value === "string" && /^\d+$/.test(value)) return value;
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return String(value);
+  if (typeof value === "bigint" && value >= 0n) return value.toString();
+  return null;
+}
+
+function entryFromEvent(repr: string, json: unknown, digest: string): RoyaltyClaimEntry {
+  const fail = (reason: string) => new MalformedRoyaltyClaimedEventError({ digest, reason });
+  let typeParams: (string | { address: string })[];
+  try {
+    typeParams = parseStructTag(repr).typeParams as (string | { address: string })[];
+  } catch {
+    throw fail(`unparseable event type ${repr}`);
+  }
+  const [share, currency] = typeParams;
+  if (!share || !currency) throw fail("RoyaltyClaimedEvent without <Share, Currency>");
+  if (!json || typeof json !== "object") throw fail("RoyaltyClaimedEvent without JSON contents");
+  const fields = json as Record<string, unknown>;
+  const amount = u64String(fields.reward_amount);
+  if (typeof fields.pool_id !== "string" || typeof fields.stake_id !== "string" || amount === null) {
+    throw fail("RoyaltyClaimedEvent missing pool_id, stake_id or reward_amount");
+  }
+  return {
+    poolId: normalizeSuiAddress(fields.pool_id),
+    stakeId: normalizeSuiAddress(fields.stake_id),
+    shareType: normalizeStructTag(share as never),
+    currency: normalizeStructTag(currency as never),
+    amount,
+  };
+}
+
+/**
+ * One page of an address's royalty claims, newest first.
+ *
+ * Fails with `GraphQLUnavailable` when no GraphQL endpoint is configured,
+ * `TransportError` when the indexer cannot be reached or rejects the query,
+ * and `MalformedRoyaltyClaimedEventError` when an event of the configured
+ * type does not carry the fields this package version expects.
+ */
+export const listRoyaltyClaims = Effect.fn("listRoyaltyClaims")(function* (
+  address: string,
+  config: MisoConfig,
+  options: ListRoyaltyClaimsOptions = {},
+): Effect.fn.Return<RoyaltyClaimPage, GraphQLUnavailable | TransportError | MalformedRoyaltyClaimedEventError, SuiGraphQL> {
+  const client = yield* SuiGraphQL;
+  const limit = Math.min(Math.max(Math.trunc(options.limit ?? ROYALTY_CLAIMS_PAGE_LIMIT), 1), ROYALTY_CLAIMS_PAGE_LIMIT);
+  const { data, errors } = yield* Effect.tryPromise({
+    try: () =>
+      client.query<ClaimsQueryResult, ClaimsQueryVariables>({
+        query: CLAIMS_QUERY,
+        variables: {
+          sender: normalizeSuiAddress(address),
+          type: royaltyClaimedEventType(config),
+          last: limit,
+          before: options.before ?? null,
+        },
+      }),
+    catch: graphqlError("royaltyClaims"),
+  });
+  if (errors?.length) {
+    return yield* TransportError.fromUnknown(
+      "royaltyClaims",
+      new AggregateError(errors.map((e) => new Error(e.message)), "Royalty claims query failed"),
+    );
+  }
+
+  const edges = data?.events?.edges ?? [];
+  const hasOlder = data?.events?.pageInfo.hasPreviousPage ?? false;
+  const availableFrom = data?.serviceConfig?.availableRange?.first?.timestamp ?? null;
+  const availableFromMs = availableFrom === null ? null : Date.parse(availableFrom);
+
+  // Group in index order (oldest first); a transaction's events are contiguous.
+  const groups: Array<{ firstCursor: string; claim: RoyaltyClaim }> = [];
+  for (const { cursor, node } of edges) {
+    const digest = node.transaction?.digest;
+    const contents = node.contents;
+    if (!digest || !contents) {
+      return yield* new MalformedRoyaltyClaimedEventError({ digest: digest ?? "?", reason: "event without transaction or contents" });
+    }
+    let entry: RoyaltyClaimEntry;
+    try {
+      entry = entryFromEvent(contents.type.repr, contents.json, digest);
+    } catch (error) {
+      return yield* (error as MalformedRoyaltyClaimedEventError);
+    }
+    const last = groups.at(-1);
+    if (last && last.claim.txDigest === digest) {
+      last.claim.entries.push(entry);
+    } else {
+      groups.push({
+        firstCursor: cursor,
+        claim: {
+          txDigest: digest,
+          timestampMs: node.timestamp ? Date.parse(node.timestamp) : 0,
+          entries: [entry],
+        },
+      });
+    }
+  }
+
+  let nextCursor: string | null = null;
+  let kept = groups;
+  if (hasOlder && groups.length > 0) {
+    if (groups.length > 1) {
+      // The oldest group may continue past the page start; hand it back whole
+      // on the next page by starting that page just before the oldest kept one.
+      kept = groups.slice(1);
+      nextCursor = kept[0]!.firstCursor;
+    } else {
+      // One transaction fills the whole page: continue before its first event.
+      nextCursor = groups[0]!.firstCursor;
+    }
+  }
+
+  return {
+    claims: kept.map((group) => group.claim).reverse(),
+    nextCursor,
+    availableFromMs: availableFromMs !== null && Number.isFinite(availableFromMs) ? availableFromMs : null,
+  };
+});

package/src/read/types.ts

@@ -426,3 +426,33 @@ export interface PurchaseReceipt {
   price: string;
   tracks: TrackRoyalty[];
 }
+
+/** One pool swept by a royalty claim transaction. */
+export interface RoyaltyClaimEntry {
+  poolId: string;
+  stakeId: string;
+  /** The pool's share type, e.g. `0x…::share::Share`. */
+  shareType: string;
+  /** The currency paid out, e.g. the network's stable coin type. */
+  currency: string;
+  /** Base units of `currency`, a u64 as a decimal string. */
+  amount: string;
+}
+
+/** One royalty claim transaction sent by the address. */
+export interface RoyaltyClaim {
+  txDigest: string;
+  /** Checkpoint timestamp, milliseconds since the epoch; 0 if the index had none. */
+  timestampMs: number;
+  /** The pools swept, in event order. */
+  entries: RoyaltyClaimEntry[];
+}
+
+/** A page of claims, newest first. */
+export interface RoyaltyClaimPage {
+  claims: RoyaltyClaim[];
+  /** Pass as `before` for the next (older) page; null when none remain. */
+  nextCursor: string | null;
+  /** Earliest timestamp the event index still covers, or null if unknown. */
+  availableFromMs: number | null;
+}