feat: integrate Story (1514) as second-class Relay chain

.beads/ss-dx5.16.json

@@ -0,0 +1,39 @@
+[
+  {
+    "id": "ss-dx5.16",
+    "title": "Integrate Story (chainId: 1514, IP, L1)",
+    "description": "TVL: $42.4M | RPC: https://mainnet.storyrpc.io | Explorer: https://storyscan.xyz | Token Support: All | Pattern B (RPC-only) | IP blockchain",
+    "notes": "\nLogo: https://assets.relay.link/icons/1514/light.png (dark: dark.png)\nCoinGecko platform: story\nCoinGecko native ID: story-2 (⚠️ NOT \"story\"!)\nArch: L1 (IP/Intellectual Property blockchain)\nNative token: IP (18 decimals)\nSLIP44: 60 (Ethereum)\nETH-native: NO — IP gas token\nViem: ✅ story (id: 1514) — import { story } from \"viem/chains\"\nAcross: ❌ NOT SUPPORTED\nZerion ID: \"story\" (standard lowercase)\n\n--- PHASE 1 LEARNED CHECKLIST (MANDATORY) ---\n[ ] adapter.json: Create packages/caip/src/adapters/coingecko/generated/eip155_1514/adapter.json → {\"eip155:1514/slip44:60\":\"story-2\"}\n[ ] Wire adapter.json: Import+export from packages/caip/src/adapters/coingecko/generated/index.ts\n[ ] getCoingeckoSupportedChainIds: Add storyChainId (feature-flagged) in src/lib/coingecko/utils.ts\n[ ] Zerion: Add \"story\" to ZERION_CHAINS + ZERION_CHAINS_MAP in packages/types/src/zerion.ts\n[ ] Across: ❌ SKIP — not supported\n[ ] ETH test ordering: ❌ SKIP — not ETH-native\n[ ] Market-service counts: ❌ SKIP — not ETH-native\n[ ] relatedAssetKey: null (NOT eip155:1/slip44:60)\n\n--- RELAY ACTIVATION ---\n[ ] Add [storyChainId]: story.id to chainIdToRelayChainId\n[ ] Add native asset case in relayTokenToAssetId.ts\n--- ASSET DATA REGEN ---\n[ ] Create scripts/generateAssetData/story/index.ts\n[ ] Add case to scripts/generateAssetData/coingecko.ts\n[ ] Add import + getAssets call to generateAssetData.ts\n--- DRAFT PR ---\n[ ] Branch: feat/integrate-story-relay (off develop)\n[ ] gh pr create --draft\n[ ] yarn lint --fix \u0026\u0026 yarn type-check must pass\n",
+    "status": "open",
+    "priority": 2,
+    "issue_type": "task",
+    "owner": "14963751+NeOMakinG@users.noreply.github.com",
+    "created_at": "2026-02-17T10:56:01Z",
+    "created_by": "NeOMakinG",
+    "updated_at": "2026-02-17T22:43:23Z",
+    "labels": [
+      "evm",
+      "non-eth-gas",
+      "relay",
+      "tier-2"
+    ],
+    "dependencies": [
+      {
+        "id": "ss-dx5",
+        "title": "Add support for missing Relay.link EVM chains",
+        "description": "Master epic tracking integration of ALL chains supported by Relay.link that ShapeShift web doesn't currently support. Enables cross-chain bridging capabilities via Relay infrastructure. See https://github.com/shapeshift/web/issues/11902 for full details. All new EVM chains will use Pattern B (RPC-only + getKnownTokens) since no ShapeShift unchained indexer infrastructure exists for these chains.",
+        "notes": "=== FROM ISSUE COMMENTS ===\n\nLOGO PATTERN: https://assets.relay.link/icons/{chainId}/light.png (dark: dark.png)\n\nARCHITECTURE GROUPS:\n- OP Stack (standard): Ink, Unichain, BOB, Mode, Hemi, World Chain, Soneium, Zircuit, Lisk, Cyber, Blast, Zora, Redstone, Shape, Superseed, Manta Pacific\n- zkEVM (special handling): Scroll, zkSync Era, Linea, Polygon zkEVM, Taiko, Abstract\n- Arbitrum Orbit: ApeChain, Xai, Sanko\n- Non-ETH gas (10 chains): Mantle(MNT), Metis(METIS), Cronos(CRO), Ronin(RON), Sonic(S), Flow(FLOW), Berachain(BERA), Plume(PLUME), Story(IP), Stable(gUSDT)\n\nCRITICAL CHAINS:\n1. Celo (42220): Native token is BOTH native AND ERC20. Relay uses wrapped CELO. Check relayTransactionMetadata.assetRequiringApproval\n2. Blast (81457): Rebasing ETH from L1 staking yield. USDB also rebases. Handle in balance displays.\n3. Ethereal (5064014): NOT in viem. Needs custom chain definition.\n4. zkSync Era (324) + Abstract (2741): Type 113 (EIP-712) transactions. Use viem zksync chainConfig.\n5. Linea (59144): Custom linea_estimateGas RPC method.\n6. Sei (1329): Parallelized EVM + CosmWasm interop. CoinGecko uses sei-v2 NOT sei.\n\nCOINGECKO GOTCHAS: sei-\u003esei-v2, plume-\u003eplume-network, zksync-\u003ezksync, metis-\u003emetis-andromeda, morph-\u003emorph-l2, gravity-\u003egravity-alpha, boba-\u003eboba, zora-\u003ezora-network, funkichain-\u003efunki, Superposition (capital S). BOB/Zero Network have null chain_identifier. 11 chains not on CoinGecko at all.\n\nPER-CHAIN CHECKLIST: [ ] chain-adapters [ ] caip [ ] asset-service [ ] feature-flag [ ] plugin [ ] env-config [ ] icon/logo\n\n=== RELAY SWAPPER INTEGRATION (per chain) ===\n\nFILE 1: packages/swapper/src/swappers/RelaySwapper/constant.ts\n  - Add to chainIdToRelayChainId map: [newChainChainId]: \u003cviem_chain\u003e.id (or numeric chain ID)\n  - Import the caip chainId (e.g., scrollChainId) from @shapeshiftoss/caip\n  - Import viem chain from viem/chains (or use raw numeric ID if not in viem)\n  - The reverse map relayChainIdToChainId auto-generates via invert()\n\nFILE 2: packages/swapper/src/swappers/RelaySwapper/utils/relayTokenToAssetId.ts\n  - Add case CHAIN_REFERENCE.NewChainMainnet: with ASSET_REFERENCE.NewChain + ASSET_NAMESPACE.slip44\n\nNO CHANGES NEEDED (for EVM chains):\n  - getRelayAssetAddress.ts (uses generic isNativeEvmAsset + DEFAULT_RELAY_EVM_TOKEN_ADDRESS)\n  - getRelayDefaultUserAddress.ts (falls through to DEFAULT_RELAY_EVM_USER_ADDRESS default)\n\nUPSTREAM DEPS REQUIRED (in @shapeshiftoss packages):\n  - @shapeshiftoss/caip: export newChainChainId, CHAIN_REFERENCE.NewChainMainnet, ASSET_REFERENCE.NewChain\n  - @shapeshiftoss/types: KnownChainIds.NewChainMainnet\n  - @shapeshiftoss/chain-adapters: NewChain chain adapter class\n  - viem/chains: chain config (or custom if not in viem)\n\nRELAY API: https://api.relay.link (env: VITE_RELAY_API_URL) - no per-chain config needed\n\n=== ASSET DATA REGENERATION (per chain) ===\n\nAfter integrating each chain, run a partial assets data regen to populate the token list.\n\nFILE 1 (CREATE): scripts/generateAssetData/\u003cchainname\u003e/index.ts\n  Pattern (identical for all EVM chains):\n    import { \u003cchainname\u003eChainId } from '@shapeshiftoss/caip'\n    import type { Asset } from '@shapeshiftoss/types'\n    import { \u003cchainname\u003e, unfreeze } from '@shapeshiftoss/utils'\n    import * as coingecko from '../coingecko'\n    export const getAssets = async (): Promise\u003cAsset[]\u003e =\u003e {\n      const assets = await coingecko.getAssets(\u003cchainname\u003eChainId)\n      return [...assets, unfreeze(\u003cchainname\u003e)]\n    }\n\nFILE 2 (MODIFY): scripts/generateAssetData/coingecko.ts\n  - Import \u003cchainname\u003eChainId from @shapeshiftoss/caip\n  - Import \u003cchainname\u003e native asset from @shapeshiftoss/utils\n  - Add case in the switch: case \u003cchainname\u003eChainId: return { assetNamespace: ASSET_NAMESPACE.erc20, category: adapters.chainIdToCoingeckoAssetPlatform(chainId), explorer/explorerAddressLink/explorerTxLink from \u003cchainname\u003e utils }\n  - NOTE: chains not on CoinGecko will only have the native asset (no ERC20 token list)\n\nFILE 3 (MODIFY): scripts/generateAssetData/generateAssetData.ts\n  - Import: import * as \u003cchainname\u003e from './\u003cchainname\u003e'\n  - Call: const \u003cchainname\u003eAssets = await \u003cchainname\u003e.getAssets()\n  - Spread into unfilteredAssetData: ...\u003cchainname\u003eAssets\n\nCOMMAND: yarn generate:asset-data\n  This regenerates: src/generated/asset-data.json + related-asset-index + manifest + compressed assets\n\n=== DRAFT PR CREATION (final step per chain) ===\n\nAfter all code changes are complete for a chain, open a draft PR using the repo template.\n\nBRANCH NAMING: feat/integrate-\u003cchainname\u003e-relay (e.g. feat/integrate-scroll-relay)\n\nCOMMAND:\n  gh pr create --draft --title 'feat: integrate \u003cChainName\u003e (chainId: \u003cid\u003e) via Relay' --body \"$(cat \u003c\u003c'PREOF'\n  ## Description\n\n  Add \u003cChainName\u003e (chainId: \u003cid\u003e) as a second-class EVM chain in ShapeShift Web with Relay bridge support.\n\n  **Changes:**\n  - Plugin registration in src/plugins/\u003cchainname\u003e/\n  - Feature flag `\u003cChainName\u003e` in preferencesSlice\n  - Relay swapper chain mapping in RelaySwapper/constant.ts\n  - Asset data generation via CoinGecko (`\u003ccoingecko_platform_id\u003e`)\n  - Environment config for RPC URL\n\n  **Chain details:**\n  - TVL: \u003ctvl\u003e\n  - Native token: \u003ctoken\u003e (18 decimals)\n  - Architecture: \u003carch_type\u003e\n  - RPC: \u003crpc_url\u003e\n  - Explorer: \u003cexplorer_url\u003e\n\n  ## Issue (if applicable)\n\n  Part of #11902\n\n  ## Risk\n\n  Low risk — new chain behind feature flag (`\u003cChainName\u003e`), no existing functionality affected.\n\n  \u003e New chain plugin + Relay bridge mapping. No modifications to existing chain logic.\n\n  ## Testing\n\n  ### Engineering\n\n  1. Enable feature flag: set `VITE_FEATURE_\u003cCHAINNAME\u003e=true` in .env\n  2. Verify chain appears in supported chains list\n  3. Verify native token balance loads (connect wallet with \u003ctoken\u003e on \u003cChainName\u003e)\n  4. Verify Relay bridge quote works: bridge ETH from Ethereum → \u003cChainName\u003e\n  5. Run `yarn lint --fix \u0026\u0026 yarn type-check` — must pass\n\n  ### Operations\n\n  - [x] :checkered_flag: My feature is behind a flag and doesn't require operations testing (yet)\n\n  ## Screenshots (if applicable)\n\n  N/A — chain integration, no UI changes.\n  PREOF\n  )\"\n\nNOTE: Replace all \u003cplaceholders\u003e with actual chain values from the bead description/notes.\nNOTE: Use --draft flag to create as draft PR.\nNOTE: Branch off develop (main branch is develop, not main).",
+        "status": "open",
+        "priority": 0,
+        "issue_type": "epic",
+        "owner": "14963751+NeOMakinG@users.noreply.github.com",
+        "created_at": "2026-02-17T10:55:02Z",
+        "created_by": "NeOMakinG",
+        "updated_at": "2026-02-17T11:21:27Z",
+        "external_ref": "gh-11902",
+        "dependency_type": "parent-child"
+      }
+    ],
+    "parent": "ss-dx5"
+  }
+]

