@opendatalabs/vana-sdk 0.1.0-alpha.273dc39 → 0.1.0-alpha.276ea01

package/dist/utils/eventParsing.d.ts

@@ -0,0 +1,60 @@
+import { Hash, TransactionReceipt } from 'viem';
+import { S as SchemaAddedResult, a as FileAddedResult, R as RefinerAddedResult } from '../permissions-eo8YeLGf.js';
+import '../types/operations.js';
+import '../generated/server/server-exports.js';
+import '../generated/server/server.js';
+import '../types/config.js';
+import '../types/chains.js';
+import '../types/storage.js';
+import '../types/permissions.js';
+import '../config/eventMappings.js';
+import '../generated/abi/index.js';
+import '../generated/abi/DataPortabilityPermissionsImplementation.js';
+import '../generated/abi/DataPortabilityServersImplementation.js';
+import '../generated/abi/DataPortabilityGranteesImplementation.js';
+import '../generated/abi/VanaEpochImplementation.js';
+import '../generated/abi/DLPRegistryImplementation.js';
+import '../generated/abi/DLPTreasuryImplementation.js';
+import '../generated/abi/DLPRewardDeployerTreasuryImplementation.js';
+import '../generated/abi/DLPPerformanceImplementation.js';
+import '../generated/abi/DLPRewardDeployerImplementation.js';
+import '../generated/abi/DLPRootImplementation.js';
+import '../generated/abi/DataLiquidityPoolImplementation.js';
+import '../generated/abi/DLPRegistryTreasuryImplementation.js';
+import '../storage/manager.js';
+import '../platform/interface.js';
+
+/**
+ * Error thrown when expected events are not found in transaction logs
+ */
+declare class EventParsingError extends Error {
+    readonly eventName: string;
+    readonly transactionHash: Hash;
+    constructor(eventName: string, transactionHash: Hash, message?: string);
+}
+/**
+ * Parses SchemaAdded event from a transaction receipt.
+ *
+ * @param receipt - The transaction receipt containing event logs.
+ * @returns A SchemaAddedResult with the schema ID and metadata from the event.
+ * @throws {EventParsingError} When the SchemaAdded event is not present in the receipt logs.
+ */
+declare function parseSchemaAddedEvent(receipt: TransactionReceipt): SchemaAddedResult;
+/**
+ * Parses FileAddedV2 event from a transaction receipt.
+ *
+ * @param receipt - The transaction receipt containing event logs.
+ * @returns A FileAddedResult with the file ID and metadata from the event.
+ * @throws {EventParsingError} When the FileAddedV2 event is not present in the receipt logs.
+ */
+declare function parseFileAddedEvent(receipt: TransactionReceipt): FileAddedResult;
+/**
+ * Parses RefinerAdded event from a transaction receipt.
+ *
+ * @param receipt - The transaction receipt containing event logs.
+ * @returns A RefinerAddedResult with the refiner ID and metadata from the event.
+ * @throws {EventParsingError} When the RefinerAdded event is not present in the receipt logs.
+ */
+declare function parseRefinerAddedEvent(receipt: TransactionReceipt): RefinerAddedResult;
+
+export { EventParsingError, parseFileAddedEvent, parseRefinerAddedEvent, parseSchemaAddedEvent };

package/dist/utils/eventParsing.js

@@ -0,0 +1,86 @@
+import {
+  parseEventLogs
+} from "viem";
+import { getAbi } from "../generated/abi";
+class EventParsingError extends Error {
+  constructor(eventName, transactionHash, message) {
+    super(
+      message || `Event "${eventName}" not found in transaction ${transactionHash}`
+    );
+    this.eventName = eventName;
+    this.transactionHash = transactionHash;
+    this.name = "EventParsingError";
+  }
+}
+function parseSchemaAddedEvent(receipt) {
+  const abi = getAbi("DataRefinerRegistry");
+  const logs = parseEventLogs({
+    abi,
+    logs: receipt.logs,
+    eventName: "SchemaAdded"
+  });
+  if (logs.length === 0) {
+    throw new EventParsingError("SchemaAdded", receipt.transactionHash);
+  }
+  const event = logs[0];
+  return {
+    transactionHash: receipt.transactionHash,
+    blockNumber: receipt.blockNumber,
+    gasUsed: receipt.gasUsed,
+    schemaId: event.args.schemaId,
+    name: event.args.name,
+    dialect: event.args.dialect,
+    definitionUrl: event.args.definitionUrl
+  };
+}
+function parseFileAddedEvent(receipt) {
+  const abi = getAbi("DataRegistry");
+  const logs = parseEventLogs({
+    abi,
+    logs: receipt.logs,
+    eventName: "FileAddedV2"
+  });
+  if (logs.length === 0) {
+    throw new EventParsingError("FileAddedV2", receipt.transactionHash);
+  }
+  const event = logs[0];
+  return {
+    transactionHash: receipt.transactionHash,
+    blockNumber: receipt.blockNumber,
+    gasUsed: receipt.gasUsed,
+    fileId: event.args.fileId,
+    ownerAddress: event.args.ownerAddress,
+    url: event.args.url,
+    schemaId: event.args.schemaId
+  };
+}
+function parseRefinerAddedEvent(receipt) {
+  const abi = getAbi("DataRefinerRegistry");
+  const logs = parseEventLogs({
+    abi,
+    logs: receipt.logs,
+    eventName: "RefinerAdded"
+  });
+  if (logs.length === 0) {
+    throw new EventParsingError("RefinerAdded", receipt.transactionHash);
+  }
+  const event = logs[0];
+  return {
+    transactionHash: receipt.transactionHash,
+    blockNumber: receipt.blockNumber,
+    gasUsed: receipt.gasUsed,
+    refinerId: event.args.refinerId,
+    dlpId: event.args.dlpId,
+    name: event.args.name,
+    schemaId: event.args.schemaId,
+    schemaDefinitionUrl: event.args.schemaDefinitionUrl,
+    refinementInstructionUrl: event.args.refinementInstructionUrl
+  };
+}
+export {
+  EventParsingError,
+  parseFileAddedEvent,
+  parseRefinerAddedEvent,
+  parseSchemaAddedEvent
+};
+//# sourceMappingURL=eventParsing.js.map

