@droplinked_inc/web3-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @droplinked_inc/web3-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- 562318e: Initial rebuild from `droplinked-web3-kit`. Hostile-namespace replacement under the supply-chain rebuild sprint.
+
+### Patch Changes
+
+- Updated dependencies [562318e]
+  - @droplinked_inc/wallet-connection@0.1.1
+
+Managed by [Changesets](https://github.com/changesets/changesets) — entries
+added via `pnpm changeset` are accumulated here on each `pnpm version`.
+
+## Unreleased
+
+- Initial rebuild from `droplinked-web3-kit@1.0.13`. See
+  [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the security delta.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Droplinked Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @droplinked_inc/web3-kit
+
+Higher-level web3 building blocks for the Droplinked frontend stack: a
+frozen chain registry, a hard-coded known-token registry, decimal-safe
+display formatters, and viem-backed transaction builders.
+
+This is a hardened rebuild of the original `droplinked-web3-kit@1.0.13`.
+See [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the security deltas.
+
+## Status
+
+Initial rebuild. Stable surface; coverage 96.81% statements / 96.87% branches.
+
+## Install
+
+```bash
+pnpm add @droplinked_inc/web3-kit @droplinked_inc/wallet-connection
+```
+
+`@droplinked_inc/wallet-connection` is a **peer dependency** — this kit
+does not reimplement EIP-1193 provider discovery, EIP-712 login signing,
+session storage, or wallet-protocol logic. Those primitives live in
+`@droplinked_inc/wallet-connection`.
+
+## Modules
+
+| Module        | Surface                                                                       |
+| ------------- | ----------------------------------------------------------------------------- |
+| `chains`      | `chains`, `getChainByName`, `getChainDetails`, `isRpcUrlAllowed`, `getTransactionLink` |
+| `tokens`      | `TOKEN_REGISTRY`, `getTokenInfo`, `hasToken`, `listTokens`, `assertCanonicalTokenAddress` |
+| `format`      | `formatAmount`, `parseAmount`, `formatEther`, `parseEther`, `shortenAddress`, `escapeTokenDisplay`, `formatBalance` |
+| `tx-builder`  | `buildErc20Transfer`, `buildErc20Approve`, `buildNativeTransfer`, `buildEip712Domain` |
+| `types`       | `Chains`, `Network`, `Groups`, `PaymentTokens`, zod schemas                    |
+| `errors`      | typed exception hierarchy mirroring v1.0.13                                    |
+
+## Quick examples
+
+### Look up a chain and a token
+
+```ts
+import { Chains, Network, getChainDetails, getTokenInfo } from '@droplinked_inc/web3-kit';
+
+const polygon = getChainDetails(Chains.POLYGON, Network.MAINNET);
+// polygon.chainIdNumber === 137
+
+const usdc = getTokenInfo(Chains.POLYGON, Network.MAINNET, 'USDC');
+// usdc.address === '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
+```
+
+### Reject a spoofed token address
+
+```ts
+import { assertCanonicalTokenAddress, TokenAddressMismatchError } from '@droplinked_inc/web3-kit';
+
+try {
+  assertCanonicalTokenAddress({
+    chain: Chains.POLYGON,
+    network: Network.MAINNET,
+    symbol: 'USDC',
+    claimedAddress: backendResponse.usdcAddress, // attacker-controlled
+  });
+} catch (err) {
+  if (err instanceof TokenAddressMismatchError) {
+    // refuse the checkout — your backend lied about what address USDC has
+  }
+}
+```
+
+### Build an ERC-20 transfer
+
+```ts
+import { buildErc20Transfer, parseAmount } from '@droplinked_inc/web3-kit';
+
+const call = buildErc20Transfer({
+  chain: Chains.POLYGON,
+  network: Network.MAINNET,
+  tokenSymbol: 'USDC',
+  to: recipient,
+  amount: parseAmount('1.5', 6),
+});
+// call.to       === USDC contract on Polygon
+// call.data     === 0x...a9059cbb… (transfer(address,uint256))
+// call.value    === 0n
+// call.chainIdNumber === 137
+```
+
+Then hand `call` to a wallet connector from `@droplinked_inc/wallet-connection`
+to actually broadcast it.
+
+### Format balances safely
+
+```ts
+import { formatBalance, escapeTokenDisplay } from '@droplinked_inc/web3-kit';
+
+formatBalance({ value: 1_999_999n, decimals: 6, displayDecimals: 2 });
+// "1.99"  — truncated, never rounded up. The user can't be shown more than they hold.
+
+escapeTokenDisplay(maliciousTokenName);
+// HTML-escaped, control-char-stripped, bidi-override-stripped, length-capped.
+```
+
+## Security model
+
+See [`THREAT_MODEL.md`](./THREAT_MODEL.md). Highlights:
+
+- The chain registry and the known-token registry are **frozen at package
+  build time**. No remote fetches, no backend-driven addresses.
+- Caller-supplied token addresses for known symbols (USDC, USDT, DAI,
+  WETH, USDS) are **validated against the registry** — passing any other
+  address as e.g. "USDC" throws `TokenAddressMismatchError`.
+- All amounts are `bigint`. `parseAmount` rejects inputs with more
+  fractional digits than the token allows, preventing silent truncation
+  that could let a UI display "1.234 USDC" but submit "1.23 USDC".
+- `escapeTokenDisplay` strips ASCII control chars, Unicode bidi-override
+  chars, and HTML metachars before any on-chain string reaches a UI.
+- RPC URLs passed by callers are validated against the registry via
+  `isRpcUrlAllowed` (https-only, exact host+path match).
+- Transaction-hash inputs to `getTransactionLink` are regex-validated
+  to block `javascript:` open-redirect payloads.
+
+## License
+
+MIT — see [`LICENSE`](../../LICENSE).

package/THREAT_MODEL.md

@@ -0,0 +1,139 @@
+# Threat Model — @droplinked_inc/web3-kit
+
+This document captures the security boundaries and hardening deltas of
+`@droplinked_inc/web3-kit` relative to the legacy `droplinked-web3-kit@1.0.13`
+which it replaces.
+
+Companion document: `@droplinked_inc/wallet-connection`'s `THREAT_MODEL.md`.
+This kit composes on top of that package for wallet-protocol primitives.
+
+## 1. Trust boundaries
+
+| Boundary | Direction | Trust posture |
+| --- | --- | --- |
+| Caller → kit (chain id, network, symbol) | inbound | **untrusted** — zod / registry validated |
+| Caller → kit (token address claim) | inbound | **untrusted** — compared against frozen registry |
+| Caller → kit (RPC URL) | inbound | **untrusted** — `isRpcUrlAllowed` |
+| Caller → kit (amount as string/number) | inbound | **untrusted** — `Uint256Schema`, no truncation |
+| Kit → caller (canonical address, ABI-data) | outbound | **trusted** — sourced from the frozen tables |
+| Kit ↔ network | none | this package never opens a socket |
+
+The kit has **no I/O of its own** — it neither contacts the network
+nor reads `localStorage`. All side effects belong to the consumer.
+
+## 2. Threats addressed
+
+### 2.1 Backend-controlled chain metadata
+The original v1.0.13 fetched chain metadata and contract addresses
+from `apiv3dev.droplinked.com/storage/...` at runtime. Any compromise
+of that endpoint — or a DNS hijack, or a MITM during checkout — could
+redirect every customer payment to an attacker address.
+
+**Mitigation:** chain registry is a frozen, package-baked table
+(`chains.ts`). Adding a new chain is a code-review + npm publish, not
+a backend mutation. Unknown chain identifiers throw
+`ChainNotImplementedException`.
+
+### 2.2 Token-address impersonation ("look-alike USDC drainer")
+A malicious backend / cart payload says "the user is paying in USDC,
+the USDC contract address is `0xDEAD…`". The wallet signs an ERC-20
+transfer to that address — funds drained.
+
+**Mitigation:** known token contracts (USDC, USDT, USDS, DAI, WETH)
+are hard-coded per (chain, network) in `tokens.ts`.
+`assertCanonicalTokenAddress` rejects any caller-supplied address that
+does not match the registry value (case-insensitive). The check runs
+inside every `tx-builder` entry point — there is no way to construct
+an ERC-20 transfer to a non-canonical address for a known symbol.
+
+### 2.3 Display-string XSS / homoglyph spoofing
+v1.0.13 returned raw on-chain `name` / `symbol` strings. A malicious
+ERC-20 with `name = "<img src=x onerror=alert(1)>"` would crash or
+hijack any consumer using `dangerouslySetInnerHTML`. RLO-flipped
+"USDC" (i.e. "U‮CDSU") could spoof the legit token in a list.
+
+**Mitigation:** `escapeTokenDisplay` strips ASCII control chars
+(0x00–0x1F + 0x7F) by replacing them with spaces, strips Unicode
+bidi-override / invisible chars (RLM, LRM, LRE-RLO, LRI-FSI-PDI, BOM),
+collapses whitespace, HTML-escapes `&<>"'/\`=` for both element-body
+and unquoted-attribute contexts, and truncates at 64 characters.
+Property-test asserts the output never contains a raw `<` or `>`.
+
+### 2.4 Silent decimal truncation
+A UI shows the user "1.23456 USDC" but submits "1.23 USDC" on-chain
+because `parseFloat → toFixed(decimals)` rounded down.
+
+**Mitigation:** `parseAmount` rejects inputs whose fractional part is
+longer than `decimals`. There is no rounding in the parse path at all
+— either the amount is representable exactly, or you get a
+`RangeError`.
+
+### 2.5 Wrong-chain submission via user-controlled chainId
+A consumer that builds typed-data with `domain.chainId = req.body.chainId`
+can be tricked into signing a cross-chain replayable payload.
+
+**Mitigation:** `buildEip712Domain` derives `chainId` from the (chain,
+network) pair, looked up in the frozen registry. Callers cannot
+inject a chainId. The same applies to every `tx-builder` helper:
+`chainIdNumber` is on the returned `BuiltCall` and is always the
+registry value.
+
+### 2.6 Open-redirect via transaction-hash field
+`getTransactionLink` was previously string-concat — a caller passing
+`javascript:alert(1)` as `transactionHash` would produce a malicious
+href.
+
+**Mitigation:** transaction hashes must match `/^0x[a-fA-F0-9]{64}$/`.
+Anything else throws `InvalidParametersException`.
+
+### 2.7 SSRF via attacker-controlled RPC URL
+A consumer that takes an RPC URL from URL params and uses it to add a
+chain to MetaMask lets the attacker pin the user to a malicious RPC
+(seeing every signed tx pre-broadcast, faking balances, censoring).
+
+**Mitigation:** `isRpcUrlAllowed` requires `https:`, exact host match,
+exact pathname match against the frozen registry. The check is
+provided as a public helper; consumers should always gate user-typed
+RPC URLs through it.
+
+### 2.8 Mutation of the registry post-import
+A previously-imported registry object could in principle be mutated
+by some other module loaded later in the bundle.
+
+**Mitigation:** every registry table is `Object.freeze`d at module
+load time. Mutation throws in strict mode (which the package builds
+under). Frozen-ness is asserted in unit tests.
+
+## 3. Threats not addressed (out of scope)
+
+- **Off-chain price oracle manipulation.** Token-USD conversions are
+  the consumer's responsibility; this kit only emits raw `bigint`
+  amounts.
+- **Wallet-protocol issues** (EIP-1193 race conditions, account
+  switching). Owned by `@droplinked_inc/wallet-connection`.
+- **Solana / XION / Unstoppable Domains tokens.** Only EVM tokens are
+  in the canonical registry today. Solana SPL token verification is
+  planned for a follow-up.
+- **ENS / homoglyph attacks on resolved names.** `shortenAddress`
+  only accepts raw 20-byte hex; ENS-resolved labels remain the UI's
+  responsibility.
+
+## 4. Cryptographic dependencies
+
+- `viem@^2.21` — ABI encoding and `formatUnits`/`parseUnits`. Pure
+  JS, no native dependencies.
+- `zod@^3.23` — schema validation. No regex back-references; all
+  patterns are linear-time.
+
+No `ethers`, no `web3.js` — both were direct dependencies of v1.0.13
+and brought a much larger attack surface (custom keccak / RLP /
+secp256k1 reimplementations).
+
+## 5. Coverage gates
+
+- statements 96.8%
+- branches 96.9%
+- functions 100%
+- lines 99.1%
+
+A drop below 85% on any axis fails CI.

package/dist/chains.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Hard-coded chain registry.
+ *
+ * The original droplinked-web3-kit@1.0.13 fetched chain metadata and
+ * contract addresses from `apiv3dev.droplinked.com/storage/...` at
+ * runtime. Any compromise of that endpoint — or a DNS hijack, or a
+ * MITM during the customer's checkout — could redirect every payment
+ * to an attacker-controlled address. We replace this with a frozen,
+ * package-baked registry. Adding a new chain is a code-review + npm
+ * publish, not a backend mutation.
+ *
+ * Caller-supplied chain identifiers are validated against this table
+ * via `getChainByName` / `requireChain`; unknown values throw
+ * `ChainNotImplementedException` rather than being silently passed
+ * through.
+ */
+import { Chains, Groups, Network } from './types.js';
+export interface ChainNativeCurrency {
+    readonly name: string;
+    readonly decimals: number;
+    readonly symbol: string;
+}
+export interface ChainDetails {
+    readonly chainName: string;
+    /** 0x-prefixed hex chain id, e.g. "0x89". */
+    readonly chainIdHex: `0x${string}`;
+    /** Decimal chain id for EIP-712 / viem. */
+    readonly chainIdNumber: number;
+    readonly nativeCurrency: ChainNativeCurrency;
+    /** Hard-coded vetted public RPCs. Validated by `isRpcUrlAllowed`. */
+    readonly rpcUrls: readonly string[];
+    /** Canonical block-explorer base (no trailing slash). */
+    readonly blockExplorerUrl: string;
+}
+export interface Chain {
+    readonly name: Chains;
+    readonly group: Groups;
+    readonly [Network.TESTNET]?: ChainDetails;
+    readonly [Network.MAINNET]?: ChainDetails;
+}
+/**
+ * Snapshot of the registry as an array — matches the v1.0.13 `chains`
+ * named export so consumers iterating over it keep working.
+ */
+export declare const chains: readonly Chain[];
+export declare function getChainByName(chainName: Chains): Chain;
+export declare function getGroupOfChain(chainName: Chains): Groups;
+export declare function isChainInGroup(chainName: Chains, group: Groups): boolean;
+export declare function getChainsByGroup(group: Groups): readonly Chain[];
+export declare function getChainDetails(chain: Chains, network: Network): ChainDetails;
+/**
+ * Validates that the caller-supplied RPC URL appears in the registry
+ * for the (chain, network) pair. Used by anything that issues a JSON-RPC
+ * request — never trust a user-supplied RPC URL.
+ */
+export declare function isRpcUrlAllowed(chain: Chains, network: Network, rpcUrl: string): boolean;
+/**
+ * Builds a block-explorer URL for a transaction hash. The hash is
+ * regex-validated to defend against `javascript:` / open-redirect
+ * payloads sneaking into a UI that renders the result as a link.
+ */
+export declare function getTransactionLink(args: {
+    chain: Chains;
+    network: Network;
+    transactionHash: string;
+}): string;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAIrD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,KAAK,MAAM,EAAE,CAAC;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,yDAAyD;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC;IAC1C,QAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC;CAC3C;AAwND;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EAA4C,CAAC;AAEhF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAMvD;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,EAAE,CAEhE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAO7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAsBT;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAST"}

package/dist/chains.js

@@ -0,0 +1,302 @@
+/**
+ * Hard-coded chain registry.
+ *
+ * The original droplinked-web3-kit@1.0.13 fetched chain metadata and
+ * contract addresses from `apiv3dev.droplinked.com/storage/...` at
+ * runtime. Any compromise of that endpoint — or a DNS hijack, or a
+ * MITM during the customer's checkout — could redirect every payment
+ * to an attacker-controlled address. We replace this with a frozen,
+ * package-baked registry. Adding a new chain is a code-review + npm
+ * publish, not a backend mutation.
+ *
+ * Caller-supplied chain identifiers are validated against this table
+ * via `getChainByName` / `requireChain`; unknown values throw
+ * `ChainNotImplementedException` rather than being silently passed
+ * through.
+ */
+import { Chains, Groups, Network } from './types.js';
+import { ChainNotImplementedException, InvalidParametersException } from './errors.js';
+import { deepFreeze } from './deep-freeze.js';
+/**
+ * The canonical registry. All values are `readonly` deeply — mutating
+ * an entry in a consumer would be a TypeScript error and at runtime
+ * the object is frozen via `Object.freeze` on import.
+ */
+const CHAINS_TABLE = deepFreeze({
+    [Chains.ETH]: {
+        name: Chains.ETH,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Ethereum',
+            chainIdHex: '0x1',
+            chainIdNumber: 1,
+            nativeCurrency: { name: 'Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://eth.llamarpc.com'],
+            blockExplorerUrl: 'https://etherscan.io',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Sepolia',
+            chainIdHex: '0xaa36a7',
+            chainIdNumber: 11155111,
+            nativeCurrency: { name: 'Sepolia Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://eth-sepolia.public.blastapi.io/'],
+            blockExplorerUrl: 'https://sepolia.etherscan.io',
+        },
+    },
+    [Chains.POLYGON]: {
+        name: Chains.POLYGON,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Polygon Mainnet',
+            chainIdHex: '0x89',
+            chainIdNumber: 137,
+            nativeCurrency: { name: 'MATIC', decimals: 18, symbol: 'MATIC' },
+            rpcUrls: ['https://polygon-rpc.com/'],
+            blockExplorerUrl: 'https://polygonscan.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Polygon Amoy',
+            chainIdHex: '0x13882',
+            chainIdNumber: 80002,
+            nativeCurrency: { name: 'MATIC', decimals: 18, symbol: 'MATIC' },
+            rpcUrls: ['https://rpc-amoy.polygon.technology'],
+            blockExplorerUrl: 'https://amoy.polygonscan.com',
+        },
+    },
+    [Chains.BINANCE]: {
+        name: Chains.BINANCE,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'BNB Smart Chain',
+            chainIdHex: '0x38',
+            chainIdNumber: 56,
+            nativeCurrency: { name: 'BNB', decimals: 18, symbol: 'BNB' },
+            rpcUrls: ['https://bsc-dataseed.binance.org/'],
+            blockExplorerUrl: 'https://bscscan.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'BNB Smart Chain Testnet',
+            chainIdHex: '0x61',
+            chainIdNumber: 97,
+            nativeCurrency: { name: 'tBNB', decimals: 18, symbol: 'BNB' },
+            rpcUrls: ['https://data-seed-prebsc-1-s1.binance.org:8545/'],
+            blockExplorerUrl: 'https://testnet.bscscan.com',
+        },
+    },
+    [Chains.BASE]: {
+        name: Chains.BASE,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Base',
+            chainIdHex: '0x2105',
+            chainIdNumber: 8453,
+            nativeCurrency: { name: 'Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://mainnet.base.org/'],
+            blockExplorerUrl: 'https://basescan.org',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Base Sepolia',
+            chainIdHex: '0x14a34',
+            chainIdNumber: 84532,
+            nativeCurrency: { name: 'Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://sepolia.base.org'],
+            blockExplorerUrl: 'https://sepolia.basescan.org',
+        },
+    },
+    [Chains.LINEA]: {
+        name: Chains.LINEA,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Linea',
+            chainIdHex: '0xe708',
+            chainIdNumber: 59144,
+            nativeCurrency: { name: 'Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://rpc.linea.build'],
+            blockExplorerUrl: 'https://lineascan.build',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Linea Sepolia',
+            chainIdHex: '0xe705',
+            chainIdNumber: 59141,
+            nativeCurrency: { name: 'Ether', decimals: 18, symbol: 'ETH' },
+            rpcUrls: ['https://rpc.sepolia.linea.build'],
+            blockExplorerUrl: 'https://sepolia.lineascan.build',
+        },
+    },
+    [Chains.SKALE]: {
+        name: Chains.SKALE,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'SKALE Europa',
+            chainIdHex: '0x79f99296',
+            chainIdNumber: 2046399126,
+            nativeCurrency: { name: 'sFUEL', decimals: 18, symbol: 'sFUEL' },
+            rpcUrls: ['https://mainnet.skalenodes.com/v1/elated-tan-skat'],
+            blockExplorerUrl: 'https://elated-tan-skat.explorer.mainnet.skalenodes.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'SKALE Calypso Testnet',
+            chainIdHex: '0x3a14269b',
+            chainIdNumber: 974399131,
+            nativeCurrency: { name: 'sFUEL', decimals: 18, symbol: 'sFUEL' },
+            rpcUrls: ['https://testnet.skalenodes.com/v1/giant-half-dual-testnet'],
+            blockExplorerUrl: 'https://giant-half-dual-testnet.explorer.testnet.skalenodes.com',
+        },
+    },
+    [Chains.REDBELLY]: {
+        name: Chains.REDBELLY,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Redbelly Network Mainnet',
+            chainIdHex: '0x97',
+            chainIdNumber: 151,
+            nativeCurrency: { name: 'RBNT', decimals: 18, symbol: 'RBNT' },
+            rpcUrls: ['https://governors.mainnet.redbelly.network'],
+            blockExplorerUrl: 'https://redbelly.routescan.io',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Redbelly Network Testnet',
+            chainIdHex: '0x99',
+            chainIdNumber: 153,
+            nativeCurrency: { name: 'RBNT', decimals: 18, symbol: 'RBNT' },
+            rpcUrls: ['https://governors.testnet.redbelly.network'],
+            blockExplorerUrl: 'https://explorer.testnet.redbelly.network',
+        },
+    },
+    [Chains.BITLAYER]: {
+        name: Chains.BITLAYER,
+        group: Groups.EVM,
+        [Network.MAINNET]: {
+            chainName: 'Bitlayer',
+            chainIdHex: '0xc4',
+            chainIdNumber: 200901,
+            nativeCurrency: { name: 'Bitcoin', decimals: 18, symbol: 'BTC' },
+            rpcUrls: ['https://rpc.bitlayer.org'],
+            blockExplorerUrl: 'https://www.btrscan.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Bitlayer Testnet',
+            chainIdHex: '0xc5',
+            chainIdNumber: 200810,
+            nativeCurrency: { name: 'Bitcoin', decimals: 18, symbol: 'BTC' },
+            rpcUrls: ['https://testnet-rpc.bitlayer.org'],
+            blockExplorerUrl: 'https://testnet.btrscan.com',
+        },
+    },
+    [Chains.SOLANA]: {
+        name: Chains.SOLANA,
+        group: Groups.SOL,
+        [Network.MAINNET]: {
+            chainName: 'Solana',
+            chainIdHex: '0x65',
+            chainIdNumber: 101,
+            nativeCurrency: { name: 'Solana', decimals: 9, symbol: 'SOL' },
+            rpcUrls: ['https://api.mainnet-beta.solana.com'],
+            blockExplorerUrl: 'https://explorer.solana.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'Solana Devnet',
+            chainIdHex: '0x67',
+            chainIdNumber: 103,
+            nativeCurrency: { name: 'Solana', decimals: 9, symbol: 'SOL' },
+            rpcUrls: ['https://api.devnet.solana.com'],
+            blockExplorerUrl: 'https://explorer.solana.com?cluster=devnet',
+        },
+    },
+    [Chains.XION]: {
+        name: Chains.XION,
+        group: Groups.XION,
+        [Network.MAINNET]: {
+            chainName: 'XION',
+            chainIdHex: '0x0',
+            chainIdNumber: 0,
+            nativeCurrency: { name: 'XION', decimals: 6, symbol: 'XION' },
+            rpcUrls: ['https://rpc.xion-mainnet-1.burnt.com'],
+            blockExplorerUrl: 'https://explorer.burnt.com',
+        },
+        [Network.TESTNET]: {
+            chainName: 'XION Testnet',
+            chainIdHex: '0x0',
+            chainIdNumber: 0,
+            nativeCurrency: { name: 'XION', decimals: 6, symbol: 'XION' },
+            rpcUrls: ['https://rpc.xion-testnet-2.burnt.com'],
+            blockExplorerUrl: 'https://explorer.burnt.com/xion-testnet-2',
+        },
+    },
+    [Chains.UNSTOPPABLE]: {
+        name: Chains.UNSTOPPABLE,
+        group: Groups.UD,
+        // Unstoppable Domains is an identity/SSO layer, not an EVM chain.
+        // No network metadata.
+    },
+});
+/**
+ * Snapshot of the registry as an array — matches the v1.0.13 `chains`
+ * named export so consumers iterating over it keep working.
+ */
+export const chains = deepFreeze(Object.values(CHAINS_TABLE));
+export function getChainByName(chainName) {
+    const entry = CHAINS_TABLE[chainName];
+    if (!entry) {
+        throw new ChainNotImplementedException(chainName);
+    }
+    return entry;
+}
+export function getGroupOfChain(chainName) {
+    return getChainByName(chainName).group;
+}
+export function isChainInGroup(chainName, group) {
+    return getChainByName(chainName).group === group;
+}
+export function getChainsByGroup(group) {
+    return chains.filter((c) => c.group === group);
+}
+export function getChainDetails(chain, network) {
+    const entry = getChainByName(chain);
+    const details = entry[network];
+    if (!details) {
+        throw new ChainNotImplementedException(chain);
+    }
+    return details;
+}
+/**
+ * Validates that the caller-supplied RPC URL appears in the registry
+ * for the (chain, network) pair. Used by anything that issues a JSON-RPC
+ * request — never trust a user-supplied RPC URL.
+ */
+export function isRpcUrlAllowed(chain, network, rpcUrl) {
+    try {
+        const parsed = new URL(rpcUrl);
+        if (parsed.protocol !== 'https:') {
+            return false;
+        }
+        const details = getChainDetails(chain, network);
+        return details.rpcUrls.some((u) => {
+            try {
+                const allowed = new URL(u);
+                return (allowed.protocol === parsed.protocol &&
+                    allowed.host === parsed.host &&
+                    allowed.pathname === parsed.pathname);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds a block-explorer URL for a transaction hash. The hash is
+ * regex-validated to defend against `javascript:` / open-redirect
+ * payloads sneaking into a UI that renders the result as a link.
+ */
+export function getTransactionLink(args) {
+    if (!/^0x[a-fA-F0-9]{64}$/u.test(args.transactionHash)) {
+        throw new InvalidParametersException(args.chain, 'transactionHash must be 0x-prefixed 32-byte hex');
+    }
+    const details = getChainDetails(args.chain, args.network);
+    return `${details.blockExplorerUrl}/tx/${args.transactionHash}`;
+}
+//# sourceMappingURL=chains.js.map