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
| Protocol | Actions |
|---|---|
| Sui staking | Stake, unstake with rewards |
| Cetus | Swap (CLMM and DLMM), aggregator swap, open and close position, add and remove liquidity, fees, rewards |
| Turbos, Momentum | Swap, add and remove liquidity, fees, rewards |
| Magma, Full Sail, FlowX, Kriya, Bolt Liquidity | Swap |
| STEAMM | Swap, bank deposit and withdrawal |
| Bluefin | Swap, open and close position, add and remove liquidity, fees, rewards, Bluefin Pro trade settlement |
| Aftermath | Swap, afSUI stake and unstake, Perpetuals orders, fills and collateral; funding updates (1) |
| DeepBook | Limit orders, cancels, taker fills, balance manager deposits and withdrawals |
| DeepBook Predict | Orders, fills, position and market settlement, account deposits and withdrawals; oracle updates (1) |
| Suilend, NAVI, Scallop | Deposit, withdraw, borrow, repay, rewards, Scallop collateral |
| Haedal, Volo, SpringSui, AlphaFi | Liquid stake and unstake |
| SuiNS | Register, renew, set the default name |
| Kiosk, TradePort | Kiosk listing, TradePort purchase and accepted bid |
| Walrus | Register and certify blobs |
| Sui Bridge | Send to Ethereum; transfer approvals and claims (1) |
| Pyth, Supra, Bolt Liquidity | Price 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
{
"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
packagesnames each package family by its original id (the id of version 1). Every later version of the family matches.eventsmaps an alias to a type patternfamily::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 examplelst::events::Event<lst::liquid_staking::MintEvent>. noiselists 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.opiseq,ne,gt,gte,lt,existsormissing. A condition can also ask for an object change, for example aStakedSuicreated for the sender.pair: use one more event of the transaction.onlists fields that must be equal. Withrequired, the rule does not match without it.group: join all matches of the rule into one action. Amounts are added,countcounts the matches.fields: the values of the action. Types:amount,address,object,coinType,objectType,text,number,price,count.template: the sentence.{in}writes12.5 SUIand{in.symbol}writesSUI. 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.