package/dist/utils/eventParsing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/eventParsing.ts"],"sourcesContent":["import {\n  parseEventLogs,\n  type Log,\n  type TransactionReceipt,\n  type Hash,\n} from \"viem\";\nimport type {\n  SchemaAddedResult,\n  FileAddedResult,\n  RefinerAddedResult,\n} from \"../types/transactionResults\";\nimport { getAbi } from \"../generated/abi\";\n\n/**\n * Error thrown when expected events are not found in transaction logs\n */\nexport class EventParsingError extends Error {\n  constructor(\n    public readonly eventName: string,\n    public readonly transactionHash: Hash,\n    message?: string,\n  ) {\n    super(\n      message ||\n        `Event \"${eventName}\" not found in transaction ${transactionHash}`,\n    );\n    this.name = \"EventParsingError\";\n  }\n}\n\n/**\n * Parses SchemaAdded event from a transaction receipt.\n *\n * @param receipt - The transaction receipt containing event logs.\n * @returns A SchemaAddedResult with the schema ID and metadata from the event.\n * @throws {EventParsingError} When the SchemaAdded event is not present in the receipt logs.\n */\nexport function parseSchemaAddedEvent(\n  receipt: TransactionReceipt,\n): SchemaAddedResult {\n  const abi = getAbi(\"DataRefinerRegistry\");\n\n  const logs = parseEventLogs({\n    abi,\n    logs: receipt.logs as Log[],\n    eventName: \"SchemaAdded\",\n  });\n\n  if (logs.length === 0) {\n    throw new EventParsingError(\"SchemaAdded\", receipt.transactionHash);\n  }\n\n  const event = logs[0];\n  return {\n    transactionHash: receipt.transactionHash,\n    blockNumber: receipt.blockNumber,\n    gasUsed: receipt.gasUsed,\n    schemaId: event.args.schemaId as bigint,\n    name: event.args.name as string,\n    dialect: event.args.dialect as string,\n    definitionUrl: event.args.definitionUrl as string,\n  };\n}\n\n/**\n * Parses FileAddedV2 event from a transaction receipt.\n *\n * @param receipt - The transaction receipt containing event logs.\n * @returns A FileAddedResult with the file ID and metadata from the event.\n * @throws {EventParsingError} When the FileAddedV2 event is not present in the receipt logs.\n */\nexport function parseFileAddedEvent(\n  receipt: TransactionReceipt,\n): FileAddedResult {\n  const abi = getAbi(\"DataRegistry\");\n\n  const logs = parseEventLogs({\n    abi,\n    logs: receipt.logs as Log[],\n    eventName: \"FileAddedV2\",\n  });\n\n  if (logs.length === 0) {\n    throw new EventParsingError(\"FileAddedV2\", receipt.transactionHash);\n  }\n\n  const event = logs[0];\n  // FileAddedV2 event has 'ownerAddress' field, not 'owner'\n  return {\n    transactionHash: receipt.transactionHash,\n    blockNumber: receipt.blockNumber,\n    gasUsed: receipt.gasUsed,\n    fileId: event.args.fileId as bigint,\n    ownerAddress: event.args.ownerAddress as `0x${string}`,\n    url: event.args.url as string,\n    schemaId: event.args.schemaId as bigint,\n  };\n}\n\n/**\n * Parses RefinerAdded event from a transaction receipt.\n *\n * @param receipt - The transaction receipt containing event logs.\n * @returns A RefinerAddedResult with the refiner ID and metadata from the event.\n * @throws {EventParsingError} When the RefinerAdded event is not present in the receipt logs.\n */\nexport function parseRefinerAddedEvent(\n  receipt: TransactionReceipt,\n): RefinerAddedResult {\n  const abi = getAbi(\"DataRefinerRegistry\");\n\n  const logs = parseEventLogs({\n    abi,\n    logs: receipt.logs as Log[],\n    eventName: \"RefinerAdded\",\n  });\n\n  if (logs.length === 0) {\n    throw new EventParsingError(\"RefinerAdded\", receipt.transactionHash);\n  }\n\n  const event = logs[0];\n  return {\n    transactionHash: receipt.transactionHash,\n    blockNumber: receipt.blockNumber,\n    gasUsed: receipt.gasUsed,\n    refinerId: event.args.refinerId as bigint,\n    dlpId: event.args.dlpId as bigint,\n    name: event.args.name as string,\n    schemaId: event.args.schemaId as bigint,\n    schemaDefinitionUrl: event.args.schemaDefinitionUrl as string,\n    refinementInstructionUrl: event.args.refinementInstructionUrl as string,\n  };\n}\n"],"mappings":"AAAA;AAAA,EACE;AAAA,OAIK;AAMP,SAAS,cAAc;AAKhB,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YACkB,WACA,iBAChB,SACA;AACA;AAAA,MACE,WACE,UAAU,SAAS,8BAA8B,eAAe;AAAA,IACpE;AAPgB;AACA;AAOhB,SAAK,OAAO;AAAA,EACd;AACF;AASO,SAAS,sBACd,SACmB;AACnB,QAAM,MAAM,OAAO,qBAAqB;AAExC,QAAM,OAAO,eAAe;AAAA,IAC1B;AAAA,IACA,MAAM,QAAQ;AAAA,IACd,WAAW;AAAA,EACb,CAAC;AAED,MAAI,KAAK,WAAW,GAAG;AACrB,UAAM,IAAI,kBAAkB,eAAe,QAAQ,eAAe;AAAA,EACpE;AAEA,QAAM,QAAQ,KAAK,CAAC;AACpB,SAAO;AAAA,IACL,iBAAiB,QAAQ;AAAA,IACzB,aAAa,QAAQ;AAAA,IACrB,SAAS,QAAQ;AAAA,IACjB,UAAU,MAAM,KAAK;AAAA,IACrB,MAAM,MAAM,KAAK;AAAA,IACjB,SAAS,MAAM,KAAK;AAAA,IACpB,eAAe,MAAM,KAAK;AAAA,EAC5B;AACF;AASO,SAAS,oBACd,SACiB;AACjB,QAAM,MAAM,OAAO,cAAc;AAEjC,QAAM,OAAO,eAAe;AAAA,IAC1B;AAAA,IACA,MAAM,QAAQ;AAAA,IACd,WAAW;AAAA,EACb,CAAC;AAED,MAAI,KAAK,WAAW,GAAG;AACrB,UAAM,IAAI,kBAAkB,eAAe,QAAQ,eAAe;AAAA,EACpE;AAEA,QAAM,QAAQ,KAAK,CAAC;AAEpB,SAAO;AAAA,IACL,iBAAiB,QAAQ;AAAA,IACzB,aAAa,QAAQ;AAAA,IACrB,SAAS,QAAQ;AAAA,IACjB,QAAQ,MAAM,KAAK;AAAA,IACnB,cAAc,MAAM,KAAK;AAAA,IACzB,KAAK,MAAM,KAAK;AAAA,IAChB,UAAU,MAAM,KAAK;AAAA,EACvB;AACF;AASO,SAAS,uBACd,SACoB;AACpB,QAAM,MAAM,OAAO,qBAAqB;AAExC,QAAM,OAAO,eAAe;AAAA,IAC1B;AAAA,IACA,MAAM,QAAQ;AAAA,IACd,WAAW;AAAA,EACb,CAAC;AAED,MAAI,KAAK,WAAW,GAAG;AACrB,UAAM,IAAI,kBAAkB,gBAAgB,QAAQ,eAAe;AAAA,EACrE;AAEA,QAAM,QAAQ,KAAK,CAAC;AACpB,SAAO;AAAA,IACL,iBAAiB,QAAQ;AAAA,IACzB,aAAa,QAAQ;AAAA,IACrB,SAAS,QAAQ;AAAA,IACjB,WAAW,MAAM,KAAK;AAAA,IACtB,OAAO,MAAM,KAAK;AAAA,IAClB,MAAM,MAAM,KAAK;AAAA,IACjB,UAAU,MAAM,KAAK;AAAA,IACrB,qBAAqB,MAAM,KAAK;AAAA,IAChC,0BAA0B,MAAM,KAAK;AAAA,EACvC;AACF;","names":[]}

