@odatano/defi

Cardano DeFi protocols as data: the deployed script hashes and policies, and pure functions that turn an output's datum and value into a typed record. No network, no database, no framework; @harmoniclabs/plutus-data reads the CBOR.

npm install @odatano/defi

import { minswapV2PoolState, sundaeV3PoolState, decodeFluidLoanDatum, decodeLiqwidMarketState, decodeIndigoCdp } from '@odatano/defi';

const pool = minswapV2PoolState({ datum, value: [{ unit: 'lovelace', quantity: '4999452955' }, ...] });
// { protocol: 'minswap-v2', poolId, assetA, assetB, reserveA, reserveB, lpSupply, feeBps }

Every decoder takes the datum as CBOR hex and returns null when the bytes are not that datum, so one address with several datum shapes can be filtered without exceptions. Amounts are bigint in the smallest unit of the asset; timestamps are milliseconds.

Protocols

| Protocol | Constants | Decoders | | --- | --- | --- | | Minswap V1 | MINSWAP_V1_CONFIG (pool and order script, pool NFT and LP policy, factory token) | decodeMinswapV1PoolDatum, minswapV1PoolState (reserves from the value; the pool NFT name is the pool id; fixed 0.3 % fee), decodeMinswapV1OrderDatum, minswapV1Order (names no pool: a swap offers what the value holds besides the wanted asset; the owner is the sender) | | Minswap V2 | MINSWAP_V2_CONFIG (pool, order, factory, LP policy, pool NFT per network) | decodeMinswapV2PoolDatum, minswapV2PoolState (needs the pool NFT and exactly one LP token in the value; the LP token name is the pool id), decodeMinswapV2OrderDatum, minswapV2Order (every order step; a swap's offered asset comes from the value by direction) | | SundaeSwap V3 | SUNDAE_V3_CONFIG (pool, order, settings, manager; the pool script mints the pool NFT and LP tokens) | decodeSundaeV3PoolDatum, sundaeV3PoolState (reserves from the value, protocol fees netted out of the ADA side; the pool identifier is the pool id), decodeSundaeV3OrderDatum, sundaeV3Order | | SundaeSwap V4 | SUNDAE_V4_CONFIG (pool, order and settings script, pool NFT and LP policy, the constant-sum and stableswap modules) | decodeSundaeV4PoolDatum, sundaeV4Curve (constant sum or stableswap, from the module that leads an enabled action), sundaeV4PoolState (reserves from the datum, pools of two assets), sundaeV4CurveConfig (fees, prices and rates: the datum keeps only their hash, the configuration with that hash is found in the redeemers of the transaction that created the state), sundaeV4Price (second asset per first at the margin, before the fee) | | WingRiders V2 | WINGRIDERS_V2_CONFIG (constant product and stableswap pools and requests, factory, LP policy) | decodeWingRidersV2PoolDatum, wingRidersV2PoolState (reserves from the value minus the treasuries and the 3 ADA minimum; LP supply is the maximum minus what the pool holds), decodeWingRidersV2RequestDatum, wingRidersV2Order (names the pool by its asset pair) | | FluidTokens Lending V3 | FLUIDTOKENS_V3_CONFIG (validators and policies of the mainnet deployment) | decodeFluidPoolDatum, decodeFluidLoanDatum, decodeFluidConfigDatum | | Liqwid v2 | LIQWID_MARKETS (market id, MarketState script, underlying asset and decimals per live market), liqwidMarketByCredential | decodeLiqwidMarketState, liqwidTotalSupplied, liqwidUtilization, liqwidQTokenRate | | Djed | DJED_CONFIG (DJED, SHEN and reserve NFT units, the pre-minted supply) | djedReserveState (reserve ADA and DJED and SHEN in circulation from the value of the reserve UTxO), djedReserveRatioPct | | RealFi | REALFI_CONFIG (USDrf and sUSDrf units, staking vault, treasury, order and yield oracle scripts with their NFTs) | decodeRealFiVaultDatum, realFiVaultState (USDrf held, sUSDrf supply and the running reward of the vault UTxO), realFiStakedUsdrf, realFiStakeRate (USDrf per sUSDrf at a point in time), realFiTreasuryState (USDrf supply) | | Indigo | INDIGO_CONFIG (current and former CDP validators, CDP token, stability pools) | decodeIndigoCdp (every CDP layout so far; the iAsset registry entry at the same script decodes to null) |

STABLECOINS lists the mainnet stablecoins with policy, asset name, decimals, peg and backing.

PoolState is the shape every DEX decoder maps to, so a consumer can aggregate pools of different DEXes together: protocol, poolId, assetA, assetB, reserveA, reserveB, lpSupply, feeBps. poolPrice gives A per B in smallest units, adaUsdOfPool the dollars per ADA an ADA / stablecoin pool implies, median folds several of those into one.

Helpers

decodeData, fields, int, num, bytes, list, option, bool, credential, address and asset read PlutusData the way Aiken encodes it (Option as Constr 0/1, Bool as Constr 0/1, Credential as Constr 0 key / Constr 1 script, assets as Constr 0 [policy, name]). They return null instead of throwing, so a decoder is a chain of reads with one check at the end.

Tests

npm test runs the decoders against outputs read from mainnet (test/fixtures.ts, test/fixtures-dex.ts, test/fixtures-orders.ts, test/fixtures-hash.ts, test/fixtures-realfi.ts, test/fixtures-sundae-v4.ts), field by field against the published layouts and against on-chain invariants (LP supply plus the pool's LP holding is the maximum; Liqwid's rate times its qToken supply is the total supplied).

License

Apache License 2.0, see LICENSE.