.env

@@ -162,6 +162,7 @@ VITE_MEGAETH_NODE_URL=https://mainnet.megaeth.com/rpc
 VITE_LINEA_NODE_URL=https://rpc.linea.build
 VITE_SCROLL_NODE_URL=https://rpc.scroll.io/
 VITE_KATANA_NODE_URL=https://rpc.katana.network
+VITE_STORY_NODE_URL=https://mainnet.storyrpc.io
 VITE_ZKSYNC_ERA_NODE_URL=https://mainnet.era.zksync.io
 VITE_BLAST_NODE_URL=https://rpc.blast.io
 VITE_WORLDCHAIN_NODE_URL=https://worldchain-mainnet.g.alchemy.com/public
@@ -326,6 +327,7 @@ VITE_FEATURE_BERACHAIN=false
 VITE_FEATURE_SCROLL=false
 VITE_FEATURE_NEAR=true
 VITE_FEATURE_KATANA=true
+VITE_FEATURE_STORY=false
 VITE_FEATURE_ZK_SYNC_ERA=false
 VITE_FEATURE_BLAST=false
 VITE_FEATURE_HEMI=false

.env.development

@@ -61,6 +61,7 @@ VITE_BASE_NODE_URL=https://dev-api.base.shapeshift.com/api/v1/jsonrpc
 VITE_MONAD_NODE_URL=https://rpc.monad.xyz
 VITE_PLASMA_NODE_URL=https://rpc.plasma.to
 VITE_KATANA_NODE_URL=https://rpc.katana.network