package/dist/utils/formatters.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var formatters_exports = {};
+__export(formatters_exports, {
+  formatEth: () => formatEth,
+  formatNumber: () => formatNumber,
+  formatToken: () => formatToken,
+  shortenAddress: () => shortenAddress
+});
+module.exports = __toCommonJS(formatters_exports);
+var import_viem = require("viem");
+function formatNumber(value) {
+  return Number(value);
+}
+function formatEth(wei, decimals = 4) {
+  return (0, import_viem.formatEther)(BigInt(wei.toString())).slice(0, decimals + 2);
+}
+function formatToken(amount, decimals = 18, displayDecimals = 4) {
+  const value = (0, import_viem.formatUnits)(BigInt(amount.toString()), decimals);
+  const parts = value.split(".");
+  if (parts.length === 1) {
+    return parts[0];
+  }
+  return `${parts[0]}.${parts[1].slice(0, displayDecimals)}`;
+}
+function shortenAddress(address) {
+  if (!address || address.length < 10) return address;
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatEth,
+  formatNumber,
+  formatToken,
+  shortenAddress
+});
+//# sourceMappingURL=formatters.cjs.map

package/dist/utils/formatters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/formatters.ts"],"sourcesContent":["import { formatEther, formatUnits } from \"viem\";\n\n/**\n * Format a bigint or BigNumber to a regular number\n *\n * @remarks\n * This function converts blockchain-specific large number types to standard JavaScript\n * numbers. Use with caution for values that may exceed safe integer range.\n *\n * **Edge Cases:**\n * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision\n * - Negative values are supported\n * - String values must be valid numeric strings or will return NaN\n *\n * @param value BigInt, BigNumber or numeric string to convert\n * @returns Regular JavaScript number\n * @example\n * ```typescript\n * formatNumber(1000000000000000000n) // Returns: 1000000000000000000\n * formatNumber(\"123456789\") // Returns: 123456789\n * formatNumber(-100n) // Returns: -100\n *\n * // Precision loss example:\n * const bigValue = 9007199254740993n; // MAX_SAFE_INTEGER + 2\n * formatNumber(bigValue) // Returns: 9007199254740992 (lost precision)\n * ```\n */\nexport function formatNumber(value: bigint | string | number): number {\n  return Number(value);\n}\n\n/**\n * Format wei value to ETH with specified decimal places\n *\n * @remarks\n * Converts wei (smallest ETH unit) to human-readable ETH format.\n * 1 ETH = 10^18 wei. The function truncates rather than rounds\n * to ensure predictable display in financial contexts.\n *\n * **Edge Cases:**\n * - Truncates (not rounds) to specified decimal places\n * - Negative values are supported\n * - Zero values return \"0.0000\" (based on decimals)\n * - Very small values may display as \"0.0000\" due to truncation\n *\n * @param wei Value in wei (as bigint, string, or number)\n * @param decimals Number of decimal places to display (default: 4)\n * @returns Formatted ETH value as string\n * @example\n * ```typescript\n * // Standard conversions\n * formatEth(1000000000000000000n) // Returns: \"1.0000\"\n * formatEth(1500000000000000000n, 2) // Returns: \"1.50\"\n * formatEth(\"2000000000000000000\") // Returns: \"2.0000\"\n *\n * // Edge cases\n * formatEth(1000000000000000n) // Returns: \"0.0010\" (0.001 ETH)\n * formatEth(100000000000000n) // Returns: \"0.0001\"\n * formatEth(10000000000000n) // Returns: \"0.0000\" (truncated)\n * formatEth(-1000000000000000000n) // Returns: \"-1.000\"\n * ```\n */\nexport function formatEth(wei: bigint | string | number, decimals = 4): string {\n  return formatEther(BigInt(wei.toString())).slice(0, decimals + 2);\n}\n\n/**\n * Format a token amount based on its decimals\n *\n * @remarks\n * Generic token formatter that handles any ERC20-style token with\n * configurable decimal places. Most tokens use 18 decimals like ETH,\n * but some use different values (e.g., USDC uses 6).\n *\n * @param amount Raw token amount\n * @param decimals Token decimals (default: 18)\n * @param displayDecimals Decimals to show in formatted output (default: 4)\n * @returns Formatted token amount as string\n * @example\n * ```typescript\n * // 18 decimal token (like ETH)\n * formatToken(1000000000000000000n) // Returns: \"1.0000\"\n * formatToken(1500000000000000000n, 18, 2) // Returns: \"1.50\"\n *\n * // 6 decimal token (like USDC)\n * formatToken(1000000n, 6) // Returns: \"1.0000\"\n * formatToken(1500000n, 6, 2) // Returns: \"1.50\"\n *\n * // Whole numbers\n * formatToken(5000000000000000000n) // Returns: \"5\"\n * formatToken(5123456789000000000n, 18, 6) // Returns: \"5.123456\"\n * ```\n */\nexport function formatToken(\n  amount: bigint | string | number,\n  decimals = 18,\n  displayDecimals = 4,\n): string {\n  const value = formatUnits(BigInt(amount.toString()), decimals);\n  const parts = value.split(\".\");\n\n  if (parts.length === 1) {\n    return parts[0];\n  }\n\n  return `${parts[0]}.${parts[1].slice(0, displayDecimals)}`;\n}\n\n/**\n * Format an address for display (showing first 6 and last 4 characters)\n *\n * @remarks\n * Creates a human-readable abbreviated version of Ethereum addresses\n * for UI display. Preserves enough characters to maintain uniqueness\n * while saving screen space. Does not validate address format.\n *\n * **Edge Cases:**\n * - Addresses shorter than 10 characters are returned unchanged\n * - Works with both checksummed and lowercase addresses\n * - Does not validate address format\n *\n * @param address EVM address\n * @returns Shortened address string\n * @example\n * ```typescript\n * // Standard addresses\n * shortenAddress(\"0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36\")\n * // Returns: \"0x742d...Bd36\"\n *\n * // Checksummed address\n * shortenAddress(\"0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36\")\n * // Returns: \"0x742d...Bd36\"\n *\n * // Edge cases\n * shortenAddress(\"0x123\") // Returns: \"0x123\" (too short)\n * shortenAddress(\"\") // Returns: \"\"\n * shortenAddress(\"not-an-address\") // Returns: \"not-an...ress\"\n * ```\n */\nexport function shortenAddress(address: string): string {\n  if (!address || address.length < 10) return address;\n  return `${address.slice(0, 6)}...${address.slice(-4)}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAyC;AA2BlC,SAAS,aAAa,OAAyC;AACpE,SAAO,OAAO,KAAK;AACrB;AAiCO,SAAS,UAAU,KAA+B,WAAW,GAAW;AAC7E,aAAO,yBAAY,OAAO,IAAI,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;AAClE;AA6BO,SAAS,YACd,QACA,WAAW,IACX,kBAAkB,GACV;AACR,QAAM,YAAQ,yBAAY,OAAO,OAAO,SAAS,CAAC,GAAG,QAAQ;AAC7D,QAAM,QAAQ,MAAM,MAAM,GAAG;AAE7B,MAAI,MAAM,WAAW,GAAG;AACtB,WAAO,MAAM,CAAC;AAAA,EAChB;AAEA,SAAO,GAAG,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;AAC1D;AAiCO,SAAS,eAAe,SAAyB;AACtD,MAAI,CAAC,WAAW,QAAQ,SAAS,GAAI,QAAO;AAC5C,SAAO,GAAG,QAAQ,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,MAAM,EAAE,CAAC;AACtD;","names":[]}

