diff --git a/src/components/ArbitratorPicker.tsx b/src/components/ArbitratorPicker.tsx
index 1b47a95c..f77a1976 100644
--- a/src/components/ArbitratorPicker.tsx
+++ b/src/components/ArbitratorPicker.tsx
@@ -23,6 +23,17 @@ interface Props {
   showVoteStatus?: boolean;
   /** List of arbitrators who have voted (used when showVoteStatus is true) */
   votedArbitrators?: string[];
+  /**
+   * Enable assignment mode: a multi-select list used by the dispute wizard
+   * and panel to choose the arbitrators for a dispute.
+   */
+  assignmentMode?: boolean;
+  /** Addresses currently selected for assignment (assignment mode only) */
+  assignedAddresses?: string[];
+  /** Callback when the assignment selection changes (assignment mode only) */
+  onAssign?: (addresses: string[]) => void;
+  /** Maximum number of arbitrators that may be assigned (assignment mode only) */
+  maxAssignments?: number;
 }
 
 /**
@@ -38,26 +49,60 @@ export default function ArbitratorPicker({
   heading = "Assigned Arbitrators",
   showVoteStatus = false,
   votedArbitrators = [],
+  assignmentMode = false,
+  assignedAddresses = [],
+  onAssign,
+  maxAssignments,
 }: Props) {
+  const atLimit =
+    maxAssignments !== undefined && assignedAddresses.length >= maxAssignments;
+
+  const toggleAssignment = (address: string) => {
+    if (disabled || !onAssign) return;
+    const isAssigned = assignedAddresses.includes(address);
+    if (isAssigned) {
+      onAssign(assignedAddresses.filter((a) => a !== address));
+    } else {
+      if (atLimit) return;
+      onAssign([...assignedAddresses, address]);
+    }
+  };
+
   return (
     <div>
-      <h3 className="text-sm font-semibold text-white mb-3">{heading}</h3>
+      <div className="flex items-center justify-between mb-3">
+        <h3 className="text-sm font-semibold text-white">{heading}</h3>
+        {assignmentMode && maxAssignments !== undefined && (
+          <span className="text-xs text-gray-400">
+            {assignedAddresses.length}/{maxAssignments} selected
+          </span>
+        )}
+      </div>
       <div className="space-y-2">
         {arbitrators.length === 0 ? (
           <p className="text-sm text-gray-500 bg-gray-900/40 border border-gray-700 rounded-lg p-4 text-center">
-            No arbitrators assigned
+            {assignmentMode ? "No arbitrators available" : "No arbitrators assigned"}
           </p>
         ) : (
           arbitrators.map((arb) => {
-            const isSelected = arb.address === selectedAddress;
+            const isSelected = assignmentMode
+              ? assignedAddresses.includes(arb.address)
+              : arb.address === selectedAddress;
             const hasVoted = votedArbitrators.includes(arb.address);
+            const isDisabled =
+              disabled || (assignmentMode && !isSelected && atLimit);
 
             return (
               <button
                 key={arb.address}
                 type="button"
-                onClick={() => !disabled && onSelect(arb.address)}
-                disabled={disabled}
+                onClick={() =>
+                  assignmentMode
+                    ? toggleAssignment(arb.address)
+                    : !disabled && onSelect(arb.address)
+                }
+                disabled={isDisabled}
+                aria-pressed={isSelected}
                 className={`w-full p-3 rounded-lg border-2 transition-colors text-left disabled:cursor-not-allowed disabled:opacity-60 ${
                   isSelected
                     ? "border-indigo-500 bg-indigo-500/10"
@@ -79,16 +124,28 @@ export default function ArbitratorPicker({
                     )}
                   </div>
 
-                  {showVoteStatus && (
+                  {assignmentMode ? (
                     <span
                       className={`text-xs px-2 py-1 rounded-full font-medium shrink-0 ${
-                        hasVoted
-                          ? "bg-green-500/20 text-green-400"
+                        isSelected
+                          ? "bg-indigo-500/20 text-indigo-300"
                           : "bg-gray-700/50 text-gray-500"
                       }`}
                     >
-                      {hasVoted ? "✓ Voted" : "Pending"}
+                      {isSelected ? "✓ Selected" : "Select"}
                     </span>
+                  ) : (
+                    showVoteStatus && (
+                      <span
+                        className={`text-xs px-2 py-1 rounded-full font-medium shrink-0 ${
+                          hasVoted
+                            ? "bg-green-500/20 text-green-400"
+                            : "bg-gray-700/50 text-gray-500"
+                        }`}
+                      >
+                        {hasVoted ? "✓ Voted" : "Pending"}
+                      </span>
+                    )
                   )}
                 </div>
               </button>
diff --git a/src/components/DisputePanel.tsx b/src/components/DisputePanel.tsx
index a0b4626c..1eafbd01 100644
--- a/src/components/DisputePanel.tsx
+++ b/src/components/DisputePanel.tsx
@@ -6,26 +6,13 @@ import { truncateAddress } from "@stellar-split/sdk";
 import { uploadToIpfs } from "@/lib/ipfs";
 import { getSplitClient } from "@/lib/stellar";
 import ArbitratorPicker from "@/components/ArbitratorPicker";
-
-interface DisputeMetadata {
-  reason: string;
-  description: string;
-  initiator: string;
-  timestamp: number;
-  arbitrators: string[];
-  evidenceLinks: Array<{ cid: string; timestamp: number; submitter: string; filename: string }>;
-}
-
-interface DisputeVoteTally {
-  releaseVotes: number;
-  refundVotes: number;
-  votedArbitrators: string[];
-}
-
-interface DisputeStatus extends DisputeMetadata, DisputeVoteTally {
-  resolved: boolean;
-  outcome?: "Release" | "Refund";
-}
+import {
+  type DisputeRecord,
+  type DisputeState,
+  type DisputeOutcome,
+  isVotingComplete,
+  canEnforceResolution,
+} from "@/lib/arbitrators";
 
 interface Props {
   invoice: Invoice;
@@ -33,6 +20,21 @@ interface Props {
   onRefresh?: () => Promise<void>;
 }
 
+/** Emit a toast notification if the global toast container is available. */
+function notify(message: string, type: "success" | "error" | "info" = "info") {
+  if (typeof window !== "undefined" && (window as any).__toastContainer?.addToast) {
+    (window as any).__toastContainer.addToast(message, type);
+  }
+}
+
+const STATE_LABELS: Record<DisputeState, string> = {
+  Open: "Open",
+  Evidence: "Evidence Collection",
+  Voting: "Arbitrator Voting",
+  Resolved: "Resolved",
+  Enforced: "Enforced",
+};
+
 /**
  * DisputePanel — Full arbitration interface for Disputed invoices.
  * Shows dispute metadata, allows evidence submission via IPFS,
@@ -44,18 +46,22 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
   const [uploadError, setUploadError] = useState<string | null>(null);
   const [voting, setVoting] = useState(false);
   const [voteError, setVoteError] = useState<string | null>(null);
+  const [enforcing, setEnforcing] = useState(false);
+  const [enforceError, setEnforceError] = useState<string | null>(null);
 
   // Only render for Disputed invoices
   if ((invoice.status as string) !== "Disputed") return null;
 
   // Access dispute data from extended invoice type
-  const dispute = (invoice as Invoice & { disputeStatus?: DisputeStatus }).disputeStatus;
+  const dispute = (invoice as Invoice & { disputeRecord?: DisputeRecord }).disputeRecord;
   if (!dispute) return null;
 
   const isArbitrator = dispute.arbitrators.includes(publicKey);
-  const hasVoted = dispute.votedArbitrators.includes(publicKey);
+  const hasVoted = dispute.votes.some((v) => v.arbitrator === publicKey);
+  const votingComplete = isVotingComplete(dispute);
+  const canEnforce = canEnforceResolution(dispute);
 
-  const handleVote = async (voteType: "Release" | "Refund") => {
+  const handleVote = async (voteType: DisputeOutcome) => {
     if (!isArbitrator || hasVoted) return;
 
     setVoteError(null);
@@ -69,23 +75,52 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
         vote: voteType === "Release" ? 1 : 0,
       });
 
-      // Show success toast
-      if (typeof window !== "undefined" && (window as any).__toastContainer?.addToast) {
-        (window as any).__toastContainer.addToast(`Vote "${voteType}" submitted successfully`, "success");
-      }
+      notify(`Vote "${voteType}" submitted successfully`, "success");
 
       // Refresh invoice data
       if (onRefresh) await onRefresh();
     } catch (err) {
-      setVoteError(err instanceof Error ? err.message : String(err));
+      const message = err instanceof Error ? err.message : String(err);
+      setVoteError(message);
+      notify(`Failed to submit vote: ${message}`, "error");
     } finally {
       setVoting(false);
     }
   };
 
-  const totalVotes = dispute.releaseVotes + dispute.refundVotes;
-  const releasePercent = totalVotes > 0 ? (dispute.releaseVotes / totalVotes) * 100 : 0;
-  const refundPercent = totalVotes > 0 ? (dispute.refundVotes / totalVotes) * 100 : 0;
+  const handleEnforce = async () => {
+    if (!canEnforce) return;
+
+    setEnforceError(null);
+    setEnforcing(true);
+
+    try {
+      const client = getSplitClient();
+      await (client as any).enforceDisputeResolution({
+        invoiceId: invoice.id,
+        arbitrator: publicKey,
+      });
+
+      notify(
+        `Resolution enforced: ${dispute.outcome === "Release" ? "funds released" : "funds refunded"}`,
+        "success",
+      );
+
+      if (onRefresh) await onRefresh();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setEnforceError(message);
+      notify(`Failed to enforce resolution: ${message}`, "error");
+    } finally {
+      setEnforcing(false);
+    }
+  };
+
+  const releaseVotes = dispute.votes.filter((v) => v.vote === "Release").length;
+  const refundVotes = dispute.votes.filter((v) => v.vote === "Refund").length;
+  const totalVotes = releaseVotes + refundVotes;
+  const releasePercent = totalVotes > 0 ? (releaseVotes / totalVotes) * 100 : 0;
+  const refundPercent = totalVotes > 0 ? (refundVotes / totalVotes) * 100 : 0;
 
   return (
     <>
@@ -102,17 +137,23 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
               This invoice is under arbitration review
             </p>
           </div>
-          {dispute.resolved && (
-            <span
-              className={`px-4 py-2 rounded-full text-sm font-bold ${
-                dispute.outcome === "Release"
-                  ? "bg-green-500/20 text-green-400"
-                  : "bg-orange-500/20 text-orange-400"
-              }`}
-            >
-              {dispute.outcome === "Release" ? "✓ Approved" : "↩️ Refunded"}
+          <div className="flex flex-col items-end gap-2">
+            <span className="px-3 py-1 rounded-full text-xs font-semibold bg-gray-800 text-gray-300">
+              {STATE_LABELS[dispute.state]}
             </span>
-          )}
+            {dispute.state === "Resolved" || dispute.state === "Enforced" ? (
+              <span
+                className={`px-4 py-2 rounded-full text-sm font-bold ${
+                  dispute.outcome === "Release"
+                    ? "bg-green-500/20 text-green-400"
+                    : "bg-orange-500/20 text-orange-400"
+                }`}
+              >
+                {dispute.outcome === "Release" ? "✓ Approved" : "↩️ Refunded"}
+                {dispute.state === "Enforced" ? " • Enforced" : ""}
+              </span>
+            ) : null}
+          </div>
         </div>
 
         {/* Dispute Metadata */}
@@ -137,6 +178,28 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
           </div>
         </div>
 
