@chillwhales/lsp31 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,53 @@
+# @chillwhales/lsp31
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+LSP31 Multi-Storage URI — encode, decode, and resolve multi-backend content references for redundant storage on LUKSO Universal Profiles.
+
+## Install
+
+```bash
+pnpm add @chillwhales/lsp31
+```
+
+> **Peer dependency:** This package requires [`viem`](https://viem.sh) ^2.0.0
+>
+> ```bash
+> pnpm add viem
+> ```
+
+## Usage
+
+```typescript
+import {
+  encodeLsp31Uri,
+  parseLsp31Uri,
+  computeContentHash,
+} from "@chillwhales/lsp31";
+
+// Define storage entries (minimum 2 backends for redundancy)
+const entries = [
+  { backend: "ipfs" as const, cid: "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG" },
+  { backend: "arweave" as const, id: "abcdef1234567890abcdef1234567890abcdef123456" },
+];
+
+// Encode with a verification hash of the content bytes
+const contentBytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+const hash = computeContentHash(contentBytes);
+const encoded = encodeLsp31Uri(entries, hash);
+// encoded is a hex string ready for setData()
+
+// Later, parse the on-chain value back into structured entries
+const { verificationData, entries: decoded } = parseLsp31Uri(encoded);
+console.log(decoded[0].backend); // "ipfs"
+```
+
+> **Spec:** See `LSP-31-MultiStorageURI.md` in the repository for the full specification.
+
+## API
+
+Types are exported and available in your editor via TypeScript IntelliSense.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,553 @@
+import { Hex } from 'viem';
+import { z } from 'zod';
+
+/**
+ * LSP31 Multi-Storage URI Constants
+ *
+ * These constants mirror LSP2 verification constants locally to avoid
+ * external dependencies (this package is standalone).
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+/**
+ * Reserved prefix for LSP31 Multi-Storage URI (2 bytes)
+ * Distinguishes LSP31 from LSP2 VerifiableURI (0x0000)
+ */
+declare const LSP31_RESERVED_PREFIX: "0x0031";
+/**
+ * Verification method ID for keccak256(bytes)
+ * Computed as: bytes4(keccak256('keccak256(bytes)')) = 0x8019f9b1
+ * Same as LSP2 — verification model is identical
+ */
+declare const KECCAK256_BYTES_METHOD_ID: "0x8019f9b1";
+/**
+ * Length of a keccak256 hash in bytes (32 bytes = 0x0020)
+ */
+declare const HASH_LENGTH_PREFIX: "0x0020";
+/**
+ * Minimum length of a valid LSP31 URI value in hex characters
+ * 2 (prefix) + 4 (method ID) + 2 (hash length) + 32 (hash) = 40 bytes = 80 hex chars + '0x' prefix
+ * Note: A valid LSP31 URI will always be longer (entries JSON adds more), but 82 is the structural minimum
+ */
+declare const MIN_LSP31_URI_LENGTH = 82;
+/**
+ * Closed set of supported storage backends
+ * Adding a backend requires a schema update — this is intentional for validation safety
+ */
+declare const LSP31_BACKENDS: readonly ["ipfs", "s3", "lumera", "arweave"];
+/**
+ * Minimum number of entries required in an LSP31 multi-storage URI
+ * Single-backend content should use LSP2 VerifiableURI instead
+ */
+declare const LSP31_MIN_ENTRIES = 2;
+
+/**
+ * LSP31 Multi-Storage URI Zod Schemas
+ *
+ * Validates multi-storage entries with a discriminated union on the `backend` field.
+ * Four backend types: ipfs, s3, lumera, arweave — each with backend-specific identifier fields.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * IPFS storage entry
+ * Identified by a Content Identifier (CID)
+ */
+declare const lsp31IpfsEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>;
+/**
+ * S3 storage entry
+ * Identified by bucket, key, and region
+ */
+declare const lsp31S3EntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>;
+/**
+ * Lumera/Pastel Cascade storage entry
+ * Identified by a Cascade action ID
+ */
+declare const lsp31LumeraEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>;
+/**
+ * Arweave storage entry
+ * Identified by a transaction ID
+ */
+declare const lsp31ArweaveEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>;
+/**
+ * LSP31 entry schema — discriminated union on `backend` field
+ *
+ * Each entry represents a single storage backend with its backend-specific identifiers.
+ * The `backend` field determines which additional fields are required.
+ *
+ * @example
+ * ```typescript
+ * const ipfsEntry = { backend: 'ipfs', cid: 'QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG' };
+ * const s3Entry = { backend: 's3', bucket: 'my-bucket', key: 'content/file.bin', region: 'us-east-1' };
+ * ```
+ */
+declare const lsp31EntrySchema: z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>]>;
+/**
+ * LSP31 entries array — minimum 2 entries required
+ *
+ * Single-backend content should use LSP2 VerifiableURI instead.
+ * The entries array is unordered — resolvers select based on viewer preference.
+ */
+declare const lsp31EntriesSchema: z.ZodArray<z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>]>, "many">;
+/**
+ * LSP31 URI data schema — input for encoding an LSP31 multi-storage URI
+ *
+ * Contains the pre-computed content verification hash and the entries array.
+ * The hash covers the content bytes (identical across all backends), not the entries JSON.
+ */
+declare const lsp31UriDataSchema: z.ZodObject<{
+    /** keccak256 hash of content bytes, 0x-prefixed 64-char hex string */
+    verificationHash: z.ZodString;
+    /** Storage backend entries (minimum 2) */
+    entries: z.ZodArray<z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+        backend: z.ZodLiteral<"ipfs">;
+        /** IPFS content identifier (CIDv0 or CIDv1) */
+        cid: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "ipfs";
+        cid: string;
+    }, {
+        backend: "ipfs";
+        cid: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"s3">;
+        /** S3 bucket name */
+        bucket: z.ZodString;
+        /** S3 object key */
+        key: z.ZodString;
+        /** AWS region (e.g., "us-east-1") */
+        region: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    }, {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"lumera">;
+        /** Lumera/Pastel Cascade action ID */
+        actionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "lumera";
+        actionId: string;
+    }, {
+        backend: "lumera";
+        actionId: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"arweave">;
+        /** Arweave transaction ID */
+        transactionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "arweave";
+        transactionId: string;
+    }, {
+        backend: "arweave";
+        transactionId: string;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: ({
+        backend: "ipfs";
+        cid: string;
+    } | {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    } | {
+        backend: "lumera";
+        actionId: string;
+    } | {
+        backend: "arweave";
+        transactionId: string;
+    })[];
+    verificationHash: string;
+}, {
+    entries: ({
+        backend: "ipfs";
+        cid: string;
+    } | {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    } | {
+        backend: "lumera";
+        actionId: string;
+    } | {
+        backend: "arweave";
+        transactionId: string;
+    })[];
+    verificationHash: string;
+}>;
+
+/**
+ * LSP31 Multi-Storage URI TypeScript Types
+ *
+ * Entry types are inferred from Zod schemas via z.infer.
+ * ParsedLsp31Uri is a manual interface representing the parsed on-chain byte shape
+ * (not user input, so no Zod schema needed).
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/** Union of supported storage backend identifiers */
+type Lsp31Backend = (typeof LSP31_BACKENDS)[number];
+/** IPFS storage entry */
+type Lsp31IpfsEntry = z.infer<typeof lsp31IpfsEntrySchema>;
+/** S3 storage entry */
+type Lsp31S3Entry = z.infer<typeof lsp31S3EntrySchema>;
+/** Lumera/Pastel Cascade storage entry */
+type Lsp31LumeraEntry = z.infer<typeof lsp31LumeraEntrySchema>;
+/** Arweave storage entry */
+type Lsp31ArweaveEntry = z.infer<typeof lsp31ArweaveEntrySchema>;
+/** Discriminated union of all storage entry types */
+type Lsp31Entry = z.infer<typeof lsp31EntrySchema>;
+/** Array of storage entries (minimum 2) */
+type Lsp31Entries = z.infer<typeof lsp31EntriesSchema>;
+/** Input data for encoding an LSP31 multi-storage URI */
+type Lsp31UriData = z.infer<typeof lsp31UriDataSchema>;
+/**
+ * Output of parsing an LSP31 multi-storage URI from on-chain bytes
+ * Used by parseLsp31Uri (implemented in Plan 02)
+ */
+interface ParsedLsp31Uri {
+    /** Verification method (4 bytes, e.g., 0x8019f9b1 for keccak256(bytes)) */
+    verificationMethod: Hex;
+    /** Verification data (keccak256 hash of content bytes) */
+    verificationData: Hex;
+    /** Decoded and validated storage entries */
+    entries: Lsp31Entry[];
+}
+
+/**
+ * LSP31 Multi-Storage URI Decoding
+ *
+ * Parses and verifies LSP31 on-chain hex values back into structured data.
+ * Mirrors the LSP2 parseVerifiableUri/decodeVerifiableUri pattern.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Parses an LSP31 Multi-Storage URI hex value into its components.
+ *
+ * Format: 0x + reserved (2 bytes) + method (4 bytes) + length (2 bytes) + hash (N bytes) + entries JSON
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @returns Parsed components (verificationMethod, verificationData, entries)
+ * @throws Error if the value is malformed, wrong prefix, or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * const { verificationMethod, verificationData, entries } = parseLsp31Uri(rawValue);
+ * entries.forEach(entry => console.log(entry.backend));
+ * ```
+ */
+declare function parseLsp31Uri(value: Hex): ParsedLsp31Uri;
+/**
+ * Decodes and verifies an LSP31 Multi-Storage URI against its content bytes.
+ *
+ * 1. Parses the URI structure
+ * 2. Verifies the verification method is keccak256(bytes)
+ * 3. Computes keccak256 of the provided content and checks against the embedded hash
+ * 4. Validates entries through Zod schema
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @param content - The actual content bytes (used to verify the hash)
+ * @returns Validated entries and verification data
+ * @throws Error if hash doesn't match, method is unsupported, or entries are invalid
+ *
+ * @example
+ * ```typescript
+ * const contentBytes = await fetchFromBackend(entry);
+ * const { entries, verificationData } = decodeLsp31Uri(rawValue, contentBytes);
+ * ```
+ */
+declare function decodeLsp31Uri(value: Hex, content: Uint8Array): {
+    entries: Lsp31Entry[];
+    verificationData: Hex;
+};
+
+/**
+ * LSP31 Multi-Storage URI Encoding
+ *
+ * Encodes multi-storage entries into the LSP31 on-chain format:
+ * 0x0031 + method (4) + hashLength (2) + hash (32) + toUtf8Hex(JSON.stringify(entries))
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Computes the keccak256 content hash from raw bytes.
+ *
+ * @param content - Raw content bytes (identical across all storage backends)
+ * @returns keccak256 hash as a 0x-prefixed hex string
+ *
+ * @example
+ * ```typescript
+ * const contentBytes = new Uint8Array([...]);
+ * const hash = computeContentHash(contentBytes);
+ * const encoded = encodeLsp31Uri(entries, hash);
+ * ```
+ */
+declare function computeContentHash(content: Uint8Array): Hex;
+/**
+ * Encodes storage entries and a pre-computed verification hash into the LSP31 on-chain format.
+ *
+ * The output is a hex string with the layout:
+ * - 2 bytes: reserved prefix (0x0031)
+ * - 4 bytes: verification method ID (0x8019f9b1, keccak256(bytes))
+ * - 2 bytes: hash length (0x0020 = 32 bytes)
+ * - 32 bytes: content verification hash
+ * - variable: UTF-8 encoded JSON of entries array
+ *
+ * @param entries - Array of storage backend entries (minimum 2)
+ * @param verificationHash - Pre-computed keccak256 hash of the content bytes (0x + 64 hex chars)
+ * @returns Hex-encoded LSP31 URI value
+ * @throws Error if entries fail validation or hash format is invalid
+ *
+ * @example
+ * ```typescript
+ * const entries = [
+ *   { backend: 'ipfs', cid: 'QmTest...' },
+ *   { backend: 's3', bucket: 'my-bucket', key: 'file.bin', region: 'us-east-1' },
+ * ];
+ * const hash = computeContentHash(contentBytes);
+ * const encoded = encodeLsp31Uri(entries, hash);
+ * ```
+ */
+declare function encodeLsp31Uri(entries: Lsp31Entry[], verificationHash: Hex): Hex;
+
+/**
+ * LSP31 Multi-Storage URI Type Guards
+ *
+ * Quick structural checks for identifying LSP31 encoded values.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Checks if a hex value appears to be a valid LSP31 Multi-Storage URI format.
+ *
+ * This is a quick structural check based on length and prefix, not full content validation.
+ * Distinguishes LSP31 (0x0031 prefix) from LSP2 VerifiableURI (0x0000 prefix).
+ *
+ * @param value - Hex value to check
+ * @returns true if the value has valid LSP31 structure
+ *
+ * @example
+ * ```typescript
+ * if (isLsp31Uri(rawValue)) {
+ *   const { entries } = parseLsp31Uri(rawValue);
+ * } else if (isVerifiableUri(rawValue)) {
+ *   const { url } = parseVerifiableUri(rawValue);
+ * }
+ * ```
+ */
+declare function isLsp31Uri(value: Hex): boolean;
+
+/**
+ * LSP31 Multi-Storage URI Resolver
+ *
+ * Pure functions for selecting preferred storage backends and deriving access URLs.
+ * No actual fetching — that's the app layer's responsibility.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Selects and orders storage entries based on preference.
+ *
+ * Uses exhaustive fallback: preferred entries come first, then remaining entries
+ * in their original order. Output always has the same length as input — no entries
+ * are ever dropped.
+ *
+ * @param entries - Array of storage entries to order
+ * @param preference - Optional preferred backend(s). Can be:
+ *   - undefined: returns entries in original order
+ *   - string: single preferred backend
+ *   - array: ordered list of preferred backends
+ *   - empty array: treated as undefined (no preference)
+ * @returns New array with all entries, preferred ones first
+ *
+ * @example
+ * ```typescript
+ * const ordered = selectBackend(entries, 'ipfs');
+ * // IPFS entry first, then remaining in original order
+ *
+ * const ordered2 = selectBackend(entries, ['lumera', 'ipfs']);
+ * // Lumera first, IPFS second, then remaining
+ * ```
+ */
+declare function selectBackend(entries: Lsp31Entry[], preference?: Lsp31Backend | Lsp31Backend[]): Lsp31Entry[];
+/**
+ * Derives an access URL from a storage backend entry.
+ *
+ * Returns protocol URLs for IPFS and Lumera (actual gateway resolution is app-layer),
+ * and direct HTTPS URLs for S3 and Arweave.
+ *
+ * @param entry - A single storage entry
+ * @returns The derived access URL
+ *
+ * @example
+ * ```typescript
+ * const url = resolveUrl({ backend: 'ipfs', cid: 'QmTest...' });
+ * // 'ipfs://QmTest...'
+ *
+ * const url2 = resolveUrl({ backend: 's3', bucket: 'b', key: 'k', region: 'r' });
+ * // 'https://b.s3.r.amazonaws.com/k'
+ * ```
+ */
+declare function resolveUrl(entry: Lsp31Entry): string;
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, LSP31_BACKENDS, LSP31_MIN_ENTRIES, LSP31_RESERVED_PREFIX, MIN_LSP31_URI_LENGTH, computeContentHash, decodeLsp31Uri, encodeLsp31Uri, isLsp31Uri, lsp31ArweaveEntrySchema, lsp31EntriesSchema, lsp31EntrySchema, lsp31IpfsEntrySchema, lsp31LumeraEntrySchema, lsp31S3EntrySchema, lsp31UriDataSchema, parseLsp31Uri, resolveUrl, selectBackend };
+export type { Lsp31ArweaveEntry, Lsp31Backend, Lsp31Entries, Lsp31Entry, Lsp31IpfsEntry, Lsp31LumeraEntry, Lsp31S3Entry, Lsp31UriData, ParsedLsp31Uri };

