@chillwhales/lsp4 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/lsp4
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+LSP4 Digital Asset Metadata — schemas, types, and utilities for reading and validating LSP7/LSP8 token metadata on LUKSO.
+
+## Install
+
+```bash
+pnpm add @chillwhales/lsp4
+```
+
+## Usage
+
+```typescript
+import { lsp4MetadataSchema, getAssetDisplayName } from "@chillwhales/lsp4";
+
+// Validate raw token metadata fetched from IPFS / on-chain
+const raw = {
+  name: "Chillwhale #42",
+  description: "A chill whale living on LUKSO",
+  category: "Collectible",
+  links: [],
+  icon: [{ url: "ipfs://QmIcon...", width: 64, height: 64 }],
+  images: [[{ url: "ipfs://QmFull...", width: 1024, height: 1024 }]],
+  assets: [],
+  attributes: [
+    { key: "Background", value: "Ocean", type: "string" },
+    { key: "Rarity", value: "42", type: "number" },
+  ],
+};
+
+const metadata = lsp4MetadataSchema.parse(raw);
+const name = getAssetDisplayName(metadata); // "Chillwhale #42"
+```
+
+> **Spec:** [LSP-4 Digital Asset Metadata](https://docs.lukso.tech/standards/tokens/LSP4-Digital-Asset-Metadata)
+
+## API
+
+Types are exported and available in your editor via TypeScript IntelliSense.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,435 @@
+import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
+import { Image } from '@chillwhales/lsp2';
+import { z } from 'zod';
+
+/**
+ * Asset attribute schema
+ * Supports string, number, and boolean attribute types
+ */
+declare const attributesSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    type: z.ZodLiteral<"string">;
+}, "strip", z.ZodTypeAny, {
+    type: "string";
+    value: string;
+    key: string;
+}, {
+    type: "string";
+    value: string;
+    key: string;
+}>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodEffects<z.ZodString, string, string>;
+    type: z.ZodLiteral<"number">;
+}, "strip", z.ZodTypeAny, {
+    type: "number";
+    value: string;
+    key: string;
+}, {
+    type: "number";
+    value: string;
+    key: string;
+}>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodBoolean;
+    type: z.ZodLiteral<"boolean">;
+}, "strip", z.ZodTypeAny, {
+    type: "boolean";
+    value: boolean;
+    key: string;
+}, {
+    type: "boolean";
+    value: boolean;
+    key: string;
+}>]>;
+/**
+ * LSP4 Digital Asset metadata schema
+ * Full metadata structure for LSP7/LSP8 tokens
+ */
+declare const lsp4MetadataSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    category: z.ZodNullable<z.ZodString>;
+    links: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        title: string;
+    }, {
+        url: string;
+        title: string;
+    }>, "many">;
+    icon: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+    images: z.ZodArray<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">, "many">;
+    assets: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        fileType: z.ZodString;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }>, "many">;
+    attributes: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+        type: z.ZodLiteral<"string">;
+    }, "strip", z.ZodTypeAny, {
+        type: "string";
+        value: string;
+        key: string;
+    }, {
+        type: "string";
+        value: string;
+        key: string;
+    }>, z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodEffects<z.ZodString, string, string>;
+        type: z.ZodLiteral<"number">;
+    }, "strip", z.ZodTypeAny, {
+        type: "number";
+        value: string;
+        key: string;
+    }, {
+        type: "number";
+        value: string;
+        key: string;
+    }>, z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodBoolean;
+        type: z.ZodLiteral<"boolean">;
+    }, "strip", z.ZodTypeAny, {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    }, {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    links: {
+        url: string;
+        title: string;
+    }[];
+    icon: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    images: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[][];
+    assets: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    attributes: ({
+        type: "string";
+        value: string;
+        key: string;
+    } | {
+        type: "number";
+        value: string;
+        key: string;
+    } | {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    })[];
+}, {
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    links: {
+        url: string;
+        title: string;
+    }[];
+    icon: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    images: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[][];
+    assets: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    attributes: ({
+        type: "string";
+        value: string;
+        key: string;
+    } | {
+        type: "number";
+        value: string;
+        key: string;
+    } | {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    })[];
+}>;
+
+/**
+ * LSP4 Inferred Types
+ *
+ * TypeScript types inferred from LSP4 Zod schemas.
+ */
+
+type LSP4Attribute = z.infer<typeof attributesSchema>;
+type LSP4Metadata = z.infer<typeof lsp4MetadataSchema>;
+
+/**
+ * LSP4 Digital Asset Metadata Utilities
+ *
+ * Pure functions for working with LSP4 digital asset metadata (LSP7/LSP8).
+ */
+
+/**
+ * Gets the best image URL from pre-extracted LSP4 Image objects.
+ * By default prefers image over icon (for content display).
+ * Use preferIcon: true to prefer icon (for compact displays).
+ *
+ * @param options.image - Pre-extracted image object (from images[0][0])
+ * @param options.icon - Pre-extracted icon object (from icon[0])
+ * @param options.preferIcon - If true, prefer icon over image (default: false)
+ * @param options.parseUrl - Function to parse/transform the URL (e.g., IPFS parsing)
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // With destructured metadata: images: [[image]], icon: [icon]
+ * const imageUrl = getImageUrl({ image, icon, parseUrl });
+ * const iconUrl = getImageUrl({ image, icon, preferIcon: true, parseUrl });
+ * ```
+ */
+declare function getImageUrl(options: {
+    image?: Image | null;
+    icon?: Image | null;
+    preferIcon?: boolean;
+    parseUrl: (url: string) => string;
+}): string | undefined;
+/**
+ * Get display name for Digital Asset.
+ * Uses name, falls back to 'Digital Asset'.
+ *
+ * @param metadata - Object with optional name field
+ * @returns Display name string
+ */
+declare function getAssetDisplayName(metadata: LSP4Metadata): string;
+
+/**
+ * LSP4 Type Guards
+ *
+ * Runtime type guards for LSP4 schemas.
+ */
+
+/**
+ * Type guard for LSP4 attribute schema
+ */
+declare function isAttributesSchema(obj: unknown): obj is z.infer<typeof attributesSchema>;
+/**
+ * Type guard for LSP4 metadata schema
+ */
+declare function isLsp4MetadataSchema(obj: unknown): obj is z.infer<typeof lsp4MetadataSchema>;
+
+export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
+export type { LSP4Attribute, LSP4Metadata };

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
+import { Image } from '@chillwhales/lsp2';
+import { z } from 'zod';
+
+/**
+ * Asset attribute schema
+ * Supports string, number, and boolean attribute types
+ */
+declare const attributesSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    type: z.ZodLiteral<"string">;
+}, "strip", z.ZodTypeAny, {
+    type: "string";
+    value: string;
+    key: string;
+}, {
+    type: "string";
+    value: string;
+    key: string;
+}>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodEffects<z.ZodString, string, string>;
+    type: z.ZodLiteral<"number">;
+}, "strip", z.ZodTypeAny, {
+    type: "number";
+    value: string;
+    key: string;
+}, {
+    type: "number";
+    value: string;
+    key: string;
+}>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodBoolean;
+    type: z.ZodLiteral<"boolean">;
+}, "strip", z.ZodTypeAny, {
+    type: "boolean";
+    value: boolean;
+    key: string;
+}, {
+    type: "boolean";
+    value: boolean;
+    key: string;
+}>]>;
+/**
+ * LSP4 Digital Asset metadata schema
+ * Full metadata structure for LSP7/LSP8 tokens
+ */
+declare const lsp4MetadataSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    category: z.ZodNullable<z.ZodString>;
+    links: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        title: string;
+    }, {
+        url: string;
+        title: string;
+    }>, "many">;
+    icon: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+    images: z.ZodArray<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">, "many">;
+    assets: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        fileType: z.ZodString;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }>, "many">;
+    attributes: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+        type: z.ZodLiteral<"string">;
+    }, "strip", z.ZodTypeAny, {
+        type: "string";
+        value: string;
+        key: string;
+    }, {
+        type: "string";
+        value: string;
+        key: string;
+    }>, z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodEffects<z.ZodString, string, string>;
+        type: z.ZodLiteral<"number">;
+    }, "strip", z.ZodTypeAny, {
+        type: "number";
+        value: string;
+        key: string;
+    }, {
+        type: "number";
+        value: string;
+        key: string;
+    }>, z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodBoolean;
+        type: z.ZodLiteral<"boolean">;
+    }, "strip", z.ZodTypeAny, {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    }, {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    links: {
+        url: string;
+        title: string;
+    }[];
+    icon: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    images: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[][];
+    assets: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    attributes: ({
+        type: "string";
+        value: string;
+        key: string;
+    } | {
+        type: "number";
+        value: string;
+        key: string;
+    } | {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    })[];
+}, {
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    links: {
+        url: string;
+        title: string;
+    }[];
+    icon: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    images: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[][];
+    assets: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    attributes: ({
+        type: "string";
+        value: string;
+        key: string;
+    } | {
+        type: "number";
+        value: string;
+        key: string;
+    } | {
+        type: "boolean";
+        value: boolean;
+        key: string;
+    })[];
+}>;
+
+/**
+ * LSP4 Inferred Types
+ *
+ * TypeScript types inferred from LSP4 Zod schemas.
+ */
+
+type LSP4Attribute = z.infer<typeof attributesSchema>;
+type LSP4Metadata = z.infer<typeof lsp4MetadataSchema>;
+
+/**
+ * LSP4 Digital Asset Metadata Utilities
+ *
+ * Pure functions for working with LSP4 digital asset metadata (LSP7/LSP8).
+ */
+
+/**
+ * Gets the best image URL from pre-extracted LSP4 Image objects.
+ * By default prefers image over icon (for content display).
+ * Use preferIcon: true to prefer icon (for compact displays).
+ *
+ * @param options.image - Pre-extracted image object (from images[0][0])
+ * @param options.icon - Pre-extracted icon object (from icon[0])
+ * @param options.preferIcon - If true, prefer icon over image (default: false)
+ * @param options.parseUrl - Function to parse/transform the URL (e.g., IPFS parsing)
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // With destructured metadata: images: [[image]], icon: [icon]
+ * const imageUrl = getImageUrl({ image, icon, parseUrl });
+ * const iconUrl = getImageUrl({ image, icon, preferIcon: true, parseUrl });
+ * ```
+ */
+declare function getImageUrl(options: {
+    image?: Image | null;
+    icon?: Image | null;
+    preferIcon?: boolean;
+    parseUrl: (url: string) => string;
+}): string | undefined;
+/**
+ * Get display name for Digital Asset.
+ * Uses name, falls back to 'Digital Asset'.
+ *
+ * @param metadata - Object with optional name field
+ * @returns Display name string
+ */
+declare function getAssetDisplayName(metadata: LSP4Metadata): string;
+
+/**
+ * LSP4 Type Guards
+ *
+ * Runtime type guards for LSP4 schemas.
+ */
+
+/**
+ * Type guard for LSP4 attribute schema
+ */
+declare function isAttributesSchema(obj: unknown): obj is z.infer<typeof attributesSchema>;
+/**
+ * Type guard for LSP4 metadata schema
+ */
+declare function isLsp4MetadataSchema(obj: unknown): obj is z.infer<typeof lsp4MetadataSchema>;
+
+export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
+export type { LSP4Attribute, LSP4Metadata };

