Encrypted NFT Manifests (ENM-1) - Public and Private Multi-File NFTs

[lennynerowuzhere]

title: Encrypted NFT Manifests (ENM-1) - Public and Private Multi-File NFTs
author: Lenny Nero lennynero722@gmail.com
working-group: Native Hedera Economic Stack
type: Standards Track
category: Application
status: Draft
needs-hiero-approval: No
needs-hedera-review: No
created: 2025-09-05
updated: 2025-12-12
requires: 412, 920, 1081, 1195

Abstract

This HIP defines ENM-1 (Encrypted NFT Manifest version 1), a standardized JSON manifest format for NFT metadata that includes both public and encrypted private files. ENM-1 uses a Hybrid Schema that is a strict superset of HIP-412 v2, maintaining full backward compatibility by preserving standard root-level fields (name, image, description, attributes) while introducing an enm object for encrypted content specifications.

The standard enables content creators to embed locked content within NFT metadata that only the current token holder can decrypt, without requiring smart contracts or on-chain key management. Key distribution uses Key Encapsulation Mechanism (KEM) exclusively—the keyHints field stores encrypted key capsules, NEVER raw symmetric keys.

Key innovations include Mandatory KEM for key security (client-side enforcement), Storage Location Enum that PROHIBITS raw on-chain storage, Dynamic Batching for safe transaction sizing, HIP-1195 Hook Integration for access control validation, Consolidated URI Handling for future-proof storage support, and adherence to the Layer Architecture where L1 anchors the token and L4 stores encrypted metadata.

Encryption and decryption occur entirely client-side using AES-256-GCM or ChaCha20-Poly1305. No private keys are stored on-chain.

---

Motivation

NFT creators frequently need to attach private or exclusive content to tokens, but current approaches have significant limitations:

Premium content for members: Music artists want to include high-resolution audio, behind-the-scenes videos, or unreleased tracks that only NFT holders can access. HIP-920 established excellent metadata patterns for music NFTs but lacks encryption support for premium content. Artists lose potential revenue when they can't offer tiered access.

Private documents for compliance: Real-world asset tokenization requires attaching legal documents, certifications, and compliance materials that should only be visible to verified token holders. A tokenized property deed needs associated legal documents that shouldn't be public.

Gaming and surprise mechanics: Game developers want to hide attributes, lore documents, or bonus content until a player owns specific NFTs. Current solutions require centralized servers that can go offline.

Phased reveals: Creators want to sell NFTs with hidden content that only becomes accessible after purchase. Mystery box mechanics require trustworthy encryption.

Multi-tier access: DAOs and membership organizations need to gate different content levels based on token rarity or type without deploying complex access control contracts.

Compatibility requirements: Any solution must work seamlessly with existing HIP-412 and HIP-920 compliant wallets and explorers, which expect standard root-level fields. Breaking compatibility fragments the ecosystem.

Security gaps in existing approaches:

• Raw key storage: Systems that store symmetric keys directly are vulnerable to key theft from manifest inspection, logs, or network traffic
• Centralized platforms: Require trust in platform, create vendor lock-in, can disappear
• Smart contract gating: Expensive ($15-30 to deploy), vulnerable to exploits, complex to maintain
• Public IPFS: Anyone can access "private" content by guessing or discovering CIDs
• Off-chain databases: Break composability, not verifiable, not portable
• Fixed batch sizes: Lead to transaction failures when metadata exceeds network limits

A standardized encrypted manifest format with mandatory KEM, prohibited raw storage, and dynamic batching solves these problems while maintaining full backward compatibility with existing NFT infrastructure.

---

Rationale

Design Decisions

Hybrid Schema (Strict Superset of HIP-412 v2): ENM-1 manifests MUST include standard HIP-412 root-level fields (name, image, description, attributes, type, etc.) while adding encrypted content in a dedicated enm object. This ensures existing wallets display NFTs correctly (they ignore the enm object), ENM-aware wallets provide enhanced UX, no migration is required, and full compatibility with HIP-920 music metadata is maintained.

enm Object Encapsulation: All encrypted content metadata lives within an enm object:

{
  "name": "My NFT",
  "image": "ipfs://...",
  "enm": {
    "version": "1.0",
    "encrypted_files": [...]
  }
}

This separation provides clear namespace isolation and makes ENM detection trivial.

Mandatory Key Encapsulation Mechanism (KEM): The keyHints field MUST store an encrypted key capsule, NEVER a raw symmetric key:

PROHIBITED: { "aes_key": "raw_base64_key..." }
REQUIRED:   { "method": "jwe", "capsule": { "ciphertext": "..." } }

IMPORTANT: This is a Client-Side/Standard Compliance requirement, not a protocol-enforced rule. L1 Consensus Nodes see only byte arrays and cannot validate encryption quality. Malformed or insecure manifests are technically valid on-chain but MUST be rejected by compliant wallets.

Storage Location Enum: Encrypted metadata MUST be stored off-chain. The protocol defines three valid storage options and PROHIBITS raw on-chain storage:

