Collections

Curated NFT collections with optional merkle proof enforcement

The ERC-721 Ethscriptions Collections protocol allows creators to build curated collections of ethscriptions with rich metadata and optional access control.

Collections are an AppChain-only feature. They require smart contract execution on the L2.

Overview

• Collection: A named set of ethscriptions with metadata (name, symbol, description, max supply)

• Items: Individual ethscriptions added to a collection

• Merkle Enforcement: Optional cryptographic restriction on which items can be added

Creating a Collection

Use the create_collection_and_add_self operation to create a collection and add the first item in one transaction:

data:image/png;rule=esip6;p=erc-721-ethscriptions-collection;op=create_collection_and_add_self;d=<base64-json>;base64,<image-bytes>

The rule=esip6 parameter allows duplicate content. Without it, if the same data URI (including headers) was used in a previous ethscription, the new ethscription would be rejected as a duplicate. Uniqueness is based on SHA256 of the full data URI, not just the payload.

Where the base64-decoded d parameter contains:

{
  "metadata": {
    "name": "My Collection",
    "symbol": "MYC",
    "max_supply": "100",
    "description": "A curated collection of digital artifacts",
    "logo_image_uri": "",
    "banner_image_uri": "",
    "background_color": "",
    "website_link": "https://example.com",
    "twitter_link": "myhandle",
    "discord_link": "https://discord.gg/...",
    "merkle_root": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "initial_owner": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "item": {
    "item_index": "0",
    "name": "Item #1",
    "background_color": "#FF0000",
    "description": "The first item in the collection",
    "attributes": [
      { "trait_type": "Rarity", "value": "Legendary" },
      { "trait_type": "Color", "value": "Red" }
    ],
    "merkle_proof": []
  }
}

Metadata Object Fields

All fields must be present in exact order. Use empty strings for optional values.

Field	Description
name	Collection name
symbol	Short symbol (e.g., "MYC")
max_supply	Maximum number of items (as string)
description	Collection description (can be empty)
logo_image_uri	Logo image as Data URI (can be empty)
banner_image_uri	Banner image as Data URI (can be empty)
background_color	Default background color (can be empty)
website_link	Project website URL (can be empty)
twitter_link	Twitter/X handle (can be empty)
discord_link	Discord invite URL (can be empty)
merkle_root	Merkle root for access control (use zero bytes32 for owner-only)
initial_owner	Address that will own the collection (lowercase)

Item Object Fields

Field	Description
item_index	Position in collection (0-indexed, as string)
name	Item name
background_color	Item-specific background color
description	Item description
attributes	Array of { trait_type, value } objects
merkle_proof	Array of proof hashes (for non-owner adds)

Strict Key Order: For JSON-based operations, keys must appear in exactly the order shown in the tables above. Attribute objects must use { "trait_type": "...", "value": "..." } key order.

Adding Items to a Collection

After creating a collection, add items with add_self_to_collection:

data:image/png;rule=esip6;p=erc-721-ethscriptions-collection;op=add_self_to_collection;d=<base64-json>;base64,<image-bytes>

Where the d parameter contains:

{
  "collection_id": "0x...",
  "item": {
    "item_index": "1",
    "name": "Item #2",
    "background_color": "#00FF00",
    "description": "The second item",
    "attributes": [
      { "trait_type": "Rarity", "value": "Rare" },
      { "trait_type": "Color", "value": "Green" }
    ],
    "merkle_proof": []
  }
}

The collection_id is the L1 transaction hash of the collection creation.

Merkle Proof Enforcement

When a collection has a non-zero merkle_root, non-owners must provide a merkle proof to add items. This ensures only pre-approved items with exact metadata can be added.

How It Works

1. Creator generates merkle tree from approved items

2. Each leaf is computed from item metadata

3. Creator sets merkle root when creating collection

4. Non-owners provide proofs when adding items

Merkle Leaf Computation

Each leaf is computed as:

keccak256(abi.encode(
    contentHash,      // keccak256 of content bytes (bytes32)
    itemIndex,        // uint256
    name,             // string
    backgroundColor,  // string
    description,      // string
    attributes        // (string,string)[] - array of (trait_type, value) tuples
))

Merkle Tree Structure

For a 3-item collection, the tree looks like:

        root
       /    \
    H(0,1)   leaf2
    /    \
 leaf0  leaf1

Where:

• Proof for leaf0: [leaf1, leaf2]

• Proof for leaf1: [leaf0, leaf2]

• Proof for leaf2: [H(leaf0, leaf1)]

Pair Hashing

The merkle tree uses byte-wise ordering (same as OpenZeppelin):

function hashPair(a: Hex, b: Hex): Hex {
  // Compare bytes, not strings
  const aBytes = hexToBytes(a);
  const bBytes = hexToBytes(b);
  let aLessThanB = false;
  for (let i = 0; i < 32; i++) {
    if (aBytes[i] !== bBytes[i]) {
      aLessThanB = aBytes[i] < bBytes[i];
      break;
    }
  }
  return keccak256(concat(aLessThanB ? [a, b] : [b, a]));
}

This ensures consistent proof verification regardless of sibling order.

Adding Items with Proofs

Non-owners include the merkle proof in the item object:

{
  "collection_id": "0x...",
  "item": {
    "item_index": "1",
    "name": "Item #2",
    "background_color": "#00FF00",
    "description": "The second item",
    "attributes": [
      { "trait_type": "Rarity", "value": "Rare" }
    ],
    "merkle_proof": ["0xaab5a305...", "0x58672b0c..."]
  }
}

Owner Bypass

Collection owners can always add items without providing merkle proofs. This allows:

• Adding items not in the original tree

• Making corrections

• Flexibility for collection management

Example: Creating a Merkle-Enforced Collection

This walkthrough creates a 3-item collection where:

Item	Index	Added By	Merkle Proof Required?
Item 1 (Red)	0	Owner	No (owner bypass)
Item 2 (Green)	1	Non-owner	Yes
Item 3 (Blue)	2	Non-owner	Yes

Step 1: Compute Content Hashes

For each image, compute the keccak256 hash of the raw bytes:

Item 0 content hash: 0x666af27e...
Item 1 content hash: 0x06e51d26...
Item 2 content hash: 0x09ecc1a2...

Step 2: Build Merkle Leaves

Compute each leaf from the item metadata:

Leaf 0: keccak256(abi.encode(0x666af27e..., 0, "Item #1", "#FF0000", "First item", [("Rarity", "Common")]))
        = 0xd9b535b9...

Leaf 1: keccak256(abi.encode(0x06e51d26..., 1, "Item #2", "#00FF00", "Second item", [("Rarity", "Rare")]))
        = 0xaab5a305...

Leaf 2: keccak256(abi.encode(0x09ecc1a2..., 2, "Item #3", "#0000FF", "Third item", [("Rarity", "Epic")]))
        = 0x58672b0c...

Step 3: Compute Merkle Root

H(leaf0, leaf1) = 0x659a61c9...
Merkle Root = H(H(leaf0, leaf1), leaf2) = 0x06fbc22a...

Step 4: Create Collection (Owner)

The owner creates the collection with the merkle root and adds the first item:

1. Send a 0 ETH transaction to any address

2. Include the hex-encoded Data URI with op=create_collection_and_add_self

3. The merkle_root is set to 0x06fbc22a...

4. Save the transaction hash as collection_id

The owner doesn't need a merkle proof for their own item.

Step 5: Add Items (Non-Owner)

A different address adds items 2 and 3 with merkle proofs:

For Item 2 (index 1):

{
  "collection_id": "0x<tx-hash-from-step-4>",
  "item": {
    "item_index": "1",
    "name": "Item #2",
    "background_color": "#00FF00",
    "description": "Second item",
    "attributes": [
      { "trait_type": "Rarity", "value": "Rare" }
    ],
    "merkle_proof": ["0xd9b535b9...", "0x58672b0c..."]
  }
}

The proof must match exactly, and the metadata must match what was used to compute the leaf.

Operations Reference

Operation	Description
create_collection_and_add_self	Create collection and add first item
add_self_to_collection	Add item to existing collection
edit_collection	Update collection metadata
edit_collection_item	Update item metadata
transfer_ownership	Transfer collection ownership
renounce_ownership	Surrender ownership (to zero address)
remove_items	Delete items from collection
lock_collection	Prevent further additions

ESIP-6 is optional. Add rule=esip6 to your data URI only if you need to allow duplicate content (e.g., sending the same JSON command multiple times). Without it, an ethscription with identical content to an existing one will not be created. For image-based operations, add it to the header: data:image/png;rule=esip6;p=.... For text-based operations: data:;rule=esip6,{...json...}.

Editing Collections

Update collection metadata with edit_collection. Send as a data URI:

data:;rule=esip6,{"p":"erc-721-ethscriptions-collection","op":"edit_collection",...}

JSON payload (all fields required; pass current values to keep them, empty strings will clear fields):

{
  "p": "erc-721-ethscriptions-collection",
  "op": "edit_collection",
  "collection_id": "0x...",
  "description": "Updated description",
  "logo_image_uri": "",
  "banner_image_uri": "",
  "background_color": "",
  "website_link": "",
  "twitter_link": "",
  "discord_link": "",
  "merkle_root": "0x0000000000000000000000000000000000000000000000000000000000000000"
}

Only the collection owner can edit.

Editing Items

Update item metadata with edit_collection_item (all fields required):

{
  "p": "erc-721-ethscriptions-collection",
  "op": "edit_collection_item",
  "collection_id": "0x...",
  "item_index": "0",
  "name": "New Item Name",
  "background_color": "#FF0000",
  "description": "Updated description",
  "attributes": [
    { "trait_type": "Rarity", "value": "Legendary" }
  ]
}

Only the collection owner can edit items.

Removing Items

Remove items with remove_items using ethscription IDs (transaction hashes):

{
  "p": "erc-721-ethscriptions-collection",
  "op": "remove_items",
  "collection_id": "0x...",
  "ethscription_ids": [
    "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  ]
}

Only the collection owner can remove items.

Transferring Ownership

Transfer collection ownership with transfer_ownership:

{
  "p": "erc-721-ethscriptions-collection",
  "op": "transfer_ownership",
  "collection_id": "0x...",
  "new_owner": "0x..."
}

Only the current owner can transfer ownership.

Renouncing Ownership

Permanently surrender ownership with renounce_ownership:

{
  "p": "erc-721-ethscriptions-collection",
  "op": "renounce_ownership",
  "collection_id": "0x..."
}

After renouncing, no one can edit the collection or add items (unless they have valid merkle proofs for a non-zero merkle root collection).

Locking Collections

Once locked, no more items can be added:

{
  "p": "erc-721-ethscriptions-collection",
  "op": "lock_collection",
  "collection_id": "0x..."
}

This is irreversible. Only the collection owner can lock.

Error Handling

Error	Cause
Invalid Merkle proof	Proof doesn't match root, or metadata differs from what was used to compute the leaf
Merkle proof required	Non-owner tried to add to a collection with zero merkle root (owner-only mode)
Item slot taken	Index already has an item
Collection locked	Cannot add to locked collection
Exceeds max supply	Collection is full
Not collection owner	Only owner can perform this operation

Security Considerations

1. Content Hash Verification - The merkle leaf includes the content hash, ensuring exact image content is verified

2. Metadata Binding - All metadata is bound to the merkle proof and cannot be changed after the tree is computed

3. Owner Bypass - Collection owners can always add items, useful for corrections

4. Locking - Once locked, no more items can be added even with valid proofs

5. Zero Merkle Root - When merkle_root is zero, only the owner can add items

Generating Merkle Trees (TypeScript)

Below is complete TypeScript code using viem for generating merkle trees and collection calldata.

Dependencies

npm install viem

Helper Functions

import {
  keccak256,
  encodeAbiParameters,
  stringToHex,
  concat,
  hexToBytes,
  type Hex,
} from 'viem';

/**
 * Compare two bytes32 values byte-by-byte (matches OpenZeppelin)
 */
function lt32(a: Hex, b: Hex): boolean {
  const aBytes = hexToBytes(a);
  const bBytes = hexToBytes(b);
  for (let i = 0; i < 32; i++) {
    if (aBytes[i] !== bBytes[i]) return aBytes[i] < bBytes[i];
  }
  return false;
}

/**
 * Hash pair with byte-wise ordering (matches OpenZeppelin MerkleProof)
 */
function hashPair(a: Hex, b: Hex): Hex {
  return keccak256(concat(lt32(a, b) ? [a, b] : [b, a]));
}

/**
 * Compute content hash from image bytes
 */
function computeContentHash(imageBase64: string): Hex {
  const imageBytes = Uint8Array.from(Buffer.from(imageBase64, 'base64'));
  return keccak256(imageBytes);
}

/**
 * Compute merkle leaf hash matching the Solidity contract
 */
function computeLeafHash(
  contentHash: Hex,
  itemIndex: bigint,
  name: string,
  backgroundColor: string,
  description: string,
  attributes: { traitType: string; value: string }[]
): Hex {
  const encoded = encodeAbiParameters(
    [
      { name: 'contentHash', type: 'bytes32' },
      { name: 'itemIndex', type: 'uint256' },
      { name: 'name', type: 'string' },
      { name: 'backgroundColor', type: 'string' },
      { name: 'description', type: 'string' },
      { name: 'attributes', type: 'tuple[]', components: [
        { name: 'traitType', type: 'string' },
        { name: 'value', type: 'string' },
      ]},
    ],
    [
      contentHash,
      itemIndex,
      name,
      backgroundColor,
      description,
      attributes.map(a => ({ traitType: a.traitType, value: a.value })),
    ]
  );
  return keccak256(encoded);
}

/**
 * Build merkle tree from 3 leaves
 *
 * Tree structure:
 *         root
 *        /    \
 *     H(0,1)   leaf2
 *    /    \
 * leaf0  leaf1
 */
function buildMerkleTree(leaves: [Hex, Hex, Hex]): {
  root: Hex;
  proofs: [Hex[], Hex[], Hex[]];
} {
  const [leaf0, leaf1, leaf2] = leaves;
  const h01 = hashPair(leaf0, leaf1);
  const root = hashPair(h01, leaf2);

  return {
    root,
    proofs: [
      [leaf1, leaf2],  // Proof for leaf0
      [leaf0, leaf2],  // Proof for leaf1
      [h01],           // Proof for leaf2
    ],
  };
}

/**
 * Generate data URI for collection operations
 */
function generateCollectionDataUri(
  operation: string,
  params: object,
  imageBase64: string
): string {
  const jsonBase64 = Buffer.from(JSON.stringify(params)).toString('base64');
  return `data:image/png;rule=esip6;p=erc-721-ethscriptions-collection;op=${operation};d=${jsonBase64};base64,${imageBase64}`;
}

/**
 * Convert data URI to hex calldata for transaction
 */
function dataUriToHex(dataUri: string): Hex {
  return stringToHex(dataUri);
}

Complete Example

// Sample 1x1 pixel PNGs (red, green, blue)
const IMAGES = [
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==',
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M/wHwAEBgIApD5fRAAAAABJRU5ErkJggg==',
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPj/HwADBgIA/JDm2AAAAABJRU5ErkJggg==',
];

const ITEMS = [
  { name: 'Item #1', bg: '#FF0000', desc: 'First item', attrs: [{ traitType: 'Color', value: 'Red' }] },
  { name: 'Item #2', bg: '#00FF00', desc: 'Second item', attrs: [{ traitType: 'Color', value: 'Green' }] },
  { name: 'Item #3', bg: '#0000FF', desc: 'Third item', attrs: [{ traitType: 'Color', value: 'Blue' }] },
];

const OWNER_ADDRESS = '0xYourAddressHere';

// Step 1: Compute content hashes
const contentHashes = IMAGES.map(img => computeContentHash(img));
console.log('Content hashes:', contentHashes);

// Step 2: Compute merkle leaves
const leaves = ITEMS.map((item, i) => computeLeafHash(
  contentHashes[i],
  BigInt(i),
  item.name,
  item.bg,
  item.desc,
  item.attrs
)) as [Hex, Hex, Hex];
console.log('Leaves:', leaves);

// Step 3: Build merkle tree
const { root: merkleRoot, proofs } = buildMerkleTree(leaves);
console.log('Merkle root:', merkleRoot);
console.log('Proofs:', proofs);

// Step 4: Generate create collection calldata
const createParams = {
  metadata: {
    name: 'My Collection',
    symbol: 'MYC',
    max_supply: '3',
    description: 'A merkle-enforced collection',
    logo_image_uri: '',
    banner_image_uri: '',
    background_color: '',
    website_link: '',
    twitter_link: '',
    discord_link: '',
    merkle_root: merkleRoot,
    initial_owner: OWNER_ADDRESS.toLowerCase(),
  },
  item: {
    item_index: '0',
    name: ITEMS[0].name,
    background_color: ITEMS[0].bg,
    description: ITEMS[0].desc,
    attributes: ITEMS[0].attrs.map(a => ({ trait_type: a.traitType, value: a.value })),
    merkle_proof: [],  // Owner bypasses merkle check
  },
};

const createDataUri = generateCollectionDataUri(
  'create_collection_and_add_self',
  createParams,
  IMAGES[0]
);

console.log('Create collection data URI:', createDataUri);
console.log('Create collection hex:', dataUriToHex(createDataUri));

// Step 5: Generate add item calldata (for non-owner)
// Replace with actual collection_id after creating collection
const COLLECTION_ID = '0x<tx-hash-from-create>';

const addItemParams = {
  collection_id: COLLECTION_ID,
  item: {
    item_index: '1',
    name: ITEMS[1].name,
    background_color: ITEMS[1].bg,
    description: ITEMS[1].desc,
    attributes: ITEMS[1].attrs.map(a => ({ trait_type: a.traitType, value: a.value })),
    merkle_proof: proofs[1],  // Include proof for non-owner
  },
};

const addDataUri = generateCollectionDataUri(
  'add_self_to_collection',
  addItemParams,
  IMAGES[1]
);

console.log('Add item data URI:', addDataUri);
console.log('Add item hex:', dataUriToHex(addDataUri));

Sending Transactions

To create an ethscription, send a 0 ETH transaction with the hex calldata:

import { createWalletClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount('0xYourPrivateKey');
const client = createWalletClient({
  account,
  chain: mainnet,
  transport: http('https://your-rpc-url'),
});

// Self-ethscription (send to yourself)
const txHash = await client.sendTransaction({
  to: account.address,
  data: dataUriToHex(createDataUri),
  value: 0n,
});

console.log('Transaction hash (this is the collection_id):', txHash);