@faremeter/info 0.16.0 → 0.17.0

package/dist/src/evm.test.js

@@ -2,38 +2,87 @@
 import t from "tap";
 import * as evm from "./evm.js";
 await t.test("basicNetworkLookup", async (t) => {
-    t.ok(evm.isKnownX402Network("base"));
-    t.ok(!evm.isKnownX402Network("asdkljas"));
+    t.ok(evm.isKnownCAIP2Network("eip155:8453"));
+    t.ok(!evm.isKnownCAIP2Network("eip155:999999"));
+    t.ok(!evm.isKnownCAIP2Network("base"));
+    t.end();
+});
+await t.test("networkConversions", async (t) => {
+    await t.test("chainIdToCAIP2", (t) => {
+        t.equal(evm.chainIdToCAIP2(8453), "eip155:8453");
+        t.equal(evm.chainIdToCAIP2(84532), "eip155:84532");
+        t.equal(evm.chainIdToCAIP2(999999), "eip155:999999");
+        t.end();
+    });
+    await t.test("caip2ToChainId", (t) => {
+        t.equal(evm.caip2ToChainId("eip155:8453"), 8453);
+        t.equal(evm.caip2ToChainId("eip155:84532"), 84532);
+        t.equal(evm.caip2ToChainId("invalid"), null);
+        t.equal(evm.caip2ToChainId("eip155:"), null);
+        t.end();
+    });
+    await t.test("legacyNameToCAIP2", (t) => {
+        t.equal(evm.legacyNameToCAIP2("base"), "eip155:8453");
+        t.equal(evm.legacyNameToCAIP2("base-sepolia"), "eip155:84532");
+        t.equal(evm.legacyNameToCAIP2("skale-europa-testnet"), "eip155:1444673419");
+        t.equal(evm.legacyNameToCAIP2("unknown-network"), null);
+        t.end();
+    });
+    await t.test("caip2ToLegacyName", (t) => {
+        t.equal(evm.caip2ToLegacyName("eip155:8453"), "base");
+        t.equal(evm.caip2ToLegacyName("eip155:84532"), "base-sepolia");
+        t.equal(evm.caip2ToLegacyName("eip155:999999"), null);
+        t.end();
+    });
+    await t.test("normalizeNetworkId", (t) => {
+        t.equal(evm.normalizeNetworkId(8453), "eip155:8453");
+        t.equal(evm.normalizeNetworkId("base"), "eip155:8453");
+        t.equal(evm.normalizeNetworkId("base-sepolia"), "eip155:84532");
+        t.equal(evm.normalizeNetworkId("eip155:8453"), "eip155:8453");
+        t.equal(evm.normalizeNetworkId("84532"), "eip155:84532");
+        t.end();
+    });
+    t.end();
 });
 await t.test("basicAssetLookup", async (t) => {
     await t.test((t) => {
-        const info = evm.lookupKnownAsset("base-sepolia", "USDC");
+        const info = evm.lookupKnownAsset("eip155:84532", "USDC");
         if (!info) {
             throw new Error("failed to lookup known EVM asset");
         }
         t.matchOnly(info.address, "0x036cbd53842c5426634e7929541ec2318f3dcf7e");
         t.matchOnly(info.name, "USDC");
-        t.matchOnly(info.network, "base-sepolia");
+        t.matchOnly(info.network, "eip155:84532");
         t.equal(info.forwarder, undefined);
         t.equal(info.forwarderName, undefined);
         t.equal(info.forwarderVersion, undefined);
         t.end();
     });
+    await t.test("lookup by legacy name", (t) => {
+        const info = evm.lookupKnownAsset("base-sepolia", "USDC");
+        if (!info) {
+            throw new Error("failed to lookup known EVM asset by legacy name");
+        }
+        t.matchOnly(info.address, "0x036cbd53842c5426634e7929541ec2318f3dcf7e");
+        t.matchOnly(info.name, "USDC");
+        t.matchOnly(info.network, "eip155:84532");
+        t.end();
+    });
     await t.test((t) => {
-        const info = evm.lookupKnownAsset("skale-europa-testnet", "USDC");
+        const info = evm.lookupKnownAsset("eip155:1444673419", "USDC");
         if (!info) {
             throw new Error("failed to lookup known EVM asset");
         }
         t.matchOnly(info.address, "0x9eAb55199f4481eCD7659540A17Af618766b07C4");
         t.matchOnly(info.name, "USDC");
-        t.matchOnly(info.network, "skale-europa-testnet");
+        t.matchOnly(info.network, "eip155:1444673419");
         t.matchOnly(info.forwarder, "0x7779B0d1766e6305E5f8081E3C0CDF58FcA24330");
         t.matchOnly(info.forwarderName, "USDC Forwarder");
         t.matchOnly(info.forwarderVersion, "1");
         t.end();
     });
     await t.test((t) => {
-        const info = evm.lookupKnownAsset("alsdkjaklsdj", "asldkjasd");
+        const info = evm.lookupKnownAsset("eip155:999999", "asldkjasd");
         t.matchOnly(info, undefined);
         t.end();
     });
@@ -42,21 +91,21 @@ await t.test("basicAssetLookup", async (t) => {
         t.ok(!evm.isKnownAsset("notarealtoken"));
         t.end();
     });
-    await t.test((t) => {
+    await t.test("lookup by chain ID number", (t) => {
         const info = evm.lookupKnownAsset(84532, "USDC");
         if (!info) {
             throw new Error("failed to lookup known EVM asset");
         }
         t.matchOnly(info.address, "0x036cbd53842c5426634e7929541ec2318f3dcf7e");
         t.matchOnly(info.name, "USDC");
-        t.matchOnly(info.network, "base-sepolia");
+        t.matchOnly(info.network, "eip155:84532");
         t.end();
     });
     t.end();
 });
 await t.test("basicChainLookup", async (t) => {
-    t.matchOnly(evm.lookupX402Network(8453), "base");
-    t.matchOnly(evm.lookupX402Network(84532), "base-sepolia");
+    t.matchOnly(evm.lookupX402Network(8453), "eip155:8453");
+    t.matchOnly(evm.lookupX402Network(84532), "eip155:84532");
     t.matchOnly(evm.lookupX402Network(8675309), "eip155:8675309");
     t.end();
 });

package/dist/src/index.d.ts

@@ -1,3 +1,35 @@
-export * as solana from "./solana.js";
-export * as evm from "./evm.js";
+/**
+ * @title Info Package
+ * @sidebarTitle Info
+ * @description Network and asset information utilities for EVM and Solana chains
+ * @packageDocumentation
+ */
+import * as solana from "./solana.js";
+import * as evm from "./evm.js";
+/**
+ * @title Solana Network Info
+ * @sidebarTitle Info / Solana
+ * @description Solana cluster, network ID, and SPL token utilities
+ */
+export { solana };
+/**
+ * @title EVM Network Info
+ * @sidebarTitle Info / EVM
+ * @description EVM chain ID, CAIP-2, and ERC-20 token utilities
+ */
+export { evm };
+/**
+ * Normalize a legacy network identifier to CAIP-2 format.
+ * Handles both EVM and Solana networks.
+ * Returns the input unchanged if no mapping exists (may already be CAIP-2
+ * or an unknown network).
+ */
+export declare function normalizeNetworkId(network: string): string;
+/**
+ * Translate a CAIP-2 network identifier to legacy format.
+ * Handles both EVM and Solana networks.
+ * Returns the input unchanged if no mapping exists (may not be a known
+ * CAIP-2 network, or may already be legacy).
+ */
+export declare function translateNetworkToLegacy(network: string): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;GAIG;AACH,OAAO,EAAE,MAAM,EAAE,CAAC;AAClB;;;;GAIG;AACH,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAShE"}

package/dist/src/index.js

@@ -1,2 +1,55 @@
-export * as solana from "./solana.js";
-export * as evm from "./evm.js";
+/**
+ * @title Info Package
+ * @sidebarTitle Info
+ * @description Network and asset information utilities for EVM and Solana chains
+ * @packageDocumentation
+ */
+import * as solana from "./solana.js";
+import * as evm from "./evm.js";
+/**
+ * @title Solana Network Info
+ * @sidebarTitle Info / Solana
+ * @description Solana cluster, network ID, and SPL token utilities
+ */
+export { solana };
+/**
+ * @title EVM Network Info
+ * @sidebarTitle Info / EVM
+ * @description EVM chain ID, CAIP-2, and ERC-20 token utilities
+ */
+export { evm };
+/**
+ * Normalize a legacy network identifier to CAIP-2 format.
+ * Handles both EVM and Solana networks.
+ * Returns the input unchanged if no mapping exists (may already be CAIP-2
+ * or an unknown network).
+ */
+export function normalizeNetworkId(network) {
+    if (network.startsWith("eip155:"))
+        return network;
+    const evmCaip2 = evm.legacyNameToCAIP2(network);
+    if (evmCaip2)
+        return evmCaip2;
+    if (network.startsWith("solana:"))
+        return network;
+    const solanaNetwork = solana.legacyNetworkIdToCAIP2(network);
+    if (solanaNetwork)
+        return solanaNetwork.caip2;
+    return network;
+}
+/**
+ * Translate a CAIP-2 network identifier to legacy format.
+ * Handles both EVM and Solana networks.
+ * Returns the input unchanged if no mapping exists (may not be a known
+ * CAIP-2 network, or may already be legacy).
+ */
+export function translateNetworkToLegacy(network) {
+    const evmLegacy = evm.caip2ToLegacyName(network);
+    if (evmLegacy)
+        return evmLegacy;
+    const solanaLegacy = solana.caip2ToLegacyNetworkIds(network);
+    const firstSolanaLegacy = solanaLegacy?.[0];
+    if (firstSolanaLegacy)
+        return firstSolanaLegacy;
+    return network;
+}

package/dist/src/solana.d.ts

@@ -1,10 +1,76 @@
 import { type UnitInput } from "./common.js";
-import { Base58Address } from "@faremeter/types/solana";
-declare const knownClusters: readonly ["devnet", "testnet", "mainnet-beta"];
-type knownClusters = typeof knownClusters;
-export type KnownCluster = (typeof knownClusters)[number];
+import { type SolanaCluster, type SolanaCAIP2Network, Base58Address, isSolanaCluster, isSolanaCAIP2Network, isSolanaCAIP2NetworkString, createSolanaNetwork } from "@faremeter/types/solana";
+export type { SolanaCluster, SolanaCAIP2Network };
+export type KnownCluster = SolanaCluster;
+export { isSolanaCluster, isSolanaCAIP2Network, isSolanaCAIP2NetworkString, createSolanaNetwork, };
 export declare function isKnownCluster(c: string): c is KnownCluster;
-export declare const lookupX402Network: (network: string) => string[];
+export declare const SOLANA_MAINNET_BETA: SolanaCAIP2Network;
+export declare const SOLANA_DEVNET: SolanaCAIP2Network;
+export declare const SOLANA_TESTNET: SolanaCAIP2Network;
+/**
+ * Type guard that checks if a string is a known Solana CAIP-2 network.
+ *
+ * @param n - The string to check
+ * @returns True if the string is a known Solana CAIP-2 network identifier
+ */
+export declare function isKnownSolanaCAIP2Network(n: string): boolean;
+/**
+ * Converts a Solana cluster name to a SolanaCAIP2Network object.
+ *
+ * @param cluster - The Solana cluster name
+ * @returns The corresponding SolanaCAIP2Network object
+ * @throws Error if the cluster is unknown
+ */
+export declare function clusterToCAIP2(cluster: SolanaCluster): SolanaCAIP2Network;
+/**
+ * Converts a CAIP-2 network identifier to Solana cluster name.
+ *
+ * @param caip2 - The CAIP-2 network identifier string
+ * @returns The cluster name, or null if not a known Solana network
+ */
+export declare function caip2ToCluster(caip2: string): SolanaCluster | null;
+/**
+ * Converts a legacy Solana network ID to a SolanaCAIP2Network object.
+ *
+ * @param legacy - Legacy network identifier (e.g., "solana-mainnet-beta")
+ * @returns The SolanaCAIP2Network object, or null if unknown
+ */
+export declare function legacyNetworkIdToCAIP2(legacy: string): SolanaCAIP2Network | null;
+/**
+ * Converts a CAIP-2 network identifier to legacy Solana network IDs.
+ *
+ * @param caip2 - The CAIP-2 network identifier string
+ * @returns Array of legacy network IDs, or null if unknown
+ */
+export declare function caip2ToLegacyNetworkIds(caip2: string): readonly string[] | null;
+/**
+ * Normalizes a Solana network identifier to CAIP-2 format string.
+ *
+ * Accepts cluster names, legacy IDs, or CAIP-2 identifiers.
+ * Returns the input unchanged if no mapping exists.
+ *
+ * @param network - The network identifier in any supported format
+ * @returns The CAIP-2 network identifier string, or the original string if unrecognized
+ */
+export declare function normalizeNetworkId(network: string): string;
+/**
+ * Looks up the x402 network identifier for a Solana cluster.
+ *
+ * Accepts a cluster name, CAIP-2 identifier string, legacy network ID,
+ * or an existing SolanaCAIP2Network object.
+ *
+ * @param network - Cluster name, CAIP-2 ID, legacy network ID, or SolanaCAIP2Network object
+ * @returns A SolanaCAIP2Network object
+ * @throws Error if the network is unknown or invalid
+ */
+export declare function lookupX402Network(network: string | SolanaCAIP2Network): SolanaCAIP2Network;
+/**
+ * Gets the v1 legacy network IDs for a Solana cluster.
+ *
+ * @param cluster - The Solana cluster name
+ * @returns Array of legacy network IDs for v1 compatibility
+ */
+export declare function getV1NetworkIds(cluster: KnownCluster): string[];
 declare const knownSPLTokens: {
     readonly USDC: {
         readonly cluster: {
@@ -19,12 +85,25 @@ declare const knownSPLTokens: {
     };
 };
 export type KnownSPLToken = keyof typeof knownSPLTokens;
+/**
+ * Looks up SPL token information by cluster and token name.
+ *
+ * @param cluster - The Solana cluster
+ * @param name - The known SPL token name (e.g., "USDC")
+ * @returns Token information including address, or undefined if not found
+ */
 export declare function lookupKnownSPLToken(cluster: KnownCluster, name: KnownSPLToken): {
-    cluster: "devnet" | "testnet" | "mainnet-beta";
+    cluster: "mainnet-beta" | "devnet" | "testnet";
     name: "USDC";
     toUnit: (v: UnitInput) => string;
     address: Base58Address;
 } | undefined;
+/**
+ * Type guard that checks if a string is a known SPL token name.
+ *
+ * @param splToken - The string to check
+ * @returns True if the string is a known SPL token
+ */
 export declare function isKnownSPLToken(splToken: string): splToken is KnownSPLToken;
 export type x402ExactArgs = {
     network: KnownCluster;
@@ -32,16 +111,24 @@ export type x402ExactArgs = {
     amount: UnitInput;
     payTo: Base58Address;
 };
+/**
+ * Creates x402 exact payment requirements for Solana.
+ *
+ * Returns multiple requirements for v1 compatibility (one per legacy network ID).
+ *
+ * @param args - Payment configuration including network, asset, amount, and payTo
+ * @returns Array of x402 payment requirements
+ */
 export declare function x402Exact(args: x402ExactArgs): Partial<{
     scheme: string;
     network: string;
     maxAmountRequired: string;
     resource: string;
     description: string;
-    mimeType: string;
     payTo: string;
     maxTimeoutSeconds: number;
     asset: string;
+    mimeType?: string;
     outputSchema?: object;
     extra?: object;
 }>[];
@@ -51,18 +138,25 @@ export type xSolanaSettlementArgs = {
     amount: UnitInput;
     payTo: Base58Address;
 };
+/**
+ * Creates x-solana-settlement payment requirements.
+ *
+ * Supports both SPL tokens and native SOL.
+ *
+ * @param args - Payment configuration including network, asset, amount, and payTo
+ * @returns x402 payment requirement for the settlement scheme
+ */
 export declare function xSolanaSettlement(args: xSolanaSettlementArgs): Partial<{
     scheme: string;
     network: string;
     maxAmountRequired: string;
     resource: string;
     description: string;
-    mimeType: string;
     payTo: string;
     maxTimeoutSeconds: number;
     asset: string;
+    mimeType?: string;
     outputSchema?: object;
     extra?: object;
 }>;
-export {};
 //# sourceMappingURL=solana.d.ts.map

package/dist/src/solana.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/solana.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,QAAA,MAAM,aAAa,gDAAiD,CAAC;AACrE,KAAK,aAAa,GAAG,OAAO,aAAa,CAAC;AAC1C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,aAQhD,CAAC;AAOF,QAAA,MAAM,cAAc;;;;;;;;;;6BAUJ,SAAS;;CAEwB,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAExD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,aAAa;;;gBApBP,SAAS,KAAK,MAAM;aADiB,aAAa;cAyC/D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,aAAa,CAE3E;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa;;;;;;;;;;;;KAqB5C;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,aAAa,GAAG,KAAK,CAAC;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB;;;;;;;;;;;;GA2B5D"}
+{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/solana.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,UAAU,CAAC;AAC7E,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,GACpB,CAAC;AAEF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,YAAY,CAE3D;AAED,eAAO,MAAM,mBAAmB,oBAG/B,CAAC;AAEF,eAAO,MAAM,aAAa,oBAGzB,CAAC;AAEF,eAAO,MAAM,cAAc,oBAG1B,CAAC;AAwBF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5D;AAgBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,kBAAkB,CAMzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GACb,kBAAkB,GAAG,IAAI,CAE3B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GACZ,SAAS,MAAM,EAAE,GAAG,IAAI,CAM1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAe1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,kBAAkB,GACnC,kBAAkB,CAuBpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAI/D;AAOD,QAAA,MAAM,cAAc;;;;;;;;;;6BAUJ,SAAS;;CAEwB,CAAC;AAElD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,aAAa;;;gBA5BP,SAAS,KAAK,MAAM;aADiB,aAAa;cAiD/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,aAAa,CAE3E;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa;;;;;;;;;;;;KAqB5C;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,aAAa,GAAG,KAAK,CAAC;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB;;;;;;;;;;;;GA2B5D"}

package/dist/src/solana.js

@@ -1,16 +1,157 @@
 import { addX402PaymentRequirementDefaults } from "./common.js";
-import { Base58Address } from "@faremeter/types/solana";
-const knownClusters = ["devnet", "testnet", "mainnet-beta"];
+import { Base58Address, isSolanaCluster, isSolanaCAIP2Network, isSolanaCAIP2NetworkString, createSolanaNetwork, } from "@faremeter/types/solana";
+export { isSolanaCluster, isSolanaCAIP2Network, isSolanaCAIP2NetworkString, createSolanaNetwork, };
 export function isKnownCluster(c) {
-    return knownClusters.includes(c);
+    return isSolanaCluster(c);
 }
-export const lookupX402Network = (network) => {
-    const networks = [`solana-${network}`];
-    if (network === "mainnet-beta") {
-        networks.push("solana");
-    }
-    return networks;
+export const SOLANA_MAINNET_BETA = createSolanaNetwork("solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "mainnet-beta");
+export const SOLANA_DEVNET = createSolanaNetwork("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "devnet");
+export const SOLANA_TESTNET = createSolanaNetwork("solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z", "testnet");
+const knownSolanaNetworks = {
+    [SOLANA_MAINNET_BETA.caip2]: {
+        network: SOLANA_MAINNET_BETA,
+        legacyNetworkIds: ["solana-mainnet-beta", "solana"],
+    },
+    [SOLANA_DEVNET.caip2]: {
+        network: SOLANA_DEVNET,
+        legacyNetworkIds: ["solana-devnet"],
+    },
+    [SOLANA_TESTNET.caip2]: {
+        network: SOLANA_TESTNET,
+        legacyNetworkIds: ["solana-testnet"],
+    },
 };
+/**
+ * Type guard that checks if a string is a known Solana CAIP-2 network.
+ *
+ * @param n - The string to check
+ * @returns True if the string is a known Solana CAIP-2 network identifier
+ */
+export function isKnownSolanaCAIP2Network(n) {
+    return n in knownSolanaNetworks;
+}
+const clusterToNetworkMap = new Map(Object.values(knownSolanaNetworks).map((info) => [
+    info.network.name,
+    info.network,
+]));
+const legacyNetworkIdToNetworkMap = new Map();
+for (const info of Object.values(knownSolanaNetworks)) {
+    for (const legacyId of info.legacyNetworkIds) {
+        legacyNetworkIdToNetworkMap.set(legacyId, info.network);
+    }
+}
+/**
+ * Converts a Solana cluster name to a SolanaCAIP2Network object.
+ *
+ * @param cluster - The Solana cluster name
+ * @returns The corresponding SolanaCAIP2Network object
+ * @throws Error if the cluster is unknown
+ */
+export function clusterToCAIP2(cluster) {
+    const network = clusterToNetworkMap.get(cluster);
+    if (!network) {
+        throw new Error(`Unknown Solana cluster: ${cluster}`);
+    }
+    return network;
+}
+/**
+ * Converts a CAIP-2 network identifier to Solana cluster name.
+ *
+ * @param caip2 - The CAIP-2 network identifier string
+ * @returns The cluster name, or null if not a known Solana network
+ */
+export function caip2ToCluster(caip2) {
+    const info = knownSolanaNetworks[caip2];
+    if (!info) {
+        return null;
+    }
+    return info.network.name;
+}
+/**
+ * Converts a legacy Solana network ID to a SolanaCAIP2Network object.
+ *
+ * @param legacy - Legacy network identifier (e.g., "solana-mainnet-beta")
+ * @returns The SolanaCAIP2Network object, or null if unknown
+ */
+export function legacyNetworkIdToCAIP2(legacy) {
+    return legacyNetworkIdToNetworkMap.get(legacy) ?? null;
+}
+/**
+ * Converts a CAIP-2 network identifier to legacy Solana network IDs.
+ *
+ * @param caip2 - The CAIP-2 network identifier string
+ * @returns Array of legacy network IDs, or null if unknown
+ */
+export function caip2ToLegacyNetworkIds(caip2) {
+    const info = knownSolanaNetworks[caip2];
+    if (!info) {
+        return null;
+    }
+    return info.legacyNetworkIds;
+}
+/**
+ * Normalizes a Solana network identifier to CAIP-2 format string.
+ *
+ * Accepts cluster names, legacy IDs, or CAIP-2 identifiers.
+ * Returns the input unchanged if no mapping exists.
+ *
+ * @param network - The network identifier in any supported format
+ * @returns The CAIP-2 network identifier string, or the original string if unrecognized
+ */
+export function normalizeNetworkId(network) {
+    if (isSolanaCAIP2NetworkString(network)) {
+        return network;
+    }
+    if (isSolanaCluster(network)) {
+        return clusterToCAIP2(network).caip2;
+    }
+    const networkObj = legacyNetworkIdToCAIP2(network);
+    if (networkObj) {
+        return networkObj.caip2;
+    }
+    return network;
+}
+/**
+ * Looks up the x402 network identifier for a Solana cluster.
+ *
+ * Accepts a cluster name, CAIP-2 identifier string, legacy network ID,
+ * or an existing SolanaCAIP2Network object.
+ *
+ * @param network - Cluster name, CAIP-2 ID, legacy network ID, or SolanaCAIP2Network object
+ * @returns A SolanaCAIP2Network object
+ * @throws Error if the network is unknown or invalid
+ */
+export function lookupX402Network(network) {
+    if (isSolanaCAIP2Network(network)) {
+        return network;
+    }
+    if (isSolanaCluster(network)) {
+        return clusterToCAIP2(network);
+    }
+    if (isSolanaCAIP2NetworkString(network)) {
+        const known = knownSolanaNetworks[network];
+        if (known) {
+            return known.network;
+        }
+        return createSolanaNetwork(network);
+    }
+    const networkObj = legacyNetworkIdToCAIP2(network);
+    if (networkObj) {
+        return networkObj;
+    }
+    throw new Error(`Unknown Solana network: ${network}`);
+}
+/**
+ * Gets the v1 legacy network IDs for a Solana cluster.
+ *
+ * @param cluster - The Solana cluster name
+ * @returns Array of legacy network IDs for v1 compatibility
+ */
+export function getV1NetworkIds(cluster) {
+    const network = clusterToCAIP2(cluster);
+    const legacyIds = caip2ToLegacyNetworkIds(network.caip2) ?? [];
+    return [...legacyIds];
+}
 const knownSPLTokens = {
     USDC: {
         cluster: {
@@ -24,6 +165,13 @@ const knownSPLTokens = {
         toUnit: (v) => v.toString(),
     },
 };
+/**
+ * Looks up SPL token information by cluster and token name.
+ *
+ * @param cluster - The Solana cluster
+ * @param name - The known SPL token name (e.g., "USDC")
+ * @returns Token information including address, or undefined if not found
+ */
 export function lookupKnownSPLToken(cluster, name) {
     const splTokenInfo = knownSPLTokens[name];
     if (!splTokenInfo) {
@@ -40,28 +188,50 @@ export function lookupKnownSPLToken(cluster, name) {
         toUnit: splTokenInfo.toUnit,
     };
 }
+/**
+ * Type guard that checks if a string is a known SPL token name.
+ *
+ * @param splToken - The string to check
+ * @returns True if the string is a known SPL token
+ */
 export function isKnownSPLToken(splToken) {
     return splToken in knownSPLTokens;
 }
+/**
+ * Creates x402 exact payment requirements for Solana.
+ *
+ * Returns multiple requirements for v1 compatibility (one per legacy network ID).
+ *
+ * @param args - Payment configuration including network, asset, amount, and payTo
+ * @returns Array of x402 payment requirements
+ */
 export function x402Exact(args) {
     const tokenInfo = lookupKnownSPLToken(args.network, args.asset);
     if (!tokenInfo) {
         throw new Error(`couldn't look up token '${args.asset}' on Solana cluster`);
     }
-    const networks = lookupX402Network(args.network);
+    const networks = getV1NetworkIds(args.network);
     const req = networks.map((network) => addX402PaymentRequirementDefaults({
         scheme: "exact",
         network,
         maxAmountRequired: tokenInfo.toUnit(args.amount),
         payTo: args.payTo,
         asset: tokenInfo.address,
-        maxTimeoutSeconds: 60, // from coinbase/x402's middleware defaults
+        maxTimeoutSeconds: 60,
     }));
     return req;
 }
+/**
+ * Creates x-solana-settlement payment requirements.
+ *
+ * Supports both SPL tokens and native SOL.
+ *
+ * @param args - Payment configuration including network, asset, amount, and payTo
+ * @returns x402 payment requirement for the settlement scheme
+ */
 export function xSolanaSettlement(args) {
     let tokenInfo;
-    // Special-case this, because it's not an SPL Token.
+    // Special-case SOL, because it is not an SPL Token.
     if (args.asset === "sol") {
         tokenInfo = {
             address: "sol",
@@ -80,7 +250,7 @@ export function xSolanaSettlement(args) {
         maxAmountRequired: tokenInfo.toUnit(args.amount),
         payTo: args.payTo,
         asset: tokenInfo.address,
-        maxTimeoutSeconds: 60, // from coinbase/x402's middleware defaults
+        maxTimeoutSeconds: 60,
     });
     return req;
 }