@suilend/sui-core

The canonical, isomorphic Sui core for the Suilend ecosystem. It holds the pieces that must be identical everywhere they run — on the frontend, inside the protocol SDKs, and in the backend indexer/workflows:

• Coin types — normalized coin-type constants, grouped sets (stablecoins, BTC, ETH, points, mSEND), Pyth price-feed metadata, and the coin-type registry (COINTYPE_LOGO_MAP, COINTYPE_SYMBOL_MAP, …) plus guards (isSui, isStablecoin, isSendPoints, extractCTokenCoinType, …).
• Coin metadata — getCoinMetadataMap and the Token type.
• Transactions — spendable-coin construction, coin/object enumeration, balance-change helpers.
• Pricing — getPrice / getHistoryPrice.
• Formatting — number / token / USD / id formatters.
• Constants — API_URL, MAX_U64, MS_PER_YEAR, RPC/explorer config.

This package is the source of truth. @suilend/sui-fe re-exports it and layers the browser/React-only surface on top; the protocol SDKs and the backend depend on it directly.

Isomorphic by design

Every module runs unchanged in Node and the browser. The only browser-specific code path — the IndexedDB metadata cache used by getCoinMetadataMap — is feature-detected (typeof indexedDB === "undefined") and becomes a no-op outside the browser, so metadata still resolves from the API in Node.

API host

API_URL is PROD_API_URL unless SUILEND_API_URL is set, with any trailing slash dropped. The helpers here and in @suilend/sdk build every request from API_URL, so the variable moves all of them, for example to STAGING_API_URL.

No bundler passes SUILEND_API_URL into a browser bundle by itself. Define process.env.SUILEND_API_URL explicitly, for example with Vite's define or the env key in next.config.js. Next.js inlines only NEXT_PUBLIC_* keys on its own, so a plain environment variable leaves the browser on prod.

A relative value such as /_proxy/mainnet/lending works only in a browser bundle. In Node, use an absolute URL.

The API answers browsers only from Suilend's own https:// origins. A frontend dev server on http://localhost sets SUILEND_API_URL to a path that it proxies to the API.

Peer dependency

@mysten/sui is a peer dependency (>=2.17.0 <3) — the consumer pins the exact version so there is a single copy in the tree.

Build

yarn build     # tsc -> ./dist, then rewrite relative imports to .js (ESM)
yarn typecheck # tsc --noEmit

Releasing

Publishing is automated by .github/workflows/sui_core_publish.yaml via npm OIDC Trusted Publishing — there is no npm token to manage or rotate, and provenance is attached automatically.

To cut a release:

1. Bump version in package.json and merge it.

2. Push a tag whose version matches:

   • release-sui-core-v<version> → published to the latest dist-tag.
   • release-sui-core-prerelease-<version> → published to the next dist-tag.

   git tag release-sui-core-v0.1.0 && git push origin release-sui-core-v0.1.0

   The workflow fails loudly if the tag version and package.json version disagree.

One-time bootstrap (first publish of this package name only): Trusted Publishing attaches to a package that already exists on npm, so publish once manually — yarn release locally (npm publish with 2FA), or a short-lived 90-day granular token — then on npmjs.com set @suilend/sui-core → Settings → Trusted Publisher → GitHub Actions (org fireflyprotocol, repo lending-mono, workflow sui_core_publish.yaml). Every release after that is token-free.