package/dist/utils/formatters.d.cts

@@ -0,0 +1,120 @@
+/**
+ * Format a bigint or BigNumber to a regular number
+ *
+ * @remarks
+ * This function converts blockchain-specific large number types to standard JavaScript
+ * numbers. Use with caution for values that may exceed safe integer range.
+ *
+ * **Edge Cases:**
+ * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision
+ * - Negative values are supported
+ * - String values must be valid numeric strings or will return NaN
+ *
+ * @param value BigInt, BigNumber or numeric string to convert
+ * @returns Regular JavaScript number
+ * @example
+ * ```typescript
+ * formatNumber(1000000000000000000n) // Returns: 1000000000000000000
+ * formatNumber("123456789") // Returns: 123456789
+ * formatNumber(-100n) // Returns: -100
+ *
+ * // Precision loss example:
+ * const bigValue = 9007199254740993n; // MAX_SAFE_INTEGER + 2
+ * formatNumber(bigValue) // Returns: 9007199254740992 (lost precision)
+ * ```
+ */
+declare function formatNumber(value: bigint | string | number): number;
+/**
+ * Format wei value to ETH with specified decimal places
+ *
+ * @remarks
+ * Converts wei (smallest ETH unit) to human-readable ETH format.
+ * 1 ETH = 10^18 wei. The function truncates rather than rounds
+ * to ensure predictable display in financial contexts.
+ *
+ * **Edge Cases:**
+ * - Truncates (not rounds) to specified decimal places
+ * - Negative values are supported
+ * - Zero values return "0.0000" (based on decimals)
+ * - Very small values may display as "0.0000" due to truncation
+ *
+ * @param wei Value in wei (as bigint, string, or number)
+ * @param decimals Number of decimal places to display (default: 4)
+ * @returns Formatted ETH value as string
+ * @example
+ * ```typescript
+ * // Standard conversions
+ * formatEth(1000000000000000000n) // Returns: "1.0000"
+ * formatEth(1500000000000000000n, 2) // Returns: "1.50"
+ * formatEth("2000000000000000000") // Returns: "2.0000"
+ *
+ * // Edge cases
+ * formatEth(1000000000000000n) // Returns: "0.0010" (0.001 ETH)
+ * formatEth(100000000000000n) // Returns: "0.0001"
+ * formatEth(10000000000000n) // Returns: "0.0000" (truncated)
+ * formatEth(-1000000000000000000n) // Returns: "-1.000"
+ * ```
+ */
+declare function formatEth(wei: bigint | string | number, decimals?: number): string;
+/**
+ * Format a token amount based on its decimals
+ *
+ * @remarks
+ * Generic token formatter that handles any ERC20-style token with
+ * configurable decimal places. Most tokens use 18 decimals like ETH,
+ * but some use different values (e.g., USDC uses 6).
+ *
+ * @param amount Raw token amount
+ * @param decimals Token decimals (default: 18)
+ * @param displayDecimals Decimals to show in formatted output (default: 4)
+ * @returns Formatted token amount as string
+ * @example
+ * ```typescript
+ * // 18 decimal token (like ETH)
+ * formatToken(1000000000000000000n) // Returns: "1.0000"
+ * formatToken(1500000000000000000n, 18, 2) // Returns: "1.50"
+ *
+ * // 6 decimal token (like USDC)
+ * formatToken(1000000n, 6) // Returns: "1.0000"
+ * formatToken(1500000n, 6, 2) // Returns: "1.50"
+ *
+ * // Whole numbers
+ * formatToken(5000000000000000000n) // Returns: "5"
+ * formatToken(5123456789000000000n, 18, 6) // Returns: "5.123456"
+ * ```
+ */
+declare function formatToken(amount: bigint | string | number, decimals?: number, displayDecimals?: number): string;
+/**
+ * Format an address for display (showing first 6 and last 4 characters)
+ *
+ * @remarks
+ * Creates a human-readable abbreviated version of Ethereum addresses
+ * for UI display. Preserves enough characters to maintain uniqueness
+ * while saving screen space. Does not validate address format.
+ *
+ * **Edge Cases:**
+ * - Addresses shorter than 10 characters are returned unchanged
+ * - Works with both checksummed and lowercase addresses
+ * - Does not validate address format
+ *
+ * @param address EVM address
+ * @returns Shortened address string
+ * @example
+ * ```typescript
+ * // Standard addresses
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Checksummed address
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Edge cases
+ * shortenAddress("0x123") // Returns: "0x123" (too short)
+ * shortenAddress("") // Returns: ""
+ * shortenAddress("not-an-address") // Returns: "not-an...ress"
+ * ```
+ */
+declare function shortenAddress(address: string): string;
+
+export { formatEth, formatNumber, formatToken, shortenAddress };

