[Phase 3] Metadata Parser Refactoring (Issue #38)

[gmajor-encrypt]

Summary

This PR refactors the Metadata parser to support new version formats and optimize performance.

Features Implemented

Metadata Version Support

• v12/v13: Legacy module format
• v14: Portable types, modern pallet format
• v15: Runtime APIs, extended metadata

Components

MetadataVersion (enum)

• Version detection and validation
• Feature capability checks (portable types, APIs)

Pallet (class)

• Pallet name and index
• Storage entries lookup
• Call functions lookup
• Events and errors lookup
• Constants lookup

TypeDefinition (class)

• Type kind detection (composite/variant/sequence/array/tuple/primitive)
• Field extraction for structs
• Variant extraction for enums
• Element type for sequences/arrays

Metadata (class)

• Type registry by ID
• Pallet registry by name/index
• Type lookup by name/path
• Integration with TypeRegistry

MetadataParser (class)

• SCALE-encoded metadata parsing
• Magic number validation
• Version-specific parsing logic
• Metadata caching

Performance Optimizations

• Cached parsed metadata (md5 key)
• Lazy type resolution
• Quick lookup by name/path

Example Usage

use Substrate\ScaleCodec\Metadata\{MetadataParser, MetadataVersion};

$parser = new MetadataParser();
$metadata = $parser->parse($hexMetadata);

// Check version
echo $metadata->version->value; // 14 or 15

// Get pallet
$system = $metadata->getPallet('System');
$account = $system->getStorage('Account');

// Get type
$type = $metadata->getType(0);
if ($type->isComposite()) {
    $fields = $type->getFields();
}

// Register types into TypeRegistry
$metadata->registerTypes($registry);

Tests

• Unit tests in tests/Metadata/MetadataParserTest.php
• Version support tests
• Type definition tests
• Pallet lookup tests
• Caching tests

Issue

• Closes [Phase 3] Metadata Parser Refactoring #38

---

Ready for review.