package/dist/index.d.ts

@@ -0,0 +1,553 @@
+import { Hex } from 'viem';
+import { z } from 'zod';
+
+/**
+ * LSP31 Multi-Storage URI Constants
+ *
+ * These constants mirror LSP2 verification constants locally to avoid
+ * external dependencies (this package is standalone).
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+/**
+ * Reserved prefix for LSP31 Multi-Storage URI (2 bytes)
+ * Distinguishes LSP31 from LSP2 VerifiableURI (0x0000)
+ */
+declare const LSP31_RESERVED_PREFIX: "0x0031";
+/**
+ * Verification method ID for keccak256(bytes)
+ * Computed as: bytes4(keccak256('keccak256(bytes)')) = 0x8019f9b1
+ * Same as LSP2 — verification model is identical
+ */
+declare const KECCAK256_BYTES_METHOD_ID: "0x8019f9b1";
+/**
+ * Length of a keccak256 hash in bytes (32 bytes = 0x0020)
+ */
+declare const HASH_LENGTH_PREFIX: "0x0020";
+/**
+ * Minimum length of a valid LSP31 URI value in hex characters
+ * 2 (prefix) + 4 (method ID) + 2 (hash length) + 32 (hash) = 40 bytes = 80 hex chars + '0x' prefix
+ * Note: A valid LSP31 URI will always be longer (entries JSON adds more), but 82 is the structural minimum
+ */
+declare const MIN_LSP31_URI_LENGTH = 82;
+/**
+ * Closed set of supported storage backends
+ * Adding a backend requires a schema update — this is intentional for validation safety
+ */
+declare const LSP31_BACKENDS: readonly ["ipfs", "s3", "lumera", "arweave"];
+/**
+ * Minimum number of entries required in an LSP31 multi-storage URI
+ * Single-backend content should use LSP2 VerifiableURI instead
+ */
+declare const LSP31_MIN_ENTRIES = 2;
+
+/**
+ * LSP31 Multi-Storage URI Zod Schemas
+ *
+ * Validates multi-storage entries with a discriminated union on the `backend` field.
+ * Four backend types: ipfs, s3, lumera, arweave — each with backend-specific identifier fields.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * IPFS storage entry
+ * Identified by a Content Identifier (CID)
+ */
+declare const lsp31IpfsEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>;
+/**
+ * S3 storage entry
+ * Identified by bucket, key, and region
+ */
+declare const lsp31S3EntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>;
+/**
+ * Lumera/Pastel Cascade storage entry
+ * Identified by a Cascade action ID
+ */
+declare const lsp31LumeraEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>;
+/**
+ * Arweave storage entry
+ * Identified by a transaction ID
+ */
+declare const lsp31ArweaveEntrySchema: z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>;
+/**
+ * LSP31 entry schema — discriminated union on `backend` field
+ *
+ * Each entry represents a single storage backend with its backend-specific identifiers.
+ * The `backend` field determines which additional fields are required.
+ *
+ * @example
+ * ```typescript
+ * const ipfsEntry = { backend: 'ipfs', cid: 'QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG' };
+ * const s3Entry = { backend: 's3', bucket: 'my-bucket', key: 'content/file.bin', region: 'us-east-1' };
+ * ```
+ */
+declare const lsp31EntrySchema: z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>]>;
+/**
+ * LSP31 entries array — minimum 2 entries required
+ *
+ * Single-backend content should use LSP2 VerifiableURI instead.
+ * The entries array is unordered — resolvers select based on viewer preference.
+ */
+declare const lsp31EntriesSchema: z.ZodArray<z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+    backend: z.ZodLiteral<"ipfs">;
+    /** IPFS content identifier (CIDv0 or CIDv1) */
+    cid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "ipfs";
+    cid: string;
+}, {
+    backend: "ipfs";
+    cid: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"s3">;
+    /** S3 bucket name */
+    bucket: z.ZodString;
+    /** S3 object key */
+    key: z.ZodString;
+    /** AWS region (e.g., "us-east-1") */
+    region: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}, {
+    backend: "s3";
+    bucket: string;
+    key: string;
+    region: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"lumera">;
+    /** Lumera/Pastel Cascade action ID */
+    actionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "lumera";
+    actionId: string;
+}, {
+    backend: "lumera";
+    actionId: string;
+}>, z.ZodObject<{
+    backend: z.ZodLiteral<"arweave">;
+    /** Arweave transaction ID */
+    transactionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    backend: "arweave";
+    transactionId: string;
+}, {
+    backend: "arweave";
+    transactionId: string;
+}>]>, "many">;
+/**
+ * LSP31 URI data schema — input for encoding an LSP31 multi-storage URI
+ *
+ * Contains the pre-computed content verification hash and the entries array.
+ * The hash covers the content bytes (identical across all backends), not the entries JSON.
+ */
+declare const lsp31UriDataSchema: z.ZodObject<{
+    /** keccak256 hash of content bytes, 0x-prefixed 64-char hex string */
+    verificationHash: z.ZodString;
+    /** Storage backend entries (minimum 2) */
+    entries: z.ZodArray<z.ZodDiscriminatedUnion<"backend", [z.ZodObject<{
+        backend: z.ZodLiteral<"ipfs">;
+        /** IPFS content identifier (CIDv0 or CIDv1) */
+        cid: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "ipfs";
+        cid: string;
+    }, {
+        backend: "ipfs";
+        cid: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"s3">;
+        /** S3 bucket name */
+        bucket: z.ZodString;
+        /** S3 object key */
+        key: z.ZodString;
+        /** AWS region (e.g., "us-east-1") */
+        region: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    }, {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"lumera">;
+        /** Lumera/Pastel Cascade action ID */
+        actionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "lumera";
+        actionId: string;
+    }, {
+        backend: "lumera";
+        actionId: string;
+    }>, z.ZodObject<{
+        backend: z.ZodLiteral<"arweave">;
+        /** Arweave transaction ID */
+        transactionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        backend: "arweave";
+        transactionId: string;
+    }, {
+        backend: "arweave";
+        transactionId: string;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: ({
+        backend: "ipfs";
+        cid: string;
+    } | {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    } | {
+        backend: "lumera";
+        actionId: string;
+    } | {
+        backend: "arweave";
+        transactionId: string;
+    })[];
+    verificationHash: string;
+}, {
+    entries: ({
+        backend: "ipfs";
+        cid: string;
+    } | {
+        backend: "s3";
+        bucket: string;
+        key: string;
+        region: string;
+    } | {
+        backend: "lumera";
+        actionId: string;
+    } | {
+        backend: "arweave";
+        transactionId: string;
+    })[];
+    verificationHash: string;
+}>;
+
+/**
+ * LSP31 Multi-Storage URI TypeScript Types
+ *
+ * Entry types are inferred from Zod schemas via z.infer.
+ * ParsedLsp31Uri is a manual interface representing the parsed on-chain byte shape
+ * (not user input, so no Zod schema needed).
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/** Union of supported storage backend identifiers */
+type Lsp31Backend = (typeof LSP31_BACKENDS)[number];
+/** IPFS storage entry */
+type Lsp31IpfsEntry = z.infer<typeof lsp31IpfsEntrySchema>;
+/** S3 storage entry */
+type Lsp31S3Entry = z.infer<typeof lsp31S3EntrySchema>;
+/** Lumera/Pastel Cascade storage entry */
+type Lsp31LumeraEntry = z.infer<typeof lsp31LumeraEntrySchema>;
+/** Arweave storage entry */
+type Lsp31ArweaveEntry = z.infer<typeof lsp31ArweaveEntrySchema>;
+/** Discriminated union of all storage entry types */
+type Lsp31Entry = z.infer<typeof lsp31EntrySchema>;
+/** Array of storage entries (minimum 2) */
+type Lsp31Entries = z.infer<typeof lsp31EntriesSchema>;
+/** Input data for encoding an LSP31 multi-storage URI */
+type Lsp31UriData = z.infer<typeof lsp31UriDataSchema>;
+/**
+ * Output of parsing an LSP31 multi-storage URI from on-chain bytes
+ * Used by parseLsp31Uri (implemented in Plan 02)
+ */
+interface ParsedLsp31Uri {
+    /** Verification method (4 bytes, e.g., 0x8019f9b1 for keccak256(bytes)) */
+    verificationMethod: Hex;
+    /** Verification data (keccak256 hash of content bytes) */
+    verificationData: Hex;
+    /** Decoded and validated storage entries */
+    entries: Lsp31Entry[];
+}
+
+/**
+ * LSP31 Multi-Storage URI Decoding
+ *
+ * Parses and verifies LSP31 on-chain hex values back into structured data.
+ * Mirrors the LSP2 parseVerifiableUri/decodeVerifiableUri pattern.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Parses an LSP31 Multi-Storage URI hex value into its components.
+ *
+ * Format: 0x + reserved (2 bytes) + method (4 bytes) + length (2 bytes) + hash (N bytes) + entries JSON
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @returns Parsed components (verificationMethod, verificationData, entries)
+ * @throws Error if the value is malformed, wrong prefix, or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * const { verificationMethod, verificationData, entries } = parseLsp31Uri(rawValue);
+ * entries.forEach(entry => console.log(entry.backend));
+ * ```
+ */
+declare function parseLsp31Uri(value: Hex): ParsedLsp31Uri;
+/**
+ * Decodes and verifies an LSP31 Multi-Storage URI against its content bytes.
+ *
+ * 1. Parses the URI structure
+ * 2. Verifies the verification method is keccak256(bytes)
+ * 3. Computes keccak256 of the provided content and checks against the embedded hash
+ * 4. Validates entries through Zod schema
+ *
+ * @param value - The raw hex value from ERC725Y getData
+ * @param content - The actual content bytes (used to verify the hash)
+ * @returns Validated entries and verification data
+ * @throws Error if hash doesn't match, method is unsupported, or entries are invalid
+ *
+ * @example
+ * ```typescript
+ * const contentBytes = await fetchFromBackend(entry);
+ * const { entries, verificationData } = decodeLsp31Uri(rawValue, contentBytes);
+ * ```
+ */
+declare function decodeLsp31Uri(value: Hex, content: Uint8Array): {
+    entries: Lsp31Entry[];
+    verificationData: Hex;
+};
+
+/**
+ * LSP31 Multi-Storage URI Encoding
+ *
+ * Encodes multi-storage entries into the LSP31 on-chain format:
+ * 0x0031 + method (4) + hashLength (2) + hash (32) + toUtf8Hex(JSON.stringify(entries))
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Computes the keccak256 content hash from raw bytes.
+ *
+ * @param content - Raw content bytes (identical across all storage backends)
+ * @returns keccak256 hash as a 0x-prefixed hex string
+ *
+ * @example
+ * ```typescript
+ * const contentBytes = new Uint8Array([...]);
+ * const hash = computeContentHash(contentBytes);
+ * const encoded = encodeLsp31Uri(entries, hash);
+ * ```
+ */
+declare function computeContentHash(content: Uint8Array): Hex;
+/**
+ * Encodes storage entries and a pre-computed verification hash into the LSP31 on-chain format.
+ *
+ * The output is a hex string with the layout:
+ * - 2 bytes: reserved prefix (0x0031)
+ * - 4 bytes: verification method ID (0x8019f9b1, keccak256(bytes))
+ * - 2 bytes: hash length (0x0020 = 32 bytes)
+ * - 32 bytes: content verification hash
+ * - variable: UTF-8 encoded JSON of entries array
+ *
+ * @param entries - Array of storage backend entries (minimum 2)
+ * @param verificationHash - Pre-computed keccak256 hash of the content bytes (0x + 64 hex chars)
+ * @returns Hex-encoded LSP31 URI value
+ * @throws Error if entries fail validation or hash format is invalid
+ *
+ * @example
+ * ```typescript
+ * const entries = [
+ *   { backend: 'ipfs', cid: 'QmTest...' },
+ *   { backend: 's3', bucket: 'my-bucket', key: 'file.bin', region: 'us-east-1' },
+ * ];
+ * const hash = computeContentHash(contentBytes);
+ * const encoded = encodeLsp31Uri(entries, hash);
+ * ```
+ */
+declare function encodeLsp31Uri(entries: Lsp31Entry[], verificationHash: Hex): Hex;
+
+/**
+ * LSP31 Multi-Storage URI Type Guards
+ *
+ * Quick structural checks for identifying LSP31 encoded values.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Checks if a hex value appears to be a valid LSP31 Multi-Storage URI format.
+ *
+ * This is a quick structural check based on length and prefix, not full content validation.
+ * Distinguishes LSP31 (0x0031 prefix) from LSP2 VerifiableURI (0x0000 prefix).
+ *
+ * @param value - Hex value to check
+ * @returns true if the value has valid LSP31 structure
+ *
+ * @example
+ * ```typescript
+ * if (isLsp31Uri(rawValue)) {
+ *   const { entries } = parseLsp31Uri(rawValue);
+ * } else if (isVerifiableUri(rawValue)) {
+ *   const { url } = parseVerifiableUri(rawValue);
+ * }
+ * ```
+ */
+declare function isLsp31Uri(value: Hex): boolean;
+
+/**
+ * LSP31 Multi-Storage URI Resolver
+ *
+ * Pure functions for selecting preferred storage backends and deriving access URLs.
+ * No actual fetching — that's the app layer's responsibility.
+ *
+ * @see LSP-31-MultiStorageURI.md for full specification
+ */
+
+/**
+ * Selects and orders storage entries based on preference.
+ *
+ * Uses exhaustive fallback: preferred entries come first, then remaining entries
+ * in their original order. Output always has the same length as input — no entries
+ * are ever dropped.
+ *
+ * @param entries - Array of storage entries to order
+ * @param preference - Optional preferred backend(s). Can be:
+ *   - undefined: returns entries in original order
+ *   - string: single preferred backend
+ *   - array: ordered list of preferred backends
+ *   - empty array: treated as undefined (no preference)
+ * @returns New array with all entries, preferred ones first
+ *
+ * @example
+ * ```typescript
+ * const ordered = selectBackend(entries, 'ipfs');
+ * // IPFS entry first, then remaining in original order
+ *
+ * const ordered2 = selectBackend(entries, ['lumera', 'ipfs']);
+ * // Lumera first, IPFS second, then remaining
+ * ```
+ */
+declare function selectBackend(entries: Lsp31Entry[], preference?: Lsp31Backend | Lsp31Backend[]): Lsp31Entry[];
+/**
+ * Derives an access URL from a storage backend entry.
+ *
+ * Returns protocol URLs for IPFS and Lumera (actual gateway resolution is app-layer),
+ * and direct HTTPS URLs for S3 and Arweave.
+ *
+ * @param entry - A single storage entry
+ * @returns The derived access URL
+ *
+ * @example
+ * ```typescript
+ * const url = resolveUrl({ backend: 'ipfs', cid: 'QmTest...' });
+ * // 'ipfs://QmTest...'
+ *
+ * const url2 = resolveUrl({ backend: 's3', bucket: 'b', key: 'k', region: 'r' });
+ * // 'https://b.s3.r.amazonaws.com/k'
+ * ```
+ */
+declare function resolveUrl(entry: Lsp31Entry): string;
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, LSP31_BACKENDS, LSP31_MIN_ENTRIES, LSP31_RESERVED_PREFIX, MIN_LSP31_URI_LENGTH, computeContentHash, decodeLsp31Uri, encodeLsp31Uri, isLsp31Uri, lsp31ArweaveEntrySchema, lsp31EntriesSchema, lsp31EntrySchema, lsp31IpfsEntrySchema, lsp31LumeraEntrySchema, lsp31S3EntrySchema, lsp31UriDataSchema, parseLsp31Uri, resolveUrl, selectBackend };
+export type { Lsp31ArweaveEntry, Lsp31Backend, Lsp31Entries, Lsp31Entry, Lsp31IpfsEntry, Lsp31LumeraEntry, Lsp31S3Entry, Lsp31UriData, ParsedLsp31Uri };

package/dist/index.mjs

@@ -0,0 +1,175 @@
+import { keccak256, slice, hexToString, stringToHex, concat } from 'viem';
+import { z } from 'zod';
+
+const LSP31_RESERVED_PREFIX = "0x0031";
+const KECCAK256_BYTES_METHOD_ID = "0x8019f9b1";
+const HASH_LENGTH_PREFIX = "0x0020";
+const MIN_LSP31_URI_LENGTH = 82;
+const LSP31_BACKENDS = ["ipfs", "s3", "lumera", "arweave"];
+const LSP31_MIN_ENTRIES = 2;
+
+const lsp31IpfsEntrySchema = z.object({
+  backend: z.literal("ipfs"),
+  /** IPFS content identifier (CIDv0 or CIDv1) */
+  cid: z.string().min(1, "CID is required")
+});
+const lsp31S3EntrySchema = z.object({
+  backend: z.literal("s3"),
+  /** S3 bucket name */
+  bucket: z.string().min(1, "Bucket is required"),
+  /** S3 object key */
+  key: z.string().min(1, "Key is required"),
+  /** AWS region (e.g., "us-east-1") */
+  region: z.string().min(1, "Region is required")
+});
+const lsp31LumeraEntrySchema = z.object({
+  backend: z.literal("lumera"),
+  /** Lumera/Pastel Cascade action ID */
+  actionId: z.string().min(1, "Action ID is required")
+});
+const lsp31ArweaveEntrySchema = z.object({
+  backend: z.literal("arweave"),
+  /** Arweave transaction ID */
+  transactionId: z.string().min(1, "Transaction ID is required")
+});
+const lsp31EntrySchema = z.discriminatedUnion("backend", [
+  lsp31IpfsEntrySchema,
+  lsp31S3EntrySchema,
+  lsp31LumeraEntrySchema,
+  lsp31ArweaveEntrySchema
+]);
+const lsp31EntriesSchema = z.array(lsp31EntrySchema).min(
+  LSP31_MIN_ENTRIES,
+  "LSP31 requires at least 2 storage entries \u2014 use LSP2 VerifiableURI for single-backend content"
+);
+const lsp31UriDataSchema = z.object({
+  /** keccak256 hash of content bytes, 0x-prefixed 64-char hex string */
+  verificationHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/, "Must be a 0x-prefixed 64-char hex hash"),
+  /** Storage backend entries (minimum 2) */
+  entries: lsp31EntriesSchema
+});
+
+function parseLsp31Uri(value) {
+  if (value.length < MIN_LSP31_URI_LENGTH) {
+    throw new Error(
+      `Invalid LSP31 URI: value too short (${value.length} chars, minimum ${MIN_LSP31_URI_LENGTH})`
+    );
+  }
+  const reservedPrefix = slice(value, 0, 2);
+  if (reservedPrefix !== LSP31_RESERVED_PREFIX) {
+    throw new Error(
+      `Invalid LSP31 URI: expected prefix ${LSP31_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 entriesHex = slice(value, 8 + hashLength);
+  let entries;
+  try {
+    const entriesJson = hexToString(entriesHex);
+    entries = JSON.parse(entriesJson);
+  } catch {
+    throw new Error("Invalid LSP31 URI: entries portion contains invalid JSON");
+  }
+  return {
+    verificationMethod,
+    verificationData,
+    entries
+  };
+}
+function decodeLsp31Uri(value, content) {
+  const parsed = parseLsp31Uri(value);
+  if (parsed.verificationMethod !== KECCAK256_BYTES_METHOD_ID) {
+    throw new Error(
+      `Unsupported verification method: ${parsed.verificationMethod}. Expected ${KECCAK256_BYTES_METHOD_ID} (keccak256(bytes))`
+    );
+  }
+  const computedHash = keccak256(content);
+  if (computedHash.toLowerCase() !== parsed.verificationData.toLowerCase()) {
+    throw new Error(
+      `LSP31 hash mismatch: content hash ${computedHash} does not match verification data ${parsed.verificationData}`
+    );
+  }
+  const validatedEntries = lsp31EntriesSchema.parse(parsed.entries);
+  return {
+    entries: validatedEntries,
+    verificationData: parsed.verificationData
+  };
+}
+
+function computeContentHash(content) {
+  return keccak256(content);
+}
+function encodeLsp31Uri(entries, verificationHash) {
+  lsp31EntriesSchema.parse(entries);
+  if (typeof verificationHash !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(verificationHash)) {
+    throw new Error(
+      `Invalid verification hash: expected 0x-prefixed 64-char hex string, got ${String(verificationHash).slice(0, 20)}...`
+    );
+  }
+  const entriesHex = stringToHex(JSON.stringify(entries));
+  return concat([
+    LSP31_RESERVED_PREFIX,
+    KECCAK256_BYTES_METHOD_ID,
+    HASH_LENGTH_PREFIX,
+    verificationHash,
+    entriesHex
+  ]);
+}
+
+function isLsp31Uri(value) {
+  if (value.length < MIN_LSP31_URI_LENGTH) {
+    return false;
+  }
+  try {
+    const reservedPrefix = slice(value, 0, 2);
+    return reservedPrefix === LSP31_RESERVED_PREFIX;
+  } catch {
+    return false;
+  }
+}
+
+function selectBackend(entries, preference) {
+  if (!preference || Array.isArray(preference) && preference.length === 0) {
+    return [...entries];
+  }
+  const prefs = typeof preference === "string" ? [preference] : preference;
+  const placed = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const pref of prefs) {
+    for (let i = 0; i < entries.length; i++) {
+      if (!placed.has(i) && entries[i].backend === pref) {
+        result.push(entries[i]);
+        placed.add(i);
+      }
+    }
+  }
+  for (let i = 0; i < entries.length; i++) {
+    if (!placed.has(i)) {
+      result.push(entries[i]);
+    }
+  }
+  return result;
+}
+function resolveUrl(entry) {
+  switch (entry.backend) {
+    case "ipfs":
+      return `ipfs://${entry.cid}`;
+    case "s3":
+      return `https://${entry.bucket}.s3.${entry.region}.amazonaws.com/${encodeURIComponent(entry.key)}`;
+    case "lumera":
+      return `lumera://${entry.actionId}`;
+    case "arweave":
+      return `https://arweave.net/${entry.transactionId}`;
+    default: {
+      const _exhaustive = entry;
+      throw new Error(
+        `Unknown backend: ${_exhaustive.backend}`
+      );
+    }
+  }
+}
+
+export { HASH_LENGTH_PREFIX, KECCAK256_BYTES_METHOD_ID, LSP31_BACKENDS, LSP31_MIN_ENTRIES, LSP31_RESERVED_PREFIX, MIN_LSP31_URI_LENGTH, computeContentHash, decodeLsp31Uri, encodeLsp31Uri, isLsp31Uri, lsp31ArweaveEntrySchema, lsp31EntriesSchema, lsp31EntrySchema, lsp31IpfsEntrySchema, lsp31LumeraEntrySchema, lsp31S3EntrySchema, lsp31UriDataSchema, parseLsp31Uri, resolveUrl, selectBackend };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@chillwhales/lsp31",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "LSP31 Multi-Storage URI standard — encode, decode, and resolve multi-backend content references",
+  "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/lsp31"
+  },
+  "keywords": [
+    "chillwhales",
+    "lukso",
+    "lsp",
+    "lsp31",
+    "multi-storage",
+    "storage-uri"
+  ],
+  "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"
+  }
+}