@epoch-protocol/epoch-commons-sdk 0.1.20 → 0.2.0

package/README.md

@@ -1 +1,20 @@
 # Epoch Commons SDK
+
+### Ethereum and Robinhood mainnet graph
+
+`mainnetGraph` is the canonical source for Ethereum (1) and Robinhood Chain
+(4663) network, token, and protocol relationships. `getGraphChain`,
+`getGraphToken`, and `supportsGraphProtocol` resolve chain ids and validate
+path eligibility without treating a token on one network as available on another.
+
+Native ETH uses the zero-address sentinel and 18 decimals. Generic filler and
+external routes can select ETH; `uniswap-v3` relationships expose WETH instead,
+because that solver currently requires ERC20 input. Ethereum USDG and USDe use
+the issuer addresses documented by [Paxos](https://docs.paxos.com/guides/stablecoin/usdg/mainnet)
+and [Ethena](https://docs.ethena.fi/api-documentation/overview). WBTC uses its
+Ethereum token address and 8 decimals, distinct from the 18-decimal testnet mock.
+
+Protocol router and custom Epoch/Safe address maps retain deployment
+placeholders as requested. A graph relationship describes configured routing
+eligibility; it does not verify deployment or pool liquidity. Replace placeholder
+addresses with verified deployments before executing production operations.

package/dist/constants/chains.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical chain ids. Define new ones HERE and import them — `MIDEN_CHAIN_ID`
+ * is currently redefined in seven places across the monorepo.
+ *
+ * Ids MUST fit in uint32: `getEncodedIntent` and the deployed IntentRegistry
+ * both declare `uint32[] chainIds`, so anything larger throws at ABI encode
+ * time. That rules out Solana's CAIP-2 id (1151111081099710).
+ */
+/**
+ * Solana mainnet-beta. Leading digits of the CAIP-2 id, so it stays traceable.
+ * PROVISIONAL — check chainlist for collisions before mainnet.
+ */
+export declare const SOLANA_MAINNET_CHAIN_ID = 1151111;
+/**
+ * Solana devnet. Separate id rather than one shared with mainnet, so devnet can
+ * pass the testnet-gated checks in dex-solver's candidate-evaluator and mainnet
+ * still can't skip them.
+ */
+export declare const SOLANA_DEVNET_CHAIN_ID = 1151112;
+/** Graph chain name. Load-bearing: `chains` and `token.contractAddress` key off it. */
+export declare const SOLANA_CHAIN_NAME = "Solana";

package/dist/constants/chains.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical chain ids. Define new ones HERE and import them — `MIDEN_CHAIN_ID`
+ * is currently redefined in seven places across the monorepo.
+ *
+ * Ids MUST fit in uint32: `getEncodedIntent` and the deployed IntentRegistry
+ * both declare `uint32[] chainIds`, so anything larger throws at ABI encode
+ * time. That rules out Solana's CAIP-2 id (1151111081099710).
+ */
+/**
+ * Solana mainnet-beta. Leading digits of the CAIP-2 id, so it stays traceable.
+ * PROVISIONAL — check chainlist for collisions before mainnet.
+ */
+export const SOLANA_MAINNET_CHAIN_ID = 1151111;
+/**
+ * Solana devnet. Separate id rather than one shared with mainnet, so devnet can
+ * pass the testnet-gated checks in dex-solver's candidate-evaluator and mainnet
+ * still can't skip them.
+ */
+export const SOLANA_DEVNET_CHAIN_ID = 1151112;
+/** Graph chain name. Load-bearing: `chains` and `token.contractAddress` key off it. */
+export const SOLANA_CHAIN_NAME = "Solana";

package/dist/constants/contractAddresses.js

@@ -97,10 +97,13 @@ export const ARBITER_ADDRESS = {
     10: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
     42161: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
     8453: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
+    // Robinhood placeholders — replace after deployment.
+    4663: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
     // Testnets
     11155111: "0x2F5eA866716A04e91a55099620F2e1B423eC7011",
     84532: "0x2F5eA866716A04e91a55099620F2e1B423eC7011",
     11155420: "0x2F5eA866716A04e91a55099620F2e1B423eC7011",
+    46630: "0x2F5eA866716A04e91a55099620F2e1B423eC7011",
     123456789: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
     999999999: "0x9f1de3ca45b09c61792a6f649ae68f420aa8a43b",
 };
@@ -111,10 +114,13 @@ export const ALLOCATOR_ADDRESS = {
     10: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
     42161: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
     8453: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
+    // Robinhood placeholders — replace after deployment.
+    4663: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
     // Testnets
     11155111: "0xa46827635A7d329608085401a3b2Bf14a8a2bDF9",
     84532: "0xa46827635A7d329608085401a3b2Bf14a8a2bDF9",
     11155420: "0xa46827635A7d329608085401a3b2Bf14a8a2bDF9",
+    46630: "0xa46827635A7d329608085401a3b2Bf14a8a2bDF9",
     123456789: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
     999999999: "0x444E8C0fC85BB47aBD3E97d00E2E2B0719034769",
 };
@@ -134,6 +140,39 @@ export function getArbiterAddress(chainId) {
     }
     return address;
 }
+// The Robinhood Testnet deployment uses the same deterministic/testnet
+// addresses as the existing Epoch testnet configuration. Populate every
+// shared contract map together so any consumer consulting one of these maps
+// cannot silently treat 46630 as unsupported.
+const TESTNET_CONTRACT_ADDRESS_MAPS = [
+    INTENT_REGISTRY_ADDRESS,
+    EPOCH_MODULE_SAFE_ADDRESS,
+    EPOCH_SAFE_INIT_SETUP,
+    SAFE_INIT_SETUP_FORWARDER,
+    SAFE_WEBAUTHN_SHARED_SIGNER,
+    SAFE_WEBAUTHN_SIGNER_FACTORY,
+    FCLP256Verifier,
+    SAFE_PROXY_FACTORY_ADDRESS,
+    SAFE_SINGLETON_ADDRESS,
+    SAFE_7702_SINGLETON_ADDRESS,
+    SAFE_7579_MODULE_ADDRESS,
+    SAFE_7579_REGISTRY_ADDRESS,
+    EIP7702_SAFE_PROXY_ADDRESS,
+    METAMASK_EXEC_MANAGER,
+    EPOCH_ESCROW_ADDRESS,
+    SAFE_MULTISEND_ADDRESS,
+    SAFE_MULTISEND_CALL_ONLY_ADDRESS,
+];
+for (const addresses of TESTNET_CONTRACT_ADDRESS_MAPS) {
+    addresses[46630] = addresses[11155420];
+}
+// Ethereum and Robinhood mainnet deployment placeholders. These preserve the
+// deterministic address configuration used by testnets; replace each entry
+// with its verified mainnet deployment before executing production operations.
+for (const addresses of TESTNET_CONTRACT_ADDRESS_MAPS) {
+    addresses[1] = addresses[11155420];
+    addresses[4663] = addresses[1];
+}
 const CONTRACT_ADDRESSES = {
     METAMASK_EXEC_MANAGER,
     SAFE_PROXY_FACTORY_ADDRESS,

package/dist/constants/dummyLending.d.ts

@@ -7,7 +7,7 @@ export declare const DUMMY_LENDING_PROTOCOL: "dummy-lending";
 export declare const DUMMY_LENDING_MARKET_ADDRESS = "0xa73c1ae0e4e9116020dba0a419f91585d73459ee";
 /** CREATE2 staking contract — same on all dummy-staking testnets. */
 export declare const DUMMY_STAKING_CONTRACT_ADDRESS = "0xA25A981bc027E1f13aC70882a323B8B8EE880B9C";
-export declare const DUMMY_LENDING_CHAIN_IDS: readonly [84532, 11155111, 11155420];
+export declare const DUMMY_LENDING_CHAIN_IDS: readonly [84532, 11155111, 11155420, 46630];
 export type DummyLendingChainId = (typeof DUMMY_LENDING_CHAIN_IDS)[number];
 /** Unified CREATE2 token addresses — same on every dummy-lending chain. */
 export declare const DUMMY_LENDING_TOKENS: {

package/dist/constants/dummyLending.js

@@ -11,6 +11,7 @@ export const DUMMY_LENDING_CHAIN_IDS = [
     84532, // Base Sepolia
     11155111, // Ethereum Sepolia
     11155420, // Optimism Sepolia
+    46630, // Robinhood Testnet
 ];
 /** Unified CREATE2 token addresses — same on every dummy-lending chain. */
 export const DUMMY_LENDING_TOKENS = {

package/dist/data/epochgraphmainnet.json

@@ -5,7 +5,9 @@
                 "Base": "0xMorphoBaseAddress",
                 "Optimism": "0xMorphoOptimismAddress",
                 "Polygon": "0xMorphoPolygonAddress",
-                "Arbitrum": "0xMorphoArbitrumAddress"
+                "Arbitrum": "0xMorphoArbitrumAddress",
+                "Ethereum": "0xrafflesEthereumAddress",
+                "Robinhood": "0xrafflesRobinhoodAddress"
             },
             "type": ["protocol-interaction"]
         },
@@ -15,7 +17,8 @@
                 "Base": "0x1deltaBaseAddress",
                 "Optimism": "0x1deltaOptimismAddress",
                 "Polygon": "0x1deltaPolygonAddress",
-                "Arbitrum": "0x1deltaArbitrumAddress"
+                "Arbitrum": "0x1deltaArbitrumAddress",
+                "Robinhood": "0xOnedeltaRobinhoodAddress"
             },
             "type": ["protocol-interaction"]
         },
