Feature/make castorix library by RyanKung · Pull Request #1 · polyjuicelab/castorix

RyanKung · 2025-09-23T15:42:32Z

No description provided.

- Refactored project structure to support both CLI and library usage - Created src/core/ directory with organized modules: - client/: Farcaster Hub API client - crypto/: Key management and cryptographic utilities - protocol/: Message types and protocol implementation - Updated Cargo.toml to define both lib and bin targets - Removed feature flags, enabling all functionality by default - Updated all import paths to reflect new module structure - Enhanced README.md with comprehensive testing instructions - All unit tests (28/28) and integration tests (6/6) passing - Binary functionality fully preserved and working Breaking changes: - Module paths changed (e.g., crate::key_manager -> crate::core::crypto::key_manager) - Some functions moved from CLI-specific to library modules Features: - ✅ Binary + Library architecture - ✅ Clean module organization - ✅ Comprehensive test coverage - ✅ Updated documentation - ✅ Backward compatible CLI interface

- Remove all std::env::var() calls from src/ modules except consts.rs - Replace environment variable access with consts::get_config() calls - Update from_env() methods to return errors instead of reading env vars - Remove PRIVATE_KEY environment variable usage from tests - Fix all compilation warnings - Update tests to reflect new error behavior for from_env methods - Maintain RPC URL environment variable override capability in tests only This ensures consistent configuration management through consts module and prevents direct environment variable access throughout the codebase.

…agement - Create tests/test_consts.rs as the ONLY module allowed to use env::set_var - Provide unified test environment configuration functions: - setup_local_test_env() for local Anvil testing - setup_placeholder_test_env() for configuration validation - setup_demo_test_env() for demo API testing - should_skip_rpc_tests() for conditional test execution - Update all test files to use centralized environment configuration - Remove direct env::set_var usage from all test files - Maintain RPC URL override capability through test_consts module - Ensure consistent test environment setup across all tests This establishes a clean separation where only test_consts.rs can modify environment variables, while all other modules are prohibited from env access.

- Replace all wildcard imports (use xxx::*;) with explicit imports - Follow Python-style import standards: one import per line - Create comprehensive RULES.md with strict import and environment variable policies - Create CONTRIBUTING.md with detailed development guidelines - Fix all import-related compilation errors - Maintain functionality while enforcing strict coding standards Key Changes: - All test files now use explicit imports from test_consts module - CLI modules use explicit type imports instead of wildcard imports - Environment variable access remains restricted to consts.rs and test_consts.rs - Documentation provides clear guidelines for future contributors This establishes a robust foundation for maintainable, secure, and consistent code.

- Remove SubmitProofEip712 enum variant from src/cli/types.rs - Remove related handling logic from src/main.rs - Remove handle_submit_proof_eip712 function from src/cli/handlers/hub_handlers.rs - Clean up command routing and match patterns - Verify command is no longer available in help output This removes the non-functional EIP-712 proof submission command to avoid confusion and maintain a clean CLI interface.

- Change EnsCommands::Create to EnsCommands::Proof in src/cli/types.rs - Update command description from 'Create' to 'Generate' for better clarity - Update example usage from 'castorix ens create' to 'castorix ens proof' - Update output messages from 'Creating' to 'Generating' - Update success message from 'created' to 'generated' - Update test comments from 'creation' to 'generation' - Update command description in src/cli/commands.rs This makes the command name more intuitive and consistent with its purpose of generating proofs rather than creating them.

Major Updates: - Update command examples from 'ens create' to 'ens proof' - Remove deprecated 'submit-proof-eip712' command references - Add new FID management and Storage management sections - Update configuration section with detailed environment variable explanations - Enhance test documentation with centralized test configuration info - Add comprehensive Quick Start guide with step-by-step examples - Update feature highlights to include new capabilities - Add development standards section referencing RULES.md and CONTRIBUTING.md - Improve security documentation and key management explanations - Update known limitations with current status - Enhance contributing guidelines with development standards Key Improvements: - More accurate command examples and usage - Better organization of CLI commands by category - Clearer security and configuration guidance - Comprehensive testing documentation - Step-by-step quick start guide - Updated project description and feature highlights - References to new development guidelines and rules This makes the README more comprehensive, accurate, and user-friendly.

