[Evangel90]

Description

Closes #44

This PR implements the Sui Move Escrow System using Move 2024 Edition. It includes modular smart contracts for asset locking, custodied single-owner swaps, and trustless peer-to-peer shared object swaps, along with a 13-scenario unit test suite, automated CI/CD, gas benchmarking tooling, and complete localnet deployment documentation.

Key Changes

1. Move 2024 Smart Contracts (contract/sources/)

• lock.move: Low-level asset locking container (Locked<T>) and single-use Key primitive using Dynamic Object Fields (DOF).
• owned.move: Single-owner / custodied escrow pattern managed by a trusted third-party custodian with reciprocity validation.
• shared.move: Peer-to-peer trustless escrow pattern built on Sui shared objects with storage gas rebate reclamation via id.delete().

2. Unit Test Suite (contract/tests/)

• Decoupled test modules (lock_tests.move, owned_tests.move, shared_tests.move).
• 13/13 passing tests covering successful swaps, unlock mechanics, sender/recipient mismatch reverts, object tampering assertions, and cancellation flows.

3. Architecture & Package Structure

• Flattened Move package structure directly into Sui/Move/smart-contracts/escrow/contract/.
• Added [environments] local chain ID configuration in Move.toml and tracked Published.toml.

4. CI/CD Pipeline (.github/workflows/sui-ci.yml)

• Automated GitHub Actions workflow using precompiled Sui release binary.
• Executes compilation, strict Move linter checks (--lint --warnings-are-errors), test execution, code coverage reporting, and GitHub Step Summaries for gas statistics.

5. Performance Benchmarking (performance/)

• Created executable performance/benchmark.sh for single-command gas profile generation.
• Recorded full test execution gas statistics and 3-option verification instructions in performance/README.md.

6. Documentation & Localnet Deployment (contract/README.md)

• Added Mermaid flowcharts and sequence diagrams for all 3 escrow modules.
• Included annotated Move code walkthroughs and a step-by-step 5-stage Localnet setup, funding, publishing, and CLI interaction guide.

---

Verification & Testing

1. Unit Tests & Linter

cd Sui/Move/smart-contracts/escrow/contract
sui move build --lint --warnings-are-errors
sui move test

• Result: Test result: OK. Total tests: 13; passed: 13; failed: 0

2. Code Coverage

sui move test --coverage
sui move coverage summary

3. Gas Profile & Benchmarks

./Sui/Move/smart-contracts/escrow/performance/benchmark.sh

4. Localnet Deployment

sui client switch --env local
sui client faucet
sui client publish

• Deployed Package ID: 0xf155a09874b07527d5bd7e8f919f26e09c9e4a324166425c9c4b4c0221e79f4e
• UpgradeCap ID: 0xb5e86fdba15a266be9a659635ace8af7ac1e698e7087389b6f9f6777ae4f5c4c

---

Checklist

• Smart contracts compiled with zero warnings (--lint --warnings-are-errors)
• Unit test suite passed (13/13)
• Code coverage verified
• CI pipeline configured and passing on GitHub
• Benchmarks recorded in performance/README.md
• Localnet deployment tested and Published.toml tracked
• Documentation updated with sequence diagrams and localnet setup guide