+VITE_STORY_NODE_URL=https://mainnet.storyrpc.io
 VITE_ZKSYNC_ERA_NODE_URL=https://mainnet.era.zksync.io
 VITE_BLAST_NODE_URL=https://rpc.blast.io
 VITE_WORLDCHAIN_NODE_URL=https://worldchain-mainnet.g.alchemy.com/public
@@ -117,6 +118,7 @@ VITE_FEATURE_LINEA=true
 VITE_FEATURE_BERACHAIN=true
 VITE_FEATURE_SCROLL=true
 VITE_FEATURE_KATANA=true
+VITE_FEATURE_STORY=true
 VITE_FEATURE_ZK_SYNC_ERA=true
 VITE_FEATURE_BLAST=true
 VITE_FEATURE_WORLDCHAIN=true

headers/csps/chains/story.ts

@@ -0,0 +1,10 @@
+import { loadEnv } from 'vite'
+
+import type { Csp } from '../../types'
+
+const mode = process.env.MODE ?? process.env.NODE_ENV ?? 'development'
+const env = loadEnv(mode, process.cwd(), '')
+
+export const csp: Csp = {
+  'connect-src': [env.VITE_STORY_NODE_URL],
+}

headers/csps/index.ts

@@ -38,6 +38,7 @@ import { csp as solana } from './chains/solana'
 import { csp as soneium } from './chains/soneium'
 import { csp as sonic } from './chains/sonic'
 import { csp as starknet } from './chains/starknet'