@@ -24,7 +27,9 @@
                 "Base": "0xMorphoBaseAddress",
                 "Optimism": "0xMorphoOptimismAddress",
                 "Polygon": "0xMorphoPolygonAddress",
-                "Arbitrum": "0xMorphoArbitrumAddress"
+                "Arbitrum": "0xMorphoArbitrumAddress",
+                "Ethereum": "0xuniswapv3EthereumAddress",
+                "Robinhood": "0xuniswapv3RobinhoodAddress"
             },
             "type": ["swap"]
         },
@@ -80,7 +85,22 @@
                 "Base": "0x4200000000000000000000000000000000000006",
                 "Optimism": "0x4200000000000000000000000000000000000006",
                 "Polygon": "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
-                "Arbitrum": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1"
+                "Arbitrum": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+                "Robinhood": "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73"
+            },
+            "decimals": 18
+        },
+        "USDG": {
+            "contractAddress": {
+                "Robinhood": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+                "Ethereum": "0xe343167631d89B6Ffc58B88d6b7fB0228795491D"
+            },
+            "decimals": 6
+        },
+        "USDe": {
+            "contractAddress": {
+                "Robinhood": "0x5d3a1Ff2b6BAb83B63cd9AD0787074081a52ef34",
+                "Ethereum": "0x4c9EDD5852cd905f086C759E8383e09bff1E68B3"
             },
             "decimals": 18
         },
@@ -92,12 +112,30 @@
                 "Arbitrum": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9"
             },
             "decimals": 6
