feat(models): add SwapPayment model and SwapStatus enum (#41)

[ALIPHATICHYD]

Summary

Closes #41

Implements the SwapPayment model and SwapStatus enum for Shade's cross-asset payment routing, as described in issue #41.

Changes

src/shade/models/swap.py (new)

• SwapStatus(str, Enum) — five lifecycle states: pending, swapping, completed, failed, slippage_exceeded
• SwapPayment — all required fields:
  • id: str, pay_in_token: str, settle_out_token: str
  • amount_in: Decimal, amount_out: Optional[Decimal]
  • routing_path: list[str]
  • slippage_tolerance: float — validated strictly in (0, 1); raises ValueError otherwise
  • status: SwapStatus, stellar_tx_hash: Optional[str], created_at: Optional[datetime]
• SwapPayment.from_dict(data) — deserialises all fields including the routing path list
• SwapPayment.to_dict() — serialises back to a plain dict (round-trip safe)

src/shade/models/__init__.py (new)

• Package init; re-exports SwapPayment and SwapStatus

src/shade/__init__.py (modified)

• Surfaces SwapPayment and SwapStatus in the top-level shade namespace

tests/test_swap_payment.py (new)

• 29 tests covering all acceptance criteria — 29 passed ✅

Acceptance Criteria

• SwapPayment.from_dict(...) populates all fields including routing path list
• slippage_tolerance outside (0, 1) raises ValueError
• status is a SwapStatus enum

Summary by CodeRabbit

• New Features

  • Added support for tracking cross-asset swap payments.
  • Introduced swap statuses for pending, in-progress, completed, failed, and slippage-exceeded transactions.
  • Added payment details including assets, amounts, routing, slippage tolerance, transaction hash, and creation time.
  • Added serialization and deserialization for storing and exchanging payment data.

• Bug Fixes

  • Added validation to reject invalid slippage tolerances and unknown payment statuses.

• Tests

  • Added comprehensive coverage for swap payment creation, validation, status handling, and data conversion.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 26a7b0f1-8ed5-4d1d-bcf4-f983a1d8537d

📥 Commits

Reviewing files that changed from the base of the PR and between c21ef8e and bb1dc3d.

📒 Files selected for processing (2)

• src/shade/models/swap.py
• tests/test_swap_payment.py

🚧 Files skipped from review as they are similar to previous changes (1)

• src/shade/models/swap.py

---

📝 Walkthrough

Walkthrough

Adds a SwapStatus lifecycle enum and SwapPayment model with validation, status coercion, dictionary serialization/deserialization, defensive list copying, equality, and representation behavior. Comprehensive tests cover construction, conversion, optional fields, timestamps, slippage boundaries, and invalid statuses.

Changes

SwapPayment model

Layer / File(s)	Summary
Model contract and construction src/shade/models/swap.py, tests/test_swap_payment.py	Defines swap lifecycle statuses and payment fields, validates slippage tolerance, coerces statuses, copies routing paths, and tests constructor behavior.
Dictionary conversion and model helpers src/shade/models/swap.py, tests/test_swap_payment.py	Implements from_dict, to_dict, equality, and representation behavior, with tests for parsing, serialization, optional values, timestamps, and invalid statuses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the main change: adding SwapPayment and SwapStatus.
Description check	✅ Passed	It includes a summary, issue reference, changes, and acceptance criteria, though template sections like testing and checklist are incomplete.
Linked Issues check	✅ Passed	The changes match issue #41: model, enum, required fields, routing path handling, slippage validation, and SwapStatus usage are all covered.
Out of Scope Changes check	✅ Passed	The extra exports and tests are supportive of the linked issue and do not appear unrelated to the requested model work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/shade/models/swap.py`:
- Around line 156-169: Update Swap.to_dict() so the "routing_path" serialized
value is a copy of self.routing_path rather than the original mutable list,
while preserving the existing serialized contents and behavior for other fields.
- Around line 74-92: Update the direct constructor around the status assignment
to enforce the SwapStatus contract: normalize valid string inputs to SwapStatus
or reject non-enum values before assigning self.status. Ensure self.status is
always a SwapStatus instance so to_dict() can safely access .value.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0157ab4e-496c-4a11-910b-3569f6711cac

📥 Commits

Reviewing files that changed from the base of the PR and between 0cf3f50 and c21ef8e.

📒 Files selected for processing (4)

• src/shade/__init__.py
• src/shade/models/__init__.py
• src/shade/models/swap.py
• tests/test_swap_payment.py

[codebestia]

GM @ALIPHATICHYD
Please resolve the conflicts.

[ALIPHATICHYD]

GM @codebestia
I have resolved the conflicts

[codebestia]

LGTM!
Nice implementation.
Thank you for your contribution.