package/dist/utils/formatters.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Format a bigint or BigNumber to a regular number
+ *
+ * @remarks
+ * This function converts blockchain-specific large number types to standard JavaScript
+ * numbers. Use with caution for values that may exceed safe integer range.
+ *
+ * **Edge Cases:**
+ * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision
+ * - Negative values are supported
+ * - String values must be valid numeric strings or will return NaN
+ *
+ * @param value BigInt, BigNumber or numeric string to convert
+ * @returns Regular JavaScript number
+ * @example
+ * ```typescript
+ * formatNumber(1000000000000000000n) // Returns: 1000000000000000000
+ * formatNumber("123456789") // Returns: 123456789
+ * formatNumber(-100n) // Returns: -100
+ *
+ * // Precision loss example:
+ * const bigValue = 9007199254740993n; // MAX_SAFE_INTEGER + 2
+ * formatNumber(bigValue) // Returns: 9007199254740992 (lost precision)
+ * ```
+ */
+declare function formatNumber(value: bigint | string | number): number;
+/**
+ * Format wei value to ETH with specified decimal places
+ *
+ * @remarks
+ * Converts wei (smallest ETH unit) to human-readable ETH format.
+ * 1 ETH = 10^18 wei. The function truncates rather than rounds
+ * to ensure predictable display in financial contexts.
+ *
+ * **Edge Cases:**
+ * - Truncates (not rounds) to specified decimal places
+ * - Negative values are supported
+ * - Zero values return "0.0000" (based on decimals)
+ * - Very small values may display as "0.0000" due to truncation
+ *
+ * @param wei Value in wei (as bigint, string, or number)
+ * @param decimals Number of decimal places to display (default: 4)
+ * @returns Formatted ETH value as string
+ * @example
+ * ```typescript
+ * // Standard conversions
+ * formatEth(1000000000000000000n) // Returns: "1.0000"
+ * formatEth(1500000000000000000n, 2) // Returns: "1.50"
+ * formatEth("2000000000000000000") // Returns: "2.0000"
+ *
+ * // Edge cases
+ * formatEth(1000000000000000n) // Returns: "0.0010" (0.001 ETH)
+ * formatEth(100000000000000n) // Returns: "0.0001"
+ * formatEth(10000000000000n) // Returns: "0.0000" (truncated)
+ * formatEth(-1000000000000000000n) // Returns: "-1.000"
+ * ```
+ */
+declare function formatEth(wei: bigint | string | number, decimals?: number): string;
+/**
+ * Format a token amount based on its decimals
+ *
+ * @remarks
+ * Generic token formatter that handles any ERC20-style token with
+ * configurable decimal places. Most tokens use 18 decimals like ETH,
+ * but some use different values (e.g., USDC uses 6).
+ *
+ * @param amount Raw token amount
+ * @param decimals Token decimals (default: 18)
+ * @param displayDecimals Decimals to show in formatted output (default: 4)
+ * @returns Formatted token amount as string
+ * @example
+ * ```typescript
+ * // 18 decimal token (like ETH)
+ * formatToken(1000000000000000000n) // Returns: "1.0000"
+ * formatToken(1500000000000000000n, 18, 2) // Returns: "1.50"
+ *
+ * // 6 decimal token (like USDC)
+ * formatToken(1000000n, 6) // Returns: "1.0000"
+ * formatToken(1500000n, 6, 2) // Returns: "1.50"
+ *
+ * // Whole numbers
+ * formatToken(5000000000000000000n) // Returns: "5"
+ * formatToken(5123456789000000000n, 18, 6) // Returns: "5.123456"
+ * ```
+ */
+declare function formatToken(amount: bigint | string | number, decimals?: number, displayDecimals?: number): string;
+/**
+ * Format an address for display (showing first 6 and last 4 characters)
+ *
+ * @remarks
+ * Creates a human-readable abbreviated version of Ethereum addresses
+ * for UI display. Preserves enough characters to maintain uniqueness
+ * while saving screen space. Does not validate address format.
+ *
+ * **Edge Cases:**
+ * - Addresses shorter than 10 characters are returned unchanged
+ * - Works with both checksummed and lowercase addresses
+ * - Does not validate address format
+ *
+ * @param address EVM address
+ * @returns Shortened address string
+ * @example
+ * ```typescript
+ * // Standard addresses
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Checksummed address
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Edge cases
+ * shortenAddress("0x123") // Returns: "0x123" (too short)
+ * shortenAddress("") // Returns: ""
+ * shortenAddress("not-an-address") // Returns: "not-an...ress"
+ * ```
+ */
+declare function shortenAddress(address: string): string;
+
+export { formatEth, formatNumber, formatToken, shortenAddress };

