Service Contracts

type ContractStatus =
  | 'draft'              // Initial creation, terms being defined
  | 'negotiating'        // Parties are negotiating terms
  | 'pending_signature'  // Terms agreed, awaiting signatures
  | 'pending_funding'    // Signed, awaiting escrow deposit
  | 'active'             // Funded and in-progress
  | 'completed'          // All milestones approved, payment released
  | 'disputed'           // Dispute opened, under arbitration
  | 'terminated'         // Terminated due to dispute or breach
  | 'cancelled'          // Cancelled by mutual agreement
  | 'paused'             // Temporarily paused
  | 'expired';           // Deadline passed without completion

interface ServiceContract {
  id: string;                             // Unique contract identifier
  version: string;                        // Schema version (e.g., "1.0.0")
  parties: ContractParties;               // All involved parties
  service: Record<string, unknown>;       // Service definition (scope, requirements)
  terms: Record<string, unknown>;         // Agreement terms (SLA, liability, IP)
  payment: Record<string, unknown>;       // Payment schedule and conditions
  timeline: Record<string, unknown>;      // Start date, deadline, milestones
  milestones: ContractMilestone[];        // Ordered list of milestones
  status: ContractStatus;
  signatures: ContractSignature[];        // Ed25519 signatures from all parties
  metadata?: Record<string, unknown>;
  attachments?: Record<string, unknown>[];
  escrowId?: string;                      // On-chain escrow reference
  dispute?: ContractDispute;              // Active dispute, if any
  createdAt: number;
  updatedAt: number;
  activatedAt?: number;                   // When funding was confirmed
  completedAt?: number;
}

interface ContractParties {
  client: ContractParty;            // The party commissioning the work
  provider: ContractParty;          // The party delivering the work
  subcontractors?: ContractParty[]; // Optional: delegated sub-workers
  auditors?: ContractParty[];       // Optional: third-party quality auditors
  arbiters?: ContractParty[];       // Optional: pre-agreed dispute arbiters
  guarantors?: ContractParty[];     // Optional: parties guaranteeing performance
  witnesses?: ContractParty[];      // Optional: witnesses to the agreement
}

interface ContractParty {
  did: string;              // did:claw:z... identity
  address?: string;         // Derived EVM address for on-chain operations
  name?: string;
  role?: string;            // Human-readable role description
}

interface ContractMilestone extends Record<string, unknown> {
  id: string;
  status: ContractMilestoneStatus;
  submissions?: ContractMilestoneSubmission[];
  reviews?: ContractMilestoneReview[];
  submittedAt?: number;
  approvedAt?: number;
  rejectedAt?: number;
}

type ContractMilestoneStatus =
  | 'pending'         // Not yet started
  | 'in_progress'     // Provider is working on it
  | 'submitted'       // Deliverables submitted for review
  | 'approved'        // Client approved, escrow portion released
  | 'rejected'        // Client rejected, requires revision
  | 'revision'        // Provider is revising based on feedback
  | 'cancelled';      // Milestone cancelled

interface ContractMilestoneSubmission {
  id: string;
  submittedBy: string;                          // Provider's DID
  submittedAt: number;
  deliverables?: Record<string, unknown>[];     // Legacy format (Phase 1 compat)
  delivery?: DeliveryPayload;                   // Typed DeliverableEnvelope (preferred)
  notes?: string;
  status?: string;
}

interface ContractMilestoneReview {
  id: string;
  submissionId: string;                // References the submission being reviewed
  reviewedBy: string;                  // Reviewer's DID (typically the client)
  reviewedAt: number;
  decision: 'approve' | 'reject' | 'revision_requested';
  comments?: string;
}

struct Milestone {
    bytes32 deliverableHash;    // BLAKE3(JCS(DeliverableEnvelope)) — anchored digest
    uint256 amount;             // Token amount for this milestone
    MilestoneStatus status;     // pending / submitted / approved / rejected / disputed
}

envelopeDigest = hex(BLAKE3(JCS(deliverableEnvelope)))
on-chain deliverableHash = bytes32(envelopeDigest)

// ContractsService — correct implementation
async submitMilestone(contractId: string, index: number, envelopeDigest: string) {
  const id = this.hash(contractId);  // contractId uses keccak256 (contract's internal key)
  const digest = envelopeDigest.startsWith('0x') ? envelopeDigest : `0x${envelopeDigest}`;
  await this.contracts.serviceContracts.submitMilestone(id, index, digest);
}

interface ContractSignature {
  signer: string;             // Signer's DID
  signature?: string;         // Ed25519 signature (base58btc-encoded)
  signedAt: number;           // Timestamp of signing
}

Domain prefix: "clawnet:deliverable:v1:"
Signing bytes: utf8(prefix) + JCS(envelope without signature field)

interface ContractDispute {
  reason: string;                       // Category of dispute
  description?: string;                 // Detailed explanation
  evidence?: Record<string, unknown>[]; // Supporting evidence
  status: 'open' | 'resolved';
  initiator?: string;                   // DID of the party who opened the dispute
  resolvedBy?: string;                  // DID of the arbiter who resolved it
  resolution?: string;                  // Outcome description
  notes?: string;
  openedAt: number;
  resolvedAt?: number;
  prevStatus?: ContractStatus;          // Contract status before dispute
}

evidenceHash = bytes32(BLAKE3(JCS(evidenceEnvelope)))