package/dist/index.mjs

@@ -0,0 +1,64 @@
+import { assetSchema, imageSchema, linkSchema } from '@chillwhales/lsp2';
+import { isNumeric } from '@chillwhales/utils';
+import { z } from 'zod';
+
+function getImageUrl(options) {
+  const { image, icon, preferIcon = false, parseUrl } = options;
+  const primary = preferIcon ? icon : image;
+  const fallback = preferIcon ? image : icon;
+  if (primary?.url) {
+    return parseUrl(primary.url);
+  }
+  if (fallback?.url) {
+    return parseUrl(fallback.url);
+  }
+  return void 0;
+}
+function getAssetDisplayName(metadata) {
+  return metadata.name || "Digital Asset";
+}
+
+const attributesSchema = z.discriminatedUnion("type", [
+  z.object({
+    key: z.string({ invalid_type_error: "Invalid value, not a string" }),
+    value: z.string({ invalid_type_error: "Invalid value, not a string" }),
+    type: z.literal("string")
+  }),
+  z.object({
+    key: z.string({ invalid_type_error: "Invalid value, not a string" }),
+    value: z.string({ required_error: "Value required" }).refine(isNumeric, "Invalid value, not a number"),
+    type: z.literal("number")
+  }),
+  z.object({
+    key: z.string({ invalid_type_error: "Invalid value, not a string" }),
+    value: z.boolean({ invalid_type_error: "Invalid value, not a boolean" }),
+    type: z.literal("boolean")
+  })
+]);
+const lsp4MetadataSchema = z.object({
+  name: z.string({
+    invalid_type_error: "Name must be a string"
+  }).nullable(),
+  description: z.string({
+    invalid_type_error: "Description must be a string"
+  }).nullable(),
+  category: z.string({
+    invalid_type_error: "Category must be a string"
+  }).nullable(),
+  links: z.array(linkSchema),
+  icon: z.array(imageSchema),
+  images: z.array(z.array(imageSchema)),
+  assets: z.array(assetSchema),
+  attributes: z.array(attributesSchema)
+});
+
+function isAttributesSchema(obj) {
+  const { success } = attributesSchema.safeParse(obj);
+  return success;
+}
+function isLsp4MetadataSchema(obj) {
+  const { success } = lsp4MetadataSchema.safeParse(obj);
+  return success;
+}
+
+export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@chillwhales/lsp4",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "LSP4 Digital Asset Metadata — schemas, types, and utilities for LSP7/LSP8 token metadata on LUKSO",
+  "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/lsp4"
+  },
+  "keywords": [
+    "chillwhales",
+    "lukso",
+    "lsp",
+    "lsp4",
+    "digital-asset",
+    "metadata",
+    "lsp7",
+    "lsp8"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^3.24.1",
+    "@chillwhales/lsp2": "0.1.1",
+    "@chillwhales/utils": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1",
+    "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"
+  }
+}