Feat/circular dependency fix

[allenday]

feat: add circular dependency resolution for validation schemas

Summary

• Implement automatic detection of circular dependencies in buf/validate types
• Use bytes fields with encode/decode helpers to break circular references
• Enable buf/validate schemas to compile successfully in Solidity

Changes

Automatic Circular Dependency Detection

• Added CIRCULAR_DEPENDENCY_MAP for FieldRules ↔ MapRules ↔ RepeatedRules relationships
• Implemented is_circular_dependency() and should_use_bytes_for_field() functions
• Automatic detection based on message and field type analysis

Bytes Field Solution

• Circular fields are converted to bytes representation with descriptive comments
• Original protobuf semantics preserved through encode/decode operations
• No manual intervention required - transparent to developers

Integration Across Generation Pipeline

• Updated struct generation to handle circular fields with comments
• Modified encoder/decoder to process bytes fields for circular references
• Applied field name mangling consistently throughout

Technical Details

Files Modified:

• protobuf-solidity/src/protoc/plugin/gen_util.py - Added circular dependency detection logic
• protobuf-solidity/src/protoc/plugin/gen_decoder.py - Updated to use bytes decoder for circular fields
• protobuf-solidity/src/protoc/plugin/gen_encoder.py - Updated to handle circular fields as bytes
• protobuf-solidity/src/protoc/plugin/gen_sol.py - Updated struct generation with circular field handling
• README.md - Added Circular Dependency Resolution documentation section

Key Functions Added:

• is_circular_dependency(msg, field) - Detects circular references
• should_use_bytes_for_field(msg, field) - Determines if bytes conversion needed

Circular Dependencies Resolved:

• FieldRules ↔ MapRules: Field rules can reference map validation rules
• FieldRules ↔ RepeatedRules: Field rules can reference repeated field validation rules
• MapRules → FieldRules: Map rules reference field rules for key/value validation

Example Output

struct BufValidateFieldRules {
    bytes map_field;        // Circular reference: use encode/decode helpers
    bytes repeated_field;   // Circular reference: use encode/decode helpers
    // ... other fields maintain their natural types
}

Test Plan

• Verify buf/validate schemas compile without circular dependency errors
• Test generated contracts build successfully with Forge/Hardhat
• Confirm circular fields can be serialized/deserialized correctly
• Validate non-circular fields maintain original type system

Dependencies

This PR builds on feat/solidity-compatibility for the field name mangling functionality used throughout the circular dependency resolution system.

Impact

Enables buf/validate and other validation schemas with circular dependencies to work seamlessly with the Solidity protobuf generator, expanding the plugin's capability to handle complex validation scenarios.