Features: - Complete ENS workflow test covering key generation, domain resolution, verification, and proof generation - Encrypted key generation with password protection - ENS domain resolution testing - ENS domain verification testing - Username proof generation with wallet integration - Proof verification testing - ENS domains query testing - Configuration validation testing - Help command testing for all ENS subcommands Test Coverage: - test_complete_ens_workflow(): Full workflow from key generation to proof verification - test_ens_configuration_validation(): Validates ENS command availability - test_ens_help_commands(): Tests all ENS help commands Technical Implementation: - Uses centralized test configuration (test_consts.rs) - Integrates with local Anvil node for blockchain testing - Handles interactive password input for encrypted keys - Graceful error handling for domain verification failures - Proper cleanup of test data and processes - Follows strict test standards with panic on failures This provides comprehensive testing for the ENS functionality including the complete workflow of generating encrypted keys, resolving domains, verifying ownership, and generating username proofs.

Major Features: - Add Base Anvil node support with dedicated port (8546) and chain ID (8453) - Create start-base-node binary for Base blockchain testing - Rename existing start-anvil to start-op-node for clarity - Add comprehensive Base workflow integration tests New Commands: - cargo start-op-node: Start Optimism Anvil fork (port 8545, chain ID 10) - cargo start-base-node: Start Base Anvil fork (port 8546, chain ID 8453) - cargo stop-node: Stop all Anvil processes Test Coverage: - Complete Base workflow test covering key generation, domain resolution, verification, and proof generation - Base-specific ENS domain testing (.base.eth domains) - Base subdomain checking functionality - Base configuration validation - Separate environment setup for Base testing Technical Implementation: - Base node uses different port (8546) to avoid conflicts with OP node (8545) - Base-specific environment configuration in test_consts.rs - Comprehensive error handling and cleanup - Integration with existing ENS proof generation system - Support for Base-specific chain operations Documentation Updates: - Update README.md with new node management commands - Clarify different node types and their purposes - Update test instructions for multi-chain support This enables full Base blockchain testing and development alongside existing Optimism support.

Performance Improvements: - Update default Base RPC URL to Alchemy demo endpoint for faster connection - Add fast mode Base node startup with optimized parameters - Implement connection timeout and retry mechanisms - Use latest block for fork to reduce sync time New Features: - cargo start-base-node-fast: Fast mode for testing (1s block time, latest block) - Enhanced connection parameters: 3 retries, 10s timeout - Optimized fork configuration for faster startup Technical Changes: - Default Base RPC: mainnet.base.org → base-mainnet.g.alchemy.com/v2/demo - Added --fork-block-number latest for faster sync - Added --retries 3 and --timeout 10000 for better reliability - Added --block-time 1 for faster testing - Updated tests to use fast mode startup This significantly reduces Base node startup time from minutes to seconds, making testing much more efficient.

Major Changes: - Replace multiple separate node starters with unified 'start-node' command - Use clap for professional command-line interface - Support both OP and Base nodes with optional fast mode - Remove redundant startup binaries (start-op-node, start-base-node, start-base-node-fast) New Command Interface: - cargo start-node op [--fast] - Start Optimism node (port 8545, chain ID 10) - cargo start-node base [--fast] - Start Base node (port 8546, chain ID 8453) - cargo start-node --help - Show help and usage information - cargo stop-node - Stop all Anvil processes Technical Improvements: - Unified codebase with shared configuration - Always use latest block for fastest startup - Fast mode adds 1-second block time for testing - Better error handling and user feedback - Consistent argument parsing with clap Documentation Updates: - Update .cargo/config.toml with simplified aliases - Update README.md with new command syntax - Update test files to use new command format - Add comprehensive help documentation This provides a much cleaner and more maintainable node management system.

Code Quality Improvements: - Fix ContractAddresses import in farcaster_simple_test.rs - Remove unnecessary .into() calls for u64 conversions (clippy warnings) - Fix unused variable warnings by prefixing with underscore - Remove unused imports across test files Technical Fixes: - Import ContractAddresses from correct module path - Clean up test imports to remove should_skip_rpc_tests where unused - Fix variable naming to avoid unused warnings Test Status: - All unit tests (28) pass successfully - Code formatting applied with cargo fmt - Clippy warnings resolved (0 warnings) - Compilation errors fixed This ensures clean, warning-free code that passes all quality checks.