+        },
+        "ETH": {
+            "contractAddress": {
+                "Ethereum": "0x0000000000000000000000000000000000000000",
+                "Robinhood": "0x0000000000000000000000000000000000000000"
+            },
+            "decimals": 18
+        },
+        "WBTC": {
+            "contractAddress": {
+                "Ethereum": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"
+            },
+            "decimals": 8
         }
     },
     "chains": {
         "Ethereum": {
             "chainId": 1,
-            "explorer": "https://etherscan.io"
+            "explorer": "https://etherscan.io",
+            "nativeCurrency": {
+                "name": "Ether",
+                "symbol": "ETH",
+                "decimals": 18
+            }
         },
         "Base": {
             "chainId": 8453,
@@ -114,6 +152,15 @@
         "Arbitrum": {
             "chainId": 42161,
             "explorer": "https://arbiscan.io"
+        },
+        "Robinhood": {
+            "chainId": 4663,
+            "explorer": "https://robinhoodchain.blockscout.com",
+            "nativeCurrency": {
+                "name": "Ether",
+                "symbol": "ETH",
+                "decimals": 18
+            }
         }
     },
     "relationships": {
@@ -124,6 +171,21 @@
                 },
                 "Optimism": {
                     "tokensInAndOut": ["WETH", "USDC", "DAI", "USDT"]
+                },
+                "Ethereum": {
+                    "tokensInAndOut": [
+                        "DAI",
+                        "USDC",
+                        "WETH",
+                        "USDG",
+                        "USDe",
+                        "USDT",
+                        "ETH",
+                        "WBTC"
+                    ]
+                },
+                "Robinhood": {
+                    "tokensInAndOut": ["WETH", "USDG", "USDe", "ETH"]
                 }
             },
             "uniswap-v3": {
@@ -138,6 +200,20 @@
                 },
                 "Arbitrum": {
                     "tokensInAndOut": ["WETH", "USDC", "DAI", "USDT"]
+                },
+                "Ethereum": {
+                    "tokensInAndOut": [
+                        "DAI",
+                        "USDC",
+                        "WETH",
+                        "USDG",
+                        "USDe",
+                        "USDT",
+                        "WBTC"
+                    ]
+                },
+                "Robinhood": {
+                    "tokensInAndOut": ["WETH", "USDG", "USDe"]
                 }
             },
             "FillerCrossChain": {
@@ -158,6 +234,21 @@
             "1delta": {
                 "*": {
                     "tokensInAndOut": ["*"]
+                },
+                "Ethereum": {
+                    "tokensInAndOut": [
+                        "DAI",
+                        "USDC",
+                        "WETH",
+                        "USDG",
+                        "USDe",
+                        "USDT",
+                        "ETH",
+                        "WBTC"
+                    ]
+                },
+                "Robinhood": {
+                    "tokensInAndOut": ["WETH", "USDG", "USDe", "ETH"]
                 }
             },
             "ExternalSwapBridge": {
@@ -169,16 +260,25 @@
         "tokenChains": {
             "DAI": ["Ethereum", "Base", "Optimism", "Polygon", "Arbitrum"],
             "USDC": ["Ethereum", "Base", "Optimism", "Polygon", "Arbitrum"],
-            "WETH": ["Ethereum", "Base", "Optimism", "Polygon", "Arbitrum"],
+            "WETH": [
+                "Ethereum",
+                "Base",
+                "Optimism",
+                "Polygon",
+                "Arbitrum",
+                "Robinhood"
+            ],
+            "USDG": ["Ethereum", "Robinhood"],
             "USDT": ["Ethereum", "Optimism", "Polygon", "Arbitrum"],
-            "WBTC": ["Ethereum", "Optimism", "Polygon", "Arbitrum"],
+            "WBTC": ["Ethereum"],
             "wstETH": ["Ethereum", "Base", "Optimism", "Arbitrum"],
             "GHO": ["Ethereum", "Arbitrum", "Base"],
-            "USDe": ["Ethereum", "Arbitrum"],
+            "USDe": ["Ethereum", "Robinhood"],
             "cbBTC": ["Ethereum", "Base"],
             "PYUSD": ["Ethereum"],
             "LINK": ["Ethereum", "Base", "Optimism", "Polygon", "Arbitrum"],
-            "weETH": ["Ethereum", "Base", "Arbitrum"]
+            "weETH": ["Ethereum", "Base", "Arbitrum"],
+            "ETH": ["Ethereum", "Robinhood"]
         }
     }
 }

package/dist/data/epochgraphtestnet.json

@@ -71,7 +71,8 @@
                 "Base": "0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69",
                 "Mainnet": "0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69",
                 "Miden": "0x537c15a622074e91188aa894456c52",
-                "Optimism": "0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69"
+                "Optimism": "0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69",
+                "Robinhood": "0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69"
             },
             "decimals": 18,
             "decimalsByChain": {
@@ -83,6 +84,7 @@
                 "Base": "0xc30f1Ce05d1434d484E9A47283aA925fc8A8699a",
                 "Mainnet": "0xc30f1Ce05d1434d484E9A47283aA925fc8A8699a",
                 "Optimism": "0xc30f1Ce05d1434d484E9A47283aA925fc8A8699a",
+                "Robinhood": "0xc30f1Ce05d1434d484E9A47283aA925fc8A8699a",
                 "Miden": "0xd17976f0809a8191412f2a126625df"
             },
             "decimals": 18,
@@ -95,7 +97,8 @@
                 "Base": "0xc04d2869665Be874881133943523723Be5782720",
                 "Mainnet": "0xc04d2869665Be874881133943523723Be5782720",
                 "Miden": "0x6500ca8c2dd69e9147ab7eafad162c",
-                "Optimism": "0xc04d2869665Be874881133943523723Be5782720"
+                "Optimism": "0xc04d2869665Be874881133943523723Be5782720",
+                "Robinhood": "0xc04d2869665Be874881133943523723Be5782720"
             },
             "decimals": 18,
             "decimalsByChain": {
@@ -107,6 +110,7 @@
                 "Base": "0x7946dd86eE310D0aC16804A37787289Fa5b88A8A",
                 "Mainnet": "0x7946dd86eE310D0aC16804A37787289Fa5b88A8A",
                 "Optimism": "0x7946dd86eE310D0aC16804A37787289Fa5b88A8A",
+                "Robinhood": "0x7946dd86eE310D0aC16804A37787289Fa5b88A8A",
                 "Miden": "0x4a09f13153d9cd114c078bfb62a7ec"
             },
             "decimals": 18,
@@ -119,6 +123,7 @@
                 "Base": "0x9b2a2754a9182fD65360E23afCDf3BeFF51796E9",
                 "Mainnet": "0x9b2a2754a9182fD65360E23afCDf3BeFF51796E9",
                 "Optimism": "0x9b2a2754a9182fD65360E23afCDf3BeFF51796E9",
+                "Robinhood": "0x9b2a2754a9182fD65360E23afCDf3BeFF51796E9",
                 "Miden": "0x5fd2e6fd17712c51404d09c2b847f7"
             },
             "decimals": 18,
@@ -130,7 +135,8 @@
             "contractAddress": {
                 "Base": "0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C",
                 "Mainnet": "0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C",
-                "Optimism": "0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C"
+                "Optimism": "0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C",
+                "Robinhood": "0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C"
             },
             "decimals": 18
         },
