feat(public-api): add chains endpoint

[0xApotheosis]

Description

Add chains endpoints to the public API:

• GET /v1/chains - List all supported blockchain networks with metadata
• GET /v1/chains/count - Return the total count of supported chains

The chains endpoint provides metadata about all supported blockchain networks including chain ID (CAIP-2 format), chain type (evm, utxo, cosmos, solana, etc.), native asset information, and explorer links. Chains are sorted alphabetically by name.

Issue (if applicable)

Closes #11699

Risk

Low Risk - This is a new read-only endpoint in the public-api package. No existing functionality is modified. No on-chain transactions involved.

What protocols, transaction types, wallets or contract interactions might be affected by this PR?

None. This is a new informational endpoint that returns static chain metadata.

Testing

Engineering

1. Build and run the public-api locally:

   cd packages/public-api
   yarn build:bundle && yarn start:prod

2. Test the new endpoints:

   curl http://localhost:3001/v1/chains
   curl http://localhost:3001/v1/chains/count

3. Run smoke tests:

   cd packages/public-api
   yarn test

4. Verify OpenAPI docs include the new endpoints at /docs

Operations

• 🏁 My feature is behind a flag and doesn't require operations testing (yet)

This is a backend-only API endpoint with no user-facing UI changes.

Screenshots (if applicable)

N/A - Backend API changes only

Summary by CodeRabbit

• New Features

  • GET /v1/chains — returns supported chains with metadata (id, name, type, symbol, explorer links, icons, native asset).
  • GET /v1/chains/count — returns total chain count and timestamp.
  • Added chain-related types to the public API schema.

• Documentation

  • Updated integration overview and examples to reflect a chains-first workflow.

• Tests

  • Added smoke tests validating chain list and chain count endpoints.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds two new public endpoints, /v1/chains and /v1/chains/count, plus types, OpenAPI schemas/docs updates, a routes module that builds/caches chain metadata from KnownChainIds and base assets, route registration, and two smoke tests.

Changes

Cohort / File(s)	Summary
Type Definitions packages/public-api/src/types.ts	Adds ChainType, Chain, ChainsResponse, and ChainCountResponse exported types describing chain metadata and responses.
Route Implementation packages/public-api/src/routes/chains.ts	New route module implementing getChains and getChainCount; builds a sorted chain list by iterating KnownChainIds, resolving base asset metadata, mapping namespaces to chain types, assembling explorer/icon fields, with in-memory caching and error handling.
API Registration packages/public-api/src/index.ts	Imports and registers the new handlers (getChains, getChainCount) on the v1 router and exposes the endpoints in the startup info response.
OpenAPI / Docs packages/public-api/src/docs/openapi.ts	Adds ChainType/Chain schemas, documents GET /v1/chains and GET /v1/chains/count, and reorganizes the integration overview to a chains-first flow with updated examples.
Tests packages/public-api/tests/smoke-tests.ts	Inserts two smoke tests validating chain count (non-zero) and chain list (non-empty array with chainId, name, type) and renumbers adjacent tests accordingly.

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant API as API Server
    participant Cache as In-Memory Cache
    participant ChainDB as KnownChainIds
    participant AssetDB as getBaseAsset

    Client->>API: GET /v1/chains
    API->>Cache: getChainList()
    alt Cache Hit
        Cache-->>API: return cached chains
    else Cache Miss
        API->>ChainDB: iterate KnownChainIds
        loop for each chainId
            ChainDB-->>API: chainId
            API->>AssetDB: getBaseAsset(chainId)
            AssetDB-->>API: asset metadata
            API->>API: construct Chain object (name, symbol, icons, explorer, nativeAssetId)
        end
        API->>Cache: store built chains
        Cache-->>API: chains stored
    end
    API-->>Client: { chains: Chain[], timestamp }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: starknet implementation #11511: Extends KnownChainIds and base asset definitions (e.g., Starknet additions) which this chain-list builder depends on.

Suggested reviewers

• gomesalexandre
• NeOMakinG

Poem

🐰 I hopped through KnownChainIds at dawn,
Collected icons, explorers, and a yarn,
I cached the list so queries fly on,
Now chains parade beneath the API moon! 🌙

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(public-api): add chains endpoint' accurately describes the main change: adding new chain-related API endpoints to the public-api package.
Linked Issues check	✅ Passed	The PR implements the requirement from issue #11699 by adding GET /v1/chains endpoint returning supported chains with metadata and GET /v1/chains/count endpoint for chain count.
Out of Scope Changes check	✅ Passed	All changes are scoped to the chains endpoint feature: new types, route handlers, integration with OpenAPI docs, and smoke tests—no unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/public-api-chains-endpoint

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• CAIP-2: Entity not found: Issue - Could not find referenced Issue.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/public-api/src/types.ts`:
- Around line 136-149: Change the Chain type so the optional icon uses idiomatic
TS syntax and nativeAssetId is strongly typed: replace "icon: string |
undefined" with "icon?: string" and change "nativeAssetId: string" to
"nativeAssetId: AssetId"; import the AssetId type at the top of the file and
update any callers that rely on string-only typing to satisfy the AssetId type
if necessary (look for usages around baseAsset.assetId and the chains list).

🧹 Nitpick comments (1)

packages/public-api/src/types.ts (1)

125-134: Consider a string enum for ChainType to align with TS conventions.

This is a fixed set of constants; a string enum improves discoverability and avoids typo-prone string literals. If adopted, update any assignments to use enum members (e.g., ChainType.Evm).

♻️ Proposed refactor

-export type ChainType =
-  | 'evm'
-  | 'utxo'
-  | 'cosmos'
-  | 'solana'
-  | 'tron'
-  | 'sui'
-  | 'near'
-  | 'starknet'
-  | 'ton'
+export enum ChainType {
+  Evm = 'evm',
+  Utxo = 'utxo',
+  Cosmos = 'cosmos',
+  Solana = 'solana',
+  Tron = 'tron',
+  Sui = 'sui',
+  Near = 'near',
+  Starknet = 'starknet',
+  Ton = 'ton',
+}

As per coding guidelines, please prefer string enums for constant sets.

[0xApotheosis]

As this is isolated to the public-api package and it's not currently consumed externally I'm going to keep this moving and merge.