Entities

Roles, milestones, trustline, and on-chain escrow entity shapes.

These are the on-chain / post-submit shapes. For list and detail UI, prefer the read model (EscrowSummary) in Reads & responses.

Roles

v2 roles use arrays for operational wallets. Single-release keeps an escrow-level receiver. Multi-release puts receiver on each milestone instead.

Single-release — Roles

type Roles = {
  approvers: string[];        // G… wallets that approve milestones
  serviceProviders: string[]; // who delivers work / updates status
  platform: string;           // platform fee address
  releaseSigners: string[];   // who can release funds
  disputeResolvers: string[]; // who can resolve disputes
  receiver: string;           // who receives the single payout
  admin: string;              // who can update / manage milestones
  observers?: string[];       // optional watchers
};

Multi-release — MultiReleaseRoles

Same as Roles, without receiver (each milestone has its own):

type MultiReleaseRoles = {
  approvers: string[];
  serviceProviders: string[];
  platform: string;
  releaseSigners: string[];
  disputeResolvers: string[];
  admin: string;
  observers?: string[];
};

Role filter — Role

Used when filtering lists (ListEscrowsParams.role):

type Role =
  | "approver"
  | "serviceProvider"
  | "platform"
  | "releaseSigner"
  | "disputeResolver"
  | "receiver"
  | "admin"
  | "observer"
  | "signer";

Trustline

On deploy — DeployTrustline

type DeployTrustline = {
  contractId: string; // Soroban SAC contract id (C…)
  symbol: string;     // e.g. "USDC"
};

On read / snapshot — Trustline

type Trustline = {
  address: string;     // issuer or related address
  symbol?: string;
  contractId?: string; // SAC id when present
};

Milestones

Approvals — MilestoneApprovals

type MilestoneApprovals = {
  target: number;         // how many approvals are required
  approvalCount: number;  // how many have approved so far
  approvedBy: string[];   // G… wallets that already approved
};

Single-release milestone — SingleReleaseMilestone

type SingleReleaseMilestone = {
  description: string;
  status?: string;           // free-form status label
  evidence?: string;         // optional proof / link
  approvalsTarget?: number;
  approvals?: MilestoneApprovals;
};

Multi-release milestone — MultiReleaseMilestone

type MultiReleaseMilestone = {
  description: string;
  amount: number;            // payout for this milestone
  receiver: string;          // G… who receives this milestone
  status?: string;
  evidence?: string;
  approvalsTarget?: number;
  approvals?: MilestoneApprovals;
  released?: boolean;
  dispute?: {
    isDisputed: boolean;
    reason: string;
    resolved: boolean;
  };
};

Escrow-level dispute (single-release) — Dispute

type Dispute = {
  isDisputed: boolean;
  reason: string;
  resolved: boolean;
};

Escrow entities

Single-release

type SingleReleaseEscrow = {
  type: "single-release";
  contractId: string;
  contractBaseId?: string;
  signer: string;
  engagementId: string;
  title: string;
  description: string;
  platformFee: number;
  balance: number;
  amount: number;
  transactionHash?: string | null;
  trustline: Trustline;
  roles: Roles;
  milestones: SingleReleaseMilestone[];
  dispute?: Dispute;
  released?: boolean;
};

Multi-release

type MultiReleaseEscrow = {
  type: "multi-release";
  contractId: string;
  contractBaseId?: string;
  signer: string;
  engagementId: string;
  title: string;
  description: string;
  platformFee: number;
  balance: number;
  transactionHash?: string | null;
  trustline: Trustline;
  roles: MultiReleaseRoles;
  milestones: MultiReleaseMilestone[];
};

There is no escrow-level amount. Total value is the sum of milestone amounts.

Escrow is either single or multi:

type Escrow = SingleReleaseEscrow | MultiReleaseEscrow;