@@ -138,7 +144,8 @@
             "contractAddress": {
                 "Base": "0xB588418c0f90F07Bc9587d0050845a90C23C7502",
                 "Mainnet": "0xB588418c0f90F07Bc9587d0050845a90C23C7502",
-                "Optimism": "0xB588418c0f90F07Bc9587d0050845a90C23C7502"
+                "Optimism": "0xB588418c0f90F07Bc9587d0050845a90C23C7502",
+                "Robinhood": "0xB588418c0f90F07Bc9587d0050845a90C23C7502"
             },
             "decimals": 18
         },
@@ -146,7 +153,8 @@
             "contractAddress": {
                 "Base": "0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD",
                 "Mainnet": "0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD",
-                "Optimism": "0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD"
+                "Optimism": "0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD",
+                "Robinhood": "0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD"
             },
             "decimals": 18
         },
@@ -154,7 +162,8 @@
             "contractAddress": {
                 "Base": "0x145e03A80c19ad1b9d0429d06b6d52707de724A0",
                 "Mainnet": "0x145e03A80c19ad1b9d0429d06b6d52707de724A0",
-                "Optimism": "0x145e03A80c19ad1b9d0429d06b6d52707de724A0"
+                "Optimism": "0x145e03A80c19ad1b9d0429d06b6d52707de724A0",
+                "Robinhood": "0x145e03A80c19ad1b9d0429d06b6d52707de724A0"
             },
             "decimals": 18
         }
@@ -175,6 +184,10 @@
         "Optimism": {
             "chainId": 11155420,
             "explorer": "https://sepolia-optimistic.etherscan.io/"
+        },
+        "Robinhood": {
+            "chainId": 46630,
+            "explorer": "https://explorer.testnet.chain.robinhood.com"
         }
     },
     "relationships": {
@@ -338,15 +351,15 @@
             }
         },
         "tokenChains": {
-            "DAI": ["Base", "Mainnet", "Optimism"],
-            "USDT": ["Base", "Mainnet", "Optimism"],
-            "USDC": ["Base", "Optimism", "Mainnet", "Miden"],
-            "WETH": ["Base", "Mainnet", "Optimism"],
-            "WBTC": ["Base", "Mainnet", "Optimism"],
-            "PENGU": ["Base", "Mainnet", "Optimism"],
-            "OSWALD": ["Base", "Mainnet", "Optimism"],
-            "KICK": ["Base", "Mainnet", "Optimism"],
-            "FERB": ["Base", "Mainnet", "Optimism"]
+            "DAI": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "USDT": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "USDC": ["Base", "Optimism", "Mainnet", "Miden", "Robinhood"],
+            "WETH": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "WBTC": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "PENGU": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "OSWALD": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "KICK": ["Base", "Mainnet", "Optimism", "Robinhood"],
+            "FERB": ["Base", "Mainnet", "Optimism", "Robinhood"]
         }
     }
 }

package/dist/data/index.d.ts

@@ -1,3 +1,3 @@
-import mainnetGraph from "./epochgraphmainnet.json";
-import testnetGraph from "./epochgraphtestnet.json";
-export { mainnetGraph, testnetGraph };
+import type { Graph } from "../types/index.js";
+export declare const mainnetGraph: Graph;
+export declare const testnetGraph: Graph;

package/dist/data/index.js

@@ -1,3 +1,5 @@
-import mainnetGraph from "./epochgraphmainnet.json" with { type: "json" };
-import testnetGraph from "./epochgraphtestnet.json" with { type: "json" };
-export { mainnetGraph, testnetGraph };
+import mainnetGraphData from "./epochgraphmainnet.json" with { type: "json" };
+import testnetGraphData from "./epochgraphtestnet.json" with { type: "json" };
+// Keep public graph exports compatible with graph utilities and consumers.
+export const mainnetGraph = mainnetGraphData;
+export const testnetGraph = testnetGraphData;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 import { ethers } from "ethers";
 import { Address, WalletClient } from "viem";
