feat: consensus release smart contracts and tests

[FrankiePower]

Pull Request: Implement Consensus Release Smart Contract and Tests

---

🧠 Summary:

This PR implements a comprehensive Consensus Release Contract on Soroban that enables secure escrow transactions with multi-party consensus mechanisms. The contract ensures funds are only released when all required parties agree, providing a transparent and secure solution for marketplace transactions that require mutual confirmation between buyers, sellers, and optional arbitrators.

---

📌 Type of Change

• Documentation (updates to README, docs, or comments)
• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

---

Context:

This PR introduces the Consensus Release Contract, a Stellar smart contract built with Soroban SDK to handle escrow scenarios where funds are only released after consensus is reached between multiple parties (buyer, seller, and optionally an arbitrator). The contract supports four different consensus rules, secure fund management, automatic expiration handling, and comprehensive event logging for full transparency.

The contract is modular, comprising:

• lib.rs: Main contract interface with public functions for transaction lifecycle management
• contract.rs: Core business logic for transaction creation, funding, agreements, and fund release
• types.rs: Comprehensive data structures including transaction states and consensus rules
• storage.rs: Persistent data management for transactions and user mappings
• utils.rs: Helper functions for consensus validation and transaction utilities
• events.rs: Event definitions for complete transaction transparency
• error.rs: Robust error handling with 23 specific error types
• test.rs: Comprehensive test suite with 19 test cases covering all scenarios

---

Assumptions

Token Handling:

• Supports any Soroban-compatible token using token::Client, with token address specified per transaction
• Tokens must be approved for transfer by the buyer before funding the escrow
• Contract holds funds securely until consensus is reached or expiration occurs

Consensus Mechanisms:

• Four consensus rules supported: Unanimous, Majority, BuyerSellerOnly, and WithArbitrator
• Each rule has specific validation logic to determine when consensus is achieved
• Any party rejection immediately triggers refund to buyer

Time Management:

• Deadline-based expiration system prevents indefinite fund locking
• Expired transactions automatically refund buyers if funds were deposited
• Current Stellar ledger timestamp used for all time validations

Security Model:

• All functions require proper authentication via require_auth
• Only authorized parties can submit agreements or release funds
• Admin controls for contract initialization and management

---

📝 Changes description

1. Contract Initialization:

   • initialize function sets admin address with single initialization enforcement
   • Transaction counter initialization for unique ID generation

2. Transaction Creation:

   • create_transaction allows buyers to set up escrow with flexible consensus rules
   • Comprehensive validation for amounts, deadlines, and party uniqueness
   • Support for optional arbitrator based on consensus rule selection

3. Secure Escrow Management:

   • fund_transaction securely locks buyer funds in contract until consensus
   • Prevention of unauthorized access or premature fund release
   • Automatic status tracking through transaction lifecycle

4. Multi-Party Consensus System:

   • submit_agreement enables all parties to vote on fund release
   • Four consensus rules: Unanimous (all agree), Majority (>50%), BuyerSellerOnly (ignores arbitrator), WithArbitrator (requires all three)
   • Immediate rejection handling with automatic refunds

5. Fund Release Mechanism:

   • release_funds transfers tokens to seller once consensus is achieved
   • Double validation of consensus state before transfer
   • One-time release enforcement to prevent double spending

6. Expiration Handling:

   • handle_expiration manages expired transactions with automatic refunds
   • Time-based fallback logic when consensus is not reached within deadline
   • Proper state transitions and event emissions for expired transactions

7. Comprehensive Event System:

   • 9 detailed event types covering every transaction action
   • Events include transaction creation, funding, agreements, consensus, releases, and expirations
   • Full audit trail for transparency and off-chain tracking

8. Query Functions:

   • get_transaction provides complete transaction details
   • get_user_transactions lists all transactions for a specific user
   • Admin management functions for contract oversight

---

Design Considerations

The contract design addresses key challenges in multi-party escrow systems:

1. Flexible Consensus Rules:

   • Challenge: Different transaction types require different agreement mechanisms
   • Solution: Four distinct consensus rules to handle various business scenarios
   • Why: Supports simple buyer-seller agreements, arbitrated disputes, democratic majority decisions, and complete unanimity requirements

2. Security and Authorization:

   • Challenge: Prevent unauthorized fund access and ensure only valid parties can participate
   • Solution: Comprehensive authentication checks, party validation, and status-based access controls
   • Why: Protects all participants and ensures funds are only released under proper conditions

3. Time-Based Safety:

   • Challenge: Prevent indefinite fund locking in case of non-responsive parties
   • Solution: Mandatory deadlines with automatic expiration handling and refunds
   • Why: Ensures buyers can recover funds in consensus cannot be reached within reasonable timeframes

4. Transparency and Auditability:

   • Challenge: Provide complete transaction visibility for all stakeholders
   • Solution: Comprehensive event logging andpersistent storage of all transaction data
   • Why: Enables off-chain tracking, dispute resolution, and regulatory compliance

5. State Management:

   • Challenge: Ensure proper transaction state transitions and prevent invalid operations
   • Solution: Clear status enumeration with validation at each transition point
   • Why: Prevents double-spending, invalid operations, and maintains transaction integrity

6. Error Handling:

   • Challenge: Provide clear feedback for various failure scenarios
   • Solution: 23 specific error types covering all possible failure conditions
   • Why: Enables proper error handling in client applications and clear user feedback

---

Acceptance Criteria

✅ Multi-Party Consensus:

• Supports Unanimous, Majority, BuyerSellerOnly, and WithArbitrator consensus rules
• Proper validation for each consensus type with immediate rejection handling

✅ Secure Escrow Management:

• Funds safely stored until consensus with proper authorization checks
• Prevention of unauthorized or premature fund release

✅ Dispute Handling:

• Any party rejection triggers immediate refund to buyer
• Arbitrator support for complex dispute resolution scenarios

✅ Event Logging:

• 9 comprehensive event types covering all transaction actions
• Complete audit trail with timestamps and party information

✅ Thorough Testing:

• 19 test cases covering happy paths, rejections, expirations, and edge cases
• 100% test pass rate with comprehensive coverage validation

✅ Fallback Logic:

• Time-based expiration with automatic buyer refunds
• Proper handling of non-responsive parties

✅ Fund Release:

• Secure one-time fund transfer to seller after consensus validation
• Double-checking of consensus state before release

---

📸 Evidence

[FrankiePower]

@salazarsebas This PR is ready to be review and merged

[salazarsebas]

LGTM