feat: cleanup onchain legacy AidEscrow documentation and tests

.kiro/specs/onchain-legacy-cleanup/.config.kiro

@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}

.kiro/specs/onchain-legacy-cleanup/design.md

@@ -0,0 +1,214 @@
+# Design Document: OnChain Legacy Cleanup
+
+## Overview
+
+This feature addresses documentation and test inconsistencies in the AidEscrow contract by updating README.md, CONTRIBUTING.md, and core_flow.rs to accurately reflect the current implementation. The cleanup ensures developers have complete, accurate information about all available methods and that tests comprehensively validate contract functionality.
+
+The approach is primarily documentation-focused with test expansion. We will:
+1. Parse the current contract implementation to extract all public methods and their signatures
+2. Update README.md to include complete method documentation
+3. Update CONTRIBUTING.md examples to match current signatures
+4. Expand core_flow.rs to test all methods including newer additions
+5. Validate consistency between documentation and implementation
+
+## Architecture
+
+This is a documentation and test maintenance feature with no runtime architecture changes. The work involves:
+
+### Documentation Layer
+- **README.md**: Primary user-facing documentation with method reference table
+- **CONTRIBUTING.md**: Developer guidelines with code examples
+
+### Test Layer
+- **core_flow.rs**: Integration tests validating contract behavior
+
+### Validation Layer
+- Scripts or manual checks to verify documentation-implementation alignment
+
+## Components and Interfaces
+
+### Component 1: README Method Reference Updater
+
+**Purpose**: Ensure README.md documents all public methods from the current implementation.
+
+**Inputs**:
+- Current README.md content
+- List of public methods from lib.rs (extracted via parsing or manual review)
+
+**Outputs**:
+- Updated README.md with complete method reference table
+
+**Behavior**:
+- Parse lib.rs to identify all public methods in the AidEscrow impl block
+- Extract method signatures, parameters, and return types
+- Compare against existing method reference table
+- Add missing methods with descriptions and auth requirements
+- Ensure consistent formatting across all entries
+
+### Component 2: CONTRIBUTING Example Updater
+
+**Purpose**: Update code examples in CONTRIBUTING.md to match current method signatures.
+
+**Inputs**:
+- Current CONTRIBUTING.md content
+- Current method signatures from lib.rs
+
+**Outputs**:
+- Updated CONTRIBUTING.md with accurate examples
+
+**Behavior**:
+- Identify code examples in CONTRIBUTING.md (within code blocks)
+- Extract method signatures from examples
+- Compare against current implementation signatures
+- Update parameter lists, types, and return types
+- Update error type references to match current Error enum
+
+### Component 3: Test Suite Expander
+
+**Purpose**: Add tests for methods not currently covered in core_flow.rs.
+
+**Inputs**:
+- Current core_flow.rs test file
+- List of methods requiring test coverage
+
+**Outputs**:
+- Expanded core_flow.rs with comprehensive test coverage
+
+**Behavior**:
+- Identify untested methods: batch_create_packages, extend_expiration, get_aggregates, set_config, get_config
+- Write integration tests for each method covering:
+  - Success path with valid inputs
+  - Error conditions (using try_ variants)
+  - State transitions and side effects
+- Maintain existing tests for legacy API methods
+- Follow existing test patterns and naming conventions
+
+## Data Models
+
+### Method Metadata Structure
+
+For documentation generation, we conceptually work with:
+
+```
+MethodMetadata {
+  name: String,
+  parameters: Vec<Parameter>,
+  return_type: String,
+  auth_required: Option<String>,
+  description: String,
+  errors: Vec<String>
+}
+
+Parameter {
+  name: String,
+  type: String
+}
+```
+
+### Test Coverage Matrix
+
+Track which methods have test coverage:
+
+```
+TestCoverage {
+  method_name: String,
+  has_success_test: bool,
+  has_error_test: bool,
+  test_function_names: Vec<String>
+}
+```
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Documentation Completeness
+
+*For any* public method in the AidEscrow implementation, the README method reference table should contain an entry documenting that method.
+
+**Validates: Requirements 1.1, 5.1**
+
+### Property 2: Example Signature Accuracy
+
+*For any* code example in CONTRIBUTING.md that shows a method signature, the signature should match the current implementation in lib.rs.
+
+**Validates: Requirements 3.1, 5.2**
+
+### Property 3: Error Type Validity
+
+*For any* error type referenced in documentation examples or test assertions, that error type should exist in the current Error enum definition.
+
+**Validates: Requirements 3.4, 7.3**
+
+### Property 4: Test Signature Accuracy
+
+*For any* method call in core_flow.rs tests, the method signature (name, parameters, types) should match the current implementation in lib.rs.
+
+**Validates: Requirements 7.1**
+
+### Property 5: Test Quality - Dual Path Coverage
+
+*For any* test function that validates a contract method, the test should include both a successful execution path and at least one error condition check (using try_ variant).
+
+**Validates: Requirements 4.6**
+
+### Property 6: Data Structure Documentation
+
+*For any* public data structure (struct or enum) used in the AidEscrow contract, the README should include a description of that structure.
+
+**Validates: Requirements 5.3**
+
+## Error Handling
+
+This feature primarily deals with documentation and tests, so error handling is minimal:
+
+### Documentation Updates
+- If a method cannot be parsed from lib.rs, log a warning and continue
+- If README structure is unexpected, fail with clear error message indicating format issue
+
+### Test Expansion
+- New tests should follow existing error handling patterns in core_flow.rs
+- Use try_ variants to test error conditions
+- Assert specific error types using assert_eq! with Error enum variants
+
+### Validation
+- If documentation-implementation mismatches are found, report them clearly
+- Provide specific line numbers and method names for any inconsistencies
+
+## Testing Strategy
+
+This feature involves updating tests and documentation, so testing is meta-level:
+
+### Manual Verification
+- Review updated README.md to ensure all methods are documented
+- Review updated CONTRIBUTING.md to ensure examples are accurate
+- Run expanded core_flow.rs tests to ensure they pass
+
+### Automated Validation (Optional)
+- Script to parse lib.rs and extract public method signatures
+- Script to parse README.md and verify all methods are documented
+- Script to parse CONTRIBUTING.md examples and compare to implementation
+- Script to parse core_flow.rs and verify test coverage
+
+### Unit Tests
+- No new unit tests required (this feature updates existing tests)
+- Existing unit tests in core_flow.rs should continue to pass
+- New tests added to core_flow.rs should follow existing patterns
+
+### Property-Based Tests
+- Property 1-6 could be validated with custom scripts that parse Rust code and markdown
+- These would be one-time validation scripts rather than ongoing PBT
+- Minimum 100 iterations not applicable (these are deterministic checks)
+
+### Integration Tests
+- The expanded core_flow.rs serves as integration tests
+- Each new test should:
+  - Set up contract state
+  - Call the method being tested
+  - Verify expected state changes
+  - Test error conditions
+
+### Test Configuration
+- Use existing Soroban test framework
+- Follow existing test patterns in core_flow.rs
+- Each test should be self-contained with its own setup