enum MetadataStorageLocation {
  OFF_CHAIN = 1;        // IPFS, Arweave, HTTPS
  HASHINAL = 2;         // HCS Topic (native L4)
  PRIVATE_SPHERE = 3;   // HashSphere (enterprise)
  // RAW_ON_CHAIN is PROHIBITED - intentionally omitted
}

Consolidated URI Handling: Instead of separate fields for each storage type (ipfs_cid, arweave_tx, etc.), use a generic uri field with the location enum. This future-proofs against new storage networks:

message MetadataStorageConfig {
  MetadataStorageLocation location = 1;
  string uri = 2;  // Generic: ipfs://..., ar://..., https://..., hcs://0.0.123456
  bytes manifest_hash_sha384 = 3;
}

Dynamic Batching Safety: Clients MUST query maxTransactionSize at runtime before batching. Fixed batch sizes are PROHIBITED as they cause transaction failures when metadata varies.

HIP-1195 Hook Integration: Token mint wrapper includes hook trigger for access control validation.

Prior Art

This HIP builds upon HIP-412 (NFT Metadata), HIP-920 (Music NFT Metadata), ERC-721 tokenURI patterns, IPFS content addressing, Lit Protocol access control concepts, and W3C Verifiable Credentials selective disclosure patterns.

---

User Stories

Music Artist: "I want to sell music NFTs that follow HIP-920 standards (with genre, BPM, artwork) AND include encrypted high-fidelity audio files that only buyers can access."

Game Developer: "I want my NFTs to display normally in any wallet while hiding bonus lore documents and achievement certificates for owners."

Real Estate Platform: "I want property NFTs with public listing photos AND encrypted legal documents that only the current owner can decrypt."

DAO Member: "I want membership NFTs that work in standard wallets AND contain encrypted governance documents."

Multi-chain User: "I want to specify decryption keys using my EVM address, not just my Hedera account ID."

Collector: "I want my existing wallet to show NFT images and names normally, while ENM-aware wallets also show me my encrypted content."

Security-conscious Creator: "I want assurance that my encryption keys are never exposed—only encrypted capsules should be stored."

Enterprise Developer: "I want my batch minting operations to automatically adjust to network limits without manual tuning."

---

Specification

Layer Architecture

Layer	Component	Role
L1	Consensus Nodes	Token mint/transfer (O(1)), metadata URI reference only
L4	HCS/IPFS/HashSphere	Encrypted manifest storage
Client	Wallet/dApp	ALL encryption/decryption (never on L1 or L4)

L1 Prohibited: File storage, encrypted content, any data exceeding transaction limits, cryptographic validation of manifest contents.

Block Node Role

While HIP-1612 is primarily an Application HIP, Block Nodes provide supporting functions:

Function	Description
resolveMetadataURI	Fetch and cache manifest from L4
validateManifestSchema	Verify ENM-1 compliance
generateAccessProof	Create ownership proof for key servers

Not at Block Nodes: Decryption keys, plaintext content (never leave client).

Storage Location Enum

enum MetadataStorageLocation {
  STORAGE_UNSPECIFIED = 0;
  OFF_CHAIN = 1;        // IPFS, Arweave, HTTPS URL
  HASHINAL = 2;         // HCS Topic (native Hedera L4)
  PRIVATE_SPHERE = 3;   // HashSphere (enterprise private)
  // RAW_ON_CHAIN is PROHIBITED - intentionally omitted
}

Consolidated Storage Config

message MetadataStorageConfig {
  MetadataStorageLocation location = 1;
  
  // Generic URI field - future-proof for new storage networks
  // Examples: "ipfs://Qm...", "ar://...", "https://...", "hcs://0.0.123456"
  string uri = 2;
  
  // SHA-384 hash of manifest for integrity
  bytes manifest_hash_sha384 = 3;
}

TokenMint Wrapper with Hook

message TokenMintEnmWrapper {
  TokenID token_id = 1;
  repeated bytes metadata = 2;
  bytes hook_id = 3;  // HIP-1195 Trigger
  MetadataStorageConfig storage_config = 4;
}

ENM-1 Hybrid Schema Structure

Root level maintains HIP-412/920 compatibility; enm object adds encryption:

{
  "name": "Track Title",
  "image": "ipfs://QmPreview...",
  "type": "image/jpeg",
  "description": "Limited edition with exclusive audio",
  "attributes": [{ "trait_type": "Rarity", "value": "Legendary" }],
  "properties": { "genre": "Electronic", "bpm": 128 },
  
  "enm": {
    "version": "1.0",
    "schema": "ENM-1",
    "storage": { "location": "HASHINAL", "uri": "hcs://0.0.123456" },
    "encrypted_files": [...],
    "key_hints": [...]
  }
}

Key Hint with Mandatory KEM

{
  "method": "jwe",
  "account_id": "0.0.12345",
  "capsule": {
    "algorithm": "ECDH-ES+A256KW",
    "ephemeral_public_key": "base64...",
    "ciphertext": "base64_encrypted_cek...",
    "key_hash_sha384": "verification_hash..."
  }
}

CRITICAL: The capsule contains encrypted key material. Raw keys are NEVER stored. This is enforced by client validation, not protocol rules.

