useStartDispute

Responsible for setting the escrow in dispute state. Changes the value of the escrow's "disputed" flag property to true.

useStartDispute

Start a dispute. Single-release disputes the whole escrow; multi-release disputes selected milestones.

Import

import { useStartDispute } from "@trustless-work/escrow";
// or
import { useStartDispute } from "@trustless-work/escrow/hooks/rest";

Signature

function useStartDispute(): {
  startDispute: (
    payload: SingleReleaseStartDisputePayload | MultiReleaseStartDisputePayload,
    type: EscrowType,
  ) => Promise<BuildTransactionResponse>;

  /** Multi-release only — batch dispute milestones. */
  disputeMilestones: (
    payload: MultiReleaseStartDisputePayload,
  ) => Promise<BuildTransactionResponse>;
};

Payload	Fields
SingleReleaseStartDisputePayload	{ contractId, signer, reason }
MultiReleaseStartDisputePayload	{ contractId, signer, reason, milestoneIndexes }

Returns BuildTransactionResponse: { unsignedXdr, txHash }.

Single vs multi

single-release

await startDispute(
  { contractId, signer: address, reason: "Scope mismatch" },
  "single-release",
);

multi-release

await startDispute(
  { contractId, signer: address, reason: "Late delivery", milestoneIndexes: [1] },
  "multi-release",
);
// or
await disputeMilestones({
  contractId,
  signer: address,
  reason: "Late delivery",
  milestoneIndexes: [1],
});

Example

import {
  useStartDispute,
  useSendTransaction,
  toTrustlessWorkError,
  TrustlessWorkApiError,
  formatApiErrorMessage,
} from "@trustless-work/escrow";

const { startDispute } = useStartDispute();
const { sendTransaction } = useSendTransaction();

const onDispute = async () => {
  try {
    const { unsignedXdr } = await startDispute(
      { contractId, signer: address, reason: "Quality issues" },
      "single-release",
    );
    const signedXdr = await signWithWallet(unsignedXdr);
    return await sendTransaction(signedXdr);
  } catch (error: unknown) {
    const err = toTrustlessWorkError(error);
    if (err instanceof TrustlessWorkApiError) {
      toast.error(formatApiErrorMessage(err));
    }
    throw error;
  }
};