Skip to content

Description Catalog ​

The Transaction Descriptions API uses a catalog of rules, one file per protocol. A rule is data, not code. It says which event to match, where each value comes from, and the sentence to write.

Covered protocols ​

ProtocolActions
Sui stakingStake, unstake with rewards
CetusSwap (CLMM and DLMM), aggregator swap, open and close position, add and remove liquidity, fees, rewards
Turbos, MomentumSwap, add and remove liquidity, fees, rewards
Magma, Full Sail, FlowX, Kriya, Bolt LiquiditySwap
STEAMMSwap, bank deposit and withdrawal
BluefinSwap, open and close position, add and remove liquidity, fees, rewards, Bluefin Pro trade settlement
AftermathSwap, afSUI stake and unstake, Perpetuals orders, fills and collateral; funding updates (1)
DeepBookLimit orders, cancels, taker fills, balance manager deposits and withdrawals
DeepBook PredictOrders, fills, position and market settlement, account deposits and withdrawals; oracle updates (1)
Suilend, NAVI, ScallopDeposit, withdraw, borrow, repay, rewards, Scallop collateral
Haedal, Volo, SpringSui, AlphaFiLiquid stake and unstake
SuiNSRegister, renew, set the default name
Kiosk, TradePortKiosk listing, TradePort purchase and accepted bid
WalrusRegister and certify blobs
Sui BridgeSend to Ethereum; transfer approvals and claims (1)
Pyth, Supra, Bolt LiquidityPrice feed updates (1)

(1) Only when nothing else happened in the transaction.

Every rule was checked against real mainnet transactions before it was added.

Entry format ​

json
{
  "schema": "inodra.tx-catalog/1",
  "protocol": "cetus",
  "name": "Cetus",
  "category": "dex",
  "packages": {
    "clmm": "0x1eabed72c53feb3805120a081dc15963c204dc8d091542592abaf7a35689b2fb"
  },
  "events": {
    "Swap": "clmm::pool::SwapEvent"
  },
  "actions": [
    {
      "id": "swap",
      "version": 1,
      "kind": "swap",
      "priority": 50,
      "match": { "event": "Swap" },
      "where": [{ "ref": { "event": "amount_in" }, "op": "gt", "value": { "const": "0" } }],
      "fields": {
        "in": {
          "type": "amount",
          "amount": { "event": "amount_in" },
          "coin": {
            "pool": { "event": "pool" },
            "coin": { "if": { "event": "atob" }, "then": { "const": 0 }, "else": { "const": 1 } }
          }
        },
        "out": {
          "type": "amount",
          "amount": { "event": "amount_out" },
          "coin": {
            "pool": { "event": "pool" },
            "coin": { "if": { "event": "atob" }, "then": { "const": 1 }, "else": { "const": 0 } }
          }
        }
      },
      "template": "Swapped {in} for {out} on Cetus",
      "swap": { "in": "in", "out": "out" }
    }
  ]
}

Packages and events ​

  • packages names each package family by its original id (the id of version 1). Every later version of the family matches.
  • events maps an alias to a type pattern family::module::Struct. An event type is matched after its address is mapped to the original id of its family. A struct added in a later version has the id of that version in its type, and it still matches.
  • A wrapped event uses Outer<Inner>, for example lst::events::Event<lst::liquid_staking::MintEvent>.
  • noise lists aliases that never give an action of their own (oracle reads, route markers). They can still be paired.

Rules ​

  • match: { "event": alias }, or { "call": "family::module::function" } for intent that has no event.
  • where: conditions that must all be true. op is eq, ne, gt, gte, lt, exists or missing. A condition can also ask for an object change, for example a StakedSui created for the sender.
  • pair: use one more event of the transaction. on lists fields that must be equal. With required, the rule does not match without it.
  • group: join all matches of the rule into one action. Amounts are added, count counts the matches.
  • fields: the values of the action. Types: amount, address, object, coinType, objectType, text, number, price, count.
  • template: the sentence. {in} writes 12.5 SUI and {in.symbol} writes SUI. A plural takes a count field, a singular and a plural word, separated by |. Start with a past-tense verb.
  • templateOne: the sentence when a grouped rule matched once.
  • swap: marks the action as a swap step that can be joined into a route.
  • absorbs: remove other actions this one already covers, in the whole transaction or in the events before it.
  • onlyIfAlone: keep the action only when the transaction has nothing else to say.
  • onFailure: the sentence for a failed transaction (call rules only).
  • version: increase it when the wording or the logic changes.

Value sources ​

  • Event field: { "event": "amount_in" }, with an optional "transform" (type, suinsName, bytesToSize)
  • Paired event field: { "pair": "pool", "transform": "type" }
  • Coin of a pool: { "pool": { "event": "pool_id" }, "coin": 0 }
  • Type parameter of the event: { "eventTypeParam": [0] }
  • Pure input of the matched call: { "input": 1, "decode": "string" }
  • What the sender spent of a coin, gas removed: { "spent": { "event": "currency" } }
  • Constants and logic: const, if / then / else, map / values, add, sub

A rule that cannot fill every field gives no action. The transaction then falls back to the generic tier. A neutral sentence is better than a wrong one.

Prices ​

A price field takes a raw integer and the names of its base and quote coin fields. The decimal shift is offset + quote decimals - base decimals. For DeepBook, offset is 9.

Versions ​

The catalog has a version string. Each response carries it, with the engine version. When either changes, a description can change, and cached descriptions are made again.

The full-stack Sui data layer.