+export type { DexPoolPreference, UniswapV3PoolPreference, UniswapV4PoolKey, UniswapV4PoolPreference, } from "../utils/dex-pools.js";
 export type ApiResponse<T> = {
     data: T;
     status: number;
@@ -110,8 +111,14 @@ export type Token = {
 export type Chain = {
     chainId: number;
     explorer: string;
+    nativeCurrency?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
 };
 export type Relationships = {
+    tokenChains?: Record<string, string[]>;
     protocolTokensByChain: {
         [protocolName: string]: {
             [chainName: string]: {
@@ -183,6 +190,8 @@ export type PathItem = {
     };
     calldata?: CalldataReturnInterface;
     fillerData?: FillerTokenData;
+    /** Client-side execution metadata retained when quote-only paths strip calldata. */
+    externalExecution?: ExternalExecutionPlan;
 };
 export type Path = PathItem[][][];
 export interface QuoteReturnInterface {
@@ -205,6 +214,21 @@ export type ExecutionTransaction = {
     value: string;
     callData: string;
 };
+/** LI.FI's source bridge may be followed by an SDK-refreshed destination v4 swap. */
+export type LifiExternalExecutionPlan = {
+    provider: "lifi";
+    sourceChainId: number;
+    externalSolverUrl: string;
+    sourceTransactions: ExecutionTransaction[];
+    submitTransactionIndex: number;
+    requiresSequentialReceipts: true;
+    lifi: {
+        destinationChainId: number;
+        bridgeToken: string;
+    };
+    destinationSwap?: Record<string, unknown>;
+};
+export type ExternalExecutionPlan = LifiExternalExecutionPlan;
 export type IntermediaryApprovals = {
     tokenAddress: string;
     spenderAddress: string;

package/dist/utils/address.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Chain-aware address handling. Never call `.toLowerCase()` on an address.
+ *
+ * Lowercasing is safe for hex (EVM addresses, Miden faucet ids) and destroys
+ * base58 (Solana), where `A` and `a` are different characters. The failure is
+ * silent — graph lookups still match, because both sides get lowercased — and
+ * only surfaces once the value is used as a real address, by which point a
+ * solver has been told to deliver there.
+ */
+/** Exactly 20-byte `0x` hex — a strict EVM address. */
+export declare function isEvmAddress(value: string): boolean;
+/** Solana's base58 alphabet (no `0`, `O`, `I`, `l`), 32-44 chars = 32-byte pubkey. */
+export declare function isBase58Address(value: string): boolean;
+/** Any identifier the protocol can route: EVM, Miden faucet, or Solana mint. */
+export declare function isTokenIdentifier(value: string): boolean;
+/** Canonical form for lookups and map keys. Hex is lowercased, base58 is not. */
+export declare function normalizeTokenAddress(address: string): string;
+/**
+ * Equality that respects each family's case rules. Replaces
+ * `a.toLowerCase() === b.toLowerCase()`, which returns true for two base58
+ * strings differing only in case — i.e. two different accounts.
+ */
+export declare function sameTokenAddress(a?: string | null, b?: string | null): boolean;

package/dist/utils/address.js

@@ -0,0 +1,39 @@
+/**
+ * Chain-aware address handling. Never call `.toLowerCase()` on an address.
+ *
+ * Lowercasing is safe for hex (EVM addresses, Miden faucet ids) and destroys
+ * base58 (Solana), where `A` and `a` are different characters. The failure is
+ * silent — graph lookups still match, because both sides get lowercased — and
+ * only surfaces once the value is used as a real address, by which point a
+ * solver has been told to deliver there.
+ */
+/** `0x`-prefixed hex of any length: EVM addresses and Miden faucet ids. */
+function isHexIdentifier(value) {
+    return /^0x[a-fA-F0-9]+$/.test(value);
+}
+/** Exactly 20-byte `0x` hex — a strict EVM address. */
+export function isEvmAddress(value) {
+    return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+/** Solana's base58 alphabet (no `0`, `O`, `I`, `l`), 32-44 chars = 32-byte pubkey. */
+export function isBase58Address(value) {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value);
+}
+/** Any identifier the protocol can route: EVM, Miden faucet, or Solana mint. */
+export function isTokenIdentifier(value) {
+    return isHexIdentifier(value) || isBase58Address(value);
+}
+/** Canonical form for lookups and map keys. Hex is lowercased, base58 is not. */
+export function normalizeTokenAddress(address) {
+    return isHexIdentifier(address) ? address.toLowerCase() : address;
+}
+/**
+ * Equality that respects each family's case rules. Replaces
+ * `a.toLowerCase() === b.toLowerCase()`, which returns true for two base58
+ * strings differing only in case — i.e. two different accounts.
+ */
+export function sameTokenAddress(a, b) {
+    if (!a || !b)
+        return false;
+    return normalizeTokenAddress(a) === normalizeTokenAddress(b);
+}

package/dist/utils/chain-kind.d.ts

@@ -0,0 +1,6 @@
+import type { ChainKind, Graph } from "../types/index.js";
+/**
+ * `undefined` for an unknown chain — treat that as unsupported, never as EVM.
+ * Defaulting to EVM is how a Solana mint ends up in `ethers.getAddress()`.
+ */
+export declare function getChainKind(graph: Graph | undefined | null, chainId: number): ChainKind | undefined;

package/dist/utils/chain-kind.js

@@ -0,0 +1,18 @@
+/**
+ * `undefined` when the chain is not in the graph. Tolerates a missing or
+ * malformed graph rather than throwing — several suites stub the graph module
+ * out, and throwing there surfaces as a TypeError far from the cause.
+ */
+function findChainById(graph, chainId) {
+    if (!graph?.chains)
+        return undefined;
+    const entry = Object.entries(graph.chains).find(([, chain]) => chain?.chainId === chainId);
+    return entry ? { name: entry[0], chain: entry[1] } : undefined;
+}
+/**
+ * `undefined` for an unknown chain — treat that as unsupported, never as EVM.
+ * Defaulting to EVM is how a Solana mint ends up in `ethers.getAddress()`.
+ */
+export function getChainKind(graph, chainId) {
+    return findChainById(graph, chainId)?.chain.kind;
+}

package/dist/utils/dex-pools.d.ts

@@ -0,0 +1,24 @@
+import type { Hex } from "viem";
+export declare const DEX_POOLS_EXTRA_TYPESTRING = "string dexPools";
+export declare const MAX_DEX_POOL_PREFERENCES = 16;
+export type UniswapV3PoolPreference = {
+    protocol: "uniswap-v3";
+    chainId: number;
+    address: Hex;
+};
+export type UniswapV4PoolKey = {
+    currency0: Hex;
+    currency1: Hex;
+    fee: number;
+    tickSpacing: number;
+    hooks: Hex;
+};
+export type UniswapV4PoolPreference = {
+    protocol: "uniswap-v4";
+    chainId: number;
+    poolKey: UniswapV4PoolKey;
+    hookData?: Hex;
+};
+export type DexPoolPreference = UniswapV3PoolPreference | UniswapV4PoolPreference;
+export declare function decodeDexPools(value: unknown): DexPoolPreference[];
+export declare function encodeDexPools(pools: readonly DexPoolPreference[]): string;

package/dist/utils/dex-pools.js

@@ -0,0 +1,94 @@
+export const DEX_POOLS_EXTRA_TYPESTRING = "string dexPools";
+export const MAX_DEX_POOL_PREFERENCES = 16;
+const DYNAMIC_FEE_FLAG = 0x800000;
+function invalid(message) {
+    throw new Error(`Invalid dexPools: ${message}`);
+}
+function isHex(value) {
+    return typeof value === "string" && /^0x(?:[0-9a-fA-F]{2})*$/.test(value);
+}
+function address(value, field) {
+    if (typeof value !== "string" ||
+        !/^0x[0-9a-fA-F]{40}$/.test(value) ||
+        /^0x0{40}$/i.test(value)) {
+        return invalid(`${field} must be a non-zero address`);
+    }
+    return value.toLowerCase();
+}
+function integer(value, field, minimum, maximum) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < minimum ||
+        value > maximum) {
+        return invalid(`${field} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+function decodeEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return invalid("each entry must be an object");
+    }
+    const entry = value;
+    const chainId = integer(entry.chainId, "chainId", 1, Number.MAX_SAFE_INTEGER);
+    if (entry.protocol === "uniswap-v3") {
+        return {
+            protocol: "uniswap-v3",
+            chainId,
+            address: address(entry.address, "address"),
+        };
+    }
+    if (entry.protocol !== "uniswap-v4") {
+        return invalid("protocol must be uniswap-v3 or uniswap-v4");
+    }
+    if (!entry.poolKey ||
+        typeof entry.poolKey !== "object" ||
+        Array.isArray(entry.poolKey)) {
+        return invalid("poolKey must be an object");
+    }
+    const key = entry.poolKey;
+    const currency0 = address(key.currency0, "poolKey.currency0");
+    const currency1 = address(key.currency1, "poolKey.currency1");
+    if (currency0 >= currency1) {
+        return invalid("poolKey.currency0 must sort before poolKey.currency1");
+    }
+    const fee = integer(key.fee, "poolKey.fee", 0, 0xffffff);
+    if (fee > 1_000_000 && fee !== DYNAMIC_FEE_FLAG) {
+        return invalid("poolKey.fee is outside the v4 fee range");
+    }
+    const tickSpacing = integer(key.tickSpacing, "poolKey.tickSpacing", 1, 32767);
+    const hooks = address(key.hooks, "poolKey.hooks");
+    const hookData = entry.hookData === undefined ? "0x" : entry.hookData;
+    if (!isHex(hookData))
+        return invalid("hookData must be even-length hex");
+    return {
+        protocol: "uniswap-v4",
+        chainId,
+        poolKey: { currency0, currency1, fee, tickSpacing, hooks },
+        hookData: hookData.toLowerCase(),
+    };
+}
+export function decodeDexPools(value) {
+    if (value === undefined || value === null || value === "")
+        return [];
+    if (typeof value !== "string")
+        return invalid("must be a JSON string");
+    let decoded;
+    try {
+        decoded = JSON.parse(value);
+    }
+    catch {
+        return invalid("must contain valid JSON");
+    }
+    if (!Array.isArray(decoded))
+        return invalid("must contain an array");
+    if (decoded.length > MAX_DEX_POOL_PREFERENCES) {
+        return invalid(`must contain at most ${MAX_DEX_POOL_PREFERENCES} entries`);
+    }
+    return decoded.map(decodeEntry);
+}
+export function encodeDexPools(pools) {
+    if (!Array.isArray(pools))
+        return invalid("must be an array");
+    // Reuse the decoder so encoding and decoding accept precisely the same schema.
+    return JSON.stringify(decodeDexPools(JSON.stringify(pools)));
+}

package/dist/utils/external-provider.d.ts

@@ -0,0 +1,9 @@
+/** Compact witness declaration for selecting an external quote provider. */
+export declare const EXTERNAL_PROVIDER_EXTRA_TYPESTRING = "string provider";
+export declare const EXTERNAL_QUOTE_PROVIDERS: readonly ["khalani", "near", "lifi"];
+export type ExternalQuoteProvider = (typeof EXTERNAL_QUOTE_PROVIDERS)[number];
+/**
+ * Validates an optional signed provider field without normalizing its value.
+ * The exact string is part of the Compact witness and must remain unchanged.
+ */
+export declare function decodeExternalQuoteProvider(value: unknown): ExternalQuoteProvider | undefined;

package/dist/utils/external-provider.js

@@ -0,0 +1,16 @@
+/** Compact witness declaration for selecting an external quote provider. */
+export const EXTERNAL_PROVIDER_EXTRA_TYPESTRING = "string provider";
+export const EXTERNAL_QUOTE_PROVIDERS = ["khalani", "near", "lifi"];
+/**
+ * Validates an optional signed provider field without normalizing its value.
+ * The exact string is part of the Compact witness and must remain unchanged.
+ */
+export function decodeExternalQuoteProvider(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        !EXTERNAL_QUOTE_PROVIDERS.includes(value)) {
+        throw new Error(`Invalid external provider; expected one of ${EXTERNAL_QUOTE_PROVIDERS.join(", ")}`);
+    }
+    return value;
+}

package/dist/utils/graph.d.ts

@@ -0,0 +1,20 @@
+import type { Graph } from "../types/index.js";
+/** Resolve the canonical graph name and metadata from an EVM chain id. */
+export declare function getGraphChain(graph: Graph, chainId: number): {
+    chainId: number;
+    explorer: string;
+    nativeCurrency?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    name: string;
+} | undefined;
+/** Resolve an asset only when its address exists on the requested chain. */
+export declare function getGraphToken(graph: Graph, chainId: number, symbol: string): {
+    symbol: string;
+    address: string;
+    decimals: number;
+} | undefined;
+/** Check graph path eligibility, including wildcard filler protocols. */
+export declare function supportsGraphProtocol(graph: Graph, chainId: number, protocol: string, symbol: string): boolean;

package/dist/utils/graph.js

@@ -0,0 +1,34 @@
+/** Resolve the canonical graph name and metadata from an EVM chain id. */
+export function getGraphChain(graph, chainId) {
+    const entry = Object.entries(graph.chains).find(([, chain]) => chain.chainId === chainId);
+    return entry ? { name: entry[0], ...entry[1] } : undefined;
+}
+/** Resolve an asset only when its address exists on the requested chain. */
+export function getGraphToken(graph, chainId, symbol) {
+    const chain = getGraphChain(graph, chainId);
+    const token = graph.tokens[symbol];
+    const address = chain && token?.contractAddress[chain.name];
+    return address && chain && token
+        ? {
+            symbol,
+            address,
+            decimals: token.decimalsByChain?.[chain.name] ?? token.decimals,
+        }
+        : undefined;
+}
+/** Check graph path eligibility, including wildcard filler protocols. */
+export function supportsGraphProtocol(graph, chainId, protocol, symbol) {
+    const chain = getGraphChain(graph, chainId);
+    if (!chain || !getGraphToken(graph, chainId, symbol))
+        return false;
+    const addresses = graph.protocols[protocol]?.contractAddress;
+    if (!addresses?.[chain.name] && !addresses?.["*"])
+        return false;
+    const relationships = graph.relationships.protocolTokensByChain[protocol];
+    const relation = relationships?.[chain.name] ?? relationships?.["*"];
+    return [
+        relation?.tokensIn,
+        relation?.tokensOut,
+        relation?.tokensInAndOut,
+    ].some((tokens) => tokens?.includes(symbol) || tokens?.includes("*"));
+}

package/dist/utils/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./compact.js";
+export * from "./dex-pools.js";
+export * from "./external-provider.js";
 export * from "./miden-intent.js";
 export * from "./path.js";
 export * from "./witness-typestring.js";
+export * from "./graph.js";

package/dist/utils/index.js

@@ -1,4 +1,7 @@
 export * from "./compact.js";
+export * from "./dex-pools.js";
+export * from "./external-provider.js";
 export * from "./miden-intent.js";
 export * from "./path.js";
 export * from "./witness-typestring.js";
+export * from "./graph.js";

package/dist/utils/intent-route.d.ts

@@ -0,0 +1,19 @@
+/** Origin and destination are resolved independently and returned as a pair. */
+export type IntentOrigin = "evm" | "miden" | "solana";
+export type IntentDestination = "evm" | "miden" | "solana";
+export interface IntentRoute {
+    origin: IntentOrigin;
+    destination: IntentDestination;
+}
+/** Table-dispatch key, e.g. `"miden->solana"`. */
+export type RouteKey = `${IntentOrigin}->${IntentDestination}`;
+export type IntentRouteResult = {
+    valid: true;
+    route: IntentRoute;
+} | {
+    valid: false;
+    error: string;
+};
+export declare function routeKey(route: IntentRoute): RouteKey;
+/** Resolve from witness markers; callers validate chain-ID consistency. */
+export declare function resolveIntentRoute(data?: Record<string, unknown>): IntentRouteResult;

package/dist/utils/intent-route.js

@@ -0,0 +1,84 @@
+import { MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME, MIDEN_SOURCE_ACCOUNT_FIELD_NAME, SOLANA_MINT_FIELD_NAME, SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME, SOLANA_SOURCE_ACCOUNT_FIELD_NAME, SOLANA_SOURCE_MINT_FIELD_NAME, } from "./witness-typestring.js";
+function hasTruthyField(data, fieldName) {
+    if (!data)
+        return false;
+    const value = data[fieldName];
+    return typeof value === "string" && value.trim() !== "";
+}
+export function routeKey(route) {
+    return `${route.origin}->${route.destination}`;
+}
+/** Resolve from witness markers; callers validate chain-ID consistency. */
+export function resolveIntentRoute(data) {
+    for (const fieldName of [
+        MIDEN_SOURCE_ACCOUNT_FIELD_NAME,
+        MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME,
+        SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME,
+        SOLANA_MINT_FIELD_NAME,
+        SOLANA_SOURCE_ACCOUNT_FIELD_NAME,
+        SOLANA_SOURCE_MINT_FIELD_NAME,
+    ]) {
+        const value = data?.[fieldName];
+        if (value !== undefined &&
+            value !== null &&
+            (typeof value !== "string" || value.trim() === "")) {
+            return {
+                valid: false,
+                error: `Intent route marker "${fieldName}" must be a non-empty string`,
+            };
+        }
+    }
+    const hasMidenSource = hasTruthyField(data, MIDEN_SOURCE_ACCOUNT_FIELD_NAME);
+    const hasMidenRecipient = hasTruthyField(data, MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME);
+    const hasSolanaRecipient = hasTruthyField(data, SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME);
+    const hasSolanaMint = hasTruthyField(data, SOLANA_MINT_FIELD_NAME);
+    const hasSolanaSource = hasTruthyField(data, SOLANA_SOURCE_ACCOUNT_FIELD_NAME);
+    const hasSolanaSourceMint = hasTruthyField(data, SOLANA_SOURCE_MINT_FIELD_NAME);
+    if (hasMidenSource && hasMidenRecipient) {
+        return {
+            valid: false,
+            error: "Intent cannot include both midenSourceAccount and midenRecipientAccount",
+        };
+    }
+    if (hasSolanaRecipient !== hasSolanaMint) {
+        return {
+            valid: false,
+            error: "Solana intent must carry both solanaRecipientAccount and solanaMint",
+        };
+    }
+    if (hasSolanaSource !== hasSolanaSourceMint) {
+        return {
+            valid: false,
+            error: "Solana-origin intent must carry both solanaSourceAccount and solanaSourceMint",
+        };
+    }
+    if (hasMidenSource && hasSolanaSource) {
+        return {
+            valid: false,
+            error: "Intent declares two origins (midenSourceAccount and solanaSourceAccount)",
+        };
+    }
+    if (hasSolanaSource && hasSolanaRecipient) {
+        return {
+            valid: false,
+            error: "Solana→Solana intents are not supported",
+        };
+    }
+    if (hasMidenRecipient && hasSolanaRecipient) {
+        return {
+            valid: false,
+            error: "Intent declares two destinations (midenRecipientAccount and solanaRecipientAccount)",
+        };
+    }
+    const origin = hasMidenSource
+        ? "miden"
+        : hasSolanaSource
+            ? "solana"
+            : "evm";
+    const destination = hasSolanaRecipient
+        ? "solana"
+        : hasMidenRecipient
+            ? "miden"
+            : "evm";
+    return { valid: true, route: { origin, destination } };
+}

package/dist/utils/solana-intent.d.ts

@@ -0,0 +1,31 @@
+import { EVM_TO_SOLANA_EXTRA_TYPESTRING, EVM_TO_SOLANA_FIELD_NAMES, SOLANA_MARKER_FIELD_NAMES, SOLANA_TO_EVM_EXTRA_TYPESTRING } from "./witness-typestring.js";
+/** Detect Solana markers by exact field name in typestrings or mandate data. */
+export interface SolanaExtraData {
+    /** Base58 account that receives the payout. Case-significant. */
+    solanaRecipientAccount?: string;
+    /** Base58 SPL mint being delivered. Case-significant. */
+    solanaMint?: string;
+}
+/** Solana-origin collateral: where the escrow deposit came from. */
+export interface SolanaSourceData {
+    /** Base58 account that opened the escrow. Seeds its PDA. Case-significant. */
+    solanaSourceAccount: string;
+    /** Base58 SPL mint locked in the escrow. Case-significant. */
+    solanaSourceMint: string;
+    /** Nonce bound into the escrow PDA, preserved in its input representation. */
+    intentNonce: string | number | bigint;
+}
+/**
+ * True iff the intent is a Solana bridge intent.
+ * At least one of `typestring` or `data` must be provided.
+ */
+export declare function isSolanaIntent(typestring?: string, data?: Record<string, unknown>): boolean;
+/** True when both Solana destination identifiers are present. */
+export declare function isEVMToSolanaIntent(data?: Record<string, unknown>): boolean;
+/** True when both Solana source identifiers are present. */
+export declare function isSolanaToEVMIntent(data?: Record<string, unknown>): boolean;
+/** Extract complete Solana source metadata or return `null`. */
+export declare function getSolanaSourceMetadata(data?: Record<string, unknown>): SolanaSourceData | null;
+/** Extract Solana identifiers, or `null` when this is not a Solana intent. */
+export declare function getSolanaMetadata(data?: Record<string, unknown>, typestring?: string): SolanaExtraData | null;
+export { EVM_TO_SOLANA_EXTRA_TYPESTRING, EVM_TO_SOLANA_FIELD_NAMES, SOLANA_MARKER_FIELD_NAMES, SOLANA_TO_EVM_EXTRA_TYPESTRING, };

package/dist/utils/solana-intent.js

@@ -0,0 +1,75 @@
+import { EVM_TO_SOLANA_EXTRA_TYPESTRING, EVM_TO_SOLANA_FIELD_NAMES, SOLANA_MARKER_FIELD_NAMES, SOLANA_MINT_FIELD_NAME, SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME, SOLANA_SOURCE_ACCOUNT_FIELD_NAME, SOLANA_SOURCE_MINT_FIELD_NAME, SOLANA_SOURCE_NONCE_FIELD_NAME, SOLANA_TO_EVM_EXTRA_TYPESTRING, fieldNamesFromExtraTypestring, } from "./witness-typestring.js";
+import { isUint256Value } from "./value-validation.js";
+function hasTruthyField(data, fieldName) {
+    if (!data)
+        return false;
+    const value = data[fieldName];
+    return typeof value === "string" && value.trim() !== "";
+}
+/** True when a typestring DECLARES a field with exactly this name. */
+function declaresField(typestring, fieldName) {
+    if (!typestring.trim())
+        return false;
+    try {
+        return fieldNamesFromExtraTypestring(typestring).includes(fieldName);
+    }
+    catch {
+        // Malformed typestring declares nothing. The caller's own typestring
+        // validation is responsible for rejecting it.
+        return false;
+    }
+}
+/** True when mandate/extra data carries any Solana bridge marker field. */
+function hasSolanaMarkersInData(data) {
+    return SOLANA_MARKER_FIELD_NAMES.some((name) => hasTruthyField(data, name));
+}
+/** True when a witness/extra typestring declares any Solana bridge marker field. */
+function hasSolanaMarkersInTypestring(typestring) {
+    return SOLANA_MARKER_FIELD_NAMES.some((name) => declaresField(typestring, name));
+}
+/**
+ * True iff the intent is a Solana bridge intent.
+ * At least one of `typestring` or `data` must be provided.
+ */
+export function isSolanaIntent(typestring, data) {
+    const hasTypestring = typestring !== undefined && typestring.trim() !== "";
+    const hasData = data !== undefined;
+    if (!hasTypestring && !hasData) {
+        throw new Error("isSolanaIntent requires typestring and/or data");
+    }
+    return ((hasTypestring && hasSolanaMarkersInTypestring(typestring)) ||
+        hasSolanaMarkersInData(data));
+}
+/** True when both Solana destination identifiers are present. */
+export function isEVMToSolanaIntent(data) {
+    return (hasTruthyField(data, SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME) &&
+        hasTruthyField(data, SOLANA_MINT_FIELD_NAME));
+}
+/** True when both Solana source identifiers are present. */
+export function isSolanaToEVMIntent(data) {
+    return (hasTruthyField(data, SOLANA_SOURCE_ACCOUNT_FIELD_NAME) &&
+        hasTruthyField(data, SOLANA_SOURCE_MINT_FIELD_NAME));
+}
+/** Extract complete Solana source metadata or return `null`. */
+export function getSolanaSourceMetadata(data) {
+    if (!isSolanaToEVMIntent(data))
+        return null;
+    const intentNonce = data?.[SOLANA_SOURCE_NONCE_FIELD_NAME];
+    if (!isUint256Value(intentNonce))
+        return null;
+    return {
+        solanaSourceAccount: data[SOLANA_SOURCE_ACCOUNT_FIELD_NAME],
+        solanaSourceMint: data[SOLANA_SOURCE_MINT_FIELD_NAME],
+        intentNonce: intentNonce,
+    };
+}
+/** Extract Solana identifiers, or `null` when this is not a Solana intent. */
+export function getSolanaMetadata(data, typestring) {
+    if (!data || !isSolanaIntent(typestring, data))
+        return null;
+    return {
+        solanaRecipientAccount: data[SOLANA_RECIPIENT_ACCOUNT_FIELD_NAME],
+        solanaMint: data[SOLANA_MINT_FIELD_NAME],
+    };
+}
+export { EVM_TO_SOLANA_EXTRA_TYPESTRING, EVM_TO_SOLANA_FIELD_NAMES, SOLANA_MARKER_FIELD_NAMES, SOLANA_TO_EVM_EXTRA_TYPESTRING, };

package/dist/utils/value-validation.d.ts

@@ -0,0 +1 @@
+export declare function isUint256Value(value: unknown): value is string | number | bigint;

package/dist/utils/value-validation.js

@@ -0,0 +1,18 @@
+export function isUint256Value(value) {
+    if (typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "bigint") {
+        return false;
+    }
+    if (typeof value === "string" && value.trim() === "")
+        return false;
+    if (typeof value === "number" && !Number.isSafeInteger(value))
+        return false;
+    try {
+        const parsed = BigInt(value);
+        return parsed >= 0n && parsed < 1n << 256n;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-protocol/epoch-commons-sdk",
-  "version": "0.1.20",
+  "version": "0.2.0",
   "description": "SDK for interacting with Epoch Commons Protocol",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,9 @@
   ],
   "author": "",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "ethers": "^6.0.0",
     "viem": "2.42.0"