feat(escrow): milestone-based release schedules — storage schema, partial-release accounting, tests

[Oluwaferanmi18]

Summary

Implements/rounds out milestone-based progressive releases in contracts/escrow for #299, so the arbiter can approve discrete project milestones and disburse a proportional share of the escrowed funds on each approval.

The escrow already shipped the beginnings of this flow (deposit_with_milestones / release_milestone). This PR completes it against the issue's acceptance criteria, moves the milestone schema into storage.rs where the rest of the escrow storage lives, and closes two real accounting gaps around partial releases.

What changed

contracts/escrow/src/storage.rs

• Added the Milestone, MilestoneSpec and MilestoneSet #[contracttype] structs next to Escrow / ReleaseSchedule, plus the existing DataKey::Milestones(u64) key.
• Added storage helpers has_milestones, load_milestones, store_milestones (with TTL bump), matching the load_escrow / store_escrow conventions.

contracts/escrow/src/lib.rs

• Re-exports the milestone types and helpers, and stops poking the persistent-storage layout directly.
• release_milestone now keeps escrow.released_amount in lock-step with the milestone running total. Previously only the milestone set tracked payouts, so a timed-out escrow could compute remaining = funded_amount - 0 and over-refund funds already paid to the recipient.
• cancel now returns only the still-held remainder (proportional per asset) instead of the original full asset list, which previously would have over-transferred after a partial milestone approval.

contracts/escrow/src/test.rs

• milestone_invalid_index_rejected — out-of-range index fails with InvalidInput, no funds move.
• milestone_dust_free_exact_distribution — weights 3333/3333/3334 over an amount of 1_000 pay 333 + 333 + 334 = 1_000, leaving the contract at 0.
• milestone_partial_release_tracks_escrow_and_returns_only_remainder_on_cancel — after one of two milestones, released_amount == 4_000, and cancelling returns exactly the 6_000 still held.

contracts/escrow/README.md

• Documented the milestone flow, its duplicate/invalid-index guards and the dust-free final payout.

Acceptance criteria

• Define milestone struct and storage schema in contracts/escrow/src/storage.rs.
• Implement milestone submission and approval functions in contracts/escrow/src/lib.rs (deposit_with_milestones, release_milestone, plus the milestones view).
• Add unit tests verifying partial fund disbursements per milestone.
• Partial release amounts sum to the funded amount without dust or over-release.
• Invalid milestone indices rejected (InvalidInput).
• Duplicate milestone approvals rejected (InvalidState).

Edge cases & invariants

• Weights must sum to exactly 10_000 bps; the final approved milestone pays the exact remainder rather than its floored gross.
• Each milestone may be approved at most once; unknown indices are refused.
• Only the arbiter may approve; plain release stays blocked on milestone escrows so settlement remains phased.
• Refund/reclaim/cancel only ever return funds still in custody.

Testing

cargo test --package astroid-escrow

⚠️ Note: this work was prepared in an environment without a Rust toolchain installed, so cargo test could not be executed here. The changes are straightforward and reviewed by hand, but the suite should be run in CI before merge. The three new tests are additive and the existing milestone/escrow tests are unchanged.

Closes #299

🤖 Generated with Codebuff

[drips-wave]

@Oluwaferanmi18 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.

[Cjay-Cyber-2]

CI Checks Failed — Action Needed

The continuous integration checks on this pull request are failing. I can't merge until all required checks pass.

Failing checks:

• fmt: failure

What to do: review the failing checks in the "Checks" tab above, fix the issues in your code, and push the changes.

[Cjay-Cyber-2]

Merge Conflict — Action Needed

This pull request has merge conflicts with the base branch (main).

What to do: update your branch by merging or rebasing against main, resolve any conflicts locally, and push the result.