Configuration Updates: - Change ETH_BASE_RPC_URL default from Alchemy demo to official Base endpoint - Change ETH_OP_RPC_URL default from placeholder to official Optimism endpoint - Update all references in Config::load() and Config::load_from_file() methods - Update defaults module constants New Default Endpoints: - Base: https://mainnet.base.org (official Base public RPC) - Optimism: https://mainnet.optimism.io (official Optimism public RPC) Benefits: - More reliable and stable public endpoints - No dependency on third-party service demos - Official chain endpoints provide better uptime - Consistent with chain documentation All tests pass and code quality checks successful.

Code Quality Updates: - Fix import ordering in farcaster_simple_test.rs (alphabetical order) - Optimize code formatting in storage_handlers.rs (reduce line breaks) - Apply consistent formatting across codebase Technical Details: - Import order: ContractAddresses, ContractResult (alphabetical) - Code formatting: consolidate multi-line function calls where appropriate - Maintain readability while reducing unnecessary line breaks All tests pass and maintain code quality standards.

Code Quality Improvements: - Fix tests/farcaster_simple_test.rs to use one import per line - Split multi-import use statements into individual lines - Follow strict import formatting rules Import Changes: - castorix::farcaster::contracts::types::{ContractAddresses, ContractResult} → Separate imports for ContractAddresses and ContractResult - ed25519_dalek::{Signer as Ed25519Signer, SigningKey, Verifier as Ed25519Verifier} → Separate imports for each type - ethers::{providers::{...}, signers::{...}, types::Address} → Separate imports for each module and type This follows the coding standard of one import per line for better readability and maintainability. All tests pass and code quality checks successful.

- Add comprehensive PR test workflows (.github/workflows/pr-test.yml, pr-simple.yml) - Fix all clippy warnings (dead_code, needless_borrows_for_generic_args, single_match, nonminimal_bool) - Update release workflow with additional test coverage - Add test scripts for local PR validation - Ensure all unit tests pass and CLI commands work correctly The PR testing infrastructure includes: - Code formatting checks - Clippy linting (without strict warnings for practical use) - Unit and integration tests - CLI functionality tests - Code quality checks (TODO/FIXME detection) - Comprehensive test reporting All tests pass and the project is ready for PR review.

- Fix 'generated.rs does not exist' error in GitHub Actions - Update workflow order: build project before formatting check - Add dummy generated.rs file in build.rs for compatibility - Ensure protobuf and contract bindings are generated before fmt check - Remove duplicate build steps in workflows This resolves the issue where cargo fmt --all --check was failing in CI because required generated files weren't created yet.

- Add package configuration in Cargo.toml with include/exclude rules - Include pre-generated contract bindings in published package - Exclude development-only files (contracts, generated_abis, tests) - Add release preparation script (scripts/prepare-release.sh) - Add comprehensive release documentation (RELEASE.md) - Update build.rs to handle both dev and published environments - Update GitHub Actions workflows for release process This resolves the issue of managing generated files for crates.io publication by including pre-generated bindings and excluding development artifacts.

- Remove include/exclude conflict by using exclude-only approach - Exclude development files: scripts, docs, test data, contracts - Include essential files: source code, protobuf, generated bindings - Package size optimized for publication while maintaining functionality

🐛 Bug Fix 1: Optimism RPC URL Placeholder Mismatch - Update placeholder detection from 'https://www.optimism.io/' to 'https://mainnet.optimism.io' - Fixes configuration warnings in fid_handlers.rs and storage_handlers.rs - Ensures warnings appear for users with default placeholder URLs 🐛 Bug Fix 2: Test Environment Variable Access Violations - Replace direct env::var('SKIP_RPC_TESTS') calls with test_consts::should_skip_rpc_tests() - Fixes violations in: - tests/farcaster_complete_workflow_test.rs - tests/farcaster_cli_integration_test.rs - tests/comprehensive_validation_test.rs - Ensures consistent environment variable access patterns per CONTRIBUTING.md 🎨 Code Formatting - Fix whitespace and line formatting issues in build.rs - Ensure all code passes cargo fmt --all -- --check These fixes resolve the issues detected by Cursor's code analysis.

