@chillwhales/lsp2 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chillwhales contributors
+
+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,45 @@
+# @chillwhales/lsp2
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+LSP2 ERC725Y JSON Schema — shared primitives, VerifiableURI encoding/decoding, and image utilities for LUKSO dApps.
+
+## Install
+
+```bash
+pnpm add @chillwhales/lsp2
+```
+
+> **Peer dependency:** This package requires [`viem`](https://viem.sh) ^2.0.0
+>
+> ```bash
+> pnpm add viem
+> ```
+
+## Usage
+
+```typescript
+import { encodeVerifiableUri, parseVerifiableUri } from "@chillwhales/lsp2";
+
+// Encode metadata as a VerifiableURI for on-chain storage
+const metadata = {
+  LSP4Metadata: { name: "My Token", description: "A LUKSO token" },
+};
+const encoded = encodeVerifiableUri(metadata, "ipfs://QmYwAPJz...");
+// encoded is a hex string ready for setData()
+
+// Later, read back from on-chain and parse the components
+const { verificationMethod, verificationData, url } =
+  parseVerifiableUri(encoded);
+console.log(url); // "ipfs://QmYwAPJz..."
+```
+
+> **Spec:** [LSP-2 ERC725Y JSON Schema](https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md)
+
+## API
+
+Types are exported and available in your editor via TypeScript IntelliSense.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,423 @@
+import { z } from 'zod';
+import { Hex } from 'viem';
+
+/**
+ * LSP2 ERC725Y JSON Schema Constants
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+/**
+ * LSP2 VerifiableURI verification methods
+ */
+declare enum VERIFICATION_METHODS {
+    HASH_KECCAK256_UTF8 = "keccak256(utf8)",
+    HASH_KECCAK256_BYTES = "keccak256(bytes)",
+    ECDSA = "ecdsa"
+}
+/** Separator used in LSP2 mapping keys */
+declare const MAPPING_SEPARATOR = "0x0000";
+/**
+ * Verification method ID for keccak256(bytes)
+ * Computed as: bytes4(keccak256('keccak256(bytes)')) = 0x8019f9b1
+ */
+declare const KECCAK256_BYTES_METHOD_ID: "0x8019f9b1";
+/**
+ * Reserved bytes prefix (2 bytes of zeros) for VerifiableURI
+ */
+declare const RESERVED_PREFIX: "0x0000";
+/**
+ * Length of a keccak256 hash in bytes (32 bytes = 0x0020)
+ */
+declare const HASH_LENGTH_PREFIX: "0x0020";
+/**
+ * Minimum length of a valid VerifiableURI value in bytes
+ * 2 (reserved) + 4 (method ID) + 2 (hash length) + 32 (hash) = 40 bytes = 80 hex chars + '0x'
+ */
+declare const MIN_VERIFIABLE_URI_LENGTH = 82;
+
+/**
+ * LSP2 Shared Primitive Schemas
+ *
+ * Reusable Zod schemas for LSP2/LSP3/LSP4 metadata validation.
+ * These are the foundation schemas that downstream packages depend on.
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+
+/**
+ * Validates an Ethereum address (0x... format)
+ */
+declare const addressSchema: z.ZodString;
+/**
+ * Validates a 32-byte hex string (0x + 64 chars)
+ */
+declare const bytes32Schema: z.ZodString;
+/**
+ * Validates any hex string (0x...)
+ */
+declare const bytesSchema: z.ZodString;
+/**
+ * Verification data schema for LSP2 ERC725YJSONSchema
+ */
+declare const verificationSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+    data: z.ZodString;
+    method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+}, "strip", z.ZodTypeAny, {
+    method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+    data: string;
+}, {
+    method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+    data: string;
+}>, z.ZodObject<{
+    method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+    /** Signer address */
+    data: z.ZodString;
+    /** URL where the signature can be retrieved */
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    method: VERIFICATION_METHODS.ECDSA;
+    data: string;
+    source: string;
+}, {
+    method: VERIFICATION_METHODS.ECDSA;
+    data: string;
+    source: string;
+}>]>;
+/**
+ * Image metadata schema (LSP3/LSP4)
+ */
+declare const imageSchema: z.ZodObject<{
+    url: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        data: z.ZodString;
+        method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }>, z.ZodObject<{
+        method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+        /** Signer address */
+        data: z.ZodString;
+        /** URL where the signature can be retrieved */
+        source: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    width: number;
+    height: number;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+}, {
+    url: string;
+    width: number;
+    height: number;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+}>;
+/**
+ * Asset metadata schema (LSP3/LSP4)
+ */
+declare const assetSchema: z.ZodObject<{
+    url: z.ZodString;
+    fileType: z.ZodString;
+    verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        data: z.ZodString;
+        method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }>, z.ZodObject<{
+        method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+        /** Signer address */
+        data: z.ZodString;
+        /** URL where the signature can be retrieved */
+        source: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+    fileType: string;
+}, {
+    url: string;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+    fileType: string;
+}>;
+/**
+ * Link schema (LSP3/LSP4)
+ */
+declare const linkSchema: z.ZodObject<{
+    title: z.ZodString;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    title: string;
+}, {
+    url: string;
+    title: string;
+}>;
+/**
+ * Tag schema (LSP3/LSP4)
+ */
+declare const tagSchema: z.ZodString;
+
+/**
+ * LSP2 Type Guards
+ *
+ * Runtime type guards using Zod schema validation.
+ */
+
+/**
+ * Type guard for image schema
+ */
+declare function isImageSchema(obj: unknown): obj is z.infer<typeof imageSchema>;
+/**
+ * Type guard for link schema
+ */
+declare function isLinkSchema(obj: unknown): obj is z.infer<typeof linkSchema>;
+/**
+ * Type guard for tag schema
+ */
+declare function isTagSchema(obj: unknown): obj is z.infer<typeof tagSchema>;
+/**
+ * Type guard for asset schema
+ */
+declare function isAssetSchema(obj: unknown): obj is z.infer<typeof assetSchema>;
+
+/**
+ * LSP2 Inferred Types
+ *
+ * TypeScript types inferred from LSP2 Zod schemas.
+ */
+
+type Verification = z.infer<typeof verificationSchema>;
+type Image = z.infer<typeof imageSchema>;
+type ImagesArray = Image[];
+type ImagesMatrix = ImagesArray[];
+type Asset = z.infer<typeof assetSchema>;
+type Link = z.infer<typeof linkSchema>;
+type Tag = z.infer<typeof tagSchema>;
+
+/**
+ * LSP2 Image Utilities
+ *
+ * Functions for finding optimal images from LSP metadata arrays.
+ * Used by downstream LSP3/LSP4 packages for profile and asset images.
+ */
+
+/**
+ * Image size in pixels
+ */
+interface ImageSize {
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Find the best matching image from an array based on target dimensions.
+ * If no dimensions provided, returns the first image.
+ *
+ * @param images - Array of images with url, width, height
+ * @param options - Optional target dimensions
+ * @returns The best matching image or undefined
+ */
+declare function findBestImage(images: Image[] | undefined, options?: Partial<ImageSize>): Image | undefined;
+/**
+ * Finds the image closest to the target resolution
+ *
+ * Uses Euclidean distance in resolution space.
+ *
+ * @param images - Array of image objects
+ * @param targetWidth - Target width
+ * @param targetHeight - Target height
+ * @returns The closest image object or null if no images provided
+ */
+declare function findClosestImage(images: Image[], targetWidth: number, targetHeight: number): Image | null;
+
+/**
+ * LSP2 VerifiableURI Encoding/Decoding Utilities
+ *
+ * Pure functions for encoding and decoding VerifiableURI values according to
+ * the LSP2 ERC725Y JSON Schema specification.
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+
+/**
+ * Parsed components of a VerifiableURI
+ */
+interface ParsedVerifiableUri {
+    /** Verification method ID (e.g., 0x6f357c6a for keccak256(bytes)) */
+    verificationMethod: Hex;
+    /** Verification hash (32 bytes) */
+    verificationData: Hex;
+    /** The URL pointing to the content (e.g., ipfs://Qm...) */
+    url: string;
+}
+/**
+ * Result of decoding a VerifiableURI
+ */
+interface DecodedVerifiableUri<T> {
+    /** The parsed and validated data */
+    data: T;
+    /** The URL extracted from the VerifiableURI */
+    url: string;
+}
+/**
+ * Encodes data as a VerifiableURI value
+ *
+ * Creates an ERC725Y-compatible VerifiableURI encoding with:
+ * - 2 bytes reserved (0x0000)
+ * - 4 bytes verification method ID (keccak256(bytes)) = 0x8019f9b1
+ * - 2 bytes verification data length (0x0020 = 32)
+ * - 32 bytes verification hash
+ * - UTF-8 encoded URL
+ *
+ * @param data - Any JSON-serializable object to encode
+ * @param ipfsUrl - IPFS URL where the JSON will be stored (e.g., "ipfs://Qm...")
+ * @returns Hex-encoded VerifiableURI value
+ *
+ * @example
+ * ```typescript
+ * import { encodeVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * const metadata = { LSP4Metadata: { name: 'My Token', description: 'A token' } };
+ * const value = encodeVerifiableUri(metadata, 'ipfs://QmXyz...');
+ * // Use with setData operation
+ * ```
+ */
+declare function encodeVerifiableUri<T>(data: T, ipfsUrl: string): Hex;
+/**
+ * Parses a VerifiableURI hex value into its components
+ *
+ * Format: 0x + reserved (2 bytes) + method (4 bytes) + length (2 bytes) + hash (N bytes) + url
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @returns Parsed components (method, hash, url)
+ * @throws Error if the value is malformed
+ *
+ * @example
+ * ```typescript
+ * import { parseVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * const { verificationMethod, verificationData, url } = parseVerifiableUri(rawValue);
+ * console.log(url); // 'ipfs://Qm...'
+ * ```
+ */
+declare function parseVerifiableUri(value: Hex): ParsedVerifiableUri;
+/**
+ * Decodes a VerifiableURI value and validates the content
+ *
+ * @param verifiableUriValue - The raw hex value from ERC725Y getData
+ * @param jsonContent - The JSON content fetched from the URL
+ * @param schema - Optional Zod schema for type validation
+ * @returns Decoded data and URL
+ * @throws Error if hash doesn't match or schema validation fails
+ *
+ * @example
+ * ```typescript
+ * import { decodeVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * // Fetch JSON from IPFS first
+ * const jsonContent = await fetchFromIpfs(url);
+ *
+ * // Decode with schema validation
+ * const { data, url } = decodeVerifiableUri(
+ *   rawValue,
+ *   jsonContent,
+ *   mySchema
+ * );
+ *
+ * // Decode without schema (caller handles typing)
+ * const { data: rawData } = decodeVerifiableUri<MyType>(rawValue, jsonContent);
+ * ```
+ */
+declare function decodeVerifiableUri<T>(verifiableUriValue: Hex, jsonContent: string, schema?: z.ZodSchema<T>): DecodedVerifiableUri<T>;
+/**
+ * Computes the verification hash for JSON data
+ *
+ * Useful when you need to compute the hash without encoding the full VerifiableURI.
+ *
+ * @param data - Any JSON-serializable object
+ * @returns The keccak256 hash as a Hex string
+ *
+ * @example
+ * ```typescript
+ * import { computeVerificationHash } from '@chillwhales/lsp2';
+ *
+ * const hash = computeVerificationHash({ name: 'My Profile' });
+ * // Use for verification or comparison
+ * ```
+ */
+declare function computeVerificationHash<T>(data: T): Hex;
+/**
+ * Checks if a hex value appears to be a valid VerifiableURI format
+ *
+ * This is a quick check based on structure, not content validation.
+ *
+ * @param value - Hex value to check
+ * @returns true if the value has valid VerifiableURI structure
+ *
+ * @example
+ * ```typescript
+ * import { isVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * if (isVerifiableUri(rawValue)) {
+ *   const { url } = parseVerifiableUri(rawValue);
+ * }
+ * ```
+ */
+declare function isVerifiableUri(value: Hex): boolean;
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, MAPPING_SEPARATOR, MIN_VERIFIABLE_URI_LENGTH, RESERVED_PREFIX, VERIFICATION_METHODS, addressSchema, assetSchema, bytes32Schema, bytesSchema, computeVerificationHash, decodeVerifiableUri, encodeVerifiableUri, findBestImage, findClosestImage, imageSchema, isAssetSchema, isImageSchema, isLinkSchema, isTagSchema, isVerifiableUri, linkSchema, parseVerifiableUri, tagSchema, verificationSchema };
+export type { Asset, DecodedVerifiableUri, Image, ImageSize, ImagesArray, ImagesMatrix, Link, ParsedVerifiableUri, Tag, Verification };

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+import { z } from 'zod';
+import { Hex } from 'viem';
+
+/**
+ * LSP2 ERC725Y JSON Schema Constants
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+/**
+ * LSP2 VerifiableURI verification methods
+ */
+declare enum VERIFICATION_METHODS {
+    HASH_KECCAK256_UTF8 = "keccak256(utf8)",
+    HASH_KECCAK256_BYTES = "keccak256(bytes)",
+    ECDSA = "ecdsa"
+}
+/** Separator used in LSP2 mapping keys */
+declare const MAPPING_SEPARATOR = "0x0000";
+/**
+ * Verification method ID for keccak256(bytes)
+ * Computed as: bytes4(keccak256('keccak256(bytes)')) = 0x8019f9b1
+ */
+declare const KECCAK256_BYTES_METHOD_ID: "0x8019f9b1";
+/**
+ * Reserved bytes prefix (2 bytes of zeros) for VerifiableURI
+ */
+declare const RESERVED_PREFIX: "0x0000";
+/**
+ * Length of a keccak256 hash in bytes (32 bytes = 0x0020)
+ */
+declare const HASH_LENGTH_PREFIX: "0x0020";
+/**
+ * Minimum length of a valid VerifiableURI value in bytes
+ * 2 (reserved) + 4 (method ID) + 2 (hash length) + 32 (hash) = 40 bytes = 80 hex chars + '0x'
+ */
+declare const MIN_VERIFIABLE_URI_LENGTH = 82;
+
+/**
+ * LSP2 Shared Primitive Schemas
+ *
+ * Reusable Zod schemas for LSP2/LSP3/LSP4 metadata validation.
+ * These are the foundation schemas that downstream packages depend on.
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+
+/**
+ * Validates an Ethereum address (0x... format)
+ */
+declare const addressSchema: z.ZodString;
+/**
+ * Validates a 32-byte hex string (0x + 64 chars)
+ */
+declare const bytes32Schema: z.ZodString;
+/**
+ * Validates any hex string (0x...)
+ */
+declare const bytesSchema: z.ZodString;
+/**
+ * Verification data schema for LSP2 ERC725YJSONSchema
+ */
+declare const verificationSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+    data: z.ZodString;
+    method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+}, "strip", z.ZodTypeAny, {
+    method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+    data: string;
+}, {
+    method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+    data: string;
+}>, z.ZodObject<{
+    method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+    /** Signer address */
+    data: z.ZodString;
+    /** URL where the signature can be retrieved */
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    method: VERIFICATION_METHODS.ECDSA;
+    data: string;
+    source: string;
+}, {
+    method: VERIFICATION_METHODS.ECDSA;
+    data: string;
+    source: string;
+}>]>;
+/**
+ * Image metadata schema (LSP3/LSP4)
+ */
+declare const imageSchema: z.ZodObject<{
+    url: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        data: z.ZodString;
+        method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }>, z.ZodObject<{
+        method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+        /** Signer address */
+        data: z.ZodString;
+        /** URL where the signature can be retrieved */
+        source: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    width: number;
+    height: number;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+}, {
+    url: string;
+    width: number;
+    height: number;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+}>;
+/**
+ * Asset metadata schema (LSP3/LSP4)
+ */
+declare const assetSchema: z.ZodObject<{
+    url: z.ZodString;
+    fileType: z.ZodString;
+    verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        data: z.ZodString;
+        method: z.ZodEnum<[VERIFICATION_METHODS.HASH_KECCAK256_BYTES, VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }, {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    }>, z.ZodObject<{
+        method: z.ZodEnum<[VERIFICATION_METHODS.ECDSA]>;
+        /** Signer address */
+        data: z.ZodString;
+        /** URL where the signature can be retrieved */
+        source: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }, {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+    fileType: string;
+}, {
+    url: string;
+    verification: {
+        method: VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+        data: string;
+    } | {
+        method: VERIFICATION_METHODS.ECDSA;
+        data: string;
+        source: string;
+    };
+    fileType: string;
+}>;
+/**
+ * Link schema (LSP3/LSP4)
+ */
+declare const linkSchema: z.ZodObject<{
+    title: z.ZodString;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    title: string;
+}, {
+    url: string;
+    title: string;
+}>;
+/**
+ * Tag schema (LSP3/LSP4)
+ */
+declare const tagSchema: z.ZodString;
+
+/**
+ * LSP2 Type Guards
+ *
+ * Runtime type guards using Zod schema validation.
+ */
+
+/**
+ * Type guard for image schema
+ */
+declare function isImageSchema(obj: unknown): obj is z.infer<typeof imageSchema>;
+/**
+ * Type guard for link schema
+ */
+declare function isLinkSchema(obj: unknown): obj is z.infer<typeof linkSchema>;
+/**
+ * Type guard for tag schema
+ */
+declare function isTagSchema(obj: unknown): obj is z.infer<typeof tagSchema>;
+/**
+ * Type guard for asset schema
+ */
+declare function isAssetSchema(obj: unknown): obj is z.infer<typeof assetSchema>;
+
+/**
+ * LSP2 Inferred Types
+ *
+ * TypeScript types inferred from LSP2 Zod schemas.
+ */
+
+type Verification = z.infer<typeof verificationSchema>;
+type Image = z.infer<typeof imageSchema>;
+type ImagesArray = Image[];
+type ImagesMatrix = ImagesArray[];
+type Asset = z.infer<typeof assetSchema>;
+type Link = z.infer<typeof linkSchema>;
+type Tag = z.infer<typeof tagSchema>;
+
+/**
+ * LSP2 Image Utilities
+ *
+ * Functions for finding optimal images from LSP metadata arrays.
+ * Used by downstream LSP3/LSP4 packages for profile and asset images.
+ */
+
+/**
+ * Image size in pixels
+ */
+interface ImageSize {
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Find the best matching image from an array based on target dimensions.
+ * If no dimensions provided, returns the first image.
+ *
+ * @param images - Array of images with url, width, height
+ * @param options - Optional target dimensions
+ * @returns The best matching image or undefined
+ */
+declare function findBestImage(images: Image[] | undefined, options?: Partial<ImageSize>): Image | undefined;
+/**
+ * Finds the image closest to the target resolution
+ *
+ * Uses Euclidean distance in resolution space.
+ *
+ * @param images - Array of image objects
+ * @param targetWidth - Target width
+ * @param targetHeight - Target height
+ * @returns The closest image object or null if no images provided
+ */
+declare function findClosestImage(images: Image[], targetWidth: number, targetHeight: number): Image | null;
+
+/**
+ * LSP2 VerifiableURI Encoding/Decoding Utilities
+ *
+ * Pure functions for encoding and decoding VerifiableURI values according to
+ * the LSP2 ERC725Y JSON Schema specification.
+ *
+ * @see https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md
+ */
+
+/**
+ * Parsed components of a VerifiableURI
+ */
+interface ParsedVerifiableUri {
+    /** Verification method ID (e.g., 0x6f357c6a for keccak256(bytes)) */
+    verificationMethod: Hex;
+    /** Verification hash (32 bytes) */
+    verificationData: Hex;
+    /** The URL pointing to the content (e.g., ipfs://Qm...) */
+    url: string;
+}
+/**
+ * Result of decoding a VerifiableURI
+ */
+interface DecodedVerifiableUri<T> {
+    /** The parsed and validated data */
+    data: T;
+    /** The URL extracted from the VerifiableURI */
+    url: string;
+}
+/**
+ * Encodes data as a VerifiableURI value
+ *
+ * Creates an ERC725Y-compatible VerifiableURI encoding with:
+ * - 2 bytes reserved (0x0000)
+ * - 4 bytes verification method ID (keccak256(bytes)) = 0x8019f9b1
+ * - 2 bytes verification data length (0x0020 = 32)
+ * - 32 bytes verification hash
+ * - UTF-8 encoded URL
+ *
+ * @param data - Any JSON-serializable object to encode
+ * @param ipfsUrl - IPFS URL where the JSON will be stored (e.g., "ipfs://Qm...")
+ * @returns Hex-encoded VerifiableURI value
+ *
+ * @example
+ * ```typescript
+ * import { encodeVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * const metadata = { LSP4Metadata: { name: 'My Token', description: 'A token' } };
+ * const value = encodeVerifiableUri(metadata, 'ipfs://QmXyz...');
+ * // Use with setData operation
+ * ```
+ */
+declare function encodeVerifiableUri<T>(data: T, ipfsUrl: string): Hex;
+/**
+ * Parses a VerifiableURI hex value into its components
+ *
+ * Format: 0x + reserved (2 bytes) + method (4 bytes) + length (2 bytes) + hash (N bytes) + url
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @returns Parsed components (method, hash, url)
+ * @throws Error if the value is malformed
+ *
+ * @example
+ * ```typescript
+ * import { parseVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * const { verificationMethod, verificationData, url } = parseVerifiableUri(rawValue);
+ * console.log(url); // 'ipfs://Qm...'
+ * ```
+ */
+declare function parseVerifiableUri(value: Hex): ParsedVerifiableUri;
+/**
+ * Decodes a VerifiableURI value and validates the content
+ *
+ * @param verifiableUriValue - The raw hex value from ERC725Y getData
+ * @param jsonContent - The JSON content fetched from the URL
+ * @param schema - Optional Zod schema for type validation
+ * @returns Decoded data and URL
+ * @throws Error if hash doesn't match or schema validation fails
+ *
+ * @example
+ * ```typescript
+ * import { decodeVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * // Fetch JSON from IPFS first
+ * const jsonContent = await fetchFromIpfs(url);
+ *
+ * // Decode with schema validation
+ * const { data, url } = decodeVerifiableUri(
+ *   rawValue,
+ *   jsonContent,
+ *   mySchema
+ * );
+ *
+ * // Decode without schema (caller handles typing)
+ * const { data: rawData } = decodeVerifiableUri<MyType>(rawValue, jsonContent);
+ * ```
+ */
+declare function decodeVerifiableUri<T>(verifiableUriValue: Hex, jsonContent: string, schema?: z.ZodSchema<T>): DecodedVerifiableUri<T>;
+/**
+ * Computes the verification hash for JSON data
+ *
+ * Useful when you need to compute the hash without encoding the full VerifiableURI.
+ *
+ * @param data - Any JSON-serializable object
+ * @returns The keccak256 hash as a Hex string
+ *
+ * @example
+ * ```typescript
+ * import { computeVerificationHash } from '@chillwhales/lsp2';
+ *
+ * const hash = computeVerificationHash({ name: 'My Profile' });
+ * // Use for verification or comparison
+ * ```
+ */
+declare function computeVerificationHash<T>(data: T): Hex;
+/**
+ * Checks if a hex value appears to be a valid VerifiableURI format
+ *
+ * This is a quick check based on structure, not content validation.
+ *
+ * @param value - Hex value to check
+ * @returns true if the value has valid VerifiableURI structure
+ *
+ * @example
+ * ```typescript
+ * import { isVerifiableUri } from '@chillwhales/lsp2';
+ *
+ * if (isVerifiableUri(rawValue)) {
+ *   const { url } = parseVerifiableUri(rawValue);
+ * }
+ * ```
+ */
+declare function isVerifiableUri(value: Hex): boolean;
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, MAPPING_SEPARATOR, MIN_VERIFIABLE_URI_LENGTH, RESERVED_PREFIX, VERIFICATION_METHODS, addressSchema, assetSchema, bytes32Schema, bytesSchema, computeVerificationHash, decodeVerifiableUri, encodeVerifiableUri, findBestImage, findClosestImage, imageSchema, isAssetSchema, isImageSchema, isLinkSchema, isTagSchema, isVerifiableUri, linkSchema, parseVerifiableUri, tagSchema, verificationSchema };
+export type { Asset, DecodedVerifiableUri, Image, ImageSize, ImagesArray, ImagesMatrix, Link, ParsedVerifiableUri, Tag, Verification };

package/dist/index.mjs

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { keccak256, stringToHex, concat, slice, hexToString } from 'viem';
+
+var VERIFICATION_METHODS = /* @__PURE__ */ ((VERIFICATION_METHODS2) => {
+  VERIFICATION_METHODS2["HASH_KECCAK256_UTF8"] = "keccak256(utf8)";
+  VERIFICATION_METHODS2["HASH_KECCAK256_BYTES"] = "keccak256(bytes)";
+  VERIFICATION_METHODS2["ECDSA"] = "ecdsa";
+  return VERIFICATION_METHODS2;
+})(VERIFICATION_METHODS || {});
+const MAPPING_SEPARATOR = "0x0000";
+const KECCAK256_BYTES_METHOD_ID = "0x8019f9b1";
+const RESERVED_PREFIX = "0x0000";
+const HASH_LENGTH_PREFIX = "0x0020";
+const MIN_VERIFIABLE_URI_LENGTH = 82;
+
+const EVM_ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
+const BYTES32_REGEX = /^0x[0-9a-fA-F]{64}$/;
+const BYTES_REGEX = /^0x[0-9a-fA-F]*$/;
+const addressSchema = z.string({
+  invalid_type_error: "Invalid value, not a string"
+}).regex(EVM_ADDRESS_REGEX, "Invalid value, not an Address");
+const bytes32Schema = z.string({
+  invalid_type_error: "Invalid value, not a string"
+}).regex(BYTES32_REGEX, "Invalid value, not 32 bytes hex");
+const bytesSchema = z.string({
+  invalid_type_error: "Invalid value, not a string"
+}).regex(BYTES_REGEX, "Invalid value, not hex");
+const verificationSchema = z.discriminatedUnion("method", [
+  z.object({
+    data: bytes32Schema,
+    method: z.enum([
+      VERIFICATION_METHODS.HASH_KECCAK256_BYTES,
+      VERIFICATION_METHODS.HASH_KECCAK256_UTF8
+    ])
+  }),
+  z.object({
+    method: z.enum([VERIFICATION_METHODS.ECDSA]),
+    /** Signer address */
+    data: addressSchema,
+    /** URL where the signature can be retrieved */
+    source: z.string().url("Invalid value, not a URL")
+  })
+]);
+const imageSchema = z.object({
+  url: z.string({ invalid_type_error: "Invalid value, not a string" }).url("Invalid value, not a URL"),
+  width: z.number({ invalid_type_error: "Invalid value, not a number" }),
+  height: z.number({ invalid_type_error: "Invalid value, not a number" }),
+  verification: verificationSchema
+});
+const assetSchema = z.object({
+  url: z.string({ invalid_type_error: "Invalid value, not a string" }).url("Invalid value, not a URL"),
+  fileType: z.string({ invalid_type_error: "Invalid value, not a string" }),
+  verification: verificationSchema
+});
+const linkSchema = z.object({
+  title: z.string({ invalid_type_error: "Invalid value, not a string" }),
+  url: z.string({ invalid_type_error: "Invalid value, not a string" }).url("Invalid value, not a URL")
+});
+const tagSchema = z.string({
+  invalid_type_error: "Invalid value, not a string"
+});
+
+function isImageSchema(obj) {
+  const { success } = imageSchema.safeParse(obj);
+  return success;
+}
+function isLinkSchema(obj) {
+  const { success } = linkSchema.safeParse(obj);
+  return success;
+}
+function isTagSchema(obj) {
+  const { success } = tagSchema.safeParse(obj);
+  return success;
+}
+function isAssetSchema(obj) {
+  const { success } = assetSchema.safeParse(obj);
+  return success;
+}
+
+function findBestImage(images, options) {
+  if (!images || images.length === 0) {
+    return void 0;
+  }
+  if (options?.width != null && options?.height != null) {
+    return findClosestImage(images, options.width, options.height) ?? void 0;
+  }
+  return images[0];
+}
+function findClosestImage(images, targetWidth, targetHeight) {
+  if (!images || images.length === 0) {
+    return null;
+  }
+  const calculateDistance = (width, height) => {
+    return Math.sqrt((width - targetWidth) ** 2 + (height - targetHeight) ** 2);
+  };
+  let closestImage = null;
+  let minDistance = Infinity;
+  for (const image of images) {
+    const distance = calculateDistance(image.width, image.height);
+    if (distance < minDistance) {
+      minDistance = distance;
+      closestImage = image;
+    }
+  }
+  return closestImage;
+}
+
+function encodeVerifiableUri(data, ipfsUrl) {
+  const jsonString = JSON.stringify(data);
+  const verificationHash = keccak256(stringToHex(jsonString));
+  const urlHex = stringToHex(ipfsUrl);
+  return concat([
+    RESERVED_PREFIX,
+    KECCAK256_BYTES_METHOD_ID,
+    HASH_LENGTH_PREFIX,
+    verificationHash,
+    urlHex
+  ]);
+}
+function parseVerifiableUri(value) {
+  if (value.length < MIN_VERIFIABLE_URI_LENGTH) {
+    throw new Error(
+      `Invalid VerifiableURI: value too short (${value.length} chars, minimum ${MIN_VERIFIABLE_URI_LENGTH})`
+    );
+  }
+  const reservedPrefix = slice(value, 0, 2);
+  if (reservedPrefix !== RESERVED_PREFIX) {
+    throw new Error(
+      `Invalid VerifiableURI: expected reserved prefix ${RESERVED_PREFIX}, got ${reservedPrefix}`
+    );
+  }
+  const verificationMethod = slice(value, 2, 6);
+  const hashLengthHex = slice(value, 6, 8);
+  const hashLength = parseInt(hashLengthHex.slice(2), 16);
+  const verificationData = slice(value, 8, 8 + hashLength);
+  const urlHex = slice(value, 8 + hashLength);
+  const url = hexToString(urlHex);
+  return {
+    verificationMethod,
+    verificationData,
+    url
+  };
+}
+function decodeVerifiableUri(verifiableUriValue, jsonContent, schema) {
+  const { verificationMethod, verificationData, url } = parseVerifiableUri(verifiableUriValue);
+  if (verificationMethod !== KECCAK256_BYTES_METHOD_ID) {
+    throw new Error(
+      `Unsupported verification method: ${verificationMethod}. Expected ${KECCAK256_BYTES_METHOD_ID} (keccak256(bytes))`
+    );
+  }
+  const computedHash = keccak256(stringToHex(jsonContent));
+  if (computedHash.toLowerCase() !== verificationData.toLowerCase()) {
+    throw new Error(
+      `VerifiableURI hash mismatch: content hash ${computedHash} does not match verification data ${verificationData}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonContent);
+  } catch {
+    throw new Error("Invalid JSON content");
+  }
+  if (schema) {
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      throw new Error(`Schema validation failed: ${result.error.message}`);
+    }
+    return { data: result.data, url };
+  }
+  return { data: parsed, url };
+}
+function computeVerificationHash(data) {
+  const jsonString = JSON.stringify(data);
+  return keccak256(stringToHex(jsonString));
+}
+function isVerifiableUri(value) {
+  if (value.length < MIN_VERIFIABLE_URI_LENGTH) {
+    return false;
+  }
+  try {
+    const reservedPrefix = slice(value, 0, 2);
+    return reservedPrefix === RESERVED_PREFIX;
+  } catch {
+    return false;
+  }
+}
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, MAPPING_SEPARATOR, MIN_VERIFIABLE_URI_LENGTH, RESERVED_PREFIX, VERIFICATION_METHODS, addressSchema, assetSchema, bytes32Schema, bytesSchema, computeVerificationHash, decodeVerifiableUri, encodeVerifiableUri, findBestImage, findClosestImage, imageSchema, isAssetSchema, isImageSchema, isLinkSchema, isTagSchema, isVerifiableUri, linkSchema, parseVerifiableUri, tagSchema, verificationSchema };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@chillwhales/lsp2",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "LSP2 ERC725Y JSON Schema — shared primitives, VerifiableURI encoding/decoding, and image utilities",
+  "author": "b00ste",
+  "license": "MIT",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chillwhales/LSPs.git",
+    "directory": "packages/lsp2"
+  },
+  "keywords": [
+    "chillwhales",
+    "lukso",
+    "lsp",
+    "lsp2",
+    "erc725y",
+    "verifiable-uri",
+    "json-schema"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1",
+    "viem": "^2.0.0",
+    "vitest": "^4.0.17",
+    "@chillwhales/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "unbuild --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}