package/dist/utils/formatters.js

@@ -0,0 +1,26 @@
+import { formatEther, formatUnits } from "viem";
+function formatNumber(value) {
+  return Number(value);
+}
+function formatEth(wei, decimals = 4) {
+  return formatEther(BigInt(wei.toString())).slice(0, decimals + 2);
+}
+function formatToken(amount, decimals = 18, displayDecimals = 4) {
+  const value = formatUnits(BigInt(amount.toString()), decimals);
+  const parts = value.split(".");
+  if (parts.length === 1) {
+    return parts[0];
+  }
+  return `${parts[0]}.${parts[1].slice(0, displayDecimals)}`;
+}
+function shortenAddress(address) {
+  if (!address || address.length < 10) return address;
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+export {
+  formatEth,
+  formatNumber,
+  formatToken,
+  shortenAddress
+};
+//# sourceMappingURL=formatters.js.map

package/dist/utils/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/formatters.ts"],"sourcesContent":["import { formatEther, formatUnits } from \"viem\";\n\n/**\n * Format a bigint or BigNumber to a regular number\n *\n * @remarks\n * This function converts blockchain-specific large number types to standard JavaScript\n * numbers. Use with caution for values that may exceed safe integer range.\n *\n * **Edge Cases:**\n * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision\n * - Negative values are supported\n * - String values must be valid numeric strings or will return NaN\n *\n * @param value BigInt, BigNumber or numeric string to convert\n * @returns Regular JavaScript number\n * @example\n * ```typescript\n * formatNumber(1000000000000000000n) // Returns: 1000000000000000000\n * formatNumber(\"123456789\") // Returns: 123456789\n * formatNumber(-100n) // Returns: -100\n *\n * // Precision loss example:\n * const bigValue = 9007199254740993n; // MAX_SAFE_INTEGER + 2\n * formatNumber(bigValue) // Returns: 9007199254740992 (lost precision)\n * ```\n */\nexport function formatNumber(value: bigint | string | number): number {\n  return Number(value);\n}\n\n/**\n * Format wei value to ETH with specified decimal places\n *\n * @remarks\n * Converts wei (smallest ETH unit) to human-readable ETH format.\n * 1 ETH = 10^18 wei. The function truncates rather than rounds\n * to ensure predictable display in financial contexts.\n *\n * **Edge Cases:**\n * - Truncates (not rounds) to specified decimal places\n * - Negative values are supported\n * - Zero values return \"0.0000\" (based on decimals)\n * - Very small values may display as \"0.0000\" due to truncation\n *\n * @param wei Value in wei (as bigint, string, or number)\n * @param decimals Number of decimal places to display (default: 4)\n * @returns Formatted ETH value as string\n * @example\n * ```typescript\n * // Standard conversions\n * formatEth(1000000000000000000n) // Returns: \"1.0000\"\n * formatEth(1500000000000000000n, 2) // Returns: \"1.50\"\n * formatEth(\"2000000000000000000\") // Returns: \"2.0000\"\n *\n * // Edge cases\n * formatEth(1000000000000000n) // Returns: \"0.0010\" (0.001 ETH)\n * formatEth(100000000000000n) // Returns: \"0.0001\"\n * formatEth(10000000000000n) // Returns: \"0.0000\" (truncated)\n * formatEth(-1000000000000000000n) // Returns: \"-1.000\"\n * ```\n */\nexport function formatEth(wei: bigint | string | number, decimals = 4): string {\n  return formatEther(BigInt(wei.toString())).slice(0, decimals + 2);\n}\n\n/**\n * Format a token amount based on its decimals\n *\n * @remarks\n * Generic token formatter that handles any ERC20-style token with\n * configurable decimal places. Most tokens use 18 decimals like ETH,\n * but some use different values (e.g., USDC uses 6).\n *\n * @param amount Raw token amount\n * @param decimals Token decimals (default: 18)\n * @param displayDecimals Decimals to show in formatted output (default: 4)\n * @returns Formatted token amount as string\n * @example\n * ```typescript\n * // 18 decimal token (like ETH)\n * formatToken(1000000000000000000n) // Returns: \"1.0000\"\n * formatToken(1500000000000000000n, 18, 2) // Returns: \"1.50\"\n *\n * // 6 decimal token (like USDC)\n * formatToken(1000000n, 6) // Returns: \"1.0000\"\n * formatToken(1500000n, 6, 2) // Returns: \"1.50\"\n *\n * // Whole numbers\n * formatToken(5000000000000000000n) // Returns: \"5\"\n * formatToken(5123456789000000000n, 18, 6) // Returns: \"5.123456\"\n * ```\n */\nexport function formatToken(\n  amount: bigint | string | number,\n  decimals = 18,\n  displayDecimals = 4,\n): string {\n  const value = formatUnits(BigInt(amount.toString()), decimals);\n  const parts = value.split(\".\");\n\n  if (parts.length === 1) {\n    return parts[0];\n  }\n\n  return `${parts[0]}.${parts[1].slice(0, displayDecimals)}`;\n}\n\n/**\n * Format an address for display (showing first 6 and last 4 characters)\n *\n * @remarks\n * Creates a human-readable abbreviated version of Ethereum addresses\n * for UI display. Preserves enough characters to maintain uniqueness\n * while saving screen space. Does not validate address format.\n *\n * **Edge Cases:**\n * - Addresses shorter than 10 characters are returned unchanged\n * - Works with both checksummed and lowercase addresses\n * - Does not validate address format\n *\n * @param address EVM address\n * @returns Shortened address string\n * @example\n * ```typescript\n * // Standard addresses\n * shortenAddress(\"0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36\")\n * // Returns: \"0x742d...Bd36\"\n *\n * // Checksummed address\n * shortenAddress(\"0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36\")\n * // Returns: \"0x742d...Bd36\"\n *\n * // Edge cases\n * shortenAddress(\"0x123\") // Returns: \"0x123\" (too short)\n * shortenAddress(\"\") // Returns: \"\"\n * shortenAddress(\"not-an-address\") // Returns: \"not-an...ress\"\n * ```\n */\nexport function shortenAddress(address: string): string {\n  if (!address || address.length < 10) return address;\n  return `${address.slice(0, 6)}...${address.slice(-4)}`;\n}\n"],"mappings":"AAAA,SAAS,aAAa,mBAAmB;AA2BlC,SAAS,aAAa,OAAyC;AACpE,SAAO,OAAO,KAAK;AACrB;AAiCO,SAAS,UAAU,KAA+B,WAAW,GAAW;AAC7E,SAAO,YAAY,OAAO,IAAI,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;AAClE;AA6BO,SAAS,YACd,QACA,WAAW,IACX,kBAAkB,GACV;AACR,QAAM,QAAQ,YAAY,OAAO,OAAO,SAAS,CAAC,GAAG,QAAQ;AAC7D,QAAM,QAAQ,MAAM,MAAM,GAAG;AAE7B,MAAI,MAAM,WAAW,GAAG;AACtB,WAAO,MAAM,CAAC;AAAA,EAChB;AAEA,SAAO,GAAG,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;AAC1D;AAiCO,SAAS,eAAe,SAAyB;AACtD,MAAI,CAAC,WAAW,QAAQ,SAAS,GAAI,QAAO;AAC5C,SAAO,GAAG,QAAQ,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,MAAM,EAAE,CAAC;AACtD;","names":[]}