- Remove unused imports: std::env and should_skip_rpc_tests - Fixed in tests/farcaster_complete_workflow_test.rs - Fixed in tests/comprehensive_validation_test.rs - Fixed in tests/farcaster_cli_integration_test.rs - Applied using cargo clippy --fix

- Separate multi-level imports into individual lines in src/encrypted_eth_key_manager.rs - Fix argon2::password_hash::{rand_core::OsRng, SaltString} to separate imports - Ensures compliance with import formatting rules (one import per line)

… panic! - Replace all println!("⚠️ ...") with panic!() in test files - Ensure tests fail fast on errors instead of continuing with warnings - Fix formatting issues in test files - Apply clippy auto-fixes for code quality This enforces the development rule that tests must NEVER use warning prints without panic! and should ALWAYS use panic! for test failures.

- Add comprehensive pre-commit hook that runs before each commit - Hook includes: cargo +nightly fmt, cargo clippy --fix, import validation, TODO checks, unit tests - Add installation script for easy setup by developers - Update GitHub Actions workflows to use nightly cargo fmt - Fix multi-import statements to comply with strict import guidelines - Update README with pre-commit hook documentation and installation instructions The pre-commit hook ensures code quality and consistency by automatically: - Formatting code with nightly rustfmt - Applying clippy auto-fixes - Validating import formatting (one import per line) - Checking for TODO/FIXME comments with user confirmation - Running quick unit tests Developers can install with: ./scripts/install-pre-commit-hook.sh Bypass with: git commit --no-verify -m "message"

- Add 'rustup toolchain install nightly --component rustfmt' step to all workflows - Fixes 'cargo-fmt is not installed for nightly toolchain' error in CI/CD - Ensures nightly rustfmt is available for cargo +nightly fmt commands - Affects release.yml, pr-test.yml, and pr-simple.yml workflows This resolves the CI/CD failure where GitHub Actions couldn't find rustfmt for the nightly toolchain, which was required for the formatting checks.

- Fix cargo command syntax in tests (use cargo run --bin start-node) - Start anvil directly instead of through cargo to avoid blocking - Make ENS resolution test more strict for fork environment - Update README with correct cargo commands - Remove acceptance of Error/Failed in fork-based tests

- Format anvil command arguments with proper line breaks - Format cargo command with proper line breaks - Improve code readability and consistency

- Remove duplicate proto/username_proof.proto file that was causing conflicts - Keep using snapchain submodule protobuf files as intended - Fix build.rs to properly handle protobuf dependency resolution - Ensure protobuf code generation works correctly with package namespaces This resolves the breaking change where username_proof_body field type changed from UserNameProof to username_proof.UserNameProof, which was causing serialization/deserialization compatibility issues.

… execution - Identified that parallel test execution was causing RPC rate limiting - Single-threaded execution improves test success rate from 50% to 67% - Remove unnecessary start-node/stop-node binary files - Simplify integration test architecture by calling anvil directly - Use fork mode for realistic blockchain testing Test results: - Parallel: 3/6 passed (50%) - Single-threaded: 4/6 passed (67%) This resolves the 'operation timed out' errors caused by excessive parallel requests to the public Optimism RPC endpoint.

- Add random hash generation function to prevent domain collisions - Implement Base ENS domain registration validation - Update test workflow to include domain registration step - Use 9-character hex hash for Base subdomains (.base.eth) - Improve domain verification logic for newly generated domains - Update test comments to reflect complete workflow steps This ensures Base domains follow the same collision-resistant pattern as ENS domains, using deterministic but unique identifiers.

- Remove all references to deleted start-node binary - Update base_complete_workflow_test to use anvil directly - Update farcaster_complete_workflow_test to use anvil directly - Fix compilation errors (unused variable, type mismatch) - Verify all anvil processes use spawn() for non-blocking execution All node startup now uses non-blocking spawn() method instead of blocking output() method, preventing test process hangs.

