Events

An event is one row in activity_events. The type column is a Postgres enum; the identifier columns link the event to the token, the Pair MarketPair MarketThe canonical pairing of an internet asset with a financial Pair: TOKEN × PAIR INSTRUMENT, plus the Pair Vault, configuration and accounting that connect them., the Pair InstrumentPair InstrumentThe financial exposure a Pair Market is paired with, such as Tokyo Residential or Swiss Government Debt. A catalog object with a provider, an eligibility policy and a status. and the wallet it concerns; usdValue and amountRaw carry the quantity; txSignature points at the Solana transaction when one exists; payload holds the type-specific fields.

export const activityEvents = pgTable(
  "activity_events",
  {
    id: uuid("id").primaryKey().defaultRandom(),
    type: activityTypeEnum("type").notNull(),
    tokenId: uuid("token_id").references(() => tokens.id, { onDelete: "cascade" }),
    pairMarketId: uuid("pair_market_id").references(() => pairMarkets.id, { onDelete: "cascade" }),
    instrumentId: uuid("instrument_id").references(() => pairInstruments.id),
    wallet: text("wallet"),
    usdValue: numeric("usd_value", { precision: 24, scale: 6 }),
    amountRaw: numeric("amount_raw", { precision: 40, scale: 0 }),
    txSignature: text("tx_signature"),
    payload: jsonb("payload").$type<Record<string, unknown>>().notNull().default({}),
    ledgerMode: ledgerModeEnum("ledger_mode").notNull(),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (t) => [
    index("activity_created_idx").on(t.createdAt),
    index("activity_token_idx").on(t.tokenId, t.createdAt),
    index("activity_instrument_idx").on(t.instrumentId, t.createdAt),
    index("activity_wallet_idx").on(t.wallet, t.createdAt),
    index("activity_type_idx").on(t.type, t.createdAt),
  ],
);

• ·Amounts are stored as integer base units in amountRaw; usdValue is a display figure computed at the time of the event.
• ·Every row carries a Ledger modeLedger modeEvery financial ledger row carries live or development. Production reads and writes live rows only.. Production reads and writes live rows only.
• ·The five indexes serve the feeds PairStreet renders: global, per token, per instrument, per wallet, and per type, each ordered by time.
• ·Events are written inside the same database transaction as the state change they describe, so an event never exists without the state change it reports.

Twelve event types are defined. Three are emitted on Solana mainnet today. The settlement family is emitted by the settlement engine and goes live per Pair Instrument with its settlement route. The status column says which.

Planned for the two instrument events means the enum values exist and the activity feed renders them; emission from the catalog sync that upserts the registry is the remaining step. The Pair Requests chapter covers the demand events in context.

The architecture chapters describe the lifecycle with descriptive event names. Each maps to a stored type, or to a ledger row where the stored type is planned.

One settlement produces three events, written in a single database transaction in a fixed order: the purchase, the settlement, and the reward allocation. A reader of the stream sees them together or not at all.

Tokyo Residential here is a Pair Instrument representing the target financial exposure configured for the Pair Market. The purchase row carries the units acquired and their value at the execution price ($14,218.00 ÷ 553.01 ≈ $25.7102 per unit); the settlement row carries the sequence that ties all three rows to pair_settlements; the allocation row carries the epoch number and the Merkle root holders verify their claims against. See Accounting for the full chain.

GET /api/activity returns events newest first, with the token and instrument joined in. Production returns live rows only.

GET /api/activity?group=pair&token=<mint>&limit=30

200 OK
cache-control: no-store

{
  "items": [
    {
      "id": "<uuid>",
      "type": "PAIR_SELECTED",
      "createdAt": "<iso-8601>",
      "wallet": "<creator-wallet>",
      "usdValue": null,
      "amountRaw": null,
      "txSignature": null,
      "ledgerMode": "live",
      "payload": { "instrument": "tokyo-residential" },
      "token": { "mint": "<mint>", "symbol": "TOKYO", "name": "<name>", "imageUrl": "<url>" },
      "instrument": { "slug": "tokyo-residential", "name": "Tokyo Residential", "shortName": "Tokyo Residential", "icon": "<icon>", "country": "JP" }
    }
  ],
  "nextCursor": "<iso-8601 of the last item, or null>"
}

Groups