.kiro/specs/onchain-legacy-cleanup/requirements.md

@@ -0,0 +1,101 @@
+# Requirements Document
+
+## Introduction
+
+This feature addresses documentation and test inconsistencies in the onchain module's AidEscrow contract. The current implementation has evolved to include newer methods (batch_create_packages, cancel_package, extend_expiration, get_aggregates) that are not documented in README.md, and the test suite only covers the legacy API subset. Additionally, CONTRIBUTING.md contains example code with outdated method signatures. This cleanup ensures all documentation accurately reflects the current implementation and establishes a single coherent contract model.
+
+## Glossary
+
+- **AidEscrow**: The Soroban smart contract that manages aid package escrow using a pool-based model
+- **Pool_Model**: The architecture where the contract holds a global token balance and packages lock portions of that balance
+- **Package**: A locked allocation of funds from the pool designated for a specific recipient
+- **Legacy_API**: The original subset of methods (init, fund, create_package, claim, disburse, revoke, refund)
+- **Current_API**: The complete set of methods including newer additions (batch_create_packages, cancel_package, extend_expiration, get_aggregates)
+- **Method_Reference_Table**: The documentation table in README.md listing all available contract methods
+- **Core_Flow_Tests**: The test suite in app/onchain/contracts/aid_escrow/tests/core_flow.rs
+
+## Requirements
+
+### Requirement 1: Update README Method Reference
+
+**User Story:** As a developer integrating with AidEscrow, I want complete and accurate method documentation, so that I can discover and use all available contract functionality.
+
+#### Acceptance Criteria
+
+1. WHEN the Method_Reference_Table is viewed, THE Documentation SHALL include all methods from Current_API
+2. THE Method_Reference_Table SHALL include batch_create_packages with description and auth requirements
+3. THE Method_Reference_Table SHALL include cancel_package with description and auth requirements
+4. THE Method_Reference_Table SHALL include extend_expiration with description and auth requirements
+5. THE Method_Reference_Table SHALL include get_aggregates with description and auth requirements
+6. THE Method_Reference_Table SHALL include set_config with description and auth requirements
+7. THE Method_Reference_Table SHALL include get_admin with description and auth requirements
+8. THE Method_Reference_Table SHALL include get_package with description and auth requirements
+
+### Requirement 2: Align README with Pool Model
+
+**User Story:** As a developer reading the documentation, I want consistent terminology and model descriptions, so that I understand the contract architecture without confusion.
+
+#### Acceptance Criteria
+
+1. THE README SHALL describe the Pool_Model as the current and only architecture
+2. THE README SHALL NOT reference any deprecated or alternative models
+3. WHEN describing invariants, THE README SHALL use terminology consistent with Pool_Model
+4. WHEN describing methods, THE README SHALL explain their behavior in terms of Pool_Model
+
+### Requirement 3: Update CONTRIBUTING Examples
+
+**User Story:** As a contributor writing new contract code, I want accurate code examples, so that I follow current patterns and signatures.
+
+#### Acceptance Criteria
+
+1. WHEN the CONTRIBUTING documentation shows a method signature example, THE signature SHALL match the current implementation
+2. THE create_package example SHALL include all current parameters (id, recipient, amount, token, expires_at)
+3. THE documentation example SHALL use correct parameter types matching the implementation
+4. THE documentation example SHALL include accurate error types from the current Error enum
+
+### Requirement 4: Expand Test Coverage
+
+**User Story:** As a developer maintaining the contract, I want comprehensive test coverage, so that I can verify all functionality works correctly.
+
+#### Acceptance Criteria
+
+1. THE Core_Flow_Tests SHALL include tests for batch_create_packages
+2. THE Core_Flow_Tests SHALL include tests for cancel_package beyond the existing basic test
+3. THE Core_Flow_Tests SHALL include tests for extend_expiration
+4. THE Core_Flow_Tests SHALL include tests for get_aggregates
+5. THE Core_Flow_Tests SHALL include tests for set_config and get_config
+6. WHEN a new method is tested, THE test SHALL verify both success and error conditions
+7. THE Core_Flow_Tests SHALL maintain existing tests for Legacy_API methods
+
+### Requirement 5: Verify Documentation Completeness
+
+**User Story:** As a project maintainer, I want to ensure no documentation gaps exist, so that developers have complete information about the contract.
+
+#### Acceptance Criteria
+
+1. WHEN comparing README to implementation, THE README SHALL document every public method
+2. WHEN comparing CONTRIBUTING to implementation, THE CONTRIBUTING SHALL NOT contain outdated examples
+3. THE documentation SHALL include descriptions of all data structures (Package, Config, Aggregates, PackageStatus)
+4. THE documentation SHALL explain the relationship between fund, create_package, and the pool balance
+
+### Requirement 6: Remove Ambiguous Legacy References
+
+**User Story:** As a developer new to the codebase, I want clear documentation without confusing legacy references, so that I understand what is current versus deprecated.
+
+#### Acceptance Criteria
+
+1. THE README SHALL NOT use phrases like "legacy" or "deprecated" unless explicitly marking removed functionality
+2. WHEN describing the contract model, THE README SHALL present Pool_Model as the definitive approach
+3. THE documentation SHALL NOT suggest alternative architectures or models exist
+4. IF any methods are truly deprecated, THE documentation SHALL explicitly mark them as deprecated with migration guidance
+
+### Requirement 7: Ensure Test-Implementation Alignment
+
+**User Story:** As a developer running tests, I want tests that validate the actual implementation, so that I can trust test results reflect real contract behavior.
+
+#### Acceptance Criteria
+
+1. WHEN Core_Flow_Tests call contract methods, THE method signatures SHALL match the current implementation
+2. THE tests SHALL use current parameter names and types
+3. THE tests SHALL verify current error conditions defined in the Error enum
+4. THE tests SHALL NOT test removed or non-existent functionality