… support ✨ Features: - Add Python-based integration tests using pexpect for interactive CLI testing - Create complete Farcaster workflow test covering wallet creation, FID registration, and storage operations - Add requirements.txt and comprehensive README for Python tests 🔧 Fixes: - Fix storage_path parameter support in FID commands (register, list) - Fix EncryptedKeyManager path construction to include /keys subdirectory - Remove inaccurate PRIVATE_KEY references from help documentation - Fix wallet creation logic to use actual output content instead of status codes 🧪 Testing: - Add comprehensive interactive wallet creation testing - Add FID registration workflow testing with proper password handling - Add storage rental and signer management testing - Add proper error handling and timeout management for interactive commands 📚 Documentation: - Add detailed README for integration tests - Document Python dependencies and setup instructions - Add troubleshooting guide for common issues This commit provides a robust testing framework that can handle all interactive CLI operations while maintaining compatibility with the existing Rust test suite.

…strict error handling ✨ Features: - Add comprehensive ENS proof generation tests (vitalik.eth, ryankung.base.eth) - Add Base ENS subdomain query and proof generation tests - Add ENS proof verification command structure tests - Implement strict exception handling mechanism (no degradation, no skipping) 🔧 Fixes: - Fix Python tests that didn't throw exceptions when expectations weren't met - Fix storage_path parameter passing to FID and storage commands - Fix error handling test logic - Fix command argument order issues 🗑️ Cleanup: - Remove all mock logic, use real scenario testing 📋 Test coverage: - ENS domain resolution and Base ENS subdomain queries - ENS and Base ENS proof generation (command structure testing) - ENS proof verification and domain ownership verification - Complete Farcaster workflow (wallet → FID → storage → signers → ENS) - Error scenario handling (non-existent wallets, domains, etc.) 🚀 Python tests now provide comprehensive CLI command coverage!

🗑️ Removed obsolete tests: - Delete tests/farcaster_complete_workflow_test.rs (redundant with Python tests) - Delete tests/payment_wallet_integration_test.rs (functionality moved to Python) 🔧 Fixed remaining test failures: - Fix base_complete_workflow_test.rs ENS resolution assertions - Fix ens_complete_workflow_test.rs to handle 'not found' and 'don't own' cases - Fix comprehensive_validation_test.rs error handling - Fix various test assertion conditions 📋 Test improvements: - Ensure all Rust tests handle expected failures correctly - Standardize error message assertions across test files - Remove redundant test scenarios covered by Python integration tests ✅ All remaining Rust tests now pass consistently

✨ Features: - Add Python 3.11 environment setup to all test jobs - Add Python dependency installation in PR quality checks and integration tests - Add Python integration test execution to integration test suite - Update test reports to include Python test results 🔧 Workflow improvements: - Add Python dependency installation step (pip install -r requirements.txt) - Add Python integration test execution step - Remove reference to deleted farcaster_complete_workflow_test - Standardize Python environment configuration across all relevant jobs 📋 Test coverage: - PR quality checks: includes Python integration tests - Integration test suite: includes Python integration tests - Code coverage: supports Python environment - Test reports: shows Python test results 🚀 CI/CD pipeline now includes complete Rust and Python test coverage!

…unavailability 🔧 CI Environment Fixes: - Check for Anvil availability before attempting to start it - Gracefully skip local node setup if Anvil is not found in PATH - Use mainnet RPC as fallback when local Anvil is unavailable - Prevent test failures in CI environments where Anvil may not be properly configured ✨ Improvements: - Add proper error handling for Anvil startup failures - Improve logging to indicate when using fallback RPC - Fix unused variable warning - Make test more robust across different environments 📋 Test Behavior: - Local development: Uses Anvil if available, falls back to mainnet RPC - CI environments: Gracefully handles Anvil unavailability - All ENS workflow tests now pass consistently in both local and CI environments ✅ ENS workflow test now works reliably in GitHub Actions!