+import { csp as story } from './chains/story'
 import { csp as sui } from './chains/sui'
 import { csp as thorchain } from './chains/thorchain'
 import { csp as ton } from './chains/ton'
@@ -159,6 +160,7 @@ export const csps = [
   monad,
   near,
   plasma,
+  story,
   worldchain,
   sonic,
   trustwallet,

packages/caip/src/adapters/coingecko/generated/eip155_1514/adapter.json

@@ -0,0 +1 @@
+{"eip155:1514/slip44:60":"story-2"}

packages/caip/src/adapters/coingecko/generated/index.ts

@@ -21,6 +21,7 @@ import linea from "./eip155_59144/adapter.json";
 import bob from "./eip155_60808/adapter.json";
 import mode from "./eip155_34443/adapter.json";
 import megaeth from "./eip155_4326/adapter.json";
+import story from "./eip155_1514/adapter.json";
 import mantle from "./eip155_5000/adapter.json";
 import berachain from "./eip155_80094/adapter.json";
 import ink from "./eip155_57073/adapter.json";
@@ -65,6 +66,7 @@ export {
   linea,
   mode,
   megaeth,
+  story,
   mantle,
   berachain,
   ink,

packages/caip/src/adapters/coingecko/index.ts

@@ -37,6 +37,7 @@ import {
   soneiumChainId,
   sonicChainId,
   starknetChainId,
+  storyChainId,
   suiChainId,
   thorchainChainId,
   tonChainId,
@@ -67,6 +68,7 @@ export enum CoingeckoAssetPlatform {
   Plasma = 'plasma',
   Ink = 'ink',
   Katana = 'katana',
+  Story = 'story',
   ZkSyncEra = 'zksync',
   Blast = 'blast',
   WorldChain = 'world-chain',
@@ -142,6 +144,8 @@ export const chainIdToCoingeckoAssetPlatform = (chainId: ChainId): string => {
           return CoingeckoAssetPlatform.Plasma
         case CHAIN_REFERENCE.KatanaMainnet:
           return CoingeckoAssetPlatform.Katana
+        case CHAIN_REFERENCE.StoryMainnet:
+          return CoingeckoAssetPlatform.Story
         case CHAIN_REFERENCE.ZkSyncEraMainnet:
           return CoingeckoAssetPlatform.ZkSyncEra
         case CHAIN_REFERENCE.BlastMainnet:
@@ -283,6 +287,8 @@ export const coingeckoAssetPlatformToChainId = (
       return worldChainChainId
     case CoingeckoAssetPlatform.Katana:
       return katanaChainId
+    case CoingeckoAssetPlatform.Story:
+      return storyChainId
     case CoingeckoAssetPlatform.Mantle:
       return mantleChainId
     case CoingeckoAssetPlatform.Sonic:

packages/caip/src/adapters/coingecko/utils.test.ts

@@ -191,6 +191,9 @@ describe('adapters:coingecko:utils', () => {
         'eip155:747474': {
           'eip155:747474/slip44:60': 'katana',
         },
+        'eip155:1514': {
+          'eip155:1514/slip44:60': 'story-2',
+        },
         'eip155:324': {
           'eip155:324/slip44:60': 'ethereum',
         },

packages/caip/src/adapters/coingecko/utils.ts

@@ -70,6 +70,8 @@ import {
   sonicChainId,
   starknetAssetId,
   starknetChainId,
+  storyAssetId,
+  storyChainId,
   suiAssetId,
   suiChainId,
   thorchainChainId,
@@ -431,6 +433,20 @@ export const parseData = (coins: CoingeckoCoin[]): AssetMap => {
         }
       }
 
+      if (Object.keys(platforms).includes(CoingeckoAssetPlatform.Story)) {
+        try {
+          const assetId = toAssetId({
+            chainNamespace: CHAIN_NAMESPACE.Evm,
+            chainReference: CHAIN_REFERENCE.StoryMainnet,
+            assetNamespace: 'erc20',
+            assetReference: platforms[CoingeckoAssetPlatform.Story],
+          })
+          prev[storyChainId][assetId] = id
+        } catch {
+          // unable to create assetId, skip token
+        }
+      }
+
       if (Object.keys(platforms).includes(CoingeckoAssetPlatform.ZkSyncEra)) {
         try {
           const assetId = toAssetId({
@@ -606,6 +622,7 @@ export const parseData = (coins: CoingeckoCoin[]): AssetMap => {
       [berachainChainId]: { [berachainAssetId]: 'berachain-bera' },
       [cronosChainId]: { [cronosAssetId]: 'crypto-com-chain' },
       [katanaChainId]: { [katanaAssetId]: 'katana' },
+      [storyChainId]: { [storyAssetId]: 'story-2' },
       [zkSyncEraChainId]: { [zkSyncEraAssetId]: 'ethereum' },
       [blastChainId]: { [blastAssetId]: 'ethereum' },
       [worldChainChainId]: { [worldChainAssetId]: 'ethereum' },

packages/caip/src/constants.ts

@@ -25,6 +25,7 @@ export const worldChainAssetId: AssetId = 'eip155:480/slip44:60'
 export const berachainAssetId: AssetId = 'eip155:80094/slip44:60'
 export const cronosAssetId: AssetId = 'eip155:25/slip44:60'
 export const katanaAssetId: AssetId = 'eip155:747474/slip44:60'
+export const storyAssetId: AssetId = 'eip155:1514/slip44:60'
 export const zkSyncEraAssetId: AssetId = 'eip155:324/slip44:60'
 export const blastAssetId: AssetId = 'eip155:81457/slip44:60'
 export const hemiAssetId: AssetId = 'eip155:43111/slip44:60'
@@ -101,6 +102,7 @@ export const worldChainChainId: ChainId = 'eip155:480'
 export const berachainChainId: ChainId = 'eip155:80094'
 export const cronosChainId: ChainId = 'eip155:25'
 export const katanaChainId: ChainId = 'eip155:747474'
+export const storyChainId: ChainId = 'eip155:1514'
 export const zkSyncEraChainId: ChainId = 'eip155:324'
 export const blastChainId: ChainId = 'eip155:81457'
 export const hemiChainId: ChainId = 'eip155:43111'
@@ -168,6 +170,7 @@ export const CHAIN_REFERENCE = {
   BerachainMainnet: '80094',
   CronosMainnet: '25',
   KatanaMainnet: '747474', // https://docs.katana.network
+  StoryMainnet: '1514', // https://docs.story.foundation
   ZkSyncEraMainnet: '324', // https://docs.zksync.io
   BlastMainnet: '81457', // https://docs.blast.io
   HemiMainnet: '43111', // https://docs.hemi.xyz
@@ -227,6 +230,7 @@ export const ASSET_REFERENCE = {
   Berachain: '60', // evm chain which uses ethereum derivation path as common practice
   Cronos: '60', // evm chain which uses ethereum derivation path as common practice
   Katana: '60', // evm chain which uses ethereum derivation path as common practice
+  Story: '60', // evm chain which uses ethereum derivation path as common practice
   ZkSyncEra: '60', // evm chain which uses ethereum derivation path as common practice
   Blast: '60', // evm chain which uses ethereum derivation path as common practice
   WorldChain: '60', // evm chain which uses ethereum derivation path as common practice
@@ -272,6 +276,7 @@ export const VALID_CHAIN_IDS: ValidChainMap = Object.freeze({
     CHAIN_REFERENCE.BerachainMainnet,
     CHAIN_REFERENCE.CronosMainnet,
     CHAIN_REFERENCE.KatanaMainnet,
+    CHAIN_REFERENCE.StoryMainnet,
     CHAIN_REFERENCE.ZkSyncEraMainnet,
     CHAIN_REFERENCE.BlastMainnet,
     CHAIN_REFERENCE.WorldChainMainnet,
@@ -340,6 +345,7 @@ export const FEE_ASSET_IDS = [
   mantleAssetId,
   inkAssetId,
   megaethAssetId,
+  storyAssetId,
   zkSyncEraAssetId,
   blastAssetId,
   hemiAssetId,

packages/chain-adapters/src/evm/EvmBaseAdapter.ts

@@ -33,6 +33,7 @@ import {
   supportsScroll,
   supportsSoneium,
   supportsSonic,
+  supportsStory,
   supportsUnichain,
   supportsWorldChain,
   supportsZkSyncEra,
@@ -107,6 +108,7 @@ export const evmChainIds = [
   KnownChainIds.BerachainMainnet,
   KnownChainIds.CronosMainnet,
   KnownChainIds.KatanaMainnet,
+  KnownChainIds.StoryMainnet,
   KnownChainIds.ZkSyncEraMainnet,
   KnownChainIds.BlastMainnet,
   KnownChainIds.WorldChainMainnet,
@@ -230,6 +232,8 @@ export abstract class EvmBaseAdapter<T extends EvmChainId> implements IChainAdap
           return supportsCronos(wallet)
         case Number(fromChainId(KnownChainIds.KatanaMainnet).chainReference):
           return supportsKatana(wallet)
+        case Number(fromChainId(KnownChainIds.StoryMainnet).chainReference):
+          return supportsStory(wallet)
         case Number(fromChainId(KnownChainIds.ZkSyncEraMainnet).chainReference):
           return supportsZkSyncEra(wallet)
         case Number(fromChainId(KnownChainIds.BlastMainnet).chainReference):
@@ -369,6 +373,11 @@ export abstract class EvmBaseAdapter<T extends EvmChainId> implements IChainAdap
         symbol: 'ETH',
         explorer: 'https://katanascan.com',
       },
+      [KnownChainIds.StoryMainnet]: {
+        name: 'Story',
+        symbol: 'IP',
+        explorer: 'https://storyscan.xyz',
+      },
       [KnownChainIds.ZkSyncEraMainnet]: {
         name: 'Ether',
         symbol: 'ETH',