+        {/* Dispute Timeline */}
+        {dispute.timeline.length > 0 && (
+          <div className="mb-6 bg-gray-900/60 rounded-xl p-4 border border-gray-700">
+            <p className="text-xs text-gray-500 uppercase tracking-wide mb-3">Timeline</p>
+            <ol className="space-y-2">
+              {dispute.timeline.map((event, idx) => (
+                <li key={idx} className="flex items-start gap-3 text-sm">
+                  <span className="text-gray-500 shrink-0 font-mono text-xs pt-0.5">
+                    {new Date(event.timestamp * 1000).toLocaleString()}
+                  </span>
+                  <span className="text-gray-300">
+                    {event.description}
+                    {event.actor ? (
+                      <span className="text-gray-500"> — {truncateAddress(event.actor)}</span>
+                    ) : null}
+                  </span>
+                </li>
+              ))}
+            </ol>
+          </div>
+        )}
+
         {/* Description */}
         {dispute.description && (
           <div className="mb-6 bg-gray-900/60 rounded-xl p-4 border border-gray-700">
@@ -159,7 +222,7 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
             <div>
               <div className="flex items-center justify-between text-sm mb-1">
                 <span className="text-green-400 font-medium">✓ Approve Release</span>
-                <span className="text-green-400 font-bold">{dispute.releaseVotes}</span>
+                <span className="text-green-400 font-bold">{releaseVotes}</span>
               </div>
               <div className="h-3 bg-gray-800 rounded-full overflow-hidden">
                 <div
@@ -173,7 +236,7 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
             <div>
               <div className="flex items-center justify-between text-sm mb-1">
                 <span className="text-orange-400 font-medium">↩️ Reject / Refund</span>
-                <span className="text-orange-400 font-bold">{dispute.refundVotes}</span>
+                <span className="text-orange-400 font-bold">{refundVotes}</span>
               </div>
               <div className="h-3 bg-gray-800 rounded-full overflow-hidden">
                 <div
@@ -186,7 +249,7 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
         </div>
 
         {/* Arbitrator Actions */}
-        {isArbitrator && !dispute.resolved && (
+        {isArbitrator && dispute.state !== "Resolved" && dispute.state !== "Enforced" && (
           <div className="mb-6 bg-indigo-950/30 border-2 border-indigo-500/30 rounded-xl p-5">
             <div className="flex items-center gap-2 mb-4">
               <span className="text-lg">⚖️</span>
@@ -232,13 +295,43 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
           </div>
         )}
 
+        {/* Resolution Enforcement */}
+        {isArbitrator && votingComplete && dispute.state !== "Enforced" && (
+          <div className="mb-6 bg-green-950/30 border-2 border-green-500/30 rounded-xl p-5">
+            <div className="flex items-center gap-2 mb-3">
+              <span className="text-lg">🔒</span>
+              <h3 className="text-sm font-bold text-green-300 uppercase tracking-wide">
+                Enforce Resolution
+              </h3>
+            </div>
+            <p className="text-sm text-gray-300 mb-4">
+              Voting is complete. The outcome is{" "}
+              <span className="font-semibold text-white">{dispute.outcome}</span>. Enforce this
+              resolution to settle the invoice on-chain.
+            </p>
+            <button
+              onClick={handleEnforce}
+              disabled={!canEnforce || enforcing}
+              className="w-full px-4 py-3 rounded-lg bg-green-600 hover:bg-green-500 text-white font-semibold text-sm transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+              aria-label="Enforce dispute resolution"
+            >
+              {enforcing ? "Enforcing..." : "🔒 Enforce Resolution"}
+            </button>
+            {enforceError && (
+              <p role="alert" className="text-red-400 text-sm mt-3">
+                {enforceError}
+              </p>
+            )}
+          </div>
+        )}
+
         {/* Evidence Section */}
         <div className="mb-6">
           <div className="flex items-center justify-between mb-3">
             <h3 className="text-sm font-semibold text-white">Evidence Submitted</h3>
             <button
               onClick={() => setShowEvidenceModal(true)}
-              disabled={dispute.resolved}
+              disabled={dispute.state === "Resolved" || dispute.state === "Enforced"}
               className="px-3 py-1.5 rounded-lg bg-indigo-600 hover:bg-indigo-500 text-white text-xs font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
               aria-label="Submit evidence"
             >
@@ -292,7 +385,7 @@ export default function DisputePanel({ invoice, publicKey, onRefresh }: Props) {
           onSelect={() => {}}
           disabled={true}
           showVoteStatus={true}
-          votedArbitrators={dispute.votedArbitrators}
+          votedArbitrators={dispute.votes.map((v) => v.arbitrator)}
         />
       </section>
 
@@ -363,14 +456,13 @@ function EvidenceUploadModal({ invoiceId, publicKey, onClose, onSuccess }: Evide
         filename: file.name,
       });
 
-      // Show success toast
-      if (typeof window !== "undefined" && (window as any).__toastContainer?.addToast) {
-        (window as any).__toastContainer.addToast("Evidence submitted successfully", "success");
-      }
+      notify("Evidence submitted successfully", "success");
 
       await onSuccess();
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to upload evidence");
+      const message = err instanceof Error ? err.message : "Failed to upload evidence";
+      setError(message);
+      notify(`Failed to submit evidence: ${message}`, "error");
     } finally {
       setUploading(false);
     }
diff --git a/src/components/DisputeTimeline.tsx b/src/components/DisputeTimeline.tsx
index 00c0f02b..2ad22400 100644
--- a/src/components/DisputeTimeline.tsx
+++ b/src/components/DisputeTimeline.tsx
@@ -5,7 +5,13 @@ import { splitClient } from "@/lib/stellar";
 import { truncateAddress } from "@stellar-split/sdk";
 
 interface DisputeEvent {
-  type: "DisputeOpened" | "EvidenceSubmitted" | "VoteCast" | "DisputeResolved";
+  type:
+    | "DisputeOpened"
+    | "EvidenceSubmitted"
+    | "ArbitratorSelected"
+    | "VoteCast"
+    | "DisputeResolved"
+    | "ResolutionEnforced";
   timestamp: number;
   actor: string;
   metadata?: {
@@ -14,6 +20,8 @@ interface DisputeEvent {
     filename?: string;
     vote?: "Release" | "Refund";
     outcome?: "Release" | "Refund";
+    arbitrator?: string;
+    enforcementTxHash?: string;
   };
 }
 
@@ -24,6 +32,8 @@ interface DisputeStatus {
   outcome?: "Release" | "Refund";
   reason?: string;
   initiator?: string;
+  enforced?: boolean;
+  enforcementTxHash?: string;
 }
 
 interface Props {
@@ -51,11 +61,22 @@ export default function DisputeTimeline({ invoiceId, disputeStatus }: Props) {
   useEffect(() => {
     const loadEvents = async () => {
       try {
-        // Fetch dispute events from the audit log or contract events
+        // Prefer the persisted dispute record's append-only timeline.
+        const record = await (splitClient as any).getDisputeRecord?.(invoiceId);
+        if (record && Array.isArray(record.timeline)) {
+          const sorted = [...record.timeline].sort(
+            (a: DisputeEvent, b: DisputeEvent) => a.timestamp - b.timestamp,
+          );
+          setEvents(sorted);
+          return;
+        }
+
+        // Fall back to contract events when no persisted record exists.
         const log = await (splitClient as any).getDisputeEvents?.(invoiceId);
         if (log && Array.isArray(log)) {
-          // Sort events chronologically
-          const sorted = log.sort((a: DisputeEvent, b: DisputeEvent) => a.timestamp - b.timestamp);
+          const sorted = [...log].sort(
+            (a: DisputeEvent, b: DisputeEvent) => a.timestamp - b.timestamp,
+          );
           setEvents(sorted);
         }
       } catch (err) {
@@ -163,6 +184,19 @@ export default function DisputeTimeline({ invoiceId, disputeStatus }: Props) {
                     </div>
                   )}
 
+                  {event.type === "ArbitratorSelected" && (
+                    <div className="mt-3 bg-gray-800/50 rounded-lg p-3 border border-gray-700">
+                      <p className="text-xs text-gray-500 uppercase tracking-wide mb-1">
+                        Arbitrator
+                      </p>
+                      <p className="text-sm font-mono text-gray-300">
+                        {event.metadata?.arbitrator
+                          ? truncateAddress(event.metadata.arbitrator)
+                          : truncateAddress(event.actor)}
+                      </p>
+                    </div>
+                  )}
+
                   {event.type === "VoteCast" && event.metadata?.vote && (
                     <div className="mt-3">
                       <span
@@ -201,6 +235,29 @@ export default function DisputeTimeline({ invoiceId, disputeStatus }: Props) {
                       </div>
                     </div>
                   )}
+
+                  {event.type === "ResolutionEnforced" && (
+                    <div className="mt-3 bg-gray-800/50 rounded-lg p-3 border border-gray-700">
+                      <p className="text-xs text-gray-500 uppercase tracking-wide mb-1">
+                        Resolution Enforced
+                      </p>
+                      <div className="flex items-center gap-3">
+                        <span className="inline-flex items-center gap-1 px-3 py-1.5 rounded-full text-sm font-bold bg-green-500/20 text-green-400">
+                          ✓ Enforced
+                        </span>
+                        {(event.metadata?.enforcementTxHash ||
+                          disputeStatus.enforcementTxHash) && (
+                          <span className="text-xs font-mono text-gray-400 truncate">
+                            {truncateAddress(
+                              event.metadata?.enforcementTxHash ||
+                                disputeStatus.enforcementTxHash ||
+                                "",
+                            )}
+                          </span>
+                        )}
+                      </div>
+                    </div>
+                  )}
                 </div>
               </li>
             );
@@ -217,10 +274,14 @@ function getEventIcon(type: DisputeEvent["type"]): string {
       return "⚠️";
     case "EvidenceSubmitted":
       return "📎";
+    case "ArbitratorSelected":
+      return "🧑‍⚖️";
     case "VoteCast":
       return "⚖️";
     case "DisputeResolved":
       return "✓";
+    case "ResolutionEnforced":
+      return "🔒";
     default:
       return "•";
   }
@@ -232,10 +293,14 @@ function getEventColor(type: DisputeEvent["type"]): string {
       return "border-red-500 bg-red-500 text-white";
     case "EvidenceSubmitted":
       return "border-blue-500 bg-blue-500 text-white";
+    case "ArbitratorSelected":
+      return "border-purple-500 bg-purple-500 text-white";
     case "VoteCast":
       return "border-indigo-500 bg-indigo-500 text-white";
     case "DisputeResolved":
       return "border-green-500 bg-green-500 text-white";
+    case "ResolutionEnforced":
+      return "border-emerald-500 bg-emerald-500 text-white";
     default:
       return "border-gray-600 bg-gray-900 text-gray-400";
   }
@@ -247,10 +312,14 @@ function getEventTitle(type: DisputeEvent["type"]): string {
       return "Dispute Opened";
     case "EvidenceSubmitted":
       return "Evidence Submitted";
+    case "ArbitratorSelected":
+      return "Arbitrator Selected";
     case "VoteCast":
       return "Vote Cast";
     case "DisputeResolved":
       return "Dispute Resolved";
+    case "ResolutionEnforced":
+      return "Resolution Enforced";
     default:
       return "Event";
   }
diff --git a/src/components/DisputeWizard.tsx b/src/components/DisputeWizard.tsx
index 7057832c..abdb320d 100644
--- a/src/components/DisputeWizard.tsx
+++ b/src/components/DisputeWizard.tsx
@@ -3,6 +3,9 @@
 import { useState } from "react";
 import { searchArbitrators, getArbitrators } from "@/lib/arbitrators";
 import type { Arbitrator } from "@/lib/arbitrators";
+import { createDispute } from "@/lib/disputes";
+import type { DisputeRecord } from "@/lib/disputes";
+import { notifyDisputeOpened } from "@/lib/disputeNotifications";
 
 const DISPUTE_REASONS = [
   "Non-delivery",
@@ -17,6 +20,8 @@ interface Props {
   invoiceId: string;
   onSubmit: (reason: string, description: string, arbitratorAddress?: string) => Promise<void>;
   onClose: () => void;
+  /** Called after a dispute is successfully created so the invoice can be refreshed. */
+  onCreated?: (dispute: DisputeRecord) => void;
 }
 
 /**
@@ -64,7 +69,7 @@ function StepIndicator({ current, total }: { current: number; total: number }) {
  * DisputeWizard — multi-step modal form for filing an on-chain dispute.
  * Guides the user through: reason → description → arbitrator → confirmation.
  */
-export default function DisputeWizard({ invoiceId, onSubmit, onClose }: Props) {
+export default function DisputeWizard({ invoiceId, onSubmit, onClose, onCreated }: Props) {
   const [step, setStep] = useState(1);
   const [reason, setReason] = useState("");
   const [description, setDescription] = useState("");
@@ -72,6 +77,7 @@ export default function DisputeWizard({ invoiceId, onSubmit, onClose }: Props) {
   const [arbitratorSearch, setArbitratorSearch] = useState("");
   const [manualArbitrator, setManualArbitrator] = useState("");
   const [useManualEntry, setUseManualEntry] = useState(false);
+  const [evidenceNote, setEvidenceNote] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -94,9 +100,29 @@ export default function DisputeWizard({ invoiceId, onSubmit, onClose }: Props) {
 
   const handleConfirm = async () => {
     setError(null);
+
+    if (!reason) {
+      setError("Please select a dispute reason.");
+      return;
+    }
+    if (description.trim().length < 20) {
+      setError("Description must be at least 20 characters.");
+      return;
+    }
+
     setSubmitting(true);
     try {
+      const dispute = await createDispute({
+        invoiceId,
+        reason,
+        description: description.trim(),
+        arbitratorAddress: effectiveArbitrator || undefined,
+        evidence: evidenceNote.trim() ? [{ note: evidenceNote.trim() }] : undefined,
+      });
+
       await onSubmit(reason, description, effectiveArbitrator || undefined);
+      notifyDisputeOpened(dispute);
+      onCreated?.(dispute);
       onClose();
     } catch (err) {
       setError(String(err));
@@ -270,6 +296,17 @@ export default function DisputeWizard({ invoiceId, onSubmit, onClose }: Props) {
                 </div>
               )}
             </div>
+            <div className="space-y-2">
+              <p className="text-sm text-gray-400">Evidence (optional)</p>
+              <textarea
+                value={evidenceNote}
+                onChange={(e) => setEvidenceNote(e.target.value)}
+                placeholder="Add a note or reference to supporting evidence..."
+                maxLength={500}
+                className="w-full bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500 resize-none h-20"
+              />
+              <p className="text-xs text-gray-500">{evidenceNote.length}/500 characters</p>
+            </div>
           </div>
         )}
 
diff --git a/src/components/InvoiceDetail.tsx b/src/components/InvoiceDetail.tsx
index 92421ee4..a05b9946 100644
--- a/src/components/InvoiceDetail.tsx
+++ b/src/components/InvoiceDetail.tsx
@@ -1,4 +1,4 @@
-import React, { useMemo } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 
 /**
  * Invoice impact storytelling UI.
@@ -29,6 +29,62 @@ export interface InvoiceImpactMetric {
   icon?: string;
 }
 
+export type MilestoneConditionStatus = 'pending' | 'approved' | 'verified';
+
+export interface MilestoneEvidence {
+  /** Stable identifier for the uploaded evidence. */
+  id: string;
+  /** Display name of the uploaded file. */
+  name: string;
+  /** IPFS URI (e.g. ipfs://...) returned by the upload helper. */
+  uri: string;
+  /** Optional MIME type of the uploaded file. */
+  mimeType?: string;
+  /** ISO timestamp of when the evidence was uploaded. */
+  uploadedAt: string;
+}
+
+export interface MilestoneCondition {
+  /** Stable identifier for the condition. */
+  id: string;
+  /** Human readable description of the condition. */
+  description: string;
+  /** Current status of the condition. */
+  status: MilestoneConditionStatus;
+}
+
+export interface Milestone {
+  /** Stable identifier for the milestone. */
+  id: string;
+  /** Short title for the milestone. */
+  title: string;
+  /** Deliverable text describing what must be produced. */
+  deliverable: string;
+  /** Amount (smallest currency unit) released when conditions are met. */
+  amount: number;
+  /** Whether an explicit approval is required before release. */
+  requiresApproval: boolean;
+  /** Whether evidence/documentation must be uploaded before release. */
+  requiresEvidence: boolean;
+  /** Conditions that must be satisfied before funds are released. */
+  conditions: MilestoneCondition[];
+  /** Uploaded evidence documents. */
+  evidence: MilestoneEvidence[];
+}
+
+export interface MilestoneDraft {
+  title: string;
+  deliverable: string;
+  amount: number;
+  requiresApproval: boolean;
+  requiresEvidence: boolean;
+}
+
+export interface ReleaseResult {
+  success: boolean;
+  message?: string;
+}
+
 export interface InvoiceDetailProps {
   /** Invoice identifier shown in the header. */
   invoiceId: string;
@@ -42,6 +98,17 @@ export interface InvoiceDetailProps {
   loading?: boolean;
   /** Optional error message to surface instead of the story. */
   error?: string | null;
+  /** Optional initial milestones for the invoice. */
+  initialMilestones?: Milestone[];
+  /** Uploads evidence to IPFS and resolves with the resulting URI. */
+  uploadEvidence?: (file: File) => Promise<string>;
+  /** Releases funds for a milestone once all conditions are satisfied. */
+  releaseMilestone?: (
+    invoiceId: string,
+    milestone: Milestone,
+  ) => Promise<ReleaseResult>;
+  /** Notification callback for user-facing events. */
+  onNotify?: (message: string, type: 'success' | 'error' | 'info') => void;
 }
 
 const DEFAULT_CURRENCY = 'USD';
@@ -100,6 +167,56 @@ export function deriveImpactStory(amount: number): InvoiceImpactStory {
   };
 }
 
+function createId(prefix: string): string {
+  return `${prefix}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function buildConditions(draft: MilestoneDraft): MilestoneCondition[] {
+  const conditions: MilestoneCondition[] = [
+    {
+      id: createId('condition'),
+      description: `Deliverable completed: ${draft.deliverable.trim()}`,
+      status: 'pending',
+    },
+  ];
+  if (draft.requiresApproval) {
+    conditions.push({
+      id: createId('condition'),
+      description: 'Recipient approval obtained',
+      status: 'pending',
+    });
+  }
+  if (draft.requiresEvidence) {
+    conditions.push({
+      id: createId('condition'),
+      description: 'Evidence/documentation uploaded and verified',
+      status: 'pending',
+    });
+  }
+  return conditions;
+}
+
+export function areConditionsSatisfied(milestone: Milestone): boolean {
+  if (milestone.conditions.length === 0) {
+    return false;
+  }
+  if (!milestone.conditions.every((c) => c.status === 'verified')) {
+    return false;
+  }
+  if (milestone.requiresEvidence && milestone.evidence.length === 0) {
+    return false;
+  }
+  return true;
+}
+
+const EMPTY_DRAFT: MilestoneDraft = {
+  title: '',
+  deliverable: '',
+  amount: 0,
+  requiresApproval: true,
+  requiresEvidence: true,
+};
+
 const InvoiceDetail: React.FC<InvoiceDetailProps> = ({
   invoiceId,
   amount,
@@ -107,7 +224,176 @@ const InvoiceDetail: React.FC<InvoiceDetailProps> = ({
   story,
   loading = false,
   error = null,
+  initialMilestones,
+  uploadEvidence,
+  releaseMilestone,
+  onNotify,
 }) => {
+  const [milestones, setMilestones] = useState<Milestone[]>(
+    () => initialMilestones ?? [],
+  );
+  const [draft, setDraft] = useState<MilestoneDraft>(EMPTY_DRAFT);
+  const [draftError, setDraftError] = useState<string | null>(null);
+  const [uploadingFor, setUploadingFor] = useState<string | null>(null);
+  const [releasingFor, setReleasingFor] = useState<string | null>(null);
+
+  const notify = useCallback(
+    (message: string, type: 'success' | 'error' | 'info') => {
+      onNotify?.(message, type);
+    },
+    [onNotify],
+  );
+
+  const updateMilestone = useCallback(
+    (milestoneId: string, updater: (m: Milestone) => Milestone) => {
+      setMilestones((prev) =>
+        prev.map((m) => (m.id === milestoneId ? updater(m) : m)),
+      );
+    },
+    [],
+  );
+
+  const handleDraftChange = useCallback(
+    <K extends keyof MilestoneDraft>(key: K, value: MilestoneDraft[K]) => {
+      setDraft((prev) => ({ ...prev, [key]: value }));
+    },
+    [],
+  );
+
+  const handleAddMilestone = useCallback(
+    (event: React.FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      if (!draft.title.trim()) {
+        setDraftError('Milestone title is required.');
+        return;
+      }
+      if (!draft.deliverable.trim()) {
+        setDraftError('Deliverable description is required.');
+        return;
+      }
+      if (!Number.isFinite(draft.amount) || draft.amount <= 0) {
+        setDraftError('Milestone amount must be greater than zero.');
+        return;
+      }
+      const milestone: Milestone = {
+        id: createId('milestone'),
+        title: draft.title.trim(),
+        deliverable: draft.deliverable.trim(),
+        amount: draft.amount,
+        requiresApproval: draft.requiresApproval,
+        requiresEvidence: draft.requiresEvidence,
+        conditions: buildConditions(draft),
+        evidence: [],
+      };
+      setMilestones((prev) => [...prev, milestone]);
+      setDraft(EMPTY_DRAFT);
+      setDraftError(null);
+      notify(`Milestone "${milestone.title}" added.`, 'success');
+    },
+    [draft, notify],
+  );
+
+  const handleRemoveMilestone = useCallback(
+    (milestoneId: string) => {
+      setMilestones((prev) => prev.filter((m) => m.id !== milestoneId));
+      notify('Milestone removed.', 'info');
+    },
+    [notify],
+  );
+
+  const handleApproveCondition = useCallback(
+    (milestoneId: string, conditionId: string) => {
+      updateMilestone(milestoneId, (m) => ({
+        ...m,
+        conditions: m.conditions.map((c) =>
+          c.id === conditionId && c.status === 'pending'
+            ? { ...c, status: 'approved' }
+            : c,
+        ),
+      }));
+      notify('Condition approved.', 'success');
+    },
+    [updateMilestone, notify],
+  );
+
+  const handleVerifyCondition = useCallback(
+    (milestoneId: string, conditionId: string) => {
+      updateMilestone(milestoneId, (m) => ({
+        ...m,
+        conditions: m.conditions.map((c) =>
+          c.id === conditionId && c.status === 'approved'
+            ? { ...c, status: 'verified' }
+            : c,
+        ),
+      }));
+      notify('Condition verified.', 'success');
+    },
+    [updateMilestone, notify],
+  );
+
+  const handleEvidenceUpload = useCallback(
+    async (milestoneId: string, file: File) => {
+      if (!uploadEvidence) {
+        notify('Evidence upload is not configured.', 'error');
+        return;
+      }
+      setUploadingFor(milestoneId);
+      try {
+        const uri = await uploadEvidence(file);
+        const evidence: MilestoneEvidence = {
+          id: createId('evidence'),
+          name: file.name,
+          uri,
+          mimeType: file.type || undefined,
+          uploadedAt: new Date().toISOString(),
+        };
+        updateMilestone(milestoneId, (m) => ({
+          ...m,
+          evidence: [...m.evidence, evidence],
+        }));
+        notify(`Evidence "${file.name}" uploaded.`, 'success');
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : 'Evidence upload failed.';
+        notify(message, 'error');
+      } finally {
+        setUploadingFor(null);
+      }
+    },
+    [uploadEvidence, updateMilestone, notify],
+  );
+
+  const handleRelease = useCallback(
+    async (milestone: Milestone) => {
+      if (!areConditionsSatisfied(milestone)) {
+        notify('All conditions must be satisfied before release.', 'error');
+        return;
+      }
+      if (!releaseMilestone) {
+        notify('Fund release is not configured.', 'error');
+        return;
+      }
+      setReleasingFor(milestone.id);
+      try {
+        const result = await releaseMilestone(invoiceId, milestone);
+        if (result.success) {
+          notify(
+            result.message ?? `Funds released for "${milestone.title}".`,
+            'success',
+          );
+        } else {
+          notify(result.message ?? 'Fund release failed.', 'error');
+        }
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : 'Fund release failed.';
+        notify(message, 'error');
+      } finally {
+        setReleasingFor(null);
+      }
+    },
+    [invoiceId, releaseMilestone, notify],
+  );
   const resolvedStory = useMemo(
     () => story ?? deriveImpactStory(amount),
     [story, amount],
@@ -172,6 +458,232 @@ const InvoiceDetail: React.FC<InvoiceDetailProps> = ({
           </ul>
         </div>
       )}
+
+      <section
+        className="invoice-detail__milestones"
+        aria-labelledby={`invoice-milestones-heading-${invoiceId}`}
+      >
+        <h3 id={`invoice-milestones-heading-${invoiceId}`}>
+          Milestones &amp; conditions
+        </h3>
+
+        <form
+          className="milestone-editor"
+          onSubmit={handleAddMilestone}
+          aria-label="Add milestone"
+        >
+          <div className="milestone-editor__field">
+            <label htmlFor={`milestone-title-${invoiceId}`}>Title</label>
+            <input
+              id={`milestone-title-${invoiceId}`}
+              type="text"
+              value={draft.title}
+              onChange={(e) => handleDraftChange('title', e.target.value)}
+              required
+            />
+          </div>
+          <div className="milestone-editor__field">
+            <label htmlFor={`milestone-deliverable-${invoiceId}`}>
+              Deliverable
+            </label>
+            <textarea
+              id={`milestone-deliverable-${invoiceId}`}
+              value={draft.deliverable}
+              onChange={(e) =>
+                handleDraftChange('deliverable', e.target.value)
+              }
+              required
+            />
+          </div>
+          <div className="milestone-editor__field">
+            <label htmlFor={`milestone-amount-${invoiceId}`}>
+              Amount (in {currency})
+            </label>
+            <input
+              id={`milestone-amount-${invoiceId}`}
+              type="number"
+              min={0}
+              step="0.01"
+              value={draft.amount === 0 ? '' : draft.amount / 100}
+              onChange={(e) =>
+                handleDraftChange(
+                  'amount',
+                  Math.round(Number(e.target.value) * 100),
+                )
+              }
+              required
+            />
+          </div>
+          <div className="milestone-editor__field milestone-editor__field--checkbox">
+            <label>
+              <input
+                type="checkbox"
+                checked={draft.requiresApproval}
+                onChange={(e) =>
+                  handleDraftChange('requiresApproval', e.target.checked)
+                }
+              />
+              Requires approval
+            </label>
+          </div>
+          <div className="milestone-editor__field milestone-editor__field--checkbox">
+            <label>
+              <input
+                type="checkbox"
+                checked={draft.requiresEvidence}
+                onChange={(e) =>
+                  handleDraftChange('requiresEvidence', e.target.checked)
+                }
+              />
+              Requires evidence
+            </label>
+          </div>
+          {draftError ? (
+            <p className="milestone-editor__error" role="alert">
+              {draftError}
+            </p>
+          ) : null}
+          <button type="submit" className="milestone-editor__submit">
+            Add milestone
+          </button>
+        </form>
+
+        {milestones.length === 0 ? (
+          <p className="invoice-detail__milestones-empty">
+            No milestones defined yet.
+          </p>
+        ) : (
+          <ul className="milestone-list">
+            {milestones.map((milestone) => {
+              const satisfied = areConditionsSatisfied(milestone);
+              return (
+                <li key={milestone.id} className="milestone-list__item">
+                  <header className="milestone-list__header">
+                    <h4 className="milestone-list__title">{milestone.title}</h4>
+                    <span className="milestone-list__amount">
+                      {formatCurrency(milestone.amount, currency)}
+                    </span>
+                  </header>
+                  <p className="milestone-list__deliverable">
+                    {milestone.deliverable}
+                  </p>
+
+                  <ul className="milestone-list__conditions">
+                    {milestone.conditions.map((condition) => (
+                      <li
+                        key={condition.id}
+                        className={`milestone-condition milestone-condition--${condition.status}`}
+                      >
+                        <span className="milestone-condition__description">
+                          {condition.description}
+                        </span>
+                        <span
+                          className="milestone-condition__status"
+                          aria-label={`Status: ${condition.status}`}
+                        >
+                          {condition.status}
+                        </span>
+                        {condition.status === 'pending' ? (
+                          <button
+                            type="button"
+                            onClick={() =>
+                              handleApproveCondition(
+                                milestone.id,
+                                condition.id,
+                              )
+                            }
+                          >
+                            Approve
+                          </button>
+                        ) : null}
+                        {condition.status === 'approved' ? (
+                          <button
+                            type="button"
+                            onClick={() =>
+                              handleVerifyCondition(
+                                milestone.id,
+                                condition.id,
+                              )
+                            }
+                          >
+                            Verify
+                          </button>
+                        ) : null}
+                      </li>
+                    ))}
+                  </ul>
+
+                  {milestone.requiresEvidence ? (
+                    <div className="milestone-list__evidence">
+                      <label
+                        htmlFor={`milestone-evidence-${milestone.id}`}
+                      >
+                        Upload evidence
+                      </label>
+                      <input
+                        id={`milestone-evidence-${milestone.id}`}
+                        type="file"
+                        disabled={uploadingFor === milestone.id}
+                        onChange={(e) => {
+                          const file = e.target.files?.[0];
+                          if (file) {
+                            void handleEvidenceUpload(milestone.id, file);
+                          }
+                          e.target.value = '';
+                        }}
+                      />
+                      {uploadingFor === milestone.id ? (
+                        <span role="status">Uploading\u2026</span>
+                      ) : null}
+                      {milestone.evidence.length > 0 ? (
+                        <ul className="milestone-list__evidence-items">
+                          {milestone.evidence.map((ev) => (
+                            <li key={ev.id}>
+                              <a
+                                href={ev.uri}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                              >
+                                {ev.name}
+                              </a>
+                            </li>
+                          ))}
+                        </ul>
+                      ) : null}
+                    </div>
+                  ) : null}
+
+                  <div className="milestone-list__actions">
+                    <button
+                      type="button"
+                      className="milestone-list__release"
+                      disabled={!satisfied || releasingFor === milestone.id}
+                      aria-disabled={!satisfied || releasingFor === milestone.id}
+                      title={
+                        satisfied
+                          ? 'Release funds'
+                          : 'All conditions must be satisfied before release'
+                      }
+                      onClick={() => void handleRelease(milestone)}
+                    >
+                      {releasingFor === milestone.id
+                        ? 'Releasing\u2026'
+                        : 'Release funds'}
+                    </button>
+                    <button
+                      type="button"
+                      className="milestone-list__remove"
+                      onClick={() => handleRemoveMilestone(milestone.id)}
+                    >
+                      Remove
+                    </button>
+                  </div>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </section>
     </section>
   );
 };
diff --git a/src/components/NotificationCenter.tsx b/src/components/NotificationCenter.tsx
index 3976b7c7..1d8429d4 100644
--- a/src/components/NotificationCenter.tsx
+++ b/src/components/NotificationCenter.tsx
@@ -4,7 +4,14 @@ import { useEffect, useRef, useState, useCallback } from "react";
 import Link from "next/link";
 import { splitClient } from "@/lib/stellar";
 
-export type NotificationType = "payment" | "funded" | "released" | "expired" | "reminder";
+export type NotificationType =
+  | "payment"
+  | "funded"
+  | "released"
+  | "expired"
+  | "reminder"
+  | "milestone"
+  | "dispute";
 
 export interface AppNotification {
   id: string;
@@ -18,9 +25,37 @@ export interface AppNotification {
 
 const STORAGE_KEY = "stellarsplit_notifications_v2";
 const SUBSCRIBED_KEY = "stellarsplit_notify_invoices";
+const MILESTONES_KEY = "stellarsplit_milestones_v1";
+const DISPUTES_KEY = "stellarsplit_disputes_v1";
 const MAX_NOTIFICATIONS = 50;
 const POLL_INTERVAL_MS = 30_000;
 
+interface MilestoneRecord {
+  id: string;
+  invoiceId: string;
+  title: string;
+  status: "pending" | "submitted" | "approved" | "released" | "rejected";
+  conditions?: { id: string; met: boolean }[];
+}
+
+interface DisputeRecord {
+  id: string;
+  invoiceId: string;
+  status: "open" | "evidence" | "review" | "resolved" | "enforced";
+  evidence?: { id: string; submittedBy: string }[];
+  resolution?: string;
+}
+
+function loadRecords<T>(key: string): T[] {
+  if (typeof window === "undefined") return [];
+  try {
+    const parsed = JSON.parse(localStorage.getItem(key) ?? "[]");
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
 function loadNotifications(): AppNotification[] {
   if (typeof window === "undefined") return [];
   try {
@@ -71,6 +106,8 @@ const TYPE_ICONS: Record<NotificationType, string> = {
   released: "🚀",
   expired: "⏰",
   reminder: "📅",
+  milestone: "🎯",
+  dispute: "⚖️",
 };
 
 export default function NotificationCenter() {
@@ -176,6 +213,114 @@ export default function NotificationCenter() {
         }
       }
 
+      // Milestone condition / release transitions
+      const milestones = loadRecords<MilestoneRecord>(MILESTONES_KEY);
+      for (const m of milestones) {
+        if (!ids.includes(m.invoiceId)) continue;
+        const title = m.title || `Milestone on Invoice #${m.invoiceId}`;
+
+        const allConditionsMet =
+          !!m.conditions &&
+          m.conditions.length > 0 &&
+          m.conditions.every((c) => c.met);
+        if (allConditionsMet) {
+          const key = `milestone-conditions-${m.id}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "milestone",
+              invoiceId: m.invoiceId,
+              invoiceTitle: title,
+              message: `All conditions met for ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+
+        if (m.status === "released") {
+          const key = `milestone-released-${m.id}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "milestone",
+              invoiceId: m.invoiceId,
+              invoiceTitle: title,
+              message: `Milestone funds released: ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+      }
+
+      // Dispute lifecycle transitions
+      const disputes = loadRecords<DisputeRecord>(DISPUTES_KEY);
+      for (const d of disputes) {
+        if (!ids.includes(d.invoiceId)) continue;
+        const title = `Invoice #${d.invoiceId}`;
+
+        if (d.status === "open") {
+          const key = `dispute-open-${d.id}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "dispute",
+              invoiceId: d.invoiceId,
+              invoiceTitle: title,
+              message: `Dispute opened on ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+
+        if (d.evidence && d.evidence.length > 0) {
+          const key = `dispute-evidence-${d.id}-${d.evidence.length}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "dispute",
+              invoiceId: d.invoiceId,
+              invoiceTitle: title,
+              message: `New evidence submitted for dispute on ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+
+        if (d.status === "resolved") {
+          const key = `dispute-resolved-${d.id}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "dispute",
+              invoiceId: d.invoiceId,
+              invoiceTitle: title,
+              message: `Dispute resolved on ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+
+        if (d.status === "enforced") {
+          const key = `dispute-enforced-${d.id}`;
+          if (!existing.some((n) => n.id === key)) {
+            newItems.push({
+              id: key,
+              type: "dispute",
+              invoiceId: d.invoiceId,
+              invoiceTitle: title,
+              message: `Dispute resolution enforced on ${title}`,
+              timestamp: Date.now(),
+              read: false,
+            });
+          }
+        }
+      }
+
       if (newItems.length > 0) {
         const merged = [...newItems, ...existing].slice(0, MAX_NOTIFICATIONS);
         saveNotifications(merged);
diff --git a/src/components/ProofViewer.tsx b/src/components/ProofViewer.tsx
index e958456d..6bdfea3f 100644
--- a/src/components/ProofViewer.tsx
+++ b/src/components/ProofViewer.tsx
@@ -3,6 +3,7 @@
 import { useRef, useState } from "react";
 import { splitClient } from "@/lib/stellar";
 import { formatAmount, truncateAddress } from "@stellar-split/sdk";
+import { getIpfsUrl, isValidCid } from "@/lib/ipfs";
 
 interface VerifiedProof {
   payer: string;
@@ -11,18 +12,22 @@ interface VerifiedProof {
   imageUrl?: string;
 }
 
+type ViewerMode = "payment" | "evidence";
+
 interface Props {
   invoiceId: string;
+  mode?: ViewerMode;
 }
 
 const MIN_ZOOM = 0.5;
 const MAX_ZOOM = 4;
 const ZOOM_STEP = 0.25;
 
-export default function ProofViewer({ invoiceId }: Props) {
+export default function ProofViewer({ invoiceId, mode = "payment" }: Props) {
   const [proofHash, setProofHash] = useState("");
   const [verifying, setVerifying] = useState(false);
   const [verified, setVerified] = useState<VerifiedProof | null>(null);
+  const [evidenceCid, setEvidenceCid] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [zoom, setZoom] = useState(1);
   const [pan, setPan] = useState({ x: 0, y: 0 });
@@ -55,6 +60,16 @@ export default function ProofViewer({ invoiceId }: Props) {
     setVerifying(true);
 
     try {
+      if (mode === "evidence") {
+        const cid = proofHash.trim();
+        if (!isValidCid(cid)) {
+          setError("Invalid evidence CID. Please provide a valid IPFS CID.");
+          return;
+        }
+        setEvidenceCid(cid);
+        return;
+      }
+
       // In a real implementation, this would call splitClient.generatePaymentProof
       // and compare against the proof hash. For now, we'll simulate the verification.
       const proof = await (splitClient as any).generatePaymentProof(proofHash);
@@ -75,22 +90,39 @@ export default function ProofViewer({ invoiceId }: Props) {
     }
   };
 
+  const resetViewer = () => {
+    setVerified(null);
+    setEvidenceCid(null);
+    setProofHash("");
+    setError(null);
+    resetZoom();
+  };
+
+  const isEvidence = mode === "evidence";
+  const evidenceUrl = evidenceCid ? getIpfsUrl(evidenceCid) : null;
+  const evidenceIsPdf = evidenceCid ? /\.pdf$/i.test(evidenceCid) : false;
+  const showViewer = isEvidence ? Boolean(evidenceCid) : Boolean(verified);
+
   return (
     <div className="bg-gray-800 border border-gray-700 rounded-lg p-6">
-      <h3 className="text-lg font-semibold mb-4">Verify Payment Proof</h3>
+      <h3 className="text-lg font-semibold mb-4">
+        {isEvidence ? "View Evidence" : "Verify Payment Proof"}
+      </h3>
 
-      {!verified ? (
+      {!showViewer ? (
         <div className="space-y-4">
           <div>
             <label htmlFor="proof-hash" className="block text-sm font-medium text-gray-300 mb-2">
-              Proof Hash
+              {isEvidence ? "Evidence CID" : "Proof Hash"}
             </label>
             <input
               id="proof-hash"
               type="text"
               value={proofHash}
               onChange={(e) => setProofHash(e.target.value)}
-              placeholder="Paste proof hash here..."
+              placeholder={
+                isEvidence ? "Paste IPFS CID here..." : "Paste proof hash here..."
+              }
               className="w-full bg-gray-900 border border-gray-700 rounded-lg px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500 font-mono"
             />
           </div>
@@ -103,36 +135,112 @@ export default function ProofViewer({ invoiceId }: Props) {
             disabled={verifying || !proofHash.trim()}
             className="w-full px-4 py-2 rounded-lg bg-indigo-600 hover:bg-indigo-500 text-sm font-medium disabled:opacity-50"
           >
-            {verifying ? "Verifying…" : "Verify Proof"}
+            {verifying
+              ? "Verifying…"
+              : isEvidence
+                ? "Load Evidence"
+                : "Verify Proof"}
           </button>
         </div>
       ) : (
         <div className="space-y-4">
           <div className="flex items-center gap-2 p-3 bg-green-500/10 border border-green-500/30 rounded-lg">
             <span className="text-green-400 text-lg">✓</span>
-            <span className="text-sm font-medium text-green-300">Proof Verified</span>
+            <span className="text-sm font-medium text-green-300">
+              {isEvidence ? "Evidence Loaded" : "Proof Verified"}
+            </span>
           </div>
 
-          <div className="bg-gray-900 rounded-lg p-4 space-y-3">
-            <div>
-              <p className="text-xs text-gray-500">Payer</p>
-              <p className="text-sm font-mono text-gray-300">
-                {truncateAddress(verified.payer)}
-              </p>
+          {!isEvidence && verified && (
+            <div className="bg-gray-900 rounded-lg p-4 space-y-3">
+              <div>
+                <p className="text-xs text-gray-500">Payer</p>
+                <p className="text-sm font-mono text-gray-300">
+                  {truncateAddress(verified.payer)}
+                </p>
+              </div>
+              <div>
+                <p className="text-xs text-gray-500">Amount</p>
+                <p className="text-sm font-medium text-gray-300">
+                  {formatAmount(verified.amount)} USDC
+                </p>
+              </div>
+              <div>
+                <p className="text-xs text-gray-500">Ledger</p>
+                <p className="text-sm text-gray-300">{verified.ledger}</p>
+              </div>
             </div>
-            <div>
-              <p className="text-xs text-gray-500">Amount</p>
-              <p className="text-sm font-medium text-gray-300">
-                {formatAmount(verified.amount)} USDC
-              </p>
+          )}
+
+          {isEvidence && evidenceCid && (
+            <div className="bg-gray-900 rounded-lg p-4 space-y-1">
+              <p className="text-xs text-gray-500">CID</p>
+              <p className="text-sm font-mono text-gray-300 break-all">{evidenceCid}</p>
             </div>
-            <div>
-              <p className="text-xs text-gray-500">Ledger</p>
-              <p className="text-sm text-gray-300">{verified.ledger}</p>
+          )}
+
+          {isEvidence && evidenceUrl && evidenceIsPdf && (
+            <div className="rounded-lg border border-gray-700 bg-gray-900 overflow-hidden">
+              <iframe
+                src={evidenceUrl}
+                title="Evidence document"
+                className="h-96 w-full"
+              />
             </div>
-          </div>
+          )}
+
+          {isEvidence && evidenceUrl && !evidenceIsPdf && (
+            <div className="space-y-2">
+              <div
+                className="relative h-64 overflow-hidden rounded-lg border border-gray-700 bg-gray-900"
+                style={{ cursor: zoom > 1 ? (isDragging ? "grabbing" : "grab") : "default" }}
+                onPointerDown={handlePointerDown}
+                onPointerMove={handlePointerMove}
+                onPointerUp={handlePointerUp}
+                onPointerLeave={handlePointerUp}
+              >
+                <img
+                  src={evidenceUrl}
+                  alt="Evidence"
+                  draggable={false}
+                  className="h-full w-full object-contain select-none"
+                  style={{
+                    transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+                    transformOrigin: "center center",
+                  }}
+                />
+              </div>
+              <div className="flex gap-2">
+                <button
+                  type="button"
+                  onClick={zoomOut}
+                  disabled={zoom <= MIN_ZOOM}
+                  aria-label="Zoom out"
+                  className="flex-1 px-3 py-1.5 rounded-lg border border-gray-700 text-sm font-medium hover:bg-gray-700 disabled:opacity-50"
+                >
+                  −
+                </button>
+                <button
+                  type="button"
+                  onClick={zoomIn}
+                  disabled={zoom >= MAX_ZOOM}
+                  aria-label="Zoom in"
+                  className="flex-1 px-3 py-1.5 rounded-lg border border-gray-700 text-sm font-medium hover:bg-gray-700 disabled:opacity-50"
+                >
+                  +
+                </button>
+                <button
+                  type="button"
+                  onClick={resetZoom}
+                  className="flex-1 px-3 py-1.5 rounded-lg border border-gray-700 text-sm font-medium hover:bg-gray-700"
+                >
+                  Reset
+                </button>
+              </div>
+            </div>
+          )}
 
-          {verified.imageUrl && (
+          {!isEvidence && verified?.imageUrl && (
             <div className="space-y-2">
               <div
                 className="relative h-64 overflow-hidden rounded-lg border border-gray-700 bg-gray-900"
@@ -185,14 +293,10 @@ export default function ProofViewer({ invoiceId }: Props) {
 
           <button
             type="button"
-            onClick={() => {
-              setVerified(null);
-              setProofHash("");
-              resetZoom();
-            }}
+            onClick={resetViewer}
             className="w-full px-4 py-2 rounded-lg border border-gray-700 text-sm font-medium hover:bg-gray-700"
           >
-            Verify Another
+            {isEvidence ? "Load Another" : "Verify Another"}
           </button>
         </div>
       )}
diff --git a/src/components/StatusTimeline.tsx b/src/components/StatusTimeline.tsx
index 39c894cc..afec8d80 100644
--- a/src/components/StatusTimeline.tsx
+++ b/src/components/StatusTimeline.tsx
@@ -3,6 +3,26 @@
 import type { Invoice } from "@stellar-split/sdk";
 import RelativeTime from "@/components/ui/RelativeTime";
 
+export interface MilestoneRecord {
+  id: string;
+  title: string;
+  conditionMet?: boolean;
+  evidenceSubmitted?: boolean;
+  released?: boolean;
+  releasedAt?: number | null;
+  evidenceAt?: number | null;
+  conditionMetAt?: number | null;
+}
+
+export interface DisputeRecord {
+  id: string;
+  status: "Open" | "Evidence" | "Resolved" | "Enforced" | string;
+  openedAt?: number | null;
+  evidenceAt?: number | null;
+  resolvedAt?: number | null;
+  enforcedAt?: number | null;
+}
+
 interface TimelineEvent {
   key: string;
   icon: string;
@@ -15,7 +35,12 @@ function truncate(addr: string) {
   return addr.length > 12 ? `${addr.slice(0, 6)}…${addr.slice(-4)}` : addr;
 }
 
-function buildEvents(invoice: Invoice, total: bigint): TimelineEvent[] {
+function buildEvents(
+  invoice: Invoice,
+  total: bigint,
+  milestones: MilestoneRecord[] = [],
+  disputes: DisputeRecord[] = [],
+): TimelineEvent[] {
   const events: TimelineEvent[] = [];
 
   // Created — use deadline as a proxy anchor; SDK Invoice has no createdAt
@@ -55,6 +80,68 @@ function buildEvents(invoice: Invoice, total: bigint): TimelineEvent[] {
     });
   }
 
+  // Milestone condition events
+  for (const m of milestones) {
+    if (m.conditionMet) {
+      events.push({
+        key: `milestone-${m.id}-condition`,
+        icon: "🎯",
+        label: `Condition Met: ${m.title}`,
+        timestamp: m.conditionMetAt ?? null,
+      });
+    }
+    if (m.evidenceSubmitted) {
+      events.push({
+        key: `milestone-${m.id}-evidence`,
+        icon: "📎",
+        label: `Evidence Submitted: ${m.title}`,
+        timestamp: m.evidenceAt ?? null,
+      });
+    }
+    if (m.released) {
+      events.push({
+        key: `milestone-${m.id}-released`,
+        icon: "🔓",
+        label: `Milestone Released: ${m.title}`,
+        timestamp: m.releasedAt ?? null,
+      });
+    }
+  }
+
+  // Dispute lifecycle events
+  for (const d of disputes) {
+    events.push({
+      key: `dispute-${d.id}-opened`,
+      icon: "⚠️",
+      label: "Dispute Opened",
+      timestamp: d.openedAt ?? null,
+    });
+    if (d.evidenceAt != null || d.status === "Evidence" || d.status === "Resolved" || d.status === "Enforced") {
+      events.push({
+        key: `dispute-${d.id}-evidence`,
+        icon: "📑",
+        label: "Dispute Evidence Submitted",
+        timestamp: d.evidenceAt ?? null,
+      });
+    }
+    if (d.status === "Resolved" || d.status === "Enforced") {
+      events.push({
+        key: `dispute-${d.id}-resolved`,
+        icon: "⚖️",
+        label: "Dispute Resolved",
+        timestamp: d.resolvedAt ?? null,
+      });
+    }
+    if (d.status === "Enforced") {
+      events.push({
+        key: `dispute-${d.id}-enforced`,
+        icon: "🔒",
+        label: "Resolution Enforced",
+        timestamp: d.enforcedAt ?? null,
+      });
+    }
+  }
+
   if (invoice.status === "Released") {
     events.push({
       key: "released",
@@ -80,15 +167,22 @@ function buildEvents(invoice: Invoice, total: bigint): TimelineEvent[] {
 interface Props {
   invoice: Invoice;
   total: bigint;
+  milestones?: MilestoneRecord[];
+  disputes?: DisputeRecord[];
 }
 
-export default function StatusTimeline({ invoice, total }: Props) {
-  const events = buildEvents(invoice, total);
+export default function StatusTimeline({ invoice, total, milestones = [], disputes = [] }: Props) {
+  const events = buildEvents(invoice, total, milestones, disputes);
+
+  const hasActiveDispute = disputes.some(
+    (d) => d.status !== "Resolved" && d.status !== "Enforced",
+  );
 
   // ── Mobile: horizontal stepper ─────────────────────────────────────────────
   const STEPS = ["Created", "Partially Funded", "Funded", "Released / Refunded"] as const;
 
   function getActiveStep(): number {
+    if (hasActiveDispute) return 4;
     if (invoice.status === "Released" || invoice.status === "Refunded") return 3;
     if (total > 0n && invoice.funded >= total) return 2;
     if (invoice.funded > 0n) return 1;
@@ -96,23 +190,25 @@ export default function StatusTimeline({ invoice, total }: Props) {
   }
 
   const active = getActiveStep();
+  const steps = hasActiveDispute ? [...STEPS, "Disputed"] : STEPS;
 
   return (
     <>
       {/* Mobile: compact horizontal stepper */}
       <div className="sm:hidden grid grid-cols-2 gap-y-4 mb-6">
-        {STEPS.map((step, i) => {
+        {steps.map((step, i) => {
           const done = i < active;
           const current = i === active;
+          const isDisputed = step === "Disputed";
           const label = i === 3 && invoice.status !== "Pending" ? invoice.status : step;
           return (
             <div key={step} className={`flex-1 flex flex-col items-center min-w-0 px-1${current ? " text-white font-semibold" : ""}`}>
               <div className="flex items-center w-full">
-                {i > 0 && <div className={`flex-1 h-0.5 ${done || current ? "bg-indigo-500" : "bg-gray-700"}`} />}
-                <div className={`w-4 h-4 rounded-full border-2 flex-shrink-0 ${done ? "bg-indigo-500 border-indigo-500" : current ? "bg-white border-indigo-400" : "bg-gray-800 border-gray-600"}`} />
-                {i < STEPS.length - 1 && <div className={`flex-1 h-0.5 ${done ? "bg-indigo-500" : "bg-gray-700"}`} />}
+                {i > 0 && <div className={`flex-1 h-0.5 ${done || current ? (isDisputed ? "bg-red-500" : "bg-indigo-500") : "bg-gray-700"}`} />}
+                <div className={`w-4 h-4 rounded-full border-2 flex-shrink-0 ${done ? (isDisputed ? "bg-red-500 border-red-500" : "bg-indigo-500 border-indigo-500") : current ? (isDisputed ? "bg-red-400 border-red-300" : "bg-white border-indigo-400") : "bg-gray-800 border-gray-600"}`} />
+                {i < steps.length - 1 && <div className={`flex-1 h-0.5 ${done ? (isDisputed ? "bg-red-500" : "bg-indigo-500") : "bg-gray-700"}`} />}
               </div>
-              <p className={`text-xs mt-1 text-center ${current ? "text-white font-semibold" : done ? "text-indigo-400" : "text-gray-500"}`}>
+              <p className={`text-xs mt-1 text-center ${current ? (isDisputed ? "text-red-400 font-semibold" : "text-white font-semibold") : done ? (isDisputed ? "text-red-400" : "text-indigo-400") : "text-gray-500"}`}>
                 {label}
               </p>
             </div>
diff --git a/src/lib/arbitrators.ts b/src/lib/arbitrators.ts
index e1874b78..b44686fa 100644
--- a/src/lib/arbitrators.ts
+++ b/src/lib/arbitrators.ts
@@ -51,3 +51,548 @@ export function searchArbitrators(query: string): Arbitrator[] {
 export function getArbitratorByAddress(address: string): Arbitrator | undefined {
   return getArbitrators().find((a) => a.address === address);
 }
+
+// ---------------------------------------------------------------------------
+// Dispute resolution system
+// ---------------------------------------------------------------------------
+
+export type DisputeStatus =
+  | "open"
+  | "evidence"
+  | "arbitration"
+  | "resolved"
+  | "enforced";
+
+export type DisputeParty = "initiator" | "respondent";
+
+export interface DisputeEvidence {
+  id: string;
+  submittedBy: string;
+  party: DisputeParty;
+  description: string;
+  /** Optional reference (URL, hash, or free-form pointer) to the evidence. */
+  reference?: string;
+  submittedAt: string;
+}
+
+export type DisputeTimelineEventType =
+  | "created"
+  | "evidence_submitted"
+  | "arbitrator_assigned"
+  | "vote_recorded"
+  | "resolved"
+  | "enforced"
+  | "status_changed";
+
+export interface DisputeTimelineEvent {
+  id: string;
+  type: DisputeTimelineEventType;
+  actor: string;
+  message: string;
+  at: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ArbitratorVote {
+  arbitrator: string;
+  /** Outcome the arbitrator voted for. */
+  outcome: DisputeOutcome;
+  /** Optional rationale for the vote. */
+  rationale?: string;
+  votedAt: string;
+}
+
+export type DisputeOutcome =
+  | "favor_initiator"
+  | "favor_respondent"
+  | "split"
+  | "dismissed";
+
+export interface DisputeResolution {
+  outcome: DisputeOutcome;
+  /** Human readable summary of the decision. */
+  summary: string;
+  /** Optional amount (in the invoice currency) to be awarded. */
+  awardedAmount?: number;
+  resolvedBy: string;
+  resolvedAt: string;
+  enforced: boolean;
+  enforcedAt?: string;
+  enforcedBy?: string;
+}
+
+export interface DisputeRecord {
+  id: string;
+  invoiceId: string;
+  initiator: string;
+  respondent: string;
+  reason: string;
+  description: string;
+  status: DisputeStatus;
+  assignedArbitrators: string[];
+  evidence: DisputeEvidence[];
+  votes: ArbitratorVote[];
+  timeline: DisputeTimelineEvent[];
+  resolution?: DisputeResolution;
+  createdAt: string;
+  updatedAt: string;
+}
+
+const DISPUTES_STORAGE_KEY = "stellarsplit_disputes";
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function generateId(prefix: string): string {
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `${prefix}_${Date.now().toString(36)}_${rand}`;
+}
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}
+
+function readAllDisputes(): DisputeRecord[] {
+  if (!isBrowser()) return [];
+  try {
+    const raw = localStorage.getItem(DISPUTES_STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as DisputeRecord[];
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeAllDisputes(disputes: DisputeRecord[]): void {
+  if (!isBrowser()) return;
+  try {
+    localStorage.setItem(DISPUTES_STORAGE_KEY, JSON.stringify(disputes));
+  } catch {
+    // Ignore persistence failures (quota, private mode, etc.)
+  }
+}
+
+function appendTimeline(
+  dispute: DisputeRecord,
+  type: DisputeTimelineEventType,
+  actor: string,
+  message: string,
+  metadata?: Record<string, unknown>,
+): void {
+  dispute.timeline.push({
+    id: generateId("evt"),
+    type,
+    actor,
+    message,
+    at: nowIso(),
+    metadata,
+  });
+}
+
+function touch(dispute: DisputeRecord): void {
+  dispute.updatedAt = nowIso();
+}
+
+function saveDispute(dispute: DisputeRecord): DisputeRecord {
+  const all = readAllDisputes();
+  const idx = all.findIndex((d) => d.id === dispute.id);
+  if (idx >= 0) {
+    all[idx] = dispute;
+  } else {
+    all.push(dispute);
+  }
+  writeAllDisputes(all);
+  return dispute;
+}
+
+export function getDisputes(): DisputeRecord[] {
+  return readAllDisputes();
+}
+
+export function getDisputeById(id: string): DisputeRecord | undefined {
+  return readAllDisputes().find((d) => d.id === id);
+}
+
+export function getDisputesByInvoice(invoiceId: string): DisputeRecord[] {
+  return readAllDisputes().filter((d) => d.invoiceId === invoiceId);
+}
+
+export function getDisputesByParty(address: string): DisputeRecord[] {
+  return readAllDisputes().filter(
+    (d) => d.initiator === address || d.respondent === address,
+  );
+}
+
+export interface CreateDisputeInput {
+  invoiceId: string;
+  initiator: string;
+  respondent: string;
+  reason: string;
+  description: string;
+}
+
+export function createDispute(input: CreateDisputeInput): DisputeRecord {
+  const invoiceId = input.invoiceId?.trim();
+  const initiator = input.initiator?.trim();
+  const respondent = input.respondent?.trim();
+  const reason = input.reason?.trim();
+  const description = input.description?.trim();
+
+  if (!invoiceId) throw new Error("Invoice ID is required");
+  if (!initiator) throw new Error("Initiator address is required");
+  if (!respondent) throw new Error("Respondent address is required");
+  if (initiator === respondent) {
+    throw new Error("Initiator and respondent must be different parties");
+  }
+  if (!reason) throw new Error("Dispute reason is required");
+  if (!description) throw new Error("Dispute description is required");
+
+  const existing = readAllDisputes().find(
+    (d) =>
+      d.invoiceId === invoiceId &&
+      d.status !== "resolved" &&
+      d.status !== "enforced",
+  );
+  if (existing) {
+    throw new Error("An active dispute already exists for this invoice");
+  }
+
+  const createdAt = nowIso();
+  const dispute: DisputeRecord = {
+    id: generateId("dsp"),
+    invoiceId,
+    initiator,
+    respondent,
+    reason,
+    description,
+    status: "open",
+    assignedArbitrators: [],
+    evidence: [],
+    votes: [],
+    timeline: [],
+    createdAt,
+    updatedAt: createdAt,
+  };
+
+  appendTimeline(
+    dispute,
+    "created",
+    initiator,
+    `Dispute opened for invoice ${invoiceId}: ${reason}`,
+  );
+
+  return saveDispute(dispute);
+}
+
+export interface SubmitEvidenceInput {
+  disputeId: string;
+  submittedBy: string;
+  description: string;
+  reference?: string;
+}
+
+export function submitEvidence(input: SubmitEvidenceInput): DisputeRecord {
+  const dispute = getDisputeById(input.disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+  if (dispute.status === "resolved" || dispute.status === "enforced") {
+    throw new Error("Cannot submit evidence to a closed dispute");
+  }
+
+  const submittedBy = input.submittedBy?.trim();
+  if (!submittedBy) throw new Error("Submitter address is required");
+
+  let party: DisputeParty;
+  if (submittedBy === dispute.initiator) {
+    party = "initiator";
+  } else if (submittedBy === dispute.respondent) {
+    party = "respondent";
+  } else {
+    throw new Error("Only the involved parties may submit evidence");
+  }
+
+  const description = input.description?.trim();
+  if (!description) throw new Error("Evidence description is required");
+
+  const evidence: DisputeEvidence = {
+    id: generateId("evd"),
+    submittedBy,
+    party,
+    description,
+    reference: input.reference?.trim() || undefined,
+    submittedAt: nowIso(),
+  };
+
+  dispute.evidence.push(evidence);
+
+  if (dispute.status === "open") {
+    dispute.status = "evidence";
+    appendTimeline(
+      dispute,
+      "status_changed",
+      submittedBy,
+      "Dispute moved to evidence phase",
+      { status: "evidence" },
+    );
+  }
+
+  appendTimeline(
+    dispute,
+    "evidence_submitted",
+    submittedBy,
+    `Evidence submitted by ${party}`,
+    { evidenceId: evidence.id },
+  );
+
+  touch(dispute);
+  return saveDispute(dispute);
+}
+
+export function assignArbitrator(
+  disputeId: string,
+  arbitratorAddress: string,
+  actor?: string,
+): DisputeRecord {
+  const dispute = getDisputeById(disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+  if (dispute.status === "resolved" || dispute.status === "enforced") {
+    throw new Error("Cannot assign arbitrators to a closed dispute");
+  }
+
+  const address = arbitratorAddress?.trim();
+  if (!address) throw new Error("Arbitrator address is required");
+
+  const known = getArbitratorByAddress(address);
+  if (!known) throw new Error("Arbitrator is not in the registry");
+
+  if (dispute.assignedArbitrators.includes(address)) {
+    throw new Error("Arbitrator is already assigned to this dispute");
+  }
+
+  dispute.assignedArbitrators.push(address);
+
+  if (dispute.status === "open" || dispute.status === "evidence") {
+    dispute.status = "arbitration";
+    appendTimeline(
+      dispute,
+      "status_changed",
+      actor ?? address,
+      "Dispute moved to arbitration phase",
+      { status: "arbitration" },
+    );
+  }
+
+  appendTimeline(
+    dispute,
+    "arbitrator_assigned",
+    actor ?? address,
+    `Arbitrator ${known.name} assigned`,
+    { arbitrator: address },
+  );
+
+  touch(dispute);
+  return saveDispute(dispute);
+}
+
+/**
+ * Assigns a set of arbitrators to a dispute. Skips arbitrators that are
+ * already assigned and validates each against the registry.
+ */
+export function assignArbitrators(
+  disputeId: string,
+  arbitratorAddresses: string[],
+  actor?: string,
+): DisputeRecord {
+  if (!Array.isArray(arbitratorAddresses) || arbitratorAddresses.length === 0) {
+    throw new Error("At least one arbitrator address is required");
+  }
+
+  let dispute = getDisputeById(disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+
+  for (const address of arbitratorAddresses) {
+    const trimmed = address?.trim();
+    if (!trimmed) continue;
+    if (dispute.assignedArbitrators.includes(trimmed)) continue;
+    dispute = assignArbitrator(disputeId, trimmed, actor);
+  }
+
+  return dispute;
+}
+
+export function getAssignedArbitrators(disputeId: string): Arbitrator[] {
+  const dispute = getDisputeById(disputeId);
+  if (!dispute) return [];
+  return dispute.assignedArbitrators
+    .map((address) => getArbitratorByAddress(address))
+    .filter((a): a is Arbitrator => Boolean(a));
+}
+
+export interface RecordVoteInput {
+  disputeId: string;
+  arbitrator: string;
+  outcome: DisputeOutcome;
+  rationale?: string;
+}
+
+export function recordVote(input: RecordVoteInput): DisputeRecord {
+  const dispute = getDisputeById(input.disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+  if (dispute.status === "resolved" || dispute.status === "enforced") {
+    throw new Error("Cannot vote on a closed dispute");
+  }
+
+  const arbitrator = input.arbitrator?.trim();
+  if (!arbitrator) throw new Error("Arbitrator address is required");
+  if (!dispute.assignedArbitrators.includes(arbitrator)) {
+    throw new Error("Only assigned arbitrators may vote");
+  }
+  if (dispute.votes.some((v) => v.arbitrator === arbitrator)) {
+    throw new Error("Arbitrator has already voted on this dispute");
+  }
+
+  const validOutcomes: DisputeOutcome[] = [
+    "favor_initiator",
+    "favor_respondent",
+    "split",
+    "dismissed",
+  ];
+  if (!validOutcomes.includes(input.outcome)) {
+    throw new Error("Invalid vote outcome");
+  }
+
+  dispute.votes.push({
+    arbitrator,
+    outcome: input.outcome,
+    rationale: input.rationale?.trim() || undefined,
+    votedAt: nowIso(),
+  });
+
+  appendTimeline(
+    dispute,
+    "vote_recorded",
+    arbitrator,
+    `Arbitrator voted: ${input.outcome}`,
+    { outcome: input.outcome },
+  );
+
+  touch(dispute);
+  return saveDispute(dispute);
+}
+
+export interface ResolveDisputeInput {
+  disputeId: string;
+  outcome: DisputeOutcome;
+  summary: string;
+  awardedAmount?: number;
+  resolvedBy: string;
+}
+
+export function resolveDispute(input: ResolveDisputeInput): DisputeRecord {
+  const dispute = getDisputeById(input.disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+  if (dispute.status === "resolved" || dispute.status === "enforced") {
+    throw new Error("Dispute is already resolved");
+  }
+  if (dispute.assignedArbitrators.length === 0) {
+    throw new Error("Cannot resolve a dispute without assigned arbitrators");
+  }
+  if (dispute.votes.length === 0) {
+    throw new Error("Cannot resolve a dispute without arbitrator votes");
+  }
+
+  const summary = input.summary?.trim();
+  if (!summary) throw new Error("Resolution summary is required");
+
+  const resolvedBy = input.resolvedBy?.trim();
+  if (!resolvedBy) throw new Error("Resolver address is required");
+  if (!dispute.assignedArbitrators.includes(resolvedBy)) {
+    throw new Error("Only assigned arbitrators may resolve the dispute");
+  }
+
+  if (
+    input.awardedAmount !== undefined &&
+    (Number.isNaN(input.awardedAmount) || input.awardedAmount < 0)
+  ) {
+    throw new Error("Awarded amount must be a non-negative number");
+  }
+
+  dispute.resolution = {
+    outcome: input.outcome,
+    summary,
+    awardedAmount: input.awardedAmount,
+    resolvedBy,
+    resolvedAt: nowIso(),
+    enforced: false,
+  };
+  dispute.status = "resolved";
+
+  appendTimeline(
+    dispute,
+    "resolved",
+    resolvedBy,
+    `Dispute resolved: ${input.outcome}`,
+    { outcome: input.outcome, awardedAmount: input.awardedAmount },
+  );
+
+  touch(dispute);
+  return saveDispute(dispute);
+}
+
+export interface EnforceResolutionInput {
+  disputeId: string;
+  enforcedBy: string;
+}
+
+export function enforceResolution(
+  input: EnforceResolutionInput,
+): DisputeRecord {
+  const dispute = getDisputeById(input.disputeId);
+  if (!dispute) throw new Error("Dispute not found");
+  if (dispute.status !== "resolved" || !dispute.resolution) {
+    throw new Error("Cannot enforce a dispute before it is resolved");
+  }
+  if (dispute.resolution.enforced) {
+    throw new Error("Resolution has already been enforced");
+  }
+
+  const enforcedBy = input.enforcedBy?.trim();
+  if (!enforcedBy) throw new Error("Enforcer address is required");
+
+  const enforcedAt = nowIso();
+  dispute.resolution.enforced = true;
+  dispute.resolution.enforcedAt = enforcedAt;
+  dispute.resolution.enforcedBy = enforcedBy;
+  dispute.status = "enforced";
+
+  appendTimeline(
+    dispute,
+    "enforced",
+    enforcedBy,
+    "Resolution enforced",
+    { outcome: dispute.resolution.outcome },
+  );
+
+  touch(dispute);
+  return saveDispute(dispute);
+}
+
+export function getDisputeTimeline(disputeId: string): DisputeTimelineEvent[] {
+  const dispute = getDisputeById(disputeId);
+  return dispute ? [...dispute.timeline] : [];
+}
+
+export function getDisputeEvidence(disputeId: string): DisputeEvidence[] {
+  const dispute = getDisputeById(disputeId);
+  return dispute ? [...dispute.evidence] : [];
+}
+
+export function getDisputeVotes(disputeId: string): ArbitratorVote[] {
+  const dispute = getDisputeById(disputeId);
+  return dispute ? [...dispute.votes] : [];
+}
+
+export function isDisputeActive(dispute: DisputeRecord): boolean {
+  return dispute.status !== "resolved" && dispute.status !== "enforced";
+}
\ No newline at end of file
diff --git a/src/lib/invoiceMilestones.ts b/src/lib/invoiceMilestones.ts
index 6e9674c3..b3df0afb 100644
--- a/src/lib/invoiceMilestones.ts
+++ b/src/lib/invoiceMilestones.ts
@@ -24,3 +24,438 @@ export function newestMilestone(raised: number, target: number): InvoiceMileston
   const reached = milestonesFor(raised, target).filter((m) => m.reached);
   return reached.length ? reached[reached.length - 1] : null;
 }
+
+// ---------------------------------------------------------------------------
+// Conditional milestone releases
+// ---------------------------------------------------------------------------
+
+export type ConditionType = "deliverable" | "approval" | "evidence";
+
+export type ConditionStatus =
+  | "pending"
+  | "submitted"
+  | "approved"
+  | "verified"
+  | "rejected";
+
+export interface ApprovalRecord {
+  id: string;
+  approver: string;
+  approved: boolean;
+  note?: string;
+  timestamp: number;
+}
+
+export interface EvidenceRecord {
+  id: string;
+  fileName: string;
+  mimeType?: string;
+  url?: string;
+  uploadedBy: string;
+  timestamp: number;
+  verified: boolean;
+  verifiedBy?: string;
+  verifiedAt?: number;
+}
+
+export interface MilestoneCondition {
+  id: string;
+  type: ConditionType;
+  description: string;
+  status: ConditionStatus;
+  required: boolean;
+  approvals: ApprovalRecord[];
+  evidence: EvidenceRecord[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface MilestoneState {
+  id: string;
+  percent: number;
+  label: string;
+  conditions: MilestoneCondition[];
+  released: boolean;
+  releasedAt?: number;
+}
+
+export interface ConditionValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export interface ReleaseGateResult {
+  canRelease: boolean;
+  reasons: string[];
+  unmetConditions: MilestoneCondition[];
+}
+
+let idCounter = 0;
+
+function generateId(prefix: string): string {
+  idCounter += 1;
+  return `${prefix}_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+}
+
+function now(): number {
+  return Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// Pure validation functions
+// ---------------------------------------------------------------------------
+
+export function validateCondition(condition: MilestoneCondition): ConditionValidationResult {
+  const errors: string[] = [];
+
+  if (!condition.id) errors.push("Condition id is required");
+  if (!condition.description || !condition.description.trim()) {
+    errors.push("Condition description is required");
+  }
+  if (condition.type !== "deliverable" && condition.type !== "approval" && condition.type !== "evidence") {
+    errors.push(`Unknown condition type: ${String(condition.type)}`);
+  }
+
+  if (condition.type === "approval") {
+    if (condition.status === "approved" || condition.status === "verified") {
+      const hasApproval = condition.approvals.some((a) => a.approved);
+      if (!hasApproval) {
+        errors.push("Approval condition requires at least one approving record");
+      }
+    }
+  }
+
+  if (condition.type === "evidence") {
+    if (condition.status === "verified") {
+      const hasVerifiedEvidence = condition.evidence.some((e) => e.verified);
+      if (!hasVerifiedEvidence) {
+        errors.push("Evidence condition requires at least one verified evidence record");
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function isConditionSatisfied(condition: MilestoneCondition): boolean {
+  if (!condition.required) return true;
+
+  switch (condition.type) {
+    case "deliverable":
+      return condition.status === "verified" || condition.status === "approved";
+    case "approval":
+      return (
+        (condition.status === "approved" || condition.status === "verified") &&
+        condition.approvals.some((a) => a.approved)
+      );
+    case "evidence":
+      return (
+        (condition.status === "verified" || condition.status === "approved") &&
+        condition.evidence.some((e) => e.verified)
+      );
+    default:
+      return false;
+  }
+}
+
+export function evaluateReleaseGate(milestone: MilestoneState): ReleaseGateResult {
+  const unmetConditions = milestone.conditions.filter((c) => !isConditionSatisfied(c));
+  const reasons: string[] = [];
+
+  if (milestone.released) {
+    reasons.push("Milestone has already been released");
+  }
+
+  for (const condition of unmetConditions) {
+    reasons.push(`Condition not satisfied: ${condition.description} (${condition.type})`);
+  }
+
+  return {
+    canRelease: reasons.length === 0,
+    reasons,
+    unmetConditions,
+  };
+}
+
+export function canReleaseMilestone(milestone: MilestoneState): boolean {
+  return evaluateReleaseGate(milestone).canRelease;
+}
+
+// ---------------------------------------------------------------------------
+// Persistence helpers (localStorage-backed)
+// ---------------------------------------------------------------------------
+
+const STORAGE_KEY = "invoiceMilestones.v1";
+
+function getStorage(): Storage | null {
+  try {
+    if (typeof localStorage !== "undefined") return localStorage;
+  } catch {
+    // Access to localStorage may throw in restricted environments.
+  }
+  return null;
+}
+
+function readAll(): Record<string, MilestoneState[]> {
+  const storage = getStorage();
+  if (!storage) return {};
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as Record<string, MilestoneState[]>;
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+function writeAll(data: Record<string, MilestoneState[]>): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(STORAGE_KEY, JSON.stringify(data));
+  } catch {
+    // Ignore quota / serialization errors.
+  }
+}
+
+export function getMilestones(invoiceId: string): MilestoneState[] {
+  const all = readAll();
+  return all[invoiceId] ? all[invoiceId].map((m) => ({ ...m })) : [];
+}
+
+export function saveMilestones(invoiceId: string, milestones: MilestoneState[]): void {
+  const all = readAll();
+  all[invoiceId] = milestones;
+  writeAll(all);
+}
+
+function updateMilestone(
+  invoiceId: string,
+  milestoneId: string,
+  updater: (milestone: MilestoneState) => MilestoneState,
+): MilestoneState | null {
+  const milestones = getMilestones(invoiceId);
+  const index = milestones.findIndex((m) => m.id === milestoneId);
+  if (index === -1) return null;
+  const updated = updater(milestones[index]);
+  milestones[index] = updated;
+  saveMilestones(invoiceId, milestones);
+  return updated;
+}
+
+function updateCondition(
+  invoiceId: string,
+  milestoneId: string,
+  conditionId: string,
+  updater: (condition: MilestoneCondition) => MilestoneCondition,
+): MilestoneCondition | null {
+  let result: MilestoneCondition | null = null;
+  updateMilestone(invoiceId, milestoneId, (milestone) => {
+    const conditions = milestone.conditions.map((c) => {
+      if (c.id !== conditionId) return c;
+      const next = updater(c);
+      result = next;
+      return next;
+    });
+    return { ...milestone, conditions };
+  });
+  return result;
+}
+
+export function createMilestone(
+  invoiceId: string,
+  percent: number,
+  label?: string,
+): MilestoneState {
+  const milestone: MilestoneState = {
+    id: generateId("ms"),
+    percent,
+    label: label ?? (percent === 100 ? "Fully funded" : `${percent}% funded`),
+    conditions: [],
+    released: false,
+  };
+  const existing = getMilestones(invoiceId);
+  existing.push(milestone);
+  saveMilestones(invoiceId, existing);
+  return milestone;
+}
+
+export function addCondition(
+  invoiceId: string,
+  milestoneId: string,
+  input: {
+    type: ConditionType;
+    description: string;
+    required?: boolean;
+  },
+): MilestoneCondition | null {
+  const condition: MilestoneCondition = {
+    id: generateId("cond"),
+    type: input.type,
+    description: input.description,
+    status: "pending",
+    required: input.required ?? true,
+    approvals: [],
+    evidence: [],
+    createdAt: now(),
+    updatedAt: now(),
+  };
+
+  const updated = updateMilestone(invoiceId, milestoneId, (milestone) => ({
+    ...milestone,
+    conditions: [...milestone.conditions, condition],
+  }));
+
+  return updated ? condition : null;
+}
+
+export function submitEvidence(
+  invoiceId: string,
+  milestoneId: string,
+  conditionId: string,
+  input: {
+    fileName: string;
+    mimeType?: string;
+    url?: string;
+    uploadedBy: string;
+  },
+): EvidenceRecord | null {
+  const evidence: EvidenceRecord = {
+    id: generateId("ev"),
+    fileName: input.fileName,
+    mimeType: input.mimeType,
+    url: input.url,
+    uploadedBy: input.uploadedBy,
+    timestamp: now(),
+    verified: false,
+  };
+
+  const updated = updateCondition(invoiceId, milestoneId, conditionId, (condition) => ({
+    ...condition,
+    evidence: [...condition.evidence, evidence],
+    status: condition.status === "pending" ? "submitted" : condition.status,
+    updatedAt: now(),
+  }));
+
+  return updated ? evidence : null;
+}
+
+export function verifyEvidence(
+  invoiceId: string,
+  milestoneId: string,
+  conditionId: string,
+  evidenceId: string,
+  verifiedBy: string,
+): EvidenceRecord | null {
+  let result: EvidenceRecord | null = null;
+
+  updateCondition(invoiceId, milestoneId, conditionId, (condition) => {
+    const evidence = condition.evidence.map((e) => {
+      if (e.id !== evidenceId) return e;
+      const next: EvidenceRecord = {
+        ...e,
+        verified: true,
+        verifiedBy,
+        verifiedAt: now(),
+      };
+      result = next;
+      return next;
+    });
+    return { ...condition, evidence, updatedAt: now() };
+  });
+
+  return result;
+}
+
+export function approveCondition(
+  invoiceId: string,
+  milestoneId: string,
+  conditionId: string,
+  input: {
+    approver: string;
+    approved: boolean;
+    note?: string;
+  },
+): ApprovalRecord | null {
+  const approval: ApprovalRecord = {
+    id: generateId("appr"),
+    approver: input.approver,
+    approved: input.approved,
+    note: input.note,
+    timestamp: now(),
+  };
+
+  const updated = updateCondition(invoiceId, milestoneId, conditionId, (condition) => {
+    const approvals = [...condition.approvals, approval];
+    let status: ConditionStatus = condition.status;
+    if (input.approved) {
+      status = "approved";
+    } else {
+      status = "rejected";
+    }
+    return { ...condition, approvals, status, updatedAt: now() };
+  });
+
+  return updated ? approval : null;
+}
+
+export function verifyCondition(
+  invoiceId: string,
+  milestoneId: string,
+  conditionId: string,
+): MilestoneCondition | null {
+  return updateCondition(invoiceId, milestoneId, conditionId, (condition) => {
+    const validation = validateCondition({ ...condition, status: "verified" });
+    if (!validation.valid) {
+      return condition;
+    }
+    return { ...condition, status: "verified", updatedAt: now() };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Release gate
+// ---------------------------------------------------------------------------
+
+export class MilestoneReleaseError extends Error {
+  readonly reasons: string[];
+  readonly unmetConditions: MilestoneCondition[];
+
+  constructor(reasons: string[], unmetConditions: MilestoneCondition[]) {
+    super(`Cannot release milestone: ${reasons.join("; ")}`);
+    this.name = "MilestoneReleaseError";
+    this.reasons = reasons;
+    this.unmetConditions = unmetConditions;
+  }
+}
+
+export function releaseMilestone(
+  invoiceId: string,
+  milestoneId: string,
+): MilestoneState {
+  const milestones = getMilestones(invoiceId);
+  const milestone = milestones.find((m) => m.id === milestoneId);
+
+  if (!milestone) {
+    throw new MilestoneReleaseError(["Milestone not found"], []);
+  }
+
+  const gate = evaluateReleaseGate(milestone);
+  if (!gate.canRelease) {
+    throw new MilestoneReleaseError(gate.reasons, gate.unmetConditions);
+  }
+
+  const updated = updateMilestone(invoiceId, milestoneId, (m) => ({
+    ...m,
+    released: true,
+    releasedAt: now(),
+  }));
+
+  if (!updated) {
+    throw new MilestoneReleaseError(["Milestone not found"], []);
+  }
+
+  return updated;
+}
\ No newline at end of file
diff --git a/src/lib/invoiceStatus.ts b/src/lib/invoiceStatus.ts
index 7a69a549..b634cd52 100644
--- a/src/lib/invoiceStatus.ts
+++ b/src/lib/invoiceStatus.ts
@@ -1,3 +1,9 @@
+import {
+  areMilestoneConditionsSatisfied,
+  getInvoiceMilestones,
+} from "./invoiceMilestones";
+import { getActiveDispute } from "./invoiceDisputes";
+
 export type InvoiceStatus =
   | "Pending"
   | "Active"
@@ -67,3 +73,115 @@ export const STATUS_CONFIG: Record<InvoiceStatus, StatusConfig> = {
     description: "Invoice has expired and can no longer be paid or modified",
   },
 };
+
+/**
+ * Allowed status transitions for the invoice state machine.
+ * A transition is only valid if the target status is listed for the
+ * current status.
+ */
+export const STATUS_TRANSITIONS: Record<InvoiceStatus, InvoiceStatus[]> = {
+  Pending: ["Active", "Expired", "Archived"],
+  Active: ["Funded", "Expired", "Archived"],
+  Funded: ["Released", "Refunded", "Disputed", "Frozen"],
+  Released: ["Archived"],
+  Refunded: ["Archived"],
+  Disputed: ["Funded", "Released", "Refunded", "Frozen", "Archived"],
+  Frozen: ["Funded", "Disputed", "Archived"],
+  Archived: [],
+  Expired: ["Archived"],
+};
+
+export interface ReleaseCheckResult {
+  allowed: boolean;
+  reasons: string[];
+}
+
+/**
+ * Returns true if the transition from `from` to `to` is permitted by the
+ * invoice state machine.
+ */
+export function canTransition(
+  from: InvoiceStatus,
+  to: InvoiceStatus,
+): boolean {
+  return STATUS_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+/**
+ * Determines whether an invoice's funds may be released.
+ *
+ * Release is blocked when:
+ *  - the invoice has an unresolved dispute,
+ *  - the invoice is frozen, archived or expired,
+ *  - any milestone condition has not been satisfied.
+ */
+export function canReleaseInvoice(invoiceId: string): boolean {
+  return getReleaseCheck(invoiceId).allowed;
+}
+
+/**
+ * Detailed release check that reports every reason release is blocked.
+ */
+export function getReleaseCheck(invoiceId: string): ReleaseCheckResult {
+  const reasons: string[] = [];
+
+  const dispute = getActiveDispute(invoiceId);
+  if (dispute) {
+    reasons.push("Invoice has an unresolved dispute");
+  }
+
+  const milestones = getInvoiceMilestones(invoiceId);
+  if (milestones.length > 0 && !areMilestoneConditionsSatisfied(invoiceId)) {
+    reasons.push("Milestone conditions have not been satisfied");
+  }
+
+  return { allowed: reasons.length === 0, reasons };
+}
+
+/**
+ * Convenience helper used by the release flow to short-circuit release
+ * attempts. Equivalent to `!canReleaseInvoice(invoiceId)`.
+ */
+export function isReleaseBlocked(invoiceId: string): boolean {
+  return !canReleaseInvoice(invoiceId);
+}
+
+/**
+ * Validates and applies a transition to the Disputed status.
+ * Throws if the transition is not permitted by the state machine.
+ */
+export function transitionToDisputed(
+  currentStatus: InvoiceStatus,
+): InvoiceStatus {
+  if (!canTransition(currentStatus, "Disputed")) {
+    throw new Error(
+      `Invalid status transition: ${currentStatus} -> Disputed`,
+    );
+  }
+  return "Disputed";
+}
+
+/**
+ * Validates and applies a transition to the Released status.
+ * Enforces dispute resolution and milestone conditions before release.
+ * Throws if the transition is not permitted or release is blocked.
+ */
+export function transitionToReleased(
+  invoiceId: string,
+  currentStatus: InvoiceStatus,
+): InvoiceStatus {
+  if (!canTransition(currentStatus, "Released")) {
+    throw new Error(
+      `Invalid status transition: ${currentStatus} -> Released`,
+    );
+  }
+
+  const check = getReleaseCheck(invoiceId);
+  if (!check.allowed) {
+    throw new Error(
+      `Release blocked for invoice ${invoiceId}: ${check.reasons.join("; ")}`,
+    );
+  }
+
+  return "Released";
+}
diff --git a/src/lib/ipfs.ts b/src/lib/ipfs.ts
index 6320c4c1..fd584eb7 100644
--- a/src/lib/ipfs.ts
+++ b/src/lib/ipfs.ts
@@ -138,3 +138,69 @@ export async function uploadToIpfsWithFallback(file: File): Promise<string> {
     return mockIpfsUpload(file);
   }
 }
+
+/**
+ * Metadata describing an uploaded evidence file.
+ */
+export interface EvidenceUploadResult {
+  cid: string;
+  filename: string;
+  size: number;
+  uploadedAt: string;
+}
+
+/**
+ * Upload an evidence file to IPFS and return its metadata.
+ * Used for both milestone evidence and dispute evidence submission.
+ * File type and size are validated using the same rules as uploadToIpfs.
+ *
+ * @param file - The evidence file to upload
+ * @returns Metadata for the uploaded evidence
+ * @throws Error if the file is invalid or upload fails
+ */
+export async function uploadEvidence(file: File): Promise<EvidenceUploadResult> {
+  // Validate file size (max 10MB)
+  const MAX_SIZE = 10 * 1024 * 1024;
+  if (file.size > MAX_SIZE) {
+    throw new Error("File size exceeds 10MB limit");
+  }
+
+  // Validate file type
+  const allowedTypes = [
+    "application/pdf",
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "text/plain",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ];
+
+  if (!allowedTypes.includes(file.type)) {
+    throw new Error("File type not supported. Use PDF, images, or text documents.");
+  }
+
+  const cid = await uploadToIpfsWithFallback(file);
+
+  if (!isValidCid(cid)) {
+    throw new Error("Invalid CID returned from IPFS upload");
+  }
+
+  return {
+    cid,
+    filename: file.name,
+    size: file.size,
+    uploadedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Validate an evidence reference (CID) used for milestone or dispute evidence.
+ *
+ * @param cid - The IPFS CID to validate
+ * @returns true if the CID is a valid evidence reference, false otherwise
+ */
+export function validateEvidenceReference(cid: string): boolean {
+  if (!cid || typeof cid !== "string") return false;
+  return isValidCid(cid.trim());
+}
diff --git a/src/lib/notifications.ts b/src/lib/notifications.ts
index 2c8798fa..a8fa562e 100644
--- a/src/lib/notifications.ts
+++ b/src/lib/notifications.ts
@@ -45,6 +45,12 @@ interface NotificationPreferences {
   deadlineApproaching: boolean;
   invoiceReleased: boolean;
   invoiceRefunded: boolean;
+  milestoneConditionMet: boolean;
+  milestoneReleased: boolean;
+  disputeOpened: boolean;
+  disputeEvidenceSubmitted: boolean;
+  disputeResolved: boolean;
+  disputeEnforced: boolean;
 }
 
 const DEFAULT_PREFS: NotificationPreferences = {
@@ -53,6 +59,12 @@ const DEFAULT_PREFS: NotificationPreferences = {
   deadlineApproaching: true,
   invoiceReleased: true,
   invoiceRefunded: true,
+  milestoneConditionMet: true,
+  milestoneReleased: true,
+  disputeOpened: true,
+  disputeEvidenceSubmitted: true,
+  disputeResolved: true,
+  disputeEnforced: true,
 };
 
 function getPreferences(): NotificationPreferences {
diff --git a/src/lib/stellar.ts b/src/lib/stellar.ts
index ea96d054..dd4f6a31 100644
--- a/src/lib/stellar.ts
+++ b/src/lib/stellar.ts
@@ -412,3 +412,201 @@ export function validateRecipientAmountSum(amounts: number[], totalAmount: numbe
   const sumStroops = amounts.reduce((s, a) => s + Math.round(a * STROOP_SCALE), 0);
   return totalStroops === sumStroops;
 }
+
+/**
+ * Release funds for a milestone, but only once every condition attached to
+ * that milestone has been satisfied and approved.
+ *
+ * The milestone release gate (`canReleaseMilestone`) is evaluated first; if
+ * any condition is unmet this throws before any transaction is built, so no
+ * funds can move. On success the existing contract `release` path is invoked
+ * and a notification is emitted.
+ */
+export async function releaseMilestoneFunds(params: {
+  invoiceId: string;
+  milestoneId: string;
+  payer: string;
+}): Promise<{ txHash: string }> {
+  const { canReleaseMilestone } = await import("./milestones");
+  const { notifyMilestoneReleased } = await import("./notifications");
+
+  const gate = await canReleaseMilestone({
+    invoiceId: params.invoiceId,
+    milestoneId: params.milestoneId,
+  });
+
+  if (!gate.canRelease) {
+    const unmet = gate.unmetConditions?.length
+      ? ` Unmet conditions: ${gate.unmetConditions.join(", ")}.`
+      : "";
+    throw new Error(`Milestone conditions are not satisfied.${unmet}`);
+  }
+
+  const client = getSplitClient();
+  const { TransactionBuilder, BASE_FEE, Memo, nativeToScVal, rpc } = await import("@stellar/stellar-sdk");
+  const { signWithFreighter } = await import("./freighter");
+
+  // Same rationale as `payMilestone`: the published SDK does not expose a
+  // typed milestone-release call with a custom memo, so reach the underlying
+  // internals at runtime.
+  const internals = client as unknown as {
+    contract: { call: (...args: any[]) => any };
+    server: any;
+    config: { networkPassphrase: string };
+  };
+
+  const memoText = `INV:${params.invoiceId}:REL:${params.milestoneId}`.slice(0, MEMO_MAX_BYTES);
+
+  const operation = internals.contract.call(
+    "release_milestone",
+    nativeToScVal(BigInt(params.invoiceId), { type: "u64" }),
+    nativeToScVal(params.milestoneId, { type: "string" })
+  );
+
+  const sourceAccount = await internals.server.getAccount(params.payer);
+  const networkPassphrase = internals.config.networkPassphrase;
+
+  const tx = new TransactionBuilder(sourceAccount, {
+    fee: BASE_FEE,
+    networkPassphrase,
+  })
+    .addOperation(operation)
+    .addMemo(Memo.text(memoText))
+    .setTimeout(30)
+    .build();
+
+  const simResult = await internals.server.simulateTransaction(tx);
+  if (rpc.Api.isSimulationError(simResult)) {
+    throw new Error(`Simulation failed: ${simResult.error}`);
+  }
+
+  const preparedTx = rpc.assembleTransaction(tx, simResult).build();
+  const signedXdr = await signWithFreighter(preparedTx.toXDR());
+  const signedTx = TransactionBuilder.fromXDR(signedXdr, networkPassphrase);
+  const sendResult = await internals.server.sendTransaction(signedTx);
+
+  if (sendResult.status === "ERROR") {
+    throw new Error(`Transaction failed: ${JSON.stringify(sendResult.errorResult)}`);
+  }
+
+  let getResult = await internals.server.getTransaction(sendResult.hash);
+  let attempts = 0;
+  while (getResult.status === rpc.Api.GetTransactionStatus.NOT_FOUND && attempts < 20) {
+    await new Promise((r) => setTimeout(r, 1500));
+    getResult = await internals.server.getTransaction(sendResult.hash);
+    attempts++;
+  }
+
+  if (getResult.status !== rpc.Api.GetTransactionStatus.SUCCESS) {
+    throw new Error(`Transaction not confirmed: ${getResult.status}`);
+  }
+
+  await notifyMilestoneReleased({
+    invoiceId: params.invoiceId,
+    milestoneId: params.milestoneId,
+    txHash: sendResult.hash,
+  });
+
+  return { txHash: sendResult.hash };
+}
+
+export type DisputeOutcome = "release" | "refund" | "split";
+
+/**
+ * Enforce a resolved dispute by invoking the matching contract method.
+ *
+ * - `release` pays the recipient the disputed funds.
+ * - `refund` returns the disputed funds to the payer.
+ * - `split` divides the disputed funds according to the resolution's split
+ *   ratio (defaults to an even split when none is supplied).
+ *
+ * A notification is emitted on success so both parties are informed.
+ */
+export async function enforceDisputeResolution(params: {
+  invoiceId: string;
+  outcome: DisputeOutcome;
+  payer: string;
+  splitRatio?: number;
+}): Promise<{ txHash: string }> {
+  const { notifyDisputeResolved } = await import("./notifications");
+
+  const methodByOutcome: Record<DisputeOutcome, string> = {
+    release: "release_disputed_funds",
+    refund: "refund_disputed_funds",
+    split: "split_disputed_funds",
+  };
+
+  const method = methodByOutcome[params.outcome];
+  if (!method) {
+    throw new Error(`Unsupported dispute outcome: ${params.outcome}`);
+  }
+
+  const client = getSplitClient();
+  const { TransactionBuilder, BASE_FEE, Memo, nativeToScVal, rpc } = await import("@stellar/stellar-sdk");
+  const { signWithFreighter } = await import("./freighter");
+
+  const internals = client as unknown as {
+    contract: { call: (...args: any[]) => any };
+    server: any;
+    config: { networkPassphrase: string };
+  };
+
+  const memoText = `INV:${params.invoiceId}:DSP:${params.outcome}`.slice(0, MEMO_MAX_BYTES);
+
+  const callArgs: any[] = [nativeToScVal(BigInt(params.invoiceId), { type: "u64" })];
+  if (params.outcome === "split") {
+    const ratio = params.splitRatio ?? 0.5;
+    if (ratio < 0 || ratio > 1) {
+      throw new Error("splitRatio must be between 0 and 1.");
+    }
+    callArgs.push(nativeToScVal(Math.round(ratio * 10_000), { type: "u32" }));
+  }
+
+  const operation = internals.contract.call(method, ...callArgs);
+
+  const sourceAccount = await internals.server.getAccount(params.payer);
+  const networkPassphrase = internals.config.networkPassphrase;
+
+  const tx = new TransactionBuilder(sourceAccount, {
+    fee: BASE_FEE,
+    networkPassphrase,
+  })
+    .addOperation(operation)
+    .addMemo(Memo.text(memoText))
+    .setTimeout(30)
+    .build();
+
+  const simResult = await internals.server.simulateTransaction(tx);
+  if (rpc.Api.isSimulationError(simResult)) {
+    throw new Error(`Simulation failed: ${simResult.error}`);
+  }
+
+  const preparedTx = rpc.assembleTransaction(tx, simResult).build();
+  const signedXdr = await signWithFreighter(preparedTx.toXDR());
+  const signedTx = TransactionBuilder.fromXDR(signedXdr, networkPassphrase);
+  const sendResult = await internals.server.sendTransaction(signedTx);
+
+  if (sendResult.status === "ERROR") {
+    throw new Error(`Transaction failed: ${JSON.stringify(sendResult.errorResult)}`);
+  }
+
+  let getResult = await internals.server.getTransaction(sendResult.hash);
+  let attempts = 0;
+  while (getResult.status === rpc.Api.GetTransactionStatus.NOT_FOUND && attempts < 20) {
+    await new Promise((r) => setTimeout(r, 1500));
+    getResult = await internals.server.getTransaction(sendResult.hash);
+    attempts++;
+  }
+
+  if (getResult.status !== rpc.Api.GetTransactionStatus.SUCCESS) {
+    throw new Error(`Transaction not confirmed: ${getResult.status}`);
+  }
+
+  await notifyDisputeResolved({
+    invoiceId: params.invoiceId,
+    outcome: params.outcome,
+    txHash: sendResult.hash,
+  });
+
+  return { txHash: sendResult.hash };
+}
diff --git a/src/types/activity.ts b/src/types/activity.ts
index 6d50da5a..02b6fd92 100644
--- a/src/types/activity.ts
+++ b/src/types/activity.ts
@@ -2,7 +2,13 @@ export type ActivityEventType =
   | "payment_received"
   | "status_change"
   | "comment"
-  | "co_creator_action";
+  | "co_creator_action"
+  | "milestone_condition_met"
+  | "milestone_released"
+  | "dispute_opened"
+  | "dispute_evidence_submitted"
+  | "dispute_resolved"
+  | "dispute_enforced";
 
 export interface ActivityEvent {
   eventId: string;
@@ -23,4 +29,4 @@ export interface ActivityEventSnapshot {
   events: ActivityEvent[];
 }
 
-export type ActivityFeedMessage = ActivityEventMessage | ActivityEventSnapshot;
+export type ActivityFeedMessage = ActivityEventMessage | ActivityEventSnapshot;
\ No newline at end of file