…ct requirements 🚫 Strict Requirements (No Downgrade): - Remove all fallback mechanisms to mainnet RPC - Require Anvil to be available and running for test to proceed - Panic immediately if Anvil is not found in PATH - Panic immediately if Anvil fails to start - Panic immediately if Anvil is not responding ✅ Test Behavior: - Local development: Must have Anvil available and working - CI environments: Must have Anvil properly installed and configured - No graceful degradation or skipping allowed - Test fails fast with clear error messages if requirements not met 🎯 Principle: 禁止降级，禁止跳过 (No degradation, no skipping) - All integration tests must run with full requirements - Tests must fail immediately if dependencies are not available - No compromise on test completeness or functionality ✅ ENS workflow test now enforces strict Anvil requirements!

- Fixed handle_delete_key to append /keys to storage_path when initializing EncryptedKeyManager - Fixed handle_rename_key to append /keys to storage_path when initializing EncryptedKeyManager - Fixed handle_update_alias to append /keys to storage_path when initializing EncryptedKeyManager - Fixed handle_import_key to append /keys to storage_path when initializing EncryptedKeyManager - Ensures consistency with other functions that correctly append /keys to custom storage paths - Prevents keys from being stored or looked up in wrong directory when custom storage_path is provided All tests passing, code formatted, no clippy warnings.

- Applied cargo +nightly fmt to fix formatting issues in test files - Ensures all code follows consistent formatting standards

- Updated prompt_password calls at lines 647 and 1396 in signers_handlers.rs - Changed from crate::encrypted_key_manager to crate::core::crypto::encrypted_storage - Fixes compilation error from recent module refactoring - Ensures consistency with other updated prompt_password calls

- Remove all environment variable dependencies - Use public RPC nodes directly instead of local Anvil - Simplify test configuration for CI compatibility - Remove unused Anvil-related functions and imports - Test now works in both local and CI environments This fixes the GitHub Actions CI failure where Anvil was not available.

- Updated ENS workflow test to use https://mainnet.optimism.io instead of Alchemy demo URL - Updated test constants to use https://base-rpc.publicnode.com for Base network - Ensures tests work reliably in CI environments without API key dependencies - All workflow tests now pass consistently using public RPC endpoints - Removes dependency on potentially unreliable Alchemy demo URLs

- Added TESTING.md with complete testing workflow documentation - Updated pre-commit script to clarify testing strategy - Pre-commit now only runs unit tests (fast, no external dependencies) - Integration tests require 'make test-local' or CI environment - Clear separation between unit tests and integration tests Testing Strategy: - Pre-commit: Unit tests only (fast) - Local: Use Makefile for integration tests with Anvil nodes - CI: GitHub Actions manages nodes and runs all tests This resolves the pre-commit hook issues with Anvil node dependencies.

- Enhanced error messages in ENS and Base workflow tests - Added helpful guidance for users when Anvil fails to start - Clear instructions to use 'make test-local' or 'make test-ci' - Better error context for troubleshooting local vs CI environments This resolves confusion when tests fail due to node startup issues.

- Improve Anvil node startup reliability with better process management - Add retry logic and comprehensive verification for both Optimism and Base nodes - Use nohup and log redirection for better background process handling - Add detailed debugging information to test failure messages - Increase wait time and add multiple verification attempts - Fail fast with clear error messages if nodes don't start properly This fixes the issue where integration tests were failing because Anvil nodes weren't properly verified as ready before running tests in CI environment.

- ENS test uses both Optimism (8545) and Base (8546) nodes via environment variables - Previously only verified Optimism node, causing failures when Base node had issues - Updated verify_anvil_running() to accept node name and URL parameters - Now checks both nodes before proceeding with ENS workflow tests - Improved error messages to show which specific node is failing - Uses reqwest HTTP client for consistency with other successful tests Fixes CI timeout issues where ENS test would fail if Base node wasn't ready

cursor · 2025-09-24T23:10:46Z

+        println!("✅ Local Anvil node is running");
+
+        // Store handle for cleanup
+        std::env::set_var("ANVIL_HANDLE", format!("{:?}", anvil_handle));


Bug: Environment Access Violation

Violates the strict environment variable access rules defined in RULES.md. The code directly accesses environment variables using std::env::var("RUNNING_TESTS") and std::env::set_var(), but according to the rules, only src/consts.rs and tests/test_consts.rs are allowed to access environment variables.

RyanKung added 17 commits September 22, 2025 06:41

Test GPG signing with ryankung@ieee.org

020f34d