@hardkas/l2 0.2.2-alpha.1 → 0.4.0-alpha

package/dist/index.d.ts

@@ -10,9 +10,26 @@ interface L2SecurityAssumptions {
     readonly riskProfile: L2RiskProfile;
     readonly notes: readonly string[];
 }
+type L2ProfileSource = "built-in" | "user-config";
+interface L2UserNetworkConfig {
+    readonly kind?: "igra" | string;
+    readonly chainId: number;
+    readonly rpcUrl: string;
+    readonly explorerUrl?: string;
+    readonly bridgePhase?: L2BridgePhase;
+    readonly trustlessExit?: boolean;
+    readonly nativeCurrency?: {
+        readonly name?: string;
+        readonly symbol?: string;
+        readonly decimals?: number;
+    };
+    readonly contracts?: Record<string, string>;
+    readonly metadata?: Record<string, unknown>;
+}
 interface L2NetworkProfile {
     readonly schema: "hardkas.l2Profile.v1";
     readonly hardkasVersion: string;
+    readonly source: L2ProfileSource;
     readonly name: string;
     readonly displayName: string;
     readonly type: L2NetworkType;
@@ -27,9 +44,38 @@ interface L2NetworkProfile {
 }
 declare const BUILTIN_L2_PROFILES: readonly L2NetworkProfile[];
 
-declare function getBuiltInL2Profiles(): readonly L2NetworkProfile[];
-declare function listL2Profiles(): readonly L2NetworkProfile[];
-declare function getL2Profile(name: string): L2NetworkProfile | null;
+interface MetaMaskChainParams {
+    chainId: string;
+    chainName: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls?: string[] | undefined;
+}
+/**
+ * Generates the standard wallet_addEthereumChain payload for MetaMask.
+ */
+declare function generateAddEthereumChainPayload(profile: L2NetworkProfile): MetaMaskChainParams;
+/**
+ * Generates a JavaScript snippet for browser consoles to add the network to MetaMask.
+ */
+declare function generateMetaMaskSnippet(profile: L2NetworkProfile): string;
+
+declare function listL2Profiles(userProfiles?: Record<string, L2UserNetworkConfig>): L2NetworkProfile[];
+declare function getL2Profile(name: string, userProfiles?: Record<string, L2UserNetworkConfig>): L2NetworkProfile | null;
+declare function resolveL2Profile(args: {
+    name?: string | undefined;
+    userProfiles?: Record<string, L2UserNetworkConfig> | undefined;
+    cliOverrides?: {
+        url?: string | undefined;
+        rpcUrl?: string | undefined;
+        chainId?: number | string | undefined;
+        [key: string]: unknown;
+    } | undefined;
+}): L2NetworkProfile;
 declare function validateL2Profile(profile: any): {
     ok: boolean;
     errors: string[];
@@ -174,4 +220,4 @@ declare function assertValidL2BridgeAssumptions(input: unknown): L2BridgeAssumpt
  */
 declare function encodeConstructorArgs(bytecode: string, constructorSignature: string, args: string[]): string;
 
-export { BUILTIN_L2_PROFILES, type EvmCallRequest, EvmJsonRpcClient, type EvmJsonRpcClientOptions, type EvmRpcHealthResult, type EvmTransactionReceiptSummary, type IgraTxSigner, type IgraTxSigningInput, type IgraTxSigningResult, type L2BridgeAssumptions, type L2BridgePhase, type L2NetworkProfile, type L2NetworkType, type L2RiskProfile, type L2SecurityAssumptions, UnsupportedIgraTxSigner, ViemIgraTxSigner, type ViemIgraTxSignerOptions, assertValidL2BridgeAssumptions, assertValidL2Profile, checkEvmRpcHealth, encodeConstructorArgs, formatWeiAsEtherLike, getBuiltInL2Profiles, getL2BridgeAssumptions, getL2Profile, listL2BridgeAssumptions, listL2Profiles, normalizeEvmTransactionReceipt, toHexQuantity, validateL2BridgeAssumptions, validateL2Profile, waitForEvmRpcReady };
+export { BUILTIN_L2_PROFILES, type EvmCallRequest, EvmJsonRpcClient, type EvmJsonRpcClientOptions, type EvmRpcHealthResult, type EvmTransactionReceiptSummary, type IgraTxSigner, type IgraTxSigningInput, type IgraTxSigningResult, type L2BridgeAssumptions, type L2BridgePhase, type L2NetworkProfile, type L2NetworkType, type L2ProfileSource, type L2RiskProfile, type L2SecurityAssumptions, type L2UserNetworkConfig, type MetaMaskChainParams, UnsupportedIgraTxSigner, ViemIgraTxSigner, type ViemIgraTxSignerOptions, assertValidL2BridgeAssumptions, assertValidL2Profile, checkEvmRpcHealth, encodeConstructorArgs, formatWeiAsEtherLike, generateAddEthereumChainPayload, generateMetaMaskSnippet, getL2BridgeAssumptions, resolveL2Profile as getL2NetworkProfile, getL2Profile, listL2BridgeAssumptions, listL2Profiles, normalizeEvmTransactionReceipt, resolveL2Profile, toHexQuantity, validateL2BridgeAssumptions, validateL2Profile, waitForEvmRpcReady };

package/dist/index.js

@@ -4,6 +4,7 @@ var BUILTIN_L2_PROFILES = [
   {
     schema: "hardkas.l2Profile.v1",
     hardkasVersion: HARDKAS_VERSION,
+    source: "built-in",
     name: "igra",
     displayName: "Igra",
     type: "evm-based-rollup",
@@ -11,6 +12,8 @@ var BUILTIN_L2_PROFILES = [
     executionLayer: "evm",
     gasToken: "iKAS",
     nativeTokenDecimals: 18,
+    chainId: 19416,
+    rpcUrl: "http://127.0.0.1:8545",
     security: {
       bridgePhase: "pre-zk",
       trustlessExit: false,
@@ -27,15 +30,106 @@ var BUILTIN_L2_PROFILES = [
   }
 ];
 
+// src/metamask.ts
+function generateAddEthereumChainPayload(profile) {
+  if (!profile.chainId) {
+    throw new Error(`Profile "${profile.name}" is missing chainId`);
+  }
+  if (!profile.rpcUrl) {
+    throw new Error(`Profile "${profile.name}" is missing rpcUrl`);
+  }
+  return {
+    chainId: `0x${profile.chainId.toString(16)}`,
+    chainName: profile.displayName || profile.name,
+    nativeCurrency: {
+      name: profile.gasToken || "iKAS",
+      symbol: profile.gasToken || "iKAS",
+      decimals: profile.nativeTokenDecimals || 18
+    },
+    rpcUrls: [profile.rpcUrl],
+    blockExplorerUrls: profile.explorerUrl ? [profile.explorerUrl] : void 0
+  };
+}
+function generateMetaMaskSnippet(profile) {
+  const payload = generateAddEthereumChainPayload(profile);
+  return `await window.ethereum.request({
+  method: "wallet_addEthereumChain",
+  params: [
+    ${JSON.stringify(payload, null, 4).replace(/\n/g, "\n    ")}
+  ]
+});`;
+}
+
 // src/registry.ts
-function getBuiltInL2Profiles() {
-  return BUILTIN_L2_PROFILES;
+import { HARDKAS_VERSION as HARDKAS_VERSION2 } from "@hardkas/artifacts";
+function listL2Profiles(userProfiles) {
+  const profiles = [...BUILTIN_L2_PROFILES];
+  if (userProfiles) {
+    for (const [name, config] of Object.entries(userProfiles)) {
+      const existingIndex = profiles.findIndex((p) => p.name === name);
+      const profile = mapUserConfigToProfile(name, config);
+      if (existingIndex !== -1) {
+        profiles[existingIndex] = profile;
+      } else {
+        profiles.push(profile);
+      }
+    }
+  }
+  return profiles;
+}
+function getL2Profile(name, userProfiles) {
+  return listL2Profiles(userProfiles).find((p) => p.name === name) || null;
 }
-function listL2Profiles() {
-  return BUILTIN_L2_PROFILES;
+function resolveL2Profile(args) {
+  const name = args.name || "igra";
+  const profile = getL2Profile(name, args.userProfiles);
+  if (!profile) {
+    const available = listL2Profiles(args.userProfiles).map((p) => `${p.name} (${p.source})`).join(", ");
+    throw new Error(`L2 profile '${name}' not found. Available profiles: ${available}`);
+  }
+  let rpcUrl = args.cliOverrides?.rpcUrl || args.cliOverrides?.url || profile.rpcUrl;
+  if (args.cliOverrides?.rpcUrl && args.cliOverrides?.url && args.cliOverrides.rpcUrl !== args.cliOverrides.url) {
+    throw new Error("Conflict: Both --rpc-url and --url provided with different values.");
+  }
+  let chainId = profile.chainId;
+  if (args.cliOverrides?.chainId !== void 0) {
+    chainId = typeof args.cliOverrides.chainId === "string" ? parseInt(args.cliOverrides.chainId, 10) : args.cliOverrides.chainId;
+    if (isNaN(chainId)) {
+      throw new Error(`Invalid chainId: ${args.cliOverrides.chainId}`);
+    }
+  }
+  const resolved = {
+    ...profile,
+    ...rpcUrl ? { rpcUrl } : {},
+    ...chainId !== void 0 ? { chainId } : {}
+  };
+  return assertValidL2Profile(resolved);
 }
-function getL2Profile(name) {
-  return listL2Profiles().find((p) => p.name === name) || null;
+function mapUserConfigToProfile(name, config) {
+  const bridgePhase = config.bridgePhase || "pre-zk";
+  const trustlessExit = config.trustlessExit ?? false;
+  return {
+    schema: "hardkas.l2Profile.v1",
+    hardkasVersion: HARDKAS_VERSION2,
+    source: "user-config",
+    name,
+    displayName: name,
+    type: "evm-based-rollup",
+    settlementLayer: "kaspa",
+    executionLayer: "evm",
+    gasToken: config.nativeCurrency?.symbol || (config.kind === "igra" || !config.kind ? "iKAS" : "ETH"),
+    nativeTokenDecimals: config.nativeCurrency?.decimals || 18,
+    chainId: config.chainId,
+    rpcUrl: config.rpcUrl,
+    ...config.explorerUrl ? { explorerUrl: config.explorerUrl } : {},
+    security: {
+      bridgePhase,
+      trustlessExit,
+      custodyModel: "User-defined bridge custody.",
+      riskProfile: "unknown",
+      notes: ["User-defined network from config"]
+    }
+  };
 }
 function validateL2Profile(profile) {
   const errors = [];
@@ -45,36 +139,10 @@ function validateL2Profile(profile) {
   if (profile.schema !== "hardkas.l2Profile.v1") {
     errors.push(`Invalid schema: expected 'hardkas.l2Profile.v1', got '${profile.schema}'`);
   }
-  if (typeof profile.hardkasVersion !== "string") {
-    errors.push("Missing or invalid hardkasVersion");
-  }
-  if (!profile.name || typeof profile.name !== "string") {
-    errors.push("Missing or invalid name");
-  }
-  if (profile.type !== "evm-based-rollup") {
-    errors.push(`Invalid type: expected 'evm-based-rollup', got '${profile.type}'`);
-  }
-  if (profile.settlementLayer !== "kaspa") {
-    errors.push(`Invalid settlementLayer: expected 'kaspa', got '${profile.settlementLayer}'`);
-  }
-  if (profile.executionLayer !== "evm") {
-    errors.push(`Invalid executionLayer: expected 'evm', got '${profile.executionLayer}'`);
-  }
-  if (!profile.gasToken || typeof profile.gasToken !== "string") {
-    errors.push("Missing or invalid gasToken");
-  }
   if (profile.security) {
-    if (profile.security.bridgePhase === "zk") {
-    } else {
-      if (profile.security.trustlessExit === true) {
-        errors.push("Security invariant violation: trustlessExit must be false when bridgePhase is not 'zk'");
-      }
+    if (profile.security.bridgePhase !== "zk" && profile.security.trustlessExit === true) {
+      errors.push(`Security invariant violation: trustlessExit=true is only allowed when bridgePhase='zk'. Current phase: ${profile.security.bridgePhase}`);
     }
-    if (!Array.isArray(profile.security.notes) || profile.security.notes.length === 0) {
-      errors.push("Security notes must not be empty");
-    }
-  } else {
-    errors.push("Missing security assumptions");
   }
   return {
     ok: errors.length === 0,
@@ -370,10 +438,10 @@ function normalizeEvmTransactionReceipt(raw) {
 }
 
 // src/bridge.ts
-import { HARDKAS_VERSION as HARDKAS_VERSION2 } from "@hardkas/artifacts";
+import { HARDKAS_VERSION as HARDKAS_VERSION3 } from "@hardkas/artifacts";
 var IGRA_BRIDGE_ASSUMPTIONS = {
   schema: "hardkas.l2BridgeAssumptions.v1",
-  hardkasVersion: HARDKAS_VERSION2,
+  hardkasVersion: HARDKAS_VERSION3,
   l2Network: "igra",
   bridgePhase: "pre-zk",
   trustlessExit: false,
@@ -457,12 +525,15 @@ export {
   checkEvmRpcHealth,
   encodeConstructorArgs,
   formatWeiAsEtherLike,
-  getBuiltInL2Profiles,
+  generateAddEthereumChainPayload,
+  generateMetaMaskSnippet,
   getL2BridgeAssumptions,
+  resolveL2Profile as getL2NetworkProfile,
   getL2Profile,
   listL2BridgeAssumptions,
   listL2Profiles,
   normalizeEvmTransactionReceipt,
+  resolveL2Profile,
   toHexQuantity,
   validateL2BridgeAssumptions,
   validateL2Profile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/l2",
-  "version": "0.2.2-alpha.1",
+  "version": "0.4.0-alpha",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "viem": "^2.48.8",
-    "@hardkas/artifacts": "0.2.2-alpha.1"
+    "@hardkas/artifacts": "0.4.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",