Supported KEM Methods

Method	Algorithm	Use Case
jwe	ECDH-ES+A256KW, RSA-OAEP-256	Standard web encryption
did	X25519 key agreement	Decentralized identity
kms	AWS/Azure/GCP/HashiCorp	Enterprise key management
password	PBKDF2/Argon2id	User-controlled access
ml_kem	ML-KEM-768 (Kyber)	Post-quantum security

Dynamic Batching Requirement

Clients MUST query network parameters at runtime:

async function createSafeBatches(metadataList: string[]): Promise<string[][]> {
  const params = await getNetworkParams();  // Query at runtime
  const maxSize = params.maxTransactionSize - 500;  // Reserve overhead
  
  // Build batches dynamically based on actual sizes
  // PROHIBITED: const BATCH_SIZE = 10; // Fixed sizes fail
}

Encryption Workflow

Creator-side (client):

1. Generate random AES-256 CEK
2. Encrypt content with CEK
3. Encapsulate CEK using recipient's public key (KEM)
4. Store encrypted capsule in key_hints—never raw CEK
5. Upload encrypted content to L4
6. Create manifest with enm object

Wallet-side (client):

1. Verify NFT ownership
2. Check access conditions (including HIP-1195 hook if specified)
3. Decapsulate CEK from encrypted capsule
4. Verify CEK integrity via SHA-384 hash
5. Decrypt content
6. Verify plaintext hash
7. Clear CEK from memory

Wallet Behavior

Non-ENM Wallets: Display name, image, description, attributes normally; ignore enm object.

ENM-Aware Wallets: Show lock icons, display encrypted file count, provide "Unlock" button, handle decapsulation flow, REJECT manifests with raw keys.

---

Security Considerations

Client-Side KEM Enforcement: The requirement that keyHints stores encrypted capsules (never raw keys) is a standard compliance requirement, not a protocol-enforced rule. L1 Consensus Nodes see only byte arrays and cannot validate cryptographic quality. Malformed or insecure manifests are technically valid on-chain but MUST be rejected by compliant wallets. This is similar to how HTTPS certificates are validated by browsers, not by DNS.

Storage Location Restriction: RAW_ON_CHAIN is PROHIBITED. All content stored at L4 prevents consensus state bloat and transaction failures.

Dynamic Batching: Fixed batch sizes are PROHIBITED. Runtime parameter queries prevent transaction failures from size overflows.

Confidentiality: Encrypted files remain confidential until keys are obtained.

Metadata Privacy Acknowledgment: The manifest reveals metadata about encrypted content including: file names, file sizes, MIME types, and encryption parameters. Traffic analysis could potentially identify content types (e.g., a 4GB file is likely video). This is an acceptable trade-off for UX but users should be aware that "size fingerprinting" is possible.

Authentication: AES-GCM provides authenticated encryption. SHA-384 hashes enable verification at multiple stages.

Key Rotation on Transfer: Previous owner may retain keys. Creators can accept this (one-time secrets), re-encrypt for new owner, or use revocable key servers.

Delegation Separation: HIP-1611 governance delegation does NOT grant decryption rights.

Post-Quantum Readiness: ML-KEM-768 support ensures future security.

---

Backward Compatibility

ENM-1 is fully backward compatible:

• HIP-412 v2: All required root fields present; wallets display normally
• HIP-920 Music: All music metadata fields supported at root level
• Existing NFTs: No changes required; ENM is additive
• Non-ENM Wallets: Simply ignore enm object
• Migration: Existing NFTs can add enm via metadata update (if mutable)

---

How to Teach This

For Creators: "Keep normal NFT metadata at root level—that's what wallets see. Add the enm object for encrypted content. Keys are always encrypted (capsules), never stored raw. Wallets enforce this, not the protocol."

For Wallet Developers: "Check for enm object. If present, show lock icons and decrypt on demand. REJECT manifests with raw keys in key_hints. Query network params before batching."

For Users: "Your NFT shows up normally in any wallet. ENM-enabled wallets show you have locked content. Click to unlock using your wallet's private key. Note: file sizes are visible even when encrypted."

---

Reference Implementation

See assets/hip-1612/enm_schema.json for complete JSON schema and assets/hip-1612/enm_types.proto for protobuf definitions.

---

Rejected Ideas

• Replacing HIP-412: Rejected for backward compatibility
• On-chain key storage: Rejected for security
• Raw key storage in hints: Rejected—KEM is mandatory (client-enforced)
• RAW_ON_CHAIN storage: Rejected for state bloat
• Fixed batch sizes: Rejected for reliability
• Separate URI fields per storage type: Rejected—generic uri field is more future-proof

---

Open Issues

1. Should there be a maximum manifest size recommendation?
2. Should there be a standard for key rotation events on transfer?

---

References

• HIP-412: NFT Token Metadata JSON Schema
• HIP-920: Music NFT Metadata Standard
• HIP-1081: Block Nodes
• HIP-1195: Hiero Hooks
• NIST SP 800-38D: AES-GCM Specification
• RFC 7516: JSON Web Encryption (JWE)
• NIST FIPS 203: ML-KEM (Kyber)

---